Rules Engine Silo

Introduction

To enable a more flexible configuration of the backend, Use-Case and especially customer-specific logic can be kept outside of standard code by creating rules: event-handlers for specific scenarios.

Getting Started

Authentication

For authentication with gcloud functionality, like google cloud storage for images, please run the following command from your dev machine:

gcloud auth application-default login

And allow it to connect to your sstid.com account.

This will authenticate any app running locally, (e.g. from VSCode) to use your user account to authenticate. To give permissions to a user account go to https://console.cloud.google.com/iam-admin/iam?project=backbone-168621 and add the approrpiate roles.

These are the required roles at this time:

• File Storage : Storage Object Admin role (or Storage Admin role)

Rules

The Rules Engine uses a case-insensitive folder-structure based organization of rules, which are loaded from the rules folder at startup. Directly in the root of that folder, you can have generic rules, per event, that apply to all use cases, and all customers. The filenames should match the verb, namespace, relation, and optionally status and action value of the events (message queue messages) they handle.

Additionally, the rules folder can contain folders, again preferably with the same naming scheme of the events they apply to. These event folders should contain zero or more files named for the Use-Cases they apply to, or the specific functionality they implement.

e.g.:

• rules
  • create_security_user_success.js
  • CREATE_SECURITY_USER_SUCCESS
    • rex.js
    • strategicRfid.js
    • rex
      • disney.js
  • CREATE_REX_RMA_SUCCESS
    • rex.js
    • rex
      • autoPlus.js
      • disney.js
    • preventDuplicates.js

The rules engine will automatically build a workflow by comparing the incomming userContext with the rules, and will build a pipeline by expanding the incomming verb as follows:

• get
  • willGet, get, got (executed synchronously)
  • get_..._..._success (executed asynchronously after completing the above successfully)
• create
  • willCreate, create, created (executed in order, synchronously)
  • create_..._..._success (executed asynchronously after completing the above successfully)
• update
  • willUpdate, update, updated (executed in order, synchronously)
  • update_..._..._success (executed asynchronously after completing the above successfully)
• remove
  • willRemove, remove, removed (executed in order, synchronously)
  • remove_..._..._success (executed asynchronously after completing the above successfully)
• count
  • willCount, count, counted (executed in order, synchronously)
  • count_..._..._success (executed asynchronously after completing the above successfully)

Create your own Rules

Apart from being organized in the described folder/file structure, rules are expected to have the following effective outline:

/**
 * @typedef Rule
 * @property {string} verb e.g. 'willGet', 'get', 'got', 'willCreate', 'create', 'created', etc
 * @property {string} [namespace] e.g. 'item', applies to all namespaces if not provided
 * @property {string} [relation] e.g. 'type', applies to all relations if not provided
 * @property {Object[]} [excludeNamespaceRelations] if no namespace/relations defined, these relations will be excluded
 * @property {string} excludeNamespaceRelations.namespace
 * @property {string} excludeNamespaceRelations.relation
 * @property {'success'|'fail'} [status]
 * @property {string} [action] e.g. 'heartbeat', 'content', etc
 * @property {number} priority smaller numbers mean lower priority. Rules with higher priority for the same verb get executed first
 * @property {string} description
 * @property {string[]} [useCaseNames] e.g. 'Lot Management' or `REX` or 'FLAIR'
 * @property {string[]} [excludeUseCases] not applicable if useCaseNames are provided
 * @property {string[]} [tenantNames] e.g. `Kefi` or 'Office Depot'
 * @property {string[]} [excludeTenantNames] not applicable if tenantNames are provided
 * @property {function[]} [prerequisites]   See exsting rules for examples
 * @property {function} logic  //the actual logic
  * /

Notes:

• The response from logic is optional, if no response is returned, the input message is automatically used as result
• aborting
  • Throwing an error in logic or prerequisite code will abort the entire workflow
  • Returning an object in the form of { abort: { message: 'your reason to abort goes here' } } will end stop a prerequisite sub-workflow, but allows continueing the rest of the workflow.

Build and Test

Unit tests

Unit test files must be named *.unit.js for the testing tool to pick them up. To execute all unit tests, you can run npm run test or npm run test:unit.

Integration tests

Integration test files must be named *.integration.js for the testing tool to pick them up. To execute all integration tests, you can run npm run test:integration

All tests

To execute all tests, run npm run test:all If you'd like to see code coverage reports, pass true after any test command: npm run test:unit true

#Contribute

Git Repository: https://sstdev.visualstudio.com/DefaultCollection/Backbone/_git/silo_rules-engine