Getting Started

This guide will help you complete your first App, giving you a practical feel for integrating an external system. You'll see how the App Platform uses a configuration-driven approach and the appcfg tool to define and manage your integration with minimal custom code.

Limitations

• JSON and XML responses are supported.

  • The response must have the Content-Type: application/json or Content-Type: application/graphql 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.

Before you start

To develop App Platform apps you will need the latest appcfg tool. Head to Install appcfg for up-to-date instructions.

A Simple Example

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

Initialize the project

ONE TIME ONLY. Create a dedicated directory to store your Gladly projects:

mkdir -p ~/gladly/projects
cd ~/gladly/projects

Create an App

Use appcfg to initialize the project by following the instructions in Develop an App

Tip

appcfg has expansive range of commands to help you with development. Explore the documentation by running appcfg —-help

Let’s inspect the files. 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"
}

Create an Action

To expose a “Cancel Order” Action, the App must be configured to connect to your existing 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}}

Tip

You could have used appcfg add action cancel to generate the action code!

Installation & Administration

Install your app 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 config create 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

Configure Sidekick

Contact

To be able to test the App in your Gladly environment contact a PS Engineer.

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.