Skip to main content

Configuration-Driven Integration

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 Amazon 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 and category. Select "Webhook" for your trigger type.

Create Integration Config Variables#

This integration requires five variables: Customer Name, Pokemon Avatar, S3 Bucket Name, AWS Region, and AWS Connection. Select the Config Variables button and add those five config variables. Make sure the first four are strings, and the last one is a connection. Specify that the connection is of type "AWS API Key and Secret" from the AWS S3 component.

Since the S3 bucket, region and connection are going to be global for all customers, you can set default values for those config variables. You can find values for all three config variables from the bucket/key pair you created in the prerequisite section.

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

Pokemon Avatar Sync config variables in Prismatic integration designer
note

If we were to add this integration to the integration marketplace, where customers can self-deploy, we would make the AWS config variables non-customer-deployable, so customers don't see our AWS keys.

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.

Test Pokemon config variables in Prismatic integration designer

Action 1 - Pull Pokemon info#

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

Under the URL input field, choose the Expression tab and create an expression that combines the string https://pokeapi.co/api/v2/pokemon/ with the Pokemon Name config variable.

Keep the Response Type as json.

Configure Pokemon HTTP GET request in Prismatic integration designer

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

HTTP Get Request step outputs in Prismatic integration designer

Action 2 - 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.

Get Pokemon Avatar in Prismatic integration designer

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:

Pokemon Avatar step results in Prismatic integration designer

Action 3 - Save the PNG to S3#

Finally, let's save that file to our Amazon S3 bucket. Add an S3 - Put 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 Expression made up of the customer name config variable and the string .png.

Object Tags are not required for this example.

Your configuration will look something like this:

Configure Pokemon avatar save in Prismatic integration designer

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:

Test Pokemon Avatar Sync in Prismatic integration designer

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.

Deploy Pokemon Avatar Sync instance to customer in Prismatic integration designer

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:

Test Pokemon Avatar Sync instance in Prismatic integration designer