Methods available for transitions

Prerequisite: You must be familiar with the Syntax used in Tutorials and have already created an extension.

Within an XML customization of a class lifecycle, you may want to execute some actions when a particular transition is occurring on an object.

For this, you must:

1. Modify the XML lifecycle to call the action (an action is a PHP method of the object class) - Check this tutorial to see how to do that.
2. You can either write a PHP method on that object class or use already existing methods declared on DBObject, which are listed and explain in this tutorial.

Below you will find some of the Methods which exist already on all classes and can be used in action. Those methods have arguments, which are often the same.

• We will start by explaining the expected content of those arguments.
• Then we will detail the behavior of each method.

• It is a string, which must be a valid attribute code for that class.
• There is no control that the provided string code is a valid attribute for the current class, fatal error will occur if not
• It can be found in the field id of the XML class definition.
• It can also be found in your iTop, in the Datamodel Viewer, as the code, not the label, of the attribute

$sDestAttCode and $sSourceAttCode are aliases, following the same rules.

• a fixed literal value, in general a string, but it can also be a number

Allow to increment or decrement a field of the current object

• No control on the type of field provided, nor on the value. Invalid combination will crash iTop.
• The $value is expected to be an number or a float. It can be negative.
• The $sAttCode should be the code of an attribute of type Decimal, Integer, Percentage or Duration. For other types, results are unpredictable.

itop-design / classes / class@UserRequest / lifecycle / states / state@New / transitions / transition@ev_assign

  <actions>
    <action id="1">
      <verb>AddValue</verb>
      <params>
        <param id="1" xsi:type="string">assign_counter</param>
        <param id="2" xsi:type="integer">1</param>
      </params>
    </action>
  </actions>

There is no object on the default datamodel with a lifecycle and an Integer, Decimal, Percentage or Duration field. This is why I proposed this example with a non-existing field “assign_counter”.

The execution of the method will add the $value to the content of the field $sAttCode. If $value is negative, then the value of $sAttCode will be decreased.

Allow to copy the content of a field of the current object in another field of that same current object

• No control to check if your attribute code are valid and coherent
• It does convert HTML into text if required
• Date and numbers are automatically converted into text
• The opposite transformation may work in rare cases where the format is the supported one.

Reset a particular field of the current object, to its default value.

Allow to reset a Stopwatch.

• It does control that it is a stopwatch attribute for the current object.
• It empties the TimeSpent,
• After the reset, it is as if it had never been stopped.
• If it was running, then it is still but starting all over again from now.

Set a fixed value in the specified attribute. It does not control any format or validity of the provided code nor value.

• Example, to set on a Ticket a particular caller_id, you must provide a number for the $value, which must correspond to an existing Person object in your iTop
• The $value to provide for an Enumeration is the code, not the label.

Set('caller_id',6);

Same as above, except if the field of the current object is already set, it is left unchanged.

• This is useful if you don't want to overwrite an already entered value for eg.

Compute a date starting from $sAttCodeSource date (using now if omitted), by applying on that date the provided $sModifier
Then it copy this computed date into the field $sAttCode.

• Field $sAttCode and $sAttCodeSource could be a date or a date-time or a string
• There is no control on the content of the field $sAttCodeSource so if it is a string not following this format YYYY-MM-DD or this one YYYY-MM-DD HH:mm:ss, the resulting date is unpredictable

What to put in the Modifier?

• +5 days
• -3 weeks
• first weekday of next month
• monday of next week

Formore options

Same as above, except if the field of the current object is already set, it is left unchanged.

• This is useful if you don't want to overwrite an already entered value for eg.

Allow to set in a field of the current object, the Person associated with the User executing this method

• Depending on the type of field:
  • if it's an ExternalKey pointing to the Person class or any parent class of Person, the id of the Person associate with current USer is copied. If there is no Person associated, then it's set to 0, which for ExternalKey is equivalent to empty.
  • if it's an ExternalKey pointing to another class, then it crashes
  • If it's a String, it put the friendlyname of the Person associated with the current user, if there is such Person
  • It does not do anything in other cases

Set a Date or DateTime attribute of the current object to now, so the date or time it is right now at the time of the method execution.

• Does not control that the attribute code is a Date or DateTime,
• The method would work on a String as well, using probably the iTop internal date format for this transformation

Same behavior as the above method, unless there is already a value in the field, in which case, it is left unchanged.

Check the code for details on this one in itop/core/dbobject.class.inc.php