ThingWorx Flow > ThingWorx Flow Connectors > Deploying Connectors
  
Deploying Connectors
Deployment in an On-premise Environment
After the Connector is built and tested locally, it can be deployed to a test instance of ThingWorx Flow on premise. The flow-deploy tools is available for use in an on-premise installation. Use the following command to deploy a connector:
flow-deploy <command>
The deploy command consists of the following 5 sub commands:
flow-deploy about—Provides information about ThingWorx Flow.
flow-deploy connector—Deploys the connector artifacts to a local installation of ThingWorx Flow.
flow-deploy migrate—Loads the deployed artifact metadata into ThingWorx Flow server.
flow-deploy oauths <command>—OAuth related actions
flow-deploy settings <command>—Upload or download the connector settings.
The following options are supported by the deploy command:
Options
Description
Data Type
--version
Displays the version number.
[Boolean]
--help
Displays the help for various commands.
[Boolean]
The flow-deploy tool needs to run on the server that holds ThingWorx Flow installation. Use the --help option to get help on a command and sub-command. It also displays the possible options that can be provided to the command. All the commands accept --log/-I <level> option to print logs.
Each command is explained in the sections that follow:
flow-deploy about
Prints the version information of the flow-deploy tool. The command syntax and its 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 ThingWorx Flow installation directory, and then update the load scripts to include metadata about the custom connector artifacts such as connections, actions and so on.
The syntax of the flow-deploy connector command is as follows:
flow-deploy connector --sourceDir <path to the connector directory> --targetDir <path to the ThingWorx Flow root directory>
It has the following 3 sub-commands:
--sourceDir/-s—The location of the custom connector project directory.
--targetDir/-t—ThingWorx Flow installation directory, defaults to c:\orchestration.
--allow_schema_overwrite—The flow-deploy tool does not allow overwriting the input and output schema properties found in the metadata json files of an existing action, connection, and trigger. If this were allowed, any flows created using the old schema is broken. However during the development, you can overwrite the input and output schema properties. The flag allows the schema to be overwritten with the new schema from the connector project.
* 
This is an optional step.
The flow deploy connector command accepts 2 optional parameters. The following table depicts the options available for this command:
Options
Description
Data Type
--version
Displays the version number.
[Boolean]
--help
Displays the help for various commands.
[Boolean]
--sourceDir,-s
Root directory of the connector project.
[String]
--targetDir,-t
ThingWorx Flow install directory.
[String]
--log,-l
Sets the log level.
[String] [default: “info”]
flow-deploy migrate
The flow deploy migrate command adds or updates the connector metadata to a running instance of ThingWorx Flow server.
The syntax of the flow deploy migrate command is as follows:
flow-deploy migrate --sourceDir <path to the connector directory> -u <username for Postgress database> -p <password for Postgress database>
The command requires the following options:
-u—The user name of ThingWorx Flow postgres flow schema.
-p—The password of ThingWorx Flow postgres flow schema.
--sourceDir/s—ThingWorx Flow installation directory defaults to c:\orchestration
flow-deploy oauths
This command allows working with OAuth configurations. This has two sub-commands—load and delete. The load sub-command is used to add one or more Oauth configurations and the delete sub-command is used to delete an existing configuration from ThingWorx Flow. If you delete the OAuth configurations, you need to recreate the connection in the flows. This command adds or updates the connector metadata into a running instance of ThingWorx Flow server. The following options are common across the oauths load and delete commands.
--username/-u—The user name of a user in the Administrators group in ThingWorx
--password/-p—The password of the user specified with -u.
--twx-url/-t—The URL of the ThingWorx server that typically is as follows https://host[:port]/Thingworx
--app-key/-a—This can be used instead of -u and -p. The application key should be retrieved from ThingWorx. Refer to ThingWorx Flow Help Center for creation of the application key.
flow-deploy oauths load
The flow deploy oauths load command uploads oauth configurations to a running instance of ThingWorx Flow.
The syntax of the flow deploy oauths load command is as follows:
flow-deploy oauths load <Connector name> -u <ThingWorx Administrator User name> -p <ThingWorx Administrator password> --twx-url <ThingWorx Flow URL> -f <Path to the OAuth Configuration file>
For instruction on oauth load process, refer to the Configuring Connector OAuth Settings topic.
The following options are available for the flow deploy oauths load command:
Options
Description
Data Type
--version
Displays the version number.
[Boolean]
--help
Displays the help for various commands.
[Boolean]
--username,-u
ThingWorx Administrator username
[String]
--password,-p
ThingWorx Administrator password
[String]
--app-key,-a
ThingWorx App Key
[String]
--twx-url,-t
ThingWorx Base URL
[String]
--logLevel,-l
Sets the log level.
[Default: “info”]
--file,-f
Provides the file name of the oauth data file.
[String]
flow-deploy oauths delete
Deletes OAuth configuration from a running instance of ThingWorx Flow.
The syntax of the flow-deploy oauths delete command is as follows:
flow-deploy oauths delete <Connector name> -u <ThingWorx Administrator User name> -p <ThingWorx Administrator password> --twx-url <ThingWorx Flow URL>
This command deletes specific options.
--name/-n—The name of the oauth to delete. You will find the name in the sample oauth data file.
--title—The title of the oauth to delete. This will be available in the oauth data file that you loaded with flow-deploy oauth load.
For example, to delete a box oauth with title “Box”, type the following command:
-n box –title Box
flow-deploy settings
You can configure multiple tenants for a single connector. This fcommand allows you to update the behavior of a connector by allowing customization of some of its settings for a particular server.
Execute the following command to list all the commands related to deploy settings:
flow-deploy settings --help
flow—deploy settings download—Download settings configuration from a running instance of ThingWorx Flow.
flow-deploy settings file-download—Download file to a running instance of ThingWorx Flow.
flow-deploy settings file-upload—Upload file to a running instance of ThingWorx Flow.
flow—deploy settings upload—Upload settings configurations to a running instance of ThingWorx Flow.
The deploy settings command has the following options:
Options
Description
Data Types
--version
Displays the version number.
[Boolean]
--help
Displays the help
[Boolean]
--file,-f
Path to a settings data file.
[String]
--username,-u
ThingWorx Administrator username
[String]
--password,-p
ThingWorx Administrator password
[String]
--app-key,-a
ThingWorx App Key
[String]
--twx-url,-t
ThingWorx Base URL
[String]
--connector,-c
Connector name
[String]
--systemid,-s
System ID
[String]
--logLevel,-l
Set the log level.
[Default: “info”]
Execute the following command to list the options to download the setting from the flow server:
flow-deploy settings download --help
The following options are available to download the setting from the flow server.
Options
Description
Data Types
--version
Displays the version number.
[Boolean]
--help
Displays the help
[Boolean]
--file,-f
Path to a settings data file.
[String]
--username,-u
ThingWorx Administrator username
[String]
--password,-p
ThingWorx Administrator password
[String]
--app-key,-a
ThingWorx App Key
[String]
--twx-url,-t
ThingWorx Base URL
[String]
--connector,-c
Connector name
[String]
--systemid,-s
System ID
[String]
--logLevel,-l
Set the log level.
[Default: “info”]
For example, to download setting for the flow server for given connector, execute the following command:
flow-deploy settings download -f <Path of the Customization File> -t <ThingWorx Flow URL> -u <ThingWorx Administrator User> -p <ThingWorx Administrator User Password> -c <Connector Name> -s <System ID>
Execute the following command to download the file based settings from the flow server for a given connector:
flow-deploy settings file-download --help
The following options are available to download the file based settings from the flow server.
Options
Description
Data Types
--version
Displays the version number.
[Boolean]
--help
Displays the help
[Boolean]
--file,-f
Path to a settings data file.
[String]
--username,-u
ThingWorx Administrator username
[String]
--password,-p
ThingWorx Administrator password
[String]
--app-key,-a
ThingWorx App Key
[String]
--twx-url,-t
ThingWorx Base URL
[String]
--connector,-c
Connector name
[String]
--systemid,-s
System ID
[String]
--logLevel,-l
Set the log level.
[Default: “info”]
--fileId
File ID to upload.
[String]
To list the options to upload the setting to the flow server , execute the following command:
flow-deploy settings upload --help
The following options are available to upload the setting to the flow server:
Options
Description
Data Types
--version
Displays the version number.
[Boolean]
--help
Displays the help
[Boolean]
--file,-f
Path to a settings data file.
[String]
--username,-u
ThingWorx Administrator username
[String]
--password,-p
ThingWorx Administrator password
[String]
--app-key,-a
ThingWorx App Key
[String]
--twx-url,-t
ThingWorx Base URL
[String]
--connector,-c
Connector name
[String]
--systemid,-s
System ID
[String]
--logLevel,-l
Set the log level.
[Default: “info”]
To upload file based connector settings from the flow server, execute the following command:
flow-deploy settings file upload --help
The following options are available to upload the file to the flow server:
Options
Description
Data Types
--version
Displays the version number.
[Boolean]
--help
Displays the help
[Boolean]
--file,-f
Path to a settings data file.
[String]
--username,-u
ThingWorx Administrator username
[String]
--password,-p
ThingWorx Administrator password
[String]
--app-key,-a
ThingWorx App Key
[String]
--twx-url,-t
ThingWorx Base URL
[String]
--connector,-c
Connector name
[String]
--systemid,-s
System ID
[String]
--logLevel,-l
Set the log level.
[Default: “info”]
--fileId
File ID to upload
[String]
--contentType
Content type of the file.
[String]
For example, flow-deploy settings file upload -f <Path of the Customization File> -t <ThingWorx Flow URL> -u <ThingWorx Administrator User> -p <ThingWorx Administrator User Password> -c <Connector Name> -s <System ID>
Before you execute this command, place the setting in any JSON and then provide the path of the file for the -f option in the command. If the settings matches the schema, you will get a loaded settings successful message or you will get an error message with the required schema to match the settings.
Deploying Connectors
Deploying connectors involves the following steps that are performed by the flow-deploy connector command.
1. Copy the artifact metadata to the database load file.
2. Deploy icons to the runtime location.
3. Copy the connector code to the runtime location for connectors.
To deploy your connector, do the following:
1. Run the npm install from your connector project. This installs all the packages required by the connector.
2. Open the command prompt, and then execute the following command:
flow-deploy connector -s C:\temp\custom-connector -t C:\flow
3. To load the deployed artifact metadata into ThingWorx Flow, execute the following command:
flow-deploy migrate
4. Restart the Flow service by navigating to Control Panel > Administrative Tools > Services. You should be able to author flows using Connections, Action and Triggers from your connector.