Workflows

View as Markdown

A workflow is a state machine that an object moves through, such as Draft, Waiting for Approval, Approved. In M-Files the workflow and the state are property values of the object version, so moving an object to another state is a property change that the server checks against the workflow's rules.

The pieces

Each state belongs to one workflow. State IDs and transition IDs are their own ID spaces: state 135 and transition 2 below are unrelated numbers.

Sample Vault workflow 106 "Reviewing drawings"

  (no state) --[1]--> 135 Listed for approval --[2]--> 136 Approved
                                  ^                          |
                                  '----------[3]-------------'

Classes link to workflows: ObjectClass.default_workflow proposes one, and with force_workflow true every object of the class must use it. In the Sample Vault, class 2 (Purchase Invoice) forces workflow 102; creating an invoice without it fails with 'The specified workflow "(empty)" is not allowed for this class.' A workflow's object_class_id in Workflow is -3 when it is meant for all classes.

Reading workflows and the allowed transitions

• GetWorkflowsForClient lists the workflows.
• GetWorkflowStatesAndTransitions returns the states of one workflow and the transitions out of current_state. Without current_state it returns the states and no transitions. Each StateTransitionBasic has from_state_id, to_state_id and can_current_user_select.
• Pass obj_ver too when the transition permissions depend on the object (for example "the object's owner may approve"). Without it, transitions whose permissions refer to such object-specific users are reported as selectable, and are_state_transition_permissions_object_specific tells you that the flag cannot be trusted.
• GetWorkflowStateHistory returns the object's workflow state history as object versions with their property values.
• The full definitions (state actions, preconditions, transition permissions, signature settings) come from GetWorkflows, which needs administrator rights.

Changing the state

Set property 39 to the new state, in any call that writes properties: SetProperties, CheckIn or AddObject.

SetPropertiesRequest
  obj_ver { obj_id { type: 0 item_id { internal_id: 546 } }
            version { type: OBJ_VER_VERSION_TYPE_SPECIFIC internal_version: 1 } }
  allow_modifying_checked_in_object: true
  properties { property_def: 39
               value { type: DATATYPE_LOOKUP data { lookup { value_list_item_info {
                       obj_id { type: 8 item_id { internal_id: 136 } } } } } } }

Run against the Sample Vault, this moved a document from state 135 to 136 and created version 2 with property 40 set to the time of the change. Alternatively, set property 99 to a transition ID: the server then sets property 39 to the transition's target state.

The server checks the change and answers with an error when it is not allowed (messages shortened; the server puts line breaks between their parts):

To start an object in a workflow, set property 38 and the first state in property 39 together. Setting only property 38 leaves the state empty.

A state can carry actions that run when an object enters it. In the Sample Vault, the first state of the invoice workflow is defined to replace the object's permissions and to assign the object to a user, so a state change can change who can see the object.

Electronic signatures

A state transition can require an electronic signature, for example for regulated approvals. GetStateTransitionSignatureSettings returns the transition's ElectronicSignatureSettings (is_required, the reason and meaning to show, where the signature is stored). Requests that change properties have a signature field for the signature; the remarks of SetProperties describe what it holds. The workflows of the Sample Vault require no signatures.

The workflow state guide puts these calls together.