Order Fulfillment with SMS Notification

In the following recipe, we will walk through a flow where a merchant has marked an order fulfilled through their Order Management System (OMS). Conscia is listening for a webhook from the OMS, and marks the commerce order fulfilled and sends an SMS notification to the shopper letting them know their order is on the way. We will use Twilio and Elastic Path Commerce Cloud APIs as well as a Postman call to simulate a webhook event from an OMS.

Overall Orchestration Flow

Here is the flow that we will be modeling in the DX Engine:

• The merchant fulfills the order, triggering a webhook with the order status and shipping information.
• A Conscia listener hears the event and triggers:
  • Elastic Path to update the order status to Fulfilled, and
  • Twilio to send an SMS to the shopper with shipping information.

Mapping Out Orchestration Components, Templates, and Listeners

The Order Fulfilled listener invokes the Order Fulfillment Template once the merchant has fulfilled the order and passes the necessary Context values through the engineRequest field on the listener:

"engineRequest": {
  templateCode": "epcc-order-fulfilled",
  "context": {
    "epcc_orderId": "`body.orderId`",
    "status": "`body.status`",
    "shipping_method": "`body.shipping_method`",
    "tracking_number": "`body.tracking_number`",
    "edd": "`body.edd`"
  }
}

The Order Fufillment Template consists of the following Components and Context values:

Orchestration Flow

When the merchant marks the order fulfilled in their order management system, the order management system will emit a webhook containing the order id, status, and shipping information.

In Conscia, we have created an Order Fulfilled listener waiting for this order fulfillment event. It's looking in particular for the order id and status, and then triggering the Order Fulfilled Template.

• Elastic Path Fulfill Order: With the order id passed in the webhook payload from the OMS, we can update the order status in Elastic Path and mark it fulfilled. We verify in the trigger conditions that the status coming from the OMS is in fact "fulfilled" before running this component. If you have set up additional custom fields on the Elastic Path order to hold shipping information, you can pass that in this API call as well.

• Twilio Send Order Fulfilled Message: Using the information provided by the webhook as well as the customer name and phone number retrieved from Elastic Path, we can send a text notification to the customer letting them know that their order has been fulfilled and how to track it. Twilio sends back a "queued" status and you may want to implement another listener to wait for the successful delivery message and troubleshoot if it fails.

DX Engine Configuration Details

You will need to configure a connection to Twilio and to Elastic Path Commerce Cloud.

Below are instructions on how to configure the two connections, the listener, and each of the Components discussed above.

Create a Connection to Twilio

• Navigate to the Connections page (Settings --> Connections).
• Click the Configure Connection button.
• Enter the following and click Submit:

Field	Value
Connection Code	twilio-resource-connection
Connection Name	Twilio Message Resource Connection
Connector	Universal API Connector
Base URL	Get value from: Literal https://api.twilio.com/2010-04-01
Base Header	Header: Authorization Value (JS Expression): 'Basic ' + secret('twilio-basic-creds-btoa')

Twilio requires your credentials to be Bas64 encoded. You can store the encoded authorization token in a Conscia Secret and refer to it from the Connection header.

Create a Connection to Elastic Path Commerce Cloud

• Navigate to the Connections page (Settings --> Connections).
• Click the Configure Connection button.
• Enter the following and click Submit:

Field	Value
Connection Code	epcc-connection
Connection Name	Elastic Path Commerce Cloud Connection
Connector	Universal API Connector
Base URL	Get value from: Literal https://useast.api.elasticpath.com

Create a Listener to listen for the order validated webhook

To create a listener you will need to make a direct API call to DX Engine.

POST https://engine-staging.conscia.io/api/listeners

{
  "listener": {
    "listenerCode": "order-fulfilled",
    "name": "Order Fulfilled",
    "sync": true,
    "endpointRequestSpec": {
      "methods": ["POST", "PUT"]
    },
    "engineRequest": {
      "templateCode": "epcc-order-fulfilled",
      "context": {
        "epcc_orderId": "`body.orderId`",
        "status": "`body.status`",
        "shipping_method": "`body.shipping_method`",
        "tracking_number": "`body.tracking_number`",
        "edd": "`body.edd`"
      }
    },
    "endpointResponse": {
      "status": 200,
      "body": {
        "epcc_trx_response": "`engineResponse.components['twilio_sms_response']`"
      },
      "headers": [
        {
          "header": "content-type",
          "value": "application/json"
        }
      ]
    }
  }
}

The mocked webhook event looks like this:

POST https://engine-staging.conscia.io/api/experience/_listener/:listenerLocator/:listenerUuid

Body:

{
    "orderId":"48f24697-f51f-4dd3-a21c-34f6d14aa393",
    "status":"fulfilled",
    "shipping_method": "UPS",
    "tracking_number": "LZ243019839US",
    "edd": "2024/03/26"
 }

Create a Component to fulfill the order in Elastic Path

• Navigate to the Experience Components page (Manage Experiences --> Components)
• Click the + Add Component button.
• Enter the following and click Submit:

Field	Value
Component Code	epcc-fulfill-order
Component Name	EPCC Fulfill Order
No Rules	Checked
Component Type	Conscia - Universal API Connector

The DX Engine will create and prepare the Component for further configuration. You should see the new component appear in the Component listing.

• Click Edit.
• Enter the following and click Submit:

Field	Form Tab	Value
Connection	Main	Elastic Path Commerce Cloud Connection
Webservice Path	Main	Get value from: JS Expression /v2/orders/${contextField('epcc_orderId')}
Method	Main	POST
Headers	Main	Header: Authorization Value (Context Field): EPCC Client Credentials Token
Headers	Main	Header: content-type Value (Literal): application/json
Body	Main	Get value from: JS Expression {"data": {"type": "order","shipping": "fulfilled"}}
Trigger Expression	Conditions	contextField('status') === 'fulfilled'

Create a Component to send an SMS from Twilio

• Navigate to the Experience Components page (Manage Experiences --> Components)
• Click the + Add Component button.
• Enter the following and click Submit:

Field	Value
Component Code	twilio-send-order-fulfilled-message
Component Name	Twilio Send Order Fulfilled Message
No Rules	Checked
Component Type	Conscia - Universal API Connector

The DX Engine will create and prepare the Component for further configuration. You should see the new component appear in the Component listing.

• Click Edit.
• Enter the following and click Submit:

Field	Form Tab	Value
Connection	Main	Twilio Message Resource Connection
Webservice Path	Main	Get value from: Literal /Accounts/{{Account SID}}/Messages.json
Method	Main	POST
Headers	Main	Header: Content-Type Value (Literal): application/x-www-form-urlencoded
Body	Main	Get value from: JS Expression

'To=' + componentResponse('epcc-fulfill-order').data.shipping_address.phone_number +'&From=+18316619576&Body=Your order #' + componentResponse('epcc-fulfill-order').data.id + ' has been fulfilled! ' + contextField('shipping_method') + ' Tracking number: ' + contextField('tracking_number') + ' Estimated Arrival: ' + contextField('edd') + ' Love, TheShop'

References

• Twilio API documentation - Message Resource
• Elastic Path Commerce Cloud API documentation - Orders
• DX Engine Listener documentation