Query Attribute Names - j5 - 28.0 - Reference - Hexagon PPM

j5 Framework IndustraForm API Reference

PPMProduct
j5
PPMCategory_custom
Reference
Version_j5
2019

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:

  • error_type: an integer defined below in ERROR_TYPES

  • error_name: the String error name associated with the error_type

  • error_message: a longer error String, if one is available

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

},

]