Adaptive's API

To integrate data in Workday Adaptive Planning, customers typically use the integration module to connect with ERPs, SFTPs, AWS S3, Snowflake, SalesForce, Excel, and Google Sheets, etc. 

You can also use third party platforms such as Tray.ai, Boomi, Matilion etc. which leverage Adaptive's APIs in a user friendly setup. 

And lastly, you can write your very own scripts (C#, Python, Powershell...) to make these API calls. 


Most  common Adaptive's API use cases

  • Import Data from ERPs
    • Actual summaries and transaction details (by supplier, employee...)
    • Assets, amortization, depreciation
    • Payroll details and taxes
  • Import Sales data from CRMs or datalakes
    • Pipeline, churn, opportunities and customers 
    • Billings, bookings, revenue, ARR
  • Import Headcount data from an HRIS
    • Current headcount and terminations
    • Hired, not started
    • Wages and compensation plans
    • Benefits and other demographics
  • Import Other data:
    • Exchange Rates
    • Weather
    • Meta data: currencies, attributes, dimensions such as customers, suppliers, regions...
  • You can also export data from Adaptive (actuals and forecast, metrics, metadata...), to:
    • PowerBI
    • Tableau
    • Snowflake
    • Hyperion
    • For your own backups etc.

What can the API do and where is the documentation?

Adaptive's API touches 3 areas of its data:
  • Metadata: Get (read) and Edit (Create and Update)
    • GL accounts, Dimensions, Attributes, Time, Versions...
  • Data Fetch: retrieve sheets' content, including the metric and custom accounts / calculations
    • Example: P&L Forecast, Headcount, CAC, COA, ARR, Sales Commissions etc.
  • Data creation and update: push new or update content to Adaptive's sheets, data entry accounts
    • X Rates, add new levels etc.

API Updates    

As of December 2024, the current version is # 40 

Generally Workday updates their API when new releases are published (twice a year usually). Each version continues to be supported for at least 1 year after the release of the subsequent update.
To view the history of API Changes by Release, click here.

Security, Permissions and Call types

Adaptive's API is based on RESTful Web Services and proposes HTTP POST and GET methods.
And a small subset of the APIs also use JSON format with GET, POST, PUT, PATCH and DELETE HTTPS requests. More explanation on the JSON APIs below.

Security and Permissions

  • Single-action requests. User must be authenticated on each invocation (reducing risk of hijacking an existing web service session).
  • Requests are encrypted (using HTTPS)
  • Authentication credentials are transmitted within the body of the webservice request
  • Login and password are encrypted by the web layer before leaving the computer requesting it and decrypted by the target server.
  • There is no specific permission for a user to access webservices. That being said, the user making a request must have the required persmissions to actually perform the requested actions.
    • Eg.: if a user calls method importStandardData: the user must have import permission
  • The output of the request is also restricted to the user's levels and metadata access:
    • Eg.: if a user is calling method exportData: the returned data will only be for the levels and metadata (dimensions, attributes) assigned to this user.

💡Best Practice

Create a seperate integration user!

List of XML API Methods

Here is the list, extracted from Workday's website for the XML API:

Create, Update, and Read Methods for Metadata + data

Creations in Adaptive and Exports from Adaptive:
Pushes and updates to Adaptive:

Metadata in-bulk update methods via the upload of an XML file


Data submission methods

  • importConfigurableModelData: submits a set of rows for a modeled sheet
  • importCubeData: submits a set of data to be inserted into a cube sheet
  • importStandardData: submits a set of data to be inserted into standard accounts (GL accounts, assumptions, or custom accounts)
  • importTransactions: submits a set of transactions to be inserted into the transactions data, if the transactions feature has been enabled
  • eraseActuals: erases numeric data in specified time periods and accounts of an actuals version.
  • eraseData: erases numeric data from a plan or actuals version for the specified set of accounts for a given time frame
  • recalculateSheet: recalculates sheets with the Recalculate on Demand property.

Link to the official documentation:  HERE.


JSON APIs


Only a limited number of APIs use the JSON format to get or submit data.
More to come in future releases! (per their website).
More info and examples: click here.

JSON Request requirements

  1. HTTP Method: GET, POST, PUT, PATCH, DELETE
  2. URL Endpoint
    • By default, all Workday tenants use a US-based authentication service. If your tenant use another regional authentication, you can use your sign-in URL to determine your region.  Your auythorization URLs and API endpoints may vary!  Find more info on the login URLs by region here.

  3. Authorization header / authentication

1. HTTP Method (or verb)

Note that the method vary depending on the service and resources called.
  • GET: retrieves a collection or a single object
  • POST: creates a single data instance
  • PATCH: partially updates existing data
  • PUT: updates existing data and replaces existing data (with new data)
  • DELETE: Deletes an existing data instance

2. URL Endpoint

https://api.adaptiveplanning.com/rest/<service mame>/<version>/<tenant>/<resource path>

  • service name: A component name, based on functionality like modeling, security, or report.
  • version: The version of the service. Current version for all services: v1.
  • tenant: The tenant for this service, indicating the Adaptive Planning instance. Use default for the default instance of the user in the authorization.
  • resource path: The path to the resource, using nouns like sheet and availability. The path also supports query parameters, like:
    • sheetName to specify the name of a sheet in Adaptive Planning.
    • columnName to specify the name of a column in an Adaptive Planning sheet.
    • limit to specify the limit of object data entries included in a single response.
    • offset to specify the offset to the first object in a collection to include in the response.
Example:
https://api.adaptiveplanning.com/api/rest/modeling/v1/globosales/sheet/availability?sheetName=Expense Cube&columnName=Level&columnType=Level


3. Authorization header / authentication

All API invocations are single-action requests. User must be authenticated on each invocation (so a hacker can't attempt to hijack any existing web service session). Basically it does not create a persistent session for this user to make API calls.
The JSON formatted APIs support both Basic and Token Based Authentication (TBA). The authorization is indicated in the header of the request and not in the body like the XML APIs!



Basic Authentication
Basic authentication uses base64 encoded username and password in the authentication header.
Sample:
'Authorization': 'Basic <insert base64 encoded string>'
Example:
 
xyz@zzzzzzz.com:password
 
encodes to                             
eHl6QGRlbW8uY29tOnBhc3N3b3Jk

Token Based Authentication (TBA)
If you synchronize users from Workday to Adaptive Planning, you must use Token Based Authentication. To get your token, here are the steps from the official documentation: Make Adaptive Planning API Requests with Workday Credentials.  And you can also refer to my article about USER SYNC and API CALLS in Adaptive.
Once you got your token, pass it in the header.

Sample:
 'Authorization': 'Bearer <insert token here>'
Example:
 
'
Authorization: Bearer eyJjdHkiOiJ0ZXh0L3BsYWluIiwiYWxnIjoiSFMyNTYifQ.eyJsb2dpbl9pZCI6InN0ZXZlY0BheWdsb2JvLmNvbSIsIm5iZiI6MTU4NjEzMDA2NywibXVsdGlfdXNlIjoiMCIsImlzX2F1dGgiOiIxIiwiZXhwIjoxODg2MTMwMTg3LCJpYXQiOjE2MDM5NDYwMjEsImp0aSI6IjM0YzFkZDY2LTY2MTMtNDk0Ny05MjFhLTliZDQ2ZDVmZDkwNyJ9.FZnLHGQ3dNfpzvW-A9ILi53z6YLGNNI45Mlc-4NT3As'

Comments

Post a Comment

Popular posts from this blog

What is OAuth 2.0 and how to set it up in Adaptive?

Image
Uh Oh... OAuth? Was ist das? Adaptive can connect with other applications's via REST APIs using the OAuth 2.0 authentication.  I will explain what OAUTH is so you will no longer ask: "What is this?" (Was ist das?) and feel like someone is talking a foreign language to you!   What is OAUTH 2 really? How does it work and what do you need to do in Adaptive? Let me give you 2 sets of explanations: a real life illustration to demistify OAuth 2.0 and a more technical summary. And lastly high level steps on the setup in Adaptive. If you have no idea what OAUTH is, continue reading, otherwise jump to the 2nd section.  In this example: imagine you need to connect to Microsoft Sharepoint and you want to bring CSV files  into Adaptive. 1) Illustrational explanation for total newbs: OAuth Access vs Hotel Access! OAuth 2.0 can sound overwhelming at first, but it's essentially a way for applications to securely talk to each other and access data. Let me break it down into sim...
Read more

What are Metric accounts and when to use them?

Image
 I am often asked: "What are Metric accounts in Adaptive and what is their use case?" Before we jump into the weeds, you can create "global" metric accounts, called standard metric accounts  and within cube sheets.  To create a standard metric account, go to:  Menu > Modeling > Metric Accounts Adaptive will come with a couple of pre-built Metric accounts, such as Gross Margin % What are Metric Accounts? A metric account in Adaptive is a calculated account , meaning it carries a formula .  It does   not carry any data entry .  It can not be a rollup account,  meaning it can not have any "children accounts" rolling up to a parent. Metric accounts are typically used to calculate ratios , this is why they can only be either a number or a percent ! But... there is more subtility in them! Metric accounts are different from the other calculated accounts (custom, modeled, cube etc.) in the sense that their formula is also computed at the level an...
Read more