Creating Connections
Some systems may not support OAuth mechanism. They may use other mechanisms for authentication such as basic authentication with a user name and password or they may support a key–based mechanism. Connections need to be defined for all systems that do not support OAuth.
To create a new connection, do the following:
1. From the command prompt, execute the following commands:
a. cd <user project root directory>
b. flow add connection <name>
Your connection will be in the format <service-name>-<connection-name>
The service name is added automatically by the CLI. A new folder, connector name-connection name, is created in your local directory consisting of the connection.json file and the index.js file.
The following options are available for the command.
|
Options
|
Description
|
Data Type
|
|---|---|---|
|
--version
|
Displays the version number.
|
[boolean]
|
|
--help
|
Displays the help.
|
[boolean]
|
|
--parentDir,-d
|
The parent directory for the project.
|
[default: “.”]
|
|
--logLevel,-1
|
Sets the log level.
|
[default: “info”]
|
|
--artifactVersion,-v
|
Version of the artifact to create.
|
[default: “v1”]
|
2. Determine the information that needs to be collected to connect to the system.
 |
The information can be in the form of a URL, a user name, password, or an App key, or any other information needed to connect to the system.
|
The above information needs to be expressed as a JSON schema in the connection.json file. ThingWorx Flow uses this information to display the form on ThingWorx Flow workflow editor.
An index.js file converts the information stored in a form that can be used by Actions and Triggers. This information returned by the form is encrypted and stored in the ThingWorx Flow database.
The formatted schema connection.json file and the input form appears like follows:
The table below describes the properties used in the JSON schema.
Properties | Enter the property in the JSON file |
|---|---|
type | The top-level type should always be of type object. |
title | Used as the title of the authentication window on ThingWorx Flow home page. |
format | Layout used to display the form on ThingWorx Flow canvas. |
properties | Contains attributes that are acquired from the users for authenticating the target system. This can contain any number of children attributes. All children attributes need to have a title, type and description. The type can be of any type supported by the JSON schema. For example, we can see that an email, subscription_id, account_url and API token are required to connect to the system. |
Contract
The JavaScript file such as index.js must export a JavaScript object that contains two methods:
• connect—Converts the input into a form suitable for consumption by Actions, Triggers and Lookups.
• validate—Used to validate a connection. You can typically connect to the target system using some API such as the npm request library.
For information on SDK for APIs that can be used in Connections, refer to the section ThingWorx Flow Connector SDK.
For information on formatting the input and output schema, refer to the note under the topic Creating Actions.
The following video demonstrates the creation of a connection using ThingWorx Flow CLI.
For more information on creating Connections, refer to ThingWorx Flow Connectors SDK Tutorial.