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