Partner Tasks

February 28, 2025

The Partner task type offers a simple way for partners and developers to integrate any custom workflow as an Onboard task.

Add a Partner Task

Follow the steps in this article to create an onboarding flow. On the Create Flow screen, add the Partner task type.

When adding this task type, you will have a number of additional fields to complete:

• 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 clicking { }, you can append some variables to the URL that are needed in the workflow.

• End event (optional): The worker portal is listening to this event as a trigger for closing the iframe and continuing to the next task.

• Append task context: If this option is selected, the following query parameters will be appended automatically to the URL: wxWorkerUuid, wxAssignedTaskUuid, wxTaskFlowUuid, wxCompanyUuid. These are useful if your workflow needs to perform actions on the API especially wxAssignedTaskUuid.

• Hide "Task Completed" button: If this is unchecked, a button will be shown to the worker allowing them to mark the task as complete.

Partner Status

When a worker starts interacting with the task, it will be shown as In Progress in the Worker's Profile. You may choose to update the status of the task to be more reflective of the actual actions that the worker is taking in the task.

You can create a more defined status by using a dedicated endpoint which allows you to update the overall task status as well as add metadata about the internal status.

Important Note:

You must have API credentials and the proper Fountain permissions to make these updates. Reach out to your Fountain Customer Success contact or support@fountain.com if you experience issues and believe you have the correct permissions.

Below is an example request that could be performed. 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 also 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 the task. Not started in any capacity.
  • "inProgress": The worker has started working on the task but has not yet completed it
  • "completed": The worker is done with the task. If the task requires review it will be in a "completed" state while it awaits Fountain user approval.
  • "error": Something is wrong with the task. The worker likely needs the task reset.
• sentAt*: An ISO-8601 formatted string with the time of the update via the partner. If events are sent out of order, out of date events will be ignored.
• **partnerId:* An optional internal reference or identifier via the partner.
• **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 shown in the worker's Onboard profile. The last update and task metadata are shown prominently at the top with other updates from the partner shown in an audit trail section.

Important Notes:

• If the task requires review (based on the onboard flow configuration) and is marked as "completed", then a Fountain user will be able to approve or reject the task submission.
• If the task is in an in progress status, a Fountain user can reset the task, which means that the partner workflow must allow for any task to be restarted with the same parameters.
• If a task has been completed and reviewed by a Fountain user and a request with taskStatus of "ready", "viewed", or "inProgress" is received, then the previous review information will be reset and deleted. This task will need to be re-reviewed by a Fountain user after the worker has completed the task for a second time.

Additional Resources

Want to dive deeper? Check out Fountain's Developer Docs.