Rule Inspection

Pre-requirements

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

  • You have the API credentials to retrieve an access token.

  • 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 before you start inspecting the rules to get an overview of how the Apiax decision trees (rules) work.

 

Rule inspection

Use this Rule inspection description before you start building your use cases to:

  • Understand the properties of the rule sets - find these in the response at the JSON path $.properties.
    Check what the regulatory properties are and what their allowed values are in each country.

  • Understand which were the rule sets inspected - find these in the response at the JSON path $.ruleSets.
    Check the rule sets' ID, version, and country.

  • Understand the taxonomy terms referenced by those rule sets - find these in the response at the JSON path $.concepts.
    Check which are the used concepts and what definitions they have.

Find the Rule API inspect endpoint at RULE_ENGINE_HOST/api/v3/rules/inspect

If you only want to inspect specific rule sets, make sure to add the details to your request.


Notice: TEST API keys fall back to PROD activated rules if there is no TEST activation for a given rule set.

 

Example Request

The following request inspects all the product families, rule sets and country regimes accessible with your API-key. Find further below also examples highlighting how to create specific requests.

 


POST /api/v3/rules/inspect HTTP/1.1
Content-Type: application/json
Apikey: YOUR_APIKEY
Authorization: Bearer YOUR_ACCESS_TOKEN
Host: RULE_ENGINE_HOST
{
    "config": {
    "debug": true,
    "correlationId": "cb-report",
    "withConcepts": true,
    "analyzeActions": true
    },
    "products": [],
    "versionFilter": "latest",
    "regimes": []
}

 

Detailed Response Description

Endpoint

RULE_ENGINE_HOST/api/v3/rules/inspect

The standard RULE_ENGINE_HOST is https://rule-engine.apiax.io.

 

Method

POST

 

Headers

Content-Type: application/json

apikey: YOUR_APIKEY

Authorization:Bearer YOUR_ACCESS_TOKEN

The inspect endpoint requires 3 headers:

  • Content-Type: application/json ensures that client and server use the same syntax for request and response.

  • apikey: the api key controls which rule sets you can access. You need an api key to call any endpoint successfully.

  • Authorization: every API call must have a valid JWT as an Authorization bearer token. See Retrieving an API Access Token for instructions on how to get a JWT access token.

 

Request Body


{
    "products": [
    {
        "familyId": "string",
        "productId": "string"
    }
    ],
    "versionFilter": "timestamp-1499870512663",
    "regimes": [
    "string"
    ],
    "config": {
    "debug": true,
    "withConcepts": true,
    "correlationId": "string",
    "analyzeActions": true,
    "showAllProperties": true,
    "translations": true,
    "conceptDefinitionFormat": "string",
    "withLegalEntities": true,
    "languages": [
        "string"
    ],
    "withVerboseConceptData": true
    }
}

 

The request body of an inspect call has the following properties:

  • Config: an optional structure configuring details about the request/response.

    • debug: includes debug information, that is, adds variables used in the rule set.

    • withConcepts: a flag that indicates if you should resolve concepts and put them into the response.

    • correlationId: a value that allows correlating independent requests.

    • analyzeActions: a flag that indicates if you should analyse actions and put them into the response.

    • showAllProperties: a flag that lists all properties (active or inactive) if set to true. If set to false, it only considers the active properties. In both cases, the rule sets listed on the properties only contain the rule sets where the property is active.

    • translations: a flag that returns all available languages in a separate response structure with a concepts map and lookup table.

    • conceptDefinitionFormat:  a flag that defines the format concepts to get in return. The default value of this parameter is html. By setting this parameter to raw, the response returns the concepts as plain text, without HTML encodings.

    • withLegalEntities: a flag that allows you to get a list of the current Legal Entities for your company from the Legal Entity Manager.

    • languages: a flag to specify the languages in scope. If available, the API adds the requested translation languages to the concepts collection.

    • withVerboseConceptData: a flag that returns the categories and jurisdictions of the requested concepts. Default value: false.

  • products: a list of rule sets/product references. This list defines which are the rule sets to analyze.

      • familyId: the rule set family ID

      • productId: the rule set ID. Use * as a shortcut to inspect all products of the same family accessible with the given API key.

      • versionFilter: the version filter to use for retrieving the rule set version to analyse. Valid version filters are latest | timestamp-JAVA_TIMESTAMP

      • regimes: a list of alpha-3 country codes indicating the jurisdictions to analyse.

 

Response


{
    "properties":[PROPERTY],
    "variables":[VARIABLE],
    "ruleSets":[RULE_SET],
    "concepts":[CONCEPT],
    "apikey":{...}
}

In the response, you get an analysis of the products mentioned in the request. The response structure has the following properties:

  • properties: the list of regulatory properties with the possible options grouped by country

  • variables: the list of variables defined in the rule sets

  • ruleSets: the list of decision trees with their version and id, accessible by the API key

  • concepts: the list of taxonomy terms referenced by the rules

  • apikey: details about the API key used for inspection

 

Response properties


{
    "name": "financialInstituteLicense",
    "type": "Text",
    "options": {
        "BEL": [
            {
                "name": "none"
            }
        ]
    },
    "ruleSets": [
        "606c6dcc11d5bc3a1d2db010"
    ]
},

The properties collection contains structures with the following properties:

  • Name: the term ID of the regulatory property, used to look up the concept definition in the concepts collection.

  • type: the type of the property. This can be one of the following values: Text | Number | Boolean | Country | Currency | Money | Product.

  • options: the list of options/values that the regulatory property can have, grouped by country.

    • COUNTRY_ALPHA3_CODE: the alpha3 country code where the option is valid.

    • name: the value or the term ID of the option.

  • ruleSets: a collection of rule set IDs, that indicates the rule sets using the regulatory property.

 

Response actions


{
    "title": "activitiesDistribution",
    "type": "CustomAction",
    "propertyNames": [
        "receiveExecutionDistribution",
        "distributeFinancialInstruments"
    ],
    "ruleSets": [
        "606c7a974c4d897cbf051731"
    ]
},
{
    "title": "investorTypeSelectionCategory",
    "type": "CategorizationAction",
    "categories": [
        "[[representativeOfLegalEntityBeneficialOwnerInvestorTypeSelectionApp:definition]]",
        "[[representativeOfLegalEntityPowerOfAttorneyInvestorTypeSelectionApp:definition]]",
        "[[naturalPerson]]",
        "[[representativeOfLegalEntityOtherInvestorTypeSelectionApp:definition]]",
        "[[legalEntity:term]]"<
    ],
    "ruleSets": [
        "5ede42fa29049312fc59bd6a"
    ]
},

The actions collection contains information about actions triggered by the inspected rule sets.

  • title: the action title

  • type: the action type [CustomAction, InformationAction, CategorsationAction, ScoreAction, LinkAction].

    • CustomAction propertyNames, list of properties of a custom action.

    • CategorizationAction categories, list of categories used in a categorization action.
  • ruleSets: a collection of rule set IDs, indicating the rule sets using the action.

 

Response variables


{
    "name": "apxProduct",
    "type": "Text",
    "options": {
        "BEL": []
    },
    "description": "The product of the document.",
    "ruleSets": [
        "606c72f611d5bc3a1d2db129"
    ]
},

The variables collection contains information about variables used in the inspected rule sets.

  • name: the name of the variable.

  • type: the type of the variable.

  • options: values the variable has per country.

    • COUNTRY_ALPHA3_CODE, the alpha3 country code where the option is valid.

    • name: the value or the term ID of the option.
  • description: text that describes the purpose of the variable.

  • ruleSets: a collection of rule set IDs, indicating the rule sets using the regulatory property.

 

Response ruleSets


{
    "id": "606c72f611d5bc3a1d2db129",
    "productFamilyId": "Financial Services",
    "productId": "Investment Advice",
    "productFamily": "[[financialServicesRuleSetFamily]]",
    "product": "[[apiaxInvestmentAdvice]]",
    "version": "28.1",
    "country": "BEL",
    "contentProviderId": "5acf2f957b13a61fa4304c96",
    "rulesetActivationState": "PROD"<
},

The ruleSets collection contains information about the rule sets accessible by the API key. The collection only contains the rule sets inspected. If the inspection request restricts regimes and products, only those rule sets are listed.

  • id: the id of the rule set.

  • productFamilyId: the id of the product family the rule set belongs to.

  • productFamily: the label of the product family the rule set belongs to.

  • productId: the id of the product the rule set belongs to.

  • product: the label of the product the rule set belongs to.

  • version: the rule set version.

  • country: the regime/jurisdiction the rule set belongs to.

  • contentProviderId: the id of the content provider responsible for the rule set content.

  • rulesetActivationState: the activation state of the rule set [PROD, TEST].

 

Example Request

POST /api/v3/rules/inspect HTTP/1.1
Content-Type: application/json
Apikey: YOUR_APIKEY
Authorization: Bearer YOUR_TOKEN
Host: RULE_ENGINE_HOST


{
"products":[
    {"familyId":"Financial Services","productId":"Brand Marketing"},
    {"familyId":"Financial Services","productId":"Discretionary Asset Management"},
    {"familyId":"Financial Instruments","productId":"Investment Funds"}
],
"regimes":["BEL","CHL","SAU","ZAF"],
"versionFilter": "latest"
}

 

  • The rule set/products to analyse:

    • Financial Services - Brand Marketing

    • Financial Services - Discretionary Asset Management

    • Financial Instruments - Investment Funds.
  • The regimes:

    • Belgium (BEL)

    • Chile (CHL)

    • Saudi Arabia (SAU)

    • South Africa (ZAF)

  • The version filter: selects the latest available versions of the mentioned rule sets and regimes.

 

Further readings

Was this article 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 ticket