CloudWorks—This is How We Use It, Part 3: The CloudWorks API
In Part 3 of our CloudWorks - This is How We Use It series, we will introduce you to the CloudWorks API.
This blog post is typically for an audience comfortable with REST APIs concepts and programming.
If you need a refresher on What CloudWorks is, see Part 1, or on How to set it up, see Part 2.
CloudWorks API will allow you to create & execute connections and integrations extending integration automation capabilities between Amazon AWS S3 & Anaplan.
We will use a typical CloudWorks workflow to build and run integrations using REST API & Postman. To follow along, download the set of Jupyter Notebooks and data set that will walk you through each step of this workflow using Python (CloudWorksAPIBasic.zip and AccountDetailsS3.zip).
The following are minimum requirements to be able to perform the steps described in this blog.
Anaplan: Create a Model, LIST (Accounts), Module (AccountDetails), Import AccountDetailsS3.csv into LIST (Create Import Action), Import AccountDetailsS3.csv into Module (Create Import Action).
AWS S3: AWS Account, Create Access Key, Secret Access Key, Create a bucket, upload Source File (AccountDetailsS3.csv) to S3 Bucket.
Working knowledge of Anaplan Model Building Concepts, REST API, Postman, Python, Jupyter.
Familiarity with Anaplan Authentication & Integration REST APIs.
Step 1 - Anaplan Setup
Download AccountDetailsS3.csv from this blog and save it to your workstation.
Create a new Anaplan Model. Provide an appropriate model name.
Create LIST named Accounts. Import AccountID into this LIST from AccountDetailsS3.csv.
Create a Module named AccountDetails with Accounts as a dimension.
Create the following line items:
AccountName (Text), Industry (Text), AnnualRevenue (Number), EmployeeCount (Number)
Import AccountDetailsS3.csv into AccountDetails Module.
Import Action Name for LIST (Accounts): ______________________
Import Action Name for Module (AccountDetails): __________________________
Step 2 - AWS Setup
Assumptions: AWS Access Key & Secret Access Key have been generated in AWS Console.
Create an S3 bucket named anaplandemo.
Create a folder named source.
Upload AccountDetailS3.csv to anaplandemo/source in AWS S3.
Step 3 - Postman Setup
Create a collection named CloudWorks.
Create following folder structure in collection CloudWorks.
We will use variables in API requests. Create the following variables in collection CloudWorks.
Now that we have completed the required prep-work in Anaplan, AWS S3 & Postman, we will make CloudWorks API requests to build and execute integrations to load data from AWS S3 to Anaplan. We will follow steps outlined in a typical CloudWorks task, outlined below, to build this integration. CloudWorks REST API requests will be made using Postman.
Step 4 - CloudWorks API
Each Anaplan API request begins with generating an Authentication Token using Anaplan Authentication Services REST API. Generated Auth Token is then passed in the header of CloudWorks API request for Anaplan authentication. Keep in mind, Anaplan Authtoken is valid for only 30 min. Once expired, you will need to regenerate the token and update CloudWorks API header.
We will perform the following tasks in Postman to bring AWS S3 data to Anaplan.
Create a connection: Using AWS S3 connector, we will create a CloudWorks connection to AWS S3 Bucket.
Create an integration: Using AWS connection and Anaplan information (workspaceid, modelid, fileid, import action id), we will create a CloudWorks integration.
Run an integration: Run integration using CloudWorks API.
Retrieve Integration Information: Get integration run information.
The first step in any Anaplan API request, including CloudWorks, is generating Anaplan Authentication Token. The authentication token can be generated using Anaplan Authentication Services API. URL for authentication services is https://auth.anaplan.com/token/authentication.
Authentication Services API to generate token has the following REST structure:
Authorization: Basic username:password (username:password string must be base64 encoded)
Copy value for tokenValue to collection variable token_value. You will use variables instead of hard coding values in your API requests. Token values expire every 30 minutes. You will need to re-generate a token and update the token_value value variable if you encounter authentication failures.
Create a Connection Using CloudWorks API
The first step in building a CloudWorks integration is to create a connection to AWS S3 bucket. Passing AuthToken in the header of API request, we will create a connection to AWS S3 bucket in this step. Create connection API has the following REST structure.
Select “NoAuth” for Authorization Type. We will pass the authentication token in the header of the request.
Create the following headers: Authorization and Content-Type.
Copy and paste the following JSON structure into the Body of your request. Replace values for accessKeyId, secretAccessKey, and bucketName with your values.
Once the API request is submitted, the service should return a successful response back with HTTP code 200 and a value for connection id. You will save this connection id, to be used in the next API request in creating a CloudWorks integration. Copy the value for connectionId in a notepad and update it for collection variable connection_id.
Log into Anaplan CloudWorks. You should see the connection you created under Connections.
Create an Integration Using CloudWorks API
In this second step, we will create a CloudWorks integration. In the integration, we will provide connectivity information for both AWS S3 and Anaplan. Two types of integrations can be built:
AWS S3 (Source) Anaplan (Target): Data from a file on AWS S3 is selected as a source and Anaplan Import Action as a target.
Anaplan (Source) AWS S3: Data from Anaplan is exported using Export Action (Source) and written to a file on AWS S3 Bucket (Target).
Create integration API has the following REST structure:
Create the following headers: Authorization and Content-Type
Copy and paste the following JSON structure into the Body of your request. Replace values for connectionId, file, actionId, fileId, workspaceId, and modelId. You may obtain values for your import action (actionId) and Data Source File (fileId) using Anaplan Integration API. Details on Integration APIs can be found on Anapedia. You can obtain values for workspaceId & modeled from Anaplan UX.
Once the API request is submitted, the service should return a successful response back with HTTP code 200 and a value for integration id. Copy & paste value for integrationId to collection variable s3_anaplan_int_id. We will use integrationId in a later step when we gather run details for an integration.
Log into Anaplan CloudWorks. You should see the integration you created under Integrations.
Run an Integration Using CloudWorks API
Now that we have created an integration, we will run the integration that loads data from a file on AWS S3 bucket to an Anaplan module. Once the integration is run, we will retrieve a history of integration runs and its details. We will do this in the next step. CloudWorks APIs can be used to schedule integrations. However, in this blog, we will focus on executing integrations via API.
You will need to provide the following details in your API request:
The content in this article has not been evaluated for all Anaplan implementations and may not be recommended for your specific situation.
Please consult your internal administrators prior to applying any of the ideas or steps in this article.