OneList Integration APIs

API endpoints

The base URL of the APIs is: /onelistserver/api/datasync e.g. https://iqx.onelistapprovals.com/onelistserver/api/datasync/synctasks. These APIs can be viewed and tested using Swagger which is accessible via /onelistserver/swagger. The full API signatures can also be found here.

Authentication

The adapter must use the OneList API key that is assigned to the source system to interact with the data sync APIs. Follow the steps in Manage Source Systems to find the API key for the source system. The API key should be specified in the X-API-Key header in every HTTP request. Below is an example of a HTTP POST request:

POST https://iqx.onelistapprovals.com/onelistserver/api/datasync/SyncTasks HTTP/1.1
X-API-Key: TQUIteYnrxqHkBvh2{
Content-Type: application/json

{"activeTasks":[….]}

The key terms used in the APIs

Term	Description
TaskType	This constant value must match the Task Adapter Task Type in OneList configured to handle the request.
TaskId	This is the source system unique identifier of the task. The value must be consistent in the whole lifecycle of the task.
BusinessObjId	This is source system identifier of the business object associated with the task. For example, The PO number for the purchase order approval task; The SharePoint item id for the document approval task; It can be the same as the Task Id if there is no separate entity for the task.
ActionId	This is the source system workflow action identifier.
Assignee	The user id of the source system user who is assigned to the task as the approver / agent.
Delegator	The user id of the source system user who is delegating the task.
Delegate	The user id of the source system user who is the task delegate.
HashValue	The string value can be used to compare if the task has been changed. The following can be used as the hash value for a task: Last update timestamp; Version number of the business object, e.g. document version; Calculated based on the value of critical fields or the entire task, e.g. MD5 hash.

The key APIs for integration

Note: only the key parameters of each API are listed here, please view the full API signature via /onelistserver/swagger.

Function	Description
`/onelistserver/api/datasync/SyncTasks`	This API synchronises OneList tasks with source workflow tasks. The ActiveTasks array contains new or updated task detail. OneList reads this array to add or update the tasks to its task cache; The supported task actions must be defined in the EnabledActions field. For each action, specify the type of action in the ActionType field: Action - the action is a task level action. LineAction - the action is a line-level action. Actions of this type can be bound to a Section in the OneList Task Configurator. ForwardTask - the action is to forward the task to a different user. OneList ensures a forwarded user is selected when executing this action. For each task level action, specify the ApplyLineAction field: true - apply line-level actions; false - do not apply line-level actions. The TaskDetail field is mandatory and it must be assigned the full detail of the task (JSON). It can contain hierarchical data structures and there is no limit to the number of levels of hierarchy. This is the source data for the OneList task engine to layout the task for presentation. The meta data of the task attachments should be included in the Attachments field. The attachment files are posted to OneList separately using the `/onelistserver/api/datasync/SyncAttachments` API. If the HasValue field is not set then OneList uses the TaskDetail field to calculate the hash. The DeletedTaskId array contains the id of the tasks that are completed by the source workflow. OneList removes these tasks from its task cache;
`/onelistserver/api/datasync/GetUserSyncRequests`	This API returns the list of user id of the source system users who have outstanding task but are not yet mapped to an OneList user. The source system should call the SyncUsers API to create or update their accounts in OneList so they can view their tasks in OneList.
`/onelistserver/api/datasync/GetActiveUsers`	This API returns the profile of active OneList users. It can be used to compare with source system user information to detect outdated OneList user profile. The UserName field is the source system user id; The OneListUserId field is the OneList user id; The other fields are the current OneList user profile information.
`/onelistserver/api/datasync/SyncUsers`	This API adds or updates OneList user account with the source system user information. It also creates the user mapping between the OneList user account and the source system user account. The UserName field is the source system user id; The OneListUserId field is optional, if not specified then the UserName is used as the OneList user id; The other fields are used to populate the OneList user profile.
`/onelistserver/api/datasync/SyncAttachments`	This API synchronises OneList task attachment cache with source system files. The Attachments array contains the current version of the files for the task; The DeletedAttachments array contains the source system document id that is removed from the source system document repository.
`/onelistserver/api/datasync/GetActionRequests`	This API returns the list of user task actions. The source system should perform the requested task action in the workflow. The UserId is the source system user id who performed the action in OneList; The Task field contains the key information of the task to be actioned; The TaskAction field contains the detail of the task action including user input such as approval comment; The LineActions array is only populated for task supporting line-level action; The Token field may contain the refresh token for source system to impersonate the user.
`/onelistserver/api/datasync/PostTaskActionOutcome` `/onelistserver/api/datasync/PostLineLevalTaskActionOutcome`	Source system calls this API to notify OneList of the requested task action. The OneListRequestId is the identifier of the action request; The Messages array is optional for posting any status or error messages to OneList.
`/api/DataSync/GetDelegationRequests`	This API returns the list of new or deleted delegation requested by the user. The adapter should add or remove the delegation records in the source system accordingly. The Operation is either New or Delete; The OneListRequestId is the OneList request id. It should be passed back in the PostDelegationOutcome API for OneList to update the status of the request; The SourceSystemRecordId is used for identifying the delegation record in the source system for deletion. This field is null when the Operation is New; The DelegateFromUser is the delegator’s user id in the source system; The DelegateToUser is the delegate’s user id in the source system; The WorkflowType is used for identifying the delegation subsystem or subcategory for which the request is targeting; The Scope is used for identifying the profile or scope for which the request is targeting;
`/api/DataSync/PostDelegationOutcome`	The adapter calls this API to post the outcome of each delegation request. The OneListRequestId is required and must be assigned with the OneList request id; The SourceSystemRecordId is required when the outcome is successful; The IsError is a boolean value indicating if the request was processed successfully or not; The Message is an array of string for the adapter to return success or error information to OneList;
`/api/DataSync/SyncDelegations`	The adapter calls this API to post the full list of current delegation records of the source system to OneList The SourceSystemRecordId is required and has the unique id of the source system delegation record; The DelegateFromUser is the delegator’s user id in the source system; The DelegateToUser is the delegate’s user id in the source system; The WorkflowType is the delegation subsystem or workflow of the delegation; The Scope is the profile or scenario of the delegation;
`/api/DataSync/GetBusinessObjectRequests`	The adapter calls this API to get the list of id of the business objects requiring the updated snapshots. The API returns the following: The task type; The id of the business object; The hash value; The last workflow task id for the business object. Adapter can use this id to identify the workflow and retrieve the workflow history.
`/api/DataSync/SyncBusinessObjects`	The adapter calls this API to post the snapshot of business objects. The information posted are: The task type; The id of the business object; The hash value; The title of the business object. The full name of the requestor. Whether it is the final snapshot based on the status of the business object. The detail field must be the same task JSON as the TaskDetail JSON for the SyncTask API.

What needs to integrate with OneList

An adapter will generally implement these integration processes:

Adapter design considerations

You should consider these questions before implementing the OneList adapter as the answer could affect the design of the adapter and the process it needs to implement.

Where is the adapter hosted?

The adapter can be hosted by the source system if it is capable, such as SAP, otherwise the adapter should be hosted by an integration platform (iPaaS), such as Azure Integration Services. Source system hosted adapter can access the system’s internal processes and data. External hosted adapter can only access the public APIs and a sub-set of data exposed by the source system.

What are the security and permission requirements of the source system?

The adapter is a daemon service. It needs permission to query all user’s tasks, as well as the business objects and attachment files related to the tasks. You need to decide whether it should use the running service account or an explicit account to access source system data and make sure that account has sufficient permission to query the source data.

The adapter may need to impersonate the approver to perform task action in the source system. Impersonation requires permissions such as to run SAP background job as the approver, or to request access token using the approver’s refresh token.

Should the adapter implement user sync process?

The adapter is required to implement the user sync process when

the source system user id and the OneList user id are the same;
the adapter can automatically map the source user id to the OneList user id.

The user sync process involves calling the /onelistserver/api/datasync/GetUserSyncRequests to get the list of user ids to be sync’d and calling the /onelistserver/api/datasync/SyncUsers to post the user profile and user mapping to OneList. The adapter should query the user information from either the source system or the identity management system, e.g. internal AD or Azure AD. In response to the Sync Users API, OneList will create user accounts and send email notification to the new users inviting them to start using OneList.

If there is no relationship between the source system user id and the OneList user id then the adapter does not implement the user sync process. OneList will prompt users log in to the source system with the source system user credentials in order to complete the user mapping process. The prerequisites of this manual mapping are:

user has an existing OneList account;
the source system supports one of these protocols: OAuth, OpenID Connect or SAML.

What level of detail in the task is required?

In order to provide sufficient detail for users to make approval decisions directly within OneList, the adapter will need to retrieve comprehensive information for the task, such as

details of the business object associated to the task, e.g. the purchase order detail, the SharePoint list item properties;
the key and value of master data look ups;
prior approvals and comments from the workflow history;
documents attached to the task or the business object;

What is the selection criteria for the initial load?

When integrating with an existing workflow, it is important to identify the selection criteria for the initial load to avoid outdated and invalid tasks being posted to OneList. Fields like task id, creation date and status are commonly used as the selection criteria. The adapter should efficiently perform the initial push of tasks to OneList. Consider HTTP connection and request size limits imposed on the OneList APIs, paging of data may be required to handle large volume of data.

Event-based integration process

Event-based process is preferred as it is timely and efficient. However, the adapter should also consider implementing time-base trigger for the process so that it can catch up any missed events due to downtime or lost connectivity to the event source.