Not every form on your site will be related to a workflow process. If you need your stand-alone forms to write data to the History Service there are two field types you can use, multiple versions of them can be placed on the same form.
History - Write Event
This field creates a history and writes an event to it. It lets you set the various label values, the event properties, whether the 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.
Labels
When you add the field to your form the label a and b properties are prefilled.
"#FORM_NAME#" follows our convention of using the name of the form or process as labela. This means you can fetch all histories created by this form just by querying on labela.
"#UNIQUE_ID#" generates a unique ID for each history, in a similar format to a workflow business key. This ensures that each history created by the form are unique.
The property fields include drop-downs that let you pick the value of another field on the form. You can also use "#FIELDNAME#" to access a field value, or "%MYVARIABLE%" to access the value of a helper variable. Alternatively you can insert your own fixed value, just remember to put it in quotes, like "this".
You don't have to add any values at all for the other labels. Our standard approach is to leave the labels c-e blank if the history contains user data and is subject to data retention policies. We use labelc values to create histories for specific purposes, as explained in Labelc Histories and Reporting Data.
Subject
The subject always records the ID of the current user, and if there is one, the proxy user ID (if using Assisted Service).
The description field gets added to the subject description. You can access the values of other fields and variables using ## or %% in the same way as you can for labels. if left blank the description of the form is used.
The additional properties function lets you add new properties to the subject, or override existing ones. The subject properties you can override are the
Event
The event section is where you decide what data your history is actually going to store.
The event name, description, history description, user role and privacy settings are described in the standard history data article.
The additional properties function lets you add new properties to the event, or override existing ones. The subject properties you can override are the
Storing Form Data
Take care when deciding to store form data. If this is set as true the complete form submission will be stored in the history event, including any personal data entered into the form.
The Form Name setting controls what form will be used to view the saved form data when it is displayed in templates like Self Service and User Requests. There's more information about how these templates interact with histories in the History Events and Summary Events article.
This example shows the form data saved from a two page form. Note how the page name is included with each field name in the form data, as well as the actions that navigated through the form. The default event name and description can also be seen:
"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"
}
}
Subject and Event Additional Properties
You can save additional data in the subject and event data packets. The two additional property data functions return an
For example, this function is used to store additional data in an event. It stores the value of a single form field, the value of a variable, some fixed text and a call to an End Point.
function(helper) {
var additionalProps;
additionalProps = {
nameField: helper.getFieldValue('NAME'),
formVariable: helper.getVariable('myVariable'),
fixedText: 'Hello',
endPointCall: helper.utilServerAPIServerCall('serverlibrary', 'tim', {
request: 'string'
})
};
return additionalProps;
}
You can see the event data in the export of the history below.
Example History
Here's the history generated by the form action using the settings above. It is not storing the full form data, but is storing a record that the form has been submitted. By using the event additional properties function some values from the form have been saved, along with some data returned from a call to an End Point.
{
"id": "4247702d-846c-4687-a839-cce4aefc749f",
"labela": "WRITEHISTORY",
"labelb": "2265-0644-5795-2923",
"labelc": null,
"labeld": null,
"labele": null,
"created": 1538051982023,
"lastupdated": 1538051982193,
"sealed": true,
"subject": {
"description": "Write some history",
"proxyUserId": null,
"userId": "ANONYMOUS"
},
"events": [{
"pos": [1, 1],
"event": {
"private": false,
"event": "Form Submission",
"description": "Form: [Write some history] submitted.",
"userRole": null,
"userId": "ANONYMOUS",
"proxyUserId": null,
"nameField": "Tim",
"formVariable": "myValue",
"fixedText": "Hello",
"endPointCall": "A string returned from an End Point"
},
"fpos": [1, 1],
"timestamp": 1538051982193
}]
}
History - Form Reporting
This form action is designed specifically to create histories with no user data in them. The field automatically sets the label a and b values as the name of the form and a unique ID, and always sets the labelc value as "reporting" to fit in with our conventions.
The only property you are able to edit in the forms designer is the Event Additional Property function, which works in exactly the same way as described above. However, as the purpose of this field is to store data that can be kept indefinitely, it's important that you don't collect any user data with it, otherwise the history it creates may have to be deleted following a data subject request.
Here's the "reporting" history that was generated at the same time as the example history above. Note how all of the
{
"id": "50b0dbe7-c760-4323-91ba-3fd9e8c2871c",
"labela": "WRITEHISTORY",
"labelb": "1559-8499-9426-2429",
"labelc": "reporting",
"labeld": null,
"labele": null,
"created": 1538051982280,
"lastupdated": 1538051982287,
"sealed": true,
"subject": {
"description": "Write some history"
},
"events": [{
"pos": [1, 1],
"event": {
"private": false,
"historyDescription": "Reporting data",
"description": "Reporting data",
"event": "Reporting data"
},
"fpos": [1, 1],
"timestamp": 1538051982287
}]
}
Share this page
