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 Ellipses ButtonOpens 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 General Knowledge Search ButtonOpens 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 Legal Values ButtonEnabled 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.

    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 the Annotations for a One-Step Action.
  7. Click Save.