models.form.Form

class Form(json, **kwargs)

A virtual object representing a KE-chain Form Collection.

New in version v3.20.

Variables:

• id – id of the form

• name – name of the form

• description – description of the form

• ref – reference (slugified name) of the form

• category – the category of the form (FormCategory.MODEL or FormCategory.INSTANCE)

• active_status – current active Status of the form

• form_model_root – the form model root Part

• form_instance_root – the form instance root Part

• model_id – the pk of the model of this form instance

• status_forms – The StatusForms of this form

• prefill_parts – The parts to prefill when a Form Model is isntantiated.

• created_at – datetime in UTC timezone when the form was created

• updated_at – datetime in UTC timezone when the form was last updated

• derived_from_id – (optional) id where the objects is derived from.

Construct a service from provided json data.

classmethod create_model(client: Client, name: str, scope: Scope | str | UUID, workflow: Workflow | str | UUID, contexts: List[Context | str | UUID], **kwargs: dict) → Form

Create a new form model.

Needs scope, name, workflow. :param client: The client connection to KE-chain API :param name: Name of the new form model :param scope: Scope or scope_id where to create the form model :param workflow: Workflow or workflow_id of the workflow associated to the form model,

should be in scope.

Parameters:

• contexts – A list of Context or context id’s to link to the Form model.

• kwargs – Additional kwargs such as contexts.

property status_forms

Retrieve the Status Forms of this Form.

property is_model: bool

Form is a Form Model or Form Template.

property is_instance: bool

Form is a Form Instance.

property is_active: bool

Form is an active Form.

instances(**kwargs) → [typing.List[ForwardRef('Form')]]

Retrieve the instances of this Form Model.

instance(**kwargs) → Form

Retrieve a single instance of a Form Model.

edit(name: str | ~pykechain.utils.Empty | None = <pykechain.utils.Empty object>, description: str | ~pykechain.utils.Empty | None = <pykechain.utils.Empty object>, **kwargs) → None

Edit the details of a Form (model or instance).

Setting an input to None will clear out the value (exception being name).

Parameters:

• name (basestring or None or Empty) – optional name of the form to edit. Cannot be cleared.

• description (basestring or None or Empty) – (optional) description of the form. Can be cleared.

• kwargs – (optional) additional kwargs that will be passed in the during the edit/update request

Returns:

None

Raises:

• IllegalArgumentError – when the type or value of an argument provided is incorrect

• APIError – in case an Error occurs

delete() → None

Delete this Form.

Raises:

APIError – if delete was not successful.

instantiate(name: str | None, **kwargs) → Form

Create a new Form instance based on a model.

clone(name: str | None, target_scope: Scope | None = None, **kwargs) → Form | None

Clone a new Form model based on a model.

If target_scope is specified and different from the scope of the form, then use the clone_cross_scope endpoint. Otherwise, use the basic clone endpoint.

activate()

Put the form to active.

Model Forms can be put to inactive. When the Form model is not active the form cannot be instantiated. This methods sets the form to active.

deactivate()

Put the form to inactive.

Model Forms can be put to inactive. When the Form model is not active the form cannot be instantiated.

link_contexts(contexts: List[Context | str | UUID])

Link a list of Contexts to a Form.

Parameters:

contexts – a list of Context Objects or context_ids to link to the form.

Raises:

APIError – in case an Error occurs when linking

unlink_contexts(contexts: List[Context | str | UUID])

Unlink a list of Contexts from a Form.

Parameters:

contexts – a list of Context Objects or context_ids to unlink from the form.

Raises:

APIError – in case an Error occurs when unlinking

set_status_assignees(statuses: List[dict])

Set a list of assignees on each status of a Form.

Parameters:

statuses – a list of dicts, each one contains the status_id and the list of

assignees. Available fields per dict:

param status:

Status object

param assignees:

List of User objects

Raises:

APIError – in case an Error occurs when setting the status assignees

Example

When the Form is known, one can easily access its status forms ids and build a dictionary, as such:

>>> for status_form in form.status_forms:
>>>    status_dict = {
>>>        "status": status_form.status,
>>>        "assignees": [user_1, user_2]
>>>    }
>>>     status_assignees_list.append(status_dict)
>>> self.form.set_status_assignees(statuses=status_assignees_list)

possible_transitions() → List[Transition]

Retrieve the possible transitions that may be applied on the Form.

It will return the Transitions from the associated workflow are can be applied on the Form in the current status. :returns: A list with possible Transitions that may be applied on the Form.

apply_transition(transition: Transition)

Apply the transition to put the form in another state following a transition.

Apply transition is to put the Form in another state. Only transitions that can apply to the form should have the ‘from_status’ to the current state. (or it is a Global transition). If applied the Form will be set in the ‘to_state’ of the Transition.

Parameters:

transition – a Transition object belonging to the workflow of the Form

Raises:

APIError – in case an Error occurs when applying the transition

Example

When the Form and Workflow is known, one can easily apply a transition on it, as such:

>>> transition = workflow.transition("In progress")
>>> form.apply_transition(transition=transition)

has_part(part: Part) → bool

Return boolean if given Part is part of the Form tree.

Based on the Parts category, either the model or the instance tree is checked.

Parameters:

part – a Part object

Raises:

• IllegalArgumentError – in case not a Part object is used when calling the method

• APIError – in case an Error occurs when checking whether Form contains the Part

set_prefill_parts(prefill_parts: dict) → None

Set the prefill_parts on the Form.

Prefill parts are insatnces of a part model that are stored on the Form Model (only for models) and these instances of the parts are instantiated by the backend when the Form is also instantiated.

Set the prefill_parts on the form collection model using a special structure. The structure is jsonschema validated by the backend before the Form is updated.

The prefill_parts on the form should be in the following structure: ``` {

<uuid of the part_model>[

{

# an individual instance with ‘partname’=’name’ name: null_string, part_properties: [

{

property_id: <uuid>, value: <null_string>

},{…}

]

}, {…}

], <uuid of another part_model>: […]

}

param prefill_parts:

dictionary of <part_model_id>: [array of instances to create]

raises APIError:

When the prefill_parts is tried to be set on Form Instances

raises APIError:

WHen the update of the prefill_parts on the Form does not succeed.

workflows_compatible_with_scope(scope: Scope)

Return workflows from target scope that are compatible with source workflow.

Parameters:

scope – a Scope object

Raises:

• IllegalArgumentError – in case not a Scope object is used when calling the method

• APIError – in case an Error occurs