Using Configuration Variables and Credentials in an Integration

Overview

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

Config variables set at the organization level
Config variables set at the customer level
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 "Smith Rocket Company", 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

Click the Customers link on the left-hand sidebar.
Click + Customer on the upper-right, and give the customer the name "Smith Rocket Company" and optional description.
Repeat the customer addition process for a new customer, "FTL Rockets".
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 button and add those three required variables. Provide a couple of testing values for pokemonAvatar and customerName. 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, if you click the icon you'll notice that the Config variables tab 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 - Combine some strings and config variables for future use

This integration will require two two things:

A URL to pull pokemon data from
A filename to save an avatar file to in S3

Both of those are strings. We'll use a short code component to generate those strings.

Add a Code step to your integration and name it Path Helper. Enter the following code:

module.exports = async ({ configVars }, params) => {
  return {
    data: {
      pokemonUrl: `https://pokeapi.co/api/v2/pokemon/${configVars.pokemonAvatar}`,
      s3ObjectPath: `${configVars.customerName}.png`,
    },
  };
};

Action 2 - Pull down information about a Pokemon

Add an HTTP - GET Request action and name it Get Pokemon Data.

Under the URL input field, choose to reference output from the previous step and enter results.pokemonUrl as your reference search to reference the URL that was generated in the previous step.

If you clicked Run Test on your integration after adding the first step, a preview of available results from the first step will be available.

Keep the Response Type as json.

Action 3 - Download the Pokemon Avatar PNG

Add another HTTP - GET Request action and name it Get Pokemon Avatar.

For the URL input, choose to reference the output from a previous step and enter results.sprites.front_default in the reference search field. This will pull information from the previous HTTP - GET action to determine where the Pokemon's avatar is located.

Enter binary as your Response Type.

Action 4 - Save the PNG to S3

Add an S3 - Put an Object action.

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

For the Bucket Name input, reference config variable bucketName.

For the File Contents input, reference the Get Pokemon Avatar step and enter results in the . This will write the binary data pulled down from the previous step to S3.

For the Object Key input, we'll use an output from the first code component step. Reference the Path Helper step and enter results.s3ObjectPath in the results search field.

Object Tags are not required for this example.

Test Your Integration

You already set up test config variables above.

Now, click the icon and enter the Credentials tab. Bind the AWS S3 step with the AWS credentials you created. The HTTP - GET steps do not require credentials, since the Pokemon API does not require credentials.

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 left-hand of your integration page in the menu.

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, select the customer config variables you set up for pokemonAvatar and customerName, and the organization config var for S3 bucket name.

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

Test Your Instance

Click the 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.

Overview#

The "Pokemon Avatar Sync" Integration#

Prerequisite: S3 Bucket and Credentials#

Create Your Integration#

Set Bucket Configuration Variable#

Set AWS Credentials#

Create Customers#

Create the New Integration#

Create Required Integration Config Variables#

Set Config Vars for Testing#

Add Some Actions#

Test Your Integration#

Deploy Your Integration to Customers#

Publish Your Integration#

Create an Instance for a Customer#

Test Your Instance#