TABLE OF CONTENTS

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 


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 a such a way so that the required outcome is true, i.e. Disk Space >= 20GB will return a Pass if there is 20GB or more free and Fail if there is less than 20Gb free.


The Evaluator will return a Pass or Fail answers 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.


Rule TypePurpose
FieldUsed to test a Date \ Value \ Text to see if it matches either static data or calculated data.
Compare FieldsAllows for comparison of two values from a single object record
i.e. Is Migration Date > Survey Date
BlueprintChecks for membership or not of a Blueprint.
SCCM CollectionChecks for membership or not of a SCCM Collection. Three separate SCCM environments maybe queried.
AD GroupChecks for membership or not of a SCCM Collection. Any number of domains may be supported as long as there is a trust between them
PowerShellRun a PowerShell script to perform an evaluation rule. Useful if it is required to query remote systems such as vSphere or Citrix.
i.e. "Does the Citrix platform have enough free disk space?"
IgnoreSelecting this allows users to disable a Rule without fully deleting it.


3. Data Location

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



Rule TypeOptions
Field{ModuleField} {CustomFieldPath} {CustomFieldID} {MM:Field} {MM:CustomFieldPath}
Compare Fields{ModuleField} {CustomFieldPath} {CustomFieldID} (Not recommended to use an ID) 
Blueprint{BluePrintPath} {BluePrintFolder}
SCCM Collection{SCCMCollectionName} 
AD Group{ADGroupName}
PowerShellPowerShell Script Number (From Administration\PowerShell Scripts - Note the script number is at the end of the grid in the Id column)


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

4. Operator


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


Rule TypeOperator
Field==  !=  >=  <=  >  <  "Is the Day" "Not the Day"  "Like" "Not Like"
Compare Fields==  !=  >=  <=  >  <  "Is the Day" "Not the Day"  "Like" "Not Like"
Blueprint"Is In"  "Is Not In"
SCCM Collection"Is In"  "Is Not In"
AD Group"Is In"  "Is Not In"
PowerShell"PS Param"



OperatorSummary
==Explicit equals. Works for either numbers or Dates or text. If comparing text consider using "Like" or "Not Like"
!=Not Equals. Works for either numbers or Dates or text. If comparing text consider using "Like" or "Not Like"
>=Greater than or equal too. Used for Numbers or Dates
<=Less than or equal too. Used for Numbers or Dates
"Is the Day"Checks if a field matches a calculated date
"Not the Day"Checks if a field Does Not match a calculated date
"Like"Used for text comparisons to test similar text.  So Wednesday would match Day
"Not Like"Used for text comparisons to test dissimilar text.  So Wednesday would be dissimilar to Thursday
"Is In"Checks if objects exists in SCCM Collection or AD Group or Blueprint Path or Blueprint Folder.
"Is Not In"Checks if objects do not exist in SCCM Collection or AD Group or Blueprint Path or Blueprint Folder.
PS ParamRequired if using a PowerShell Script. Additionally it is possible a submit a parameter to a PowerShell script.




5. Criteria


This is where the condition of the test is defined. Most criteria examples expect actual text vales 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


Rule TypeValid Criteria
Field{text} {numeric} {Date} {Calculated Date} {Static Data} 
Compare Fields{Field Name} {CustomFieldPath} {CustomFieldId} (Not recommended to use an ID)
BlueprintNot required
SCCM Collection{SCCM Collection Name}
AD Group{AD Group Name}
PowerShell{PowerShell Param} [Blank] or is not required



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?"


Date CalculationExplanation
[Today + Y]Returns a Date  that is Y days ahead.   i.e.  [Today +14]
[Today + Y @13:00]Returns a Date  that is Y days ahead. i.e. [Today +14 1pm]
[Today - Y]Returns a Date  that is Y days ago. i.e. [Today - 7]
[Today - Y @11:00]Returns a Date  that is Y days ago. i.e. [Today - 7 11am]
[T-Y]Returns a Date  that is Y days ahead. i.e. [T-14]
[T+Y]Returns a Date  that is Y days ago. i.e. [T+7]
[Today]Returns a Date that is Today
[TimeStamp]Returns the current date and time. 
[Today + 10] - [Today + 5]Returns a Calculated date range. Should be used with "Is The Day" or "Not The Day"
[T-10] - [T-5]Returns a Calculated date range. Should be used with "Is The Day" or "Not The Day"


Date OperatorsExplanation
<Returns a Pass if the referenced date is earlier than the calculated date
>Returns a Pass if the referenced date is later less than the calculated date
<=Returns a Pass if the referenced date is earlier than \ equal to the calculated date
>=Returns a Pass if the referenced date is later than \ equal to the calculated date
Is the dayReturns a Pass if the calculated date matches the field date or is the date range  (Ignores Time) 
Not the dayReturns a Pass if the calculated date does not match the field date or is in the date range (Ignores Time) 
==Explicit check of a date time field will include the time so not always useful



Static Data Criteria


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

There are a total on 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 pass 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 use the Application field "Title" which combines AppId Vendor App Version in to 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


ModulePrefixModulePrefix
ApplicationsAP:Deployment UnitsDU:
User MigrationsUM:Mailboxes MB:
DevicesDV:Bespoke ModuleBK:


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?


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?



Dates Calculation Examples.


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

All the rules below would pass. 


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

The rules above produce the 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 the 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 maybe 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 but really, but 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" 



Object NameSource
$ScriptArgs.ItemsThe items Id's being examined by ESM
$ScriptArgs.UserInputThe value Criteria from the ESM rule line
$ScriptArgs.ScriptArg1Arg1 From the PowerShell List Grid (Hidden Column)
$ScriptArgs.ScriptArg2Arg2 From the PowerShell List Grid (Hidden Column)
$ScriptArgs.ScriptArg3Arg2 From the PowerShell List Grid (Hidden Column)



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


Sample script format.


$results = @()

foreach($id in $ScriptArgs.Items)

{


################

#Check Something  #

################


    If (Check Something Was Successful){

              $results += New-Object PSObject -Property @{

   InstanceId = $id;

   ResultHeader = "The Check passed with this outcome)";   

   ResultStatus = "Success";

               }

   }

    If (Check Something Was Unsuccessful){

              $results += New-Object PSObject -Property @{

   InstanceId = $id;

   ResultHeader = "The Check failed with this outcome";   

   ResultStatus = "Error";

               }

    }

}

   $results  



The "Check Something" is where 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 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 requirements.


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



Scheduling Delay

Determines what 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  Schedule Task ManagerThese 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 Afternoon Emails. Note the Reset Plan check box is set - this means that yesterdays Evaluate, Schedule & Publish logs will be removed the objects and the Plan will start over. This type of approach is very useful for Email Automation.


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 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 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.


Each Action requires and Event Name. This should be a short text description of the action as it it 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 fieldd of a similar type i.e. Text to Text, Date to Date, Check  Box to Check Box etc...

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 Blueprint or Remove from Blueprint

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



Add to AD Group or Remove from AD Group

Two functions to facilitate adding or removing and object from an AD Group.






Add to SCCM Collection or Remove from SCCM Collection 

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

Note the parameters on the lower two actions that instruct ManagementStuio to connect to Sites 2 and 3 and defined in the ESM Settings in Administration\Project Settings.



Move to Process

Allows ESM to move an object through 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

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. Link to the Email Definition Help Doc

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 maybe 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 maybe 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 it's 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. 

  

      

ActionExamplesExplanation
Send it nowSchedule: [TimeStamp]:Schedules with the current date and time as the schedule date.
Schedule it 10 days before MigrationSchedule: [DeploymentUnitStartDate - 10];


Schedules the latest permitted email send date 10 days before the start of the deployment unit. The second example adds a time to the schedule
Schedule 10 days before Migration at 2:30pmSchedule: [DeploymentUnitStartDate - 10 @ 14.30];Schedules the latest permitted email send date 10 days before the start of the deployment unit at 2:30pm.

                       


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 Users DU is due to start
      • Schedule: [DeployUnitSlotStart];
    • Schedule email to be sent on the before day the Users DU is due to start, at 2:30pm
      • 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 recommend 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 send at 12pm. Those emails will be spread out from 12pm to 2pm. This helps with 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 send 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 send the T-5 Email within the last 10 days they will not receive it again. 


LateEmailLimit

  • Default: 5
  • Usage: LateEmailLimit:15;
  • 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 send immediately after been 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 the T-15 & T-10 emails would be more than 5 days late and not added to the email queue. 



Example Adv. Options