Guaranteed State management cmdlets

Guaranteed State management cmdlets allow you to manage entities associated with the Guaranteed State subsystem, including fragments, policies, rules, and trigger templates.

Publish-1EFragment -File <filename>

This cmdlet uploads the specified fragment XML file. The file is assumed to be a valid Guaranteed State fragment XML file and to have been signed. As fragment files have the same format as instruction files, except for having a type of Check instead of Question or Action, you can use the protect-1Einstruction cmdlet to sign fragments.

If the fragment already exists on the 1E Platform server, the version of the fragment to be published must be greater than the existing one.

If the fragment has been associated with rules that are in turn associated with active policies, then these policies must be redeployed from the Guaranteed State administration page for the modified fragment to take effect.

To force the policy cache to be updated, you should disable and enable any rules that use the fragment (using Update-1ERule id <id> -Disable and then Update-1ERule id <id> -Enable) and then redeploy the policies with send-1epolicy.

If the fragment upload is rejected with an invalid signature, but you are certain that the signing certificate is valid on the destination platform, verify that the fragment payload does not contain characters outside the standard ASCII set. In particular, quote characters copied from Microsoft Word may lie outside this range. This can cause the platform API to reject the upload.

Get-1EAllFragment

This cmdlet returns summary information on all Guaranteed State fragments.

Get-1EFragment -Id <id>

This cmdlet returns detailed information on the specified fragment.

Export-1EFragment -Id <id>|-Name <name> -File <filename>

This cmdlet exports the specified fragment using either the specified fragment Id or Name to an XML file. The resulting output file can be directly loaded into the Tachyon Instruction Management Studio (TIMS) instruction authoring tool.

Get-1EFragmentRule -Id <id>

This cmdlet gets the rules (if any) that are associated with the current fragment.

Remove-1EFragment -Id <id> [-Force] [-Whatif]

This cmdlet removes the specified fragment. If the fragment is associated with any rules, this cmdlet will throw an error unless the -Force option is specified.

If the -Force option is specified, then any rules associated with the fragment are deleted. Any policies associated with these rules will have the rules removed from those policies.

If the -Force option is specified, all rules which were deleted as a result of using the -Force option are returned as the result of this cmdlet.

If the -Whatif option is specified, all rules which would have been deleted if -Force had been specified will be returned but no other action is taken.

Get-1EAllPolicy

This cmdlet returns summary information on all Guaranteed State policies.

Get-1EPolicy -Id <id>|-Name <name> [-AsXml] [-Path <path>]

This cmdlet returns detailed information on the specified policy, specified either by Id or Name.

If the -AsXml parameter is specified, the information is returned in a format compatible with product pack XML files that define Guaranteed State entities. For more information, refer to Export-1EPolicy -Id <id>|-Name <name> -Path <path>.

If the -Path parameter is specified, the output is written to the file whose path and name are specified.

Remove-1EPolicy -Id <id>|-Name <name>

This cmdlet deletes the policy specified by the Id or Name. Rules associated with the policy are not deleted.

Add-1EPolicy -Name <name> -Description <description> [-Disabled]

This cmdlet adds the policy with the given name and description. The policy is added in the enabled state unless the optional -Disabled flag is specified.

Enable-1EPolicy -Id <id>

This cmdlet sets the state of the specified policy to Enabled.

Disable-1EPolicy -Id <id>

This cmdlet sets the state of the specified policy to Disabled (that is, enabled = false).

Send-1EPolicy

This cmdlet deploys all enabled policies. It returns no data.

Deploy was not added as an acceptable PowerShell verb until PowerShell 6, so to avoid warning messages, this cmdlet has been named Send rather than Deploy.

Add-1EPolicyRule -Id <id> -RuleId <ruleid>

This cmdlet adds the rule specified by -RuleId to the policy specified by -Id. An exception is thrown if the rule does not exist, the policy Id does not exist, or the rule is already associated with the policy.

It returns the collection of rules associated with the policy after the operation.

Get-1EPolicyRule -Id <id> [-Full]

This cmdlet returns the rules associated with the policy specified by -Id in the format shown above for Add-1EPolicyRule.

If the -Full parameter is specified, then the rules are returned directly from the underlying rules API. The information contained in the full rule object is quite lengthy, as all SCALE payloads are included in full. For an example of the information that is returned for each policy rule if the -Full option is specified, refer to Get-1ERule [-Id <id>] [-Name <name>] [-AsXml] [-Path <path>].

Get-1EPolicyAssignment

This cmdlet returns all policy assignments to management groups.

Remove-1EPolicyRule -Id <id> -RuleId <ruleid>

This cmdlet removes the rule specified by -RuleId from the policy specified by -Id. An exception is thrown if the rule does not exist, the policy Id does not exist or the rule is not already associated with the policy.

It returns the collection of rules associated with the policy after the operation completes, as shown for the Add-1EPolicyRule cmdlet above.

Get-1EAllRule [-Unlicensed]

This cmdlet returns summary information for each rule. If -Unlicensed is specified, then only unlicensed rules are returned.

Get-1ERule [-Id <id>] [-Name <name>] [-AsXml] [-Path <path>]

This cmdlet returns detailed information for the rule specified by the Id or Name parameters.

If the AsXml parameter is specified, output is returned in XML format, consistent with the definition of rules as part of an Integrated Product Pack file. For more information, refer to Export-1EPolicy -Id <id>|-Name <name> -Path <path>.

If the Path parameter is specified, output is written to the file whose path and name are defined.

Get-1ERuleHistory -Id <id> [-Revision <Revision>] [-Full]

This cmdlet returns the revision history of the rule specified by the Id parameter.

If -Revision is specified, then only information about the specified revision is returned.

If -Full is specified, the full rule information for all revisions (or just the specified revision) is returned. Otherwise, a summary of the rule properties for each revision is returned.

A rule will always have an initial revision of 1. Each time the rule is updated, a new revision is created (2,3,....). The most recent revision of a rule will always be the version which is active within the Guaranteed State subsystem.

Remove-1ERule -Id <id>|-Name <name> [-Force] [-Whatif]

This cmdlet removes the rule specified by the Id or Name parameter.

If the -Force option is not specified, then if the rule is associated with any policies, this cmdlet will throw an exception.

If -Force is specified, all policies using this rule will have the rule removed from them.

If -Whatif is specified, any policies that use this rule will be returned.

Update-1ERule -Id <id> [-Name <name>] [-Description <description>] [-Enable|-Disable] [-CheckFragmentId <checkfragmentId>] [-TriggerTemplateIds <TriggerTemplateIds>] [-FixFragmentId <fixfragmentid>] [-PreconditionFragmentId <preconditionfragmentid>] [ Trigger Template and Fragment parameters ]

This cmdlet updates the rule specified by the -Id parameter.

At least one parameter must be specified or an error is thrown and the rule is left unmodified.

The fragments and trigger templates associated with a rule can themselves have parameters. These parameters are explained further down. Refer to Fragment and trigger template parameters.

If you specify a CheckFragmentId parameter, then the check fragment associated with the rule is replaced. You can specify the same check fragment id as the fragment presently associated with the rule. You can supply new values for any parameters associated with the check fragment. For information on how fragment parameters work, refer to Add-1ERule -Name <name> -Description <description> -CheckFragmentId <check fragment id> -TriggerTemplateIds <ids> [-PreconditionFragmentId <fragment id>] [-FixFragmentId <fragment Id>] [-Disable] [ Trigger Template and Fragment parameters ].

If you supply a FixFragmentId parameter or a PreconditionFragmentId parameter, then the existing fragments are replaced if they exist. Otherwise, they are created. You can supply parameter values for these fragments.

If you supply a fragmentid of -1 for either of these parameters, then the existing fragment (if any) is removed from the rule. You cannot remove a check fragment from a rule as it is a mandatory component for a rule.

If the fix fragment is removed, the rule type is modified to become a check rule. If a fix fragment is added, the rule type is modified to become a fix rule.

You can specify a new value for -triggertemplateids. When you do this, the entire trigger template Id set is replaced. You can specify parameters for the template(s) when you do this.

Fragment types and Ids are validated. You cannot specify a fragment with an inappropriate type. For example, you cannot assign a fix fragment to a check fragment. An error is thrown if you attempt to do so.

In 1E Platform releases prior to 8.3, updating a rule also changes its id and causes any rule compliance history associated with the rule to be lost. From release 8.3 onwards, rule ids remain stable after an update, and rule history is preserved.

Add-1ERule -Name <name> -Description <description> -CheckFragmentId <check fragment id> -TriggerTemplateIds <ids> [-PreconditionFragmentId <fragment id>] [-FixFragmentId <fragment Id>] [-Disable] [ Trigger Template and Fragment parameters ]

This cmdlet adds a new rule. You must specify the name, description, check fragment id, and at least one trigger template Id. Multiple template ids can be passed as a PowerShell array. For example @(4,17) specifies the two trigger template ids, 4 and 17.

The precondition and fix fragment ids are optional. To create a rule in an initially disabled state, specify the optional -Disable parameter. If it is not specified, the rule is created in an enabled state.

Check, precondition, and fix fragments can have parameters, as can trigger templates. These parameters will be prompted for dynamically if not specified and if there is no default value for them.

Fragment and trigger template parameters

Fragments and trigger templates can have parameters. For example, the fragment 1E-Guaranteed-State-Check-Service-State has a State parameter that specifies the service state that is to be checked by the fragment.

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.

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

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.

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.

Copy

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

Get-1ETriggerTemplateParameter -Id <id>

This cmdlet returns the parameters (if any) for the specified trigger template in a format acceptable to the Add-1ERule cmdlet.

Copy

Get-1ETriggerTemplateParameter -Id 14

Get-1EFragmentParameter -Id <id>

This cmdlet returns the parameters (if any) for the specified fragment in a format acceptable to the Add-TachyonRule cmdlet.

Copy

Get-1EFragmentParameter -Id 7

Get-1ERulePolicy -Id <id>

This cmdlet returns information on all policies that include the rule specified by -Id.

Add-1EPolicyAssignment -Id <id> -ManagementGroupId <managementgroupid>

This cmdlet assigns the specified management group to the policy specified by -Id.

The management group Id you specify is returned as the Id property from management groups returned by the get-1Emanagementgroups cmdlet. Note that this Id differs from the UseableId property that each management group also possesses. You use the UseableId property when you use management groups in scope expressions. Refer to Scope and filter expressions.

The management group Id of 1 is reserved for the All Devices management group. This group is a virtual group and is not returned by the get-1Emanagementgroups cmdlet. To assign a policy to the All Devices management group, specify a management group Id of 1 when using the Add-1EPolicyAssignment cmdlet.

Remove-1EPolicyAssignment -Id <id>

This cmdlet removes the policy assignment whose Id is specified by the -Id parameter.

Each policy assignment has a unique Id. Do not confuse policy assignment Ids with the actual policy Id itself. The policy assignment Id uniquely identifies a particular association between a specific policy and a specific management group.

To identify existing assignments and retrieve their IDs, use the get-1Epolicyassignment cmdlet.

Get-1EPolicyChange

This cmdlet shows all pending changes that will be applied if policy deployment is requested.

Get-1EPolicyDeviceStatus [-Id <id>]

This cmdlet returns a summary of device compliance for all active policies or, if a valid policy ID is specified, compliance for that specific policy.

Get-1EPolicyRuleStatus [-Id <id>]

This cmdlet returns a summary of rule compliance for all active policies or, if a valid policy ID is specified, compliance for that specific policy. The format of the returned data is identical to Get-1EPolicyDeviceStatus.

Get-1EPolicyEffectiveness [-Id <id>]

This cmdlet returns a summary of policy effectiveness by summarizing rule counts for each category for all policies or, if a valid policy ID is specified, information for that specific policy.

Get-1EPolicyRuleRemediation -Days <days> [-Id <id>]

This cmdlet returns the remediation status over time for all policies or for the specified policy. -Days can be any value from 1 to 366. Note that in some cases, result rows can be returned prior to policy creation. This is associated with the current API behaviour at this point.

Get-1EPolicyRuleDeviceStatus -Id <Id> [-RuleId <RuleId>]

This cmdlet returns the individual device compliance status for the policy whose Id is specified.

If the optional -RuleId parameter is specified, then device compliance information for that specific rule is returned.

An error is thrown if the rule is not associated with the policy.

To get a list of rules associated with a policy, use the get-1Epolicyrule cmdlet.

In the screenshot below, the output of the cmdlet has been piped to the standard PowerShell cmdlet format-list to show the results more clearly.

Copy

Get-1EPolicyRuleDeviceStatus -Id 3 | format-list *

Copy

Get-1EPolicyRuleDeviceStatus -Id 3 -RuleId 56

Get-1EAllTriggerTemplate

This cmdlet returns information for all trigger templates.

Get-1ETriggerTemplate -Id <id>|-Name <name> [-AsXml] [-Path <path>]

This cmdlet returns information for the specified trigger template.

If the AsXml parameter is specified, output is returned in XML format consistent with the requirements for files contained in Integrated Product Packs. For more information, refer to Export-1EPolicy -Id <id>|-Name <name> -Path <path>.

If the Path parameter is specified, output is written to the file whose path and name are defined.

The following creates a manifest XML file whose name, description, and (optional) icon filename properties are specified by the parameters. The output is written to the file whose path and name are given by the path property.

Copy

Set-Manifest -Name <name> -Description <description> [-Icon <icon>] -Path <path>

Manifest files are used when creating Integrated Product Packs. For more information, refer to Export-1EPolicy -Id <id>|-Name <name> -Path <path>.

Remove-1ETriggerTemplate -Id <id> | -Name <name>

This cmdlet deletes the specified trigger template. If there are rules referencing this template, an error is thrown. You must modify the rules so that they do not reference the trigger template before you can delete it.

Add-1ETriggerTemplate -Name <name> -Category <category> -Description <description> -Type <type> -ReadablePayload <readablepayload> [ -AgentParameters <agentparams> | -AgentParametersJson <agentparametersjson> ] [ -UserParameters <userparams> | -UserParametersJson <userparamsjson> ]

This cmdlet adds a trigger template. The optional AgentParameters, AgentParametersJson, UserParameters, and UserParametersJson allow you to specify agent parameters or user parameters either as JSON strings or as objects.

For example, you can specify both as JSON in the following way:

Copy

-AgentParametersJson '{"foo":"pow"}' -UserParametersJson '[{"name":"param1", "DataType": "string"}]'

You must specify user parameters as an array, as in the example here. Alternatively, you can specify either or both of these parameters using objects.

For example, you could retrieve an existing trigger template with the following: $t = get-1etriggertemplate -id 16.

Then you can use -AgentParameters $t.AgentParametersJson or -UserParameters $t.UserParameters to duplicate the existing properties of that trigger template into the one you are creating.

Alternatively, you can create objects in PowerShell or use PowerShell hashtables as inputs. For example, -AgentParameters @{foo="pow"; bar="zap"} and -UserParameters @{name="param1"; Datatype="string"}.

Note that user parameters take a fixed list of properties, and properties outside this list are ignored. These properties are the following: Name, Pattern, DataType, ControlType, ControlMetadata, Placeholder, DefaultValue, Validation, Value, HintText, and Source.

For more information, refer to Trigger templates and preconditions reference.

Export-1EPolicy -Id <id>|-Name <name> -Path <path>

This cmdlet creates a ZIP file which is compatible with the Product Pack Deployment Tool and can be used to import a Endpoint Automation policy, along with all rules, fragments, and trigger templates into another 1E Platform server instance.

These files are known as Integrated Product Packs. The path should specify a filename with the .zip extension.

For more information on the Product Pack Deployment Tool, refer to 1E product pack deployment tool.

For more information about Integrated Product Packs, refer to Endpoint Automation.

Invoke-1EProductPackDeploymentTool -Path <path> [ -Force ]

This cmdlet invokes the Product Pack Deployment tool. Note that this tool is not bundled with the 1E PowerShell Toolkit and should be obtained from an appropriate platform installation.

Recent versions of the Product Pack Deployment Tool directly support platform-neutral authentication and can therefore be used directly. This cmdlet is retained for legacy purposes only.

The -Path parameter specifies the folder in which the tool is located.

The -Force parameter enables the tool to delete existing Endpoint Automation and instruction information. If not specified, the button to enable this functionality is disabled in the tool UI.

Use caution if you enable this feature. Removing all existing Endpoint Automation and instruction information from a target platform will impact functionality significantly. This feature is intended for use with test platforms where you may want to reset the platform to a known state and then import a fresh set of product packs.

You must have set the 1E Platform server first, using the set-1Eserver cmdlet, before you can run this cmdlet.

If the platform server you are connecting to is configured for platform-neutral authentication, then an appropriate access token is passed to the product pack deployment tool so that it can access the server via platform-neutral authentication. The token is refreshed immediately prior to invoking the product pack deployment tool, so that it remains valid for a reasonable time to allow the tool to be used.

For more information on the Product Pack Deployment Tool, refer to 1E product pack deployment tool.