Working with the Policy Logic Engine

Policy Logic Engine overview

The Policy Logic Engine is an important component for users of the SaaS Platform to understand as it helps to identify dynamically the requirements (Data / Documents / Ownership and Control Details) which need to be satisfied when progressing a Journey Forward. A Journey Instance itself is configured to reflect a clients own business process so when interacting with these processes a calling application may have a question What data do I need to Gather for this Task in a Journey?. The Journey Instance itself does not hold this data but has reference points within which can be used to retrieve the information.

Tasks Within a Journey

A Journey instance and its tasks are somewhat like a container object, It contains references to all the data you need to determine what has to be gathered for that task. An example of a task object within the journey instance is shown below:

Journey Instance (Partial)

{
  "policyTarget": "client",
  "policyCategory": null,
  "policyRequirementType": "Data",
  "businessCategory": [
    "Basic Details"
  ],
  "businessSubCategory": null,
  "id": "7dd061e7-c43b-439c-a79f-0a5e12ce68ad",
  "name": "Basic Details",
  "description": "capture basic details description",
  "status": "In Progress",
  "order": 0,
  "taskType": "PolicyTask",
  "discriminator": "PolicyTask",
  "assignedTo": null,
  "started": "2021-02-16T14:02:10.12+00:00",
  "completed": "0001-01-01T00:00:00+00:00",
  "cancelled": "0001-01-01T00:00:00+00:00",
  "completedBy": null
}

From the object shown above, we can see that the "taskType" is a PolicyTask, the "policyRequirementType" is Data, the "policyTarget" is client and the "businessCategory" is Basic Details.

From this information, the policy domain can be queried to understand what data requirements need to be captured as part of this task. A detailed example of how to query the policy domain can be found in the policy documentation below.

Additional useful attributes within the task object include name, status and id.

Querying the Policy Domain

Using the information from the task, we can query the policy domain using POST ~/policyquery/api/v2/requirements-in-scope with the following request body. We saw this request in use within the Updating Entity Data and Advancing Journeys Section.

{
    "data": {
       "category": [
            "Basic Details"
        ],
        "entityType": "Company",
        "jurisdictions": [
            {
                "jurisdiction": "Global", //Optional to provide the name
                "versionId": "d8319029-0a83-43cc-b104-8f7f8526e94a"
            }
        ],
        "targetEntity": "Client",
        "type": "Data"
    }
}

The requirements which will be returned from the Policy Logic engine are :

• Where "category" matches with businessCategory" from the policy configuration.
• Where "entityType" is the type of entity that is in scope for the journey.
• Where the "jurisdiction" is the jurisdiction of the policy the entity is in scope for
• Where the "targetEntity" matches with policyTarget in the Policy configuration.
• Lastly where "type" matches with policyRequirementType.

Policy Domain Response

The requirements-in-scope response contains all data requirements that match the request body based on the details which have been sent. There are a few different request Types.

• Text fields
• Data fields
• Dropdown Requirements (Select Lists)

Text Field Requirement

Below is an example of a requirement that should be captured as a text field:

Text Field Requirement Example

{
  "dataField": {
    "propertyName": "legalEntityName",
    "propertyType": "text",
    "propertyTypeId": null
  },
  "validationRule": {
    "id": "8b356bcf-6ba2-498e-ace7-ddeed4930780",
    "setId": "4d27d138-9567-439e-b891-9ac8dce8ed2f",
    "propertyId": "ab92ecbc-bd77-494b-acad-3d2fb0b8136c",
    "propertyName": "legalEntityName",
    "friendlyName": "Legal Entity Name",
    "validationType": "text",
    "isDataGroup": false,
    "dataGroupId": null,
    "validationData": {
      "isMandatory": {
        "active": true,
        "message": "Field must be completed.",
      },
      "specialCharacters": {
        "excludedCharacters": [
          "%",
          "$"
        ],
        "active": true,
        "message": "Special characters not accepted."
      },
      "noNumbers": {
        "active": true,
        "message": "Numbers cannot be entered in this field."
      },
      "onlyInteger": null,
      "noNegative": null,
      "onlyDecimal": null,
      "regex": null,
      "characterLimit": {
        "minValue": 7,
        "maxValue": 50,
        "active": true,
        "message": "Value requires between 7 and 50 characters."
      },
      "numberLimit": null,
      "noFutureDates": null,
      "noPastDates": null,
      "dateLimit": null,
      "multiSelectLimit": null
    }
  },
  "id": "ab92ecbc-bd77-494b-acad-3d2fb0b8136c",
  "tenant": null,
  "category": "Basic Details",
  "description": "The legal name of the company",
  "entityType": "Company",
  "exclusiveCountryList": [],
  "name": "Legal Entity Name",
  "isSensitiveData": false,
  "isMaterialData": false,
  "jurisdiction": "Global",
  "references": [],
  "targetEntity": "Client",
  "classification": null,
  "type": "Data",
  "requirementSetId": "4d27d138-9567-439e-b891-9ac8dce8ed2f",
  "conditions": [],
  "identifier": "ab92ecbc-bd77-494b-acad-3d2fb0b8136c",
  "version": -1
}

The "dataField.propertyType" is set to text, indicating it is a text field.

The name of the requirement is "propertyName" and this is the is the key used to identify the requirement (Like a field name in a database).

Date Field Requirement

Below is an example of a requirement that should be captured as a date field:

Date Field Requirement

{
  "dataField": {
    "propertyName": "dateOfIncorporation",,
    "propertyType": "date",
    "propertyTypeId": null
  },
  "validationRule": {
    "id": "1386c464-2afe-49d2-b7ef-8a7ed5d9922e",
    "setId": "4d27d138-9567-439e-b891-9ac8dce8ed2f",
    "propertyId": "2ad15a32-cb24-432c-824f-9627dcdd1770",
    "propertyName": "dateOfIncorporation",
    "friendlyName": "Date Of Incorporation",
    "validationType": "date",
    "isDataGroup": false,
    "dataGroupId": null,
    "validationData": {
      "isMandatory": null,
      "specialCharacters": null,
      "noNumbers": null,
      "onlyInteger": null,
      "noNegative": null,
      "onlyDecimal": null,
      "regex": null,
      "characterLimit": null,
      "numberLimit": null,
      "noFutureDates": {
        "active": true,
        "message": "Date must be in the past."
      },
      "noPastDates": null,
      "dateLimit": null,
      "multiSelectLimit": null
    }
  },
  "id": "2ad15a32-cb24-432c-824f-9627dcdd1770",
  "tenant": null,
  "category": "Basic Details",
  "description": "Date that the company was legally incorporated",
  "entityType": "Company",
  "exclusiveCountryList": [],
  "name": "Date of Incorporation",
  "isSensitiveData": false,
  "isMaterialData": false,
  "jurisdiction": "Global",
  "references": [],
  "targetEntity": "Client",
  "classification": null,
  "type": "Data",
  "requirementSetId": "4d27d138-9567-439e-b891-9ac8dce8ed2f",
  "conditions": [],
  "identifier": "2ad15a32-cb24-432c-824f-9627dcdd1770",
  "version": -1
}

The `"dataField.propertyType"`` is set to date, indicating it is a date field.

The "propertyName" is the key for the requirement, and this is what the the field is saved as within the Entity Data domain.

info

Descriptions on the additional attributes in the response can be found in the API documentation.

Dropdown Requirement

Below is an example of a requirement that should be captured using a dropdown component:

Dropdown (reference data) Field Requirement

{
  "dataField": {
    "propertyName": "companyType",
    "propertyType": "select",
    "propertyTypeId": "d3abbc06-e992-4436-b4ab-8c26d5b65e1f"
  },
  "validationRule": {
    "id": "ef6aaf92-25d2-45cd-b5d1-e4c40388190c",
    "setId": "4d27d138-9567-439e-b891-9ac8dce8ed2f",
    "propertyId": "209db895-03f7-42ff-9fe8-4841125e7e5c",
    "propertyName": "companyType",
    "friendlyName": "Company Type",
    "validationType": null,
    "isDataGroup": false,
    "dataGroupId": "select",
    "validationData": {
      "isMandatory": {
        "active": true,
        "message": "Field must be completed.",
      },
      "specialCharacters": null,
      "noNumbers": null,
      "onlyInteger": null,
      "noNegative": null,
      "onlyDecimal": null,
      "regex": null,
      "characterLimit": null,
      "numberLimit": null,
      "noFutureDates": null,
      "noPastDates": null,
      "dateLimit": null,
      "multiSelectLimit": null
    }
  },
  "id": "209db895-03f7-42ff-9fe8-4841125e7e5c",
  "tenant": null,
  "category": "Basic Details",
  "description": "The legal formation of the company, such as public company or co-operative",
  "entityType": "Company",
  "exclusiveCountryList": [],
  "name": "Company Type",
  "isSensitiveData": false,
  "isMaterialData": false,
  "jurisdiction": "Global",
  "references": [],
  "targetEntity": "Client",
  "classification": null,
  "type": "Data",
  "requirementSetId": "4d27d138-9567-439e-b891-9ac8dce8ed2f",
  "conditions": [],
  "identifier": "209db895-03f7-42ff-9fe8-4841125e7e5c",
  "version": -1
}

The dataField.propertyType is set to select, indicating it is a dropdown. This means you will need to do a lookup query to retrieve the details of this field. the propertyTypeId is the LookupId which can be used to retrieve the lookup. This lookup can be queried from the lookup API, as shown later in this document. The propertyName is the key for the requirement, and is what the the field is saved within the Entity Data domain.

Description on the additional attributes in the response can be found in the API documentation.

Validation Object

As part of the response from policy domain, is a validation rule which is linked to data requirements. The following is an explanation of the different validation rule attributes:

• id - unique identifier of Validation Rule.
• setId - unique identifier of Requirement Set/Data Group.
• propertyId - unique identifier of Requirement/Data Group Field.
• propertyName - Requirement/Data Group Field property name.
• friendlyName - Requirement/Data Group Field friendly name.
• validationType - validation type, same value as in dataField.propertyType.
• isDataGroup - flag indicating it is validation rules for Data Group Field.
• dataGroupId - unique identifier of Data Group, is set only when Requirement/Data Group Field dataField.propertyType is "dataGroup".
• validationData - set of validation rules specific to Requirement/Data Group Field.

Each validation rule has active flag and error message properties. Depending on validationType property Requirement/Data Group Field can have different sets of rules available (except for isMandatory, which is always available).

• isMandatory - this rule doesn't allow empty value (can be set in every type of validation).

• validationType text:

  • validationData.specialCharacters - doesn't allow special characters, but allows define array of characters which can be ignored by the validation
  • validationData.noNumbers - doesn't allow numbers
  • validationData.characterLimit - allows to set minimum and maximum count of characters
  • validationData.regex - this rule validates the value against provided regex

• validationType number:

  • validationData.onlyInteger - allows only integers
  • validationData.noNegative - doesn't allow negative numbers
  • validationData.onlyDecimal - allows numbers up to two decimal places
  • validationData.numberLimit - allows to set number range

• validationType date:

  • validationData.noFutureDates - doesn't allow future dates
  • validationData.noPastDates - doesn't allow past dates
  • validationData.dateLimit - allows to set date range

• validationType multiselect:

  • validationData.multiSelectLimit - allows to set selection range.

Dynamic Requirements

Certain data requirements are dynamic, and are only triggered based on other data capture points. In order to evaluate dynamic requirements, a request to the policy logic engine can be sent to the POST ~/policylogicengine/api/v3/engine/evaluate-requirements

A sample request is shown below. This is the same sample used in Updating Entity Data and Advancing Journeys Section.

{
    "data": {
        "requirementTypes": [
            "Data"
        ],
        "jurisdictions": [
            {
                "jurisdiction": "Global",
                "versionId": "d8319029-0a83-43cc-b104-8f7f8526e94a"
            },
            {
                "jurisdiction": "Ireland",
                "versionId": "c47d185d-12df-4595-a9f7-c763972277f6"
            }
        ],
        "targetEntity": "Client",
        "categories": [
            "Basic Details",
            "Booking Details"
        ],
        "properties": {
            "legalEntityName": {
                "type": "Single",
                "value": "Acme Finance Group"
            },
            "country": {
                "type": "Single",
                "value": "Ireland"
            },
            "dateOfIncorporation": {
                "type": "Single",
                "value": "2021-12-31"
            },
            "category": {
                "type": "Single",
                "value": "Corporation"
            },
            "companyType": {
                "type": "Single",
                "value": "Bank"
            },
            "entityType": {
                "type": "Single",
                "value": "Company"
            }
        }
    }
}

The response from this endpoint is structured the same way as the response from the ~/policyquery/api/v2/requirements-in-scope, with additional data requirements returned.

Attributes Related to UI Rendering and Decoration

As part of consuming the response for the policy API, the following attributes can be used as part of a rendering solution:

Attribute Name	Usage	Example
data.[].dataField.propertyType	Used to indicate type of control is required	select,text,date
data.[].name	Used to indicate the name of the field	Legal Entity Name
data.[].category	Used to categorize the field within a policy, which can also be used for sub headings	Basic Details
data.[].description	Used to provide additional detail about a field, can be used as part of a tooltip	Please use this field to capture the Name of the Legal Entity
data.[].validation	Used to indication what validation should be on the control	See validation section of document for full details