Fragment and trigger template parameters

This article explains how fragment and trigger template parameters work, and how you specify or update them using the 1E PowerShell Toolkit.

Rules, trigger templates, and fragments

A rule is associated with the following:

• At least one trigger template. Each template may have zero or more parameters. For example, the template to run a check periodically every N hours has a parameter for N, the number of hours.

  Similarly, the template to trigger on a service state change takes a parameter for the service name to be checked.

  In some cases, the same trigger template is included multiple times. You might do this, for instance, for a service state trigger. You might specify several instances of the same trigger template but specify a different service name for each instance. Then if the state of any of these services changes, the check fragment will be triggered.

• An optional precondition fragment. The precondition fragment can have zero or more parameters. For example, the precondition fragment that checks if a file exists in a folder takes two parameters: one for the file and one for the folder.

• A check fragment. This check fragment can have zero or more parameters. For example, the check fragment that checks that a WMI namespace exists takes the namespace as a parameter.

• An optional fix fragment. The fix fragment can have zero or more parameters. For example, the fix fragment that restarts a service with a given description takes a parameter for the service description.

Parameter defaults

Parameters can have default values specified. In this case, when the trigger template or fragment is associated with a rule, the default value is automatically populated. However, it can be overridden with a new value if desired.

PowerShell constraints on parameter names for cmdlets

PowerShell imposes some special requirements if we want to manage these parameters from a cmdlet. Parameter names need to be unique in a cmdlet. However, a rule can be associated with multiple trigger templates, along with the check fragment and optionally the fix and precondition fragment. Any of these might have the same names for a parameter. To distinguish between them, parameters are, therefore, constructed with a name derived from both the entity name (trigger template or fragment) and the parameter.

Each parameter takes the form <identifier>?<parameter name>.

(A query is valid as part of a PowerShell parameter name.)

The identifier portion is distinct to each fragment or template and the parameter name is as specified for the fragment or template. For example, the parameter for a trigger template for service status change is the following: ServiceStatusChange?ServiceName.

That is, the trigger template is called ServiceStatusChange and the parameter is called ServiceName.

Similarly, the parameter for a trigger template for running the check periodically every N hours is the following: IntervalHours?IntervalHours.

In this case, the trigger template is called IntervalHours and so is its parameter.

You can find out all the trigger template names and their parameter names by using the get-1ealltriggertemplate cmdlet.

Fragments whose names begin with a digit

PowerShell does not allow hyphens in a parameter name, nor does it allow parameters to begin with a digit.

For a check fragment called 1E-Guaranteed-State-Check-Service-State, a parameter called State is mapped to the following: _1E_GuaranteedState_Check_Service_State?State.

The underscore is used in two ways here. Firstly, it replaces the hyphens in the fragment name.

This is because hyphens (-) are not valid in PowerShell parameter names, so they are mapped to underscores. Additionally, parameter names cannot begin with a digit so an additional underscore is added.

To determine the correctly formatted names for parameters associated with a trigger template or fragment, you can use the get-1Etriggertemplateparameter and get-1Efragmentparameter cmdlets discussed below.

Multiple trigger templates

You can specify the same trigger template more than once. You might do this, for instance, if you want to watch for changes to two different files or registry keys. When you specify a trigger template more than once, you distinguish the parameters as described below.

In this example, the trigger template is called ServiceStatusChange and the parameter is ServiceName. The first instance of the parameter will be called ServiceStatusChange?ServiceName. The second instance will be called ServiceStatusChange_1?ServiceName, and so on, for each repeated instance of a particular trigger template.

add-1Erule -Name NewRule9999 -Description "New Rule 9999" -CheckFragmentId 1 -TriggerTemplateIds 11 -ServiceStatusChange?ServiceName myservice -_1E_GuaranteedState_Check_MEMCM_AssignedSite?SiteCode 123

This passes a parameter ServiceName with the value MyService to the trigger template specified (whose name is ServiceStatusChange), and a second parameter SiteCode with the value 123 to the check fragment specified (whose name is 1E-Guaranteed-State-Check-Service-State).

Note that this parameter has a leading underscore to ensure the digit is accepted by PowerShell.

An end-to-end example

In this example, we have a test rule with a check and fix fragment. We set up the test rule so that the check fragment is triggered every 21 hours. We add two more triggers to the rule. Both are process start triggers and they take a process name as a parameter. For test purposes, we use notepad.exe and pbrush.exe as the executables.

The check fragment takes a single parameter and the fix fragment takes a single parameter. This means that in total the rule will have five parameters. Three parameters are associated with the three triggers, and two parameters are associated with the check and fix fragment.

This is what the check fragment looks like in the TIMS authoring tool:

This is what the fix fragment looks like:

We are now going to bolt these all together using a rule. We create the rule in Endpoint Automation (Guaranteed State) in the 1E platform. When we save the rule, it looks like this:

We had provided a default value for the parameters in the check and fix fragments using the TIMS parameter management screen. So when we added these fragments, these defaults were automatically copied into the 1E Platform UI as shown below:

If we were to create an Endpoint Automation policy and associate that rule with it, the check fragment would be invoked every 21 hours, passing down the single parameter CheckFragParam, and its value would be DefaultCheckValue. If either of the two processes we specified in the process start triggers were run, this would also trigger the rule.

Because the check fragment always returns 1 for its passed value, the fix fragment will then always be automatically invoked. It will, in turn, have the value DefaultFixValue passed down to its FixFragParam parameter.

We are going to use the update-1erule cmdlet to change some of these parameter settings. This cmdlet allows us to change various properties of the rule, including its name, description, whether or not it is enabled or disabled, and it lets us replace or amend the trigger templates and fragments associated with the rule.

However, in this case, we don’t want to change any of those things. We want to change some of the parameters associated with the trigger templates and/or the fragments, but leave everything else unchanged.

First, we need to locate the rule by its Id because this is the key parameter we pass to the cmdlet. To do this, we can use the get-1erule cmdlet, passing the name of the rule we are searching for. In our example, the rule name is A test rule. We will see the rule id from this. In the test lab, it is 1432.

 get-1erule -name "a test rule"

Modifying the trigger template time period

To change the trigger template time period from the value we initially defined (which was 12 hours), we need to know two things:

• The name of the trigger template

• The name of the trigger template parameter for the time period

We know from the discussion earlier that the trigger template name is IntervalHours, and the name of the parameter is IntervalHours. However if we needed to find out these details, we could use the get-1ealltriggertemplate cmdlet, as discussed earlier.

In version 1.2.30 of the 1E PowerShell Toolkit, a new cmdlet called get-1eruleparameter was added.

get-1eruleparameter -id 1432

In this case, if we invoke the above, we get back a definition of the parameters, their types, current and default values. We also get back the source type of the parameter (that is, is it a trigger, check, fix, or precondition parameter) and the Id of the corresponding source.

This means we can then retrieve the full entity associated with the parameter by using the appropriate Id. For example, to get back the full check fragment for this set of parameters, use the following:

get-1efragment -id 1807

To get back the trigger template for the process launch triggers, use the following:

get-1etriggertemplate -id 10

Now suppose we want to modify the trigger period to 42 hours. We can use the update-1erule cmdlet; however, we need to pass in more information then just the new trigger period because the API model requires this.

update-1erule -id 1432 -triggertemplateids 6,10,10 -IntervalHours?IntervalHours 42 -ProcessLaunch?Executable notepad.exe -ProcessLaunch_1?Executable pbrush.exe

This ensures we put back all the existing triggers as they were but only overwriting the interval value. If we had just specified the trigger Id 6 and the interval parameter, then the other triggers would have been deleted. This is because this cmdlet must allow you to add or remove triggers or other components when the rule is updated.

If we wanted to programmatically retrieve the existing values for the process trigger templates that we supplied here, we could do this as shown here for one of the two triggers:

get-1eruleparameter -id 1432 | where-object {$_.Name -eq "ProcessLaunch?Executable"} | select-object -ExpandProperty Value

Modifying the fragment parameters

To modify the fragment parameters, we are changing the check fragment’s CheckFragParam to have a value of XXX instead of the default value that was already stored against the parameter.

Note that, as discussed, we have to reference the name of the fragment by substituting underscores for hyphens in creating the PowerShell parameter.

Because no trigger template IDs are specified, nothing is touched for these templates and they remain as they were. (You can, of course, change trigger template parameters AND add fragment parameters to the list as well if you want).

update-1erule -id 1432  -CheckFragmentId 1807 -_1E_Exchange_TestCheckFrag?CheckFragParam "XXX"

PowerShell dynamic properties and parameter defaults

If a parameter does not have a default value, then PowerShell will automatically prompt you for one. For example:

update-1erule -id 1432 -triggertemplateids 6,10,10

If we updated the rule and specified the existing trigger template Ids like this, then we would be prompted for the non-default parameter values for the two process triggers. However, we would not be prompted for the trigger time period because this has a default of 12, and this is used automatically unless we override it by providing a parameter value for it.

Modifying a rule or its parameters from the existing rule

Starting with version 1.2.30 of the 1E PowerShell Toolkit, you can specify a rule object as the source for the update-1erule cmdlet. For example:

$r = get-1erule -id 1432
$r.Description = "I have changed this"
update-1eRule -id 1432 -Rule $r

You could change the time period to every 55 hours like this:

$r = get-1erule -id 1432
$r.Triggers[0].UserParameters[0].Value=55
update-1eRule -id 1432 -Rule $r