log()

Description

This function adds a packet of "event" data to a history. If the history does not yet exist it will first create the history and record any "subject" data. Attempts to log to a "sealed" history will fail.

Parameters

Returns

If the log() operation was successful then the "result" structure will contain the following.

Example

"method": "log",
"params": {
    "labela": "User",
    "labelb": "823",
    "subject": {
        "name": {
            "first": "Richard",
            "surname": "Green"
        }
    },
    "event": {
        "type": "birthday",
        "age": 42
    }
}

"result": {
    "historyid": "d295ef5c-32e1-4806-b95d-b4fe90550874",
    "eventid": 347200,
    "eventpos": 2
}

Logging Geographic Data

Geographic points can be logged in event and subject data packets. Each point is represented by a GeoJSON object with two properties.

"type" will always be "Point" and "coordinates" an array of long/lat coordinates with an optional integer for altitude.

"method": "log",
"params": {
    "labela": "logginghistory",
    "labelb": "2",
    "subject": {
        "userId": "user",
        "description": "just a test"
        "mySubjectPoint": {
            "type": "Point",
            "coordinates": [-2.961243, 51.974358]
        }
    },
    "event": {
        "description": "History Logged",
        "event": "HISTORY LOGGED",
        "myLocation": {
            "type": "Point",
            "coordinates": [-0.1246892262, 51.4828989175]
        }
    }
}

Geographic Form Data

The location-based fields of the forms designer (location picker and client location) log their coordinates as a string when their form data is saved in a history event. Something like this:

"formData": {
    "data": {
        "FORMACTION.FINISH": "Submit",
        "LOCATIONPICKER": "51.4910227315,-0.131373291"
    }
}

Because that's not valid GeoJSON, the History worker needs to be told that the string represents a location. If you use the Write Event form field, or store form data during a workflow process, the Forms Service and Workflow workers call a method (in FormUtils) which supplies a field hint to the History, flagging strings that look like coordinates as locations.

Note that the form location fields using Google maps record their geographic data as latitude/longitude values rather than longitude/latitude, so while the coordinates in saved form data may look like this:

"formData": {
    "data": {
        "TEST1": "test",
        "LOCATIONPICKER": "51.4828989175, -0.1246892262" //This was a point in central London, not somewhere off the coast of Somalia
    },
    "formName": "STARTWORKFLOW",
    "typeName": "FORM_STARTWORKFLOW",
    "formDefinitionType": "FORMDEFINITIONEX"
}

The history worker will retrieve the event using this filter:

{
    "EVENTEXISTSWHERE": {
        "GEOGDISTLT": 10,
        "key": "formData.data.LOCATIONPICKER",
        "to": {
            "type": "Point",
            "coordinates": [-0.1246892263, 51.4828989176]
        }
    }
}

Data from Repeating Form Pages

If a form has repeating pages, and the form data is written to history, the data of the repeating page is structured as an array of objects (an object for each instance of the page). The array name is the name of the page, and the keys of each object are the field names. For example, history written by a workflow action field, with two repeats of page 1 would look like this:

"formData": {
    "data": {
        "PAGE1": [{
            "NAME": "Tim",
            "AGE": "41"
        }, {
            "NAME": "Leo",
            "AGE": "40"
        }]
    },
    "formName": "TIMSFORM",
    "typeName": "FORM_TIMSFORM",
    "formDefinitionType": "FORMDEFINITIONEX"
}

So that it's possible to write filters that query this data, the keys of form data from repeating pages are stored using generic array indexes.

For example, given the form data above, the keys would be written to the database as formData.data.PAGE1[*].NAME, formData.data.PAGE1[*].AGE. These keys can then be used in your filter objects. The actual keys formData.data.PAGE1[0].NAME, formData.data.PAGE1[1].NAME are also saved, and used when the history is returned via the various API methods, so the event can be reconstructed and appear in the same format as the example above. It is not possible to write filters using the true array index.

Note that this wildcarding only takes place in the formData.data object.