# Setting up a First Value Stream
By going through this guide, you will create a value stream that responds to a **Hello World** event from a sender. The response is a feedback form that is first sent to the sender with a request for completion. In this case, the sender can be a customer whom we are asking for feedback. The value stream ends once the sender submits the feedback form. To successfully complete the trail, make sure to go through all the sections from top to bottom.
## Building the initial part of the value stream
A value stream involves an initiating event followed by subsequent steps. External events work as triggers for value stream to run, they are transmitted to an Orchestration Engine event-receiver endpoint. The subsequent process steps are basically a combination of actions following one after another making a whole process complete.
To start building a value stream, follow these steps:
1. Create a new **Hello World** event, with `hello_world` as the event name, which works as its technical ID.
* To create the event, go to **Orchestration** -> **Events** -> **Event Registry**. For details, see the [Events Registry](https://developer.emporix.io/oe/management-dashboard/events/event-registry) and [Events Authentication and Configuration](https://developer.emporix.io/oe/management-dashboard/events/events-configuration) guides.
2. Create a new value stream with the `hello_world` event as a trigger.
* To create the value stream, go to **Orchestration** -> **Value Streams** and choose **Create value stream**.
* Add **Hello World** as a name for your process.
* Choose the **Hello World** event as a trigger for the process.
* Choose **Publish** to save the changes. When you choose publish, your changes are saved but the process is not active yet. To **activate the process**, use the active/inactive toggle in the value stream dashboard.
{% hint style="info" %}
For details on how to create a value stream, see [Creating a Value Stream](https://developer.emporix.io/oe/value-streams/working-with-value-streams/creating-value-streams) guides.
{% endhint %}
## Sending an event to trigger the value stream
To move to the next steps you need the data to be processed first. To do so, you need to send some data to OE to complete the event connection. You can do this using Postman, or with Celonis Action Flows.
### Postman
1. Get the Webhook Target URL and HMAC Secret and send the Hello World event following the instructions in [Events Authentication and Configuration](https://developer.emporix.io/oe/management-dashboard/events/events-configuration). The authentication and configuration guide includes a **Postman collection** that also shows you how to authenticate the request by generating the HMAC signature.
You can check there all the details that must be included in the request.
Send the POST request, with `{"hello" : "world"}` in the body content. The endpoint responds with 200 OK status and a payload to confirm a successful receipt. Here's how the payload looks like:
```json
{
"status": "SUCCESS",
"message": "Request successfully handled. Request ID: req_M4XnFkQm2aPUTGqiteyN",
"request_id": "req_M4XnFkQm2aPUTGqiteyN"
}
```
{% hint style="warning" %}
* If you receive 401, verify if your setup for the `secret` is correct.
* If you receive any other status, verify if the webhook source URL is correct.
{% endhint %}
2. Note down your `request_id`, it may be useful later to search for the process in OE.
### Celonis action flows
If you are a Celonis customer and want to trigger a value stream from EMS, it is possible to do this using the Action Flow module.\
There's a public [Emporix Orchestration Engine module](https://www.make.com/en/integrations/emporix-oe) that enables you to start value streams.
1. Add the OE module to your Action Flow.
2. Set up the connection to include the `source`, `secret` and OE API `client` and `secret` following the instructions in [Configuring a Connection between OE and Make Modules](https://developer.emporix.io/oe/value-streams/working-with-value-streams/configuring-a-connection-between-oe-and-make-module).
3. Select the “Hello World” event type.
4. Send `{ “hello” : “world” }` as the payload.
5. Trigger the action flow.
To confirm a successful receipt, the endpoint responds with 200 OK status and a confirmation payload.\
Here's how the payload looks like:
```json
{
"status": "SUCCESS",
"message": "Request successfully handled. Request ID: req_M4XnFkQm2aPUTGqiteyN",
"request_id": "req_M4XnFkQm2aPUTGqiteyN"
}
```
{% hint style="warning" %}
* If you receive 401, verify if your setup for the `secret` is correct.
* If you receive any other status, verify if the `source` value is correct.
{% endhint %}
6. Note down your `request_id`, it may be useful later to search for the process in OE.
## Verifying receipt of the message in OE Debugger
Check if your payload was retrieved and whether it activated a new value stream. You can verify this using the [Value Streams Debugger](https://developer.emporix.io/oe/troubleshooting/value-streams-debugger).
1. Go to **Value Streams** and open the debug mode of your Hello World value stream. You can do this from the main view by clicking the magnifier icon, or opening the process and choosing the **Go to Debugger** option. If the request worked, you should see the details of the instance run.
2. To confirm the data was received as expected, open the instance and check the logs.
## Creating a feedback form
After creating and validating the trigger event, we can now add a process step in the Hello World value stream. The process step includes a form prepared for the sender to add a feedback message.
To create the form, you can use the Form builder that is integrated with OE. For details, see [Forms](https://developer.emporix.io/oe/management-dashboard/forms) documentation.
1. Create a new form with **Feedback** as a name.
2. Add a new **dropdown** component and label it as **Sentiment** in the **Display** tab.
3. Go to the **Data** tab and configure the component to have three **Data Source Values**:
* happy
* sad
* indifferent
4. Go to the **Validation** tab and flag the field with the dropdown as **Required**.
5. Save the configuration.
6. Add two separate text fields:
* first with a **First Name** label - set it as required in the validation tab
* second with a **Last Name** label
7. Save the form. You can also check its preview to see if all the fields are added.
## Creating a skeleton scenario process step
1. Update the event that you sent previously with a new data: **replyTo**, where you add the email address as a value.
```json
{
"hello" : "world",
"replyTo" : "your.email@emporix.com"
}
```
2. Send the updated event to OE. You can use Postman or Celonis Action Flow as in the previous step.
3. Go to debugger to check if the data was properly received.
4. Copy the **Instance ID**, we will use it in the next steps.
5. Go to your **Hello World** value stream, and a new process step. For details, see [Creating Value Streams](https://developer.emporix.io/oe/value-streams/working-with-value-streams/creating-value-streams).
6. In the new process step, choose the **Create New Scenario** option.
This opens a new tab and redirects you to a scenario step template wizard in Make, with a starting module and completion event.
After going to Make, ensure you are working in the right organization. The name should reflect your tenant name in OE. To check if the organization is the correct one, it's enough to hover over the Make's sidebar, the name is visible at the top. Then, you can either click directly on the template to start working with it, or choose the **Start guided setup** option to continue.
{% hint style="danger" %}
If you click on any of the Make's sidebar nodes, it switches off the template and redirects you the selected section in Make. It's not possible to get back to the template.
{% endhint %}
7. Add a name for the scenario, in this example it's "Send a Survey on Hello World". Save the scenario to make sure the name is kept.
8. Add a webhook name in the **Trigger Event** module.
{% hint style="warning" %}
There's no validation requirement for the name, but we recommend to use the same name for the webhook as for the scenario. Without the webhook, the value stream is marked as **invalid** in OE.
{% endhint %}
The webhook connection is established automatically, but it may happen that you'll need to set it up manually. In that case choose **Add** next to the connection field in the Webhook module and provide there the **Connection Name**, **Tenant ID** and **Event-Receiver Secret**.
The **tenant ID** is the first part of the value stream ID, you can find it in two places:
* In the **OE** -> **Admin** -> **Settings** tab, the tenant ID is displayed next to the Make Team name.
* In the URL of your value stream instance.
9. The template shows that the last Make scenario step should be a **completion event**. To send the completion event, we need to create a new event in **OE Management Dashboard**. Go to **OE** -> **Events** -> **Event Registry** and create a new event with the following data:
* **Display name**: `Hello World Feedback Sent`
* **Event name**: `hello_feedback_sent`
10. Go back to your scenario editor in Make -> **Completion Event** module and select the connection.
**Optional**: If it happens that you don't have the connection established yet, you need to configure it in the module.
* Choose **Add** next to the **Connection** field.
* Provide the necessary data for the Event-Receiver Endpoint and Environment.
The data for the endpoint is the one from the Admin settings in OE, the data for the environment is the one that you can find in the Developer Portal in your API keys - COP API.
11. Select the newly created event as an **Event Type**. If you don't see the event, try to refresh the list.
12. Choose **Save**. This creates the scenario, you can now add a relevant name for it, for example **Send a Survey on Hello World**.
13. Get the Make scenario to access the **replyTo** field. For this, you can use the **Set Variable from Process Context** module to extract the **replyTo** email address that we send in the payload, and assign it to a **Variable** called email.
* Add the **Set Variable from Process Context** module and place it between the **Trigger Event** and **Completion Event** modules.
* Assign the Data from the Trigger Event.
* Select the Hello World value stream.
* Use the Instance ID from the debugger (see step 4) as the **Example Instance**. You can select the ID from the drop-down list. The ID at the top is the one from the latest instance.
* Enter `email` in the **Variable Name** field.
14. Modify the **Completion Module** payload to include the email. In the **Payload** field, select **Map as JSON String** and add the JSON string. The email should point to the email settings from the **Set Variable from Process Context** module. For example: `{ "email" : "{{4.email}}"}` - if the reference is to email from module 4.
{% hint style="warning" %}
If it happens that you don't see the email variable in the list, try running the scenario. Even if it doesn't start, the run trigger itself updates the from the previous modules.
{% endhint %}
15. Save the scenario.
16. Go back to your **Hello World** value stream in OE and add the **Send a Survey on Hello World** scenario as the next process step.
17. Choose **Publish** and then activate the new version of the **Hello World** value stream.
18. Check if your value stream is activated and if it has a **valid** status.
* Invalid status is usually caused by a missing webhook on the trigger module, or on improperly set up completion module.
* OE revalidates each value stream with every new publishing.
## Verifying if the scenario step works
To verify if you scenario works properly, do the following checks:
1. Go back to your scenario editor in Make.\
If you closed the tab with the scenario in Make, you can open it directly from the process step in the Hello World value stream.
2. To verify the step before activating the scenario, use the **Run once** option.
You should see a confirmation about a successful scenario load that is waiting for data.
3. Make sure there are no errors in your request and resend the previous request using Postman or Celonis Action Flow (as in Step 2 of **Creating a skeleton scenario process step section**) and check if the scenario is working as expected. You should see the operation details in the **Set Variable from Process Context** module. After you send the request, the scenario initializes and then you get a confirmation about scenario completion.
4. Optionally, go to debugger and verify if the new instance has logs including the new process step that you added. If there are any errors in your Make scenario, you can navigate directly to the specific scenario logs in Make from the process step visible in the debugger.
## Update the scenario process step to email the feedback survey
In this step we will use the **Feedback** form that we created earlier and email it to the **replyTo** email address. We will pre-populate one of the fields in this form. The recipient will be able to use a Magic Link to open the form. We will then change the value stream to wait till the Feedback form has been submitted (in this case saved as draft) before completing.
1. Go to **OE** -> **Events** -> **Event Registry** and create a new event with the following values:
* Display name: Hello World Feedback Provided
* Event name: `hello_feedback_provided` The event captures the feedback submitted by the recipient. All the submitted form data is enclosed inside this event.
2. Go to your **Send a Survey on Hello World** scenario in Make.
3. Add the **Create Form Magic Link** module and place it after the **Set Variable from Process Context** module.
4. Set up the module configuration:
* Select the **Feedback** form
* Choose **no** in the **Assign Contact** - we use the email address sent in the event
* Select the **Hello\_feedback\_provided** event as the submission event type. This is what ensures that the expected event is raised when the form is submitted.
* Leave **Submitted Only Once** to **Yes** - we do not want the form to be replied to more than once.
* In the **Value Stream Instance ID** field, select the **Value Stream Instance ID** item from the list of items available for the **Trigger Event** module. This is to ensure the correct process is resumed when the form is submitted. Instance ID is the ID that you can find in the debugger, but here we need to map the relevant field from the trigger.
* **Name** and **Language** fields can be left empty.
* Choose **Save** to save your module configuration.
5. Add the **Submit Form Draft** module and place it after the **Create Form Magic Link** module.
6. Set up the module configuration:
* Map the **Magic Link ID** from the previous step
* Select the **Feedback** form to reveal the fields available for pre-population. The fields can be left empty.
7. The form has to be emailed to the recipient. To do this, send a message to the recipient containing the magic link. You can use any supported Mail Provider for this. The example below shows Gmail module with the linked account.
{% hint style="warning" %}
Use the OE form UI to review and submit the form. The link has the following format: [http://cop.emporix.io/forms/TENANT\_ID/MAGIC\_LINK\_ID](https://cxpf-ext.emporix.io/TENANT_ID/MAGIC_LINK_ID)\
Match the MAGIC\_LINK\_ID and the TENANT\_ID. The TENANT\_ID is specific to the tenant for which you're creating the scenario, it can be fetched from the Trigger Event.
{% endhint %}
The whole Make scenario should look like this:
8. Go back to your **Hello World** value stream in OE and add the **Hello World Feedback Provided** event as a trigger, after the **Send a Survey on Hello World** process step. This trigger is necessary to complete the value stream, it receives information that a form was submitted by the user.
9. Publish the value stream and ensure it's activated again. Send the previous event one more time from Postman or Celonis Action flow to trigger the process. The email with the survey link is sent to the specified email address.
10. Submit the reply to the form.
11. After submitting the reply, you can check if the last step of your **Hello World** value stream (Hello World Feedback Provided) was finished.
## Troubleshooting
If it happens that the **Hello World** value stream trail did not work for you, see some fixing hints below:
* "I got the email, submitted the form, but the process did not complete."
* Check if you mapped the value stream ID in the **Create Form Magic Link** module
* Make sure you selected the **Hello\_feedback\_provided** event as the submission event type in Create Magic Link module
* "I created the process step with the **Send a Survey on Hello World** and did the test run but I didn't get any email."
* Check if there were any errors in the Make scenario sending the email
* Check your junk folder for the email
* Check you mail provider's logs
