Events Authentication and Configuration

Establish a connection between OE and Cloud Events.

Orchestration Engine uses CloudEvents specifically with HTTP Protocol Binding and Binary Content Mode, where currently we support application/json only as a content-type for the data payload.

The CloudEvents should be used if you want third party systems to send trigger events to OE. If you want to use triggers directly from Celonis, see the Retrieving Data from Celonis documentation.

CloudEvents is a specification for describing event data in a common way. It provides a structured format for event data and includes essential metadata such as the event type, source, and timestamp. HTTP Protocol Binding in CloudEvents defines how to use HTTP for transporting event data, and Binary Content Mode specifies how to encode the event in a binary format within the HTTP message.

To learn more about CloudEvents, see:

• CloudEvents

• HTTP Protocol Binding for CloudEvents

• CloudEvents spec

Configuring the connection between the event and OE execution

In OE, an event-receiver serves as an endpoint specifically designed to receive external events, which are then used for initializing or resuming digital processes. These events, for example a placement of a new order, are configured and transmitted to the receiver, subsequently triggering the corresponding processes within OE.

To ensure that OE can receive events, the initial step is to establish the connection and verify that authentication functions properly. This connection requires specific OE tenant data, including the endpoint's source and secret values. These values are then utilized, for instance, in the Postman setup for development to ensure that requests are directed to the correct OE tenant.

Once the connection is established and authenticated, you can start with creating a relevant event within OE. This sequential process ensures smooth communication and accurate event handling between systems.

To establish the connection between the event-receiver endpoint and OE:

1. Go to OE → Admin → Settings.

2. Use the Source and Secret values for postman environment configuration.

OE:

Postman:

Source - the attribute that defines the endpoint that is be used for sending an event to OE, it’s unique for every tenant. If the endpoint is: https://signals.emporix.io/e/{{src}}, your src value is the value as in the source field in OE.

Secret - an HMAC (keyed-Hash Message Authentication Code) secret; an HMAC is a type of authentication technique that uses a hash function and a secret key. You can use it to sign a request with a shared secret. It verifies if data is correct and authentic. In this configuration the hmac secret is a value for the x-emporix-hmac header.

The header attributes are defined by the CloudEvents specification and are mandatory for sending the requests:

• ce-source - Represents the source of the event, providing information about where the event originated. The ce-source attribute typically contains a URI identifying the event producer or the endpoint that generated the event.

• ce-type - Represents the type of the event, providing information about the kind of event that occurred. The ce-type attribute typically contains a string value that identifies the specific type or category of the event, such as order.created or payment.processed. The ce-type events are the ones that refer the OE tenant events.
• ce-specversion - Represents the version of the CloudEvents specification with which the event is compliant. The ce-specversion attribute typically contains a string value indicating the version of the CloudEvents specification being used, such as "1.0" or "1.1".

• ce-id - Represents the unique identifier for the event instance. The ce-id attribute typically contains a string value that serves as a globally unique identifier (GUID) or a Universally Unique Identifier (UUID) for the event.

The signature has to be added in the request that is sent. You can use the following sample to see how to generate the signature

• The request.data is the payload. OE is schemaless, the payload can be empty or it can be in any valid Json format.

• The secret is the one that you need to copy from the Management Dashboard admin settings.

Request Examples

Here's an example of a request to generate a signature:

var sha256digest = CryptoJS.HmacSHA256(request.data, "the-secret-from-management-dashboard");
var base64sha256 = CryptoJS.enc.Base64.stringify( sha256digest);
postman.setEnvironmentVariable("hmac", base64sha256);

See an example of a postman environment

{
	"id": "0c29dar5-13er-4766-82f8-91e87a45ghy6",
	"name": "devenv",
	"values": [
		{
			"key": "src",
			"value": "src_w34a44rft567",
			"type": "default",
			"enabled": true
		},
		{
			"key": "secret",
			"value": "<replace with secret from OE->Admin->Events in Management Dashboard>",
			"type": "secret",
			"enabled": true
		},
		{
			"key": "hmac",
			"value": "",
			"type": "any",
			"enabled": true
		}
	],
	"_postman_variable_scope": "environment",
	"_postman_exported_at": "2023-04-19T07:26:28.294Z",
	"_postman_exported_using": "Postman/10.10.4"
}

See an example of a postman collection

{
	"info": {
		"_postman_id": "d5ce7aff-7f71-4261-b369-7cd67813e878",
		"name": "OE Hello World",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
		"_exporter_id": "12223042"
	},
	"item": [
		{
			"name": "say-hello",
			"event": [
				{
					"listen": "prerequest",
					"script": {
						"exec": [
							"var sha256digest = CryptoJS.HmacSHA256(request.data, postman.getEnvironmentVariable(\"secret\"));",
							"var base64sha256 = CryptoJS.enc.Base64.stringify( sha256digest);",
							"postman.setEnvironmentVariable(\"hmac\", base64sha256);"
						],
						"type": "text/javascript"
					}
				}
			],
			"request": {
				"method": "POST",
				"header": [
					{
						"key": "ce-source",
						"value": "postman",
						"type": "text"
					},
					{
						"key": "ce-type",
						"value": "hello_world",
						"type": "text"
					},
					{
						"key": "ce-specversion",
						"value": "1.0",
						"type": "text"
					},
					{
						"key": "ce-id",
						"value": "{{$guid}}",
						"type": "text"
					},
					{
						"key": "x-emporix-hmac",
						"value": "{{hmac}}",
						"type": "text"
					}
				],
				"body": {
					"mode": "raw",
					"raw": "{\n    \"hello\" : \"world\"\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "https://signals.emporix.io/e/{{src}}",
					"protocol": "https",
					"host": [
						"signals",
						"emporix",
						"io"
					],
					"path": [
						"e",
						"{{src}}"
					]
				}
			},
			"response": []
		}
	]
}

Creating a new event

Once the connection setup is complete, you can proceed to create a new event. Ensure that the name of the event you create corresponds to the event used in Postman's POST request.

Utilize the ce-type attribute to recognize events and provide information indicating that the event has occurred. By aligning the event configured in OE with the ce-type name, you ensure that information about events is accurately received and processed. This alignment facilitates seamless communication and data handling between OE and Postman.

To create a new event:

1. Go to OE -> Admin -> Events.

2. Choose Create New Event.

3. Specify the Display and Event names.

   • Display name is the name that is visible in the UI when you create an execution template, for example: Order Created.

   • Event name is the name of the registered event, for example: emporix/dcp/order.created.

4. Save your changes.