Executing Workflows

This chapter contains the following sections:

Workflow Execution

When you execute a workflow, a service request is created. You can execute a workflow directly, schedule a workflow to run later, or create a trigger to run a workflow when certain conditions are met. You can also create a policy to execute workflows on VMs.

Each of these options is briefly outlined here.

  • Execute a Workflow Directly - You can execute a selected workflow immediately. Navigate to Policies > Orchestration > Workflows or open the Workflow Designer, then choose Execute Now.

  • Schedule a Service Request to be Executed Later - You can schedule execution of a selected workflow. Navigate to Policies > Orchestration > Workflows, then choose Schedule.

  • Trigger Conditional Workflow Execution - You can create a trigger to execute a workflow when a set of conditions is met. Navigate to Policies > Orchestration > Workflows, then choose Triggers.

  • Create an Action Policy - You can create a policy to execute workflows on VMs within a virtual data center (vDC). Navigate to Policies > Orchestration > Workflows, choose User VM Action Policy, then add the policy to a virtual data center (vDC).

Detailed instructions and examples are given in the following sections.

Executing a Workflow

You can execute a workflow immediately from either the Workflows page or the Workflow Designer.

    Step 1   Choose Orchestration.
    Step 2   On the Orchestration page, click Workflows.
    Step 3   Choose the workflow you want to execute by navigating to it on the Workflows page (it might be in a directory or subdirectory).

    Optionally, open the workflow in the Workflow Designer by clicking Workflow Designer.

    Step 4   Click Execute Workflow.
    Note    If you are in the Workflow Designer, Execute Workflow is near the upper right of the window.
    Step 5   On the Executing Workflow screen, choose the version of the workflow you want to run.
    Step 6   Also on the Executing Workflow screen, complete the user input fields for the workflow.

    The input fields show the workflow inputs that you are allowed to change as a user.

    If an input is mandatory and has no default input, you must provide a user input.

    Note   

    Workflow inputs can be defined with values (admin inputs) that cannot be overridden at runtime. Admin inputs are not displayed in the Executing Workflow dialog.

    Step 7   Click Submit. The Service Request Submit Status screen appears.
    What to Do Next

    On the Service Request Submit Status screen, click Show Detail Status to see the progress of the service request.

    Example: Executing a Workflow

    This example demonstrates executing a workflow directly.

    Before You Begin

    Create the example workflow as described in Example: Creating a Workflow.

      Step 1   Choose Orchestration.
      Step 2   On the Orchestration page, click Workflows.
      Step 3   Locate and select the PowerCycleVM workflow you created in Example: Creating a Workflow.
      Step 4   On the Executing Workflow screen, click Submit.
      Step 5   On the Service Request Submit Status screen, click Show Detail Status.
      Step 6   On the Service Request screen, click Workflow Status. On the status page is a graphic of the service request's progress.
      Step 7   Click Log to view the service request log.
      Note   

      Click Refresh to view the latest updates to the log.

      What to Do Next

      Click Workflow Status and record the Request ID from the report. You can view the status of a service request by ID at any time. See Viewing Service Requests.

      Click Close to leave the Service Request screen.

      Creating a Workflow Trigger

      You can define a trigger to execute a workflow when specific conditions are met. These conditions are typically the states of various system components. When you enable a trigger, Cisco UCS Director monitors the system state and when the trigger conditions are met executes the workflow you specify.

      To create a workflow trigger, follow these steps:

        Step 1   Choose Orchestration.
        Step 2   On the Orchestration page, click Triggers.
        Step 3   Click Add.
        Step 4   On the Add Trigger: Trigger Information screen, complete the following fields:
        Name Description

        Trigger Name

        A unique name for the trigger.

        Is Enabled

        Enables the trigger. (You can create and save a trigger, then enable it later.)

        Description

        A description of the trigger.

        Frequency

        The period between checks for the trigger rule. The choices for this period span three minutes to one month.

        Note   

        Internally, Cisco UCS Director polls for triggers every two minutes. Therefore, the actual period might be up to two minutes longer than specified. This can be significant for small trigger periods.

        For example, with Frequency set to three minutes, the trigger might activate up to three + two = five minutes after the trigger condition is satisfied.

        Trigger Type

        Choose the trigger type:

        • Stateful—The last trigger state is recorded and actions are executed when there is a change in the trigger state. (The trigger state is Active when the trigger conditions are met, and Clear otherwise.) You choose workflows for both trigger state transitions: one for when the trigger state changes from Active to Clear, and one for when the trigger state changes from Clear to Active. The trigger state is checked at the frequency specified in the Frequency drop-down list.

        • Stateless—The trigger is executed anytime the trigger conditions are met, at a frequency specified in the Frequency drop-down list.

        During execution of a triggered service request, additional requests by the same trigger are ignored. Only after the triggered service request has completed does the next polling event, as defined by the Frequency parameter, trigger another service request.

        For example: Stateful Trigger T has a Frequency parameter of 5 minutes. T polls parameter P at time 13:00 and finds that P meets the trigger criterion, so T executes a service request SR that runs for 8 minutes. At 13:05, T polls again but, because SR is still running, T does not execute another service request, regardless of the state of P. At 13:08, SR ends. When T polls again at 13:10, it executes a new service request if the criterion for P is met.

        Step 5   Click Next.
        Step 6   Specify the trigger conditions.
        1. On the Add Trigger: Specify Conditions screen, do the following: Expand the Conditions list.
        2. In the Add Entry to Monitor dialog box, complete the following fields:
          Name Description

          Type of Object to Monitor

          Choose which type of object to monitor with this condition.

          Object

          Choose the particular object to monitor. Entries in this list vary depending on the type of object. You might need to specify additional information (a pod, for example) to filter for the object.

          Parameter

          Choose an operational parameter to monitor. Entries in this list vary depending on the object.

          Operation

          Choose the relational operation for the trigger comparison. Entries in this list vary depending on the possible states of the parameter.

          Value

          Choose the value with which to compare the parameter. When the relation defined by Parameter, Operation, and Value is true, the trigger state is Active; otherwise, the trigger state is Clear.

        3. Click Submit.
        4. Repeat the previous two steps to add more trigger conditions.
        5. Choose one of the two options in the Trigger When drop-down list:

          • Choose All Condition(s) Satisfied to specify that the trigger state is true only when all of the trigger conditions are met.

          • Choose Any Condition(s) Satisfied to specify that the trigger state is true if one or more of the trigger conditions are met.

        Step 7   Click Next.
        Step 8   On the Add Trigger: Specify Workflow screen, choose the workflow or workflows to execute on the trigger:
        1. In the Select Workflow drop-down list under When Trigger State Becomes Active, choose a workflow. This workflow is executed:

          • Whenever the trigger state is Active (polled at a frequency specified in the Frequency drop-down list), if the trigger is stateless.

          • If and only if the trigger state has changed from Clear to Active since last checked one period ago (as specified in the Frequency drop-down list), if the trigger is stateful.

        2. If you chose the stateful trigger type, in the Select Workflow drop-down list under When Trigger State Becomes Clear, choose a workflow. This workflow is executed if and only if the trigger state has changed from Active to Clear since last checked one period ago (as specified in the Frequency drop-down list).
        Step 9   Click Next.
        Step 10   On the Add Trigger: Specify Workflow Inputs screen, enter all the required inputs for the workflow, and any needed optional inputs.
        Note   

        You must enter all inputs that are needed by the workflow. There is no opportunity for user input in a triggered workflow.

        Step 11   Click Submit.
        What to Do Next

        You can enable or disable a trigger by selecting the trigger on the Policies > Orchestration > Triggers screen and checking or unchecking Is Enabled.

        Example: Creating a Trigger to Execute a Workflow

        This example demonstrates creating a trigger to execute a workflow when a set of conditions are met.

          Step 1   Create a workflow with a single task as follows:
          1. Create the workflow as described in the following table.
            Name Description

            Workflow Name

            Type VM Power Event Notify.

            Description

            Type Sends an email when a VM changes power state.

            Workflow Context

            Choose Any.

            Select Folder

            Choose Orchestration Examples.

          2. Create an input as described in the following table:
            Name Description

            Input Label

            Type Admin Emails.

            Input Description

            Type Email addresses to send power event notifications.

            Optional

            Leave unchecked.

            Input Type

            Choose email_address_list.

            Value Restrictions

            Do not check Admin Input.

          3. Do not define any user outputs.
          4. In the Workflow Designer, add a Send Email task to the workflow.
          5. Complete the task information as described in the following table:
            Name Description
            Task Information screen

            Task Name

            Type VMPowerEventEmail.

            User Input Mapping screen

            Email Addresses (Mandatory)

            Check Map to User Input.

            Task Inputs screen

            Subject

            This is the subject line of the notification email. Type VM power event notification.

            Body

            This is the body of the notification email. Type One of the following VMs has had a power -on or power-off event: (list the VMs in your VMPowerCycle workflow).

            Value Restrictions

            Do not check Admin Input.

          6. On the User Output Mapping page, do not map any outputs.
          7. Validate the workflow, then exit the Workflow Designer.
          Step 2   Click Triggers.
          Step 3   Choose Add.
          Step 4   On the Trigger Information screen, complete the following fields:
          Name Description

          Trigger Name

          Type VMPowerEvent.

          Is Enabled

          Leave this checked.

          Description

          Type Executes VMPowerEventEmail when a power-on or power-off occurs on a monitored VM.

          Frequency

          To test the trigger, you want a short time between polls. Choose 3 minutes.

          Trigger Type

          Choose Stateful. This causes the trigger to activate when a condition changes between polls.

          Step 5   On the Specify Conditions screen, add some conditions.
          1. Expand the Conditions list and add a condition using the following values:
            Name Description

            Type of Object to Monitor

            Choose VM.

            Object

            Choose a VM to be monitored.

            Parameter

            Choose Power Status.

            Operation

            Choose Equals.

            Value

            Choose ON.

          2. Repeat the last step to add more VMs to be monitored. Each VM has its own condition.
          3. In the Trigger When drop-down list, select Any Condition(s) Satisfied.
          Step 6   On the Specify Workflow screen, complete the fields using the following values:
          Name Description

          Maximum Invocations

          For demo purposes, choose 20. You might choose Unlimited in an actual production application.

          When Trigger State Becomes Active

          In the Select Workflow drop-down list, choose VMPowerEventNotify. The trigger executes this workflow when any of your monitored VMs changes from OFF to ON as defined on the Specify Conditions page.

          Note   

          Items appear by serially assigned ID number in the drop-down list, so your workflow is at the bottom of list.

          When Trigger State Becomes Clear

          In the Select Workflow drop-down list, choose VMPowerEventNotify. The trigger executes this workflow when any of your monitored VMs changes from ON to OFF as defined on the Specify Conditions screen.

          What to Do Next

          Test the trigger by turning on or off one of the monitored VMs. Make sure that the VM's state remains changed for at least three minutes. The trigger polls the state, so any change that is not visible at the time of polling (on and back off during the three minute wait interval, for example) does not activate the trigger.

          Scheduling a Service Request

          You can schedule execution of a workflow for a specific time.

            Step 1   Choose Orchestration.
            Step 2   On the Orchestration page, click Workflows.
            Step 3   On the Workflows screen, choose the workflow that you want to schedule.
            Step 4   Click Schedule.
            Step 5   On the Schedule Workflow screen, complete the following fields:
            Name Description

            Recurrence Type

            Whether and at what frequency you want the workflow execution to recur. Choose one of the following:

            • No End—Execute the workflow repeatedly without end at intervals defined by Frequency Type and Frequency Interval, starting at Start Time.

            • Only once—Execute the workflow only once, at Start Time.

            • Fixed Number of Times—Execute the workflow a number of times specified by Repeat Count at intervals defined by Frequency Type and Frequency Interval, starting at Start Time.

            • End by Date—Execute the workflow until the defined end time at intervals defined by Frequency Type and Frequency Interval, starting at Start Time.

            Start Time

            The time at which to start the workflow execution (or the first of a series of recurring executions).

            Frequency Type

            The unit of the recurrence frequency interval. Choose hourly, daily, weekly, or monthly.

            Frequency Interval

            Choose the interval at which the workflow needs to be executed for the frequency that you chose. For example, if the Frequency Interval is four and the Frequency Type is daily, the workflow is executed every four days.

            User ID (optional)

            The user ID to run the workflow. The service request runs with the permissions of this user ID.
            Note    You must provide inputs with the workflow. Scheduled workflows do not accept user inputs.
            Note    The same workflow can be run from any number of workflow schedules.
            What to Do Next

            Click Workflow Schedules to view scheduled workflows.

            On the Workflow Schedules screen, you can modify a scheduled workflow by choosing a workflow and clicking the Edit button. The Modify Workflow Schedule screen appears. Modify the fields described in the previous steps. The Modify Workflow Schedule screen is identical to the Schedule Workflow screen.

            Example: Scheduling Workflow Execution

            This example demonstrates how to schedule a workflow for later execution.

            Before You Begin

            Create the example workflow as described in Example: Creating a Workflow.

              Step 1   Choose Orchestration.
              Step 2   On the Orchestration page, click Workflows.
              Step 3   Choose the VMPowerCycle workflow.
              Step 4   Click Schedule.
              Step 5   On the Schedule Workflow dialog, complete the following:
              Name Description

              Recurrence Type

              Choose Only once. You might choose other values in an actual production application.

              Start Time

              Choose today's date and set a time a few minutes later than your current time.

              Use ID

              Type the administrator ID you are signed in as.

              Step 6   Click Submit.
              What to Do Next

              Click the Workflow Schedules tab. The scheduled workflow is listed.

              Check the service request queue at the time you specified in the Start Time control. See Viewing Service Requests. A service request is generated for the workflow you specified.

              Using VM Action Policies

              You can create a user VM action policy to apply to virtual data centers (VDCs). The policy contains workflows that can be run on VMs within that VDC.


              Note

              Only one VM action policy can be assigned per VDC.

              To create a VM action policy, do the following:

                Step 1   Choose Orchestration.
                Step 2   On the Orchestration page, click User VM Action Policy.
                Step 3   Click Add.
                Step 4   On the Add Policy: Create New Policy screen, complete the following:
                Name Description

                Policy Name

                The policy name.

                Policy Description

                A description of the policy.

                Select No of Actions

                The number of actions defined by the policy. One action specifies a single workflow.

                Step 5   Click Next.
                Step 6   For each VM Action on the Add Policy: Add VM Actions screen, complete the following:
                Name Description

                Action Label

                The label for the VM action. The action is available when you select a VM that is part of a virtual data center (VDC) to which the action policy is applied.

                Workflow

                The workflow represented by this action.

                Authorized User Types

                The user types authorized to run the policy workflows.

                Step 7   Click Submit.
                What to Do Next

                After you create a User VM Action policy, as an administrator, you can choose this policy when you create a VDC. All VMs that belong to the VDC can then use the workflows specified in the action policy.