Using Variables from Order in Workflow

Let's look at using variables from an order event in a transactional workflow, for example, Order delivered. Correctly writing variables is necessary for the workflow to work without errors and for all the required parameters to be inserted into the message content.

Main Steps for Preparing Transactional Campaigns

Preparing any workflow that sends messages with information about user data, delivery address, order number, etc., includes the following steps:

• transferring of order data via API (you can use Add orders or Generate event API resources);
• preparing an email with dynamic content;
• setting up a workflow for sending the email.

We will look at transferring orders using the Add orders API resource. You can find out more about its use in this manual.

Transferring Order Data

The request contains one or more orders with mandatory and optional fields.

Required fields for the orders array:

• ExternalOrderId,
• ExternalCustomerId,
• TotalCost,
• Status,
• Date,
• Email or Phone

Required fields for the items array:

• ExternalItemId,
• Name,
• Quantity,
• Cost,
• Url,
• ImageUrl

Also, several important order statuses display the sales funnel:

• A created order usually has the INITIALIZED status.
• An order in the delivery process is displayed with the IN_PROGRESS status.
• For paid and delivered orders, the DELIVERED status is used.
• For canceled – CANCELLED.

Such a differentiation is necessary primarily to understand precisely what stage the customer is at, and not send delivery messages to those who canceled or just created the order.

Creating Events

Every time you pass order data via the API, corresponding events are created in the system, which you can later use as a condition that launches a triggered workflow.

The names of transactional events consist of the word order and the status added to it, for example, orderDELIVERED. You can see them in the Triggers → Event history section in the Yespo system.

Each event has a unique key. For order events, these are order identifiers, which are passed in the externalOrderId parameter.

For example, order events include the following standard variables:

• ${eventKey} – order unique key, contains the externalOrderId field value.
• ${orderId} – order ID in the Yespo database. The parameter is needed for the workflow’s functioning.
• ${contactId} – contact ID in Yespo.
• ${EmailAddress} – customer’s email address (if provided in the order).
• ${SMS} – customer’s phone number (if provided in the order).

Using Event Parameters in Workflow

Write event parameters in workflows precisely in the form they are transmitted in events. If the standard EmailAddress parameter is passed in an order event, the variable in the email input field in the workflow should also be called EmailAddress. Other formats like email or EmaiL will not work in the workflow.

For users' convenience, system events (generated by a subscribe request or a regular workflow) have some standard parameters, so such workflow blocks usually work by default, even without manually specifying variables. However, if you change the event for launching the workflow to something other than the standard one, the workflow will not run by default. The Yespo team recommends manually specifying variables in the workflow to avoid errors.