Description
This function retrieves histories from the database. It can also return the events of each history. Events can be returned as part of the JSON structure, or the complete result can be converted into a tabular format (an array of arrays) to better suit business analysis and dashboarding software.
Volumes of Data
This function can potentially retrieve large volumes of data. Use filters to narrow down your queries. We recommend using the created date of histories to select records in twenty-four hour or weekly periods - any longer than that then you could see performance issues. If you do need to report across large spans of time, you should use the Data Reporting Service.
Parameters
| Name | Type | Description | |
|---|---|---|---|
| datasource | String, optional | The name of the datasource from where histories will be retrieved. This parameter overrides the same parameter in the worker configuration which in turn overrides the default datasource | |
| filter | Filter-object, required | The filter specifies which histories will be returned. The syntax of filter objects relates to many methods and is explained in Filter Objects | |
| sealed | Boolean, optional | If true, then only histories that have been switched into read-only mode will be searched. If false then only writable histories will be searched. If sealed is not supplied, then all histories will be searched | |
| order | Array, optional | The elements of this array specify the order in which histories will be returned. The first element is the most significant, the second element will only be used if two histories are tied on the first element values. If no order parameter is specified, or if two histories are tied after they have been compared on all elements of the "order" array, then they will be returned in the same order that they were created. Histories can be ordered by label, subject, created and last updated. The sorting can either be "ASC" ascending or "DESC" descending. See below for an example. | |
| getevents | Object, optional | Specifies whether events should be returned for the histories that match your filter (above). If this parameter is not specified, then no event data will be returned. An empty object will return all events | |
| getevents.eventfilter | Object, optional | Only return events that match the supplied Filter Objects | |
| getevents.top | Integer, optional | Return the first n events in each history or the first n events that match the optional eventfilter (ie the oldest events) | |
| getevents.tail | Integer, optional | Return the last m events in each history or the last m events that match the optional eventfilter (ie the most recent events). If getevents.top and getevents.tail are both specified in the same request, then the events structure in the returned history will be modified to separate top from tail and to cope with events which appear in both the top and tail | |
| getevents.fields | Array<string>, optional | Only returned the named fields in each event. Each string in the array should be a fully qualified key in the event data structure (using dots and square brackets as necessary). Only simple values can be returned, not structures or arrays. This example will only get the 5 most recent events from each history, and that only the fields "status" and "reason.short" will be included in the returned events: "getevents": { | |
| getevents.lastsummary | Boolean, optional | Set as true to only return the most recent summary event in each history (ie events with the property This parameter cannot be used in combination with any other in the | |
| gettable | Object, optional | Returns histories and their event data, but in a tabular format (an array of arrays). Each array after the first represents one history event. The first array contains "column headers" which are the history "labels a-e", "N" (the position of each event within a given history), "sealed", and the properties of each event returned. Each array is the same length, with null populating empty positions. All events in each history are returned. See below for an example. gettable and getevents cannot be used in the same query | |
| gettable.eventfilter | Object, optional | Only return events that match the supplied Filter Objects | |
| gettable.fields | Array, optional | Only return certain event properties, works in the same way as getevents.fields | |
| gettable.lastsummary | Boolean, optional | If true will only return the most recent summary event and subject in each history, works in the same way as getevents.lastsummary above | |
| top | Integer, optional | Retrieve only histories in the first top of the ordered list of histories. Used in conjunction with order and skip to implement a paged view of histories | |
| skip | Integer, optional | Do not retrieve histories in the first skip of the ordered list of histories. Used in conjunction with order and top to implements a paged view of histories | |
| start | Integer, optional | Do not retrieve histories before history number start in the ordered list of histories. Used in conjunction with order and length to implement a paged view of histories | |
| length | Integer, optional | Retrieve at most length histories. Used in conjunction with order and start to implements a paged view of histories | |
| getsql | Boolean, optional | If this parameter is supplied and set to true then the return structure will include an element called "sql" which contains the query and the parameters which were used to retrieve the history data from the database. This option returns a large amount of data and is intended for testing and debugging | |
| getreadabletimes | Boolean, optional | If this parameter is supplied and set to true then the timestamps returned with each event will contain human readable dates and human readable times. This option significantly increases the amount of data that is returned from a history and is intended for testing and debugging​ | |
| getast | Boolean, optional | If true the query will return the abstract syntax tree generated by the filter and show the ast of the filter after it has been through the optimiser. This parameter is intended for testing and debugging | |
Ordering
The "order" array allows you to set the order in which histories are returned. You can order histories by any one of their five labels, by the date created, the date last updated, or by any property in their subject object. Each can be ordered either ASCending or DESCending
The first object in the array is the primary ordering rule, with subsequent objects only used to resolve ties, where histories have the same value for the first ordering rule. For example:
"order": [{
"created": "DESC"
}, {
"SUBJECT.userId": "ASC"
}]
This sorts histories by the date they were created (the most recent first), and then sorts any that were created at the same time by the userId in the subject data.
Returns
If the getHistories() operation was successful then the "result" structure will contain an array of history objects. The format of data returned from history queries is described in History Format.
Example
This example returns histories with the labela value "Feedback Review" created in the last 24 hours. Each history only includes its first (ie oldest) event.
Request
function(params, credentials) {
let lastTwentyFourHours = Date.now() - 24 * 60 * 60 * 1000;
let histories = this.callWorkerMethod("history", "getHistories", {
"filter": {
"AND": [{
"key": "labela",
"EQ": "Feedback Review"
}, {
"key": "created",
"GT": lastTwentyFourHours
}]
},
"getevents": {
"top": 1
}
});
return histories;
}
Response
We've found two histories and retuned the first event in each.
{
"id": 163,
"result": [{
"labeld": null,
"labele": null,
"created": 1647610080673,
"sealed": true,
"subject": null,
"lastupdated": 1653301508987,
"id": "e50506aa-bd65-4cd5-bebb-76dbb87c2469",
"labela": "Feedback Review",
"events": [{
"pos": [1, 3],
"event": {
"taskDefinitionKey": "reviewfeedback",
"private": true,
"description": "Task 247595 claimed for user \"timg\"",
"proxyUserId": null,
"event": "CLAIMTASK",
"userRole": "workflowengine",
"userId": "TIMG",
"taskId": "247595"
},
"fpos": [1, 3],
"timestamp": 1647610080673
}],
"labelb": "0248-8253-6388-2670",
"fpos": [3, 6],
"labelc": null
}, {
"labeld": null,
"labele": null,
"created": 1647610182943,
"sealed": true,
"subject": null,
"lastupdated": 1647610982337,
"id": "de56bf41-a0bb-480e-81d1-4e290edca239",
"labela": "Feedback Review",
"events": [{
"pos": [1, 3],
"event": {
"taskDefinitionKey": "reviewfeedback",
"private": true,
"description": "Task 245084 claimed for user \"timg\"",
"proxyUserId": null,
"event": "CLAIMTASK",
"userRole": "workflowengine",
"userId": "TIMG",
"taskId": "245084"
},
"fpos": [1, 3],
"timestamp": 1647610182943
}],
"labelb": "1953-0864-4970-8660",
"fpos": [4, 6],
"labelc": null
}],
"jsonrpc": "2.0"
}
Tabular Results
Repeating the example above, but replacing
{
"id": 169,
"result": [
["labela", "labelb", "labelc", "labeld", "labele", "sealed", "timestamp", "N", "", "taskId", "description", "event", "userId", "taskDefinitionKey", "proxyUserId", "userRole", "private", "historyDescription", "formData.typeName", "formData.formName", "formData.data.EMAILUSER", "formData.data.COMPLETE", "formData.data.EMAIL", "formData.data.ISSUETYPE", "formData.data.URL", "formData.data.EMAILBODY", "formData.data.FEEDBACK", "formData.formDefinitionType"],
["Feedback Review", "0248-8253-6388-2670", null, null, null, 1, "2022-03-18 13:28:00.673", 0, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null],
["Feedback Review", "0248-8253-6388-2670", null, null, null, 1, "2022-03-18 13:28:00.673", 1, null, "247595", "Task 247595 claimed for user \"timg\"", "CLAIMTASK", "TIMG", "reviewfeedback", null, "workflowengine", true, null, null, null, null, null, null, null, null, null, null, null],
["Feedback Review", "0248-8253-6388-2670", null, null, null, 1, "2022-05-23 10:25:08.987", 3, null, null, "Process Ended", "PROCESSENDED", null, null, null, "workflowengine", false, null, null, null, null, null, null, null, null, null, null, null],
["Feedback Review", "1953-0864-4970-8660", null, null, null, 1, "2022-03-18 13:29:42.943", 0, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null],
["Feedback Review", "1953-0864-4970-8660", null, null, null, 1, "2022-03-18 13:29:42.943", 1, null, "245084", "Task 245084 claimed for user \"timg\"", "CLAIMTASK", "TIMG", "reviewfeedback", null, "workflowengine", true, null, null, null, null, null, null, null, null, null, null, null],
["Feedback Review", "1953-0864-4970-8660", null, null, null, 1, "2022-03-18 13:43:02.337", 3, null, null, "Process Ended", "PROCESSENDED", null, null, null, "workflowengine", false, null, null, null, null, null, null, null, null, null, null, null]
],
"jsonrpc": "2.0"
}
Share this page
