Events and Event Handlers

This section describes the structure of event and event handler definitions, and some examples for the different types of events and event handlers.

All event and event handler definitions must be included in the input.json file.

Events

An event represents the actions that occur based on user interactions within a network. It defines the data used to communicate between roles or nodes in the network, such as sending and receiving information.

Types of events

• WALLET_LOCAL — A local event within TuumIO Wallet, such as sending data from one card to another.

• WALLET_FROM_NODE — An event that gets data from a specific node, such as retrieving a list of records in TuumIO Wallet.

• WALLET_TO_NODE — An event that sends data from TuumIO Wallet to a specific node, such as submitting records.

• NODE_TO_NODE — An event that sends data from one node to another node, such as a patient booking an appointment with a doctor.

• NODE_TO_ROLE — An event that sends data to all nodes with a designated role in a network, such as a patient searching for the nearest pediatrician among all doctors in the network.

Field Name	Value Type	Description
id	string	The unique ID of the event.
name	string	The name of the event.
description	string	The description of the event.
code	string	The same as the event name.
status	string	The status of the event is set to Active.
type	string	The type of event. The possible values are WALLET_LOCAL, WALLET_FROM_NODE, WALLET_TO_NODE, NODE_TO_NODE and NODE_TO_ROLE.
event_definition_ref	string	The reference path and ID of the event definition.
submit_event_handler	string	The ID of the event handler used for submitting the event.
node_event_handlers	array	The list of outgoing event handlers for node events.
card	string	The reference ID of the card associated to the event.

The following example represents an event that lets users navigate from one card to another, as defined in the input.json file.

Example:

        "events": [
            {
                "id": "ev-patient-nav-to-cd-next",
                "name": "W.PATIENT.NAV.CD-NEXT",
                "description": "Event to navigate from start card to next card",
                "code": "W.PATIENT.NAV.CD-NEXT",
                "status": "Active",
                "type": "WALLET_LOCAL",
                "event_definition_ref": "event/ev-patient-nav-to-cd-next.json",
                "submit_event_handler": "eh-w-ev-patient-nav-to-cd-next",
                "node_event_handlers": [],
                "card": "cd-start-rl-patient"
            },

The following example defines an event containing user details: event/ev-patient-nav-to-cd-next.json.

Example:

{
  "definition": {
    "description": "Get started",
    "name": "GET_STARTED",
    "resource": "GET_STARTED",
    "type": "EVENT_DATA"
  },
  "structure": {
    "attributes": [
      {
        "code": "answer",
        "name": "answer",
        "type_definition": {
          "type": "number"
        },
        "order": 3,
        "system": false,
        "required": false
      },

      {
        "code": "memberId",
        "name": "memberId",
        "type_definition": {
          "type": "string"
        },
        "order": 1,
        "system": false,
        "required": false
      }
    ]
  }
}

Event handlers

The event handler defines the instructions that execute tasks based on specific events, such as navigation and data manipulation.

Types of event handlers

• WALLET_EVENT_HANDLER — This event handler is defined in JSON and can be used to navigate between cards, submit data, or retrieve data.

• NODE_EVENT_HANDLER — This event handler is defined in either JSON or Python and can be used to search, retrieve, update, or save data. To learn more about the different types of node event handlers, see Node Event Handlers and Python Event Handlers.

Field Name	Value Type	Description
id	string	The unique ID of the event handler.
name	string	The name of the event handler.
description	string	The description of the event handler.
status	string	The status of the event handler is set to Active.
event	string	The event which the event handler executes.
type	string	The type of event handler. The possible values are: WALLET_EVENT_HANDLER and NODE_EVENT_HANDLER
event_handler_definition_ref	string	The reference path and ID of the event handler definition.

The following example is the wallet event handler for navigating to the next card, as defined in the input.json file.

Example:

        "event_handlers": [
            {
                "id": "eh-w-patient-nav-to-cd-next",
                "name": "W.PATIENT.NAV.CD-NEXT",
                "description": "Wallet Event Handler to Navigate from Start to cd-next",
                "status": "Active",
                "event": "ev-patient-nav-to-cd-next",
                "type": "WALLET_EVENT_HANDLER",
                "event_handler_definition_ref": "event-handler/eh-w-ev-patient-nav-to-cd-next.json"
            },

The following example is an event handler definition in a JSON file that sends the details to the next card in the sequence: event-handler/eh-w-ev-patient-nav-to-cd-next1.json.

Example:

{
    "walletEventHandler": [
        {
            "refId": "ev-patient-nav-to-cd-next",
            "walletEvents": [
                {
                    "actions": [
                        {
                            "name": "submit",
                            "order": 1,
                            "parameter": [
                                {
                                    "method": "POST",
                                    "url": "/events"
                                }
                            ]
                        }
                    ],
                    "postAction": "cd-next",
                    "refId": "ev-patient-nav-to-cd-next"
                }
            ]
        }
    ]
}

Use case examples

Submitting health questions

In this example, a patient submits answers from the health questions card and the data is saved in a collection.

1. Define the events in the input.json file. Here, we have two events:

Example:

            {
                "id": "ev-w-broad-health-questions",
                "name": "W.BROAD.H.QUESTIONS",
                "description": "Submit health questions",
                "code": "W.BROAD.H.QUESTIONS",
                "status": "Active",
                "type": "WALLET_TO_NODE",
                "event_definition_ref": "event/ev-w-broad-health-questions.json",
                "submit_event_handler": "eh-ev-w-broad-health-questions",
                "next_event": "ev-w-broad-health-questions-na",
                "node_event_handlers": [
                    "eh-n-ev-w-broad-health-questions", "eh-n-patient-process-py"
                ],
                "card": "cd-health-questions"
            },
            {
                "id": "ev-w-broad-health-questions-na",
                "name": "W.BROAD.H.QUESTIONS.NA",
                "description": "Broadcast health questions from Patients to rl-netadmin",
                "code": "W.BROAD.H.QUESTIONS.NA",
                "status": "Active",
                "type": "NODE_TO_ROLE",
                "event_definition_ref": "event/ev-w-broad-health-questions-na.json",
                "from_role": "rl-patient",
                "to_role": "rl-netadmin",
                "node_event_handlers": [
                    "eh-n-ev-w-broad-health-questions-na"
                ],
                "card": "cd-health-questions"
            },

2. Create the event definition for the submit event that contains the data used in the patient health questions: event/ev-w-broad-health-questions.json.

Example:

{
    "definition": {
        "description": "Save H_QUESTIONS at Patients",
        "name": "W-BROAD-H-QUESTIONS",
        "resource": "W-BROAD-H-QUESTIONS",
        "type": "EVENT_DATA"
    },
    "structure": {
        "attributes": [
            {
                "name": "Symptoms",
                "type_definition": {
                    "type": "string"
                },
                "required": false,
                "system": false,
                "code": "Symptoms",
                "order": 1
            },
            {
                "name": "History",
                "type_definition": {
                    "type": "string"
                },
                "required": false,
                "system": false,
                "code": "History",
                "order": 2
            },
            {
                "name": "Gender",
                "type_definition": {
                    "type": "string"
                },
                "required": true,
                "system": false,
                "code": "Gender",
                "order": 3
            },
            {
                "name": "Age",
                "type_definition": {
                    "type": "number"
                },
                "required": true,
                "system": false,
                "times": 1,
                "code": "Age",
                "order": 4
            },
            {
                "code": "transactionalGuid",
                "name": "transactionalGuid",
                "type_definition": {
                    "type": "string"
                },
                "required": false,
                "system": false,
                "times": 1,
                "order": 5
            },
            {
                "code": "createdAt",
                "name": "createdAt",
                "type_definition": {
                    "type": "timestamp"
                },
                "required": false,
                "system": false,
                "times": 1,
                "order": 6
            },
            {
                "name": "senderNodeAddress",
                "code": "senderNodeAddress",
                "type_definition": {
                    "type": "string"
                },
                "required": false,
                "system": false,
                "order": 7
            }
        ],
        "primary_key": "false"
    }
}

3. Define the event handlers for the submit event in the input.json file. Here, the submit event has two event handlers: eh-ev-w-broad-health-questions.json and eh-n-ev-w-broad-health-questions.json.

Example:

            {
                "id": "eh-ev-w-broad-health-questions",
                "name": "eh-ev-w-broad-health-questions",
                "description": "Submit H_Questions",
                "status": "Active",
                "event": "ev-w-broad-health-questions",
                "type": "WALLET_EVENT_HANDLER",
                "event_handler_definition_ref": "event-handler/eh-ev-w-broad-health-questions.json"
            },
            {
                "id": "eh-n-ev-w-broad-health-questions",
                "name": "eh-n-ev-w-broad-health-questions",
                "description": "Broadcast H_QUESTIONS from Patients to rl-netadmin",
                "status": "Active",
                "event": "ev-w-broad-health-questions",
                "type": "NODE_EVENT_HANDLER",
                "event_handler_definition_ref": "event-handler/eh-n-ev-w-broad-health-questions.json"
            },

4. Create the wallet event handler definition for submitting the event data: event-handler/eh-ev-w-broad-health-questions.json.

Example:

{
    "walletEventHandler": [
        {
            "refId": "ev-w-broad-health-questions",
            "walletEvents": [
                {
                    "actions": [
                        {
                            "name": "submit",
                            "order": 1,
                            "parameter": [
                                {
                                    "method": "POST",
                                    "url": "/events"
                                }
                            ]
                        }
                    ],
                    "postAction": "cd-health-questions-done",
                    "refId": "ev-w-broad-health-questions"
                } 
            ]
        }
    ]
}

5. Create the node event handler definition for saving the event payload: eh-n-ev-w-broad-health-questions.json.

Example:

{
    "nodeEventHandlers": [
        {
            "type": "MAPPER",
            "name": "Append or Exclude attributes to H_QUESTIONS payload",
            "order": 1,
            "dataSource": "EVENT_PAYLOAD",
            "additionalAttributes": {
                "createdAt": {
                    "source": "GENERATED",
                    "value": "CURRENT_TIMESTAMP"
                },
                "transactionalGuid": {
                    "source": "GENERATED",
                    "value": "UUID"
                },
                "senderNodeAddress": {
                    "source": "EVENT",
                    "value": "SENDER"
                }
            },
            "excludedAttributes": []
        },
        {
            "type": "VAULT_INSERT",
            "name": "H_QUESTIONS",
            "order": 2,
            "collection": "H_QUESTIONS",
            "collectionVersion": 1,
            "dataSource": "HANDLER_ARGUMENTS",
            "handlerOutput": "PERSISTED_ENTITY"
        },
        {
            "type": "MAPPER",
            "name": "Append or Exclude attributes in the result",
            "order": 3,
            "dataSource": "EVENT_PAYLOAD",
            "additionalAttributes": {
                "createdAt": {
                    "source": "HANDLER_ARGUMENTS",
                    "value": "createdAt"
                },
                "transactionalGuid": {
                    "source": "HANDLER_ARGUMENTS",
                    "value": "transactionalGuid"
                },
                "senderNodeAddress": {
                    "source": "EVENT",
                    "value": "SENDER"
                }
            },
            "excludedAttributes": []
        }
    ]
}

6. Create the event definition for the next event: ev-w-broad-health-questions-na.json.

{
    "definition": {
        "description": "Save H_QUESTIONS at PATIENT_ANSWERS",
        "name": "W-BROAD-H-QUESTIONS",
        "resource": "W-BROAD-H-QUESTIONS",
        "type": "EVENT_DATA"
    },
    "structure": {
        "attributes": [
            {
                "name": "Symptoms",
                "type_definition": {
                    "type": "string"
                },
                "required": false,
                "system": false,
                "code": "Symptoms",
                "order": 1
            },
            {
                "name": "History",
                "type_definition": {
                    "type": "string"
                },
                "required": false,
                "system": false,
                "code": "History",
                "order": 2
            },
            {
                "name": "Gender",
                "type_definition": {
                    "type": "string"
                },
                "required": true,
                "system": false,
                "code": "Gender",
                "order": 3
            },
            {
                "name": "Age",
                "type_definition": {
                    "type": "number"
                },
                "required": true,
                "system": false,
                "times": 1,
                "code": "Age",
                "order": 4
            },
            {
                "code": "transactionalGuid",
                "name": "transactionalGuid",
                "type_definition": {
                    "type": "string"
                },
                "required": false,
                "system": false,
                "times": 1,
                "order": 5
            },
            {
                "code": "createdAt",
                "name": "createdAt",
                "type_definition": {
                    "type": "timestamp"
                },
                "required": false,
                "system": false,
                "times": 1,
                "order": 6
            },
            {
                "name": "senderNodeAddress",
                "code": "senderNodeAddress",
                "type_definition": {
                    "type": "string"
                },
                "required": false,
                "system": false,
                "order": 7
            }
        ],
        "primary_key": "false"
    }
}

7. Define the event handler for the next event in the input.json file. The next event has one event handler: eh-n-ev-w-broad-health-questions-na.json.

            {
                "id": "eh-n-ev-w-broad-health-questions-na",
                "name": "eh-n-ev-w-broad-health-questions-na",
                "description": "Broadcast H_QUESTIONS from Patients to rl-netadmin",
                "status": "Active",
                "event": "ev-w-broad-health-questions-na",
                "type": "NODE_EVENT_HANDLER",
                "event_handler_definition_ref": "event-handler/eh-n-ev-w-broad-health-questions-na.json"
            }

8. Create the node event handler definition that saves the event data to the collection: event-handler/eh-ev-n-broad-health-questions-na.json. Here, the data is saved to the PATIENT_ANSWERS collection based on the defined search criteria.

{
    "nodeEventHandlers": [
        {
            "type": "MAPPER",
            "name": "Append or Exclude attributes to H_QUESTIONS payload",
            "order": 1,
            "dataSource": "EVENT_PAYLOAD",
            "additionalAttributes": {},
            "excludedAttributes": []
        },
        {
            "type": "VAULT_UPDATE",
            "name": "PATIENT_ANSWERS",
            "order": 2,
            "collection": "PATIENT_ANSWERS",
            "collectionVersion": 1,
            "dataSource": "HANDLER_ARGUMENTS",
            "insertIfAbsent": true,
            "searchCriteria": [
                {
                    "queryMatcher": "EQUAL",
                    "fieldName": "senderNodeAddress",
                    "dynamicValue": {
                        "source": "EVENT_PAYLOAD",
                        "value": "senderNodeAddress"
                    }
                }
            ],
            "handlerOutput": "PERSISTED_ENTITY"
        }
    ]
}

Viewing records history

In this example, the wallet retrieves the history of records from a data collection and displays it on the card.

1. Define the event in the input.json file.

Example:

            {
                "id": "ev-get-records-history",
                "name": "W.GET.RECORDS.HIST",
                "code": "W.GET.RECORDS.HIST",
                "description": "Get Records History",
                "status": "Active",
                "type": "WALLET_FROM_NODE",
                "event_definition_ref": "event/ev-get-records-history.json",
                "submit_event_handler": "eh-ev-get-records-history",
                "node_event_handlers": [],
                "card": "cd-view-records"
            }

2. Create the event definition with the source of data: event/ev-get-records-history.json. To retrieve data, this event uses the unique ID of the transactionalGuid generated from a submit event.

Example:

{
    "definition": {
        "description": "Get Records History",
        "name": "Get Records History",
        "resource": "Get Records History",
        "type": "EVENT_DATA"
    },
    "structure": {
        "attributes": [
            {
                "code": "transactionalGuid",
                "name": "transactionalGuid",
                "type_definition": {
                    "type": "string"
                },
                "order": 1,
                "system": false,
                "required": false
            }
        ]
    }
}

3. Define the event handler in the input.json file.

Example:

            {
                "id": "eh-ev-get-records-history",
                "name": "eh-ev-get-records-history",
                "description": "eh-ev-get-records-history",
                "status": "Active",
                "event": "ev-get-records-history",
                "type": "WALLET_EVENT_HANDLER",
                "event_handler_definition_ref": "event-handler/eh-ev-get-records-history.json"
            }   

4. Create the wallet event handler definition that gets the records history data from the collection: event-handler/eh-ev-get-records-history.json. This event handler uses the GET method to retrieve record data based on the filter query.

Example:

{
    "walletEventHandler": [
        {
            "refId": "ev-get-records-history",
            "walletEvents": [
                {
                    "actions": [
                        {
                            "name": "",
                            "order": 1,
                            "parameter": [
                                {
                                    "method": "GET",
                                    "url": "/transactions/RECORD_DATA?filter=[{\"queryMatcher\":\"EQUAL\",\"fieldName\":\"senderNodeAddress\",\"value\":\"${senderNodeAddress}\"}]"
                                }
                            ]
                        }
                    ],
                    "postAction": "",
                    "refId": "ev-get-records-history"
                }
            ]
        }
    ]
}