Collaborations Guide

Introduction

Real-time Business Applications leverage event and data streams combined with available context to make the best decisions possible. However, in many situations the optimal decisions result from a collaboration between the application and its users. Some examples illustrate why Real-time Business Applications almost invariably involve collaboration:

Given the importance of collaborative activities within a Real-time Business Application, VANTIQ offers extensive capabilities simplifying the development and operation of collaborations between a Real-time Business Application and its users as well as collaborations among the application’s users.

Advanced collaboration features include:

These features can be declaratively assembled into rich collaborations involving multiple users in the process of optimizing the results achieved by the Real-time Business Application.

Example

A failed machine is a simple, consistent example used throughout the collaboration documentation. The precise nature of the machine is irrelevant but the basic use case is as follows:

This use case is fairly simple but an optimal solution requires extensive collaboration between the Real-time Business Application and the collaborators - the tech specialist, the senior tech specialist, other available technical resources and the supervisor. Translating the high level use case into a Real-time Business Application might result in the following tasks being identified:

A number of exceptional conditions may occur during the execution of this collaboration:

These conditions can all be handled as escalations that assign additional resources to the collaboration either automatically or in collaboration with one or more supervisors.

Building such a collaboration in traditional tools would be a time consuming and expensive task. With VANTIQ, this collaboration can be declaratively defined in a simple manner.

The remainder of this document describes VANTIQ collaborations and the tools used to develop, deploy and operate the collaborations.

Collaboration Overview

Collaboration Model

A collaboration, as introduced above, is a collection of tasks carried out by a Real-time Business Application and its users to impact some set of entities (also referred to as objects). Execution of each task is allocated either to the application or to one or more users. The tasks cannot be executed in arbitrary order. At each point in time there are a set of possible tasks that can be executed depending on the current state of the entities impacted by the collaboration. The collaboration defines the tasks that can be undertaken and the constraints on when each task can be executed.

This collaboration definition can be contrasted with a workflow which also identifies a set of tasks and the constraints on when each task is executed. A workflow prescribes exactly when each task can be executed in relation to all other tasks defined in the flow. In contrast, a collaboration identifies a set of tasks that can be executed for each state of the impacted entities. This means a collaboration is far more flexible, allowing the users to select the best task to execute at each point in time rather than having to execute the tasks prescribed by the workflow.

A VANTIQ collaboration defines tasks as collections of activities, representing interactions between the application’s users and the collaboration, and services, representing business logic (aka procedures) executed as part of the collaboration. The states in which each activity and service can be executed are identified by events that represent the transition of the impacted entities into a particular state. Activities and services are more completely defined in later sections of this developer’s guide.

VANTIQ collaborations are formally represented by two VANTIQ artifacts named Collaboration Type and Collaboration. A Collaboration Type represents the structure of a class of collaborations. Multiple Collaborations can be instantiated from a Collaboration Type, and each such collaboration will behave in accordance with the structure defined by the Collaboration Type. A Collaboration represents an executing collaboration that is bound to a specific set of entities that are impacted by the collaboration and a set of users that are participating as collaborators within the collaboration.

In the failed machine example the Collaboration Type might be named RepairMachine and consist of activities such as selecting a specialist to handle the machine diagnosis and repair, detecting the tech specialist’s arrival at the failed machine and presenting the specialist with up to date status, recommending possible diagnostic activities and monitoring the progress of the diagnosis, monitoring the repair of the machine and bringing it back online when repairs are complete. When a specific machine fails, a Collaboration instance is created from the RepairMachine Collaboration Type, and the collaboration instance is bound to the specific machine that failed. The created Collaboration then manages the execution of the activities, services and events that comprise the collaboration.

A collaboration may be as simple as sending a single notification to a user and as complex as the machine repair example outlined above.

Collaboration Tools

Actually implementing the activities, services and events that define a Collaboration Type normally involves developing a large amount of code as all the details of the asynchronous interactions have to be handled as well as the overall management of the complete set of activities. However, using VANTIQ Collaborations and the VANTIQ Collaboration Builder, the essential collaborative activities and services are assembled using a simple graphical model. Once the activities have been assembled, the developer provides any specialized semantics unique to the application as simple declarations or more expressive VAIL scripts.

The entire collaboration is designed and constructed in an iterative and dynamic fashion allowing the effectiveness of the collaboration to be evaluated in real time as each change is made.

The remainder of this document assumes the developer is creating collaboration types using the Collaboration Builder within the Project Builder available in the Developer Portal. References are made to drop down lists and property panels that are available in the Collaboration Builder. Although far more complex, it is also possible to construct Collaboration Types programmatically as JSON objects. Documentation on programmatic creation of Collaboration Types will be included in a forthcoming documentation release. Therefore, VANTIQ strongly recommends that you begin your exploration of collaborations using the Collaboration Builder.

Collaboration Type

Tasks and Events are assembled into Collaboration Types using the Collaboration Builder in the Developer Portal. Once a Collaboration Type is completely assembled, Collaborations may be created based on the Collaboration Type by binding a set of parameter values to the Collaboration Type to create each Collaboration. Collaborations are created in response to an event (See InitiateCollaboration for details) or by explicitly invoking the CollaborationUtils.establishCollaboration service ( See Services). Once created, a Collaboration immediately starts coordinating interactions between the application and its users.

Collaboration Type Declaration

A Collaboration Type is assembled as a collection of Tasks and Events combined with a set of roles that represent the categories of users and the categories of entities that participate in the collaboration. Tasks consist of Activity Types and Services and represent the actions a Collaboration Type supports. Activity Types define interactions between the application and its users. Services are implemented as VAIL Procedures that are invoked to produce a result. The result of a service invocation is then typically used as a parameter to an Activity Type or another Service. Events are the triggers that start Tasks executing. Events are categorized as follows: activity events - each activity type defines a standard set of events that are generated by the Activity Type when it is executing. These are known as activity events. custom events - the developer can use any event the VANTIQ system is capable of producing as a trigger condition for starting Tasks. For example an insert or update or the publication of an event for a topic can be used as triggering conditions. These are known as custom events. * always events - for completeness, there are times when Tasks are triggered when an Activity is initiated. These are known as always events because they ALWAYS occur when an activity begins executing.

Roles effectively identify the responsibility of each participant in the collaboration: At execution time collaborator roles will be bound to actual users that are tasked with executing each activity while entity roles are bound to objects that represent the entities impacted by each activity:

The following properties characterize a Collaboration Type:

Every Collaboration Type must contain a single instance of the InitiateCollaboration activity type. The InitiateCollaboration activity type identifies the issue the collaboration is intended to resolve and kicks off the collaboration lifecycle. The event that triggers the beginning of this lifecycle is identified by the developer and will automatically cause a corresponding Collaboration to be created.

For example, in the machine repair Collaboration Type the triggering condition might be:

WHEN UPDATE OCCURS ON Machine WHERE Machine.status == "failed"

When this event is recognized, a Collaboration is created from the Collaboration Type and execution begins by passing the Collaboration the details of the failed machine.

A Collaboration Type is represented by a resource of type collaborationtypes.

Tasks

Tasks define the actions the Collaboration Type implements and represent a core building block of Collaboration Types. The other major building block of Collaboration Types are Events which identify the conditions under which the CollaborationTypes tasks are executed. Tasks consist of Activity Types and Services. Available Activity Types are defined in the next subsection and Services in the subsequent section of this document.

Activity Types

Activity Types declare the structure of the interactions between the collaboration and its users and define the range of interactions that are available to each user role under any given set of collaborative conditions.

Activity Types are constructed from a pre-defined inventory of Activity Patterns. An Activity Pattern is a common template useful in a range of different Activity Types. A Collaboration Type may use the same Activity Pattern multiple times to create multiple Activity Types within the Collaboration Type.

For example, in the machine repair example, activity types are defined for:

Each of these Activity Types is created by selecting the appropriate Activity Pattern and then configuring the pattern to create the Activity Type. When a new Collaboration Type is added to a Project using the Project Builder, the new Collaboration Type is created with a single Activity Type named Initiate. The Initiate Activity Type is derived from the InitiateCollaboration pattern and represents the first activity executed by the Collaboration when it is created. Additional Activity Types are added to the Collaboration Type by selecting an Activity Type and then selecting Add Task from the context menu. Adding a Task starts a dialog that asks the developer to indicate the event that triggers the execution of the task. The event can be either an activity event, a custom event or the always event. Once the event is selected the user can use the drop down list to choose the particular Activity Pattern from which the newly created Activity Type is derived. The Event and Activity Type are then added to the Collaboration Type and the developer may configure the Activity Type by selecting the Activity Type and editing its properties in the displayed property panel.

The available Activity Patterns and their configuration properties include:

InitiateCollaboration

Every Collaboration Type begins with the InitiateCollaboration pattern. InitiateCollaboration contains the following configuration parameters:

LocationTracking

The LocationTracking Activity Pattern allows you to track a user to a destination using the VANTIQ Mobile App or a developer supplied location tracking mechanism. Location Tracking contains the following configuration parameters:

When a LocationTracking Activity Type is referenced as a behavior associated with another activity, the required runtime parameters include the collaboration instance and:

LocationTracking activities produce the following events:

Location Tracking activities produce the following results:

Conversation

Start a new chatroom in the VANTIQ Mobile App. The Conversation Activity Pattern can be used to start a discussion related to a specific Collaboration instance. Conversations contain the following configuration parameters:

When a Conversation Activity Type is referenced as a behavior associated with another activity, the required runtime parameters include the collaboration instance and:

Conversation activities produce the following event:

Conversation activities produce the following results:

Notification

Send a notification to a list of users through the VANTIQ Mobile App. See VANTIQ Mobile App User’s Guide for more information on push notifications and notification payloads. Notifications contain the following configuration parameters:

When a Notification Activity Type is referenced as a behavior associated with another activity, the required runtime parameters include the collaboration instance and:

Notification activities produce the following event:

Notification activities produce the following results:

Assignment

Assign a user to a collaborator role. Collaboration Types contain collaborator roles which can be referenced as placeholders for usernames. The assignment activity updates the user assigned to a collaborator role for a given collaboration instance. Assignment contain the following configuration parameters:

When an Assignment Activity Type is referenced as a behavior associated with another activity, the required runtime parameters include the collaboration instance and:

Assignment activities produce no events.

Assignment activities produce the following results:

Escalation

Escalations trigger an event after a certain amount of time if they are not cancelled first. Escalations are a useful way to verify something happens within a set amount of time and triggering some additional behaviors if the thing doesn’t happen. Escalations can be cancelled using the builtin procedure CollaborationUtils.cancelEscalation, which takes two parameters, the id of the collaboration and the name of the escalation activity that should be cancelled. When an escalation is cancelled the escalationBehaviors are not triggered. Escalations contain the following configuration parameters:

When an Escalation Activity Type is referenced as a behavior associated with another activity, the only required parameter is the collaboration instance.

Escalation activities produce the following events:

Escalation activities produce the following results:

Recommendation

Generate a list of recommendations based on some input criteria. Recommendations use a procedure to determine how similar each candidate is to the target of the recommendation, and then the results are a limited subset of the most similar candidates. Recommendation activities contain the following configuration parameters:

When a Recommendation Activity Type is referenced as a behavior associated with another activity, the required runtime parameters include the collaboration instance and:

Recommendation activities produce no events.

Recommendation activities produce the following results:

Execute

The Execute activity invokes a procedure and saves the result of the procedure execution to the results of the collaboration. The key difference between an execute activity and a service invoking the same procedure is that the results of the execute activity are saved as part of the collaboration results and can be referenced as runtime parameters to other activities. Execute activities contain the following configuration parameter:

When an Execute Activity Type is referenced as a behavior associated with another activity, the required runtime parameters include the collaboration instance and:

Execute activities produce no events.

Execute activities produce the following results: result - The object returned by the last return statement in the invoked procedure. resultTime - The time at which the procedure returned a result.

NaturalLanguageInterpreter

(Note: More information is available in the Natural Language Guide and tutorial.)

Turn message text into an intent and related entities. The NaturalLanguageInterpreter Activity Pattern is used to interpret text, resulting in an encoding that can be used by the collaboration to execute some command. This encoding is referred to as an intent. NaturalLanguageInterpreter activities contain the following configuration parameters:

When a NaturalLanguageInterpreter Activity Type is referenced as a behavior associated with another activity, the required runtime parameters include the collaboration instance and:

NaturalLanguageInterpreter activities produce the following events:

NaturalLanguageInterpreter activities produce the following results:

NaturalLanguageCustomIntent

Execute a custom intent. The NaturalLanguageCustomIntent Activity Pattern is used to execute an intent that is a custom intent, that is, one that is specific to this application. NaturalLanguageCustomIntent activities contain the following configuration parameters:

When a NaturalLanguageCustomIntent Activity Type is referenced as a behavior associated with another activity, the required runtime parameters include the collaboration instance and:

NaturalLanguageCustomIntent activities produce no events.

NaturalLanguageCustomIntent activites produce the following results:

NaturalLanguageSystemIntent

Execute a system intent. The NaturalLanguageSystemIntent Activity Pattern is used to execute an intent that is a system intent, that is, one provided by the system. NaturalLanguageSystemIntent activities contain the following configuration parameters:

When a NaturalLanguageSystemIntent Activity Type is referenced as a behavior associated with another activity, the required runtime parameters include the collaboration instance and:

NaturalLanguageSystemIntent activities produce no events.

NaturalLanguageSystemIntent activities produce the following results:

Services

Activity Types represent interactions between the collaboration and its users. Services represent application logic that is executed as part of the overall Collaboration Type. Services are implemented as VAIL procedures. Within Collaboration Types services are generally used to augment the actions of the activity types. For example, formatting notifications before presenting them to a Notification activity for delivery to one or more users or looking up users to assign them to a specific role within the collaboration.

Services are added to a collaboration by selecting an existing Activity Type and using the context menu to add a new Task to the activity type. The desired service is selected from the appropriate drop down menu. The Service is then added to the Collaboration Type and a panel is presented in which the Service’s parameters can be bound to the data elements available within the Collaboration Type.

Several pre-defined services are available to help manage a collaboration and its activities:

In addition to these system supplied services, any user defined procedures available in the namespace may be invoked as part of a collaboration.

Events

Events represent triggers that occur during the execution of a Collaboration and cause additional Tasks to begin executing. Events are categorized as follows: activity events - each activity type defines a standard set of events that are generated by the Activity Type when it is executing. These are known as activity events. custom events - the developer can use any event the VANTIQ system is capable of producing as a trigger condition for starting Tasks. These are known as custom events. * always events - for completeness, there are times when Tasks are triggered when an Activity is initiated. These are known as always events because they ALWAYS occur when an activity begins executing. Examples of activity events are the response and firstResponse events associated with a Notification activity. A response event is generated whenever a response to a specific notification is received by the collaboration. Since a notification may be sent to multiple users, this response event may occur multiple times (once for each user). The collaboration developer may elect to handle the event by associating activity types and services with the event. Similarly, firstResponse is triggered only when the first response to the notification is received. This is convenient if a message is broadcast and only the first response needs to be dealt with. For example, in the MachineRepair collaboration may notify several techs of the repair request but assign only the first tech that responds to actually take responsibility for the repair task.

An example of a custom event is a change of state in the failed machine. When the machine’s status returns to normal, the collaboration can be considered successful and the collaboration closed. The collaboration would declare an event on the state that represents correct operation of the machine and associate it with the pre-defined CollaborationUtils.closeCollaboration service to terminate the collaboration when the machine returns to normal operation.

The special always event is available for executing activities and services unconditionally at the time the parent activity first becomes active.

Events are included in a collaboration by selecting an Activity Type and then selecting add task from the Activity Type’s context menu. The activity, custom and always events are available. Once the event has been added, the tasks executed when the event occurs are declared from the context menu associated with the event. For custom events the triggering condition may be specified in the property panel associated with the event. For both activity events and custom events an additional VAIL conditional expression can be declared that further restricts the conditions under which the event is activated.

The pre-defined events associated with each Activity Type are documented (above) with the Activity Patterns.

Collaborations

Collaborations are created by instantiating a Collaboration Type to initiate interactions between the application and its users to address a specific situation.

Collaborations are created automatically when the triggering condition declared on the initiateCollaboration activity is satisfied. See InitiateCollaboration for details.

Alternatively, an application can invoke the CollaborationUtils.establishCollaboration built-in service to manually create a collaboration. On creation the Collaboration Instance will have a state of “open”. When the issue underlying the Collaboration Instance has been resolved the state will be changed to “closed”, at which point the collaboration instance should be considered immutable. Collaboration Instances can be closed with the CollaborationUtils.closeCollaboration built-in service.

Collaborations contain of the following properties:

A collaboration may have one or more participating collaborators. The collaborators assigned to the collaboration are named in the collaborators property organized by their role in the collaboration.

The status property contains the collaboration life cycle states. Presently, the states are: active, closed, cancelled.

The situations property identifies one or more Situations that are being “handled” by the collaboration. This value is optional and applies only to collaborations that are associated with a formally defined situation. When a collaboration is created because the initialTrigger of the InitiateCollaboration activity is triggered a situation will be automatically generated with the name of the collaboration type.

If the collaboration is created manually, it is the responsibility of the implementor to supply a meaningful collaboration type. When creating a collaboration manually, it is also possible to bind all entity roles and collaborator roles in the config object passed to CollaborationUtils.establishCollaboration (which creates the actual collaboration instance).

The results property maintains the result of collaborative activities in cases where the results must be retained across multiple activities and events. For example, the guidance activity needs to record the history of diagnostic activities in order to present the user with a follow-on suggestion that does not repeat a diagnostic already applied by the collaborator.

Collaboration Instances can be operated upon by the standard DML services:

A collaboration is represented by a resource of type collaborations.