Workflow Public API

Workflow Public API

The Workflow Public API lets external systems and automations read and update workflow tasks. Credentials are per-tenant (request via DevOps or your development team); in the UI, right-click a task and choose Copy Reference ID to get the stable task identifier. For the Workflows module itself, start with Workflows: Plans & Tasks.

Public API

The Reference ID solves a key pain point with the existing Workflow Task ID: when a roll forward occurs, the Workflow Task ID changes, requiring anyone using the Public API to manually update their configurations. The Reference ID does not change on roll forward, allowing API integrations to remain stable without any maintenance after initial setup.

The Public API previously identified workflow tasks using a Workflow Task ID (also referred to as a Row ID). This ID is tied directly to the task record in the system.

When a roll forward occurs — moving the planning period from one month to the next — the Workflow Task ID updates. Any external system, script, or automation that references the old ID will no longer point to the correct task. The configuration must be manually updated every time a roll forward happens.

For teams that run roll forwards regularly, this creates a recurring maintenance burden and a risk of broken integrations if the update is missed or delayed.

A Reference ID has been added to every workflow task. Unlike the Workflow Task ID, the Reference ID:
  1. Remains the same across every roll forward.
  2. Can be used in place of the Workflow Task ID for all supported Public API calls.
  3. Is visible alongside the Row ID when you right-click a task in the workflow interface.

Once you configure your integration to use the Reference ID, no further updates are needed after roll forwards.

NOTE: The Reference ID and Workflow Task ID are both available and both functional. You do not need to migrate existing integrations immediately, but switching to the Reference ID is recommended for any integration that must survive roll forwards without manual updates.

Workflow Task ID vs. Reference ID

Workflow Task ID
Reference ID (New)

Changes every time a roll forward occurs
Remains fixed — never changes on roll forward
Must be manually updated in all API configurations after each roll forward
Configure once and leave — no updates needed
Risk of broken API calls if ID is not updated in time
API calls continue to work across all roll forwards automatically
Endpoint: /public/task/{taskId}
Endpoint: /public/task/by-reference/{referenceId}?period={date}

You can retrieve the Reference ID for any workflow task directly from the interface:

1. Open the workflow view in your Arkieva tenant.
2. Locate the task you want to integrate with.
3. Right-click the task row.
4. Select “Copy Reference ID” from the context menu.

NOTE: The same context menu also provides “Copy Row ID” (the Workflow Task ID). Both values are available side by side. The Reference ID is the value to use for stable integrations.


 

Setting Up Public API Access

Before you can make any Public API calls, you need a valid access token. Access tokens are generated using the credentials specific to your tenant.

Credentials You Need
The following values are required and are specific to each tenant. If you do not have these details, raise a request with DevOps or your development team to have a Public API secret generated for your tenant.

Credential
Description
Host Name
The base URL of your Arkieva environment.
Token Name
The identifier for your API token.
API Client
Your API client identifier.
API Secret
The secret key for your API client. Treat this like a password.
API Tenant ID
The unique identifier for your tenant.
Identity Host
The authentication host used to generate access tokens.


Generating an Access Token
Before making any API calls, generate an access token using your credentials. This token authorizes all subsequent requests.

5. In your API tool (e.g. Postman), locate the “Get Access Token” request in your collection.
6. Confirm your tenant credentials are populated in the environment file.
7. Send the request. A valid token is returned in the response.
8. The token is now active and can be used for all Public API calls.

Behavior During Roll Forwards
Understanding how IDs behave across roll forwards is the key reason to adopt the Reference ID.

What changes on roll forward
  1. The Workflow Task ID (Row ID) is updated to a new value.
  2. Any API configuration that references the old Workflow Task ID will need to be updated manually.

What stays the same on roll forward
  1. The Reference ID is unchanged.
  2. API calls using the Reference ID will continue to trigger and retrieve the correct task in the new period without any changes to the configuration.

NOTE: After a roll forward, you can verify that your Reference ID-based integration is still working by triggering the task via the Reference ID endpoint. A successful response confirms the integration is operational with no changes required.

Step-by-Step: Setting Up a Stable Integration
Follow these steps to configure a Public API integration that survives roll forwards without manual updates.

9. Raise a request with DevOps or your development team to obtain Public API credentials for your tenant if you do not already have them.
10. Add the credentials to your API tool environment file: Host Name, Token Name, API Client, API Secret, API Tenant ID, and Identity Host.
11. Send the Get Access Token request to generate a valid token.
12. In the Arkieva workflow view, right-click the task you want to integrate with and select “Copy Reference ID.”
13. Configure your integration to call the Reference ID endpoint, passing the Reference ID and the relevant period date.
14. Test the integration by sending a GET request and confirming the task details are returned correctly.
15. Test the invoke action by sending a POST request and confirming a 200 OK response. Verify the task triggers in the workflow view.
16. After the next roll forward, run the same integration without making any changes. Confirm it still triggers the correct task in the new period.