Developing and installing extensions

Extensions let developers create their own Workforce actions that integrate with 3rd party products and make their data available to be used in automation flows. You can also create extensions that contain custom business logic.

Building your own extension

On this page we'll explain the structure of extensions and walk you through developing and deploying a simple extension that installs a Hello World action in your library.

Extensions can contain multiple actions, with each extension showing in the Integrations section of the Actions Library.

Each extension appears in its own folder within the Integrations section, as shown in the Hello World example below. Any extensions you develop will be added to this section.

The example Hello World extension just contains one action, but you can include multiple actions within the same extension.

Building an extension

There are 3 parts to an extension:

• JavaScript code. This is the implementation of your extension. The code is hosted by Amplience and run within a sandbox. Your code must conform to the Minimum Common Web Platform API standard. If you write your code in TypeScript, you'll need to provide a bundler to compile it to JavaScript.
• A manifest file. This is a JSON file that provides information to our system about what actions the extension contains and the format of its inputs and outputs.
• Description- When you create an extension you will need to provide a description. This is markdown format text that will be used in our marketplace to help users discover the extension.

When you install an extension on a hub you will need to create a release. This is a version of the extension containing the code and manifest. An instance of an extension is a specific version that is installed on a hub.

The Hello World example

The Hello World example is a simple extension that implements an action named "Hello" that takes a string and appends "Hello" to the start of it. We'll use this example to outline the structure of the JavaScript and manifest files, and walk through the steps required to build and install an extension on a hub.

You can download the full example. The code is written in TypeScript but you can build it to generate an index.js file and a minified manifest file that you can use to create an extension release.

index.js

The code simply takes the input from the user and adds "Hello" at the beginning. We're also making use of an environment variable to set a default name if none is specified. Environment variables can be used for parameters such as API keys and will be passed as part of the request when you create an extension instance.

We're exporting a function named hello. Each action you define will use a function you've exported.

function hello({ name }) {
  const messageName = name || process.env.HELLO_DEFAULT_NAME;
  return { message: messageName ? `Hello ${messageName}` : `Hello world` };
}
export { hello };

Manifest files

In the manifest file we're defining a single action with the name "hello". The name must match a function that we exported from our index.js file. The label defines how the action is displayed in Workforce.

The description should specify what the action does. This should be written to be consumed by AI as well as human users, to ensure that the action can be consumed by AI agents.

The input and output schemas specify the format of the action's inputs and outputs. In this example the input and output is a string. The root of both inputSchema and outputSchema must be an object.

The schema format is a simplified version of the JSON Schema used by Dynamic Content, but you cannot use features such as $refs and linked content. However, you can specify that properties are required.

The envSchema specifies the format of the environment variables that the extension supports, in this case a string with a default name.

{
  "envSchema": {
    "type": "object",
    "properties": {
      "HELLO_DEFAULT_NAME": {
        "type": "string",
        "title": "Default name when name input is empty"
      }
    }
  },
  "actions": [
    {
      "name": "hello",
      "label": "Hello",
      "description": "Say hello",
      "inputSchema": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          }
        }
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          }
        }
      }
    }
  ]
}

Creating an extension on your hub

Once the code and manifest have been created, you can create the extension on your hub using the integrations UI or using the GraphQL Management API. See the Installing an extension using the GraphQL Management API page for more details of how to use the API. The rest of this page will walk you through creating and installing an extension using the UI.

To create an extension, open the integrations page and click the "Create extension" button.

Step 1- Create the extension

From the create extension dialog, enter the extension label, description and a URL that contains documentation. You'll also need to add the source of the SVG for the extension icon.

• The label will be used as the folder name in the Action Library in Workforce. Your actions will be shown within this folder.

• The description is markdown format text that will be used to provide detailed information about the extension.

• The URL should be a link to docs providing more information.

• The extension icon is shown in the Action Library in Workforce. It must be specified as an SVG, either as a URL or inline as a Base64 encoded string. In the example below, the SVG is included inline.

Click to view the SVG for the hello world example

data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTI4IiBoZWlnaHQ9IjEyOCIgdmlld0JveD0iMCAwIDEyOCAxMjgiIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+CjxwYXRoIGQ9Ik0xMTEuNDY3IDExNC4yMzVMMzQuNzkyOCAxMTQuMzMxTDM0LjcxMDkgNDkuMDI1M0w2MC4wNzQzIDIyLjM4NzNMMTExLjM1MiAyMi4zMjNMMTExLjM2MiAzMC40MDg0TDExMS40NTMgMTAzLjAwMkwxMTEuNDY3IDExNC4yMzVaIiBzdHJva2U9IiMyMTYwODMiIHN0cm9rZS13aWR0aD0iMiIvPgo8cGF0aCBkPSJNODEuMjA0IDIyLjM2MDhMNjAuMDc0NSAyMi4zODczTDM0LjcxMTEgNDkuMDI1M0wzNC43ODg4IDExMS4wNTFMMjMuMjg4MiAxMTMuNzYzTDguMTY0MDYgNDkuNjM5N0wyNi45Mzk0IDE3LjYzMzdMNzcuMjg4MiA1Ljc1ODU0TDgxLjIwNCAyMi4zNjA4WiIgc3Ryb2tlPSIjMjE2MDgzIiBzdHJva2Utd2lkdGg9IjIiLz4KPHBhdGggZD0iTTI2LjUzNjkgMTguMjE0NEwzMi44NDE0IDQ0LjA2MjhMOC4xNjc5NyA1MC4wODA3IiBzdHJva2U9IiMyMTYwODMiIHN0cm9rZS13aWR0aD0iMiIvPgo8cGF0aCBkPSJNNjAuMDc0MyAyMi4zODcyTDYwLjEwNzcgNDguOTkzNEwzNC43MTA5IDQ5LjAyNTMiIHN0cm9rZT0iIzIxNjA4MyIgc3Ryb2tlLXdpZHRoPSIyIi8+CjxwYXRoIGQ9Ik00NS41IDgxLjMzMTVIMTAwLjgzMyIgc3Ryb2tlPSIjRjg4QjhCIiBzdHJva2Utd2lkdGg9IjIiLz4KPHBhdGggZD0iTTQ1LjUgNzAuNjY0OEgxMDAuODMzIiBzdHJva2U9IiNGODhCOEIiIHN0cm9rZS13aWR0aD0iMiIvPgo8cGF0aCBkPSJNNDUuNSA5MS4zMzE1SDEwMC44MzMiIHN0cm9rZT0iI0Y4OEI4QiIgc3Ryb2tlLXdpZHRoPSIyIi8+CjxwYXRoIGQ9Ik00NS4xNTIzIDEwMi4xMjdIMTAwLjYiIHN0cm9rZT0iI0Y4OEI4QiIgc3Ryb2tlLXdpZHRoPSIyIi8+Cjwvc3ZnPg==

Once you've entered all the information, click the "Create" button. The extension is created and the create release dialog is displayed.

Step 2- Create the release

A release contains a specific version of the extension, including its code and the manifest file. There can be multiple versions of an extension installed on the same hub (and the user can choose between them).

Fill in the following information in the Create Release dialog:

• The label. This will generally be the version
• The manifest file. In the Hello World example, this is generated in the dist folder as part of the build.
• The code to your index.js. For Hello World all the source code is in a single file, but in more complex examples, index.js will usually be generated from several files as part of the build.

Copy and paste index.js into the field labelled "code" in the Create Release dialog.

Once everything is complete, click the "Create" button. The release is created and the extension is now available to install on your hub.

Installing an extension

To install the extension on a hub, click the "Install" button on the extension's tile in the Integrations homepage.

From the extension's install window choose the release to install. In this example we have a single version of Hello World: 0.01. Click the version to continue.

The final step is to configure the instance of the extension. An instance is a specific version of the extension that is installed on a hub.

Give the instance a label to identify it and fill in the values of any variables you defined in the manifest environment variables.

In Hello World, there is a single environment variable defined- the default name to be used if the user doesn't provide one. For commerce extensions and those containing actions to connect to Dynamic Content and Content Hub, for example, you will need to provide additional information such as API Keys.

Click the Install button to continue.

The extension is now installed and its actions are available to use in flows. You can find information about all installed extensions in the Installed extensions tab.

Multiple instances of an extension

You can install multiple instances of an extension and choose between each instance in your flows. See installing multiple instances of an extension for more details.

Testing the extension

Once installed on the hub, the extension is now shown in the Action Library under a category called "Hello World".

The name of the action is specified in the manifest file, while the folder label is configured when the extension is created using the createExtension mutation.

Download the Hello world example

You can download the Hello world example, including the code and manifest shown on this page.

Usage notes

Extensions are hosted by Amplience and run within a sandbox.

• Extension code must be written in JavaScript and conform to the Minimum common web API WinterTC standard.

• Your input and output schemas must be objects.

• The maximum character length for the SVG specified when you create an extension is 4096 characters.

The following limits apply to extensions:

• 30 seconds run time
• 10 API requests
• 128MB of RAM
• No access to the local network

Related pages

Workforce integrations