Watches

A watch is a fact that acts as a trigger for changes on another fact. Once a watch is added to a node, any modification to the node causes a watch event to be created. If the node targetted by the watch is an entity, then any change to any field of the entity causes a watch event. Changes include adding, replacing, or deleting a node.

Watch events are parented by their associated watch. They can be listed using the describe API call.

A watch can specify an external interface using the watchInterfaceId property. This interface will receive all watch events generated by the watch.

Watch Basics

A watch is created using the watch API call. For example:

POST /watch
{
    "targetNodeId": "00000000404AE4402DF969ACE2C2DA9133A23EA48773AF8A"
}

creates a watch on the node with id "00000000404AE4402DF969ACE2C2DA9133A23EA48773AF8A".

Any changes to the target node cause a watch event to be generated. Continuing with the example, if we did a write to the node targetted by the watch:

POST /write
{
    "nodeId": "00000000404AE4402DF969ACE2C2DA9133A23EA48773AF8A",
    "document": {
        "FullName": "John Watson"
    }
}

Then a watch event would be generated.

To access watch events, just target the watch with the describe API call, listing children with factType WatchEvent.

Example:

POST /describe
{
    "targetNodeId": "00000000DD0248D31A8418C62078D7A716EBA9A39F2C3A81",
    "listChildren": {
        "factType": "WatchEvent"
    }
}

The response will include a description of the watch events.

{
    ...
    "children": [{
        "parentId": "00000000DD0248D31A8418C62078D7A716EBA9A39F2C3A81",
        "factType": "WatchEvent",
        "nodeId": "00000000AEFFDB5F8A4C745A0E002736D625FC76903888D9",
        "source": "00000000C78EAB913627799CE4EB15227EA0A2FDD2EEF001",
        ...
    }]
}

The source property of the watch event is the node id of the node associated with the event. For example, if adding a field to an entity caused the watch event, then the source would be the node id of the associated information node.

Creating a Watch Event Consumer

A watch can specify an external interface for receiving watch events. The property watchInterfaceId can be set on the watch creation request with the id of such an interface.

The interface only requires the addData endpoint to be specified. Example:

POST /createinterface
{
    "parentId": "00000000C320A7BFD903745851915F6C33D20634E36C37C6",
    "name": "ExampleWatchConsumer",
    "addData": {"url": "https://example.com/addwatch"}
}

The corresponding watch would be created:

POST /watch
{
    "targetNodeId": "00000000404AE4402DF969ACE2C2DA9133A23EA48773AF8A",
    "watchInterfaceId": "ExampleWatchConsumer"
}

If a watch has such an interface, when a watch event is generated, the interface receives a POST having the watch event description. The POST will be of the form

    ?nodeId=

where nodeId is a unique id that identifies the event of sending the watch event. The Content-Type will be application/json.

For example, now when the write occurs on the watched entity:

POST /write
{
    "nodeId": "00000000404AE4402DF969ACE2C2DA9133A23EA48773AF8A",
    "document": {
        "FullName": "John Watson"
    }
}

the external interface receives a POST:

POST https://example.com/addwatch?nodeId=000000009F30B3440E8B768D34552CA45786CDB2AF2959B1
{
    "parentId": "00000000DD0248D31A8418C62078D7A716EBA9A39F2C3A81",
    "factType": "WatchEvent",
    "nodeId": "00000000AEFFDB5F8A4C745A0E002736D625FC76903888D9",
    "source": "00000000C78EAB913627799CE4EB15227EA0A2FDD2EEF001",
}