Setup

To integrate a custom workflow as a Partner Task, create a new flow and add a Partner Task. The partner task offers a few different options, let's review them:

Title: the name of the task as shown to the worker.
Estimated task completion time: how long the worker should prepare for this task to take (optional)
Iframe URL: this URL will be embedded and shown to the worker in their portal when accessing that task. This is where the partner content should be displayed. By pressing the { } on top of it, partners can append some variables to the URL that they need in the workflow.
End event: the worker portal is listening to this event as a trigger for closing the iframe and continuing to the next task (optional).
Append task context: if that option is selected, the following query parameters will be appended automatically to the URL: wxWorkerUuid, wxAssignedTaskUuid, wxTaskFlowUuid, wxCompanyUuid. These informations are useful if your workflow needs to perform some actions on the API, and especially the wxAssignedTaskUuid is important to take good note of.
Hide "Task Completed" button: if unchecked, a button will be shown to the worker, letting them mark the task as complete from their end.
Require review: whether or not the task needs to be reviewed by an admin upon completion.

Updating the task status

When the worker starts interacting with the task, it will be shown as In Progress in the WX Onboard backoffice. Following that, the partner may want to update the status of the task in relation to the actions that the worker is taking. This is made possible by using a dedicated endpoint (requiring WX API credentials and the proper permissions, see Authentication), which lets the partner update the overall task status as well as add some metadata about the internal status.

To do so, this is an example request that the partner can perform. Note that this endpoint can only be used to update Partner tasks

curl -X "POST" "http://wxp-services.fountain.com/api/servicetodo/processes/partnerTasks/{ASSIGNED_TASK_UUID}" \
     -H 'Authorization: Bearer XXXXX' \
     -H 'Content-Type: application/json' \
     -d $'{
  "sentAt": "2024-09-05T20:00:25.834Z",
  "partnerId": "IZYRUO-9384",
  "partnerUrl": "https://partner-url.com/progress/IZYRUO-9384",
  "partnerStatus": {
    "label": "misssing data",
    "color": "warning",
    "details": "The following documents are missing: Driver License, Passport"
  },
  "taskStatus": "inProgress"
}'

The body of the request should contain the following parameters (those marked with * are mandatory):

taskStatus*: the overall task status. Must be one of the following statuses:
- "ready": Initial state of a task, entirely unstarted
- "inProgress": A worker has commenced working on a task but has not yet completed it
- "completed": The worker is done with the task. If the task requires review it will be in "completed" state while it awaits an admin's approval
- "error": The task is irrevocably problematic. The worker needs to restart it or the task is abandoned
  Please note: If the task requires review and is marked as "completed", then an admin will be able to approve or reject it. If the task is in any of the statuses indicating that the worker initiated their actions, an admin can reset it, which means that the partner workflow must allow for any task to be restarted with the same parameters. Likewise if a task has already been completed and reviewed by an admin and a request with taskStatus of "ready", "viewed", or "inProgress" is received then the previous review information will be reset/deleted and the task will need to be RE-reviewed by an admin after the worker has RE-completed the task.
sentAt*: an ISO-8601 formatted string with the time of the update on the partner side. If events are sent out of order, obsolete events will be ignored.
partnerId: an optional internal reference or identifier on the partner side.
partnerUrl: an optional URL to view more information about the workflow.
partnerStatus: more information about the current status. All parameters are optional.
- label: can be any short string (max 32 characters)
- color: can be any of "success", "warning", "danger", "neutral" (defaults to "neutral" if not set)
- details: a free text field explaining more about the current status.

The result of the above request, as well as other follow-up updates are show in the worker task information panel. The last update and task metadata are shown prominently at the top, but other updates from the partner show in an audit trail section.