Skip to content

Import and Export Configuration

Export Configuration

The Export Configuration page can be used to export UIP configuration data as a file that can be downloaded by a client web browser.

There is a list of data types which can be selected for export. All of the types are selected by default and at least one type must remain selected.

Enter a passphrase to encrypt the export file. If the passphrase is empty the data will be exported using the human-readable JSON file format.

Caution should be taken when transmitting or storing unencrypted files which contain sensitive information such as account credentials that may be used within adapters, triggers, or workflows.

Import Configuration

The Import Configuration page can be used to import configuration data into UIP.

Before importing, select the types of data to be imported from the configuration file. UIP will automatically use the latest version of any adapter types that are available from the Adapter Type Store.

Use caution when importing custom Adapter Types that do not originate from the Adapter Type Store. Importing the wrong version can cause the system to function incorrectly.

Import Properties For Templates And Use Cases

The UIP Custom Packages and Templates website hosts use cases and templates which can be used to configure systems with a combination of adapters, triggers, workflows, adapter hubs, and adapter hub services that are suited to resolve its target use case.

It is also possible to create your own template by following the pattern described below in Configure File Inputs Section.

If the selected file is a configuration template an Import Properties section may display on the page containing one or more properties which may need to be configured before completing an Import.

Import operations may be blocked until the values of Import Properties meet certain validation criteria. Read the Properties section below for more details about how the configuration template file properties.

Import File Processing

Import files are expected to follow the same file structure that is used for files generated by the Export Configuration page. Each data type object is optional. If the import file contains multiple data objects they should be organized in the same order that is used for exports.

{
    "inputs": {
        "properties": [],
        "conditions": []
    },
    "adapterTypes": [],
    "externalAdapterManagers": [],  // adapter hubs
    "adapters": [],
    "globalProperties": [],
    "workflows": [],
    "triggers": [],
    "serviceInstances": [], // adapter hub services
    "mappingDataCollections": []
}

Adapters can be imported without including the corresponding adapter type. When an adapter is imported UIP will automatically download or upgrade to the latest version of any adapter type that is available from the Adapter Type Store.

Custom adapter types which are not available from the Adapter Type Store will need to be imported. For more information about adapters refer to the Adapters page.

If the chosen file was encrypted using the Export Configuration page you must provide the passphrase that was used to export the file. Leave the passphrase empty if the file is not encrypted.

The Import button will begin the import process. After import is done, an Import Summary is displayed with a Status for each of the chosen data types.

The import status can be Success, Warning, Duplicate. Skipped, or Failed. Click on a type to reveal more result details.

Configuration File Inputs Section

Import configuration files may contain an "inputs" object at the top of the file which provides a convenient way to define custom parameters which are referenced later by other parts of the import file. The inputs object is split into "properties and "conditions" arrays.

For example, an import file could contain:

"inputs": {
    "properties": [{
        "name": "baseuri",
        "value": "http://server.example.com/orchestrator/api/readiness",
        "description": "The base URI for the readiness API.",
        "hide": false,
        "type": "string",
        "required": false,
        "minLength": 1,
        "maxLength": 64,
        "regex": "^http[s]?:\/\/[A-Za-z0-9.-]*"
      }, {
        "name": "port",
        "type": "integer",
        "value": "60030",
        "required": true,
        "minValue": 1,
        "maxValue": 65535
      }, {
        "name": "wfname",
        "value": "wfimp1"
      }, {
        "name": "hookname",
        "value": "imphook"
      }, {
        "name": "flagon",
        "value": "true"
      }, {
        "name": "flagoff",
        "value": "false"
      }
    ],
    "conditions": [{
        "type": "adapter.enabled",
        "name": "httpimp1",
        "condition": "Substring(thebaseuri, 2) == 'ht'"
      }, {
        "type": "adapter.include",
        "name": "httpimp1",
        "condition": "flagoff"
      }, {
        "type": "trigger.enabled",
        "name": "trimp1",  
        "condition": "Substring(thebaseuri, 4) == 'http'"
      }, {
        "type": "adapterHub.enabled",
        "name": "mgrimptest",
        "condition": "Substring(thebaseuri, 4) == 'http'"
      }, {
        "type": "serviceTemplate.deployed",
        "name": "svcimp1",
        "condition": "Substring(thebaseuri, 4) != 'xxxx'"
      }, {
         "type": "globalProperty.include",
         "name": "testmode",
         "condition": "flagon"
      }
    ]
}

Properties

The properties section is an array used to define properties which can be referenced in later elements of the same import file.

Each item within the properties array must contain the following two parameters.

  • name - This is the name used to reference the property. It must contain between 1 to 64 characters.
  • value - This is the value that will be used when the property is referenced. String interpolation can be used within the value. It must be between 0 to 4096 characters.

Additional parameters can be specified for an item in the properties array to control if it can be modified using the Import Configuration page and how the specified value should be validated.

  • description - This can be used to display helpful text on the Import Configuration page about a property.
  • hide - This can be used to prevent a property from being displayed by the Import Configuration page. It can be set to true or false. If it is not specified the default is to display the property.
  • type - This can be set to string, secret, integer, or float. If it is not specified the default is string. If it is a secret the value will be masked on the Import Configuration page.
  • required - This controls if the value of a property can be empty. It can be set to true or false. If it is not specified the default is false.
  • minLength - This controls how short the value of a property can be. If it is not specified no minimum is enforced.
  • maxLength - This controls how long the value of a property can be. If it is not specified the maximum length is 4096.
  • regex - This is a regular expression that will be used to validate the value of a property. If it is not specified for a property that is an integer or a float a default regex will be enforced.
    • The default regex for the integer type is ^[+-]?[0-9]{0,10}$
    • The default regex for the float type is ^[+-]?[0-9]{0,10}([.][0-9]{1,10})?$

There are two native system properties that may also be used within an import file:

  • wfsystem.starttime - a string with the import start date time in local time zone
  • wfsystem.starttimeUTC - a string with the import start date time in UTC time zone

Conditions

The conditions section contains an array of objects with "type, "name", and "condition" fields.

  • The type is where this condition is to be applied. The following types are supported:
    • adapterType.include - should an adapter type be imported
    • adapterHub.include - should an adapter hub be imported
    • adapterHub.enabled - should an adapter hub be enabled
    • adapter.include - should an adapter be imported
    • adapter.enabled - should an adapter be enabled
    • adapter.external - should an adapter be external
    • globalProperty.include - should a global property be imported
    • workflow.include - should a workflow be imported
    • trigger.include - should a trigger be imported
    • trigger.enabled - should a trigger be enabled
    • serviceTemplate.include - should an adapter hub service be included
    • serviceTemplate.deployed - should an adapter hub service be deployed
  • The name is the name of the entity (adapter, trigger, etc.) that the condition should apply do.
  • The condition is the string that is evaluated as true or false.
  • The default for all conditions not specified for a given type/name is true for the ".include" and the value from the import data for the ".enabled" and ".deployed" flags.

Property Replacement

Property replacement is done by replacing the pattern: "!!prop.TEXT!!"

TEXT is the string interpolation value that is replaced. This is the same format as would be entered in a trigger property or workflow property field.

For example, in an adapter's properties array could be:

"properties": [{
  "name": "baseUri",
  "value": "!!prop.{thebaseuri}!!"
}]

The example above will set the parent adapter's baseUri property to "http://172.0.0.1/orchestrator/api/readiness".

Include/Exclude

An entity (adapter, trigger, etc) can be conditionally included or excluded using the "TYPE.include" condition type. If the condition evaluates to false the type of the specified name will be skipped during import.

If a condition of type include is not specified for a name the item will be included.

Supported Replacements

Property replacements are supported for the following:

Adapter Hub (aka externalAdapterManager)

  • Enabled - using the condition type adapterHub.enabled
  • Token - The adapter hub token
  "externalAdapterManagers": [{
      "name": "mgrimptest",
      "enabled": false,
      "token": "footokenimp",
      "description": ""
    }
  ]

Adapter

  • Enabled - using the condition type adapter.enabled
  • External - using the condition type adapter.external
  • ExternalAdapterManagerName - the name of the adapter hub (for external adapters)
  • Token - the adapter hub token (for external adapters)
  • Properties - the "value" field for the properties of the adapter
"adapters": [{
      "name": "httpimp1",
      "type": "httprequest",
      "enabled": false,
      "external": false,
      "token": "",
      "properties": [{
          "name": "baseUri",
          "value": "!!prop.{thebaseuri}!!"
        }, {
          "name": "queryString",
          "value": ""
        }, {
          "name": "header1",
          "value": ""
        }, {
          "name": "header2",
          "value": ""
        }, {
          "name": "header3",
          "value": ""
        }
      ]
    }
  ]

Global Property

  • Name - the global property name
  • Value - the value of the property
  • Description - the tool-tip text displayed for the property
"globalProperties": [{
      "name": "global1",
      "value": "!!prop.{propvalue}!!",
      "description": "This is a global property."
    }
  ]

Trigger

  • Enabled - using the condition type trigger.enabled
  • AdapterName - the adapter name field (webhook name for webhooks)
  • EventName - the event name (for an event trigger)
  • Workflow - the workflow name to execute
  • Properties - the "value" field for the properties of the trigger
  "triggers": [{
      "name": "trimp1",
      "type": "webhook",
      "enabled": false,
      "adapterName": "!!prop.{hookname}!!",
      "eventName": "",
      "workflow": "!!prop.{wfname}!!",
      "allProperties": false,
      "properties": [{
          "name": "name",
          "value": "{name}"
        }, {
          "name": "title",
          "value": "{title}"
        }, {
          "name": "triggerStartTime",
          "value": "{wfsystem.starttime}"
        }, {
          "name": "triggerStartTimeUTC",
          "value": "{wfsystem.starttimeUTC}"
        }, {
          "name": "thing",
          "value": "abc-!!prop.{?Substring(thebaseuri, 9)}!!-xyz"
        }
      ]
    }
  ]

Workflow

  • Properties - the "values" in the properties section of the workflow definition only
  "workflows": [{
      "name": "wfimp1",
      "definition": "{\"workflow\":{\"properties\":[{\"name\":\"p1\",\"value\":\"!!prop.{hookname}!!\"},{\"name\":\"p2\",\"value\":\"aa-!!prop.{flagon}!!-cc-!!prop.{flagoff}!!-zz\"}],\"steps\":[{\"id\":\"start\",\"type\":\"start\",\"next\":\"273ecbec-49d9-40e7-9450-2cd14fa80a8d\",\"parameters\":{}},{\"id\":\"422b41e4-9d65-48a2-b2a6-38fee1cc0138\",\"type\":\"end\",\"parameters\":{},\"successOutputs\":[],\"failureOutputs\":[],\"properties\":[{\"name\":\"readiness\",\"value\":\"{wfresult}\"}]},{\"id\":\"42db6b16-32e5-4006-9cdf-f665b47b3a56\",\"type\":\"command\",\"next\":\"422b41e4-9d65-48a2-b2a6-38fee1cc0138\",\"parameters\":{\"adapter\":\"httpimp1\",\"command\":\"get\"},\"successOutputs\":[{\"name\":\"readiness\",\"value\":\"{content.readiness}\"}],\"failureOutputs\":[{\"name\":\"readiness\",\"value\":\"failed\"}],\"properties\":[{\"name\":\"uri\",\"value\":\"http://172.24.132.4/orchestrator/api/readiness\"}]},{\"id\":\"273ecbec-49d9-40e7-9450-2cd14fa80a8d\",\"type\":\"command\",\"next\":\"422b41e4-9d65-48a2-b2a6-38fee1cc0138\",\"parameters\":{\"adapter\":\"httpimp1\",\"command\":\"get\"},\"successOutputs\":[{\"name\":\"readiness\",\"value\":\"{content.readiness}\"}],\"failureOutputs\":[{\"name\":\"readiness\",\"value\":\"failed\"}],\"properties\":[{\"name\":\"uri\",\"value\":\"http://172.24.132.4/orchestrator/api/readiness\"}]}]},\"designer\":{\"layout\":{\"steps\":[{\"id\":\"start\",\"position\":{\"x\":50,\"y\":50}},{\"id\":\"422b41e4-9d65-48a2-b2a6-38fee1cc0138\",\"position\":{\"x\":360,\"y\":330}},{\"id\":\"42db6b16-32e5-4006-9cdf-f665b47b3a56\",\"position\":{\"x\":220,\"y\":450}},{\"id\":\"273ecbec-49d9-40e7-9450-2cd14fa80a8d\",\"position\":{\"x\":180,\"y\":210}}],\"links\":[{\"type\":0,\"sourceId\":\"42db6b16-32e5-4006-9cdf-f665b47b3a56\",\"targetId\":\"422b41e4-9d65-48a2-b2a6-38fee1cc0138\"},{\"type\":0,\"sourceId\":\"start\",\"targetId\":\"273ecbec-49d9-40e7-9450-2cd14fa80a8d\"},{\"type\":0,\"sourceId\":\"273ecbec-49d9-40e7-9450-2cd14fa80a8d\",\"targetId\":\"422b41e4-9d65-48a2-b2a6-38fee1cc0138\"}]}}}"
    }
  ]

Service Instance (aka Adapter Hub Service)

  • Deployed - using the condition type serviceTemplate.deployed
  • Hub - the name of the adapter hub the service should be deployed to
  • Template - the values in the properties section of the template only
  "serviceInstances": [{
      "name": "svcimp1",
      "deployed": false,
      "hub": "mgrimptest",
      "template": "{\"properties\":{\"foo\":\"!!prop.{?Substring(hookname, 4)}!!\",\"listenPort\":\"7009\",\"imageBase\":\"nginx\",\"imageVersion\":\"1.17\"},\"services\":{\"nginx\":{\"image\":\"docker.io/${imageBase}:${imageVersion}\",\"xxcommand\":\"\",\"env\":[{\"name\":\"MYENV1\",\"value\":\"MYVALUE1\"}],\"ports\":[{\"protocol\":\"tcp\",\"hostPort\":\"${listenPort}\",\"containerPort\":\"80\"}]}},\"volumes\":{\"volume2\":{\"external\":true}}}"
    }
  ]