Versions Compared

Version Old Version 12 New Version 13
Changes made by

Alex Xie

Alex Xie

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Function

Description

/onelistserver/api/datasync/SyncTasks

This API synchronizes 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;

    • The TaskDetail field is madatory 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 hirerarchy.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 map these users before 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 synchronizes 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 sytem 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 is the full detail 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 notifiy 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.

...

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.

What is the main source for user information in the organization? Is user mapping required?

The adapter needs to implement the user sync process if the source system is the main source for OneList users.

...

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 invovles 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 identitify 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 are different, the adapter can then the adatper does not implement the user mapping process when it can automatically map source user id to the OneList user idsync 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?

It is better to involve end user early to identify the level of detail required for approvers to make decisions and make sure the adapter has sufficient access to the source data internally and externally as needed. In order to provide sufficent detail for users to make approval decisions directly within OneList, the adapter will need to retrieve comprehansive 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;

  • priror approvals and comments from the workflow history;

  • documents attached to the task or the business object;

What is the selection critera for the initial load?

...

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 missing missed events due to downtime and or lost of connectivity to the event source.

...