This field creates a history and writes an event to it. It includes properties that let you set the various label values, the event properties, set whether the full form data is saved in the event, control whether the event is public or private, and if the entire history should be sealed or not. The event is logged following server-side validation.
For more information see the History Service documentation and Recording History from Stand-Alone Forms in the knowledge base.
If your form is part of a workflow process, data can also be written to history without using this field. See the Workflow - Start Action and Workflow - Complete Task Action fields for more information.
Properties
| Label | Description | Type Name |
|---|---|---|
| History Label A | Required. The first part of a multi-part key that uniquely identifies a history. This label must be a valid JSON value, ie The value of another field can be used by adding the field's name between # characters, eg "#EMAILADDR#". This must be the complete field name when an external type definition is used. Maximum 50 characters (take care if you are using the value of another field) | LABELA |
| History Labels B-E | Optional. Part of a multi-part key that uniquely identifies a chain of history events. The label must be a valid JSON value. There is a special value, "#UNIQUE_ID#" that can be used to generate a unique identifier similar to a workflow business key. This is the default for labelb. The value of another field can be used by adding the field's name between # characters. Maximum 50 characters (take care if you are using the value of another field) | LABELB, LABELC, LABELD, LABELE |
| Subject Description | The description held in the subject data packet of the history. If no value is set the description of the form will be used. The value of another field can be used by adding the field's name between # characters | SUBJECTDESCRIPTION |
| Subject Additional Properties | Optional. A function that can be used to either add new properties to, or override existing properties within, the history subject. To add additional properties, return a JSON object from this function. To override existing properties, return a JSON object that includes one or more elements with the same name as an existing property. See Adding and Overriding Properties below | SUBJECTADDITIONALPROPERTIES |
| Subject Proxy User Id | This hidden property will store the username of the user that created this history if acting on behalf of another user using the Assisted Service product | SUBJECTPROXYUSERID |
| Subject Site User Id | This hidden property will store the username of the user that created this history | SUBJECTSITEUSERID |
| Event | A short one or two word phrase that describes the event. If no value is supplied the string "Form Submission" will be used. The value of another field can be used by adding the field's name between # characters | EVENTEVENT |
| Event Description | A more detailed human readable description of the event. If no value is supplied the form's description will be used, in the format "Form: [Form description] submitted" The value of another field can be used by adding the field's name between # characters | EVENTDESCRIPTION |
| Event History Description | Optional. A human readable description of the history as a whole which supersedes the subject description in the Self Service and User Requests products. This is used to provide updated subjects (as the original subject description can't be changed once written). The value of another field can be used by adding the field's name between # characters | EVENTHISTORYDESCRIPTION |
| Event User Role | Name of the role the user was performing as when they triggered the event. For example, "customer". The value of another field can be used by adding the field's name between # characters | EVENTUSERROLE |
| Event Private | If true, this event will be marked as private. The Self Service and User Requests products contain configuration options that can show or hide private events. The value of another field can be used by adding the field's name between # characters | EVENTPRIVATE |
| Event Additional Properties | Optional. A function that can be used to either add new properties to, or overwrite existing properties within, the event object. To add additional properties, return a JSON object from this function. To override existing properties, return a JSON object that includes one or more elements with the same name as an existing property. See Adding and Overriding Properties below | EVENTADDITIONALPROPERTIES |
| Event Proxy User Id | This hidden property will store the username of the user that created this event if acting on behalf of another user using the Assisted Service product | EVENTPROXYUSERID |
| Event Site User Id | This hidden property will store the username of the user that created this event | EVENTSITEUSERID |
| Store Form Data | If true, data submitted with the form will be stored within the event. A form could later be populated with this data and displayed to the user as a summary | STOREFORMDATA |
| Store User Data | If false the proxyUserId and userId won't be written to the history | STOREUSERDATA |
| Form Name | If Store Form Data is true, this is the name of the form that will be used to display the data. Defaults to the name of the current form if not supplied | FORMNAME |
| Seal History | If true, the history will be sealed when the event is recorded. When a history is sealed new events can no longer be added to it and it will appear as "Completed" in products like the Self Service template. Do not seal the history when writing to a workflow history, this will be performed automatically by the workflow worker when the process ends. The default is for the history to be sealed. In most cases this field type will be used to write a single history storing a single form submission | SEALHISTORY |
| Documentation | Add documentation to your field to help explain any complex functionality to future users. You might include information on what the field does and how it relates to other fields on the form. Notes added here are only ever visible in the Forms Designer, they can be searched for, viewed and downloaded from the action panel. See Common Field Properties for an example | DOCUMENTATION |
Action Results
The following can be accessed using .utilGetActionResults once the action has been processed.
"FIELDNAME": {
"eventId": "1027",
"success": "true"
}
Adding Additional Properties
To add additional properties to an event or the history subject, return a JSON object from the subject/event additional properties functions:
function(helper) {
var additionalProps = {};
additionalProps.additionalPropertyKey = "additionalPropertyValue";
additionalProps.totalCost = parseInt(helper.getFieldValue('PRICE')) * parseInt(helper.getFieldValue('QUANTITY'));
return additionalProps;
}
Overriding Properties
Returning a JSON/JavaScript object with an element that has the same name as the following will override the existing property value:
Overridable Subject Properties: description, userId and proxyUserId.
Overridable Event Properties: event, description, userRole, userId, proxyUserId, and historyDescription.
For example, to set the description dynamically:
function(helper) {
var additionalProps = {};
additionalProps.description = helper.getFieldValue('TEXT1');
return additionalProps;
}
History Event Format
The event written by the field has the following format. The
"event": {
"event": "Form Submission",
"description": "Form: [History write event] submitted.",
"userRole": null,
"userId": "TIMG",
"proxyUserId": null,
"private": false,
"formData": {
"data": {
"PAGE1.TEXT1": "A value",
"FORMACTION.NEXT": "HISTORYWRITEEVENT_PAGE1_NEXT",
"PAGE2.TEXT2": "Another value",
"FORMACTION.FINISH": "HISTORYWRITEEVENT_PAGE2_SUBMIT"
},
"formName": "HISTORYWRITEEVENT",
"typeName": "FORM_HISTORYWRITEEVENT",
"formDefinitionType": "FORMDEFINITIONEX"
}
}
Repeating Pages
The fields from a repeating page are stored as an array of objects, with the field names as the keys:
"formData": {
"data": {
"PAGE1": [{
"NAME": "Tim",
"AGE": "41"
}, {
"NAME": "Leo",
"AGE": "40"
}],
"PAGE2.COLOUR": "Red",
"PAGE2.SIZE": "Small",
"FORMACTION.NEXT": "TIMSFORM_PAGE1_FIELD27",
"FORMACTION.NEXTNOACTIONS": "TIMSFORM_PAGE1_FIELD8_ADD",
"FORMACTION.FINISH": "TIMSFORM_PAGE2_FIELD30"
},
"formName": "TIMSFORM",
"typeName": "FORM_TIMSFORM",
"formDefinitionType": "FORMDEFINITIONEX"
}
Share this page
