Administration Guide

Act on Related Object

You use an Act on Related Object operation to make changes to related objects. Some changes can be as simple as updating a related object’s field, others may involve triggering workflow Functions or generating E-mail Notifications. You first choose on which objects to act, and then add operations to be invoked on selected related objects.

The new operation appears in the Operation list as a section consisting of an opening and closing elements, LOOP and END LOOP, respectively. Any operations that you put inside the LOOP section will be applied to each object identified by the LOOP statement. When there are multiple target objects, the operations are performed on every object that satisfies your selection criteria.

NOTE: Typically, when Actions or Triggers execute an Act on Related Object operation, they act on objects that already exist in the database. Nevertheless, in some cases, you can configure an operation to act on objects that just are to be created by earlier operations specified on the same Programming tab. When such an Act on Object operation is not possible, the Act on Related Object dialog box displays a warning message, alerting that the operation will affect only existing objects, unsaved objects will be excluded.

To configure how to act on related object:

  1. In the Select Related Object dialog box, choose how the target objects are related to the current object:
    • To choose a single object that has a direct relation with the current object via a current object’s attribute, click Referenced Object, select that relation, and click OK. For example, a Person has a direct relation to an Incident when this Person is the Assignee on that Incident. To choose such a Person for the Incident, select Referenced Object > Assignee.

      NOTE: For this type of relations, the system allows you to act on unsaved objects created earlier on the current Programming tab.

    • To choose a single or multiple neighboring objects, click Neighboring Objects, select the relation, and click OK. For example, a Computer may have one or more neighboring Incidents where this Computer is a Related CI. To choose such an Incident for the Computer, select Neighboring Objects > Incidents (where Computer is Related CI).

      Selecting a neighbor:

      NOTE: For this type of relations, the system allows you to act on unsaved objects, however, only if no filtering option was applied. If filtering is applied, the operation is not possible, and a warning message is displayed in the Act on Related Object dialog box.

    • If objects are related to the current object via indirect relationship, click Related Objects and select an object class. You will choose their relationship type later. This option also allows you to choose objects that do not have a direct relationship with the current object.

      NOTE: For this type of relations, the system does not allow you to act on unsaved objects. The Act on Related Object dialog box .

    The Act on Related Object dialog box opens.

  2. If you chose the Related Objects option on the previous step, specify a relationship with the current object from the Relationship list.

    NOTE: The Relationship list displays parent-child relationships from the current object’s side. For example, if the current object is an Incident, in order to specify KB Articles based on that incident, choose Incident - Basis for - Knowledge Base Article. For details, see Configuring Object Relationship.

    NOTE: To choose an object that does not have a direct relationship with the current object, select By object IDs (GUID). This will allow you to create a SQL expression or script returning IDs of target objects.

  3. When you selected multiple related objects, the Where field is available. You may want to narrow the scope of affected objects by specifying criteria. The operation will affect only those that meet the criteria.
    • To build the criteria, click Criteria, and configure conditions in the Criteria dialog box.

      INFO: For details, see Building Criteria.

    When you selected the By object IDs (GUID) option, the Where ID in field is available. Here, you can specify a SQL expression or script returning IDs of target objects.

    • To specify a SQL expression or script, click the Build Expression button . The Build Expression dialog box opens.

      INFO: For more information on building SQL expressions, see Using the Expression Builder.

  4. For ranked objects such as Approval Stages, Approval Requests, or Group Members, you can narrow the scope of affected objects to only the first one. Select the Skip remaining objects in the loop check box, and the operation will affect only a single object with the highest rank of 1.
  5. You can control whether the Triggers on the related object (or objects) are fired when the operation modifies those objects. If the Execute triggers on updated object(s) check box is selected, Triggers will fire.

    INFO: For details, see Adding On Created/Modified Triggers.

    Acting on Assets associated with the current Computer:

    Acting on Assets associated with the current Computer

  6. Keep the Enable operation check box selected. Otherwise, this operation will be ignored.
  7. Click OK to close the Act on Related Object dialog box. The new operation appears in the Operation list as a section consisting of an opening and closing elements, LOOP and END LOOP, respectively. Any operations that you put inside the LOOP section will be applied to each object identified by the LOOP statement.

    An empty LOOP section:

Initially, the LOOP section is empty, meaning that your operation does not affect the related object just yet. Now you should configure what actually happens to objects within the loop, i.e. add other operations inside the LOOP section: Update Field, Execute Function, Execute SQL, E-mail Notification, Act on Related Object, etc. By default, operations run unconditionally, but you can enclose your operations in conditional blocks, if needed.

INFO: For details and instructions on adding operations, see Adding Operations.

INFO: For details and instructions on enclosing your operations in conditional blocks, see Building Conditional Statements.

For example, to invoke a Function on the related objects, proceed as follows:

  1. Keep the LOOP element selected and click New > Execute Function.
  2. Double-click the desired Function. The Execute Function dialog box opens.
  3. Under Parameters, specify parameter values that are passed to the Function. Default parameter values will display <Default> in red color. Mandatory parameters that haven't been assigned yet will display <Double-click to assign value> in red color.

    IMPORTANT: You cannot invoke a Function only with assingned parameter values.

    Assign parameter values as follows:

    • Assign a predefined value:
      • Right-click a parameter row and choose a value from the pop-up list. Contains the following items:
        • <Empty> the placeholder for an empty value as the parameter value.
        • When the Act on Related Object operation is invoked from an Action: If the invoker Action Form has virtual fields, the list displays virtual fields of the same data type as the target parameter.

        INFO: For details on Forms, see Creating Forms.

        • When the Act on Related Object operation is invoked from another Function: If the invoker Function has its own parameters, the list contains parameters of the same data type as the target parameter.

        INFO: For details on Functions, see Creating Functions.

        Assigning parameter values for an Act on Related Object operation:

        NOTE: The warning at the top is there to remind you that you are configuring this operation on an object which will be created in the course of running a step action on another (primary) object. In our example, your current object is a Computer, but you are assigning parameter values for an Asset.

      • If the pop-up list does not contain the value which you need, proceed as follows:
        1. Double-click the parameter row to bring up the Assign Parameter dialog box.
        2. Specify a parameter value in the Value field using the Expression Builder.

        INFO: For details, see Using the Expression Builder.

  4. Once you have assigned all parameter values, click OK to close the Execute Function dialog box. The new Execute Function operation appears inside the LOOP section.

    An Execute Function operation on related objects:

Now you can add other operations to the LOOP section. For example, you can add another Act on Related Object operation with a Function for updating the status of associated objects, as illustrated below.

Nested Act on Related Object operations: