Deploying Connectors
After you build and test the connector locally, you can deploy it to an on-premise test instance of ThingWorx Flow. To deploy your connector to the ThingWorx Flow server, perform the following steps:
1. From your connector project, run the npm install command.
This installs all packages required by the connector.
2. Start Command Prompt and execute the following command:
flow-deploy connector -s <Root_Directory_Of_Connector_Project> -t <ThingWorx_Flow_Install_Directory>
This command performs the following tasks:
a. Copies artifact metadata to the database load file.
b. Deploys icons to the runtime location.
c. Copies connector code to the runtime location for connectors.
3. To load the deployed artifact metadata into ThingWorx Flow, execute the following command:
flow-deploy migrate
4. Navigate to > > to restart the ThingWorx Flow service.
You should be able to author flows using connections, actions, and triggers from your connector.
flow-deploy
The flow-deploy command has the following subcommands:
• flow-deploy about —Provides information about the ThingWorx Flow Deploy Utility.
• flow-deploy connector —Deploys connector artifacts to a local installation of ThingWorx Flow.
• flow-deploy migrate —Loads deployed artifact metadata into the ThingWorx Flow server.
• flow-deploy settings <command> —Uploads or downloads connector settings.
All subcommands of the flow-deploy command accept the following parameters:
Parameter | Description | Data Type |
|---|---|---|
--log,-l | Sets the log level. | [String] [default: “info”] |
--version | Displays the version number of the ThingWorx Flow Deploy Utility. | [Boolean] |
--help | Displays help for various commands, subcommands, and parameters that can be provided to the command. | [Boolean] |
flow-deploy about
Prints version information of the ThingWorx Flow Deploy Utility. The command syntax and output for the flow-deploy about command is as follows:
flow-deploy about
ThingWorx Flow Deploy Utility, Version :1.0.2
flow-deploy connector
Deploys the custom connector package to the ThingWorx Flow installation directory, and updates load scripts to include metadata about custom connector artifacts such as connections, actions, and so on.
The flow-deploy connector command accepts the following parameters:
Parameter | Description | Data Type |
|---|---|---|
--sourceDir,-s (Required) | Root directory of the custom connector project. | [String] |
--targetDir,-t (Required) | ThingWorx Flow installation directory, defaults to C:\ThingWorxOrchestration. | [String] |
--allow_schema_overwrite | The flow-deploy tool does not allow overwriting input and output schema properties found in the metadata JSON files of an existing action, connection, and trigger. If this were allowed, any flows that were created using the old schema would break. However, during development, you can overwrite input and output schema properties. Set this flag to overwrite the existing schema with the new schema from the connector project. | - |
The syntax of the flow-deploy connector command is as follows:
flow-deploy connector --sourceDir <Root_Directory_Of_Connector_Project> --targetDir <ThingWorx_Flow_Install_Directory>
flow-deploy migrate
This command loads connector metadata into the ThingWorx Flow server.
The flow-deploy migrate command accepts the following parameters:
Parameter | Description | Data Type |
|---|---|---|
--sourceDir,-s (Required) | ThingWorx Flow installation directory, defaults to C:\ThingWorxOrchestration. | [String] |
--Database username, -u (Required) | User name for the ThingWorx Flow database. | [String] |
--Database password, -p (Required) | Password for the ThingWorx Flow database. | - |
The syntax of the flow-deploy migrate command is as follows:
flow-deploy migrate --sourceDir <ThingWorx_Flow_Install_Directory> -u <Username_for_ThingWorx_Flow_Database> -p <Password_for_ThingWorx_Flow_Database>
flow-deploy settings
You can configure multiple tenants for a single connector. This command allows you to update the behavior of a connector by allowing customization of some of its settings for a particular ThingWorx Flow server. This command has the following subcommands:
• flow-deploy settings download—Downloads connector settings from a running instance of ThingWorx Flow.
The following parameters are common across all subcommands of the flow-deploy settings command:
Parameter | Description | Data Types |
|---|---|---|
--username,-u | ThingWorx administrator user name | [String] |
--password,-p | ThingWorx administrator password | [String] |
--app-key,-a | ThingWorx application key | [String] |
--twx-url,-t | ThingWorx base URL in the https://<hostName:port>/Thingworx format. | [String] |
--connector,-c | Connector name | [String] |
--file,-f | Path to connector settings file | [String] |
--systemid,-s | Custom System ID | [String] |
--default, -d | Default System ID | [String] |
flow-deploy settings download
Downloads connector settings from a running instance of ThingWorx Flow.
For example, to download configuration settings for a specified connector on the ThingWorx Flow server, execute the following command:
flow-deploy settings download -f <Path_to_Connector_Settings_File> -t <ThingWorx_Base_URL> -u <ThingWorx_Administrator_Username> -p '<ThingWorx_Administrator_Password>' -c <Connector_Name> -s <Custom_System_ID>
flow-deploy settings file-download
Downloads a file from a running instance of ThingWorx Flow.
In addition to the common parameters across all subcommands of the flow-deploy settings command, this command accepts the following parameter:
Parameter | Description | Data Type |
|---|---|---|
--fileId | File ID of the file that you want to upload. This name is available in the connector settings definition file. | [String] |
The syntax of the flow-deploy settings file-download command is as follows:
flow-deploy settings file-download -f <Path_to_Customization_File> -t < ThingWorx_Base_URL> -u <ThingWorx_Administrator_Username> -p '<ThingWorx_Administrator_Password>' -c <Connector_Name> -s <Custom_System_ID> –fileID <ID_of_the_File_to_Upload>
flow-deploy settings upload
Uploads connector settings to a running instance of ThingWorx Flow.
 | Before you execute this command, create a configuration settings JSON file and use the -f parameter to provide the path to this file. If the settings in this file match the schema, the settings are successfully uploaded; otherwise you get an error message that provides the required schema. |
In addition to the common parameters across all subcommands of the flow-deploy settings command, this command accepts the following parameter:
Parameter | Description | Data Type |
|---|---|---|
--propertyKey,-k | Name of the property that you want to update. For a single property , provide the <propertyName> only. For a JSON object or an array, provide the <propertyPath>. For example: For JSON object, provide prop1.prop2.prop3, for array, provide prop1[0].prop2[1].prop3. | [String] |
Consider the following examples:
◦ To upload settings to the ThingWorx Flow server for a given connector with a custom system ID, execute the following command:
flow-deploy settings upload -f <Path_to_Connector_Settings_File> -t <ThingWorx_Base_URL> -u <ThingWorx_Administrator_Username> -p '<ThingWorx_Administrator_Password>' -c <Connector_Name> -s <Custom_System_ID>
◦ To upload settings to the ThingWorx Flow server for a given connector with the default system ID, execute the following command:
flow-deploy settings upload -f <Path_to_Connector_Settings_File> -t <ThingWorx_Base_URL> -u <ThingWorx_Administrator_Username> -p '<ThingWorx_Administrator_Password>' -c <Connector_Name> -d
◦ To update a single property in the settings file for a given connector, execute the following command:
flow-deploy settings upload -f <Path_to_Connector_Settings_File> -k <propertyName> or <propertyPath> -t <ThingWorx_Base_URL> -u <ThingWorx_Administrator_Username> -p '<ThingWorx_Administrator_Password>' -c <Connector_Name> -d
The command takes the value of the specified property from the settings file, and uploads it to the ThingWorx Flow server.
flow-deploy settings file-upload
Uploads a file to a running instance of ThingWorx Flow.
In addition to the common parameters across all subcommands of the flow-deploy settings command, this command accepts the following parameters:
Parameter | Description | Data Type |
|---|---|---|
--fileId | File ID of the file that you want to upload. This name is available in the connector settings definition file. | [String] |
--contentType | Content type of the file. | [String] |
For example, flow-deploy settings file-upload -f <Path_to_Customization_File> -t <ThingWorx_Base_URL> -u <ThingWorx_Administrator_Username> -p '<ThingWorx_Administrator_Password>' -c <Connector_Name> -s <Custom_System_ID> –fileID <ID_of_the_File_to_Upload> --contentType <Content_Type>