Define a Link/Unlink Business Object Action

Use the Link/Unlink Business Object Action to link or unlink a Business Object in a Relationship. The Link/Unlink Business Object Action adds records to or removes them from a Relationship, which adds/removes them from tabs in Form Arrangements.

For example, link critical Configuration Items to the active Incident.

Link Relationships are the only type of Relationships to which Business Objects can be linked/unlinked using this Action. Records can only be linked to/unlinked from an existing Relationship. If a Relationship does not already exist, create one. If a Relationship is not already displayed as a tab in a Form Arrangement, linking/unlinking records in the Relationship does not add or remove tabs in the Form Arrangement; it only adds or removes records in existing tabs.

To define a Link/Unlink Business Object Action for a One-Step™ Action:

1. Open the One-Step Editor.
2. Add a Link/Unlink Business Object Action to the Designer Board.
3. Define general properties for the Link/Unlink Business Object Action:

   Option	Description
   Name	Provide a display name for the Action (this is how the Action is identified within the One-Step Action).
   Link	Add records to the selected Relationship.
   Unlink	Remove records from the selected Relationship.
   Business Object	Select the Business Object to link/unlink.
   Link to Relationship	Select the Relationship to which the Business Object records are linked/unlinked.

4. Define which records to link/unlink:

   To link records:

   Option	Description
   Records	Provide a display name for the Action (this is how the Action is identified within the One-Step Action).
   Ellipses	Opens the Search Manager; select an existing Saved Search or create a Saved Search. Saved Searches can be used over and over in numerous places.
   Custom Query	Opens the Custom Query Builder; create a custom Search Query to use only for this scenario.
   Join Reason	Provide a join reason, or click the Selector button to open the Token menu and insert a Token to use as the join reason. A join reason allows you to provide brief information about why records are being linked. A join reason can be provided only if the selected Relationship uses a join table and has join reasons enabled. If join reasons are used for the Relationship, and no join reason is provided for this Action, the join reason defined for the Relationship is used. For more information, refer to Define Links Properties for a Relationship
   Legal Values	Enabled if there is a list of valid values to use for the join reason. These are based on the list of values defined for the selected Relationship's join reason. For more information, refer to Define Links Properties for a Relationship

   To unlink records:

   Option	Description
   Condition	Unlink records based on an Expression, and then select an Expression.
   Most recently used	Select a most recently used (MRU) Expression.
   Custom Expression	Click the Custom Expression button to open the Custom Expression Builder, and then create a custom Expression specifically for this scenario.

5. Define link/unlink options:

   Option	Description
   Link/Unlink all found records	Link/unlink all records found based on the defined search criteria or condition.
   Link/Unlink specific number of records	Link/unlink a specified number of records, and then provide a number, or use the up/down arrows to increase/decrease the number. The first x number of records are linked (up to the defined number of records). This option is only available if the Relationship is 1-to-many (multiple records can be linked/unlinked).
   Order By (Unlink only)	Select a Field from the related Business Object to use to control the order in which records are unlinked. Ascending: Unlink records in ascending order (example: 0-10, A-Z) based on the selected Field. The alphabetical order rarely matches the order in which the records should be unlinked, unless you prefix the values with numbers or letters (example: For status, you would likely want lifecycle order, not alphabetical order); therefore, it is common to define a Field that contains a sequence number purely for controlling the order (example: Status Order). Selecting (Default) unlinks records in ascending order based on the default sorting column in the related Business Object's default Grid.
   Save Business Object After Action	Select the check box to automatically save updates to the Business Object after the Action executes. If the check box is cleared, updates to the Business Object are not automatically saved. Users are prompted to save their changes if they navigate from the Business Object, however. This includes changes made by the Action and any changes made by Users before they ran the One-Step. The One-Step Action continues to run whether or not they choose to save their changes. In the Browser Client and Portal, this occurs after the last Action is executed for the One-Step Action. Note: If the One-Step Action is run from the Scheduling Server or an Automation Process, there is no Prompt to save changes and they may be lost.

6. Define Annotation properties.
7. Click Save.