Methods available for transitions

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

learning:
Existing methods usable in actions on lifecycle transitions
level:
Intermediate
domains:
XML, Stopwatch, Automation, Lifecycle
min version:
2.3.0

Within an XML customization of a class lifecycle, you may want to do some actions when a particular transition is executed on an object. In general those actions, required to write a method on that object class (which can be done with a mix of XML and PHP), or use already existing methods declared on CMDBObject.

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.

Arguments

$sAttCode

  • 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.

$value

  • a fixed literal value, in general a string, but it can also be a number
Those methods are not making any control on the provided parameters, so be cautious to provide valid arguments or your iTop will crashes

Methods

AddValue($sAttCode, $iValue = 1)

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 a 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">agent_id</param>
        <param id="2" xsi:type="integer">2</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 crasy example.

Don't copy this example: as increasing the agent_id of 2, may point to an no-existing Person or to a Team, which in both cases, leads to an incoherent database!

Copy($sDestAttCode, $sSourceAttCode)

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($sAttCode)

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

ResetStopWatch($sAttCode)

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($sAttCode, $value)

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);

SetIfNull($sAttCode, $value)

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.

SetCurrentPerson($sAttCode)

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

SetCurrentDate($sAttCode)

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

SetCurrentDateIfNull($sAttCode)

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

SetElapsedTime($sAttCode, $sRefAttCode, $sWorkingTimeComputer = null)

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

latest/customization/actions-on-transitions.txt ยท Last modified: 2021/07/06 15:44 (external edit)
Back to top
Contact us