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
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
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
secret_access_key in the API Key and API Secret fields respectively.
- 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
pokemonAvatarconfiguration 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:
Select the Required Config Variables button and add those three required variables.
Provide a couple of testing values for
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 theicon 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:
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
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 theicon 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 themenu.
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
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 thebutton 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.