Collaboration Tutorial

Tutorial Overview

This tutorial shows the user how to create a collaboration type using VANTIQ Modelo. Collaboration Types are a high-level way of expressing a system of VANTIQ rules and procedures while writing a minimum of VAIL. Modelo provides a graphical interface for assembling activities such as starting a collaboration between users (collaborators) of a system, assigning users to a collaboration, notifying users to changes in the situation that initiated the collaboration, and, ultimately, closing the collaboration.

The tutorial lessons show the developer how to create a Collaboration Type that recognizes that a human patient has an elevated heart rate and creates a collaboration to appropriately respond to the unusual situation. The Collaboration Type includes the following activities:

All lessons assume the developer has a working knowledge of VANTIQ Modelo. It is recommended that a new developer completes the lessons in the Introductory Tutorial before starting the lessons in this tutorial. In addition, please see the Collaboration Overview guide for introductory information about the VANTIQ collaboration system.

1: Creating a Patient Project

This tutorial imagines a private service organization which monitors at-risk patients for unusual metabolic readings then determines the best course of action, if any, to bring the readings into safe ranges. The first task in building our collaboration type is to create a project in VANTIQ Modelo to assemble all the collaboration components.

Use the Projects button, select Create New Project and title the project “Patient”:

        PatientProject

The rest of the lessons take place inside this Modelo project.

2: Creating a Patient Data Type

Each patient definition is fairly simple: he or she will have a name, patient ID, current location, and a continuously updating heart rate. The next task is to define the data type for that patient.

Use the Add button to select Type…:

        AddType

Then use the New Type button to create the patient type:

        PatientDef

The Patient type contains four properties:

patientId must be designated as a Natural Key because we only want one Patient record for each patientId value (i.e. only one Patient for each simulated patient). Use the Natural Key link on the Editing Type page to designate Natural Keys. Further, because patientId is a Natural Key, it must also be added as an Index for the type. Use the + button next to the No Indexes are defined label on the Editing Type page to add patientId as an Index. When adding patientId as an Index, check the Is Index unique? box to ensure that only one Patient record is created for each patientId value.

Use the Save button to save the type parameters, then use the Save button at the top, left of Modelo to save the project.

3: Simulating Patient Data

If our private service organization actually existed, patient data would be updated in the VANTIQ system via sensor readings and geolocation devices. For our tutorial, we’ll write a small procedure that can be executed to make simulated changes in a patient’s data.

Use the Add button to select Procedure… then use the New Procedure button to create the new procedure:

        PatientProcDef

The UpdatePatient procedure is defined as follows:

PROCEDURE UpdatePatient(simHeartRate Integer)

// use a fixed point for the patient's location
VAR simLocation = {
    "type": "Point",
     "coordinates": [
        -122.0651683957521,
        37.90793522730274
     ]
}

// use a fixed patient ID value to refer to a single patient
VAR simPId = Context.username()

// if the patient already exists, just update the heart rate, otherwise create a new patient record
UPSERT Patient(name:"Mary Ono", patientId:simPId, location:simLocation, heartRate:simHeartRate)

Note: the VAR ‘simPId’ becomes the patientId, and is set to your VANTIQ user id. In future lessons, this patientId is used to send notifications to the VANTIQ mobile app. Your user ID may be different than your displayed user name; if so, it is displayed (along with your current namespace name) by clicking on the user name in the top right corner of Modelo.

This procedure takes one parameter, a patient’s heart rate, and either creates a new patient record if there isn’t one already or updates the patent’s heart rate with the user-supplied value. After saving the UpdatePatient procedure and clicking the Procedure: UpdatePatient rectangle in the Project Resource Graph pane, the Project Builder window looks like this:

        PatientProject1

To simulate a change in the patient’s heart rate, use the small Execute button at the top, right of the Procedure: UpdatePatient” pane to execute the procedure. The Specify parameters for Procedure “UpdatePatient” dialog is displayed:

        PatientUpdate

Enter a value of 80 for the heart rate, then use the Execute button to create an initial patient record in the VANTIQ system. We’ll execute this procedure again in Lesson 9 to simulate the start of a collaboration.

Use the Save button at the top, left of Modelo to save the project.

4: Creating a Collaboration Type

Now that there is patient data and a way to update a patient’s heart rate at will, the next task is to create our collaboration type.

Use the Add button to select Collaboration Type… then use the New Collaboration Type button to create a Collaboration Type named “MyCollaboration”:

        PatientProject2

Several parameters need to be changed in the right hand section titled Collaboration Type in the Collaboration Type: MyCollaboration pane:

        PatientEntityRoles

Use the OK button to save the Entity Role.

There are no Collaborator Roles necessary for this tutorial.

Now that the RateCollaboration parameters are configured, two parameters need to be changed in the InitiateCollaboration Activity Pattern titled “Initiate”. Activity Patterns, or activities for short, are the pre-defined building blocks of a collaboration type. The InitiateCollaboration activity is always present in a collaboration type and represents the start of any collaboration. The Initiate activity is displayed as a rectangle in the Collaboration Type graph:

        PatientInitiate

Click the Initiate rectangle to display its parameters in the right hand section. Change these three parameters:

        PatientInitiateConfiguration

Use the OK button to save the Configuration parameters.

With this lesson complete, a new collaboration instance is created whenever our simulated patient’s heart rate is out of the range of 40 to 150 BPM. Subsequent lessons add activities to react to an out of range situation.

Use the Save button at the top, left of Modelo to save the project.

5: Notifying the Patient

Once a patient’s unusual heart rate is detected, a collaboration instance is created by the VANTIQ system. The first follow-up task is to notify the patient of the unusual situation and allow her to provide a response that clarifies the situation. The notification is received by the VANTIQ mobile app, which is available in both iOS and Android versions.

In order to notify the patient, we’ll create a VANTIQ Client which contains two response buttons for the patient. To add a new Client, use the Add button to select Client… then use the New Client button to create a new Client named “PatientResponse” with a Design for mobile apps Layout Type.

        NewCB

Use the OK button to display the Client Builder:

        PatientCB

Drag and drop two Inline buttons from the widget palette to the Client Builder canvas. Tap on the top Inline button to display its properties. Change the following property values:

Tap on the bottom Inline button to display its properties. Change the following property values:

Then use the Save button to save the PatientResponse Client. For this tutorial, the patient is shown two buttons in order to submit a response, one to indicate the unusual heart rate does not require help to resolve (perhaps the patient was exercising) and the other to indicate that help is needed. We’ll use this Client when adding a Notification task.

To add a Notification task as a task associated with the triggering of the collaboration instance, right-click on the UnusualRate rectangle in the Collaboration Type graph, then select the Add Event menu item. In the resulting Add Event Task dialog:

        PatientNotify

Use the OK button to save the Task parameters.

Click the NotifyPatient rectangle to display its parameters in the right hand section. Change these parameters:

Use the OK button to save the Configuration Parameters.

        PatientNotifyRuntime

Use the OK button to save the users parameter then the OK button again to save the Runtime Parameter. Use the Save button at the top, left of Modelo to save the project.

6: Adding an Escalation Task

Once the patient notification has been sent, another follow-up task is to arrange for an escalation task in case the patient does not respond to the notification.

To add an Escalation task associated with the triggering of the collaboration instance, right-click on the small diamond shape (which represents the always event) under the UnusualRate rectangle in the Collaboration Type graph, then select the Add Task menu item. In the resulting Add Task dialog:

        PatientEscalate

Use the OK button to save the Task parameters.

Click the EscalatePatient rectangle to display its parameters in the right hand section. Change one parameter:

Use the OK button to save the Configuration Parameter.

After adding the EscalatePatient task, the Collaboration Type graph looks like this:

        PatientEscalateGraph

If the EscalatePatient task triggers, we want to notify a first responder to be dispatched to the patient’s location. To accomplish this, we’ll create another Client and Notification task for the first responder.

To add a new Client, use the Add button to select Client… then use the New Client button to create a new Client named “FirstResponderResponse” with a Design for mobile apps Layout Type.

Drag and drop one Inline button from the widget palette to the Client Builder canvas. Tap on the Inline button to display its properties. Change the following property values:

Then use the Save button to save the FirstResponderResponse Client. For this tutorial, the first responder is given one button to acknowledge the receipt of the notification for the given patient. We’ll use this Client when adding the next Notification task.

To add a Notification task associated with the triggering of the escalation, right-click on the EscalatePatient rectangle in the Collaboration Type graph, then select the Add Event menu item. In the resulting Add Event Task dialog,

        FirstResponderEscalate

Use the OK button to save the Task parameters.

Click the FirstResponderEscalate rectangle to display its parameters in the right hand section. Change these parameters:

Use the OK button to save the Configuration Parameters.

        PatientNotifyRuntime

Use the OK button to save the Runtime Parameter.

As mentioned previously, to keep the tutorial simple, the first responder and the patient are the same. In a more realistic example, a new FirstResponder type would be created and added to this collaboration type and references would be made to instances of that type when configuring the EscalatePatient and FirstResponderEscalate activities.

7: Closing the Collaboration

Once the first responder acknowledges the receipt of the notification from the VANTIQ mobile app, we want to close the collaboration instance. To do this, we’ll add a VANTIQ built-in service, CollaborationUtils.closeCollaboration, to the FirstResponderEscalate task.

To add a service associated with the receipt of the FirstResponderEscalate response, right-click on the FirstResponderEscalate rectangle in the Collaboration Type graph, then select the Add Event menu item. In the resulting Add Event Task dialog,

Use the OK button to save the Task parameters.

Click the CollaborationUtils.closeCollaboration rectangle in the Collaboration Type graph to display its parameters in the right hand section. Change these parameters:

        FRClose

Use the OK button to save the Service Parameter.

8: Adding Notification Responses

If the patient responds to the notification, the NotifyPatient task generates a response that is used to trigger other tasks. In this tutorial, the patient response is either I’m OK or Please Send Help. Note that in the payload definition from Lesson 5, the two responses are differentiated by the value property: 0 (zero) means the patient is OK and 1 (one) means the patient is requesting help.

In the I’m OK case, we want to simply close the collaboration since the patient has indicated she is OK. To close the collaboration, right-click on the NotifyPatient rectangle in the Collaboration Type graph, then select Add Event menu item. In the resulting Add Event Task dialog,

        ResponseZero

Once the Where clause has been specified, the Add Event Task dialog looks like:

        PatientNotifyOK

Use the OK button to save the Task parameters.

Click the CollaborationUtils.closeCollaboration rectangle in the Collaboration Type graph to display its parameters in the right hand section. Change these parameters:

The parameters dialog should then look like this:

        PatientCloseParams

Use the OK button to save the Service Parameter.

In the Please Send Help case, we immediately want to trigger the escalation that notifies the first responder, EscalatePatient. To trigger the escalation, right-click on the NotifyPatient rectangle in the Collaboration Type graph, then select the Add Event menu item. In the resulting Add Event Task dialog,

        ResponseOne

Once the Where clause has been specified, the Add Event Task dialog looks like:

        TriggerEscalate

Use the OK button to save the Task parameters.

Click the CollaborationUtils.triggerEscalation rectangle in the Collaboration Type graph to display its parameters in the right hand section. Change these parameters:

The parameters dialog should then look like this:

        PatientCancelParams

Use the OK button to save the Service Parameters.

We have now completed the entire definition of the Patient collaboration type. The Collaboration Type graph should look like this:

        CollaborationComplete

Use the Save button at the top, left of Modelo to save the project.

9: Triggering the Collaboration

Now that the entire collaboration type is defined, use the small Save Changes button/arrow on the top, right of the Collaboration Type: RateCollaboration pane to save the collaboration type. As part of the saving process, the VANTIQ system generates and activates multiple rules and procedures based on the contents of the collaboration type. Depending on the complexity of the collaboration type, this process may take several seconds. Once the collaboration type is saved, use the Save button at the top, left of Modelo to save the project.

Since this collaboration type includes notification activities, please download the VANTIQ iOS or Android mobile app and use it to log into the VANTIQ account you used to create this collaboration type. When the collaboration is started, the mobile app will receive the configured notifications.

Once the collaboration type is in place and the mobile app is authenticated, use the procedure created in Lesson 3 to trigger the start of a collaboration. To simulate a change in the patient’s heart rate, use the small Execute button at the top, right of the Procedure: UpdatePatient” pane to execute the procedure. The Specify parameters for Procedure “UpdatePatient” dialog is displayed:

        PatientUpdate

Enter a value of 180 for the heart rate, then use the Execute button to update the patient’s heart rate in the VANTIQ system. In Lesson 4, we created the UnusualRate task with a triggering condition of:

WHEN UPDATE OCCURS ON Patient WHERE Patient.heartRate < 40 OR Patient.heartRate > 150

By entering a value of 180 for the heart rate, the triggering condition is met and a collaboration instance is created. A notification is sent to the patient and will immediately appear in the mobile app. Do not respond to the initial notification so that the escalation task will generate a follow-up notification meant for the first responder. This will appear 90 seconds (the escalationTime parameter configured in Lesson 6) after the collaboration starts. Recall that the patient and the first responder are the same in this simple tutorial, which is why both notifications appear in the same mobile app:

        TutCollaborationNotification

To close the collaboration, tap on the top (‘Heart Rate Alert (180)’) notification then tap the Acknowledge button to trigger the CollaborationUtils.closeCollaboration task associated with the FirstResponderEscalate response event. This task closes the collaboration.

To verify the collaboration is closed, use the Debug button to select Advanced>Collaborations to display the Collaborations query pane:

        CollaborationsTab

Use the Run Query button to display all collaborations and to observe that the RateCollaboration entry’s Status is ‘closed’:

        Collaborations