Description
This function retrieves one history and its events from the database. A history can either be retrieved by its unique id or full combined label values.
Parameters
| Name | Type | Description |
|---|---|---|
| datasource | String, optional | The name of the datasource from where the history will be retrieved. This parameter overrides the same parameter in the worker configuration which in turn overrides the default datasource |
| id | String, optional | The unique internally generated key that identifies this history. Do not specify id and label parameters together |
| labela | String/int/real/bool, required if id is not set | The first part of the unique compound key that identifies this history. Note that the full set of labels must be provided for the history to be returned (ie if a history has labela, labelb and labelc, only setting labela and labelb would return no results) |
| labelb | String/int/real/bool/null, optional | The second (optional) part of the unique compound key that identifies this history |
| labelc | String/int/real/bool/null, optional | The third (optional) part of the unique compound key that identifies this history |
| labeld | String/int/real/bool/null, optional | The fourth (optional) part of the unique compound key that identifies this history |
| labele | String/int/real/bool/null, optional | The fifth (optional) part of the unique compound key that identifies this history |
| eventfilter | Object, optional | Specifies which events in the history will be returned. The syntax of filter objects relates to many methods and is explained in Filter Objects. If no filter is supplied, all events are returned |
| top | Int, optional | Retrieve only the events in the first top events of the history. Can be used in conjunction with skip to implement a paged view of a history |
| tail | Int, optional | Retrieve only the events in the last tail events of the history (ie the most recent ones) |
| skip | Int, optional | Do not retrieve events in the first skip events of the history. Can be used in conjunction with top to implement a paged view of a history |
| start | Int, optional | Do not retrieve events before event number start in the history. Can be used in conjunction with length to implement a paged view of a history |
| length | Int, optional | Retrieve at most length events from the history. Can be used in conjunction with start to implement a paged view of a history |
| lastsummary | Boolean, optional | Set as true to only return the most recent summary event in the history (ie the last event with the property This parameter cannot be used in combination with any of the preceding parameters used to filter events, but is more efficient than constructing your own filter |
| 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 |
| 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 |
| 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 |
Returns
If the getHistory() operation was successful then the "result" structure will contain an object called "subject" and an array called "events". "subject" will contain the subject data packet that was logged at the start of this history. The "events" array contains all the events that have been logged to this history - in chronological order. The boolean "sealed" indicates whether the history has been switched into read-only mode.
The format of data returned from history queries is described in History Format.
Example
Request
In this example we are including an event filter so that only "Summary" events in the history are returned.
function(params, credentials) {
let histories = this.callWorkerMethod("history", "getHistory", {
"labela": "Feedback Review",
"labelb": "1953-0864-4970-8660",
"eventfilter": {
"key": "description",
"EQ": "Summary"
}
});
return histories;
}
Response
The returned history includes one matching events. Note the position (
{
"id": 193,
"result": {
"labeld": null,
"labele": null,
"created": 1647610182943,
"sealed": true,
"subject": null,
"lastupdated": 1647610982337,
"id": "de56bf41-a0bb-480e-81d1-4e290edca239",
"labela": "Feedback Review",
"labelb": "1953-0864-4970-8660",
"events": [{
"pos": [2, 3],
"event": {
"private": false,
"historyDescription": "Review comments from the feedback form",
"description": "Summary",
"proxyUserId": null,
"formData": {
"data": {
"COMPLETE": "Yes",
"ISSUETYPE": "Missing",
"EMAIL": "support@gossinteractive.com",
"EMAILUSER": "No",
"URL": "https://docs.gossinteractive.com/article/8275/axios",
"FEEDBACK": "Add a timeout to the example call... Otherwise you will wait forever.",
"EMAILBODY": ""
},
"formName": "PAGEFEEDBACK",
"typeName": "FORM_FEEDBACKMASTER",
"formDefinitionType": "FORMDEFINITIONEX"
},
"event": "SUMMARY",
"userRole": "workflowengine",
"userId": null
},
"fpos": [1, 1],
"timestamp": 1647610982310
}],
"labelc": null
},
"jsonrpc": "2.0"
}
Share this page
