Lifecycle: Flags on transition

New since version 2.4

When an object is going from a source state to a destination state using a transition, you can define which fields need to be documented (mandatory), changed (must_change) or just proposed (must_prompt) in the transition form

Flags on state

Flags must_change, must prompt and mandatory set on a state, applies to all transitions ending on that state.

If you don't want that behavior, remove them from the state and set them on the transitions where you want them.

Examples

For example, on a Ticket we have 3 different transitions ending on assigned state:

during a assign transition, you want to prompt the user for a mandatory agent (default behavior of all transitions before 2.4)
on a re-assign transition, you want to force the agent to be changed, (possible in XML since 2.4 only)
on a re-open transition performed on the portal, the agent field should not even be displayed (possible in Enhanced Portal since 2.4 only)
on an assigned state, agent should be in read-only mode in the Ticket modify form, otherwise a change of agent would not trigger the actions associated with the transition, such as a notification email to the new agent for example)
A field can now be required during a transition, hidden before and read-only after, thus allowing to limit write on that field only to users with profiles allowed to run that transition.

The 5th example demonstrate a new mean to control who can edit fields within an object.
Before 2.4, on the console either you can edit all the fields or none for a given object.
After, on the console you can limit edition of some fields within an object to some profiles only and restrict other fields of the same object to another profile if needed.
Such segmentation is possible on the Enhanced Portal since 2.3.0.

Configuring

Example n°2, how to configure it in the XML

  <class id="UserRequest">
    <lifecycle>
      <states>
        <state id="assigned">
          <transitions>
            <transition id="ev_reassign">
              <target>assigned</target>
              <flags>
                <attribute id="agent_id">
                  <must_change/>
                </attribute>
                <attribute id="team_id">
                  <must_prompt/>
                </attribute>
              </flags>
            </transition>

iTop behavior

Transition forms on the console are automatically built based on flags defined on the Datamodel. On the Portal, automatic form can be overwritten, with the exception of empty mandatory field which cannot be removed.

Flags applicable to a transition

For each field of the object, iTop combines all flags set on the transition and flags Must_xxx and Mandatory defined on the final state (and ignores any other final state flags such as hidden, read_only, read_write).

Transition Form

Checks flags in this order and stops after first match:

must_change: display in edit mode, value must be changed and different from previous one.
must_prompt: display in edit mode.
mandatory on final state or on transition and initial value is empty: display in edit mode.
read_only on the transition: display the field in read-only mode. 🚧 maybe it is portal specific.
if none of the above cases: do not display that field in the form.

Form Validation:

mandatory flag on transition, on final state or on field definition, then : force field to be documented
otherwise, field can be left empty.

Forcing an entry to be provided on a caselog during a transition, require to use the flag mandatory on that transition.
Must change does not force any entry on caselog

Modify Form on a state

Must Change force that field to be changed on the console (no effect on the portal)
Must Prompt no effect neither on the console nor on the portal.

Portal: defining transition form

Enhanced Portal supports specific forms by transition.

  <form id="ticket-reopen" _delta="define">
    <class>UserRequest</class>
    <fields/>
    <twig>
      <div>
        <div class="form_field" data-field-id="public_log" data-field-flags="mandatory"/>
        <div class="form_field" data-field-id="team_id" data-field-flags="hidden"></div>
        <div class="form_field" data-field-id="agent_id" data-field-flags="hidden"></div>
      </div>
    </twig>
    <modes>
      <mode id="apply_stimulus">
        <stimuli>
          <stimulus id="ev_reopen"/>
        </stimuli>
      </mode>
    </modes>
  </form>

Note than if no stimuli is defined for a “apply_stimulus” form, then this form will be used for all transitions.

As for any other form defined in the portal, you can set flags on a field to:

Hide a field to the portal user even if the field is prompted in the console

     <div class="form_field" data-field-id="xxxxx" data-field-flags="hidden"/>

Force the portal user to enter a value in a field even if the field is not mandatory in the console

     <div class="form_field" data-field-id="xxxxx" data-field-flags="mandatory"/>

Sidebar