App Platform Overview

This is a guide for developing apps to integrate external systems with Gladly using the App Platform.

Continue using Lookup Adaptor for Glady Hero integrations

Currently, to enable Agents to access and engage with data in Gladly Hero, you must create a Lookup Adaptor instead of building integrations using the App Platform. Leveraging this data within Gladly Sidekick is relatively simple. However, this process might necessitate specific adjustments to ensure data compatibility and effectiveness. For instance, all date formats must adhere strictly to the ISO8601 standard.

What is an App?

In Gladly, an App provides a mechanism for tightly integrating outside systems into the Gladly platform. While these capabilities will grow over time, Apps allow you to extend Gladly Sidekick by performing Actions in and retrieving custom data from external systems. Tools like the appcfg tool can help you develop, test, and build Gladly App Platform applications.

By giving Sidekick access to data and Actions in the systems you use to run your business, Gladly can assist your Customers in serving themselves in common service workflows.

For example, an order management system may have APIs for retrieving, updating, and canceling orders. An App would include the configuration for retrieving orders for a specific Gladly Customer, enabling Gladly Sidekick to update and cancel those orders without requiring assistance from an Agent.

The configuration for Actions and Data Pulls is described in detail in the docs below.

• App Actions

• App Data Pulls

Use the appcfg tool to guide development

The appcfg tool is not just a command line tool to build Apps by rote! A central concept of the tool is discoverability — the idea that a developer can use the tool to help them learn and discover what is possible within the App Platform. The appcfg tool has a powerful autocomplete feature, which can help by suggesting available commands and dynamically constructing commands for your App, as well as a --help flag which can be appended to any command to provide a detailed explanation.

A Simple Example

Here’s a simple example of a minimal App that exposes a custom “Cancel Order” Action in Gladly Sidekick.

• Tip – Use the appcfg tool to create the request URL, headers, and/or body go templates.

Create an App

A minimal App is simply a folder with a manifest.json file in it.

// ./your_app/manifest.json
{
  author: "yourcompany.com",
  appName: "Your App",
  version: "1.0.0",
  description: "Example cancel order app"
}

Connect to Your API

To expose a “Cancel Order” Action, the App must be configured to connect to your existing RESTful APIs. To accomplish this, add a sub-folder to the actions/ folder within your App with three files inside:

1. [action_name]/config.json

2. [action_name]/request_url.gtpl

3. actions_schema.graphql

# ./your_app/actions/actions_schema.graphql
type Response {
    """
    Whether or not the action succeeded
    """
    success: Boolean!
}

type Mutation {
    """
    Cancel an order using the order id
    """
    cancelOrder(orderId: String!): Response @action(name: "cancel_order")
}

// ./your_app/actions/cancel_order/config.json
{
    httpMethod: "POST"
}

{{/* ./your_app/actions/cancel_order/request_url.gtpl */}}
https://yourcompany.com/api/cancel_order?id={{.inputs.orderId | urlquery}}

Install Your App

Use the appcfg tool to install the App in your Gladly instance.

Configure Sidekick

Once your App is installed in Gladly, it will expose a new Action you may use in Gladly Sidekick.

Now Sidekick can Reply

Sidekick will start to cancel orders in your system when a Thread runs.

Technical Constraints

Because this is an early release of Gladly’s App platform, some important technical constraints exist:

• JSON and XML responses are supported.

  • The response must have the Content-Type: application/json HTTP header.

• Only header-based authentication is supported.

  • This includes Basic Authentication, a Bearer Token, or any static API Key token.

  • Request signing is supported.

• The following OAuth types are supported:

  • Authorization Code

  • Client Credentials

  • Password Grant

Please inform your CSM if these requirements are too constraining.

Background References

Apps leverage some foundational technologies, so it’s useful to have some familiarity with them before further reading.

Go Templates

Apps use the go template language to dynamically generate URLs, headers, bodies, and http requests.

A sample go template for retrieving Customer order data by email address

https://externalsystem.com/orders?customerEmailAddress=
{{.customer.primaryEmailAddress}}

In this template, the relevant Customer Profile data is provided to the template via the .customer attribute, and the primary email address is accessed using the {{.customer.primaryEmailAddress}} go template syntax. This will be explained in greater detail in a subsequent section of this document.

Go template references

• Learn go template syntax (Hashicorp)

• Golang text template developer guide

• Sprig template library documentation - the functionality of the Sprig library is provided to use within all go templates in the app.

GraphQL

Apps use GraphQL schemas to describe the type signatures of requests and responses. Gladly uses these types of signatures to determine how to display Actions and data within the product user interface.

Sample GraphQL type definition for a simple order

type Order {
    orderId: String
    orderDate: DateTime
}

GraphQL references

• Introduction to GraphQL

Semantic versioning

Gladly Apps make use of semantic versioning. Providing versions for key portions of your configuration is how you let Gladly know the current state of your application and when your app evolves. The goal is to always make backward-compatible changes to your app whenever possible so that everything keeps working in Gladly as your app evolves.

Semantic Versioning References

• https://semver.org/

App File Structure

An App is, at minimum, a gzipped folder containing a manifest.json file. It can also include three additional, optional, top-level resource folders:

• An actions/ folder - contains configuration for the Actions the App can run.

• A data/ folder - contains configuration for the data pulls the App can perform.

• An authentication/ folder - contains information about how to authenticate all the HTTP requests an app makes.

Sample top-level app directory structure

./your_app/
  manifest.json
  actions/
  authentication/
  data/

manifest.json

The manifest.json file contains metadata about the entire application.

An application is uniquely identified by its author, appName, and version.

{
	"author": "gladly.com",
	"appName": "loop_returns",
	"version": "1.0.0",
	"description": "Retrieve and manipulate loop returns"
}

Authentication

External systems tend to use one authentication scheme for all REST calls, so Apps share authentication configuration across both Actions and data pulls.

The authentication/ folder contains configuration for the various authentication schemes that Gladly supports when making REST calls to external systems.

Currently, the only supported authentication scheme is header-based authentication. This is configured within the authentication/headers/ folder. In this folder, template files are named after the header’s name, with the file’s content being the value; i.e. [header-name].gtpl.

Sample file for performing BASIC authentication

Basic {{b64enc (printf "%s:%s" .integration.secrets.credentials.
username .integration.secrets.credentials.password)}}

Authentication headers have access to the following template data.

{
	"integration": {
		"configuration": {},
		"secrets": {},
	}
}

Actions & Data Pulls

Both the configuration for retrieving data and taking Actions in an external system follow a similar pattern.

• The outbound HTTP request method and content type are specified in a config.json file.

• Other components of the outbound HTTP requests (including the URL, headers, and bodies) are defined with go templates.

• The data schema for the request and response is specified in a GraphQL schema.

• A go template may be defined to transform the response data if needed.

The configuration files for Actions and data pulls are stored in the actions/ and data/ folders, respectively.

Installation & Administration

Manage your installed Apps and install new apps with the appcfg tool.

• The appcfg apps subcommand is used for managing Apps within Gladly.

• Use appcfg apps install to install your App in your Gladly environment, and appcfg apps create-config to create a configuration including credentials necessary to interact with an external system.

• See your installed Apps with appcfg apps list, or get more information with appcfg apps info

More Information

For more information, continue reading our additional documentation, or try building our tutorial application!