Remiges Products » Crux: BRE/WFE

# Algorithms and data structures for the flow engine

{{>toc}}

This page is best understood only after studyihg [[cruximplement|the algorithms and data structures of the BRE]].

Here too, we need a rules schema, rulesets and a matching engine.

## Rules schema

In the BRE, each rules schema has two parts: the pattern schema and the action schema. Each `rulesschema` block is tagged with a `class` attribute, specifying which class the schema applies to. There is one rules schema for each class of entities.

In the flow engine, there is no `class` -- there is a `process` instead. A workflow schema applies to a process.

The pattern schema specification is identical here to that used in the BRE. 

In the flow engine, there is no `actionschema`, but a `flowschema`. The flow schema is much simpler than an action schema. The output of a flow engine matching exercise is just the ID of one step. Therefore the flow schema here is a list of possible steps.

``` json

"ruleschema": {

    "process": "customerkyc",

    "patternschema": {

        "attr": [{

            "name": "accttype",

            "type": "enum",

            "vals": [ "savings", "current", "recurring", "fixeddeposit", "ppf" ]

        },{

            "name": "acctholdertype",

            "type": "enum",

            "vals": [ "individual", "joint", "corporate", "hinduundivided", "partnership" ]

        },{

            "name": "branchtype",

            "type": "enum",

            "vals": [ "urban", "semirural", "rural" ]

        },{

            "name": "branchcode",

            "type": "str"

        },{

            "name": "refererquality",

            "type": "int",

            "valmin": 0,

            "valmax": 5

        },{

            "name": "districtcode",

            "type": "int"

        }]

    }

    "flowschema": {

        "steps": [ "initialdoc", "aadhaarcheck", "creditbureauchk", "pancheck", "bankdetails", "referenchk", "complete" ]

    }

}

```

In the example above:

* `class` of the business rules schema is replaced with `process`

* `patternschema` remains unchanged

* `actionschema` is replaced with `flowschema` and the structure of `flowschema` is just one array of words. Each word here is an ID of a step. So, the `flowschema.steps` lists all the valid steps which the flow engine may return after matching an entity with the rules. The array of words in the`steps` array is totally irrelevant; treat it as a set, not an array.

The example above attempts to illustrate what a workflow may incorporate when a customer is applying to open a bank account and the workflow engine is guiding the processing centre about the sequence of steps to follow to complete the applicant's KYC (Know Your Customer) process. In this example, the workflow decisions will be taken based on the following parameters of the application:

* `accttype`: whether the account being opened is a current account, a savings account, *etc*

* `acctholdertype`: whether the applicant is an individual, a Hindu Undivided Family, an incorporated company, a partnership firm, *etc*

* `branchtype`: whether the branch is in an urban area, a semi-rural area or a rural area -- customer assessment norms may be relaxed or done quite differently for rural and urban areas

* `branchcode`: an integer code which has been assigned for each branch. With this attribute, it is possible to define patterns which match specific branches

* `refererquality`: an integer which, it is assumed, will have a higher value if the quality of the referer is higher in the bank's eyes

* `districtcode: an integer uniquely identifying the district where the applicant is located; customer KYC norms may differ from district to district

This set of six attributes of each account opening application can form a solid foundation to define a rich set of rules of how the KYC process will proceed.

In addition there will always be one additional attribute in the pattern section of each rule -- the `step`. This will specify the current `step` the process is on. The ruleset(s) will look at all the other attributes, the current step the process is at, and will attempt to come up with a specification of the next step to execute. That's the entire *raison d'etre* for a workflow engine.

## Specifying a ruleset

The following is a hyopthetical ruleset for the process `customerkyc`.

``` json

"ruleset": {

    "ver": 4,

    "process": "customerkyc",

    "setname": "prioritylending",

    "rules": [{

        "rulepattern": {

            "step": "initialdoc",

            "attrs": [{

                "attr": "branchtype",

                "op": "eq",

                "val": "rural",

            },{

                "attr": "accttype",

                "op": "eq",

                "val": "savings"

            }]

        },

        "rulenextstep": "aadharchk",

        "call": ""

    },{

        "rulepattern": {

            "step": "initialdoc",

            "attrs": [{

                "attr": "branchtype",

                "op": "eq",

                "val": "semirural"

            },{

                "attr": "accttype",

                "op": "ne",

                "val": "ppf"

            }]

        },

        "call": "overseaskyc",

        "rulenextstep": ""

    },{

        :

    }],

}

```

Each `ruleset` has a perpetually-incrementing integer attribute called `ver`. This tracks changes to the ruleset. The ruleset also has

* `process`, which names a process, and

* `setname`, which specifies the ruleset name

* `rules`, which is an array of rules.

In the `rules` array, each element is a rule, and a rule has two parts:

* `rulepattern` which lists various attributes to match

* a what-to-do part, which means either a `rulenextstep` which specifies the next step or a `call` which specifies another ruleset to call

Inside the `rulepattern`, there is an array of attributes and values, which are used for matching. There is one special attribute, called `step`, which specifies the state of the caller in the process. The attribute `step` is not listed in the `patternschema`. The term `"step": "initialdoc"` actually is a shorthand for

``` json

{

    "attr": "step",

    "op": "eq",

    "val": "initialdoc"

}

```

Just like the special attribute `step`, there is another special attribute `stepfailed` which is not listed in `patternschema`. This is a special attribute of type `bool`. It may be specified by the caller when calling the flow engine, with `"stepfailed": "true"`. The meaning of this attribute is that the previous step failed. This is an extra facility for the workflow author to decide whether to take the flow engine along a different path and come up with a different value for `rulenextstep`. The attribute may also be specified with `"stepfailed": "false"`, as needed. The term `"step": "aadhaarchk", "stepfailed": "true"` means that the last step in the workflow which was attempted was the Aadhaar identity check, and that step failed. It is shorthand for

``` json

[{

    "attr": "step",

    "op": "eq",

    "val": "aadhaarchk"

},{

    "attr": "stepfailed",

    "op": "eq",

    "val": "true"

}]

```

Each rule can end with **either** the ID of a next step, **or** a ruleset to call. Since the matching engine for workflow follows the FIRST-MATCH algorithm, it unwinds from all subroutine calls and nestings as soon as it matches a rule with a `rulenextstep`.

The step ID in `rulenextstep` can have a special value not listed in `flowschema.steps`. This value is `END`. If `rulenextstep` has this value, it tells the caller that the workflow for this process is complete. The caller then is expected to stop calling the flow engine asking for what-next.

## The `queryWFE()` function (can be renamed...)