Introduction

The ESM & Automation module allows users to create both Windows Servicing and Automatic processes within ManagementStudio.

Each of the automation tasks requires three components to run successfully. Those components are Evaluate Rules, Schedule & Publish Actions. Additionally, it is possible to limit the number of devices 

TABLE OF CONTENTS

• Introduction
• Evaluate Rules
  • 1. Rule Name
  • 2. Rule Types
  • 3. Data Location
  • 4. Operator
  • 5. Criteria
    • Standard Criteria
    • Blank Text / Dates
    • Calculated Dates Criteria
    • Special Case: Checkbox (boolean)
    • Static Data Criteria
  • Cross Module Rules
  • Readiness Rules
  • Custom Rules Logic - AND/OR operator
  • Detail Field Change History Inspection
• Evaluation Examples
  • Is the User a VIP?
  • Are they Ready to Migrate in workflow?
  • Does FieldId 1684 end with the text "corp.com"?
  • Does hostname contain the word 'Lenovo'?
  • Is the User 10 days away from upgrade?
  • Combined Rules
  • Surveys
  • Valid Survey Fields
  • Dates Calculation Examples.
  • AD Evaluation
    • AD Evaluation - Multi-Domain
  • SCCM Evaluation
    • SCCM Evaluation - Multi-Site
  • PowerShell
• Scheduling
  • Overview
  • Scheduling Delay
  • Scheduling Window
  • Timed Events
  • Reset Prior to Run
  • Plan Priority
  • Allowed to Schedule on Days
  • Do not Schedule on Dates
  • Allowed to send Email on Days
  • Do not Email on Dates
• Service Plan Actions (Publisher)
  • Event Types
  • Set Field to Value
  • Copy Field to Field
  • Assign to User
  • Add to DeployUnit or Remove from DeployUnit 
  • Add to Blueprint or Remove from Blueprint
  • Add to AD Group or Remove from AD Group
  • Add to Az Group or Remove from Azure AAD Group
  • Add to SCCM Collection or Remove from SCCM Collection
  • Move to Process
  • Add Note
  • Run Custom Action
  • Send Email
  • Cancel Email
  • Archive
  • Delete  
  • Auto-Schedule In DU
• Sending Email
  • Schedule
    • Adv. Schedule
    • Detail Fields
    • Custom Fields
      • Schedule email to be sent on a date held in a Custom Field on the User Record
      • Schedule: [XX]; where XX is the CustomFieldId
      • Schedule: [1000] 
    • Date Keywords
  • Schedule email to be sent on a day relative to today 
    • Explicit Dates
      • Explicit Dates: [2020-03-18]
  • Additional Options
    • SpreadHours
    • DuplicateCheck
    • LateEmailLimit
    • Example Adv. Options
• Further Support

Evaluate Rules

This section configures what should be considered before performing an action. Rules are for example "Is a user 7 days away from migration?", "Does a machine have enough free disk space?" or "Has this site had a network upgrade completed?". These questions should be constructed in such a way so that the required outcome is true, i.e. Disk Space >= 20GB will return a Pass if there is 20GB or freer and Fail if there is less than 20Gb free.

The Evaluator will return a Pass or Fail answer for each of the rules and to achieve a Global Pass all rules must pass. Only then will the module move on to Schedule and Publish Actions. 

1. Rule Name

Every rule requires a unique rule name. The name should be descriptive but as short as possible so that reporting displays suitable column sizes

2. Rule Types

The evaluator can consider Rule Types.

3. Data Location

The Data Location value depends on what type of Rule Type is defined.

** Multiple Modules = Replace MM - These options are special and are explained elsewhere in this support document

4. Operator

The Operator is once again dependent on the Rule Type selected. "" are used to show phrases but should not be in the operator field.

5. Criteria

This is where the condition of the test is defined. Most criteria examples expect actual text values to compare against but there are two exceptions "Static Data" & "Calculated Date" both will be expanded on further down this article. So in English, the query would read "Is the User a VIP user?" or "Does the Machine have over 20GB free space". Criteria refers to the last component of the query, in this case, VIP or 20.

Standard Criteria

Blank Text / Dates

It is possible to check for blank Text and Dates with the '[blank]' keyword. 

Calculated Dates Criteria

Date Calculation is possible in the Criteria column. It provides the ability to "Test" if a condition is true or false based on a calculated date. i.e.

"Is today 10 days before a User Migration?"    "Was the machine built over 7 days ago?" 

"Has the user not responded to the survey after 5 days?"   "Is today the Users Migration Day?"

[Today] Keyword Important Note

When used in comparisons (<, >, =, etc) the [Today] keyword resolves to a time of 00:00:00. i.e. the first second of [Today]. This is especially important when checking if a date is less or equal to 'today' as any date that has a time component and is also ‘today’ will return false.

The recommended approach to do an "X <= [Today]" rule is to use "X <= [Today @23:59]"  will correctly return true for any date comparison that falls on ‘today’ regardless of the time component.

Special Case: Checkbox (boolean)

By default, you can check if a checkbox is checked or unchecked using the comparison operators "== FALSE" or "!= TRUE," etc. However, when using Management Studio for comparison, it treats blank values in the database as 'FALSE' when determining the checked state of a checkbox. To verify if the value in the database is actually set to 'FALSE' and not just blank, you can use the criteria "== *FALSE" (with an asterisk preceding False).

Static Data Criteria

ManagementStudio supports project-specific static data. It is held in Administration\Project Settings\ESM Settings.

There are a total of 10 values that can be stored and then referenced in the criteria as a variable in the format of 

[Data1] through to [Data10]

Cross Module Rules

Provides the ability to inspect the links to other modules and return a Pass status if the condition is met. A Pass will be returned if any of the designated data in the other module passes the test. This function provides a way to "check" if a link exists. i.e. 

            Does a user have SAP GUI for Windows version 7.30?

To do this specific test we would want to use the Application field "Title" which combines AppId Vendor App Version into one string.

            App #34083: SAP SAP GUI for Windows 730.0

Note the Data location of AP:Title i.e.  {Module}:{Field}

Any User to Application module link that contains "App #34083: SAP SAP GUI for Windows 730.0" in the "Title" field will cause the rule to Pass

To be less specific and test if the User has any Sap Gui products instead of using the very specific "Title" field it would be more appropriate to use the "AppName" field.

Note the Data location of AP:AppName i.e.  {Module}:{Field}

Any user to application module link that contains the words "SAP GUI" in any "AppName" field will cause this rule to Pass

Readiness Rules

It is possible to access the Readiness of a User, App, Device etc in an ESM rule. Readiness is calculated against another module e.g. User vs Apps Readiness. To access Readiness prefix the Readiness column name with the initials AR (App Readiness), UR (Readiness) etc. See the table below for the full list. 

Readiness Column Names:

1. IsReady
2. Total
3. ReadyCount
4. RemainingCount
5. ReadyPercent
6. OutOfScopeCount

Example: Get a list of Users who have more than 0 Apps and All of those Apps are Ready. 

Custom Rules Logic - AND/OR operator

The and/or operator is used to refer to both things or either one of the two rules specified. This is used to test for multiple conditions.

For example, the following rule uses the and operator and the or operator to connect three different rules. The condition should only pass users that are in two blueprints OR in a third blueprint.

Users must be in the Compliance Services BP and Purchasing BP to pass OR Users in the Audit & Financial Investigations BP

Build the rules (1) and then in the custom rules logic field, enter the following:

• ([In Compliance Services] -and [In Purchasing]) -or [Or in Audit & Financial Investigations] (2)

Use the Rule name in []
Use the -and -or operators to build the logic
All Rules must be used when using the custom logic

Example, this will Pass if the User is in any of the 3 specified AD group. 

[Rule name 1] -or [Rule Name 2] -or [Rule Name 3]

Detail Field Change History Inspection

It is possible to query the last change for a detail field, it should be noted this does not work for custom fields.

ESM can look at the

• The previous Value                    DetailField_Modified_Value
• Who changed the Value            DetailField_Modified_By
• When the Value changed.         DetailField_Modified_Date

An example is checking to see if a record has been archived for over 30 days before going on to delete it with a Plan Action.

A further example looks at Archive Date, Archived By and the Previous value of Archived = False.

This is a very powerful feature as it allows plans to understand when something changed and test for elapsed time.

Evaluation Examples

Is the User a VIP?

Are they Ready to Migrate in workflow?

Does FieldId 1684 end with the text "corp.com"?

Does hostname contain the word 'Lenovo'?

Is the User 10 days away from upgrade?

Combined Rules

Is the User a VIP, in "Ready to Migrate" workflow and 10 days away from their migration day?

Surveys

Note: In the Data Location XX is either the Survey ID or Survey Name can also be used.

Valid Survey Fields

Use these fields within the data Location column.

Dates Calculation Examples.

Assume today is January 15th and DeployUnitSlotStart = 25th January

All the rules below would pass. 

The rule validator will check the rules of a plan by examining them and deciding if the rule type is valid for the field type.

The rules above produce the following validation results.

===== Passed Checks ====== 

DeployUniitStart = 2021-01-25 :: Found Detail Field 'DeployUnitSlotStart' in 'UserMigrations' Module [datetime]. Parsed Date: '2021-01-25 00:00'

T Minus 10 :: Found Detail Field 'DeployUnitSlotStart' in 'UserMigrations' Module [datetime]. Parsed Date: '2021-01-25 00:00'

Today plus 10 days :: Found Detail Field 'DeployUnitSlotStart' in 'UserMigrations' Module [datetime]. Parsed Date: '2021-01-25 00:00'

More than three days away :: Found Detail Field 'DeployUnitSlotStart' in 'UserMigrations' Module [datetime]. Parsed Date: '2021-01-18 00:00'

Not in the past :: Found Detail Field 'DeployUnitSlotStart' in 'UserMigrations' Module [datetime]. Parsed Date: '2021-01-15 00:00'

Fewer than or equal to 13 days away :: Found Detail Field 'DeployUnitSlotStart' in 'UserMigrations' Module [datetime]. Parsed Date: '2021-01-28 00:00'

AD Evaluation

Rules to check is an object is in an AD Group or Is Not in an AD group are possible. This will work

AD Evaluation - Multi-Domain

Add the domain to the Data Location, the system will attempt to validate that domain and then connect to it. 

A Domain Trust is required.

SCCM Evaluation

The system checks the rules and will test collection membership, either "Is In" or "Is Not In"

The rules below test if:-

A machine is SCCM

The device has the Engineers Build on it

It does not have Windows 10 20H2 installed yet.

SCCM Evaluation - Multi-Site

Some environments have more than one SCCM platform. It is possible to query up to three SCCM systems per Project. As mentioned above they are configured in Administration\Project Settings\ESM Settings

The example below shows all three SCCM systems configured. The first one is TRUSTED by making use of the AppPool Service account that runs ManagementStudio. The second and third rely on a username and password to make a connection.

Be sure to specify the Site Code and the Site Server FQDN.

The Evaluator will assume that Site 1 is required if it is not specified in the rule "Data Location". 

To query other SCCM systems add Site2 or Site3 to the "Data Location" column.

In the example below the rules will query Site2 i.e.   Site Code = ABC & Site Server DC2_SCCM.USA.

PowerShell

The Evaluator can run PowerShell scripts to query remote systems or perform more complex tasks within the ManagementStudio API.

Example - PS Param is always required for PowerShell scripts but Criteria may be set to [Blank] or  & Criteria are not required unless a variable must be passed to the script.

Scripts are stored in "Administration\PowerShell Scripts" and must:-

• return a status back at the end of the script
• be assigned to a Module in "Administration\PowerShell Scripts      Module"
• have a Role Group in "Administration\PowerShell Scripts      Grant Access 1"

There are many variables passed to the script, variables that can be optionally passed to the script are set out below. For a full list of variables download the script log file on the script list grid in "Administration\PowerShell Scripts" 

The most useful is the second variable as is plan-specific and can be configured each time the rule is called.

Sample script format.

## For each Id, run a check and add a special return obj to a results list
$results = @()
foreach($id in $ScriptArgs.Items)
{
    ## Successful
    if (1 -eq 1)
    {
        $results += New-Object PSObject -Property @{
            InstanceId = $id;
            ResultHeader = "The Check passed with this outcome)";   
            ResultStatus = "Success";
        }
    }
    ## Failed
    else
    {
        $results += New-Object PSObject -Property @{
            InstanceId = $id;
            ResultHeader = "The Check failed with this outcome";   
            ResultStatus = "Error";
        }
    }
}
$results

The "Check Something" is where the custom script can be placed. Familiarity with the ManagementStudio API is required. Further details of the PowerShell Script repository can be found in this support article.

The script must return a result per object, with a value of Success or Error. This value will be reflected in the results per object.

Scheduling

Overview

The scheduler will process all the objects that pass all of the Evaluate Rules. It is also possible to subscribe Evaluate, Schedule, and Publish events to the ManagementStudio Schedule Task Manager

The scheduler allows a user to configure objects to be scheduled over a number of months, weeks, days, or a single day. The use will vary depending on the requirements.

The plan above schedules objects from tomorrow for a period of 70 Days or 10 Weeks.

Scheduling Delay

Determines the first future date the Scheduler can select. A schedule delay of 1 will start from tomorrow

Scheduling Window

• Service plans upgrading versions of Windows 10 may run over many months.
• Service Plans to email users that are due for migration tomorrow should run on a single day.

Timed Events

Each event in a plan may be subscribed to a times event from the  Scheduled Task Manager. These events allow some or all of the plan processes to be called on a schedule. The example below shows a daily email plan subscribed to a timed event called Lunchtime. 

Note the Reset Plan check box is set - this means that yesterday's Evaluate, Schedule & Publish logs will be removed from the objects and the Plan will start over. 

Reset Prior to Run

This option is useful when a plan should run the actions every time it runs. It should be used with caution in certain use-cases.

When Reset Prior to Run in on, the Evaluate result, Schedule result and Publish logs are cleared for in-scope items (those which meet the Data Source settings in the ESM Plan) so that the plan effectively runs newly on those in-scope items. 

For most plans Reset Prior to Run should be off. However, for plans where the actions need to run multiple times for each item, it should be on. An example where it should be on is an application ESM plan which checks to see if all of the tests for an application passed. In this use-case the application needs testing once per month, and if a failed test occurs in any month, the ESM plan should perform an action such as email the app owner. Reset Prior to Run should be on to ensure that the plan actions run every time.

For email automation, generally Reset Prior to Run should be off to prevent users getting the same email each time the plan runs.

Plan Priority

The default priority for a scheduled plan is 50. The lower this number, the higher the plan priority. Plans with a higher priority will run before plan with a lower priority if they are scheduled to run at the same time.

Allowed to Schedule on Days

Select the days that the Scheduler is allowed select to run a Publish and an action.

Do not Schedule on Dates

Add correctly formatted dates here to exclude them from the possible schedule dates.

Date format is YYYY-MM-DD   i.e. 2021-03-23

Ranges are also supported for a Christmas change freeze can be represented like this.

2021-12-18 => 2022-01-02 will exclude 18th Dec through to 2nd Jan inclusive.

Allowed to send Email on Days

Select the days that the Scheduler is allowed select to run a Publish and an action that involves sending an Email.

This could prevent a T-1 Email from being sent on a Sunday and instead would be selected to run on a Friday.

Do not Email on Dates

Add correctly formatted dates here to exclude them from the possible email dates.

Date format is YYYY-MM-DD   i.e. 2021-03-23

Ranges are also supported for a Christmas change freeze can be represented like this.

2021-12-18 => 2022-01-02 will exclude 18th Dec through to 2nd Jan inclusive.

Service Plan Actions (Publisher)

The Plan Actions define what the publisher does and in what order. Consider the order that plan actions should run, for example, if a calculated date is required for an email the action that generates that date and saves it to a field must run before the email that needs that date.  Moving actions up and down the actions grid will determine the order they are executed.

Event Types

• On Publish - Use this Event Type to execute an action when the plan runs
• On Success - Use this Event Type to run an action if the "On Publish" action was successful
• On Fail - Use this Event Type to run an action if the "On Publish" action fails

Each Action requires an Event Name. This should be a short text description of the action as it is written to the logs and needs to be easily readable and quite descript i.e.

• Send T-10 Email
• Add to Application AD Group
• Move To completed
• Rebuild Citrix Device

There are many actions to choose from. 

Set Field to Value

The examples below show setting a field value for Text, DateTime, Radio Button, Checkboxes.

Copy Field to Field

Allows any field to be copied to a field of a similar type i.e. Text to Text, Date to Date, Check  Box to Check Box, etc...

The field in the Target field is the location you want to copy from.

The field in the Param field is the location you want to copy to.

Often used to elevate user entered data from a survey to a Custom Field in order to allow it appear in the Grid

Assign to User

Assign an object to a ManagementStudio User. i.e. Assign failed Survey objects to a user for investigation and remediation.

The target is the ManagementStudio users login account name and the Param' is the type, either:-

AssignedTo       DelegateTo1     DelegateTo2       see the example below.

Add to DeployUnit or Remove from DeployUnit 

Two functions allow the adding or removing of a DeployUnit to an Object.

Add/Remove DeployUnits supports Keywords in the name .e.g. "Windows11_[UM-CustomProperty1]" or "Windows11_[UM-BP-79-Index:1-NoLoc]" . 

If an object is already in a DeployUnit it will not be moved unless 'ForceMove' is present in the Param box. 

If a DeployUnit does not exist it will not be created unless 'CreateIfNotFound' is present in the Param box.

Add to Blueprint or Remove from Blueprint

Two functions allow the adding or removing of a Blueprint to an Object.

Add/Remove Blueprints supports Keywords in the Target to create and add to Blueprints dynamically.

Examples of Target in a User Migration ESM plan:

• Migration Types\[UM-MigrationType]
• AD Location\[UM-CF-9999]

Example of Target in an Application ESM plan:

• Application Category\[App-AceCategory]

If the Keyword resolves to a list, then a Blueprint will be created for each item in the list. 
e.g. If the Keyword was a list of AD Groups in a textblock with each group on a new line.

Note: If the Blueprint Path does not exist, it will be created by ESM.

Add to AD Group or Remove from AD Group

Two functions allow the adding or removing of Users/Devices to AD Groups.

• Add Devices/Users to App Groups based on the Apps that are linked to those Devices/Users
  • The AD Group is read from the AD Connector tab on the Application and uses these keywords to determine which collection to use.
  • Note, the Applications must be in a Ready process to be in scope for this plan
    • [Application-Links-Available]
    • [Application-Links-Required]
    • [Application-Links-Uninstall]
• Add Devices/Users to a AD Group by the Group Name
• Remove Devices/Users from a AD Group by the Group Name

Add to Az Group or Remove from Azure AAD Group

Two functions allow the adding or removing of Users/Devices to Azure AD Groups.

1. Add Devices/Users to Azure (AAD) Groups based on the Apps that are linked to those Devices/Users
   • The ADD Group is read from the Azure Conn tab on the Application and uses these words to determine which collection to use.
   • Note, the Applications must be in a Ready process to be in scope for this plan
     • [Application-Links-Available]
     • [Application-Links-Required]
     • [Application-Links-Uninstall]
2. Add Devices/Users to a ADD Group by the Group Name
3. Remove Devices/Users from a ADD Group  by the Group Name
4. Add Devices/Users to a ADD Group  by the Group Name.
   • This uses a second Azure Enviorment specifced by the name of the connector in the Param field
5. Remove Devices/Users from a ADD Group by the Group Name
   • This uses a second Azure Enviorment specifced by the name of the connector in the Param field

Add to SCCM Collection or Remove from SCCM Collection

Two functions to facilitate adding or removing an object from an  SCCM Collection.

1. Add Devices/Users to App Collections based on the Apps that are linked to those Devices/Users
   • The SCCM Collection is read from the SCCM Conn tab on the Application and uses these words to determine which collection to use.
   • Note, the Applications must be in a Ready process to be in scope for this plan
     • [Application-Links-Available]
     • [Application-Links-Required]
     • [Application-Links-Uninstall]
2. Add Devices/Users to a SCCM Collection by the Collections Name
3. Remove Devices/Users from a SCCM Collection by the Collections Name
4. Add Devices/Users to a SCCM Collection by the Collections Name.
   • This uses a second SCCM server specifced by the name of the connector in the Param field
5. Remove Devices/Users from a SCCM Collection by the Collections Name
   • This uses a second SCCM server specifced by the name of the connector in the Param field

Move to Process

Allows ESM to move an object through the workflow.

Idea - Combine this command with sending email or adding to an AD group and then move to workflow showing that action has been completed.

Add Note

Add a note to an object.

Run Custom Action

Send Email

The email template being sent must exist for the module you are creating the ESM plan in. For example, if you are creating a Device plan, email template must have been created in the Devices section in the Admin area.

To add an email to the outgoing queue for immediate send only requires the email name. If the email is designated as a "DU Email" then the object of the email i.e. a user, device, app etc... must be in a deployment unit otherwise the email will fail to send. Please click for more information on email templates.

It is sometimes desirable to be able to future schedule emails to allow the system to avoid weekends, holidays or a change freeze. Detail of how to do this are documented in the Advanced Email Sending section below.

Cancel Email

To cancel a previously scheduled email that has not yet been sent.

Archive

Objects maybe Archived with function.  Objects maybe un-archived by setting the Param to UnArchive

If a plan needs to consider archived items then Include Archived should be selected in the 
Data Source at the top of the screen.

Delete  

Objects may be Deleted with this function. Deleted objects are not actually deleted, they are added to the deletion queue and will be deleted in the future in line with the retention policy in Administration\Project Settings\House Keeping   

Objects that are in the delete queue may be un-deleted by setting the Param to UnDelete

If a plan needs to consider deleted items then Include Deleted should be selected in the
Data Source at the top of the screen.

Auto-Schedule In DU

This function will auto-schedule an Object in its Deployment Unit. It is possible to specify a delay that will force the function to search for available slots X days in the future based on the current date. 

Combine this feature with an email plan to Schedule a user and then send an email confirming the appointment, perhaps with an opportunity for the user to change the scheduled date from the system selected date.

Sending Email

When ESM is set to send an email it doesn't sent it right away, it schedules the email for some time in the future. Depending on what options are set that time might be right now. 

Schedule

The schedule Param is required to send email e.g. "Schedule: [DeployUnitSlotStart- 10];" will tell MS to send this email 10 days before the Users migration date. This is very useful for sending T-Minus emails. 

Adv. Schedule

The Schedule Param supports Date, Day Modifier & Time as well as using fields on the User record (App, Device, etc are also supported). Detail fields need the internal name, custom fields require the Id number

• Detail Fields

  • Schedule email to be sent on the day the User's DU is due to start
    • Schedule: [DeployUnitSlotStart];
  • Schedule email to be sent on the before the day the User's DU is due to start, at 2:30 pm
    • Schedule:  [DeployUnitStartDate -1 @ 14:30]

• Custom Fields

  • Schedule email to be sent on a date held in a Custom Field on the User Record

  • Schedule: [XX]; where XX is the CustomFieldId

    • Schedule: [1000] 

• Date Keywords

  • Schedule email to be sent on a day relative to today 

    • Schedule: [Today + 5];
    • Schedule: [Today + 5 @ 18:00];
    • Schedule: [TimeStamp];  (sends it right now)

• Explicit Dates

  • Explicit Dates: [2020-03-18]

Additional Options

More options can be added to the Param field to control when and if the email can be sent. These options have an internal default already set and it is recommended that this default be used in the majority of cases.  

SpreadHours

• Default: 2
• Usage: SpreadHours:2;
• How many hours to spread the sending of a group of emails over.
• e.g. 1000 emails are set to be sent at 12 pm. Those emails will be spread out from 12 pm to 2 pm. This helps with the overall performance by preventing 1000's users from accessing the self-schedule or survey pages at the same time.   

DuplicateCheck

• Default: 10
• Usage: DuplicateCheck:15;
• Number of days in the past to check if this email has already been sent to avoid duplicate emails being sent. 
• e.g. A User has been sent their T-5 Email, but at the last minute, they are changed to a new DU which should trigger them to receive another T-5 Email. However, if they have been sent the T-5 Email within the last 10 days they will not receive it again. 

LateEmailLimit

• Default: 5
• Usage: LateEmailLimit:15;
• A number of days an email can be 'late' (scheduled for a date in the past) and still be added to the queue. 
• A late email will be sent immediately after being added to the queue
• e.g. A User is added to a DU 4 days before they are due to be migrated. Emails for T-15, T-10, T-5 are present however, only the T-5 email will be sent. The T-5 email will be 1 day late which is allowed, however, the T-15 & T-10 emails would be more than 5 days late and not added to the email queue. 

Example Adv. Options

i.e.  DuplicateCheck: 0; Schedule: [Timestamp];SpreadHours:0;

Further Support

If you require further support, please visit ManagementStudio's Service Desk to search the knowledge base or create a new support ticket.