Act on Related Object
You use an Act on Related Object operation to configure how to change another related object or multiple objects. Some changes can be as simple as updating a related object’s field, others may involve triggering workflow Functions on multiple related objects or sending notifications.
You first choose on which objects to act, and then add operations to be invoked on the target related objects. So, Act on Related Object operations are effectively "anonymous" functions that contain other operations like Update Field, E-mail Notification, etc.
NOTE: Typically you work with the Objects that already exist in the database by the runtime of the Action or Trigger executing your Act on Related Object operation. Nevertheless, in some cases, the system allows you act on unsaved objects created earlier by a Create Object operation or related by Relate To operation on the current Programming tab/ When the operation is not possible, the warning message “Exclude new, unsaved [Objects]” is displayed in the Act on Related Object window.
An Act on Related Object operation is effectively a looping statement common in programming languages. It performs the nested set of operations on each object in a collection of objects that satisfies your selection criteria. Those operations are identified by the LOOP and END LOOP rows in the list of operations.
To configure an Act on Related Object operation:
-
In the Select Related Object window, select the relation between the current object and the target (related) one:
-
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 selected as the Incident Assignee. To choose such a Person for the Incident, select Reference Object > Assignee.
NOTE: For this type of relations between the current object and the target object, the system allows you to act on unsaved objects created earlier on the current Programming tab.
-
To choose one or multiple neighboring objects, click Neighboring Objects, select the relation, and click OK. For example, a Computer may have one or more Assets related to this Computer as the Associated Cis. To choose such an Asset for the Computer, select Neighboring Objects > Assets (where Computer is Associated CI).
NOTE: For this type of relations, the system allows you to act on unsaved objects created earlier on the current Programming tab only when the filtering option Where is not applied.
-
To choose one or multiple objects related to the current object on the current object's ”Related Objects” tab, click Related Objects, select the object, and click OK. You will choose their relationship type on the next step. 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 window opens. The top section displays the current object class, the Related Object(s) field displays the target related object or multiple objects.
-
If you chose the Related Objects option on the previous step, select a relationship with the current object from the Relationship list. For example, to choose a KB Article based on the Incident, select Incident - Basic for - KB Article. For objects that do 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.
-
For 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 objects that met the criteria. For the By Object IDs (GUID) relationship, the Where ID in field is available. Here, you can create a SQL expression or script returning IDs of target objects.
-
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. If you want to affect only a single object with the highest rank of 1, select the Skip remaining objects in the loop check box.
-
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.
-
Keep the Enable operation check box selected to enable the operation. Otherwise, the operation will be disabled.
-
Click OK. The LOOP node appears in the list of operations. The LOOP node is empty, meaning that your operation does not yet affect the related object.
-
Click OK. The LOOP Object ($Object) and END LOOP rows appear in the list of operations. The LOOP node is empty, meaning that your operation does not yet affect the related object.
NOTE: The $Object identifier will help you identify the related object in nested Create Object and Act on Related Object operations. For details, see Using automatic variables.
-
Right-click the LOOP row and choose New > [Operation] from the pop-up menu. For instructions, see Adding workflow operations. By default, operations run unconditionally, but you can configure conditional statements if needed.
IMPORTANT: Unlike direct operations on the current object, all operations in the LOOP node are executed on the related objects.
Once you add Act on Related Object operations, Alloy Navigator makes available automatic variables. For details, see Using automatic variables.