API Reference: j5.IndustraForms.api - j5 - 28.0 - Reference - Hexagon PPM

j5 Framework IndustraForm API Reference

PPMProduct
j5
PPMCategory_custom
Reference
Version_j5
2019

When dealing with IndustraForms, please ONLY make use of functions and classes that are documented in the api package, or in a beta_api_vvv package. All other code in the j5.IndustraForms package must be considered INTERNAL, and may change from release to release.

j5.IndustraForms.api.create_new_logbook_linked_form(sa_session=None, form_register_logid=None, logbook_record=None, relationship_type=None, initialisation_element_data=None, previous_form=None, **kwargs)

Creates a new instance of an IndustraForm and associates it with the provided logbook_record.

Parameters:

sa_session – (REQUIRED) the sqlalchemy session with the transaction that the new form will be added in.

form_register_logid – (REQUIRED) The form_register entry logid that identifies the form to create.

logbook_record – (REQUIRED) A logbook recordclass instance to link the new form to.

relationship_type – If provided, specifies the type of relationship that this IndustraForm has to the containing logbook record.

initialisation_element_data – If provided, is a dictionary with element IDs as keys, providing an initialisation value for those elements

previous_form – If provided, is the previous instance of the form whose data should be carried over (if specified)

Returns:

IndustraForm - the new IndustraForm instance.

Raises:

Exception - in this case the transaction SHOULD be rolled back.

j5.IndustraForms.api.get_logbook_linked_forms(logbook_record=None, relationship_type=None, **kwargs)

Retrieves the IndustraForms that are linked to the provided logbook record.

This list is populated from the latest committed version of the form (a separate database session is used for the queries).

Parameters:

logbook_record – (REQUIRED) A logbook recordclass instance to retrieve the linked forms for.

relationship_type – If provided, retrieves only linked forms of with the specified relationship to the logbook_record.

Returns:

list - an unordered list of IndustraForm instances.

Raises:

Exception

j5.IndustraForms.api.delete_form(sa_session=None, form=None, only_if_empty=True, **kwargs)

Deletes an IndustraForm instance and any associations with logbook records. This does not remove the commit history (i.e. audit log) for the form.

Please note that it is not necessary to delete associated IndustraForm instances when a logbook record is deleted.

Parameters:

sa_session – (REQUIRED) the sqlalchemy session with the transaction that the delete statements will be executed in.

form – (REQUIRED) The IndustraForm instance that identifies the form to delete. Please note that this instance will be invalidated if it is deleted.

only_if_empty – (Default: True) Only remove the form if the content has not been modified by a user.

Returns:

bool - True if the form was deleted.

Raises:

Exception - in this case the transaction SHOULD be rolled back.

class j5.IndustraForms.api.IndustraForm

This class provides access to various functions for a single instance of an IndustraForm.

This class is not intended to be subclassed, or directly instantiated.

form_register_logid

The corresponding form_register entry’s logid.

get_form_data_snapshot (display_locale_name=None, display_timezone_name=None, at_date=None, **kwargs)

A FormDataSnapshot provides access the values of form elements, as well as other information through its query methods.

Parameters:

display_locale_name – Specify the locale to use for DisplayValue results. Use the two character language code and region code, for example ‘en-US’. If not specified, the current user’s locale is used.

display_timezone_name – Specify the timezone to use for DisplayValue date or date-time results. Use the Olson timezone name, for example ‘Asia/Tokyo’. If not specified, the current user’s timezone is used.

Returns:

FormDataSnapshot

get_label (locale=None, **kwargs)

Returns the localised label of this form.

Parameters:

locale – the name of the locale to use. The default is to use the current request locale.

Returns:

unicode - the label.

get_state_name()

Returns the name of the current state of the the form.

Returns:

unicode (or None) - The state name.

is_complete()

Returns:

bool - True if all sections of the form have been completed.

is_valid_form_object()

An IndustraForm object that has been instantiated, but not yet initialised is invalid. In addition, an IndustraForm object can become invalidated (for example, on deletion). If an IndustraForm object is invalid, calls to any other method or property will result in an exception.

This is not related to form content validity.

Returns:

bool - True, if this IndustraForm instance is valid.

to_pdf(locale=None, timezone=None, **kwargs)

Returns the rendered PDF representation of this form.

This PDF is created from the version of the form represented by its current snapshot state (a separate database session is used for the queries).

Parameters:

locale – the name of the locale to use. The default is to use the current request locale.

Timezone – the name of the timezone to use. The default is to use the current request timezone.

Returns:

str - the binary PDF data, or None if the form cannot be rendered as a PDF.

uuid

The IndustraForm UUID.

class j5.IndustraForms.api.FormDataSnapshot

This class is not intended to be subclassed, or directly instantiated.

get_element_names()

Returns the names of all elements in this instance of the form in left to right, top to bottom order.

Returns:

List of strings

query(attribute_names, default_element_attribute=None, **kwargs)

This returns a single ValueCollection with the values of the requested attributes.

Parameters:

attribute_names – list of element attribute IDs (str). Please refer to the IndustraForm REST API documentation for a full description of the supported attribute names.

Returns:

ValueCollection

Raises:

InvalidAttributeException: if the attribute isn’t supported

query_repeating(attribute_names, default_element_attribute=None, **kwargs)

This returns a list of ValueCollection instances, onc for each repeat of the target repeating section.

The target section is determined based on the elements referenced in the attribute_names list.

Parameters:

attribute_names – list of element attribute IDs (str). Please refer to the IndustraForm REST API documentation for a full description of the supported attribute names.

Returns:

list of ValueCollection instances

Raises:

InvalidAttributeException: if the attribute isn’t supported

to_pdf(form_uuid, locale=None, timezone=None, **kwargs)

Returns the rendered PDF representation of this form.

This PDF is created from the latest committed version of the form (a separate database session is used for the queries).

Parameters:

locale – the name of the locale to use. The default is to use the current request locale.

timezone – the name of the timezone to use. The default is to use the current request timezone.

Returns:

str - the binary PDF data, or None if the form cannot be rendered as a PDF

class j5.IndustraForms.api.ValueCollection

A tuple that positionally matches the attibute_list provided to a query method. It also allows both attribute and dictionary access to queried attributes (e.g. result.OxygenLevel or result["OxygenLevel.IsValid"]).

The values in the collection can be one of the following:

  • None

  • NOT_APPLICABLE

Or an instance of one of the following:

  • float

  • int

  • unicode / str

  • bool

  • datetime.date

  • datetime_tz.datetime_tz

  • SpreadsheetError (only returned for the ‘Error’ attribute)

This class is immutable.

This class is not intended to be subclassed, or directly instantiated.

iteritems()

Returns:

iterator of tuples (attribute_name, value)

iterkeys()

Returns:

iterator of attribute names

itervalues()

Returns:

iterator of values

exception j5.IndustraForms.api.InvalidAttributeException

An invalid or unsupported attribute was requested.

class j5.IndustraForms.api.SpreadsheetError

An immutable object representing the details of a spreadsheet error value

error_type

One of the error codes defined in ERROR_TYPES

get_display_value()

Returns:

unicode - a user readable description of the error

class j5.IndustraForms.api.ERROR_TYPES

Defines the valid values for a SpreadsheetError.error_type

NULL = 1

DIV0 = 2

VALUE = 3

REF = 4

NAME = 5

NUM = 6

NA = 7

GETTING_DATA = 8

j5.IndustraForms.api.NOT_APPLICABLE: A constant object representing the 'N/A' checklist item value