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 the 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 oauths <command> — Provides OAuth related actions.
 |
It is recommended that you use the OAuth services in the WorkflowSubsystem in ThingWorx Composer to load or delete OAuths.
|
• 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 oauths
This command enables you to work with OAuth configurations. This command has two subcommands:
• flow-deploy oauths delete — Deletes OAuth configuration from a running instance of ThingWorx Flow.
|
|
It is recommended that you use the OAuth services in the WorkflowSubsystem in ThingWorx Composer to load or delete OAuths.
|
The following parameters are common across all subcommands of the flow-deploy oauths 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]
|
flow-deploy oauths load
This command uploads OAuth configurations to a running instance of ThingWorx Flow.
For instructions on loading OAuth for connectors, refer to Configuring Connector OAuth Settings.
In addition to the common parameters across all subcommands of the flow-deploy oauths command, this command accepts the following parameter:
|
Parameter
|
Description
|
Data Type
|
|---|---|---|
|
--file, -f
|
Name of the OAuth configuration data file
|
[String]
|
The syntax of the flow-deploy oauths load command is as follows:
flow-deploy oauths load -u <ThingWorx_Administrator_Username> -p '<ThingWorx_Administrator_Password>' --twx-url <ThingWorx_Base_URL> -f <Path_to_OAuth_Configuration_File>
where <ThingWorx_Base_URL> must be in the https://<hostName:port>/Thingworx format.
flow-deploy oauths delete
This command is used to delete an existing configuration from ThingWorx Flow. If you delete OAuth configurations, you need to recreate the connection in the flows.
In addition to the common parameters across all subcommands of the flow-deploy oauths command, this command accepts the following parameter:
|
Parameter
|
Description
|
Data Type
|
|---|---|---|
|
--name, -n
(Required)
|
Name of the connector. This name is available in the OAuth configuration file.
|
[String]
|
|
--title
(Required)
|
Title of the OAuth-provider. This title is available in the OAuth configuration file.
|
[String]
|
The syntax of the flow-deploy oauths delete command is as follows:
flow-deploy oauths delete -u <ThingWorx_Administrator_Username> -p '<ThingWorx_Administrator_Password>' --twx-url <ThingWorx_Base_URL> -n <Name_of_the_Connector> --title <Title_of_the_OAuth-provider>
where <ThingWorx_Base_URL> must be in the https://<hostName:port>/Thingworx format.
For example, to delete OAuth for ‘box’ connector with title ‘Box’, run the following command:
flow-deploy oauths delete -u <ThingWorx_Administrator_Username> -p '<ThingWorx_Administrator_Password>' --twx-url <ThingWorx_Base_URL> -n box --title Box
where <ThingWorx_Base_URL> must be in the https://<hostName:port>/Thingworx format.
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.
|
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
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>