Slack Integration

User guide: Creating Slack notifications for Order status updates in Quartzy

For questions, please reach out to support@quartzy.com

Overview

This user guide contains step-by-step instructions on how to set up alerts in Slack for Order status updates in Quartzy. These alerts will help Quartzy users keep track of their Quartzy orders in Slack and prepare ahead for upcoming deliveries.

Use case name	Use case description
Item ordered (Any Vendor)	Receive a Slack notification when an item is ordered from the Quartzy Shop or a non-Quartzy vendor
Item shipped (Quartzy Shop Only)	Receive a Slack notification when an item ordered from the Quartzy Shop gets shipped and is assigned a tracking number
Item delivered (Quartzy Shop only)	Receive a Slack notification when an item ordered from the Quartzy Shop gets delivered
Item backordered (Quartzy Shop only)	Receive a Slack notification when an item ordered from Quartzy becomes backorderedReceive a Slack notification when an item ordered from the Quartzy Shop becomes backordered
Item canceled (Quartzy Shop only)	Receive a Slack notification when an order is canceled for an item previously ordered from the Quartzy Shop
Item received (Any vendor)	Receive a Slack notification when an item ordered from the Quartzy Shop or a non-Quartzy vendor is received

Here is an example of a Slack notification that one can configure using the steps mentioned in this user guide.

Prerequisites

Before getting started, please go through this checklist of prerequisites:

• Quartzy

  • You should have an active account in Quartzy
  • You should be assigned to an Organization and a Lab in Quartzy by your lab manager

• Slack

  • You should have an active account in Slack
  • You should have access to the Workflow Builder feature in Slack
    • In case you do not have access to this feature, please share this link with your Slack administrator to enable this feature for you
      • https://slack.com/help/articles/360035822734-Manage-Workflow-Builder-access-and-permissions
    • Below is an example of how to navigate to this feature. For more details:, please refer https://slack.com/help/articles/360035692513-Guide-to-Workflow-Builder
  

Step-by-step instructions

1. Create a channel where you want alerts from Quartzy to appear

• Set up a new Slack channel or use an existing Slack channel to receive alerts.

  • In the example below, we created a channel called #orders-slack-alerts to receive Slack notifications
  

2. Choose and configure which alerts you want from Quartzy

• Depending on your use case, download the Slack Workflow files linked below.

Use case name	Use case description	Slack Workflow
Item ordered (Any vendor)	Receive a Slack notification when an item is ordered from the Quartzy Shop or a non-Quartzy vendor	Link
Item shipped (Quartzy Shop only)	Receive a Slack notification when an item ordered from the Quartzy Shop gets shipped and is assigned a tracking number	Link
Item delivered (Quartzy Shop only)	Receive a Slack notification when an item ordered from the Quartzy Shop gets delivered	Link
Item backordered (Quartzy Shop only)	Receive a Slack notification when an item ordered from the Quartzy Shop becomes backordered	Link
Item canceled (Quartzy Shop only)	Receive a Slack notification when an order is canceled for an item previously ordered from the Quartzy Shop	Link
Item received (Any vendor)	Receive a Slack notification when an item ordered from the Quartzy Shop or a non-Quartzy vendor is received	Link

• Open the Slack Workflow builder

  • Under your Slack workspace name, navigate to Tools > Workflow Builder

    

• Import the downloaded file specific to your use case using the Import button and assign a name to this imported workflow.

  

• In the example below, we use the name Order Item Shipped alerts from Quartzy for our Slack workflow

  

• Once the workflow is imported, you will be taken to a new screen with the configuration of the workflow

  • To start making changes to this workflow, click Publish.
  • Note: After you customize the workflow, you will be asked to publish the workflow again at a later step

  

• After you publish the imported workflow the very first time, you will see a confirmation window like the one below.

  

• To start customizing the content of the Slack notification, close the confirmation window and click on the Edit button next to the workflow step Send a message to....

  

• A new window would appear that would allow you to make customizations to the Slack notification

  • In the example below, you can change the destination of the Slack notifications using the dropdown Send this message to:
  • In the input box named Message text, you can change the text used in the Slack notification. As you make these changes, you can see a preview in the bottom half of the same window
  • In the example below, the Quartzy team has preconfigured a message with certain variables that describe a Quartzy order item. To view the complete list of available variables, please refer to this section below in the Appendix.
  

• Once you are done making changes, click Save first, followed by Publish Changes as shown in the example below

  

• Once the changes are published, click the link Copy URL in the first workflow step. Use this URL to set up a Webhook configuration according to instructions in this other user guide.

  • In this step you would need the following information as also shown in the screenshot below.

Information needed	Example
Use case	Order item shipped
Updated URL	https://hooks.slack.com/workflows/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

• Ensure "Flatten Output?" and "Set Null Values to an Empty String?" options are enabled as in this screenshot.

  

• Now, depending on your use case, when the relevant event occurs (e.g. Order placed, Order item gets shipped etc.), Quartzy will send information to this saved URL which will in turn trigger your workflow and send Slack notifications to the channel selected by you in the previous step.

Best practices, Troubleshooting tips and FAQs

Notification etiquette

• While Slack notifications can be sent as direct messages, we recommend using channels. This allows the users to mute the channel if they are not interested in a Slack notification.
• As a Slack administrator for your organization, before setting up alerts, we recommend that you discuss with your team members and then
  • Decide which alerts to set up for your organization
  • Determine the content and tone of the message to use in the alert
  • Determine when to configure @mentions in the alerts

Opting users in and out of Slack notifications

Slack provides lots of flexibility in terms of opting users in and out of a notification. We recommend the following options:

• If a particular user wants to opt out of all Quartzy notifications, they can mute or leave the Slack channel set up in the previous step.

• If a particular user wants to opt in to a specific type of notification, then they can use this user guide and configure a Slack workflow of their own.

• To opt out all users in your organization from a particular type of notification (e.g. Order item shipped), you can Unpublish the entire Slack workflow corresponding to this notification. Here is an example:

  

Troubleshooting

• If you notice that you are not receiving Slack alerts, the first place to check is the Activity tab of your Slack Workflow in the Slack Workflow builder

  

• Common errors include

  • Typos in variable names in the Slack workflow
  • Mismatch in email address set up for the same user in Quartzy vs. Slack

If you are getting stuck while troubleshooting, please reach out to support@quartzy.com

FAQs

Q. While I like the Slack Workflow builder, I want to customize the look and feel of my Slack messages further. What do you recommend I do for that?

• In Q4 2021, Quartzy will provide a Webhooks management API and UI using which you can access the JSON of event payloads used to trigger these Slack Workflows. This JSON format of events would allow you to create custom message formats in Slack. For this, you would need to become familiar with the Slack app framework, Slack message formats and the Block Kit tool from Slack.

Q. Besides Slack, I want to handle other integration use cases such as creating a task in Asana, adding a record in Google Sheets, trigger an action in my homegrown application etc. Can you help with that?

• To integrate with other tools such as Asana, Google Sheets or even your homegrown application, you can use Quartzy’s webhooks along with your own web server or with an Integration-platform-as-a-Service tool such as Zapier or Workato.
• To learn how to configure Quartzy’s webhooks, please use this other user guide.

Appendix

List of variables that can be configured

Field name	Description	Example value
specversion	Event specification	1
id	Event ID	d31891b9-17d4-4430-aa01-2e7be1df184c
source	Event source	https://quartzy.com
type	Event type	com.quartzy.sales-order-item.shipped
datacontenttype	Event content type	application/json
time	Timestamp when event got created	2021-07-01T18:28:06Z
data.sales_order_item.id	Order item ID	1638745
data.sales_order_item.status	Order Item status	SHIPPED
data.sales_order_item.sell_price.amount	Item price (in cents)	29307
data.sales_order_item.sell_price.currency	Item price currency	USD
data.sales_order_item.quantity	Item quantity	1
data.sales_order_item.estimated_shipment_date	Estimated Ship Date	2021-07-24
data.sales_order_item.product.id	Product ID	3685196
data.sales_order_item.product.item_name	Item name	Cytiva's Amersham Hybond P 0.45 PVDF 300mmx4m 1 roll/PK
data.sales_order_item.product.catalog_number	Catalog number	Q7KAY47
data.sales_order_item.request.id	Request ID	23440056
data.sales_order_item.request.requested_at	Timestamp when requested	2021-06-08T19:49:58+00:00
data.sales_order_item.request.requested_by.id	Requester ID	412978
data.sales_order_item.request.requested_by.first_name	Requester’s first name	Ankur
data.sales_order_item.request.requested_by.last_name	Requester’s last name	Datta
data.sales_order_item.request.requested_by.email	Requester’s email address	ankur.datta@quartzy.com
data.sales_order_item.shipments.0.id	Shipment ID	1676825
data.sales_order_item.shipments.0.carrier	Carrier name	FedEx
data.sales_order_item.shipments.0.tracking	Tracking number	1234567890
data.sales_order_item.shipments.0.quantity	Shipment quantity	1
data.sales_order_item.shipments.0.shipped_at	Timestamp when item got shipped
data.sales_order_item.shipments.0.delivered_at	Timestamp when item got delivered
data.sales_order_item.sales_order.id	Order ID	1295291
data.sales_order_item.sales_order.key	Order No.	QY21070005212006
data.sales_order_item.sales_order.lab.id	Lab ID	5212
data.sales_order_item.sales_order.lab.name	Lab name	BioChem Dept
data.sales_order_item.sales_order.lab.organization.id	Organization ID	6493
data.sales_order_item.sales_order.lab.organization.name	Organization Name	Quartzy Testing University

Example JSON of event payloads

• Order item shipped

{
   "specversion":"1.0",
   "id":"d31891b9-17d4-4430-aa01-2e7be1df184c",
   "source":"https://quartzy.com",
   "type":"com.quartzy.sales-order-item.shipped",
   "datacontenttype":"application/json",
   "time":"2021-07-01T18:28:06Z",
   "data":{
      "sales_order_item":{
         "id":"1638745",
         "status":"SHIPPED",
         "sell_price":{
            "amount":"29307",
            "currency":"USD"
         },
         "quantity":1,
         "estimated_shipment_date":"2021-07-24",
         "estimated_delivery_date":"2021-07-26",
         "product":{
            "id":"3685196",
            "item_name":"Cytiva's Amersham Hybond P 0.45 PVDF 300mmx4m 1 roll/PK",
            "catalog_number":"Q7KAY47"
         },
         "request":{
            "id":"23440056",
            "app_url":"",
            "requested_at":"2021-06-08T19:49:58+00:00",
            "requested_by":{
               "id":"412978",
               "first_name":"Ankur",
               "last_name":"Datta",
               "email":"ankur.datta@quartzy.com"
            }
         },
         "shipments":[
            {
               "id":"1676825",
               "carrier":"FedEx",
               "tracking":"1234567890",
               "quantity":1,
               "shipped_at":null,
               "delivered_at":null
            }
         ],
         "sales_order":{
            "id":"1295291",
            "app_url":"",
            "key":"QY21070005212006",
            "lab":{
               "id":"5212",
               "name":"BioChem Dept",
               "organization":{
                  "id":"6493",
                  "name":"Quartzy Testing University"
               }
            }
         }
      }
   }
}

• Order item backordered

{
   "specversion":"1.0",
   "id":"f72f060e-d7dc-42e9-b508-c23dbfdbe877",
   "source":"https://quartzy.com",
   "type":"com.quartzy.sales-order-item.backordered",
   "datacontenttype":"application/json",
   "time":"2021-07-01T18:24:18Z",
   "data":{
      "sales_order_item":{
         "id":"1638744",
         "status":"BACKORDERED",
         "sell_price":{
            "amount":"5942",
            "currency":"USD"
         },
         "quantity":1,
         "estimated_shipment_date":"2021-07-16",
         "estimated_delivery_date":"",
         "product":{
            "id":"26631140",
            "item_name":"Axygen 200uL Maxymum Recovery Universal Fit Filter Tips, Clear, Rack
Pack, 96 Tips/Rack, 10 Racks/Pack, 5 Packs/Case.",
            "catalog_number":"Q9R2YA4"
         },
         "request":{
            "id":"23497518",
            "app_url":"",
            "requested_at":"2021-06-14T18:17:37+00:00",
            "requested_by":{
               "id":"412978",
               "first_name":"Ankur",
               "last_name":"Datta",
               "email":"ankur.datta@quartzy.com"
            }
         },
         "shipments":[
            
         ],
         "sales_order":{
            "id":"1295291",
            "app_url":"",
            "key":"QY21070005212006",
            "lab":{
               "id":"5212",
               "name":"BioChem Dept",
               "organization":{
                  "id":"6493",
                  "name":"Quartzy Testing University"
               }
            }
         }
      }
   }
}