CloudWorks—This is how we use it, Part 3: The CloudWorks API

AnaplanOEG
AnaplanOEG
edited January 2023 in Best Practices

In Part 3 of our CloudWorks - This is how we use it series, we will introduce you to the CloudWorks API. 

This 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, for how to set it up, see Part 2.

CloudWorks API will allow you to create and execute connections and integrations extending integration automation capabilities between Amazon AWS S3 and Anaplan. 

We will use a typical CloudWorks workflow to build and run integrations using REST API and 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.

  • Required software
    • Download and install Postman (https://www.postman.com/downloads), Python 3.8.2, Jupyter notebook
    • 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 and 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

annejulie_0-1612895606746.png 

  • We will use variables in API requests. Create the following variables in collection CloudWorks.

annejulie_1-1612895606759.png

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. 

pmarpaka_0-1612922304066.png

 

Generate Authentication Token (Basic Authentication)

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:

Method

POST

API end point

https://auth.anaplan.com/token/authenticate

Headers

Authorization: Basic username:password (username:password string must be base64 encoded)

annejulie_3-1612895606771.png

annejulie_4-1612895606790.png

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.

annejulie_5-1612895606793.png

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.

Method

POST

API end point

https://api.cloudworks.anaplan.com/1/0/integrations/connection

Authorization

No Auth

Headers

Authorization: AnaplanAuthToken {{token_value}}
Content-Type: application/json

Body

{

    "type": "AmazonS3",

    "body": {

        "name":"AWS_CW_API",

        "accessKeyId":"XXXXXXXXXXXXXXXX",

        "secretAccessKey":"XXXXXXXXXXXXXXXXXXXXXXX",

        "bucketName":"anaplandemo"

    }

}

 

Do not change the value for “type”.

Provide name for following elements:  name, accessKeyId, secretAccessKey, & bucketName

 

annejulie_6-1612895606795.png

  • Select “NoAuth” for Authorization Type. We will pass the authentication token in the header of the request.

annejulie_7-1612895606797.png

  • Create the following headers: Authorization and Content-Type.

annejulie_8-1612895606800.png

  • Copy and paste the following JSON structure into the Body of your request. Replace values for accessKeyId, secretAccessKey, and bucketName with your values.

{

    "type": "AmazonS3",

    "body": {

        "name":"AWS_CW_API",

        "accessKeyId":"XXXXXXXXXXXXXXXX",

        "secretAccessKey":"XXXXXXXXXXXXXXXXXXXXXXX",

        "bucketName":"anaplandemo"

    }

}

 

annejulie_9-1612895606805.png

  • 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.

annejulie_10-1612895606810.png

  • Log into Anaplan CloudWorks. You should see the connection you created under Connections.

annejulie_11-1612895606815.png

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:

Method

POST

API end point

https://api.cloudworks.anaplan.com/1/0/integrations

Authorization

No Auth

Headers

Authorization: AnaplanAuthToken {{token_value}}
Content-Type: application/json

Body

{

    "name": "CWAPI_AWSS3_Anaplan",

    "jobs": [

        {

            "type": "AmazonS3ToAnaplan",

            "sources": [

                {

                    "type": "AmazonS3",

                    "connectionId": "a2fb43a9-3bc8-4bcb-9f37-dd59a75eb940",

                    "file": "source/AccountsS3.csv"

                }

            ],

            "targets": [

                {

                    "type": "Anaplan",

                    "actionId": "112000000005",

                    "fileId": "113000000000",

                    "workspaceId": "8a81b09d5e8c6f27015ece3402487d33",

                    "modelId": "35A6EF893D7F47EEA5A554D5CC7DC330"

                }

            ]

        }

    ]

}

 

Do not change the value for “type”: “AmazonS3ToAnaplan”, “type”:”AmazonS3”, “type”:”Anaplan”

Provide values for following elements:  connectionId, actionId, fileId, workspaceId, modelId.

 

annejulie_12-1612895606819.png

  • Create the following headers: Authorization and Content-Type

annejulie_13-1612895606823.png

  • 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.

{

    "name": "CWAPI_AWSS3_Anaplan",

    "jobs": [

        {

            "type": "AmazonS3ToAnaplan",

            "sources": [

                {

                    "type": "AmazonS3",

                    "connectionId": "a2fb43a9-3bc8-4bcb-9f37-dd59a75eb940",

                    "file": "source/AccountsS3.csv"

                }

            ],

            "targets": [

                {

                    "type": "Anaplan",

                    "actionId": "112000000005",

                    "fileId": "113000000000",

                    "workspaceId": "8a81b09d5e8c6f27015ece3402487d33",

                    "modelId": "35A6EF893D7F47EEA5A554D5CC7DC330"

                }

            ]

        }

    ]

}

 

annejulie_14-1612895606832.png

  • 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.

annejulie_15-1612895606836.png

annejulie_16-1612895606837.png

  • Log into Anaplan CloudWorks. You should see the integration you created under Integrations.

annejulie_17-1612895606842.png

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:

 

Method

POST

API end point

https://api.cloudworks.anaplan.com/1/0/integrations/<integration_id>/run

Authorization

No Auth

Headers

Authorization: AnaplanAuthToken {{token_value}}
Content-Type: application/json

Body

None

 

annejulie_18-1612895606845.png

  • Create the following headers: Authorization and Content-Type

annejulie_19-1612895606848.png

  • Once the API request is submitted, the service should return a successful response back with HTTP code 200.

annejulie_20-1612895606853.png

  • View integration run status & details in Anaplan CloudWorks UX.

annejulie_21-1612895606858.png

  • If an integration run fails, you will also be notified via email.

annejulie_22-1612895606864.png

Get history of integration runs

 CloudWorks API provides end points to get details on integration run history. REST structure for this end point is:

 

Method

GET

API end point

https://api.cloudworks.anaplan.com/1/0/integrations/runs/<integrationId>

Parameters

Offset = 0
limit = 2

Authorization

No Auth

Headers

Authorization: AnaplanAuthToken {{token_value}}
Content-Type: application/json

Body

None

annejulie_23-1612895606865.png

  • Create two parameters offset & limit. Set their values to 0 & 2 respectively.

annejulie_24-1612895606868.png

  • Create the following headers: Authorization and Content-Type

annejulie_25-1612895606871.png

  • The service request should return a successful response back with HTTP code 200 and details for each run for selected integration.

annejulie_26-1612895606889.png

Contributing authors: Pavan Marpaka, Scott Smith, and Christophe Keomanivong.

Tagged:

Comments

  • JaredDolich
    JaredDolich

    @annejulie Brilliant. Thank you.

  • parteekkansal
    parteekkansal

    I am uploading data to S3 from Anaplan. However, my S3 bucket is KMS encrypted and I need to specify the encryption header as follows when I make an API request to S3 to upload the data.

    "ServerSideEncryption": "aws:kms"

     

    How do I specify this?

Categories