Skip to main content

Integrations in Multiple Regions

Syncing integrations between regions​

An integration can be represented as a YAML definition that specifies the flows, steps, configuration, and config variables comprising the integration. Integrations can be replicated between regions by downloading an integration's YAML definition from one region and importing the YAML file into another region.

Exporting an integration's YAML definition​

To access an integration's YAML definition from the integration builder, click the Integration Details gear icon on the left side of the integration designer and select Save to file.

To access an integration's YAML definition using prism, identify the integration's ID by running prism integrations:list --extended, or by copying the SW5..... portion of your integration's URL when it's open. Then, run prism integrations:export:

Save an integration's YAML definition to my-file.yaml
prism integrations:export SW50ZWdyYXRpb246YmE0NGU5NmQtYWMzOS00MDMxLTg4MmUtMWQyNzA5ZjY5MDg0 > my-file.yaml
Component Versions Across Regions

Component versions may not be consistent across regions. For example, you might publish an "Acme Inc" component 50 times during testing on the US Commercial stack, but only twice on your Europe tenant. In this case, "v50" in the US stack would correspond to "v2" in the Europe stack. A YAML file specifying "Acme Inc v50" would be meaningless to the Europe stack.

To avoid version mismatches, export your YAML definition using the Save to file with latest component versions button in the UI, or by adding the --latest-components flag to your prism command:

prism integrations:export --latest-components SW50Z...

When you import your integration in another region, the latest versions of each component will be used.

Importing an integration's YAML definition​

Once you have the integration's YAML definition, you can import the integration through the UI or using prism. In the integration designer, open the Integration details modal again, then select Import. Using prism, run prism integrations:import --path ./my-file.yaml to import your YAML file.

Troubleshooting: If you encounter errors, ensure that the custom components used in your source stack are also deployed to your destination stack. You may have an older version of your custom component that lacks some actions, inputs, etc.

Renaming flows and config variables in YAML definitions​

Use caution when modifying flow names or config variable names in YAML

If you modify the name of a flow or config variable in the YAML definition, you should include a renameAttributes section in your YAML.

Your integration consists of flows, steps, config variables, and additional metadata, and can be represented as a YAML file. When a YAML file is imported, the Prismatic API attempts to match flows and config variables in the YAML with flows and config variables in the existing integration. If a match is found, the existing config variable or flow will remain. If no match is found, a new config variable or flow will be created and the old flow or config variable will be removed.

This creates problems when you want to rename flows or config variables in your YAML definition:

  • If you rename a flow, the Prismatic API will not be able to match the flow in the YAML with a flow in the existing integration, and will create a new flow and delete the old one. Your integration will function identically, but the flow's ID will be different. Instances of your integration will be assigned new webhook URLs for the renamed flow when the instance is updated to the latest integration version. Different webhook URLs can cause issues if you already have webhooks configured using the old flow's URL.
  • If you rename a config variable, the Prismatic API will not be able to match the config variable in the YAML with the config variable in the existing integration, and will create a new config variable and delete the old one. This will cause issues if you have already configured instances of your integration. When a customer updates their instance, their old config variables will be removed and new ones will need to be reconfigured (this includes OAuth 2.0 connections - the customer user will need to reauthenticate their connection).

To ensure that the Prismatic API matches the flow or config variable in the YAML with the flow or config variable in the existing integration, you should include a renameAttributes section in your YAML. This section includes requiredConfigVars and flows sections, which specify the old and new names of config variables and flows, respectively.

configPages:
  - elements:
      - type: configVar
        value: SFDC Connection
      - type: configVar
        value: SFDC Record Type
    name: Page 1
    userLevelConfigured: false
definitionVersion: 7
endpointType: flow_specific
flows:
  - description: ""
    endpointSecurityType: customer_optional
    isSynchronous: false
    name: SFDC Data Import
    steps: []
name: SFDC Integration
requiredConfigVars:
  - key: SFDC Record Type
    description: ""
    dataType: string
    orgOnly: false
    defaultValue: ""
  - key: SFDC Connection
    description: ""
    dataType: string
    orgOnly: false
    defaultValue: ""
renameAttributes:
  requiredConfigVars:
    - newName: SFDC Connection
      oldName: Salesforce Connection
    - newName: SFDC Record Type
      oldName: Salesforce Record Type
  flows:
    - newName: SFDC Data Import
      oldName: Salesforce Data Import

In the above example, we renamed the flow Salesforce Data Import to SFDC Data Import, and renamed the config variable Salesforce Connection to SFDC Connection and Salesforce Record Type to SFDC Record Type. With this block included, the Prismatic API will know to match the old flow and config variable names with the new flow and config variable names, and will not replace flows or config variables with new ones.

Syncing components between regions​

When you publish a component, it is published to a single region. To publish a built component to multiple regions, you must log in to each region and run prism components:publish.

Alternatively, you can store a refresh token for each region. Then, you can deploy the component to any desired region:

Publish a component to multiple regions
# Publish to default US commercial region
prism components:publish

# Publish to EU with inline environment variables
PRISM_REFRESH_TOKEN=your-eu-refresh-token PRISMATIC_URL=https://app.eu-west-1.prismatic.io prism components:publish

# Publish to GovCloud by exporting environment variables
export PRISM_REFRESH_TOKEN=your-govcloud-refresh-token
export PRISMATIC_URL=https://app.us-gov-west-1.prismatic.io
prism components:publish

Note that component versions increment independently in each region. If you've published your custom component 50 times to US Commercial and 10 versions to the Sydney region, the same component code will be versioned as v50 and v10 respectively.

Building multi-region deployment into a CI/CD pipeline​

To develop integrations and custom components in one tenant and automatically deploy them to another, you can store your custom component code and integration YAML in a version control system (like a git repository), and configure a CI/CD pipeline to automatically deploy new versions of components and integrations when code passes QA and is merged to your production branch.

Since integrations depend on components, build and publish your components first, then update your integrations. See above for information on publishing components across multiple regions.

Once components are published, you can use the same prism authentication you used for components to import integrations. The prism integrations:import command will return an integration ID (SW50Z....). Using that integration ID, you can publish a new version of your integration:

prism integrations:publish SW50Z... --comment "My publication comment"

The integrations:publish command will return an integration version ID (SW50Z...). You can use that ID with the updateInstance GraphQL mutation to update deployed instances to the latest published version of your integration.