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 "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
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 "FTL Rockets" and optional description.
- Repeat the customer addition process for a new customer, "Mars Mission Corp".
- 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 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
HTTP - GET Request action.
"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
Action 2 - Download the Pokemon Avatar PNG
HTTP - GET Request action.
outputs.httpget.all.sprites.front_default as your URL while in "JSONata Mode".
You can toggle to JSONata mode by clicking the icon.
binary as your Response Type.
This will use the previous HTTP - GET action's outputs as input.
Action 3 - Save the PNG to S3
S3 - Put an Object action.
Enter the AWS Region that matches where you created your bucket.
=configVars.bucketName as your Bucket Name in simple mode.
=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.
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.