1. Overview of the detection methodology
The core detection capability within the platform is distributed across 3 distinct steps in the end-to-end evaluation flow.
Once data is ingested into the transaction history by the TMS API, the Channel Router and Setup Processor (CRSP) performs an initial “triage” step to determine if the transaction should be inspected by the platform, and in what way. At the moment this is a very simple decision based on the transaction type only (i.e. pain.001, pain.013, pacs.008 and pacs.002), though we envisage that the decision-making here can be more complex in the future by inspecting attributes contained in the message. For now, the CRSP uses the transaction type1 to select the typologies that are to be evaluated and triggers the rules required by the typologies. The CRSP routing is configured via a network map that defines the hierarchy of typologies and rules. While not directly influenced by a calibration process at present, the behavior of existing rules and typologies may result in changes to the scope of the evaluation defined in the network map. Some rules or typologies may be deemed to be ineffective in the current configuration and removed or recomposed, and new rules or typologies may be added as new behaviors emerge.
Each rule processor that receives the trigger payload from the CRSP evaluates the transaction and the historical behavior of its participants according to its specification and configuration. Rule processors are driven by a combination of parameters and result specifications to determine only one of a number of related outcomes. The rule outcome is then submitted to the typology processor for scoring.
The typology processor assigns a weighting to each rule outcome as it is received based on the rule’s parent typologies’ configurations. Once all the rule results for a specific typology has been received, the typology adds all the weighted scores together into the typology score. The typology score can be evaluated against an “interdiction” threshold to determine if the client system should be instructed to block a transaction “in flight” and also an investigation threshold to trigger a review process at the end of the transaction evaluation.2
Once these three steps are complete, the evaluation of the transaction is wrapped up in the Channel and Transaction Aggregation and Decisioning Processor where the results from typologies are aggregated and reviewed to determine if an investigation alert should be sent to the Case Management System. If any typology had breached either its investigation or interdiction threshold, the transaction will trigger an alert.
The evaluation process accommodates a number of different calibration levers that can be manipulated to alter the evaluation outcome.
In the CRSP:
Changes to the rule and typology scope of the evaluation
In the rule processors:
Changes to the parameters that influence the rule processors behaviour
Changes to the result bands that classify the rule processors output
In the typology processor:
Changes to the rule result weightings
Changes to the typology threshold
In this document, we will discuss how the various configuration documents are expected to be updated to influence evaluation behavior.
2. Configuration Management
Configuration documents are essentially files that contain a processor-specific configuration object in JSON format. The recommended way to upload the configuration file to the appropriate configuration database and collection is via Arango DB’s HTTP API that is deployed as standard during platform deployment.
2.1. Rule Processor Configuration
2.1.2. Introduction
A rule processor is a custom-built module that evaluates an incoming message according to its code. When a new rule processor is developed, the rule designer will specify both the input parameters for the rule, as well as the output results. Changes to these attributes can alter a rule processor’s behavior and it is expected that these attributes are hosted in the rule configuration so that the rule processor behavior can be altered by updating the configuration instead of changing the rule processor code.
A rule processor configuration document typically contains the following information:
Rule metadata, for example:
{
"id": "003@1.0.0",
"cfg": "1.0.0",
"desc": "Account dormancy - creditor"
}
A config object, that may contain parameters, for example:
"config": {
"parameters": {
"maxQueryRange": 86400000,
"tolerance": 0.1
}
}
The config object may contain a number of exit conditions, for example:
"config": {
"exitConditions": [
{
"subRuleRef": ".x00",
"outcome": false,
"reason": "Incoming transaction is unsuccessful"
},
{
"subRuleRef": ".x01",
"outcome": false,
"reason": "Insufficient transaction history"
}
]
}
The config object will also contains either result bands, for example:
"config": {
"bands": [
{
"subRuleRef": ".01",
"lowerLimit": 0,
"upperLimit": 18,
"outcome": true,
"reason": "The debtor is younger than 18 years old"
},
{
"subRuleRef": ".02",
"lowerLimit": 18,
"upperLimit": 30,
"outcome": true,
"reason": "The debtor is 18 years or older and younger than 55 years of age"
},
{
"subRuleRef": ".04",
"lowerLimit": 50,
"outcome": true,
"reason": "The debtor is 55 years or older"
}
]
}
or alternatively result cases, for example:
"config": {
"parameters": {},
"exitConditions": [],
"cases": [
{
"subRuleRef": ".00",
"outcome": false,
"reason": "The transaction type is not defined in this rule configuration"
},
{
"subRuleRef": ".01",
"value": "MP2B",
"outcome": true,
"reason": "The transaction is identified as a Mobile P2B Payment"
},
{
"subRuleRef": ".02",
"value": "MP2P",
"outcome": true,
"reason": "The transaction is identified as a Mobile P2P Payment"
},
{
"subRuleRef": ".03",
"value": "CASH",
"outcome": true,
"reason": "The transaction is identified as a general cash management instruction"
}
]
}
3. Version Management
3.1. Introduction and Basics
Each configuration document in the platform can be assigned a unique semantic version that will identify one instance of a configuration document as distinctly separate from another instance of the same configuration document.
Configuration documents in Actio are strictly structured JSON documents. Each document contains an identifier related to the specific processor and version of that processor to which the configuration is to be applied. For example, the configuration for a rule processor would have the following attribute and value in the typology configuration:
"id": "099@1.0.0"
The rule would typically be known as “rule 099” and is called the rule name. The deployed version of the rule processor would be “1.0.0” and is called the rule processor version.
In reality platform processors are deployed from their GitHub source code via Jenkins. Rule processors are version- or source-controlled using GitHub’s native source control functionality and changes to a rule processor’s source code are fully accounted for between versions.
The configuration of a particular processor is handled separately from the processor source code. The configuration of a specific version of a processor may be changed without changing the underlying code and will then result in a new behavior in the rule processor’s execution. The same rule processor version may even be deployed multiple times with a different configuration applied to each of the different instances.
In order to manage multiple consecutive or parallel versions of a processor’s configuration, each configuration file contains a configuration version attribute as well:
"cfg": "1.0.0"
The configuration version attribute defines the specific version of the configuration file when it is used by a processor.
Actio employs semantic versioning3 for both processor source control and configuration documents:
Given a version number MAJOR.MINOR.PATCH (99.999.9999), increment the:
MAJOR version when you make incompatible API changes
MINOR version when you add functionality in a backward compatible manner
PATCH version when you make backward compatible bug fixes
3.2. Configuration version management of processors
Every rule processor, typology processor and transaction aggregation and decisioning processor (TADProc) is guided by its own configuration document. The specific version of a configuration document that is required to operate a processor is defined in the network map when the evaluation routing is specified. When a processor receives an instruction from its predecessor in the evaluation flow, the processor checks the network map to determine which configuration document and version to use to perform its tasks.
When a new version of a configuration document is required, the updated version must be deployed to the appropriate configuration collection in the configuration database:
Collection name | Processor Type |
|---|---|
configuration | Rule4 |
typologyExpression | Typologies5 |
transactionConfiguration | Transaction Aggregation and Decisioning6 |
Configuration documents can be posted to the appropriate collection via the ArangoDB API, either in bulk or one-by-one. When posting a new configuration for an existing processor, the database will not allow a user to submit a configuration for an "id" and "cfg" combination that already exists in the database: a new configuration must always be assigned a unique configuration version.
Beyond this constraint imposed by the database, configuration versions are expected to be managed outside the platform. The Actio platform does not currently offer a native user interface for configuration management, though Sybrin, one of the FRMS Centre of Excellence’s System Integrator partners, have created a user interface that allows for the creation of configuration documents as well as the automated management of configuration versions between iterations of a configuration document.
Once a configuration document has been created or updated and uploaded to the configuration database, the configuration is ready to be used, but not in use yet. To activate a new configuration (or version), the configuration must be linked to the processor in the network map.
3.3. The Network Map
The network map defines the routing of an incoming transaction to all rules and typologies that are required to evaluate the transaction7. By default, the platform is configured to evaluate a pacs.002 transaction that concludes a transaction initiated from a pain.001 or pacs.008 message with a status response.
Unlike the processor configuration documents, the network map does not contain an explicit configuration version8. Instead, the network map contains an attribute to identify the current active network map being used to perform evaluations:
"active": true
The network map that is used to perform a particular evaluation is dynamically determined in the Channel Router and Setup Processor and is always encapsulated in the payload that is evaluated by all downstream processors. The processor uses the network map to retrieve the correct configuration and also accompanies the results of the evaluation so that the network map that was used for the evaluation is always explicitly traceable.
There can only be one network map in an “active” state in the platform at a time. A new network map can be posted to the network map database via the ArangoDB API. An existing network map’s “active” state can also be changed via the API.
As with other configuration documents, a network map is never intended to be updated. A new iteration (or version) of the network map must be uploaded and then the existing active network map must be deactivated and the new network map must be activated.
The unique “true” state of the active flag is expected to be enforced outside the platform. Sybrin have also embedded this functionality in their configuration management utility.
The active network map ultimately defines the scope of a particular evaluation, right down to the specific processors and their versions that are going to be used, as well as the specific version of the processor configuration required. If any of the components in a network map changes, a new network map must be deployed and activated to replace the previous iteration of the network map.
References:
In its current configuration, the platform only evaluates the pacs.002 as the trigger payload for the rule processors and typologies have only been defined with the final status of a payment transaction in mind.
The typology processor is not currently configured to interdict the transaction when the threshold is breached; only investigations are commissioned once the evaluation of all the typologies are complete.
https://frmscoe.atlassian.net/wiki/spaces/FRMS/pages/76906497/Configuration+management#References%3A
An explicit version reference has been planned for development to make it easier for an operator to link an evaluation result to the specific originating network map.