Situations

A situation identifies a specific state of the world modeled by a Vantiq application. For example, a situation with the name, failedMachine, may represent the fact that a machine is in a failed state.

A situation is most useful when associated with some real world entity modeled by the application. The state that defines the situation contains the identifier of the real world entity with which it is associated. Continuing with our failedMachine example, the situation, failedMachine, is associated with a specific machine named M1 and the identity of the failedMachine is included in the definition of the situation.

A real world entity associated with a situation need not be a physical entity. For example, a situation named latePayment may be defined on the abstract entity: invoice.

Situations typically define undesirable states of the system that represent known problems. A machine has failed, a payment is late, a consumer is unhappy. When such a situation is detected, one or more activities is initiated to resolve the problem and return the system to a desired state. The desired state is typically not represented by a situation.

Of course, it is possible to define situations that represent desirable states but, given the focus on handling exceptions in smart systems, it is much more likely situations will be defined on undesirable states. An example of a desired state is a casino guest that has won enough that the casino should offer to comp them a room for the night with the goal of keeping them in the casino. This could be considered a desirable situation – the guest is winning - but it could also be considered an undesirable situation – the guest may not continue playing so find a way to keep them in the casino.

The Situation abstraction supports both desirable and undesirable situations but is optimized for the more common undesirable cases. The optimization mostly involves nomenclature used in the supporting services and the developer portal.

Situation Lifecycles

At present, situations come into existence when explicitly created by the user. The situation is considered open from the time it is created until the time it is closed by the user. During the time the Situation is open, it may find itself in a number of different states with the specific states defined and maanged by the user. For example, the machineFailed situation may go through the states:

Once the machine has successfully returned to mormal operation, the situation is closed.

Using Situations

Situations are represented by instances of the type: ArsSituation.

ArsSituation defines the following properties:

For example, a representation of a failedMachine situation:

{
  id: "A-UNIQUE-IDENTIFIER",
  name: "failedMachine",
  openedAt: 14-DEC-2016T13:10:35Z,
  closedAt: null,
  state: "diagnosisInProgress"",
  entity: /types/Machine/M1",
  relatedEntities: {
      powerSource: "/types/Power/Circuit 14-A",
      productionLine: "/types/Production/WidgetFactory"
  },
  ars_properties: { assignedTech: "paul" }
}

The openedAt date is set but closedAt is null indicating the Situation is still opened. This is also clear because the state property is not set to closed.

The actual failed machine is referenced by the entity property that points to the specific object in the Machine type that contains the representation of the machine named M1.

The relatedEntities reference other entities modeled in the Vantiq type system that may relate to the failed machine. In this example, the object representing the machine’s power source and the object representing the production line in which the failed machine is located.

Note that the entity and related entity are all valid resource paths that can be used in a Vantiq REST request to obtain the specific object instance representing the entity. The resource path can easily be turned into its constituent parts for use in one of the Vantiq SDKs or for use in VAIL.

The ars_properties are additional descriptive information associated with the Situation. In this example, the name of the tech assigned to repair the machine is represented as a property.

Creating Situations

A Situation is created by inserting an object into ArsSituation:

Updating Situations

A Situation is updated by:

Deleting Situations

A Situation is deleted by:

Note that Situations do not have to be deleted in cases where a historical record of closed situations is useful. In such cases all Situations in the closed state can be ignored except during historical analysis.

Coming Extensions

Situations are currently a simple convenience for tracking important conditions identified by Vantiq rules and subject to some life cycle before they are closed. In the future Situations will become an integral part of Collaboration support within Vantiq for managing the ongoing collabrations between and among the people and automated systems responsible for handling the Situation. The first elements of such Collaboration support will be introduced in the first quarter of 2017.