Workflows Task Plugin Quickstart

Workflows Task Plugins are the XM Extension components that perform actions during workflow execution, like pushing, pulling, or updating data.

Objectives

By the end of this guide you will:

1. Create and Run a Qualtrics Workflows Task Plugin within an existing XM Extension (created during the Extension Quickstart guide)
2. Understand the key components and gotchas related to creating Workflows Task Plugins
3. Learn how to modify Workflows Task Plugins

Prerequisites

Before starting please ensure you've completed these prerequisites:

• Completed the Extension Quickstart guide

Create and Run a Workflows Task Plugin

Use xmt to create and run a Workflows Task Plugin from the default template.

Step 1: Create Workflows Task Plugin

Navigate to your hello_world directory that you created previously in the Extension Quickstart guide.

Run the following command to initialize an workflows_task Plugin:

xmt create plugin

Running this command will result in a prompt to gather information on the plugin. First you will be asked to provide a plugin name, let's use "My Workflows Task Plugin".

Plugin Name: My Workflows Task Plugin

Once you have provided a valid name, you will be prompted to select which Plugin Type you want to create. Select "Workflows Task" using the arrow keys and press the Enter key.

Use the arrow keys to navigate: ↓ ↑ → ← 
? select the plugin type:
    Workflows Event 
  ▸ Workflows Task

Next you will be prompted to select a "function" for your Workflows Task. Select XM Function as it is more feature-rich and flexible than the Webservice option.

? Select your task function: 
  ▸ XM Function
    Webservice

At this point you will be prompted to select a starter code package. Each Plugin Type will have different start code package options. Currently the Workflows Task Plugin Type offers an ES6 starter code package and a TypeScript starter code package. Select the ES6 option for this guide.

Use the arrow keys to navigate: ↓ ↑ → ← 
? Select your language standard: 
  ▸ ES6
    TypeScript

Select the No thanks option when prompted to add a connection to your plugin:

? Would you like to add a connection to your new plugin?: 
Add new connection
Learn more
▸ No thanks

After completing the process of configuring your Workflows Task Plugin, your hello_world/plugins directory should look like this:

plugins
    └── my_workflows_task_plugin
        ├── clean.js
        ├── config.json
        ├── package-lock.json
        ├── package.json
        ├── postcss.config.js
        ├── public
        │   ├── index.html
        │   ├── schemas
        │   │   └── schema.json        
        │   └── translations
        │       └── EN.json
        ├── src
            ├── index.html
            ├── main.js
        │   └── plugin-app
        │       ├── README.md
        │       ├── configuration-form-fields.js
        │       ├── configuration-form.jsx
        │       ├── introductory-section.jsx
        │       ├── plugin-app.jsx
        │       ├── plugin-app.scss
        │       └── xm-function-task-definition.js
        ├── webpack
        │   └── string-replace-loader-options.js
        ├── webpack.config.js
        └── worker.js

Step 2: Build and Run Your Extension

To test your XM Extension including the Workflows Task Plugin you just created locally, two processes must be run simultaneously. First, execute the following commands in your my_workflows_task_plugin Plugin directory:

npm install
npm start

Then, in a different terminal, navigate to your hello_world Extension directory and run:

xmt develop extension

You should see this output in your command line:

Submitting extension version 0.0.1-SNAPSHOT...
Preparing submission of extension {extension id}
Submitted version 0.0.1-SNAPSHOT of extension {extension id}
Submission ID: {submission id}

Note: This submission is for a snapshot version and should only be used for development purposes. Snapshot versions can be overwritten, and cannot be certified or published. To submit a non-snapshot version, run 'xmt submit extension --release'.

Waiting for submission to complete...
Submission complete. Below is the submission report:

Success! Your extension was successfully submitted. Submission ID: {submission id} 

Since this is the first time you are submitting this extension, we need some extra time to set things up. Your extension should be ready to share within 30 minutes.
Starting development session: {develop session id}
Watching for changes...

At this point you will have two processes running locally:

1. The process initiated by xmt develop extension inside the hello_world directory, which uploaded your local XM Extension and Plugin to Qualtrics by submitting a Prerelease extension version and continually resubmits that prerelease version when your Plugin changes.

2. The process initiated by npm start inside the plugins/my_workflows_task_plugin directory, which continuously builds your Plugin in response to file changes in your Plugin's src folder

Step 3: Experience Your Extension

Follow these steps to view your XM Extension in the Qualtrics XM Platform:

3.1: Navigate to your developer brand via the developer Portal Developer Brand by selecting Preview this version for your newly created snapshot.

Sharing your extension with your Developer Brand

We recommend navigating to your developer-plan by clicking Preview this version which will automatically share your new extension with your developer brand. If you do not navigate to the brand in this manner you will need to manually share your extension.

3.2: Log in to your account.

3.3: Select an existing survey or create a new one.

3.4: Select the Workflows tab. Then click the Create a workflow button. Select the option Started when an event is received.

3.5: In the dialog box that appears, select the Survey response option.

3.6: Select Newly created responses as the response type and then click Finish.

3.7: Click the plus button below the Survey Response Trigger and choose Add a task

3.8: Your extension labeled Hello World should appear in the gallery of tiles.

Your extension isn't shown

The Workflows task selector caches results which can result in your task not showing up immediately, if you don't see your task, append ?resetUserCache=true to the page url and reload the page.

3.9: Click on your Hello World Extension and you should see your template Plugin titled Hello World which includes an example UI with an Introductory Section in which you can add and remove fields.

Can't Save

Note that at this point it is expected that you can't click the Save button

Step 4: Modify Your Plugin

As part of running the command to create a new Workflows Task, some boilerplate files were added to your file structure inside the plugins directory. We'll go over all of that in more detail in the full Deep Dive guide, but for right now, the two most important folders are public and src.

When making modifications to your Plugin, you should be doing all of your coding inside the src directory. The public directory is built when you run npm start or npm run build, and it contains the code that is actually rendered by the browser but it should not be edited directly.

Use the Latest npm Version

It's important to use the latest major version of npm to ensure all plugin components build correctly.

Follow these steps to make some quick modifications to your new Plugin:

4.1: In a new terminal, navigate to the src directory by running the following command:

cd plugins/my_workflows_task_plugin/src

4.2: Open the existing index.html file and add a header inside the body element above <section id="app-root"></section>:

<h1>
  My Workflows Task Plugin
</h1>
<section id="app-root"></section>

4.3: Save the file

4.4: In your browser close the Hello World modal by pressing the Cancel button:

4.7: Select the Hello World extension again, and you should see the HTML snippet you just added.

But wait, there's more!

The instructions above let you get your hands on the code quickly, but they don't give you the whole story. Check out the Deep Dive for details on what comes with your Workflows Task out of the box and how you can use it.

Step 5: Modify Your Extension

Change the description of your Extension to align with its title, "Hello World", by following these steps:

5.1: Open up hello_world/assets/translations/EN.json:

{
  "meta": {
    "summary": "Extension Language Strings - EN"
  },
  "strings": {
    "name": {
      "text": "Hello World",
      "context": "The Extension Name"
    },
    "description": {
      "text": "Extension Description",
      "context": "Displayed when listing the extension"
    },
    "longDescription": {
      "text": "Extension Long Description",
      "context": "This long textual description is displayed when a user clicks on an extension"
    }
  }
}

5.2: Modify the value from Extension Description to Say Hello to the World!:

    "description": {
      "text": "Say Hello to the World!",
      "context": "Displayed when listing the extension"
    },

5.3: Save the file.

5.4: Refresh the Workflows webpage (closing and reopening the task selector is not sufficient for extension-level changes):

5.5: Click the plus button below the Survey Response Trigger and choose Add a task

5.6: Search for your local Extension.

5.7: Notice that the second line of text in your Extension now displays Say Hello to the World!.

What's Next?

Congratulations on creating, running, experiencing, and modifying your XM Extension and Workflows Task Plugin!

Continue building out your plugin by following the Deep Dive