This is not the latest version of Identity Director documentation.
View available documentation.

Icon

Invoke Run Book

Add the Invoke Run Book action to invoke a Run Book in an Ivanti Automation environment, for example to create user accounts, e-mail accounts, or to install software. This requires that you can connect to the Ivanti Automation environment that contains the Run Books.

See the Ivanti Automation documentation at http://help.ivanti.com for more information about Run Books and Run Book Parameters.

Configuration of Properties tab

Field

Explanation and Tips

Action Name

Optionally, specify a friendly name for the action. This name must be unique in the workflow.

Run Book

Specify the Run Book that should be invoked.
When you select a Run Book:

  • Click Refresh on the Select Run Book page to refresh the list of Run Books. This is useful if an Ivanti Automation administrator created a new Run Book while you configured the Invoke Run Book action.
  • Click the Run Book name to open the Ivanti Automation Management Portal on a new tab and view the Run Book. This functionality is only available if you have configured Automation redirection, at Setup > Ivanti Automation.

Computer

If the Run Book is configured to Ask during Run Book scheduling who should execute the job, specify the Automation Agent that should execute the Run Book. Leave this field empty if you Use a Run Book Parameter ($[RunBookWho] by default) to determine the Automation Agent that will execute the Run Book.

  • You can specify one Agent only: if you specify multiple Agents, Ivanti Automation cancels the Job.
  • You can specify service attributes. If so, you need to precede this action with a Provide Information action.
  • You can specify one of the following requester placeholders to identify the Agent that should execute the Run Book:
    • Use #Requester[DeviceName] to resolve the device name of the requester (e.g. VM-win7). Use this placeholder in managed environments to configure services that are delivered specifically to the device from which they were requested, instead of to any device on which a user logs on. For example, if a service is aimed at delivering Microsoft Visio, it is delivered to the device from which it is requested only; when the user logs on at a different device, the service is not delivered again.
    • Use #Requester[DeviceID] to resolve the GUID of the Agent (e.g. "{A299DF-611E-4479-A25A-8C8A4BdB7B6A}"). Use this placeholder in non-corporate and SaaS environments, in which Agent names are not guaranteed to be unique.
      • These placeholders only work for a requester, not for automatically delivered services or services requested by someone else. If the device name of the requester cannot resolve in a value, it is blank.
      • Identity Director uses DNS to resolve the IP address of the device from which the service is requested. This requires that you configure your DNS settings correctly.
      • If many users in your environment work from a Terminal Server session, consider the nature of the service before using these placeholders: If the service installs software, this may lead to undesired behavior, as it is installed on the Terminal Server.

Tags

Optionally, specify tags to pass on to Ivanti Automation, to be used during execution of the Run Book.

  • Separate tags with a semi-colon (;)

Schedule in parallel with other jobs

Schedule the runbook in Automation to use the parallel processing functionality of Automation.

Wait for Run Book to finish

Pause the transaction until the Run Book has been executed. This is useful if other actions depend on it.

  • Clear the option to let the workflow of the service continue, while the execution of the Run Book runs in the background. Although this may result in a faster service delivery, it may also lead to unexpected results: The service transaction may succeed, even if the execution of the Run Book fails.
  • If the option is not enabled, the service waits for the Run Book workflow action to be queued up in Automation. If the Run Book is not queued, or is scheduled to an offline Automation agent, the Run Book action fails and the service execution follows the exception path of the Invoke Run Book workflow action.

Stop transaction if Run Book fails/fails to launch

Verify if the Run Book was invoked or executed successfully.

  • If you configured an exception, the actions in the exception are executed instead.

Combinations

You can use various combinations of the options Wait for Run Book to finish and Stop transaction if Run Book fails/fails to launch to specify how the Invoke Run Book action should behave in the workflow:

  • Select both options to verify if a Run Book was executed successfully: this pauses the transaction until the Run Book has been executed. If the Run Book fails, the action is marked as Failed and any remaining actions in the workflow are not executed. If you configured an exception, the actions in the exception are executed instead. This combination is useful if other actions depend on the results of the Run Book.
  • Select Stop transaction if Run Book fails to launch only to verify if the Run Book was invoked successfully. This is useful if the results of the Run Book are irrelevant for the remainder of the workflow: it continues while the Run Book runs in the background. Although this may result in a faster service delivery, it may also lead to unexpected results: The transaction of the service may succeed, even if the execution of the Run Book fails. If the Run Book fails to launch, the action is marked as Failed. Any remaining actions in the workflow are not executed. If you configured an exception, the actions in the exception are executed instead.
  • Select Wait for Run Book to finish only to pause the workflow until the Run Book has been completed. If the Run Book fails, the action is marked as Successful and the workflow continues; any exceptions are ignored.
  • Clear both options to let the workflow continue while the Run Book runs in the background, irrespective of whether the Run Book fails or fails to launch. If the Run Book fails or fails to launch, the action is marked as Successful, and the normal workflow continues; any exceptions are ignored.

Workflow Detail

Specify the level of detail that is shown when people track the service status. Depending on your configuration of this field, the Label field specifies the status information.

  • Select Default to show the behavior configured at Setup > Behavior.
  • Select Status only to show the status of the service.
  • Select Workflow action to show the status of the action.
  • Select Full details to show the status of the action and its actor.
  • Select Use custom label to configure a custom text.

One of the input settings of Ivanti Automation Parameters is the option When scheduling Job, which asks for input when a Job is scheduled. Identity Director uses this option to determine whether to show parameters on the Run Book Parameters and Run Book Results tabs: These tabs are only shown if the option When scheduling Job is selected in Ivanti Automation.

Configuration of Run Book Parameters tab

If a Run Book contains parameters, provide the necessary input. You can specify service attributes, to let the value of Run Book Parameters depend on service attributes. To provide input for these attributes during the transaction, the Invoke Run Book action needs to be preceded by a Provide Information action or a Set Service Attribute action.

  • If you Use a Run Book Parameter ($[RunBookWho] by default) to determine the Automation Agent that will execute the Run Book, that parameter should be listed on this tab. If the Run Book is configured to Ask during Run Book scheduling who should execute the job, use the Computer field (on the Properties tab of the Invoke Run Book action).

    If the parameter is not listed, verify that it asks for input When scheduling Job (in Automation, on the Input tab of the Run Book parameter).

Item

Explanation and Tips

List service attributes

If you specify service attributes, you can link them to corresponding list parameters in the Ivanti Automation Run Book.

  • Select Use Run Book Parameter to select a static value from the list of Run Book Parameter values.
  • Select Use service attribute to provide a dynamic value of the Run Book Parameter, by linking it to a service attribute.
    • You can only use list or text service attributes.
    • When you specify a list service attribute, only the selected value in this attribute are provided to the Run Book Parameter.

Password service attributes

If you specify password service attributes, you can map them to corresponding password parameters in the Ivanti Automation Run Book. Because the values of password service attributes remain encrypted when passed from the service to the Run Book, this allows for secure scenarios in which a user or a manager can request a password change for a login account via a Run Book.

Date service attributes

If you specify date service attributes, you can map them to text parameters in the Ivanti Automation Run Book.

Configuration of Run Book Results tab

This tab is only available if the specified Run Book contains Run Book Parameters where the Action is set to Get Final Value or Both in Ivanti Automation. It allows you to let the value of service attributes depend on Run Book Parameters. These values are set when the Run Book is executed. This allows you to use the resulting Run Book Parameter values in another action of the same service, for example to satisfy a Run Book condition or to generate a user name.

If the Transaction Engine cannot retrieve the Run Book Parameters the first time, it will retry a maximum of 4 times, until successful.
The first retry will start 30 seconds after the initial retrieval attempt.
If needed, the second retry will start 60 seconds after that, the third retry 90 seconds after that and the fourth retry 120 seconds after that.

Item

Explanation and Tips

Perform Table Operation

If you specify table service attributes, you can link them to Run Book Parameters of the same format. This column specifies what should happen with the provided values:

  • Select Overwrite to overwrite the values in the table service attribute with the values of the Run Book Parameter.
  • Select Append to add the values of the Run Book Parameter as a new row in the table service attribute.

Example

Consider the following scenario:

The Ivanti Automation Run Book contains a list parameter Ivanti Products with the following settings:

Setting

Description

A

Ivanti Automation

B

Ivanti Workspace Control

C

Identity Director

The service contains a list service attribute Ivanti Products with the following settings:

Setting

Description

B

Ivanti Workspace Control

C

Identity Director

A

Ivanti Automation
  • If you specify a list service attribute, the selected value is provided to the Run Book Parameter (e.g. B;Ivanti Workspace Control). In this case, this results in Setting: B Description: Ivanti Workspace Control for the Run Book Parameter.
  • If you specify a text service attribute and it contains a value like C;Identity Director, this results in a corresponding value for the Run Book Parameter.
See also