# Events Authentication and Configuration

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](https://developer.emporix.io/oe/oe-celonis/digital-processes/oe-celonis-data-flow/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.

{% hint style="info" %}
To learn more about CloudEvents, see:

* [CloudEvents](https://cloudevents.io/?mc_phishing_protection_id=164867-cgvppu0ukimc2q6i148g)
* [HTTP Protocol Binding for CloudEvents](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md)
* [CloudEvents spec](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#context-attributes)
  {% endhint %}

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

<figure><img src="https://1593395737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQHHnOQFqJkmze1kPDN3S%2Fuploads%2Fgit-blob-6760c50242687ad77440b27bec186b334f9018ad%2Fevents.drawio.svg?alt=media" alt=""><figcaption></figcaption></figure>

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:

<figure><img src="https://1593395737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQHHnOQFqJkmze1kPDN3S%2Fuploads%2Fgit-blob-e1bd7c5a1cc48f9b5da7638e269c5d950d65607a%2Fsettings_connection.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

Postman:

<figure><img src="https://1593395737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQHHnOQFqJkmze1kPDN3S%2Fuploads%2Fgit-blob-ae65169b5f17e5f90043c3f062e16ebfc9b1e899%2Fpostman_environment.png?alt=media" alt=""><figcaption></figcaption></figure>

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

<figure><img src="https://1593395737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQHHnOQFqJkmze1kPDN3S%2Fuploads%2Fgit-blob-2f56e9cb8ca77edf1215edf24809338e8e09cb7e%2Fpostman_source.png?alt=media" alt=""><figcaption></figcaption></figure>

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

<figure><img src="https://1593395737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQHHnOQFqJkmze1kPDN3S%2Fuploads%2Fgit-blob-bfadb313f266648a63109a897e06c146eca171c4%2Fpostman_secret.png?alt=media" alt=""><figcaption></figcaption></figure>

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](https://developer.emporix.io/oe/oe-celonis/digital-processes/working-with-digital-processes/digital-process-components#events-as-triggers).
* `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.

<figure><img src="https://1593395737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQHHnOQFqJkmze1kPDN3S%2Fuploads%2Fgit-blob-6a0370ed7e43675e54bf8bb647b923bc0ebb805c%2Fpostman_secret2.png?alt=media" alt=""><figcaption></figcaption></figure>

**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:

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

{% hint style="warning" %}

<details>

<summary>See an example of a postman environment</summary>

```json
{
	"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"
}

```

</details>
{% endhint %}

{% hint style="warning" %}

<details>

<summary>See an example of a postman collection</summary>

```json
{
	"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": []
		}
	]
}
```

</details>
{% endhint %}

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