App Platform Tutorial

This tutorial introduces many concepts and requires a few hours of learning before you will be equipped to write your own app. Please complete the following tutorials in the order they are written below.

Many tools and technologies used here, such as Go Templating and GraphQL (see the Before you start section) are widely used by many organizations. Take the time to search online for various tools and tutorials that exist if what we have provided leaves you with remaining questions. We intentionally chose widely available tools so that you could leverage publicly available educational materials.  By the end of the tutorial, you will have a fully functional Gladly App that interacts with a fictitious order management system. Even if you are not familiar with GraphQL or Go Templating you will be able to build the app by following this tutorial.

Remember that if you get stuck you can always compare your app with the finished version. It's available in our app-platform-examples Github repo - sample_oms.

Before you start

Install the CLI tool, then read the OMS API documentation. Both instructions are in the sections below.

Useful links

Example apps: https://github.com/gladly/app-platform-appcfg-cli

CLI Documentation https://github.com/gladly/app-platform-appcfg-cli/tree/main/docs

curl -H "apiToken: <any-token>"  
<https://gladly-sample-oms.vercel.app/api/[email protected]>

{
  "id": "YW5kcmV3QGV4YW1wbGUub3Jn",
  "fullName": "Lamont Russel",
  "phones": [
    "+644938853685"
  ],
  "emails": [
    "[email protected]",
    "[email protected]",
    "[email protected]",
    "[email protected]"
  ],
  "ltv": "$142.11"
}

{ "status": "error", "message": "Error: emailAddress is required" }

curl -H "apiToken: <any-token>" 
<https://gladly-sample-oms.vercel.app/api/customers/YW5kcmV3QGV4YW1wbGUub3Jn>

{
  "id": "YW5kcmV3QGV4YW1wbGUub3Jn",
  "fullName": "Lamont Russel",
  "phones": [
    "+644938853685"
  ],
  "emails": [
    "[email protected]",
    "[email protected]",
    "[email protected]",
    "[email protected]"
  ],
  "ltv": "$142.11"
}

curl -H "apiToken: <any-token>" 
<https://gladly-sample-oms.vercel.app/api/orders?customerId=YW5kcmV3QGV4YW1wbGUuY29t>

[
	{
    "id": "1f85eb0a-caa8-42ee-ad10-1dcfd09d01e2",
    "orderNumber": "sGMtsfUf",
    "status": "pending",
    "shippingAddress": "64389 Sienna Village Apt. 296",
    "billingAddress": "",
    "orderDate": "2021-03-18T01:53:56.382Z",
    "customerId": "YW5kcmV3QGV4YW1wbGUuY29t",
    "lineItems": [
      {
        "id": "f9930951-ff95-4e34-8ce4-e7320e01f538",
        "quantity": 2,
        "productId": "ab30f03a-be65-4b97-81f6-8f3157b13fbc",
        "status": "refunded"
      },
      {
        "id": "8e8a31b8-75e0-4edc-8a98-98fd29a6a18a",
        "quantity": 3,
        "productId": "5d2ba910-fd1b-4939-8f57-f71199964e95",
        "status": "refunded"
      },
      {
        "id": "e6f76583-40ca-4284-9baa-518a8a4e52e5",
        "quantity": 4,
        "productId": "38af722b-14be-40f1-a7fd-26b84bb46d15",
        "status": "pending"
      }
    ],
    "shippingSpeed": "expedited",
    "totalPrice": "697.00",
    "shippingAndHandling": "816.00"
  },
  ...
}

{ "status": "error", "message": "Error: customerId or emailAddress is required" }

curl -H "apiToken: <any-token>" 
<https://gladly-sample-oms.vercel.app/api/[email protected]>

[
	{
    "id": "1f85eb0a-caa8-42ee-ad10-1dcfd09d01e2",
    "orderNumber": "sGMtsfUf",
    "status": "pending",
    "shippingAddress": "64389 Sienna Village Apt. 296",
    "billingAddress": "",
    "orderDate": "2021-03-18T01:53:56.382Z",
    "customerId": "YW5kcmV3QGV4YW1wbGUuY29t",
    "lineItems": [
      {
        "id": "f9930951-ff95-4e34-8ce4-e7320e01f538",
        "quantity": 2,
        "productId": "ab30f03a-be65-4b97-81f6-8f3157b13fbc",
        "status": "refunded"
      },
      {
        "id": "8e8a31b8-75e0-4edc-8a98-98fd29a6a18a",
        "quantity": 3,
        "productId": "5d2ba910-fd1b-4939-8f57-f71199964e95",
        "status": "refunded"
      },
      {
        "id": "e6f76583-40ca-4284-9baa-518a8a4e52e5",
        "quantity": 4,
        "productId": "38af722b-14be-40f1-a7fd-26b84bb46d15",
        "status": "pending"
      }
    ],
    "shippingSpeed": "expedited",
    "totalPrice": "697.00",
    "shippingAndHandling": "816.00"
  },
  ...
}

{ "status": "error", "message": "Error: customerId or emailAddress is required" }

curl -H "apiToken: <any-token>" 
<https://gladly-sample-oms.vercel.app/api/orders/ae3b06a1-39aa-4351-84cd-1eae728643f9>

{
  "id": "ae3b06a1-39aa-4351-84cd-1eae728643f9",
  "orderNumber": "BZcIoDCi",
  "status": "refunded",
  "shippingAddress": "503 S 4th Street Apt. 808",
  "billingAddress": "825 Henry Street Suite 284",
  "orderDate": "2019-09-02T00:53:56.135Z",
  "customerId": "5fe529f1-271d-4ced-bab8-ec28c19c0fb6",
  "lineItems": [
    {
      "id": "1fe7c456-aebb-46e0-b300-5dd675c3de3b",
      "quantity": 2,
      "productId": "5ccf268a-5718-441d-b642-2b67ea070552",
      "status": "refunded"
    }
  ],
  "shippingSpeed": "regular",
  "totalPrice": "237.00",
  "shippingAndHandling": "698.00"
}

curl -H "apiToken: <any-token>" 
<https://gladly-sample-oms.vercel.app/api/products/6422b67e-a070-4552-ae7a-600fb22d8242>

{
  "id": "6422b67e-a070-4552-ae7a-600fb22d8242",
  "name": "Rustic Plastic Pants",
  "productType": "Fantastic",
  "sku": "caAGQJxaHxOE"
}

curl -X POST -H "apiToken: <any-token>" 
<https://gladly-sample-oms.vercel.app/api/orders/13413109987/cancel> -d '{ "cancellationReason": "garbage" }'

{ "status": "success" }

{ "status": "error", "message": "cancellationReason is required" }

{ "status": "error", "message": "Error: can not cancel an order in state [the state of the order]" }

curl -i -X POST -H "apiToken: anythingyouwanthere"  
<https://gladly-sample-oms.vercel.app/api/orders/13413109918/refund> -d '{ "refundReason": "mispriced" }'

{ "status": "success"}

{ "status": "error", "message": "refund is required" }

{ "status": "error", "message": "Error: can not refund an order in state [the state of the order]" }

curl -i -X POST -H "apiToken: <any-token>"  
<https://gladly-sample-oms.vercel.app/api/return> -d '{ "orderId": "122340991j810", "lineItemIds": [ "5b8fccb7-b23f-490a-8f80-99ffc92ca64a"] }'

{ "status": "success"}

{"status":"error","message":"Error: missing orderId or lineItemIds"}

{"status":"error","message":"Error: line item does not exist asdf"}

{"status":"error","message":"Error: can not return an item with status undefined"}

Sample Apps

For your convenience, we have created a repository of some sample apps: https://github.com/gladly/app-platform-examples. In particular, sample_oms connect to the Sample OMS API referenced above. In this tutorial, we will be replicating its functionality. Clone the example repo:

git clone [email protected]:gladly/app-platform-examples.git

Summary

A pre-requisite for this tutorial is that you have read through the documentation of our sample OMS noted above. Please familiarize yourself with the Sample OMS APIs before continuing. We will be using this as our third-party system.

appcfg aims to help you create the files/folders needed for a Gladly App Platform App. Files will be created as placeholders that you can fill in manually. This process will require running some commands, manually updating files, performing validation and tests, and then running your app. Once the app is written, it must be installed in Gladly, configured, and activated. Writing an app without this tool is possible, but we built it to make the process easier for you.

When you build an app on Gladly’s App Platform, know that you are responsible for the data returned, actions taken by the app, maintenance, and testing. We are simply providing you with the ability to integrate with external systems. Given that, we recommend you pull as little data as necessary and enable as few actions as necessary. Because apps must be backward compatible, adding rather than taking away is much easier. Start small and build up from there.

This tutorial is meant to introduce you to basic App Platform concepts you can use when building your own app — it is not a comprehensive tutorial.

The top-level folders and files in your app folder will resemble the following image. The sample_oms  app we are referencing already contains all of these files. Please refer there if you get lost. We will go through the motions of adding all of this relevant configuration yourself in the tutorial below:

We will build a sample app against our example OMS Server, which will walk you through creating your own app. Please reference our documentation for detailed information on any aspect of Gladly App Configuration.

Getting Started

1. Before we begin configuring our own app, let’s quickly run a few appcfg commands and validate the existing example app provided to you in the Sample OMS.

2. Run the following commands from the sample_oms folder to validate the existing actions and data. This app should pass validation. If everything looks good, proceed to the next step. Otherwise, fix any existing errors or reach out to your CSM. This step tells us that the app we are replicating passes validation. If the app we build later does not pass validation, we should compare it against the example.

   • Export variable to point to app root: export GLADLY_APP_CFG_ROOT=app

   • Validate actions: appcfg validate actions

   • Validate data: appcfg validate data Tip – At any point in the development cycle, feel free to Run appcfg validate to check your work and expose any issues.

3. Initialize your App.  

   • If you haven't already initialized your app in step Install External App CLI Setup # do so now. From the root directory of your app run: appcfg init -n <app_name> -a <org_name> -d <description> e.g.,

     appcfg init --app-name tutorial --author ela.com --description "My first Gladly app" Running the command will return GLADLY_APP_CFG_ROOT value which you'll use in the next step.

   • Export the root variable:  export GLADLY_APP_CFG_ROOT=<value returned by previous command> e.g., export GLADLY_APP_CFG_ROOT=/Users/ela/gladly/projects/tutorial Note – Since we set the root app folder name, this will be the root of any work you do using the configuration tool unless you change the root app folder name.

4. Before continuing to configure our sample app, we want to identify data pull and action names and set them aside. In our example, we will start with our three data pulls customers, orders, and products , then move on to our three actions: cancel_order, return_order, and refund_line_items. We will start by pulling customer id by email address.

5. As you build your app, please refer to the example JSON in our test folders to understand the data's shape. This is meant to aid your discovery as you familiarize yourself with the app we will build on the App Platform.

AUTHENTICATION

Our sample OMS app does not need any action-specific or data pull-specific headers. They will all inherit our app-level auth headers. Fill out the following auth to run our app against the external system. In this example, we are configuring auth before data pulls/actions, but feel free to start the data pulls or actions first if that's how you prefer to think about things.

Adding Auth Header

Determine Auth Header name. In our case, we need to provide an apiToken key value pair. The command we will use is: appcfg add auth-header {header name} [flags]

• Run the command: appcfg add auth-header apiToken

• apiToken.gtpl contains <{{.integration.secrets.apiToken}}

• authentication/headers/_test_/data folder contains two files:

  • expected_apiToken.txt contains secret_token

  • integration.json contains:

{
  "configuration": {
  },
  "secrets": {
    "apiToken": "secret_token"
  }
}

Test the auth header by running appcfg test auth-header.

If no error is returned, the tests have passed.

DATA PULLS

1. Review the Sample OMS Server API docs again (in the Before you start section) to confirm you understand the relationships between our three data pulls. Take your time to digest the structure of the external APIs. You’ll notice that customer does not have any dependent data, orders are dependent on the customer, and products are dependent on the order. This tutorial is meant to walk you through each data pull one by one. You will run through this tutorial three times, once for each data pull.

2. Run the add data-pull command for our three desired data pulls (customer, orders, products). Customer is highlighted in pink, Orders is highlighted in orange, and Products is highlighted in yellow. Start with the Customer data pull, going through all the steps highlighted in pink. When you finalize that data pull at the end of this tutorial, return and run through the tutorial again for Orders and then a third time for Products. We recommend this iterative process to help you identify and fix errors by building data pulls on top of one another rather than simultaneously. But it is ultimately up to you to decide how you like to build apps going forward. Find an approach that works for you. Some steps are the same for all three data pulls and contain no highlight.

3. You can create multiple requests by outputting multiple bodies via the request body. This approach should be used when external data is requested via a POST. The start of each body is specified in the template by adding a “#body” marker on the line that immediately precedes the start of the body content. The marker can appear anywhere on the line making it possible to place it just above the actual body content for clarity. For simplicity, it is not necessary to add a “#body” marker to templates that only generate one body. For requests where only the request body changes, the request url template can simply generate one URL to be used with each request body. This will be the most common case for a POST. It is, however, possible to have a unique URL for each request body by generating as many URLs as there are request bodies. For example:

{{ range .customer.emailAddresses }}
        #body
        {
            “emailAddress”: “{{.}}”
        }
        {{ end }}

Add Data Pulls

appcfg add data-pull <data-pull-name> -m <http-method> -t <data-type> -v <semantic-version> -d <dependent_data> (example command).

• CUSTOMER: appcfg add data-pull customer -m GET -t sample_oms_customer -v 1.0

• ORDERS: appcfg add data-pull orders -m GET -t sample_oms_order -v 1.0 -d sample_oms_customer

• PRODUCTS: appcfg add data-pull products -m GET -t sample_oms_product -v 1.0 -d sample_oms_order

1. Navigate to your root folder and confirm the appropriate folders and files have been created for your data pull above. See the list below. If all looks good, continue to the next step.

   • request_url.gtpl

   • config.json

   • external_id.gtpl

   • external_parent_id.gtpl

   • external_updated_at.gtpl

   • response_transformation.gtpl

   • data_schema.graphql (one file for all three data pulls will be filled in later)

2. Again, we do not run the add data-pull-header command for each data pull because we have no headers specific to a data pull. Our auth headers are generic and can be applied to all data pulls. We created an auth header that will apply to all of our apps’ REST calls in an earlier step.

Configuring the Data Pulls

1. Let’s fill out the various configuration files in our new data pulls. As you know from earlier steps, each data pull has its own folder within data/pull. We will be referencing template data here.

2. Each data pull also has a _test_/data folder comprised of dataset folders. The customer and correlationId files come pre-loaded with sample data. These data set folders also contain our expected value files that we will fill out. This configuration tool allows us to use static data so that the outcome of our tests is deterministic. Normally, Gladly will provide customer data dynamically to the App Platform API requests.

3. Note that the urlquery go template function is available to you to escape url queries to be url-safe (for more information on Go Template Functions, run appcfg platform template-functions)We start at the root of the template data with a . , and then we select the primaryEmailAddress from the customer object.

4. We recommend validating and testing incrementally as each component of a data pull is created. For example, you would start by adding the request url below and then running validate command to ensure it passes validation. After that, you should set up the test file for request_url and then run the test. After you’ve tested your request url, move on to adding the external id and so on.

https://gladly-sample-oms.vercel.app/api/customers?emailAddress={{urlquery .customer.primaryEmailAddress}}

https://gladly-sample-oms.vercel.app/api/customers?emailAddress={{urlquery .customer.primaryEmailAddress}}

https://gladly-sample-oms.vercel.app/api/customers?emailAddress={{urlquery .customer.primaryEmailAddress

https://gladly-sample-oms.vercel.app/api/customers?emailAddress=primary%40email.com

{
  "emails": [
    "[email protected]",
    "[email protected]",
    "[email protected]"
  ],
  "fullName": "Eldon Beatty Sr.",
  "id": "cHJpbWFyeUBlbWFpbC5jb20=","ltv": "$85.14",
  "phones": [
    "+84251648562"
  ]
}

1aaa9504-e616-418f-b018-c72054574a60 
bf676a4a-8d6c-4cb7-a994-3e516c691fd3

cHJpbWFyeUBlbWFpbC5jb20= 
cHJpbWFyeUBlbWFpbC5jb20=

https://gladly-sample-oms.vercel.app/api/customers?emailAddress={{urlquery .customer.primaryEmailAddress}}

https://gladly-sample-oms.vercel.app/api/orders?customerId=oms-customer-1

[
  {
    "billingAddress": "13986 Elm Street Apt. 174",
    "customerId": "cHJpbWFyeUBlbWFpbC5jb20=","id": "1aaa9504-e616-418f-b018-c72054574a60",
    "lineItems": [
      {
        "id": "ce6fd4f0-6ffa-4da7-aadb-520601e41098",
        "productId": "38eb4d2a-f5c2-4048-a45a-a654ea42ec32",
        "quantity": 2,
        "status": "canceled"
      },
      {
        "id": "b08186b9-40b3-4754-92d4-d78121122fe8",
        "productId": "04bc3623-1212-4c3e-af1a-20f79c53a88a",
        "quantity": 3,
        "status": "delivered"
      }
    ],
    "orderDate": "2024-01-16T15:32:39.826Z",
    "orderNumber": "kqZzUCha",
    "shippingAddress": "181 Torp Square Apt. 861",
    "shippingAndHandling": "397.00",
    "shippingSpeed": "expedited",
    "status": "canceled",
    "totalPrice": "320.00"
  },
  {
    "billingAddress": "",
    "customerId": "cHJpbWFyeUBlbWFpbC5jb20=","id": "bf676a4a-8d6c-4cb7-a994-3e516c691fd3",
    "lineItems": [
      {
        "id": "c4ae0937-bb9a-48bb-ac85-d1a58a5ca82b",
        "productId": "e7583d9b-30ef-4f5a-a131-a1b3a102d8be",
        "quantity": 4,
        "status": "delivered"
      },
      {
        "id": "d63b1a24-c7c1-427c-bce9-f780a0c6e543",
        "productId": "fb1e57e1-3816-4fb1-acfb-763edd83ab44",
        "quantity": 2,
        "status": "canceled"
      },
      {
        "id": "e0a13a9f-fbce-4345-acd8-d1ada69825dc",
        "productId": "2c8f223c-8bd7-448f-b4c8-b475c3ae87da",
        "quantity": 4,
        "status": "pending"
      }
    ],
    "orderDate": "2020-04-13T01:55:17.525Z",
    "orderNumber": "FsVOhVCg",
    "shippingAddress": "3897 Medhurst Parkways Suite 440",
    "shippingAndHandling": "158.00",
    "shippingSpeed": "regular",
    "status": "pending",
    "totalPrice": "249.00"
  }
]

{
  "sample_oms_customer": [
    {
      "id": "oms-customer-1"
    }
  ]
}

{{- range .externalData.sample_oms_order}}

{{- range .lineItems -}}
https://gladly-sample-oms.vercel.app/api/products/{{.productId}}
{{end}}

{{- end}}

https://gladly-sample-oms.vercel.app/api/products/38eb4d2a-f5c2-4048-a45a-a654ea42ec32
https://gladly-sample-oms.vercel.app/api/products/04bc3623-1212-4c3e-af1a-20f79c53a88a
https://gladly-sample-oms.vercel.app/api/products/e7583d9b-30ef-4f5a-a131-a1b3a102d8be
https://gladly-sample-oms.vercel.app/api/products/fb1e57e1-3816-4fb1-acfb-763edd83ab44
https://gladly-sample-oms.vercel.app/api/products/2c8f223c-8bd7-448f-b4c8-b475c3ae87da

{
  "sample_oms_order": [
    {
      "billingAddress": "13986 Elm Street Apt. 174",
      "customerId": "cHJpbWFyeUBlbWFpbC5jb20=","id": "1aaa9504-e616-418f-b018-c72054574a60",
      "lineItems": [
        {
          "id": "ce6fd4f0-6ffa-4da7-aadb-520601e41098",
          "productId": "38eb4d2a-f5c2-4048-a45a-a654ea42ec32",
          "quantity": 2,
          "status": "canceled"
        },
        {
          "id": "b08186b9-40b3-4754-92d4-d78121122fe8",
          "productId": "04bc3623-1212-4c3e-af1a-20f79c53a88a",
          "quantity": 3,
          "status": "delivered"
        }
      ],
      "orderDate": "2024-01-16T15:32:39.826Z",
      "orderNumber": "kqZzUCha",
      "shippingAddress": "181 Torp Square Apt. 861",
      "shippingAndHandling": "397.00",
      "shippingSpeed": "expedited",
      "status": "canceled",
      "totalPrice": "320.00"
    },
    {
      "billingAddress": "",
      "customerId": "cHJpbWFyeUBlbWFpbC5jb20=","id": "bf676a4a-8d6c-4cb7-a994-3e516c691fd3",
      "lineItems": [
        {
          "id": "c4ae0937-bb9a-48bb-ac85-d1a58a5ca82b",
          "productId": "e7583d9b-30ef-4f5a-a131-a1b3a102d8be",
          "quantity": 4,
          "status": "delivered"
        },
        {
          "id": "d63b1a24-c7c1-427c-bce9-f780a0c6e543",
          "productId": "fb1e57e1-3816-4fb1-acfb-763edd83ab44",
          "quantity": 2,
          "status": "canceled"
        },
        {
          "id": "e0a13a9f-fbce-4345-acd8-d1ada69825dc",
          "productId": "2c8f223c-8bd7-448f-b4c8-b475c3ae87da",
          "quantity": 4,
          "status": "pending"
        }
      ],
      "orderDate": "2020-04-13T01:55:17.525Z",
      "orderNumber": "FsVOhVCg",
      "shippingAddress": "3897 Medhurst Parkways Suite 440",
      "shippingAndHandling": "158.00",
      "shippingSpeed": "regular",
      "status": "pending",
      "totalPrice": "249.00"
    }
  ]
}

{
  "id": "04bc3623-1212-4c3e-af1a-20f79c53a88a",
  "name": "Small Metal Keyboard",
  "productType": "Handmade",
  "sku": "ADVJwwsrJCYX"
}

Next, let's clean up our data pull and data set by deleting unnecessary files that are not relevant. For example, we do not need to request payloads for our GET data pulls or any transformations. We will delete such files as response_transformation.gtpl and external_updated_at.gtpl.

Validate Data Pulls

Before moving on to GraphQL schemas, let's validate and test our data pulls. In the prior step, you tested specific data pull tests:

1. Run appcfg validate data

2. You’ll notice that empty files will appear in the validator. Please delete any empty files that are still noted in the validator.

3. If the validator has any other issues, please fix them before testing our app.

Test Data Pulls

If the configuration you’ve written passes validation, it’s time to run our tests against the sample payloads again and confirm that everything works.

• We have already set up our test expectations and tested data sets individually. Confirm all expectations are correctly noted in the expected_... files.

• Run the following commands to test each data pull. Adding additional tests in data-set folders within {data pull name}/_test_/data is possible if you want to add additional test cases. Use the flag -d to name the specific test folder you want to use. In our case, because we only have one test data set called success, we will set the -d flag.

  • appcfg test data-pull customer -d success

  • appcfg test data-pull orders -d success

  • appcfg test data-pull products -d success

After running the tests above, compare the actual output with the expected output. If there is a failure, you will see an error in the console. If there are any errors while running the test, read and resolve them before re-running the test.

As an example, the expected test output for appcfg test data-pull customer -t url should look something like the following in your terminal.

data/pull/customer/request_url.gtpl
-----------------------------------
https://gladly-sample-oms.vercel.app/api/customers?emailAddress=primary%40email.com

Once tests are passing, we will run our data pulls against the external system.

Run Data Pulls

appcfg run data-pull -s '{"apiToken": "token"}'

GraphQL Schema

It is time to think about the data transformations and our data schema. While we will not be doing any data transformations because the raw data returned by our sample OMS is returned exactly in the format we want; we will be modeling data in GraphQL in the way that makes the most sense for our business. We want two GraphQL query entry points, one for customer and one for orders. Using an online transformation tool to convert your raw JSON response to GraphQL is a nice place to start. From there, you can tweak and modify. You can also write your GraphQL schema by hand.

Add the following GraphQL Schema to data_schema.graphql:

• Note that we use GraphQL directives to reference the data pull the GraphQL datatype relates to. Each transformation needs to correspond to a data definition in GraphQL.

type Product @dataType(name: "sample_oms_product", version: "1.0") {
  id: ID
  name: String
  productType: String
  sku: String
}

type LineItem {
  id: String
  quantity: Int
  product: Product @childIds(template: "{{.productId}}") (we return product object rather than product ID here)
  status: String
}

type Order @dataType(name: "sample_oms_order", version: "1.0") {
  id: ID
  orderNumber: String
  status: String
  shippingAddress: String
  billingAddress: String
  orderDate: DateTime
  customerId: String
  shippingSpeed: String
  totalPrice: Currency
  shippingAndHandling: Currency
  lineItems: [LineItem]
}

type Customer @dataType(name: "sample_oms_customer", version: "1.0") {
    id: ID
    emails: [String]
    fullName: String
    ltv: Currency
    numberOfOrders: Int
    phones: [String]
    state: String
    orders: Order @parentId(template: "{{.id}}")
}

type Query {
    customer: Customer
    orders: [Order]
}

Note on GraphQL Types that we support:

1. All the GraphQL types from the spec (Int, String, etc)

2. Datetime

3. Currency

4. Object Type Definitions

5. Enum

6. Input Type

Note on GraphQL Query Entry Points:

We have chosen only to expose two GraphQL Query entry points here (customer and orders) even though many data objects are relevant to users in Gladly. GraphQL is so efficient and flexible that clients can request only the data they need in a query. This helps to avoid issues with both underfetching data and overfetching data. In our case, because all of our data is hierarchical under Customers, users can request whatever nested fields they need using our Customer or Orders Queries, and there is no need for any additional explicit queries, such as lineItems or product.

Note on GraphQL Directives:

We utilize only the built-in GraphQL directives(@deprecated, @include, and @skip) plus three additional directives below (@dataType, @childIds, @parentId).

STANDARD

GraphQL provides several built-in directives that are commonly used in GraphQL schemas. These directives include:

These directives allow us to control the shape and content of GraphQL responses based on runtime conditions and deprecation status.

ADD-ON

We have added three additional directives for you to use:

• @dataType: We use the @dataType directive to associate a GraphQL type with a given data type from a data pull in Gladly. For example, below, you will see the GraphQL type GladlyCustomer is associated with the gladly_customer data pull version "1.0"

type GladlyCustomer @dataType(name: "gladly_customer", version: "1.0") {
...
}

• @childIds: This directive specifies how child entities are identified within a parent entity. It typically takes a template as an argument, which is used to construct the unique identifiers of child entities based on the parent entity’s data. For example, @childIds(template: "{{.productId}}") might indicate that each child entity’s ID is derived from the productId field of the parent entity.

• @parentId: This directive identifies the parent entity associated with a child entity. It often takes a template argument as well, which is used to construct the unique identifier of the parent entity based on the child entity’s data. For instance, @parentId(template: "{{.id}}") could indicate that the parent entity’s ID is derived from the id field of the child entity.

These directives help establish hierarchical relationships between different data types in GraphQL schemas, allowing for structured and efficient data retrieval.

Validate and Run GraphQL

1. Once your GraphQL data schema has been written, it is time to validate and test it.

2. Start by running the vּalidate command.

3. If your data schema passes validation, please run each GraphQL entry point using the following command.

appcfg run data-graphql -d success -q customer -s '{"apiToken": "token"}'

appcfg run data-graphql -d success -q orders -s '{"apiToken": "token"}'

ACTIONS

In our example, we will define three actions: cancel_order, refund_order, and return_line_items in our Sample OMS Server. This will be similar to our data pull tutorial, but we will work on actions in the external system rather than data pulls. You will be reusing many concepts from the data pull section above.

1. Run the add action command for each of our actions. Each of them is a POST with application/json content.

   • appcfg add action cancel_order -m POST -c application/json

   • appcfg add action refund_order -m POST -c application/json

   • appcfg add action return_line_items -m POST -c application/json

Now that the action folders and files have been created, let’s go in and add data and test data. Be sure to validate and test your actions as you incrementally add each component below:

app/actions/cancel_order

• request_url is https://gladly-sample-oms.vercel.app/api/orders/{{urlquery .inputs.orderId}}/cancel

• expected_request_url.txt contains https://gladly-sample-oms.vercel.app/api/orders/order1/cancel

• request_body:

{
  "cancellationReason": "{{.inputs.reason}}"
}

• expected_request_body.txt contains {"cancellationReason": "broken"}

• rawData.json contains {"status": "success"}

• inputs.json:

{
    "orderId": "order1",
    "reason": "broken"
}

app/actions/refund_order

• request_url is https://gladly-sample-oms.vercel.app/api/orders/{{urlquery .inputs.orderId}}/refund

• expected_request_url.txt contains https://gladly-sample-oms.vercel.app/api/orders/order1/cancel

• request_body:

{ 
  "refundReason": "{{.inputs.reason}}" 
}

• expected_request_body.txt contains {"refundReason": "broken"}

• rawData.json contains {"status": "success"}

• inputs.json:

{
    "orderId": "customer1",
    "reason": "broken"
}

app/actions/return_line_items

• request_url is https://gladly-sample-oms.vercel.app/api/return

• expected_request_url.txt contains https://gladly-sample-oms.vercel.app/api/return

• request_body:

{
  "orderId": "{{.inputs.orderId}}",
  "lineItemIds": {{toJson .inputs.lineItemIds}}
}

• expected_request_body.txt contains:

{
    "orderId": "order1",
    "lineItemIds": ["lineItemA", "lineItemB"]
}

• rawData.json contains {"status": "success"}

• inputs.json:

{
    "orderId": "order1",
    "lineItemIds": ["lineItemA", "lineItemB"]
}

GraphQL Schema

It is time to fill out the GraphQL schema for our actions.

app/actions/actions_schema.graphql:

type Result {
    status: String!
    message: String
}

type Mutation {
    cancelOrder(orderId: String!, reason: String!): Result @action(name: "cancel_order")
    refundOrder(orderId: String!, reason: String!): Result @action(name: "refund_order")
    returnLineItems(orderId: String!, lineItemIds: [String!]!): Result @action(name: "return_line_items")
}

• Delete unnecessary files that are not relevant.

Before we move on to running against the external app, validate and test our actions again.

1. Run appcfg validate actions

2. You’ll notice that empty files will appear in the validator. Delete any empty files that are still noted in the validator.

3. If the validator has any other issues, please fix them before testing our app.

If the configuration you’ve written passes validation, it’s time to run our tests against the sample payloads and see if our actions work.

Use the flag -d to name the specific test folder you want to use. Because we only have one test dataset, we will use the -d success flag to select it.

1. Run appcfg test action cancel_order -d success

2. Run appcfg test action refund_order -d success

3. Run appcfg test action return_line_items -d success

After running the tests above, compare the actual output with the expected output. If there are any errors while running the test, read and resolve them before re-running the test. The expected test output for appcfg test action cancel_order -d success should look something like the following in your terminal:

==========================
Test action "cancel_order"
==========================

actions/cancel_order/request_url.gtpl
-------------------------------------
https://gladly-sample-oms.vercel.app/api/orders/order1/cancel

actions/cancel_order/request_body.gtpl
--------------------------------------
{
  "cancellationReason": "broken"
}

actions/cancel_order/response_transformation.gtpl
-------------------------------------------------

Once tests are passed, we will run our actions against the external system.

appcfg run action -s ‘{“apiToken”: “token”}’

Then run our GraphQL mutations against the external system.

appcfg run action-graphql -d success -m cancelOrder -s ‘{“apiToken”: “token”}’ -i ‘{“orderId”: “stuff”, “reason”: “stuff”}’

appcfg run action-graphql -d success -m refundOrder -s ‘{“apiToken”: “token”}’ -i ‘{“orderId”: “stuff”, “reason”: “stuff”}’

appcfg run action-graphql -d success -m returnLineItems -s ‘{“apiToken”: “token”}’ -i ‘{“orderId”: “stuff”, “lineItemIds”: “stuff”}’

Final Steps

1. Validate all or a subset of your configuration again (actions or data) or both.

   • Run appcfg validate actions

   • Run appcfg validate data

2. Generate markdown documentation for your new app.

   • Run appcfg docs -d <root directory for the documentation tree>

3. Create the app zip file containing all of the configurations you created above.

   • Decide the path of the app file you'd like to create.

   • Run appcfg build -f <path of app file>

Install and Configure Your App

Install, configure, and activate your new app in Gladly. You can install this sample app in Gladly or stop here and begin configuring your own app, then install it in Gladly. For now, PS will walk you through the installation process while we work on building out an admin experience.

1. At this time, PS has to install, configure, and activate on your behalf.

   1. You’ll need to provide them with a zip file containing your app.

   2. Any secrets/configuration.

      1. Name of the integration.

      2. Any username, public, or private keys.

      3. Any custom configurations. If your app needs any environment-specific settings in the integration.json, they would need to provide those to PS now.

2. Now an instance of your app has been associated with the required configuration (such as API token stored on the integration), and is officially ready for use in Gladly Hero and Sidekick.