registerDigest()

This function registers a named history digest and creates history digest database tables and views with the specified columns.  A digest also defines, via a range of filters and operations, the histories and events that will later be digested into the tables using digestHistories().

Registering a digest adds an entry to iCM's security log.

Parameters

These parameters define top-level information about your digest table and the histories that will be digested when you run digestHistories().

Column Schema

These parameters define each column in your digest table. They are the properties of each object in the columns array above.

Column Operations

The following operations are used to populate the columns of your digest table.

Returns

If the registerDigest() operation was successful then the "result" structure will contain the following.

Example 1 - Basic Operations and Filters

This example creates a digest with two child tables. The histories that are to be digested have been generated by a workflow process that involves replying to a customer enquiry. It's designed to provide data for a report on the time it takes for a first response to be sent out, and includes two child tables that record the time and descriptions of each event in the history, and a list of distinct users involved in the history.

The digest will consider all histories with a labela:Customer Enquiry, and create a row for each history. The columns on the table are:

• The unique business key held in labelb
• The timestamp of the first event in the history (which will be the time the customer got in contact)
• The timestamp of the first event called Mail Sent
• A child table recording the values of all event descriptions and when they took place
• A child table of unique user IDs involved in the history

Request

function(params, credentials) {
    let resp = this.callWorkerMethod("history", "registerDigest", {
        "name": "exampledigest",
        "filter": {
            "key": "labela",
            "EQ": "Customer Enquiry"
        },
        "columns": [{
            "name": "businesskey",
            "type": "varchar",
            "size": 50,
            "operation": "label",
            "key": "labelb",
            "index": "businesskey_index"
        }, {
            "name": "started",
            "type": "datetime",
            "operation": "firsttimestamp"
        }, {
            "name": "first_response_time",
            "type": "datetime",
            "eventFilter": {
                "key": "event",
                "EQ": "Mail Sent"
            },
            "operation": "firsttimestamp"
        }, {
            "name": "all_descriptions",
            "type": "table",
            "operation": "all",
            "columns": [{
                "name": "eventdescription",
                "type": "varchar",
                "size": 250,
                "operation": "value",
                "key": "description"
            }, {
                "name": "eventtime",
                "type": "datetime",
                "operation": "timestamp"
            }]
        }, {
            "name": "involved_users",
            "type": "table",
            "operation": "distinct",
            "columns": [{
                "name": "involveduser",
                "type": "varchar",
                "size": 250,
                "operation": "value",
                "key": "userId"
            }]
        }]
    });
    return resp;
}

Response

The response includes the names of the tables and views that have been created. Not that the tables will contain no data until digestHistories() has been run.

{
    "jsonrpc": "2.0",
    "id": 53,
    "result": {
        "created_tables": ["dh_exampledigest", "dh_exampledigest_all_descriptions", "dh_exampledigest_involved_users"],
        "digest_registered": "exampledigest",
        "created_views": ["dh_exampledigest_vw", "dh_exampledigest_all_descriptions_vw", "dh_exampledigest_involved_users_vw"]
    }
}

Generated Views

The digest above created the following views, the digest tables themselves should not be queried. In all views the PublicID column holds the ID of the history that provided the data for that row.

dh_exampledigest_vw

This view has a row for each history with the three columns set in the registerDigest example above.

dh_exampledigest_all_descriptions_vw

This view was created using the all operation. There are multiple rows per history holding details about each event.

dh_exampledigest_involved_users_vw

This view was created using the distinct operation. Two users were involved in the histories, but each is only listed once per history.

Example 2 - Geographic Points

The point digest type is used to digest GeoJSON data stored in history events (see log() for more information about logging geographic points) and store data in geography columns. It can be used with the firstvalue and lastvalue operators. The key will be the name of the GeoJSON data packet in the history that is being digested.

{
    "name": "my_digest",
    "filter": {
        ...
    },
    "columns": [
        {
            "name": "first_bin_location",
            "type": "point",
            "operation": "firstvalue",
            "key": "binLocation"
        },
        {
            "name": "last_bin_location",
            "type": "point",
            "operation": "lastvalue",
            "key": "binLocation"
        }
    ]
}