This page explains how you can update the party status using a workflow.

Deprecation warning

As of release v4.82.0 we will no longer support updating the Client File party status using our API. Instead, a workflow is required to change the party status.
Specifically the method updatePartyStatus will be deprecated from endpoint: https://api.blanco.cloud/bcmd-party/graphiql

Prerequisites
One time setup: Get workflow details
- Step 1: Get ChangePartyStatus workflow id
- Step 2: Get workflow steps
Update status with a task

Prerequisites

To perform the actions in the instructions, you require a valid authorization.
To be able to set the task to done the permission changePartyStatusDoneWrite is required. (For more on permissions: User groups and permissions )

One time setup: Get workflow details

The workflow details are tenant specific. If you have multiple tenants, make sure to perform this setup for each tenant individually. The id's retrieved in the setup are also static for your tenant, so it is sufficient to retrieve them only once.

Step 1: Get ChangePartyStatus workflow id

Endpoint: GET https://api.blanco.cloud/bwfs/workflows

Body: none

Response example:

[
    {
        "id": "6efcdfc2-3e1a-11eb-8764-11dd8ebca331",
        "name": "Review",
        "workflowType": "review"
    },
    {
        "id": "changePartyStatus-0001",
        "name": "ChangePartyStatus",
        "workflowType": "changePartyStatus"
    },
    ...
]

Workflow id is found on the property id of the workflow with workflowType changePartyStatus

"id": "changePartyStatus-0001",

Step 2: Get workflow steps

Endpoint: GET https://api.blanco.cloud/bwfs/workflows/{{workflowId}}/steps

Body: none

Response example:

{
    "id": "changePartyStatus-0001",
    "description": "ChangePartyStatus",
    "steps": [
        {
            "id": "changePartyStatus-0001#1",
            "status": "Review"
        },
        {
            "id": "changePartyStatus-0001#2",
            "status": "Done"
        }
    ]
}

Get the id for the steps review and done :

review step: "id": "changePartyStatus-0001#1",
done step: "id": "changePartyStatus-0001#2",

Update status with a task

The task is an instance of the workflow and is referred to in the API as a 'process'.

Explanation on Party Status

The party status can be one of the following values:

partyStatus label	Description
P	Pending
A	Accepted
R	Rejected

Step 1: Check for existing tasks

Check for pending workflow tasks, only one task can be active at a time for a specific workflow/party.

Endpoint: GET https://api.blanco.cloud/bwfs/process/pending?entityId={{partyId}}&entityType=PRT&workflowId={{workflowId}}

Body: None

Response example:

If there is no active task:
{}

If there is an active task:

{
    "workflowId": "changePartyStatus-0001",
    "status": "Review",
    "processId": "bd007a00-e7d8-11ec-851f-9bee6256dcaa",
    "workflowType": "changePartyStatus",
    "triggerType": "eventDriven",
    "output": {
        "partyStatus": "P"
    },
    "createdAt": "2022-06-09T09:44:21.152Z"
}

If there is an active task, retrieve the value for "processId" from the response so that you can use it to complete the task and set the party status. Skip step 2 and move on to step 3 "Update the task".

Step 2: Create a task

If there is not yet an active task, create a task to change party status.

Endpoint: POST https://api.blanco.cloud/bwfs/processes

Body:

{
    "entities": [
        {
            "id": "{{partyId}}",
            "type": "PRT"
        }
    ],
    "workflowId": "{{worflowId}}",
    "stepId": "{{reviewStep}}",
    "assignee": {{userIdOfAssignee}},
    "partyStatus": "{{desiredStatus_P|A|R}}",
    "comment": "optional comment"
}

Response example:

{
    "workflowId": "changePartyStatus-0001",
    "status": "Review",
    "processId": "db647ce0-e7dc-11ec-862f-adb0ed5b2216"
}

Retrieve the value for "processId" from the response so that you can use it to complete the task and set the party status.

Step 3: Complete the task

With the processId retrieved by one of the previous steps you can now complete the task and set the status.

Endpoint: POST https://api.blanco.cloud/bwfs/processes/{{processId}}/states