Roles and Journeys

This section describes the definition structure of user roles and journeys in a network.

Roles

A role is a fundamental element of TuumIO Protocol that represents a specific participant type, such as patients or doctors. Each role is defined with the corresponding cards and events.

Field Name	Value Type	Description
id	string	The unique ID of the role.
name	string	The name of the role.
description	string	The description of the role.
type	string	The role type is defined in the platform.
status	string	The status of the role is set to Active.
version	number	The role's version number is updated when the role metadata value changes.
td_collections	array	The transactional data records are linked to the role.
allow_events_with_role	array	The events allowed for the role.
home_card_ref_id	string	The reference ID to the home card for the role.

Example:

        "roles": [
            {
                "id": "rl-patient",
                "name": "PATIENT",
                "description": "The patient user role.",
                "type": "Wallet",
                "status": "Active",
                "version": 1,
                "allow_events_with_role": [],
                "home_card_ref_id": "cd-h-patient"
            },
            {
                "id": "rl-doctor",
                "name": "DOCTOR",
                "description": "The Doctor user role.",
                "type": "Wallet",
                "status": "Active",
                "version": 1,
                "allow_events_with_role": [],
                "home_card_ref_id": "cd-h-doctor"
            }
            
        ],

Journeys

A journey is a sequence of interconnected cards, defining a specific workflow for a role or network.

Field Name	Value Type	Description
id	string	The unique ID of the journey.
icon	string	The path to the icon image file.
name	string	The name of the journey.
description	string	The description of the journey.
status	string	The status of the journey is set to Active.
start_card_ref_id	string	The reference ID of the journey starting card.
roles	string	The roles involved in the journey.
journey_data	array	The data model for synchronizing across multiple roles or nodes, triggered by events. See Journey data model.
journey_type	string	The journey type is defined in the platform.

Journey definitions

The following example shows the "Get Started" and the "Join as Doctor" journeys.

Example:

        "journeys": [
            {
                "id": "jn-start-journey",
                "icon": "",
                "name": "Get Started",
                "description": "Start journey for Patient",
                "status": "Active",
                "start_card_ref_id": "cd-start-rl-patient",
                "roles": ["rl-patient"],
                "journey_data": [],
                "journey_type": "STANDARD_JOURNEY"
            },
            {
                "id": "jn-rl-doctor",
                "icon": "",
                "name": "Join as Doctor",
                "description": "Join as Doctor",
                "status": "Active",
                "start_card_ref_id": "cd-invite-rl-doctor",
                "roles": ["rl-doctor"],
                "journey_data": [],
                "journey_type": "JOIN_NETWORK_JOURNEY"
            },

Journey data model

Here is another example of a "Book Appointment" journey that defines the events, roles, and permissions for synchronizing data across multiple nodes.

Field Name	Value Type	Description
name	string	The unique name of the journey data model.
start_event_ids	array	The IDs of start events that trigger data sharing and synchronization. Note: Only the user role with OWNER access can submit the start (init) event.
stop_event_ids	array	The IDs of stop events with shared data in the payload, completing the synchronization to all nodes.
affected_collections	array	The data collections where payload data is saved.
expire_in	string	The number of days (d), weeks (w), or years (y) from initialization until synchronization is stopped.
permissions	array	The list of roles and corresponding access permissions.
role	string	The reference ID of each role defined in the journey.
access	string	The access level permission set for each role.

Example:

{
        "id": "book-appointment-journey",
        "name": "Book Appointment",
        "description": "Book Appointment",
        "status": "Active",
        "start_card_ref_id": "get-records-list-card",
        "roles": ["patient", "doctor", "nurse"],
        "journey_data": [
          {
            "name": "jdm-001-data-01",
            "start_event_ids": [
              "e-w-broad-patient-to-rl-xxx",
              "e-w-pt-confirm-appt"
            ],
            "stop_event_ids": [
              "e-w-pt-confirm-appt-fee"
            ],
            "affected_collections": [
              "td/td-BOOKING.json"
            ],
            "expire_in": "1d",
            "permissions": [
              {
                "role": "rl-PATIENT",
                "access": "OWNER"
              },
              {
                "role": "rl-DOCTOR",
                "access": "READ"
              },
              {
                "role": "rl-NURSE",
                "access": "DELEGATION"
              }
            ]
          }
        ],
        "journey_type": "STANDARD_JOURNEY"
      }