Configuration-Driven Integration

Overview#

In this quickstart you will create and deploy an integration that takes advantage of config variables and credentials.

The "Pokemon Avatar Sync" Integration#

For this integration, each customer will have two config variables set that are unique to them:

  • Customer Name represents the name of the customer's company - something like "FTL Rockets" or "Smith Rocket Company"
  • Pokemon Avatar represents the company's avatar Pokemon - something like (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 save the image to an AWS S3 bucket as a file named {{ Customer Name }}.png. Credentials for the S3 bucket, the S3 bucket's name, and the AWS region the bucket lives in are not unique to the customers, but might change in the future, so setting them as config variables (rather than hard-coding them in integration steps) is prudent - that way they only need to be changed in one place.

This example integration is contrived, but illustrates how data flows through an integration, and how config variables and credentials can be used to drive an integration.

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. Then, create an AWS IAM user with the below IAM policy; note the user's programmatic access_key_id and secret_access_key - you'll provide those credentials to this integration.

{
"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 credential keypair for you.

Create Your Integration#

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 Integration Config Variables#

This integration requires five variables: Customer Name, Pokemon Avatar, S3 Bucket Name, AWS S3 Region, and S3 Bucket Credentials. Select the Config Variables button and add those five config variables. Make sure the first four are strings, and the last one is a credential. Specify that the credential is of type API Key / Secret by clicking the pencil icon.

Since the S3 bucket, region and credentials are going to be global for all customers, you can set default values for those config variables.

To add the credential config var, you will need to click the + Credential button, and add a credential of type API Key / Secret, entering your AWS key pair that you generated in the prerequisite section.

Your screen should look something like this - I added headers to organize the config variables:

Set Config Variables for Testing#

Now that you have set integration config variables, click the TEST RUNNER drawer on the left-hand sidebar and open the Configuration tab. Fill in testing values for Customer Name and Pokemon Name config variables.

Actions 1 and 2 - Combine some strings#

This integration will need to generate two strings:

  1. A URL to pull pokemon data from (like https://pokeapi.co/api/v2/pokemon/pikachu)
  2. A filename for saving an avatar file to S3 (like Mars Missions Corp.png)

Both of those are strings that are some combination of a config variable and some additional text, so Text Manipulation - Join actions are appropriate here.

For the first Text Manipulation - Join action, we need to combine https://pokeapi.co/api/v2/pokemon/ with the Pokemon Name config variable. Let's add that action, name it Create Pokemon URL, and enter that static string and config variable reference for the action's input:

Next, add a second Text Manipulation - Join action named Create Customer PNG Filename, and combine the Customer Name config variable with the string .png:

If we click SAVE & RUN TEST we can see that the strings are being generated appropriately:

Action 3 - Pull Pokemon info#

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

Under the URL input field, choose to reference output from the Create Pokemon URL step.

Keep the Response Type as json.

If we run a test now, we can see that this step pulls down some data about the Pokemon we've configured:

Action 4 - Download the Pokemon avatar#

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

For the URL input, choose to reference part of the output from the Get Pokemon Data step. The previous step's results included some sprite (image) information about our pokemon. In the Reference Search field for the URL input, enter results.sprites.front_default. This will use results from the previous action to determine where the Pokemon's avatar is located.

Enter binary as your Response Type, so the action knows that it is pulling down binary data.

If we run a test now, we can see that the pokemon's avatar is downloaded properly:

Action 5 - Save the PNG to S3#

Finally, let's save that file to our AWS S3 bucket. Add an S3 - Put an Object action.

Bind the AWS Region input for this step to your config variable for AWS Region. Same for Bucket Name and your bucket config variable.

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

For the Object Key (file name) input, we'll use an results from the Create Customer PNG Filename action (the one that combined customer name with ".png").

Object Tags are not required for this example.

For Step Credential, select the credential config variable you created. Your inputs should look something like this:

Test Your Integration#

Click SAVE & RUN TEST once more. 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 into the VERSION HISTORY drawer on the left side of the integration designer and click SAVE & PUBLISH.

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 Integration Configuration pane, enter values for Customer Name and Pokemon Name. You can keep the other config variables as their defaults.

Test Your Instance#

Open the Test tab and click RUN TEST.

Open the Executions tab and verify that the test execution ran successfully. Then, open up S3 to see that a Pokemon avatar was saved correctly to your S3 bucket: