Deploy an Integration

Tenant Creation

If the merchant does not already have a tenant created in the OIH instance, you need to create one. This tenant will hold ownership of all data flows for any integration deployed for that merchant, regardless of the external system.

  1. Open the Postman Collection
  2. Open IAM > tenants > POST: Create a tenant
  3. Ensure the appropriate “Environment” is selected (top-right)
  4. In the “body” tab, enter an identifiable name for the tenant.
  5. Click “Send” to create the tenant.
  6. Save the tenant ID. You’ll use this to assign flow ownership to this tenant.

Secret (Credentials) Creation

Read about creating a secret.

Flow Provisioning

Provisioning a flow for a given merchant requires multiple steps, once prerequisites for tenant creation and secret creation are accomplished. Merge Configuration Options Into Template Some flows are standard for all merchants (in that case, move on to the next steps). Others include template placeholders where merchant optionality, required logical configurations, cross-reference tables, and other options may be injected into the template to specialize the executable flow to that merchant’s needs. This provides the merchant some configurability without requiring a project for building a bespoke integration.

  1. Copy the flow template to a text file or directly into Postman.
  2. Add the tenant ownership information into the flow JSON at the base level. It should look like this:
"owners": [
    {
      "id": "<your tenant ID>",
      "type": "tenant"
    }
  ]

When you create the flow, the system will automatically add the user who is creating the flow (configured via your Postman environment) as another owner, without you explicitly setting it. 3) Look for end-customer-specific/tenant-specific configurations in the flow. These are typically in JSONata maps. Replace the config values as appropriate for that end user.

  1. URLs for API calls configured in the flow may also require updating. Update any API URLs that are unique to that end user.
  2. It’s uncommon that credentials are directly accessible in a flow JSON, but if any are present, ensure they are updated for that end user.
  3. It’s uncommon that one flow references another flow, but if there are any webhook URL references to another flow, ensure the ID in the webhook URL is set to the appropriate ID for that end user’s tenant.
  4. Consider source controlling or saving the end-user-specific version of the flow.

Merge Secret IDs into Template

Any externally communicating components (e.g. REST component) that are referenced in the template must also be configured to reference the proper API keys, passwords, etc. in the Secret Service. To do so, you must reference their secret ID on the component for that merchant-specific instance of the flow configuration.

  1. If you’ve completed the steps in “Merge Configuration Options Into Template”, open the end-customer-specific flow JSON.
  2. Various components in that flow may reference a “credentials_id”. This is a reference to a record in the Secret service, which will be safely injected into the components functionality at run time.
  3. Update all instances of “credentials_id” to the appropriate GUIDs. These were created during the steps in “Secret (Credentials) Creation”.

Create the Flow

Once configuration options and secrets are merged into the flow template, you must actually create a flow entity. This also includes assigning the flow to a tenant, which is only required on creation (not subsequent updates) unless you are changing the flow ownership, which is not recommended.

  1. Open the Postman Collection.
  2. Open Flow Repository > POST: Create a flow.
  3. Copy the end-user-specific flow JSON into the body tab.
  4. Click “Send”.
  5. Save the returned flow ID. It will be used to start, stop, and update that end user’s version of the flow, going forward.

Remember that a flow has a 1:1 relationship with a tenant. There are rarely cases where you’d deploy the same flow to the same tenant multiple times. You start with a templatized flow JSON and merge in credentials and configuration options, as described above, for each end customer (tenant) who will use the flow. Then you create that flow in each individual tenant.

Activate the Flow

When a flow is successfully created within a given tenant, it must be activated before it can start accepting webhook requests or before the trigger schedule will begin. Flows can be deactivated later, which will be required for operations like updating the flow.

  1. Open the Postman Collection.
  2. Open Flow Repository > Start a flow.
  3. In the “Params” tab, enter the flow’s GUID, returned when that end user’s instance of the flow was initially created for the “flow_id” parameter.
  4. Click “Send”.

If you receive a response back that the request was successful, it can take up to ten seconds for the flow to completely start. Usually it takes less. The activation is asynchronous, so you will not receive a confirmation back when the flow is active.

You can use “Flow Repository > Get a flow” which will return the flow and its status, if you need to verify that the flow has been activated.