The most common query attribute names are simply the names of elements in an IndustraForm design. The attributes in the previous example are all element value attributes.
The JSON datatype returned for the value of each element depends on the element type, but can be one of the following:
-
null
-
Number
-
Boolean
-
String
Date and Date&Time elements return String values, after converting the value to UTC and formatting according to RFC3339. For example, "2017-07-03" and "2017-06-30T10:23:59Z".
Checklist Item elements generally have a Boolean value, but may return the String "NOT_APPLICABLE" if the user has selected that value.
In addition to finding out the value of the element, it is also possible to query other attributes of the element. An alternative element attribute is queried using the attribute name "<ElementName>.<Attribute>". For example, querying for
"ResponsiblePerson.DisplayValue" returns the user’s full name (this is displayed in the j5 UI) rather than their user name (the underlying value).
The following element attributes can be queried:
|
Attribute |
Data Type |
Description |
|---|---|---|
|
Altitude |
Number |
The height of the position in meters above the ellipsoid. |
|
AltitudeAccuracy |
Number |
The accuracy level of the altitude coordinate in meters. |
|
DisplayValue |
String |
The element value is converted to a string. This is done in such a way as to be as close as possible to what is displayed in the j5 user interface. For example, dates and times are converted to the user’s time zone and formatted in their language and internationalized messages and labels are localized. In addition, Choice and Hierarchy Select elements convert to their labels. |
|
Error |
Object |
Returns the details of a formula calculation error, if one has occurred for the element. For CSV output this is simply an error message, and for JSON output, this is an object with three properties:
|
|
IsDefined |
Boolean |
Returns true if the specified element is defined in the form design. Undefined elements return null for Value and DisplayValue, so this attribute gives a way to distinguish them from defined elements that are null. |
|
IsError |
Boolean |
Returns true if the specified element value is not available because of a formula calculation error. The Value and DisplayValue attributes return null in this case. |
|
IsHtml |
Boolean |
Checks if the field is a richtext field. |
|
IsTask |
Boolean |
Returns true if the field that is referenced refers to a task. |
|
IsValid |
Boolean |
Returns true if the specified element value does not violate any validation rules defined for it. |
|
LastModifiedTime |
String |
The time the field was last modified. |
|
LastModifiedUser |
String |
The user that last modified the field. |
|
Latitude |
Number |
The latitude in decimal degrees. |
|
Longitude |
Number |
The longitude in decimal degrees. |
|
LocationAccuracy |
Number |
The accuracy level of the latitude and longitude coordinate in meters. |
|
NormalMax |
Number |
The maximum value the field is allow to take on without being flagged. |
|
NormalMin |
Number |
The minimum value the field is allow to take on without being flagged. |
|
NoReadingAvailable |
Boolean |
Returns whether the referenced field has no reading available. |
|
SignatureSVG |
String |
Returns the picture of the referenced signature field in SVG format, or null or if the field is not a signature. |
|
SignatureTime |
String |
Returns the time the referenced signature field was signed at, or null or if the field is not a signature. |
|
SignatureUserDisplayName |
String |
Returns the display name of the user that signed the referenced signed field, or null or if the field is note. |
|
ValidMax |
Number |
The maximum value that the field is allow to have. |
|
ValidMin |
Number |
The minimum value that the field is allow to have. |
|
Value |
As described above |
The underlying element value. If no attribute is specified, Value is the default (refer to the default_element_attribute in the Parameter reference table to adjust this). |
The following example queries all of these attributes for a sample element:
curl -X GET "https://[j5 Server URL]/restserver/30/industraform/logbook-query-v2/linked_industraforms_eg
?attribute_names=ResponsiblePerson.Value,ResponsiblePerson.DisplayValue,ResponsiblePerson.IsDefined,
ResponsiblePerson.IsValid,ResponsiblePerson.IsError,ResponsiblePerson.Error&pretty=true&top=1" -H
"accept: application/json" -H
"authorization: Basic [Base 64 encoded username and password]"
json
{
"values": [
{
"ResponsiblePerson.Error": null,
"ResponsiblePerson.IsValid": true,
"ResponsiblePerson.DisplayValue": "John Smith",
"ResponsiblePerson.Value": "johns",
"ResponsiblePerson.IsError": false,
"ResponsiblePerson.IsDefined": true
}
]
}
New versions of a form often have additional elements that weren't in the form's previous versions. Forms that were created using the older versions won't have the new elements defined. You'll get the following results when you query for attributes for an undefined element:
curl -X GET "https://[j5 Server URL]/restserver/30/industraform/logbook-query-v2/linked_industraforms_eg
?attribute_names=IrresponsiblePerson.Value,IrresponsiblePerson.DisplayValue,
IrresponsiblePerson.IsDefined,IrresponsiblePerson.IsValid,IrresponsiblePerson.IsError,
IrresponsiblePerson.Error&pretty=true&top=1" -H "accept: application/json" -H
"authorization: Basic [Base 64 encoded username and password]"
json
{
"values": [
{
"IrresponsiblePerson.DisplayValue": null,
"IrresponsiblePerson.Value": null,
"IrresponsiblePerson.IsValid": null,
"IrresponsiblePerson.IsError": null,
"IrresponsiblePerson.IsDefined": false,
"IrresponsiblePerson.Error": null
}
]
}
Here is an element with a calculation error:
curl -X GET "https://[j5 Server URL]/restserver/30/industraform/logbook-query-v2/linked_industraforms_eg
?attribute_names=AvailableCapacity.Value,AvailableCapacity.DisplayValue,AvailableCapacity.IsDefined,
AvailableCapacity.IsValid,AvailableCapacity.IsError,AvailableCapacity.Error&pretty=true&top=1" -H
"accept: application/json" -H
"authorization: Basic [Base 64 encoded username and password]"
json
{
"values": [
{
"AvailableCapacity.IsError": true,
"AvailableCapacity.IsValid": false,
"AvailableCapacity.Error": {
"error_name": "#DIV/0!",
"error_type": 2,
"error_message": "#DIV/0!"
},
"AvailableCapacity.Value": null,
"AvailableCapacity.IsDefined": true,
"AvailableCapacity.DisplayValue": "#DIV/0!"
}
]
}