Rule Evaluation

  • Updated

Pre-requirements

Before proceeding to rule evaluation, make sure you meet the following pre-requirements.

  • You have the API credentials to retrieve an access token. For more information see Getting started with Apiax.

  • You followed the procedure to retrieve a JSON Web Token (JWT, either 1FA or 2FA).

  • You have at least one API key provided by Apiax to access your digital compliance rules.

As a best practice, Apiax recommends reading Understanding Digital Compliance Rules and Rule inspection before you start evaluating rules to get an overview of how the Apiax decision trees (rules) work.

 

Use this Rule evaluation description to:

  • Understand how to structure requests to evaluate a rule set - it shows how it works based on a generic example)
    Build your use cases using this description and experiment with the Apiax endpoint.

  • Understand the response of the Apiax endpoint and how you can leverage the results into your use case - find a collection of a rule response nested inside the inner (Country rule) result at $.results[*].results[*].actions

Check which are the used concepts and what definitions they have.

 

Rule Evaluation Request

To evaluate Rules, you need to send a POST request to the evaluation endpoint at:


      RULE_ENGINE/api/v3/rules/eval

The request’s payload is a JSON structure that defines the rule sets products, the rule set selection logic (versionFilter), the attributes, and the list of regimes used for evaluation.

Ensure to familiarise yourself with the digital compliance rule (decision tree) structure you’re about to evaluate. You can do this by reviewing the tree on our Apiax Platform (subscription required) or performing a Rule Inspection.

If you’re building your use case, make sure to have a concept on every property and how it affects the activity you’re looking to evaluate. For example, which properties remain static values? What are the dynamic values, and how can you gather them?


The JSON structure below is an example evaluation request. It defines:

  • two products to evaluate (“products” :[…]), Financial Services - Brand Marketing and Financial Services - Discretionary Asset Management
  • only evaluate rules for AUS jurisdiction: “regimes”: [“AUS”]).
    This overrides any existing super logic that would derive jurisdictions from the given attributes.

  • use the latest version: “versionFilter”:” latest”. This can also be a timestamp (milliseconds since 1970-01-01 T 00:00:00) in the past (for example, select the activated rules at 2020-09-02 00:00:0 with “versionFilter”:”timestamp-1598997600000“) selecting the activated rules at a specific time.

  • use the attributes in the attributes collection: “attributes”:[…]
    (Note that this list of attributes is incomplete).


              {
              "config": {
                      "correlationId": "cb-report",
                      "debug": false,
                      "followLinkActions": true
              },
              "products":[
                  {"familyId":"Financial Services","productId":"Brand Marketing"},
                  {"familyId":"Financial Services","productId":"Discretionary Asset Management"}
              ],
              "regimes":["AUS"],
              "versionFilter": "latest",
              "attributes":[
                  {"name":"bookingLegalEntity","value":"qualalumpur"},
                  {"name":"financialInstituteLicense","value":"none"},
                  {"name":"presentFIEmployeeCountry","value":"CHE"},
                  ...
              ]
              }

 

Attribute Selection

Attributes are rule set and jurisdiction independent if they consist of name and value properties onlyFor example:


              {"name":"bookingLegalEntity","value":"qualalumpur"},

Attributes may be jurisdiction-dependent if they use the additional country property.

The following line shows a definition for clientCategory in Switzerland:

{"name":"clientCategory", "country":"CHE","value":"professional"}

 

Attributes may be rule set-dependent if they use the additional product property.

The following line is a definition for clientCategory for Brand Marketing:

{"name":"clientCategory", "product":"Finanacial Services#Brand Marketing", "value":"SemiProfessional"}

 

The attributes can be country and product-specific having both product and country properties.

The following line is a definition for clientCategory for Brand Marketing in Switzerland:

{"name":"clientCategory", "product":"Finanacial Services#Brand Marketing", "country":"CHE", "value":"SemiProfessional"}

 

When evaluating a rule set the following priorities apply:

  1. product and country-specific value
  2. product-specific value
  3. country-specific value
  4. independent value

 

Wildcard Attribute

If you find a wildcard (star) value (*) during rule evaluation, it means that all the possible options defined in the rule are followed. This can multiply the number of results returned by the rule evaluation. For example:

{"name":"clientCategory", "value":"*"}

 

Multi Value Attribute

You can give different values for the same regulatory property in the values field by separating each value with a " | " character. For example,

{"name":"clientCategory", "value":"privateClient|institutionalClient"}

returns the first branch that could be completely evaluated.

You can also use a wildcard with multi value attributes. For example,

{"name":"clientCategory", "value":"*(privateClient|institutionalClient)"}

returns all branches that could be completely evaluated.

Rule Evaluation Response

Evaluating a rule set provides you with a collection of results as part of the response. These collections are summarised under $.results

 

The rule evaluation results contain two nested results-arrays:

  • The outer results array ($.results) contains an element for each rule set.

  • The inner results array ($.results[x].results) contains an element for each branch triggered during the evaluation of the respective rule set.

 

Top Level Result

The outcome of all the rule evaluation results always has the same nested structure.

At the top level, there is a list of country rule results. Each one has branch results inside for every branch that was possible to evaluate completely.


root
    - country rule result
      - branch result

 

This structure provides a collection of results (at the JSON path $.results). Each entry wraps the results of the evaluation of the jurisdiction-specific rule sets of a product.

For example, if you evaluate a request for the Financial Services and Discretionary Asset Management products, and the LUX, BEL, and UKR regimes, as shown below,


              {
                "products":[{ "familyId":"Financial Services", "productId":"Discretionary Asset Management"} ],
                "regimes":["LUX", "BEL", "UKR"]
              }
              

the resulting structure from calling the rule evaluation endpoint at /api/v3/rules/eval contains the following product-specific results:

 

  • Financial Services / Discretionary Asset Management / LUX at JSON path:
    $.results[?(@.ruleSets[0].productFamilyId=="Financial Services" && @.ruleSets[0].productId=="Discretionary Asset Management" && @.country=="LUX")]
  • Financial Services / Discretionary Asset Management / BEL at JSON path:
    $.results[?(@.ruleSets[0].productFamilyId=="Financial Services" && @.ruleSets[0].productId=="Discretionary Asset Management" && @.country=="BEL")]
  • Financial Services / Discretionary Asset Management / UKR at JSON path:
    $.results[?(@.ruleSets[0].productFamilyId=="Financial Services" && @.ruleSets[0].productId=="Discretionary Asset Management" && @.country=="UKR")]

A rule evaluation request can have multiple products. In this case, the JSON paths to the different product-specific results contain the respective productFamilyId and productId.

The regimes’ collection of a rule evaluation request is optional. In cases where the regimes’ collection is missing or empty, the rule engine resolves the jurisdictions to evaluate from the given request attributes and the super logic definition for the requested products.

 

Product-specific Result

The following structure is a result of evaluating Financial Services / Discretionary Asset Management / LUX.


              {
                  "priorityCountry": "LUX",
                      "results": [
                      {
                          "resultId": "013b13a4-dbfe-4e70-b6c2-aaa4ea50046c",
                          "country": "LUX",
                          "generatedFor": "LUX",
                          "results": [...],
                          "aggregationResult": false,
                          "ruleSelectionLogicApplied": "[[priorityCountry]]",
                          "ruleSets": [
                              {
                                  "id": "607ef612bc9a711d18f93a73",
                                  "productFamilyId": "Financial Services",
                                  "productId": "Discretionary Asset Management",
                                  "productFamily": "[[financialServicesRuleSetFamily]]",
                                  "product": "[[apiaxDiscretionaryAssetManagement]]",
                                  "version": "22.1",
                                  "country": "LUX",
                                  "contentProviderId": "5acf2f957b13a61fa4304c96",
                                  "rulesetActivationState": "PROD"<
                              }
                          ]
                      }
                  ]
              }

At the JSON path $.results[0], you find the country result for LUX, Financial Services, and Discretionary Asset Management.

  • $.results[0].ruleSets contains the details about the rule sets contributing to the result. In this example, there's only 1 rule set contributing to the result.
  • $.results[0] has the following properties:
    • resultId: the UUID of the result.
    • country: the regime/jurisdiction the result belongs to.
    • generatedFor: indicates on which jurisdictions behalf the result was generated.
    • results: the list of branch results.
    • aggregationResult: a flag that indicates whether this result contains aggregated branch results.
    • ruleSelectionLogicApplied: a hint on which logic was applied to select this rule for evaluation.
    • ruleSets: a list of rule sets contributing to the branch results of this country result.

 

Single Branch Result

Get a closer look at a single branch result from the rule set Financial Services / Discretionary Asset Management / LUX with node path 1-22-83-96-97.

A node path is the sequence of active node IDs from the root to a leave (the Actions) of a rule set.

Rule evaluation usingle branch result

Find the single branch result at the JSON path:

$.results[0].results[*]

The branch results consist of a list of actions triggered by the rule and a path object mapping reg.props. to values used when traversing the respective branch.


              {
                  "actions":[...],
                  "path":{...},
              }
  • actions: the list of resulting actions found when traversing the branch path.
  • path: object mapping reg.props. to values used when traversing the respective branch.

 

Branch Path Element

Each element of the path stands for a node found during the decision tree traversal. Together, the path elements define the branch of the decision tree that triggered the resulting actions.

A path element has the following properties.

 


              {
                  "path":{
                          "presentProspectClientEventCountry": {
                          "value": "LUX",
                      operation": "=="
                      },
              }
  • object property name: the name of the regulatory property where a decision was made. For example, presentProspectClientEventCountry.
  • value: the option used for deciding. For example,LUX.
  • operation: the comparison operation used for deciding. For example, ==

 

 

Actions

You can identify the actions based on their class property. There are the following distinct types: InformationAction, DecisionAction, CategorizationAction, ScoreAction, CustomAction, and LinkAction.

All actions share the same set of basic properties:

  • id: the action’s identifier.
  • title: the action’s title. It can be a taxonomy reference (for example, [[demo:definition]]) or any free text.
  • message: free text.
  • type: the class/type of the action,  InformationAction, DecisionAction, CategorizationAction, ScoreAction, CustomAction, or LinkAction.
  • originRuleSetId: the rule set where the action has been defined.
  • tags: a list of tags given to a specific action. Tags can have any value. The provider of the rule defines their meaning.

 

Information Action


              {
                  "id": "cf92bc27-3d18-46a0-9b47-440a5c72efd6",
                  "title": "[[demoInformationActionTitle]]",
                  "message": "This is the description text of the action",
                  "type": "InformationAction",
                  "originRuleSetId": ["607ef612bc9a711d18f93a73"],
                  "tags": ["alpha", "echo", "charly:77"],
              }

Use this action to create informal content.

The action has only the set of common basic properties:

  • id: the action id.
  • title: the action title. You can often find here taxonomy term references.
  • message: a message.
  • type: the type of the action. This can be one of the following values InformationAction, DecisionAction, CategorizationAction, ScoreAction, CustomAction, or LinkAction.
  • originRuleSetId: the id of the rule set that produced the action. You can look up the rule set in the result rule sets structure at $.results[n].ruleSets.
  • tags: a list of tags further qualifying the action. A tag is free text which may contain special characters.

 

Decision Action


              {
                  ...
                  "type": "DecisionAction",
                  "specificInfo": {
                      "decision": false,
                      "reason": "[[reasoningFundDomicile:definition]]"
                  }
              }

Use the decision action to define a single decision.

The action-specific properties are:

  • type: DecisionAction
  • specificInfo: the type-specific information object.
    • decision: the decision value can be true or false.
    • reason: free text that might contain taxonomy references (for example, [[bondsNotAllowedByUKLaw:definition]])

 

Categorization Action


              {
                  ...
                  "type": "CategorizationAction",
                  "specificInfo": {
                      "categoryValue": "[[employeePersonalData]]",
                      "categoryDescription": "[[employeePersonalData]]"
                  }
              },

Use the categorization action to encode some categorization decisions.

The action-specific properties are:

  • type: CategorizationAction.
  • specificInfo: the type-specific information object.
    • categoryValue: a value representing the category for technical uses.
    • categoryDescription: free text used as a display label representing the category.

 

Score Action


              {
                  ...
                  "type": "ScoreAction",
                  "specificInfo": {
                      "score": "2",
                      "min": "1",
                      "max": "20"
                  }
              }

Use the score action to encode any kind of numeric (integer) value in a given range.

The action-specific properties are:

  • type:
    CScoreAction
    .
  • specificInfo: the type-specific information object.
    • min: the minimum range value.
    • max: the maximum range value.
    • score: the selected/current value in the range.

 

Custom Action


              {
                  ...
                  "type": "CustomAction",
                  "specificInfo":{
                      "properties":[
                          {
                              "title": "provideServiceAM",
                              "description": "[[provideServiceAM:definition]]",
                              "type": "Boolean",
                              "value": "yes",
                              "reason": "[[restrictionProactivePromotion:definition]]"<
                          },
                      ]
                  }
              }

Use the custom action to group a set of custom action properties.

The action-specific properties are:

  • typeCustomAction.
  • specificInfo: the type-specific information object.
  • properties: list of custom action properties. Each one has:
    • title: the name of the custom action property.
    • description: the property description.
    • type: the type of the property.
    • value: the value of the property.
    • reason: free text containing the reason for the actual value.

 

See the note below.

 

The standard usage for this type of action is to encode specific features or activities. This example shows the provideServiceAM activity, which can be yes (activity allowed), or false (activity not allowed). Other usages of the custom actions have properties defining text, number, currency, money, or date as their type, always depending on the specific semantic and information needs for which the action is designed.

 

Link Action


              {
                  "type": "LinkAction",
                  "specificInfo": {
                      "productFamilyId": "Business Rules",
                      "productId": "Instrument Offering Rules",
                      "attributes": [
                      { "name": "clientDomicile", "value": "CHE" },
                      { "name": "FIlicense", "country":"DEU", "value": "EAA1" },
                      ],
                      "actionFilters": [
                      {
                          "actionTitle": "A",
                          "actionPropertyTitle": "A"
                      },
                      {
                          "actionTitle": "assetClassTaxImpactApp"
                      }
                  ]
                  }
              }

Use the link action to create forward chaining of rule sets. The action allows to overwrite specific attributes of the next rule evaluation and allows filtering for specific actions from the next evaluation result.

The action-specific properties are:

  • type: LinkAction
  • specificInfo - the type-specific information object.

    • productFamilyId - the family ID of the rule set to evaluate.

    • productId - the product ID of the rule set to evaluate.

    • attributes - a collection of attribute definitions for the next rule evaluation.

    • actionFilters - a collection of filter definitions for actions to filter out.

See the note below.

 

Note:

Handling the Link Action requires an application to evaluate subsequent rules.

The product to evaluate is:

{“familyId”:"Business Rules", “productId”: "Instrument Offering Rules"}

The additional attributes for evaluation are:


              “attributes”: [
              { "name": "clientDomicile", "value": "CHE" },
              { "name": "FIlicense", "country": "DEU", "value": "EAA1" },
              ...
              ]

The Link Action can define an optional list of action filters. The convention is restrict resulting actions to the ones passing one of the given filters.

 

Related documents

Refer to the following documents for additional information and details about Rule Evaluation.

 

Was this article helpful?

2 out of 2 found this helpful

Comments

0 comments

Article is closed for comments.

Still have questions?

Please submit a request and we will get back to you shortly.

Submit a request