Configuration Variables and Credentials in an Integration

Overview

In this quickstart you will create and deploy an integration that takes advantage of:

  1. Config variables set at the organization level
  2. Config variables set at the customer level
  3. Credentials set at the organization level

This example integration is contrived, but illustrates how data flows through an integration, and how config vars and credentials interact with an integration.

The "Pokemon Avatar Sync" Integration

In this integration, each customer has two config variables: a customerName, like "FTL Rockets" or "Mars Mission Corp", and a pokemonAvatar, like "pikachu" or "onix". Your organization would like to create an integration periodically that pulls down a PNG of the customer's Pokemon Avatar, and saves that image to an AWS S3 bucket as ${customerName}.png. Credentials for the S3 bucket and the pokemonAvatarS3BucketName are saved at the organization level as a credential and config variable respectively.

Prerequisite: S3 Bucket and Credentials

To complete this quickstart, you will need an AWS account and permissions to create an S3 bucket and IAM user.

Log on to Amazon AWS and create a new S3 bucket. Note the name of the bucket.

Create an AWS IAM user with the below IAM policy; note the user's programmatic access_key_id and secret_access_key.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:*",
"Resource": ["arn:aws:s3:::BUCKET_NAME", "arn:aws:s3:::BUCKET_NAME/*"]
}
]
}

For your convenience, a cloudformation template is available here to create the S3 bucket, user, and credentials for you.

Create Your Integration

Set Bucket Configuration Variable

Click the Settings link on the left-hand sidebar. Select the Config Variables tab and create a new variable, pokemonAvatarS3BucketName with a value of the name of the bucket you created above.

Set AWS Credentials

Return to Settings and select the Credentials tab. Click + Credential to create a new organization-level credential. Give the credentials a name of your choice, and select API Key / Secret as your Authorization Method. Enter your newly created AWS access_key_id and secret_access_key in the API Key and API Secret fields respectively.

Create Customers

  1. Click the Customers link on the left-hand sidebar.
  2. Click + Customer on the upper-right, and give the customer the name "FTL Rockets" and optional description.
  3. Repeat the customer addition process for a new customer, "Mars Mission Corp".
  4. After adding each customer, click the Config Vars tab and add customerName and pokemonAvatar configuration variables for that customer.

Create the New Integration

Click the Integrations link on the left-hand sidebar. Click + Integration and give your integration a name and optional description.

Create Required Integration Config Variables

This integration requires three variables: pokemonAvatarS3BucketName, customerName, and pokemonAvatar. Select the Required Config Variables tab and add those three required variables. We will be sourcing config vars from the organization and customers respectively, so don't need integration-level default values here.

Set Config Vars for Testing

Now that you have set required integration config variables, you'll notice that the lower right-hand Testing pane prompts you to fill in config variables. Fill in testing values of your choice for customer name and avatar, and the S3 bucket name.

Add Some Actions

Next, we'll add some actions steps to be taken by our integration. Go back to the integration Designer tab.

Action 1 - Pull down information about a Pokemon

Add an HTTP - GET Request action.

Enter "https://pokeapi.co/api/v2/pokemon/" & configVars.pokemonAvatar as your URL while in "JSONata Mode". Note that the editor replaces configVars.pokemonAvatar with the value of the config variables that you chose.

Keep the Response Type as json.

Action 2 - Download the Pokemon Avatar PNG

Add another HTTP - GET Request action.

Enter outputs.httpget.all.sprites.front_default as your URL while in "JSONata Mode". You can toggle to JSONata mode by clicking the icon. Enter binary as your Response Type.

This will use the previous HTTP - GET action's outputs as input.

Action 3 - Save the PNG to S3

Add an S3 - Put an Object action.

Enter the AWS Region that matches where you created your bucket.

Enter =configVars.bucketName as your Bucket Name in simple mode.

Enter =outputs.httpget_1.all as your File Contents in simple mode. This will write the binary data pulled down from the previous step to S3.

Enter configVars.customerName & ".png" as your Object Key in JSONata mode.

Object Tags are not required for this example.

Test Your Integration

You already set up test config variables above.

Now, in the Credentials tab bind the AWS S3 step with the AWS credentials you created.

In the Runner tab, click RUN TEST. Verify that the test runs successfully, and verify that an avatar file is saved to your S3 bucket.

Deploy Your Integration to Customers

Now that you've verified that your integration works, deploy instances of it to some customers.

Publish Your Integration

Click the Publish button on the top-right of your integration page.

Create an Instance for a Customer

Select Customers in the left-hand sidebar. Select one of your customers and click the + Instance button. Select the integration that you created, and give the instance an appropriate name and optional description.

Within the Instance config variables pane, click Copy Organization and Copy Customer buttons to copy organization and customer configuration variables into this instance.

Within the Credentials pane, attach the credentials you created to the AWS S3 - Put an Object step.

Deploy and Test Your Instance

Click the Deploy button on the top right of the instance page, and then click RUN TEST.

Verify that a Pokemon avatar was written out correctly to your S3 bucket.

Last updated on