IndustraForm Element Attributes
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" will return the user’s full name (this is displayed in the j5 UI) rather than their username (the underlying value).
The following element attributes can be queried:
|
Attribute |
Data Type |
Description |
|---|---|---|
|
Value |
As described above |
The underlying element value. If no attribute is specified, ‘Value’ is the default (see default_element_attribute to adjust this) |
|
DisplayValue |
String |
The element value 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 will be converted to the user’s time zone and formatted in their language and internationalised messages and labels will be localised. In addition, Choice and Hierarchy Select elements will be converted to their labels. |
|
IsDefined |
Boolean |
Returns ‘true’ if the specified element is defined in the form design. Undefined elements will return null for Value and DisplayValue, so this attribute gives a way to distinguish them from defined elements that are null. |
|
IsValid |
Boolean |
Returns ‘true’ if the specified element value does not violate any validation rules defined for it. |
|
IsError |
Boolean |
Returns ‘true’ if the specified element value is not available because of a formula calculation error. The Value and DisplayValue attributes will return null in this case. |
|
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:
|
The following example queries all of these attributes for a sample element:
curl -X GET "http://j5.example.com/restserver/25.0/industraform/logbook-query/linked_industraforms_eg?attribute_names=ResponsiblePerson.Value,ResponsiblePerson.DisplayValue,ResponsiblePerson.IsDefined,ResponsiblePerson.IsValid,ResponsiblePerson.IsError,ResponsiblePerson.Error&pretty=true&limit=1" -H "accept: application/json" -H "authorization: Basic YWRtaW46YWRtaW4="
[
{
"ResponsiblePerson.Error": null,
"ResponsiblePerson.IsValid": true,
"ResponsiblePerson.DisplayValue": "John Smith",
"ResponsiblePerson.Value": "johns",
"ResponsiblePerson.IsError": false,
"ResponsiblePerson.IsDefined": true
}
]
It is often the case that a new version of a form has additional elements that previous versions did not. Forms that were created with the older versions will not have those elements defined.
The following example queries all of these attributes for an undefined element:
curl -X GET "http://j5.example.com/restserver/25.0/industraform/logbook-query/linked_industraforms_eg?attribute_names=IrresponsiblePerson.Value,IrresponsiblePerson.DisplayValue,IrresponsiblePerson.IsDefined,IrresponsiblePerson.IsValid,IrresponsiblePerson.IsError,IrresponsiblePerson.Error&pretty=true&limit=1" -H "accept: application/json" -H "authorization: Basic YWRtaW46YWRtaW4="
[
{
"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 "http://j5.example.com/restserver/25.0/industraform/logbook-query/linked_industraforms_eg?attribute_names=AvailableCapacity.Value,AvailableCapacity.DisplayValue,AvailableCapacity.IsDefined,AvailableCapacity.IsValid,AvailableCapacity.IsError,AvailableCapacity.Error&pretty=true&limit=1" -H "accept: application/json" -H "authorization: Basic YWRtaW46YWRtaW4="
[
{
"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!"
}
]
$Form Attributes
There is also a set of attributes that give information about the form entry as a whole. They are queried using the attribute name "$Form.<FormAttribute>".
|
Attribute |
Data Type |
Description |
|---|---|---|
|
UUID |
string |
The unique identifier for the form. |
|
SpecificationName |
string |
The fully qualified form specification name. The form_spec_name parameter filters data based on this value. |
|
SpecificationVersion |
string |
The form specification version hash code. |
|
IsComplete |
boolean |
Is every section of the form submitted and fully approved? |
|
StateName |
string |
The current state name (based on form design gate definitions). |
|
StateDisplayName |
string |
The localised state name. |
|
SectionsWaitingForSubmission |
integer |
The number of sections that are enabled, but have not yet been submitted. |
|
SectionsWaitingForApproval |
integer |
The number of sections that have been submitted and are waiting for at least one approval. |
|
SectionsWaitingForRevision |
integer |
The number of sections that have been rejected, and have not yet been revised. |
|
FlagsTotal |
integer |
The total number of flags raised. |
|
FlagsPending |
integer |
The total number of flags raised in sections that are still in edit mode (i.e. have not yet been submitted). |
|
Area |
string |
The area key for the containing logbook record (colon-separated). The area parameter filters data based on this value. |
|
DateTime |
string |
The ‘primary_time_field’ value for the containing logbook record, in UTC, formatted according to RFC3339 - full-date. The from_date_time and to_date_time parameters filter data based on this value. |
|
ParentLogID |
string |
The logid value for the containing logbook record. |
Area, DateTime and ParentLogID are only available through the REST API. They are
not accessible through the corresponding in-process Python query API calls.
Here is an example, querying all of the $Form attributes:
curl -X GET "http://j5.example.com/restserver/25.0/industraform/logbook-query/permits?attribute_names=$Form.UUID,$Form.SpecificationName,$Form.SpecificationVersion,$Form.IsComplete,$Form.StateName,$Form.StateDisplayName,$Form.SectionsWaitingForSubmission,$Form.SectionsWaitingForApproval,$Form.SectionsWaitingForRevision,$Form.FlagsTotal,$Form.FlagsPending,$Form.Area,$Form.DateTime,$Form.ParentLogID&pretty=true&limit=1" -H "accept: application/json" -H "authorization: Basic YWRtaW46YWRtaW4="
[
{
"$Form.StateDisplayName": "Drafting",
"$Form.SpecificationVersion": "9a039ad1952013c87470e30a2330e796bf4df6d6",
"$Form.Area": "3e880eb2-f50b-4c50-8c87-ab90672d4935:fa247105-d5d5-47c0-8205-6b972c005e1e:ab1ce956-49bf-4e5c-8878-3e8afaf655ad",
"$Form.SectionsWaitingForRevision": 1,
"$Form.SectionsWaitingForSubmission": 3,
"$Form.SpecificationName": "j5.PermitToWork.cold_work",
"$Form.UUID": "fcd569b5-83dd-4888-9073-54741cff3f6e",
"$Form.FlagsPending": 0,
"$Form.FlagsTotal": 0,
"$Form.StateName": "Drafting",
"$Form.IsComplete": false,
"$Form.ParentLogID": "ID1499061945058262581206",
"$Form.SectionsWaitingForApproval": 2,
"$Form.DateTime": "2017-07-03T06:05:45Z"
}
]
$Participants Attributes
If a form has roles defined for it, it is possible to find information about the users that have been assigned to those roles (the participants). This information is queried using an attribute name like "$Participants.<RoleID>.<AttributeName>". Any of the element attributes can be referenced for participants (Value, DisplayValue, IsDefined, IsValid, IsError or Error) Here is an example, querying all of the $Participants attributes for a particular role:
curl -X GET "http://j5.example.com/restserver/25.0/industraform/logbook-query/permits?attribute_names=$Participants.IssuingAuthority.Value,$Participants.IssuingAuthority.DisplayValue,$Participants.IssuingAuthority.IsDefined,$Participants.IssuingAuthority.IsValid,$Participants.IssuingAuthority.IsError,$Participants.IssuingAuthority.Error&pretty=true&limit=1" -H "accept: application/json" -H "authorization: Basic YWRtaW46YWRtaW4="
[
{
"$Participants.IssuingAuthority.DisplayValue": "James Roland",
"$Participants.IssuingAuthority.Value": "jamesr",
"$Participants.IssuingAuthority.IsValid": true,
"$Participants.IssuingAuthority.IsDefined": true,
"$Participants.IssuingAuthority.IsError": false,
"$Participants.IssuingAuthority.Error": null
},
]