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:
-
Config parameters:
-
correlationId
- it allows you to associate custom semantic information with the request. Possible values:any string
.
-
debug
- it allows you to toggle the debug mode to show verbose information about variables and logs. Possible values:true
orfalse
.
-
followLinkAction
- a flag that allows the rule evaluation to follow link actions, meaning to proceed the evaluation of other rules, when applicable. Possible values:true
orfalse
.
-
retainAggregationResultInfo
- Some products complement others, so the API automatically joins the results whenever possible. If you need to separate these product results, set this flag totrue
. Possible values:true
orfalse
.
-
showIterativePathActions
- a flag that allows you to show or hide the action results along the evaluated path for iterative result responses during a rule evaluation. Possible values:true
orfalse
.
-
groupInstrumentsResults
- a flag that allows you retrieve multiple iterative results and group the results based on same properties for multiple ISINs. Set this parameter totrue
to get a grouped and potentially smaller response. Possible values:true
orfalse
.
-
includeContentProviderName
- a flag to add the content provider name of a rule to the response. Possible values:true
orfalse
. If set totrue
, the ruleset propertycontentProviderName
will be added to the response body.
-
showUnrealistic
- a flag to add applicable unrealistic scenarios to the response. Possible values:true
orfalse
. If set totrue
, actions which are unrealistic scenarios will be added to the response body with a new property calledunrealisticId
. This id can be used to resolve the unrealistic scenario information via a newunrealisticScenarios
property in the outer results structure which will only be visible if any unrealistic scenario exists. If this parameter is not provided or set tofalse
, the respective unrealistic actions won't be included in the response at all.
-
- Two products to evaluate (
“products” :[…]
), Financial Services - Brand Marketing and Financial Services - Discretionary Asset Management.
- Only evaluate rules for the Australia
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,
"followLinkAction": true,
"showIterativePathActions": true,
"groupInstrumentsResults": true,
"includeContentProviderName": true,
"showUnrealistic": 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 only. For 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:
- product and country-specific value
- product-specific value
- country-specific value
- 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",
"contentProviderName": "KPMG (Schweiz) AG",
"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.
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
, orLinkAction
. -
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:
- type: CustomAction.
- 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.
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.
-
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 document for additional information and details about Rule Evaluation.
Comments
0 comments
Article is closed for comments.