This function adds a named (registered) digest to a queue to be processed. Processing involves batching history events and populating the relevant database tables and views with their values. Only events added to the history since digestHistories() was last called will be processed.
The default batch size is 250,000 events, which can be changed by setting the
When the digest is processed, its started and finished properties are automatically updated.
This function is often used in an end point which can be called using a Scheduled Tasks. Where we have used digests to provide data for dashboards, the scheduled task generally calls the end point every five minutes.
Queued Digests
This feature was added in iCM 10.1.0.73 (June 2025)
Calling digestHistories() adds a digest to a queue. The queue of digests is processed by an iCM scheduled task which, by default, runs every 15 seconds. This asynchronous behaviour changes the previous (pre 10.1.0.73) response from this function. See below.
You can inspect the digest queue from the iCM/API Servers page.
Parameters
| Name | Type | Description |
|---|---|---|
| name | String, required | The name of the digest to process |
| batchsize | Integer, optional | Defaults to 250,000 |
| synchronous | Boolean, optional | Defaults to false. For performance reasons, we recommend leaving this as false so that digests are added to the queue |
Returns
Standard Behaviour
By default (since iCM 10.1.0.73) digests are placed in a queue and the response values described in the table below will now be 0 or false.
Synchronous Behaviour
If the "synchronous" request parameter is set, the response will indicate whether there is more work to do.
| Name | Type | Description |
|---|---|---|
| allEventsProcessed | Boolean | Will be |
| totalNewRowsCount | Integer | The number of new rows added by this operation |
| totalValueCount | Integer | The number of new values added by this operation |
| columns | Object | The columns processed by this operation |
| columns.<digestname>.<columnname> | Object | Information about this column |
| columns.<digestname>.<columnname>.valueCount | Integer | The number of new values added |
| columns.<digestname>.<columnname>.cursorPosition | Integer | The current position in the history the digest has reached |
| columns.<digestname>.<columnname>.allEventsProcessed | Boolean | Will be |
| columns.<digestname>.<columnname>.newRowsCount | Integer | The number of new rows added |
Example
Request
function(params, credentials) {
let resp = this.callWorkerMethod("history", "digestHistories", {
"name": "exampledigest"
});
return resp;
}
Response
Note that with the standard asynchronous behaviour all of the values will be 0 or false.
{
"id": 8,
"result": {
"totalValueCount": 603,
"columns": {
"exampledigest.started": {
"valueCount": 30,
"cursorPosition": 2963,
"allEventsProcessed": true,
"newRowsCount": 0
},
"exampledigest.all_descriptions": {
"valueCount": 151,
"cursorPosition": 2963,
"allEventsProcessed": true,
"newRowsCount": 30
},
"exampledigest.businesskey": {
"valueCount": 30,
"cursorPosition": 2963,
"allEventsProcessed": true,
"newRowsCount": 0
},
"exampledigest.first_response_time": {
"valueCount": 30,
"cursorPosition": 2963,
"allEventsProcessed": true,
"newRowsCount": 0
},
"exampledigest.all_descriptions.eventtime": {
"valueCount": 151,
"cursorPosition": 2963,
"allEventsProcessed": true,
"newRowsCount": 0
},
"exampledigest.all_descriptions.eventdescription": {
"valueCount": 151,
"cursorPosition": 2963,
"allEventsProcessed": true,
"newRowsCount": 0
},
"exampledigest.involved_users.involveduser": {
"valueCount": 60,
"cursorPosition": 2963,
"allEventsProcessed": true,
"newRowsCount": 0
},
"exampledigest.involved_users": {
"valueCount": 0,
"cursorPosition": 2963,
"allEventsProcessed": true,
"newRowsCount": 0
}
},
"allEventsProcessed": true,
"totalNewRowsCount": 30
},
"jsonrpc": "2.0"
}
