Events Authentication and Configuration

Establish a connection between VSM and Cloud Events.

Value Stream Modeller 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 VSM. 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 VSM execution

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

To ensure that VSM can receive events, the initial step is to establish the connection and verify that authentication functions properly. This connection requires specific VSM 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 VSM tenant.

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

Overview of establishing a connection between an external event source and the VSM event-receiver endpoint

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

1. Go to VSM → Admin → Settings.
2. Use the Source and Secret values for postman environment configuration.

VSM:

The Admin Settings tab showing the Event-Receiver Endpoint Source and Secret values used for CloudEvents authentication

Postman:

Postman environment configured with src, secret, and hmac variables copied from VSM Admin settings

Source - the attribute that defines the endpoint that is be used for sending an event to VSM, 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 VSM.

The Postman request URL using the src variable from the environment to target the event-receiver endpoint

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.

CloudEvents headers in Postman, including the x-emporix-hmac header for request authentication

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 VSM 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.

Pre-request Script that generates the HMAC signature from the request payload and secret environment variable

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. VSM 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 VSM->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": "VSM 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 VSM 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 VSM and Postman.

To create a new event:

1. Go to VSM -> 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.