Sitecore OrderCloud Documentation

docs

Portal login

Message Senders

Published by Crhistian Ramirez-Hernandez on May 23, 2022

Last updated on March 13, 2024

Message Senders is a feature that helps to deliver event-driven notifications to users based on certain key commerce activities. OrderCloud defines the activities, which could be things like order submitted, order shipped, forgot password, etc. and leaves it open to you to decide the presentation and notification format such as email, text, or perhaps something else completely.

Message Senders vs Webhooks

Webhooks are another OrderCloud feature that are event-driven and could conceivably be used to drive notifications, but webhooks are much less suited than message senders for this task. For example consider trying to build a notification to all users who are able to approve a newly submitted order. To accomplish this with webhooks you would need write code to cover the following steps:

  1. Build a handler to receive the submit for your approval webhook

  2. Take the high level order information and query the API for the rest of the needed order data

  3. Query the API for all of the possible approving users (which can be complex)

  4. Look up approving users' contact information

  5. Send each message

In contrast, an OrderSubmittedForYourApproval message sender will retrieve all of the relevant information for you and send a single web request for each approver message that should be sent. This enables you to write a single, simple handler whose sole responsibility is to format the message and send it via email, text, or whichever other format you desire.

Message Sender Types

The message sender types below outline all of the different commerce activities that can trigger a notification via message senders. If you're not seeing an activity that you would expect, please reach out to us and we will consider adding it.

Message Type

Description

NewUserInvitation

Notify the buyer user when an admin user creates them or when they self register

ForgottenPassword

Notify the user when they initiate a password reset request

OrderSubmitted

Notify the buyer user when they submit an order

OrderSubmittedForApproval

Notify the buyer user when their order has been submitted, but has been placed on hold pending approval

OrderApproved

Notify the buyer user when the order that was previously on hold, has been approved and released for fulfillment

OrderDeclined

Notify the buyer user when the order that was previously on hold, has been declined and will not be fulfilled

OrderSubmittedForYourApproval

Notify approving users that there is a new order pending their approval

OrderSubmittedForYourApprovalHasBeenApproved

Notify approving users that an order that was previously on hold pending their approval has been approved

OrderSubmittedForYourApprovalHasBeenDeclined

Notify approving users that an order that was previously on hold pending their approval has been declined

ShipmentCreated

Notify the buyer user when a shipment was made for their order. Please note triggering this requires a very specific order of operations. First, the shipment must be created with a ShippedDate set to null, then the relevant shipment items should be added to the shipment, and finally the shipment should be patched with a ShippedDate

OrderReturnSubmitted

Notify the buyer user when they submit an order return

OrderReturnSubmittedForApproval

Notify the buyer user when their order has been submitted, but has been placed on hold pending approval

OrderReturnApproved

Notify the buyer user when the order that was previously on hold, has been approved and released for fulfillment

OrderReturnDeclined

Notify the buyer user when the order return that was previously on hold, has been declined and will not be fulfilled

OrderReturnSubmittedForYourApproval

Notify approving users that there is a new order return pending their approval

OrderReturnSubmittedForYourApprovalHasBeenApproved

Notify approving users that an order return that was previously on hold pending their approval has been approved

OrderReturnSubmittedForYourApprovalHasBeenDeclined

Notify approving users that an order return that was previously on hold pending their approval has been declined

OrderReturnCompleted

Notify buyer users that an order return they submitted is now complete

Configuration Options

Before you can start sending messages you'll need to decide which approach you want to take to to implement message senders. There are three different configuration options ranging from least to most control. Please read the following sections for more detail.

Default Sender

This is our no code option. It sends emails with our own Mandrill account as well as with our own templates. There is nearly no setup to get going but it also means there is no control over the email templates or the data that is sent.

To enable this option:

  1. Create a message sender in the portal and select "Default Sender"

  2. Give it a name

  3. For each template optionally define the "Message Subject". "Message From Email" can not be customized on default senders

  4. Assign the message sender to the relevant parties OR use AllowAllBuyers if you don't need explicit assignments

Custom Mandrill Account

This is our low code option that gives you a bit more control - you are able to provide your own custom email templates but the actual sending of the emails is handled by OrderCloud. This option requires that you have your own Mandrill/Mailchimp account.

To enable this option:

  1. Create each of your email templates in Mandrill. Refer to this table to determine which variables are available to render in your email template.

  2. Create a message sender in the portal and select "Custom Mandrill Account"

  3. Give it a name

  4. Provide your Mandrill API Key

  5. Select which message types you want to enable. For each message type provide your Mandrill Template Name. Check out our default templates to use as a starting point.

  6. Assign the message sender to the relevant parties

Custom URL

In this option you provide OrderCloud the URL to your publicly available endpoint that will receive the event payload and is responsible for formatting as well as sending the notification. As you can imagine this grants you the most amount of control but it also requires more work on your end to accomplish. Here are a few reasons you may decide to go down this path:

  1. You want to use a different messaging provider than Mandrill

  2. You want to send more than just emails such as texts or maybe something else entirely

  3. You need your notifications to include data that isn't available in the normal event payload

  4. You need to add some additional business-specific decisioning logic when sending an email

To enable this option:

  1. Create and host a custom endpoint to receive and process the event payload

  2. Create a message sender in the portal and select "Custom URL"

  3. Give it a name

  4. Provide the URL to your custom endpoint from step 1.

  5. Select which message types you want to enable - any message type you select should be handled by your custom endpoint

  6. Assign the message sender to the relevant parties

Of course creating the custom endpoint is going to be the most laborious part of implementing this option. To help you out we've created a .NET starter project that demonstrates how to handles these types of events and has examples for sending notifications from Mandrill, Sendgrid, and Twilio. Check out the payload models for each message type.

Here are a few other things to keep in mind as you're building your endpoint:

  • We highly recommend validating every incoming request to ensure it is coming from a legitimate source. Similar to validating request for webhooks you can do the same with message senders and should verify that the x-oc-hash header matches the value of raw request body hashed by the SharedKey on the Message Sender. If it doesn't match, then you have an unverified sender of that web request.

  • Use the special variable {messagetype} in the custom URL provided to OrderCloud. This lets you define a single message sender configuration that can handle different message types. For example the custom url https://my-message-handler/{messagetype} that has opted in for an OrderSubmitted and ForgottenPassword message type will receive requests to the endpoint https://my-message-handler/ordersubmitted as well as https://my-message-handler/forgottenpassword.

  • If your handler needs elevated permissions to complete its work you may consider defining ElevatedRoles this will grant your endpoint a token for the recipient user that additionally has any elevated roles defined. This can help simplify your logic especially if your handler is a one-off serverless function for example.

  • Like most other entities in OrderCloud, Message Senders come with extended properties which you can use to store business specific data to drive custom behavior. Please note that xp will come through as ConfigData in the event payload.

  • Check out our default templates to use as a starting point.

Custom Email Templates - Mandrill Merge Vars

If you're using our Mandrill/Mailchimp integration and providing your own custom email templates then you can use these tables to determine which variables are available for you to render in your email templates.

Variables for ForgottenPassword and NewUserInvitation

Mandrill Variable

OrderCloud Property

username

Username

passwordtoken

passwordtoken

passwordverification

passwordverificationcode

passwordrenewalurl

passwordrenewalurl

Variables for Order Emails

Mandrill Variable

OrderCloud Property

firstname

Order.FromUser.FirstName

lastname

Order.FromUser.LastName

orderid

Order.ID

datesubmitted

Order.DateSubmitted

subtotal

Order.Subtotal

tax

Order.TaxCost

shipping

Order.ShippingCost

total

Order.Total

lineitemcount

Order.LineItemCount

Mandrill Variable

OrderCloud Property

cost

LineItems[i].LineTotal

quantity

LineItems[i].Quantity

productdesc

LineItems[i].Product.Description

productid

LineItems[i].Product.ID

productname

LineItems[i].Product.Name

products (array)

shiptoname

LineItems[i].ShippingAddress.FirstName + LineItems[i].ShippingAddress.LastName

shiptostreet1

LineItems[i].ShippingAddress.Street1

shiptostreet2

LineItems[i].ShippingAddress.Street2

shiptocity

LineItems[i].ShippingAddress.City

shiptostate

LineItems[i].ShippingAddress.State

shiptopostalcode

LineItems[i].ShippingAddress.Zip

shiptocountry

LineItems[i].ShippingAddress.Country

Mandrill Variable

OrderCloud Property

approvinggroupid

OrderApproval[i].ApprovingGroupID

status

OrderApproval[i].Status

datecreated

OrderApproval[i].DateCreated

datecompleted

OrderApproval[i].DateCompleted

approvals (array)

approverid

OrderApproval[i].Approver.ID

approveremail

OrderApproval[i].Approver.Email

approverfirstname

OrderApproval[i].Approver.FirstName

approverlastname

OrderApproval[i].Approver.LastName

approverusername

OrderApproval[i].Approver.Username

approverphone

OrderApproval[i].Approver.Phone

Mandrill Variable

orderxp (array)

orderxp_keyname

for first-level xp properties

orderxp_keyname_keyname

for nested xp properties

orderxp_keyname_index

for xp arrays

Variables for OrderReturn

Includes all of the variables for order emails and additionally the following:

Mandrill Variable

OrderCloud Property

orderreturnid

OrderReturn.ID

refundamount

OrderReturn.RefundAmount

Mandrill Variable

OrderCloud Property

returnitems (array)

LineItemID

OrderReturn.ItemsToReturn[i].LineItemID

Quantity

OrderReturn.ItemsToReturn[i].Quantity

RefundAmount

OrderReturn.ItemsToReturn[i].RefundAmount

Mandrill Variable

orderreturnxp (array)

orderreturnxp_keyname

for first-level xp properties

orderreturnxp_keyname_keyname

for nested xp properties

orderreturnxp_keyname_index

for xp arrays

Variables for ShipmentCreated

Includes all of the variables for order emails and additionally the following:

Mandrill Variable

OrderCloud Property

shipmentid

Shipment.ID

shipmenttrackingnumber

Shipment.TrackingNumber

shipper

Shipment.Shipper

dateshipped

Shipment.DateShipped

toaddressid

Shipment.ToAddress.ID

toaddresscompany

Shipment.ToAddress.Company

toaddressfirstname

Shipment.ToAddress.FirstName

toaddresslastname

Shipment.ToAddress.LastName

toaddressstreet1

Shipment.ToAddress.Street1

toaddressstreet2

Shipment.ToAddress.Street2

toaddresscity

Shipment.ToAddress.City

toaddressstate

Shipment.ToAddress.State

toaddresspostalcode

Shipment.ToAddress.PostalCode

toaddresscountry

Shipment.ToAddress.Country

toaddressname

Shipment.ToAddress.AddressName

Mandrill Variable

OrderCloud Property

cost

LineItem.LineTotal

quantityshipped

Shipment.Items[i].QuantityShipped

shipmentitems(array)

productdesc

Shipment.Items[i].Product.Description

productid

Shipment.Items[i].Product.ID

productname

Shipment.Items[i].Product.Name

Message Sender Event Payload models

If you are building a custom message sender it is necessary to understand what kind of payloads your endpoint handler will receive. The first table lists properties common to all message types. The tables below that one are the event payloads specific to each message type.

Generic Payload (not event specific)

Property

Description

OcLogIdHeader

Internal log id

Environment

Maps to one of OrderCloud's environments. Can be either Sandbox, Staging, or Production

BuyerID

ID of the buyer organization the user belongs to (if user is a buyer)

UserToken

Token of the recipient user, if ElevatedRoles is defined then the token will include those additional roles as well

Recipient

The full user object of the recipient user

CCList

The list of additional emails that will be CC'd for this message

EventBody

The specific event body for that message type (see below for each message type)

MessageType

The message type that this event was triggered for. Can be one of: NewUserInvitation, ForgottenPassword, OrderSubmitted, OrderSubmittedForApproval, OrderApproved, OrderDeclined, OrderSubmittedForYourApproval, OrderSubmittedForYourApprovalHasBeenApproved, OrderSubmittedForYourApprovalHasBeenDeclined, ShipmentCreated

ConfigData

This maps directly to any extended properties defined on the message sender

Event Body for ForgottenPassword and NewUserInvitation

Property

Description

Username

The username of the user submitting the request

PasswordRenewalUrl

The URL passed in the original request

PasswordRenewalVerificationCode

The verification code to be passed when resetting by verification code

PasswordRenewalAccessToken

The token of the user with only the role PasswordReset encoded. Used when resetting password by token

Event Body for Order Events

Property

Description

Order

The order that was submitted

Approvals

The array of order approvals for the order

LineItems

The array of line items for the orders

Products

The array of products for the order

Event Body for OrderReturn Events

Property

Description

Order

The order that was submitted

Approvals

The array of order approvals for the order

LineItems

The array of line items for the orders

Products

The array of products for the order

OrderReturn

The order return that was submitted

EventBody for ShipmentCreated

Property

Description

Order

The order that was submitted

Approvals

The array of order approvals for the order

LineItems

The array of line items for the orders

Products

The array of products for the order

Shipment

The shipment for the order

ShipmentItems

The array of shipment items for the shipment

Conclusion

You should now have a good understanding of what message senders are, how they differ from webhooks, and the different implementation options at your disposal


Still have questions?
Ask in our Community Channel

Content Powered By
Sitecore Logo

© Copyright 2024, Sitecore OrderCloud®. All rights reserved.

Contact Us
Privacy Policy
Sitecore