Skip to main content

Integrations in Multiple Regions

Syncing integrations between regions​

Behind the scenes, an integration is saved as a YAML definition that outlines the flows, steps, configuration and config variables that make up the integration. Integrations can be copied 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 Integration Details gear icon on the left side of the integration designer and then 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 you have it 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 between regions. For example, you might publish an "Acme Inc" component 50 times during testing on the US Commercial stack, and only twice on your Europe tenant. In that case, "v50" in the US stack would correspond to "v2" in the Europe stack. A YAML file that specifies "Acme Inc v50" would mean nothing 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 YAML definition of your integration, you can import the integration through the UI or using prism. In the integration designer, you can open up the Integration details modal once again, and then time select Import. Using prism, run prism integrations:import --path ./my-file.yaml to import your YAML file.

Troubleshooting: If you get any errors, ensure that the custom components that you used in your source stack are also deployed to your destination stack. You may have an older version of your custom component that is missing 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 is made of flows, steps, config variables, and some other 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 presents problems if 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 functionally be the same, but the flow's ID behind the scenes 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 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 outline 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, the component is published to a single region. If you would like to publish a built component to multiple regions, you will need to log in to each region and run prism components:publish.

Alternatively, you can store a refresh token for each region. Then, you can push the component to whichever region you like:

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 seen as v50 and v10 respectively.

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

If you would like to develop integrations and custom components in one tenant, and automatically deploy them to another, you can save your custom component code and integration YAML in a version control system (like a git repo), 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.

Because integrations are dependent on components, build and publish your components first, and then update your integrations. See above for information on publishing components in several 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 along with the updateInstance GraphQL mutation to update deployed instances to the latest published version of your integration.