Node Event Handlers

This section describes the different types of node event handlers, their definitions, parameters, and examples.

Types of node event handlers

• VAULT_INSERT — This event handler is used to insert a record into a specific collection in the vault.

• VAULT_UPDATE — This event handler is used to update a record in a specific collection in the vault based on the dynamic search criteria.

• MAPPER — This event handler is used for data transformation, such as excluding, appending, or generating data in the execution chain.

• NEXT_EVENT_RECIPIENT — This event handler is used to identify the recipient for the next event.

• EXPRESSION_LANGUAGE — This event handler allows writing data manipulation expressions to easily access, filter, and calculate values.

• CUSTOM — This event handler is used to specify a specific Java class that implements a legacy JAR (Java Archive) handler.

Handler definition constants

Handler data source (GenericHandlerDataSource)

• EMPTY— An empty source or collection.

• EVENT_PAYLOAD — The payload source of events processed in the handlers chain.

• HANDLER_ARGUMENTS — The response value from the previous handler in the chain.

• PERSISTED_ENTITY — For vault-related handlers, it is the state of inserted or updated documents in a collection.

Dynamic handler value (DynamicHandlerValue)

It uses "source" and "value" fields to link data. The actual value can be determined dynamically based on the information in the "source" field. Here are the possible values:

Source	Possible values	Description
CONSTANT	Any value	The constant propagates the value field as a result.
GENERATED	UUID, CURRENT_TIMESTAMP	It generates a UUID or timestamp.
EVENT	SENDER, RECIPIENT, CODE, TIMESTAMP, CORRELATION_ID	It gets the value of the original event sender, recipient, code, timestamp, or correlation ID.
EVENT_PAYLOAD	Attribute name	It gets the value of the attribute in the event payload.
HANDLER_ARGUMENTS	Attribute name	It gets the value of the attribute in the handler arguments.

Handler definition examples

Vault Insert handler

Parameters	Data type / Values	Description
type	VAULT_INSERT	The handler type.
order	Integer	The order of the handler in the execution chain.
name	String	The name of the handler which is used for logging.
collection	String	The name of the vault collection.
collectionVersion	Integer	The version of the vault collection.
dataSource	EMPTY, EVENT_PAYLOAD, HANDLER_ARGUMENTS	The data source of the record which will be inserted into the collection.
handlerOutput	EMPTY, EVENT_PAYLOAD, HANDLER_ARGUMENTS, PERSISTED_ENTITY	The handler output that will be passed as an argument to the next handler.

Example:

    {
      "type": "VAULT_INSERT",
      "name": "Insert SAMPLE record",
      "order": 2,
      "collection": "SAMPLE",
      "collectionVersion": 1,
      "dataSource": "HANDLER_ARGUMENTS",
      "handlerOutput": "PERSISTED_ENTITY"
    }

Vault Update handler

Parameters	Data type / Values	Description
type	VAULT_UPDATE	The handler type.
order	Integer	The order of the handler in the execution chain.
name	String	The name of the handler which is used for logging.
collection	String	The name of the vault collection.
collectionVersion	Integer	The version of the vault collection.
dataSource	EMPTY, EVENT_PAYLOAD, HANDLER_ARGUMENTS	The data source from which the record changes (diffs) will be retrieved.
handlerOutput	EMPTY, EVENT_PAYLOAD, HANDLER_ARGUMENTS, PERSISTED_ENTITY	The handler output that will be passed as an argument to the next handler.
insertIfAbsent	Boolean	It defines a flag that inserts the document if it does not exist in the collection based on the search criteria. The value is set to false by default.
searchCriteria	Array of SearchQueryFilter	The search criteria to find the document to be updated.

Example:

    {
      "type": "VAULT_UPDATE",
      "name": "Answer SAMPLE question",
      "order": 1,
      "collection": "SAMPLE",
      "collectionVersion": 1,
      "dataSource": "EVENT_PAYLOAD",
      "searchCriteria": [
        {
          "queryMatcher": "EQUAL",
          "fieldName": "transactionalGuid",
          "dynamicValue": {
            "source": "EVENT_PAYLOAD",
            "value": "transactionalGuid"
          }
        }
      ],
      "handlerOutput": "PERSISTED_ENTITY"
    }

Data Transformation handler

Parameters	Data type / Values	Description
type	MAPPER	The handler type.
order	Integer	The order of the handler in the execution chain.
name	String	The name of the handler which is used for logging.
dataSource	EMPTY, EVENT_PAYLOAD, HANDLER_ARGUMENTS	The data source for the unmapped data.
handlerOutput	EMPTY, EVENT_PAYLOAD, HANDLER_ARGUMENTS, PERSISTED_ENTITY	The handler output that will be passed as an argument to the next handler.
excludedAttributes	Array of strings	A set of attributes to be excluded from the input data.
additionalAttributes	Map of DynamicHandlerValue (see Dynamic handler value)	A map of attributes with dynamic values calculated at runtime.

Example:

    {
      "type": "MAPPER",
      "name": "Append SAMPLE payload",
      "order": 1,
      "dataSource": "EVENT_PAYLOAD",
      "additionalAttributes": {
        "createdAt": {
          "source": "GENERATED",
          "value": "CURRENT_TIMESTAMP"
        },
        "transactionalGuid": {
          "source": "GENERATED",
          "value": "UUID"
        },
        "doctorNodeAddress": {
          "source": "EVENT",
          "value": "SENDER"
        }
      },
      "excludedAttributes": [
        "correlationId"
      ]
    }

Next Event Recipient handler

Parameters	Data type / Values	Description
type	NEXT_EVENT_RECIPIENT	The handler type.
order	Integer	The order of the handler in the execution chain.
name	String	The name of the handler which is used for logging.
handlerOutput	EMPTY, EVENT_PAYLOAD, HANDLER_ARGUMENTS	The handler output that will be passed as an argument to the next handler.
recipientAddress	DynamicHandlerValue (see Dynamic handler value)	The dynamic value represents the recipient of the next event.

Example:

    {
      "type": "NEXT_EVENT_RECIPIENT",
      "name": "Fetch SAMPLE target doctor",
      "order": 2,
      "recipientAddress": {
        "source": "HANDLER_ARGUMENTS",
        "value": "doctorNodeAddress"
      },
      "handlerOutput": "HANDLER_ARGUMENTS"
    }

Expression Language handler

The expression language used for this handler type is based on Spring Expression Language (SpEL). For more information, see the documentation for Spring Expression Language (SpEL).

Here are the operators supported in the language:

Type	Operators
Arithmetic	+, -, *, /, %, ^, div, mod
Relational	<, >, ==, !=, <=, >=, lt, gt, eq, ne, le, ge
Logical	and, or, not, &&, ||, !
Conditional	?:
Regex	matches

Here are the parameters in the event handler definition:

Parameter	Data type / Values	Description
type	EXPRESSION_LANGUAGE	The handler type.
order	Integer	The order of the handler in the execution chain.
name	String	The name of the handler which is used for logging.
dataSource	EMPTY, EVENT_PAYLOAD, HANDLER_ARGUMENTS	The data source of the record which will be inserted into the collection.
computedAttributes	Map of expressions, where the key is a variable name, and the value is the expression itself.	The handler executes the expression and puts the value inside the specified variable.

Example 1:

    {
      "type": "EXPRESSION_LANGUAGE",
      "name": "Calc",
      "order": 2,
      "dataSource": "EMPTY",
      "computedAttributes": {
        "c": "arguments['a']+arguments['b']"
      }
    }

In Example 1, let's assume that the HANDLER_ARGUMENTS has variables a and b. If the variables represent numeric values, such as a=1 and b=2, then the result will be 1+2=3. If the variables represent string values, such as a='1' and b='2', then the result will be '1'+'2'='12'.

Example 2:

    {
      "type": "EXPRESSION_LANGUAGE",
      "name": "Calc",
      "order": 2,
      "dataSource": "EMPTY",
      "computedAttributes": {
        "res": "arguments[users].?[country=='USA'].size()"
      }
    }

In Example 2, let's assume that the HANDLER_ARGUMENTS has a variable user, which represent a list with the following value:

    [
      {
        "name": "John",
        "country": "USA"
      },
      {
        "name": "Sam",
        "country": "Canada"
      },
    ]

The expression arguments[users].?[country=='USA'].size() will filter the items which has the country value set to "USA". Then it calculates the size, which returns the count. In this case, the result will be 1.

Example 3:

    {
      "type": "EXPRESSION_LANGUAGE",
      "name": "Calc",
      "order": 2,
      "dataSource": "EMPTY",
      "computedAttributes": {
        "res": "arguments[users].?[country=='USA'].size() > 0 ? 'USA_PRESENT' : 'USA_NOT_PRESENT'"
      }
    }

In Example 3, let's assume that the HANDLER_ARGUMENTS has a variable user, which represent a list with the following value:

    [
      {
        "name": "John",
        "country": "USA"
      },
      {
        "name": "Sam",
        "country": "Canada"
      },
    ]

The expression arguments[users].?[country=='USA'].size() > 0 ? 'USA_PRESENT' : 'USA_NOT_PRESENT' will filter the items which has the country value set to "USA". Then it calculates the size, which returns the count. In this case, the count is 1. If the count is greater than 0, then the result will be 'USA_PRESENT'.

Custom (JAR) handler

Parameter	Data type / Values	Description
type	CUSTOM	The handler type.
order	Integer	The order of the handler in the execution chain.
jarUrl	String	The URL where the JAR file with the handler implementation is stored.
className	String	The full Java class name that implements the corresponding interface.

Example:

  {
    "type": "CUSTOM",
    "order": 2,
    "jarUrl": "https://a.solvecare.net/artifactory/libs-snapshot-local/care/solve/generic/node/hello-world-handler/1.0.4-SNAPSHOT/hello-world-handler-1.0.4-20220406.133327-6.jar",
    "className": "care.solve.node.handler.demo.patient.PatientComputeBmiHandler"
  }