Displaying Shopify Data in Tickets Using Data Viewer

Within Teamwork Desk, you can use the Data Viewer integration to pull data from your Shopify account and display it in the customer details panel of individual tickets.

The Data Viewer is designed to allow you to fetch data from remote systems and display that data in Desk. You can make calls to open and authenticated JSON APIs and use a template to format how the response will look.

Step 1: Getting your credentials from Shopify

Go to the Apps section of your Shopify account and select the Manage private apps option at the bottom of the page.

In the Private apps view, click the Enable private app development button.

Note: You will need to enable private app development so that the integration can access your Shopify data.

You will then need to accept the required terms and conditions before proceeding.

Once private app development has been enabled, click the Create private app button.

When creating the private app, you will need to give it a name and set an email address.

Private app name
Emergency developer email - an email address to receive any communications from Shopify, such as your Teamwork Desk support inbox address.

E.g. support@yourcompany.com

Scroll to the Admin API section and click the Show inactive Admin API permissions option on the right.

Using the dropdown to the right of each item type, update only Customers and Orders to Read access.

Customers

Orders

Click the Save option at the top or bottom of the private app screen to create the new app.

A pop-up will open asking you to confirm the creation of the app.

Once the app has been created, you will see your open API access credentials visible in the Admin API subsection of the app settings.

Step 2: Querying Shopify

In order to pull information from Shopify, you will need to add a GraphQL query to the body of the Data Viewer settings in Teamwork Desk.

The query in this example will return information about your orders and customers. The most important part of this query is: ${ticket.customer.email}.

When you are viewing a ticket in Teamwork Desk, the associated customer's email address will automatically be posted in the query via this email variable.
The email address will then be checked for a match in your list of customers in Shopify in order to return the related Shopify data in the ticket sidebar.

{
  "query": "query{ orders( first: 10, query:\"email:${ticket.customer.email}\" ) { edges { node { id currencyCode email name createdAt updatedAt fullyPaid confirmed totalReceivedSet{presentmentMoney{amount}} totalOutstandingSet{presentmentMoney{amount}} totalRefundedSet{presentmentMoney{amount}} lineItems ( first: 10 ) { edges  { node { id name image { originalSrc } sku } } } customer{ state email firstName lastName ordersCount totalSpentV2{amount}} }}}}"
}

If you want to make your own modifications in querying the Shopify API, you can follow Shopify's GraphQL documentation.

Step 3: Configuring the Data Viewer app

In the settings area of your Teamwork Desk site, go to the Integrations subsection and select Desk Data Viewer.

Note: If you have not yet installed Desk Data Viewer for your account, you will need to follow those steps first.

While viewing the Data Viewer integration, go to the Request subsection to fill out the required details.

Note: Data Viewer currently only supports one data request at a time.

Required settings:

Method (for GraphQL): POST
URL (API endpoint):

https://yourshopifyappname.myshopify.com/admin/api/2021-01/graphql.json
Replace yourshopifyappname with the name you gave your private app in Shopify.
Note: This endpoint may change over time with different versions of the Shopify API.

Authentication: Basic
Username and Password: Copy your API key and password from the private app in Shopify.

Body: Paste the sample query outlined in step 2 or add your own custom query.

Click Save to update your Data Viewer settings for Shopify.

Testing your query

You can optionally test your query by replacing ${ticket.customer.email} with an existing customer email address in the Body field.

"email:${ticket.customer.email}\" becomes "email:youremail@domain.com\"

Go to the Response tab of the Data Viewer settings and click Fetch data. This will run the query to verify that everything is working correctly.

Note: Once you finish testing, re-add the variable to the query in place of the specific email address in the Body of the Data Viewer settings so that the query will run for all customers.

If there are any issues with the configuration, you will be alerted in the response screen. You can find more information about each error in Shopify's API documentation.

Template and display settings

In the Template tab, select JSON Explorer from the dropdown and click Save.

Once you have completed the setup, you can use the Display tab to see the formatted results of the API call.

Note: We recommend checking the option to display the data in a modal to properly display the volume of Shopify data being passed to Data Viewer.

When viewing an individual ticket in Teamwork Desk, you will see a Data Viewer section in the customer details panel on the right.

Clicking the View data button will open a quick view panel to the right of the ticket detailing the corresponding Shopify information for the associated customer.

Step 4: Using adaptive cards

Adaptive cards are a powerful Microsoft tool that allow you to format JSON into visual UI components by defining how the JSON data will be rendered using a second JSON file as a template.

By using adaptive cards with Data Viewer, you can customize how the Shopify data is displayed in the pop-up modal or when displaying the data directly in the Data Viewer panel of the ticket sidebar.

In your Data Viewer settings, go to the Template tab and select Adaptive Cards from the dropdown.

Remove the default code from the text area and paste in the following template code:

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "Container",
      "style": "emphasis",
      "items": [
        {
          "type": "TextBlock",
          "size": "ExtraLarge",
          "text": "Shopify Orders",
          "wrap": true
        }
      ]
    },
    {
      "type": "Container",
      "$data": "${response.data.orders.edges}",
      "style": "emphasis",
      "items": [
        {
          "type": "ColumnSet",
          "columns": [
            {
              "type": "Column",
              "width": "stretch",
              "items": [
                {
                  "type": "TextBlock",
                  "text": "{{DATE(${node.createdAt}, SHORT)}}",
                  "wrap": true,
                  "spacing": "none"
                },
                {
                  "type": "TextBlock",
                  "text": "${node.name}",
                  "weight": "bolder",
                  "size": "extraLarge",
                  "spacing": "none",
                  "wrap": true
                },
                {
                  "type": "TextBlock",
                  "$when": "${node.fullyPaid == true}",
                  "text": "Fully paid",
                  "color": "good",
                  "spacing": "none",
                  "wrap": true
                },
                {
                  "type": "TextBlock",
                  "$when": "${node.fullyPaid == false}",
                  "text": "Not paid",
                  "color": "attention",
                  "spacing": "none",
                  "wrap": true
                },
                {
                  "type": "TextBlock",
                  "text": "${node.currencyCode} ${node.totalReceivedSet.presentmentMoney.amount}",
                  "spacing": "none",
                  "wrap": true
                }
              ]
            },
            {
              "type": "Column",
              "width": "auto",
              "horizontalAlignment": "Right",
              "items": [
                {
                  "type": "TextBlock",
                  "text": "${node.customer.firstName} ${node.customer.lastName}",
                  "spacing": "none",
                  "wrap": true,
                  "$when": "${node.customer != null}"
                },
                {
                  "type": "TextBlock",
                  "text": "${node.customer.email}",
                  "spacing": "none",
                  "wrap": true,
                  "$when": "${node.customer != null}"
                },
                {
                  "type": "TextBlock",
                  "text": "Orders count: ${node.customer.ordersCount}",
                  "spacing": "none",
                  "wrap": true,
                  "$when": "${node.customer != null}"
                }
              ]
            }
          ]
        },
        {
          "type": "Container",
          "separator": true,
          "style": "default",
          "$data": "${node.lineItems.edges}",
          "items": [
            {
              "type": "ColumnSet",
              "spacing": "none",
              "columns": [
                {
                  "type": "Column",
                  "width": "stretch",
                  "items": [
                    {
                      "type": "TextBlock",
                      "text": "${node.name}",
                      "wrap": true,
                      "weight": "Bolder"
                    },
                    {
                      "type": "TextBlock",
                      "text": "SKU: ${node.sku}",
                      "wrap": true,
                      "spacing": "none"
                    }
                  ]
                },
                {
                  "type": "Column",
                  "width": "auto",
                  "items": [
                    {
                      "type": "Image",
                      "url": "${node.image.originalSrc}",
                      "altText": "${node.name}",
                      "size": "medium"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Click Save to update your template settings for the integration.

When you go back to the customer's ticket and click the View data button, the associated Shopify data will be formatted using the template settings.

Step 5: Advanced customization

By adapting the query used in the Data Viewer settings, you can customize the most relevant Shopify data you want captured and displayed on tickets.

When querying smaller amounts of data, you can create a simple widget to display directly in the Data Viewer section of the ticket sidebar instead of using the display option to open in a modal.

The following GraphQL query example focuses on the customer rather than the order. Paste this query to the body field of your Data Viewer settings.

{
  "query": "query { customers( first: 1, query:\"email:${ticket.customer.email}\" ) { edges { node { state email firstName lastName image{originalSrc} phone ordersCount averageOrderAmountV2{amount} totalSpentV2{amount} lastOrder{ id currencyCode name createdAt updatedAt fullyPaid confirmed } } } } } "
}

In the Template settings, select Adaptive Cards as the template option and paste the following template code:

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "Container",
      "isVisible": "${count(response.data.customers.edges) > 0}",
      "items": [
        {
          "type": "TextBlock",
          "text": "${response.data.customers.edges[0].node.firstName} ${response.data.customers.edges[0].node.lastName}",
          "wrap": true
        },
        {
          "type": "TextBlock",
          "text": "📧 ${response.data.customers.edges[0].node.email}",
          "isSubtle": true,
          "spacing": "None",
          "size": "Small",
          "wrap": true
        },
        {
          "type": "TextBlock",
          "text": "☎ ${response.data.customers.edges[0].node.phone}",
          "isSubtle": true,
          "spacing": "None",
          "size": "Small",
          "$when": "${$root.data.customers['edges[0]']['node']['phone']}",
          "wrap": true
        },
        {
          "type": "TextBlock",
          "text": "💰 Total Spent: ${response.data.customers.edges[0].node.totalSpentV2.amount} ${response.data.customers.edges[0].node.lastOrder.currencyCode}",
          "isSubtle": true,
          "spacing": "None",
          "size": "Small",
          "wrap": true
        },
        {
          "type": "TextBlock",
          "text": "Last Order: {{DATE(${response.data.customers.edges[0].node.lastOrder.createdAt}, SHORT)}} at {{TIME(${response.data.customers.edges[0].node.lastOrder.createdAt})}} ",
          "size": "Small",
          "wrap": true
        },
        {
          "type": "TextBlock",
          "text": "Last Update: {{DATE(${response.data.customers.edges[0].node.lastOrder.updatedAt}, SHORT)}} at {{TIME(${response.data.customers.edges[0].node.lastOrder.updatedAt})}}",
          "size": "Small",
          "wrap": true,
          "spacing": "None"
        },
        {
          "type": "TextBlock",
          "$when": "${response.data.customers.edges[0].node.lastOrder.fullyPaid == true}",
          "text": "✔ Fully paid",
          "size": "Small",
          "color": "Good",
          "spacing": "None",
          "wrap": true
        },
        {
          "type": "TextBlock",
          "$when": "${response.data.customers.edges[0].node.lastOrder.fullyPaid == false}",
          "text": "✘ Not paid",
          "size": "Small",
          "color": "Attention",
          "spacing": "None",
          "wrap": true
        }
      ]
    },
    {
      "type": "Container",
      "isVisible": "${count(response.data.customers.edges) == 0}",
      "items": [
        {
          "type": "TextBlock",
          "text": "✘ Not a Shopify Customer",
          "color": "Warning",
          "wrap": true
        }
      ]
    }
  ]
}

If the customer exists in Shopify, their latest order information will be presented in the Data Viewer subsection of the ticket options sidebar.

By using isVisible in the adaptive card template, a blank state note will appear on tickets for any Teamwork Desk customers whose email addresses do not match your Shopify customers list.

Additional resources

Microsoft offers an online design tool to help you to build adaptive cards online.
Microsoft adaptive cards overview documentation.
Shopify GraphQL documentation.