Rules and runbooks

Terminology

Runbooks

A Runbook represents a series of tasks you would like Cayosoft Administrator to perform. Runbooks define both the Action and Frequency with which the runbook should be executed. Actions are accomplished through the configuration of individual Rules and the frequency of execution is set by the Enforcement/Schedule of a Runbook.

Runbook Scope

The Runbook scope is defined in the first rule in the list - usually, this is some Organizational Unit in the managed domain. By default, all other rules in the Runbook have Get scope from runbook session value in the Limit scope to this Domain or OU setting. It means they use the Organizational Unit defined in the first rule to perform their tasks. That is why it is important to use some Stage OU when the rules in the runbook update the objects.

NOTE: Rules in the runbooks support Get scope from runbook session scope only if the first rule in the runbook is one of these:

• Text file | Create AD Users

• Import SQL Data | Create AD Users

• Import Oracle Data | Create AD Users

For details, please see the following article: How to use special system settings for Limit Scope and Query Criteria parameters in automation rules and Web actions.

Rules

Rules are the basic building blocks of all administrative activities performed by Cayosoft Administrator. When a user performs a task in the web portal and when a task needs to be automated rules are used to execute the operation. Rules are made up of four basic parts:

• The Query that retrieves details from a managed platform.

• The Action that can perform an operation based on the details returned by the Query.

• The Output that can provide details in a report or email of the results of the Query and Actions.

• The Enforcement Schedule that allows the rule to be executed at on a defined schedule.

Rule Execution

When a rule is triggered either by a user or on a schedule, the Cayosoft Administrator Service executes the rule under the security context of the service account being used for a specific platform. Users are granted the permission needed to run a rule by being assigned one or more Cayosoft Administrative Roles. The details of the rule’s execution are recorded and can be reviewed later for details on what happened during execution.

Rule Scope(s)

When a rule is executed it is important that the rule target only the objects that should be affected by the rule. Rule scopes are defined by the chosen settings in the Query Section of each rule.

Runbook Rule Sequences

To determine the order of tasks that a Runbook will perform, the tasks are added to a list called the Rule Sequence list. The Rule Sequence determines the order in which the tasks (Rules) in the Runbook will execute.

Runbook Enforcement/Scheduling of Execution

Runbooks can be scheduled to execute one time, every day at the specified time(s), on specific days or Monthly on specific days. Once Enforcement is enabled, the schedule intervals can be selected to view the options available for each.

Working with rules

Video Tutorial

Create new rule

1. In the Cayosoft Administrator Console, click + New in the left corner.

2. Select Rule.

3. Select the platform you would like to work with or click Show all templates.
   

4. Search for the rule template by its name.

5. Select rule output.

6. Specify rule name, description and labels.

7. Click Finish.

Rename rule

1. In the Cayosoft Administrator Console, navigate to the rule you want to rename.

2. In the Actions section click Rename Rule.

3. Specify rule name and description.

4. Click OK.

Move rule

1. In the Cayosoft Administrator Console, navigate to the rule you want to move.

2. In the Actions section, click Move Rule.

3. Select the folder where you would like to move the rule: existing or create a new one.

4. Click OK.

Copy rule

1. In the Cayosoft Administrator Console, navigate to the rule you want to copy.

2. In the Actions section, click Copy Rule.

3. On the dialog box click Yes.

Delete rule

1. In the Cayosoft Administrator Console, navigate to the rule you want to copy.

2. In the Actions section, click Delete Rule.

3. In the dialog box, click Yes.

Run rule

1. In the Cayosoft Administrator Console, navigate to the rule you want to run.

2. In the Actions section, click Run Rule.

3. Click OK in the information message that appears.

Refresh Rules

1. In the Cayosoft Administrator Console, navigate to the rule you want to run.

2. In the Actions section, click Refresh Rules.

Working with runbooks

Video Tutorial

Automatic user provisioning from an external data source is accomplished by first creating a Runbook, then adding (linking) rules to that runbook. Each rule will perform each task in the desired sequence as shown below.

Creating a provisioning runbook from a template

1. In the Cayosoft Administrator Console, click the Automation tile on the home page.

2. Click one of the runbook templates related to account provisioning. For example, click Provision Hybrid Users

   
   

3. Click the desired Data Source on the left.

4. Check all steps that the runbook must contain on the right.

5. Click Next.

6. Complete each parameter as requested on the wizard and click Next.

7. Specify a Name for the Runbook.

8. Specify a label (folder) for the Runbook.

9. Click Next.

10. Select Runbook Output if any then click Finish.

11. Click OK.

Creating an empty runbook

1. In the Cayosoft Administrator Console, click New Runbook on the toolbar.

2. Enter a name and description for the new runbook.

3. Select an existing label or create a new label.

4. Click OK.

Create a rule and add it to the runbook

1. In the Rule Sequence section, click the New rule... button.

2. Complete the New Rule wizard.

Modify an existing rule in a runbook

1. In the Rule Sequence section, select the rule to be modified.

2. Click the Modify Linked Rule button.

Add an existing rule to the runbook

1. In the Rule Sequence section, click the Add link buttonю

2. Select the Rule or Dynamic Group to be executed then click OK.

Change label for a rule or a runbook, version 5.3.1 and above

1. Navigate to the rule/runbook in the Cayosoft Administrator Console.

2. Click the Move Rule command in the command pane to the right of the rule configuration screen.

3. On the Move Rule dialog, select an existing label or create a new one.

4. Click OK to move the rule.

Remotely triggering a runbook with PowerShell

1. When provisioning, updating or deprovisioning from an HR Data Source, it may be helpful to allow the HR system to trigger Runbook Execution. The following script can be placed on the Cayosoft Administrator Server and remotely executed the HR/ERP or SIS system when an update has been made. This is especially important for immediate terminations.

2. The following PowerShell script will trigger Runbook Execution. In this example, the RUNBOOK_NAME below need to be be replaced with the name of the runbook to be executed.

[Reflection.Assembly]::LoadFrom("C:\Program Files\Cayo Software\AdminAssistant\Ca
$connection = new-object Cayo.PolicyManager.Common.Proxies.RulesManagerClient([ #Get All rules
$rules = $connection.ListRules() #filter rules to find desired
$ruleToRun = $rules | where {$_.Name -eq"RUNBOOK_NAME" } #Prepare execution context information
$execContext = New-Object Cayo.PolicyManager.Common.RuleExecutionContext
$execContext.Flags =[Cayo.PolicyManager.Common.ExecutionFlagsEnum]::Rule #Run rule
$connection.RunRuleNow($ruleToRun.RuleId, $execContext) #Free resources
$connection.Dispose()
$connection = $null