Workday Adaptive Planning provides several ways to integrate data with external systems.
Three commonly discussed integration patterns are:
Custom Cloud Loader
Data Agent
Adaptive Planning API
They are not interchangeable.
Each solves a different integration problem.
The correct architecture depends on where the data lives, which system should control the process, what network boundaries exist, and what level of data detail is required.
A useful design starts with five questions:
- Where does the source data live?
- Is the integration inbound or outbound?
- Is the source or destination accessible from the cloud?
- Should Adaptive Planning or an external platform control the process?
- What grain of data must be preserved?
What is an Adaptive Planning Custom Cloud Loader?
A Custom Cloud Loader is an Adaptive Planning integration component used to send data from an Adaptive Planning staging table to an external system.
The loader uses JavaScript and Adaptive Planning scripting capabilities.
A typical pattern is:
Adaptive Planning staging
to
Custom Cloud Loader
to
SFTP or external cloud system
The important point is that the required data is already available inside Adaptive Planning.
Adaptive Planning then owns the outbound process.
When should you use a Custom Cloud Loader?
A Custom Cloud Loader is a strong option when:
- The required data already exists in Adaptive Planning staging
- The integration is primarily outbound
- Adaptive Planning should own the process
- The destination can be reached from Adaptive Planning
- The target accepts files or supported cloud communication
- SFTP delivery is required
- Additional middleware would add unnecessary complexity
For example, assume Adaptive Planning staging already contains:
Journal Line ID
Accounting Date
Company
Ledger Account
Currency
Amount
Journal Source
Book
Required Worktags
An external reconciliation system requires a CSV file through SFTP.
A practical design is:
Workday Financial Management
to
Adaptive Planning Data Source
to
Adaptive staging
to
Custom Cloud Loader
to
SFTP
to
reconciliation platform
There may be no need to introduce another integration server only to create and transfer the file.
Keep Custom Cloud Loader logic simple
The presence of JavaScript does not mean financial business logic should automatically be written into the script.
Where practical, the Custom Cloud Loader should remain a transport layer.
For example:
Staging should determine which records are included.
Staging should determine account mappings.
Staging should determine known exclusions.
Staging should expose calculated fields needed by the destination.
The Custom Cloud Loader should mainly handle:
Reading the staging data
Creating the required file or payload
Formatting the output
Connecting to the destination
Sending the data
Logging the result
This separation makes reconciliation and support easier.
A support team should not need to read JavaScript to understand why an accounting record was included or excluded.
Preserving transaction level detail
One important reason to use a staging based outbound architecture is data grain.
Suppose Adaptive Planning receives journal line data from Workday.
The journal line contains a unique source identifier.
The data is later mapped and loaded into Planning accounts.
The Planning model may aggregate those transactions into account, level, period and dimension intersections.
An external reconciliation system may still require the original journal line identifier.
In that situation, the staging layer may be the correct outbound source because it still contains the detailed source record.
The key architectural question is:
Does the receiving system need Planning values?
Or does it need source transaction detail?
Those are different requirements.
What is the Adaptive Planning Data Agent?
The Data Agent solves a different problem.
The Data Agent runs within customer managed infrastructure and allows Adaptive Planning to communicate with data sources that are not directly accessible from the cloud.
A common architecture is:
On premises database
to
Adaptive Planning Data Agent
to
Adaptive Planning
The Data Agent is particularly relevant when the source system sits behind the organization’s firewall.
When should you use the Data Agent?
Consider the Data Agent when Adaptive Planning must access systems such as:
- On premises Oracle databases
- Microsoft SQL Server databases
- Internal finance databases
- Legacy applications
- Custom systems inside a corporate network
- Scripted sources that must execute inside the customer environment
The primary reason for introducing the Data Agent should normally be connectivity.
If Adaptive Planning cannot directly reach the source system because of the network boundary, the Data Agent provides the bridge.
Data Agent requires infrastructure
The Data Agent provides useful connectivity, but it also introduces infrastructure that must be supported.
The organization needs to consider:
Windows infrastructure
Agent installation
Network access
Firewall configuration
Service availability
Credentials
Software maintenance
Monitoring
Agent upgrades
Support ownership
This does not make Data Agent a poor solution.
It simply means it should be introduced when the architecture requires it.
If the source is already available through a cloud API or another direct integration mechanism, adding an on premises agent may create unnecessary operational complexity.
What is the Adaptive Planning API?
Adaptive Planning also provides APIs that allow external applications to communicate programmatically with Adaptive Planning.
This creates a different control model.
With a Custom Cloud Loader:
Adaptive Planning initiates the integration.
With an API based architecture:
An external application initiates the interaction with Adaptive Planning.
A typical architecture might be:
Azure integration service
to
Adaptive Planning API
or
Enterprise integration platform
to
Adaptive Planning API
The external platform can control:
Authentication
Scheduling
Transformation
Logging
Retries
Monitoring
Alerts
Dependencies
Integration with other systems
This pattern becomes useful when Adaptive Planning is one component in a larger enterprise workflow.
When should you use the Adaptive Planning API?
API based integration is a strong option when:
- An external application should control the process
- Adaptive Planning participates in a larger workflow
- Centralized monitoring is required
- The organization already has an integration platform
- Multiple systems need to be coordinated
- External applications need Adaptive Planning data
- External applications need to update Adaptive Planning
- Enterprise retry and error handling should live outside Adaptive Planning
For example:
Workday
to
enterprise integration platform
to
Adaptive Planning
to
data warehouse
to
reporting platform
An external orchestration layer may be more appropriate because the process extends beyond Adaptive Planning.
Adaptive Planning API data export
Adaptive Planning provides data export capabilities that can return Planning model data based on specified filters.
Filtering can include areas such as:
Accounts
Levels
Dimensions
Versions
Time periods
This can be useful when another application needs Planning values.
However, the required grain must be understood.
Planning model data is not necessarily the same as source staging data.
Planning data and staging data are different
This distinction is critical.
Consider this example.
A Workday source contains 100,000 journal lines.
Those journal lines enter Adaptive Planning staging.
The Planning Data Loader aggregates and loads the data into:
Account
Level
Period
Dimension
The resulting Planning model may contain far fewer intersections than the original 100,000 source records.
If another system later requires every original Journal Line ID, exporting Planning model values may not provide the required information.
The staging layer may be the correct source instead.
The architecture should therefore ask:
What data does the receiving system actually need?
Not:
Which Adaptive export technology is easiest to use?
Do not automatically choose an API
APIs are useful, but API based does not automatically mean better architecture.
Consider a simple requirement:
Adaptive Planning already contains the required staging data.
A monthly CSV must be generated.
The file must be sent to SFTP.
There are no other systems involved in the workflow.
One option would be:
External middleware
calls Adaptive API
extracts data
creates CSV
connects to SFTP
uploads file
This architecture introduces:
Another application
Another authentication layer
External hosting
External scheduling
Additional monitoring
Additional credentials
More failure points
If Adaptive Planning can already perform the required outbound process through a Custom Cloud Loader, the additional infrastructure may provide little value.
The simplest architecture that satisfies the requirement is often the better architecture.
When external orchestration is better
There are also situations where external orchestration is clearly more appropriate.
Consider a process that must:
Extract Adaptive Planning data
Extract Workday data
Retrieve information from another SaaS application
Transform all three datasets
Store the result in a data lake
Trigger another process
Create centralized logs
Retry failed integrations
Send operational alerts
This process extends well beyond Adaptive Planning.
Adaptive Planning should not necessarily become the orchestration platform for the entire workflow.
An enterprise integration platform can own the process while Adaptive Planning acts as one endpoint.
Custom Cloud Loader vs Data Agent
The main difference is the integration boundary.
Use Custom Cloud Loader when:
The data is already inside Adaptive Planning and needs to move outward.
Use Data Agent when:
Adaptive Planning needs to reach a source behind the customer network.
For example:
Adaptive staging to SFTP
Use Custom Cloud Loader.
Internal SQL database to Adaptive Planning
Consider Data Agent.
These technologies solve different problems.
Custom Cloud Loader vs API
The key difference is process ownership.
Custom Cloud Loader:
Adaptive Planning initiates the outbound process.
API:
An external application communicates with Adaptive Planning.
Choose Custom Cloud Loader when Adaptive Planning should own a contained outbound process.
Choose an API architecture when an external integration platform should own the broader workflow.
Data Agent vs API
The Data Agent primarily solves private network connectivity.
The API primarily provides programmatic access to Adaptive Planning.
Both can exist in the same enterprise architecture.
For example:
Internal database
to
Data Agent
to
Adaptive Planning
and separately:
External integration application
to
Adaptive Planning API
There is no requirement to select one integration technology for the entire organization.
Use the appropriate pattern for each interface.
A simple decision framework
Is the source behind the customer firewall?
If yes, evaluate Data Agent or another approved on premises connectivity pattern.
Is the required outbound data already available in Adaptive staging?
If yes, evaluate Custom Cloud Loader.
Should an external application own the workflow?
If yes, evaluate the Adaptive Planning API.
Is the requirement mainly SFTP file delivery?
If Adaptive Planning already contains the required staging data, Custom Cloud Loader may provide the simpler architecture.
Does the workflow involve many enterprise applications?
If yes, external orchestration may provide better operational control.
What data grain is required?
Determine whether the destination requires:
Planning model values
or
Source and staging level detail
This can completely change the correct architecture.
Integration pattern by use case
| Requirement | Starting Pattern |
|---|---|
| Adaptive staging data to SFTP | Custom Cloud Loader |
| Adaptive staging data to external cloud application | Custom Cloud Loader |
| JavaScript based outbound processing | Custom Cloud Loader |
| File based outbound integration | Custom Cloud Loader |
| On premises database to Adaptive Planning | Data Agent |
| Network restricted internal application | Data Agent |
| External application reading Adaptive Planning data | API |
| External application updating Adaptive Planning | API |
| Enterprise middleware orchestrating multiple systems | API |
| Centralized external monitoring and retries | API |
| Detailed staging records required externally | Staging plus Custom Cloud Loader |
| Planning account values required externally | API or appropriate Planning export |
This should be treated as a starting framework.
Security, data volume, licensing, operational ownership and enterprise architecture standards also need to be considered.
Authentication is part of the architecture
Integration security should be designed at the beginning.
The architecture should answer:
Which identity runs the process?
Is it a service identity?
Where are credentials stored?
Who owns the credentials?
How are credentials rotated?
What permissions does the integration require?
Can the process operate without a named employee account?
How are authentication failures detected?
How is production access separated from development access?
These questions apply whether the architecture uses Data Agent, API or Custom Cloud Loader.
Authentication should not be treated as a final deployment task.
Keep business logic separate from transport
This principle applies to every integration pattern.
Consider rules such as:
Account exclusion
Company filtering
Journal status
Sign treatment
Cost center mapping
Book filtering
Currency treatment
These are financial or integration rules.
SFTP is transport.
An API request is transport.
A JavaScript upload function is transport.
Where practical, business rules should be visible in controlled source, staging or mapping layers.
The support team should be able to answer:
Why was this record included?
Why was this record excluded?
Which account did it map to?
Which level did it map to?
Why did the amount change?
without reverse engineering the transport code.
Reconciliation is required regardless of technology
Selecting the right integration technology does not remove the need for financial controls.
For a Custom Cloud Loader process, validate:
Source staging row count
Eligible row count
Outbound row count
File row count
Amount totals
Successful SFTP delivery
Destination ingestion
For a Data Agent process, validate:
Source database population
Extracted population
Adaptive staging population
Loader output
Planning result
For an API process, validate:
Request scope
Response population
Returned amounts
Transformation logic
Destination result
Retry behavior
Duplicate handling
Every interface should have a clear reconciliation point.
Design for failure
A production integration architecture should define what happens when something goes wrong.
Examples include:
SFTP unavailable
Authentication failure
API timeout
Data Agent service unavailable
Partial file generation
Invalid destination credentials
Duplicate execution
Source system unavailable
Mapping failure
Destination rejection
Network interruption
The design should define:
Retry behavior
Logging
Alerting
Recovery
Replay
Duplicate prevention
Support ownership
A successful test run does not prove that the integration is production ready.
Failure handling is part of the production architecture.
Do not select technology based only on development speed
A quick solution can become a long term operational dependency.
The architecture should consider:
Security
Support ownership
Monitoring
Auditability
Data volume
Network design
Reconciliation
Developer skills
Infrastructure
Upgrade impact
Error handling
Long term maintenance
A proof of concept can demonstrate technical feasibility.
Production architecture must also demonstrate operational sustainability.
Example: Adaptive Planning to external reconciliation platform
Consider a requirement where an organization needs to reconcile Workday actuals against the actuals received by Adaptive Planning.
Adaptive staging already contains detailed journal information.
The reconciliation platform needs:
Journal Line ID
Transaction reference
Accounting Date
Period
Company
Ledger Account
Currency
Amount
Journal Source
Book
Selected Worktags
The platform expects a CSV file through SFTP.
Three options might initially be considered.
Option 1. Custom Cloud Loader
Adaptive staging
to
Custom Cloud Loader
to
SFTP
to
reconciliation platform
Advantages:
Data already exists in staging.
Detailed journal grain can be preserved.
Adaptive owns the outbound process.
No separate orchestration platform is required solely for file delivery.
Option 2. External orchestration using API
External integration platform
to
Adaptive Planning
to
file generation
to
SFTP
This may be appropriate if the enterprise already centralizes integrations and monitoring externally.
However, the architect must confirm that the API exposes the exact grain required by the reconciliation process.
If detailed journal identifiers exist only in staging and not in the Planning model, a Planning model export may not satisfy the requirement.
Option 3. Data Agent
Data Agent would normally be considered only if there is a network or on premises connectivity requirement.
If the required information is already inside Adaptive Planning and the destination is externally accessible, introducing Data Agent does not solve a necessary architectural problem.
For this type of requirement, the decision is primarily between an Adaptive owned outbound design and an externally orchestrated design.
Recommended architecture principles
Use Custom Cloud Loader for contained outbound integrations
This is particularly suitable when the required data already exists in Adaptive Planning staging.
Use Data Agent to solve network connectivity requirements
Do not introduce customer managed agent infrastructure unless the source or network boundary requires it.
Use API based integration when orchestration belongs outside Adaptive Planning
This is useful when Adaptive Planning participates in a wider enterprise workflow.
Preserve the required data grain
Planning data and staging data should not be assumed to be interchangeable.
Keep transport code simple
Financial rules should remain visible and governed whenever possible.
Design service identities intentionally
Authentication and authorization are part of the integration architecture.
Reconcile every interface
Technical success does not prove financial correctness.
Design failure handling before production
Retries, replay, alerting and duplicate prevention should be deliberate.
Frequently Asked Questions
What is an Adaptive Planning Custom Cloud Loader?
A Custom Cloud Loader is an Adaptive Planning integration component that uses JavaScript and Adaptive Planning scripting capabilities to send staging data to an external system.
When should I use a Custom Cloud Loader?
Consider it when the required outbound data already exists in Adaptive Planning staging and Adaptive Planning should control delivery to an external system.
Can Custom Cloud Loader be used for SFTP?
Adaptive Planning provides SFTP capabilities that can be used within supported custom cloud integration patterns.
What is the Adaptive Planning Data Agent?
The Data Agent runs on customer managed infrastructure and enables Adaptive Planning to communicate with supported sources that are accessible from within the customer network.
When is Data Agent appropriate?
It is particularly relevant for on premises databases and other sources that Adaptive Planning cannot directly access from the cloud.
What is the Adaptive Planning API used for?
The API allows external applications to interact programmatically with Adaptive Planning, including supported metadata and data operations.
Should I always use the API for enterprise integrations?
No.
Use an API architecture when external orchestration provides a real benefit.
If Adaptive already contains the required staging data and only needs to send a controlled file to SFTP, a Custom Cloud Loader may be simpler.
Can Custom Cloud Loader, Data Agent and API coexist?
Yes.
Different interfaces can use different integration technologies within the same Adaptive Planning environment.
Should Planning data be used for transaction level reconciliation?
Only if the Planning model preserves the required transaction level detail.
If the reconciliation key exists only in staging, the staging layer may be the appropriate source.
Conclusion
Custom Cloud Loader, Data Agent and API based integration solve different Workday Adaptive Planning integration problems.
The decision can usually be reduced to three questions:
Where does the data live?
Who should control the integration?
What network boundary must be crossed?
If the required information already exists in Adaptive Planning staging and needs to be delivered externally, evaluate Custom Cloud Loader.
If Adaptive Planning must reach an internal source behind the customer network, evaluate Data Agent.
If an external application or enterprise integration platform should control the workflow, evaluate the Adaptive Planning API.
Do not select the integration technology first and force the requirement into it.
Define the source, target, data grain, security model, reconciliation requirements, operational ownership and failure handling first.
Then choose the simplest integration pattern that satisfies those requirements.
About EPMLogic
EPMLogic specializes in Workday Adaptive Planning architecture, implementation, integration and optimization.
Our integration approach starts with data grain, system ownership, reconciliation, security and operational support before selecting the technology used to move the data.