Create or retrieve an assessment via workflows

You can call the Assessments API within your workflows to create, retrieve, or retake an assessment. This is done via Java delegates that can be integrated into the service tasks. The delegates handle tasks such as parameter parsing and authentication, serving as intermediaries between your workflows and the Assessments API.

The following predefined Java delegates are available:

ConductAssessmentDelegate

Class: com.collibra.assessments.api.v1.workflow.delegate.ConductAssessmentDelegate

The following table contains the properties of the input and output parameters for ConductAssessmentDelegate.

Parameter ID Type Description Example
Input
template_id
Note This parameter is required.
 String ID of the template. 002c7cac-92d0-451e-b979-8ef0857a34b4
name String Name of the assessment. Legal Checks
asset_id String ID of the asset in Collibra. 9e6ba6fa-ae24-41c8-9b42-08e7c4231689
owner_id String ID of the Collibra user to be used as the owner of the assessment. 0e787414-fd78-48a0-bfdd-69411b26c65b
assignees_users_ids String Comma-separated list of IDs of the Collibra users to be used as the assignees of the assessment.

d615a9fe-8d8c-4287-80aa-5b058519ca45

or

d615a9fe-8d8c-4287-80aa-5b058519ca45,537bc3e8-14f5-4d44-acac-565aacab2e43
assignees_groups_ids String Comma-separated list of IDs of the Collibra groups to be used as the assignees of the assessment.

387b34f5-eac8-467c-89b6-5ee7c2e7368b

or

387b34f5-eac8-467c-89b6-5ee7c2e7368b, 3421c6a6-534c-435f-b570-32c6d41fb854
is_visible_to_everyone String Boolean.

false

or

true
Output
result String ID of the assessment created. 60dfe2b6-0215-4a30-86dd-4ee235a1821e

The following steps describe how to integrate ConductAssessmentDelegate into a workflow.

  1. On the main toolbar, click Products icon → Workflow Designer.
    The Workflow Designer page opens.
  2. Create a process.
    The process editor page opens.
  3. On the canvas, click the start event.
    Attributes for the start event are shown in the right pane.
  4. In the Details section, click Form properties.
    The Form properties dialog box appears.
  5. Click Add item.
  6. Enter the information for the first input parameter from the table in the Properties section above.
  7. Repeat steps 5 and 6 for each input parameter.
    Form properties dialog box showing all the input parameters
  8. Click OK.
  9. Drag the following activities from the palette in the left pane to the canvas:
    • Service task
    • Script task
    • End event
  10. On the canvas, add the following sequence flows:
    • From the start event to the service task.
    • From the service task to the script task.
    • From the script task to the end event.
  11. Click the service task.
    Attributes for the service task are shown in the right pane.
  12. In the Details section, in the Class field, enter com.collibra.assessments.api.v1.workflow.delegate.ConductAssessmentDelegate.
    Tip This class enables the service task to call ConductAssessmentDelegate.
  13. Click the script task.
    Attributes for the script task are shown in the right pane.
  14. In the Details section, click Script.
    The Script dialog box appears.
  15. In the dialog box, enter the following.
    Copy
    def delegateResults = execution.getVariable("result")
    println "The Java Delegate service task returned the following results: " + delegateResults
  16. Click OK.
  17. To save the workflow, in the process editor menu bar, click .

Workflow incorporating ConductAssessmentDelegate

GetAssessmentDelegate

Class: com.collibra.assessments.api.v1.workflow.delegate.GetAssessmentDelegate

The following table contains the properties of the input and output parameters for GetAssessmentDelegate.

Parameter ID

 Type Description Example
Input
assessment_id String ID of the assessment. 002c7cac-92d0-451e-b979-8ef0857a34b4
assessment_review_id String ID of the assessment review asset. 9e6ba6fa-ae24-41c8-9b42-08e7c4231689
Output
result Map<String, Object> The assessment.
Copy 

                                {
                                "id": "60dfe2b6-0215-4a30-86dd-4ee235a1821e",
                                "name": "Direct Marketing",
                                "asset": {
                                "id": "9e6ba6fa-ae24-41c8-9b42-08e7c4231689",
                                "name": "Direct Marketing"
                                },
                                "status": "DRAFT",
                                "template": {
                                "id": "c8643d4d-f9f8-4484-b9c2-d0f3432e295f",
                                "name": "Legal Checks",
                                "version": 1,
                                "status": "PUBLISHED",
                                "assetType": {
                                "id": "0b781899-3dd2-4746-bc98-65daef8f1efa",
                                "name": "Business Process"
                                }
                                },
                                "owner": {
                                "id": "0e787414-fd78-48a0-bfdd-69411b26c65b",
                                "name": "Leonard Cohen"
                                },
                                "assignees": [
                                {
                                "type": "USER",
                                "id": "d615a9fe-8d8c-4287-80aa-5b058519ca45",
                                "name": "Freddie Mercury"
                                },
                                {
                                "type": "GROUP",
                                "id": "387b34f5-eac8-467c-89b6-5ee7c2e7368b",
                                "name": "Lawyers"
                                }
                                ],
                                "content": [
                                {
                                "id": "legalBasisSpecified",
                                "title": "Are all legal bases specified?",
                                "answer": {
                                "type": "BOOLEAN",
                                "value": true
                                },
                                "comment": "We use Legitimate interest as the legal basis."
                                }
                                ],
                                "createdOn": "2023-07-10T15:03:10.433Z",
                                "createdBy": {
                                "id": "0e787414-fd78-48a0-bfdd-69411b26c65b",
                                "name": "Leonard Cohen"
                                },
                                "lastModifiedOn": "2023-07-10T18:43:10.433Z",
                                "lastModifiedBy": {
                                "id": "0e787414-fd78-48a0-bfdd-69411b26c65b",
                                "name": "Leonard Cohen"
                                }
                                }
                            

The following image shows an assessment approval workflow that uses GetAssessmentDelegate to automatically approve an assessment based on certain answers.

Workflow incorporating GetAssessmentDelegate

The workflow uses GetAssessmentDelegate to fetch the details of the assessment when the assessment is submitted.

Value in the Class field for the Get Assessment Details service task

GetAssessmentDelegate expects the workflow to have either the assessment_id parameter or the assessment_review_id parameter as a string in the form properties of the workflow.

Form properties dialog box showing the assessment ID input parameter

The following is an example of how the assessment_id parameter can be declared as a form property within the workflow.

<activiti:formProperty id="assessment_id" name="Assessment ID" type="string" default="725ca8b5-8a8d-40fa-91b9-3323b70ed524" readable="false"/>

The following is an example of how the assessment_review_id parameter can be programmatically declared.

execution.setVariable("assessment_review_id", item.id.toString())

To call the Assessments API, GetAssessmentDelegate uses the declared value 725ca8b5-8a8d-40fa-91b9-3323b70ed524 or item.id.toString(). If the call is successful, the assessment details are stored in a result variable that can be accessed in the next task, Check Answers. The answers can then be used for processing and automating business decisions.

Assessment approval workflow code

RetakeAssessmentDelegate

Class:com.collibra.assessments.api.v1.workflow.delegate.RetakeAssessmentDelegate

The following table contains the properties of the input and output parameters for RetakeAssessmentDelegate.

Parameter ID

TypeDescriptionExample
Input

assessment_id

Note This parameter is required.
StringID of the assessment.002c7cac-92d0-451e-b979-8ef0857a34b4
owner_idStringID of the Collibra user to be used as the owner of the new (retaken) assessment. If this value is not provided, the owner of the original assessment is used.0e787414-fd78-48a0-bfdd-69411b26c65b
Output
resultString

ID of the new assessment.

60dfe2b6-0215-4a30-86dd-4ee235a1821e

The following example shows how RetakeAssessmentDelegate can be used in a workflow to make the process of retaking a rejected assessment more efficient.

Suppose that a user submits an assessment for review. Once an assessment is submitted, it can't be edited. If the reviewer finds missing or incorrect information in the assessment, they provide feedback and reject the assessment. Typically, this ends the review lifecycle. The user would need to manually go to the original assessment and retake it to address the feedback.

You can, however, integrate RetakeAssessmentDelegate into the workflow such that a task is automatically created for the user to retake the assessment when their assessment is rejected.

Image of a task for the user

The user clicks the task and is taken to the Assessment Review asset page containing a link to a draft version of the assessment.

Image of the Assessment Review asset page

The draft already contains the original content, so the user doesn't need to start from scratch. This is equivalent to retaking the original assessment. The user can simply update the draft based on the reviewer's feedback and submit it again for review. The reviewer then reviews and approves the new assessment, ending the review lifecyle more meaningfully.

With this updated workflow, the user doesn't need to recreate the original assessment or manually go to the original assessment to retake it. Instead, they can directly retake the assessment via the task. The updated workflow streamlines the process of retaking and resubmitting assessments, making it easier for users to address feedback.

Note RetakeAssessmentDelegate isn't integrated into the workflow by default.