Management Group cmdlets

Management group cmdlets allow you to perform various tasks associated with 1E Platform instructions.

Get-1EManagementGroup [-Id <id>|-Name <name>|-UsableId <usableId>] [-Devices] [-Source SLA|Platform]

With no parameters specified, this cmdlet returns all management groups. If no management groups are defined, no results are returned.

If the -Id, -Name, or -UsableId parameter is specified, the management group (if any) whose -Id, -Name, or -UsableId matches the parameter is returned.

If the -Devices parameter is additionally specified, then the devices contained in the specified management group are returned (if any). An error is thrown if -Devices is specified without also supplying an Id, Name, or UsableId parameter.

The -Source parameter allows you to specify whether management group information is returned from the platform (default) or from SLA.

For more information about SLA management groups, refer to Working with management groups.

To learn how to set up management groups, refer to Management Groups tutorial.

Get-1EManagementGroupReadPermission

This cmdlet returns a list of management groups for which the current user has read permission.

Get-1EManagementGroupWritePermission

This cmdlet returns a list of management groups for which the current user has write permission.

Get-1EManagementGroupDependency -Id <id>

This cmdlet returns a list of entities which have dependencies on a management group (such as Endpoint Automation policies and rules). These entities may need to be deleted or reassigned to another group before this management group can be deleted.

Get-1ESLAManagementGroup [ -Id <Id> ]|[ -Name <Name> ] [-IncludeRules] [-IncludeChildren]

This cmdlet returns all SLA management groups or the group associated with the specified Id or Name. If -IncludeRules is specified, then the management group rules associated with the group(s) are also returned. 

If -IncludeChildren is specified (1E PowerShell Toolkit version 1.2.9+), then the descendents of the rule are also included, along with their descendents, and so on. IncludeRules is ignored if IncludeChildren is specified.

This cmdlet is called internally when Get-1EManagementGroup is invoked with the -Source SLA parameter specified.

New-1ESLAManagementGroup -Name <Name> -Rules <rule expression> [-Description <description>] [-ParentId <id>]

This cmdlet creates a new SLA management group specified by the name, which must be unique for each group.

If the optional description is not specified, the group's description is set to its name.

The rule expression is either a human-readable management group rule expression (1E PowerShell Toolkit version 1.2.9+) or a JSON expression tree. For more information on human-readable management group rule expressions, refer to SLA management groups and rule expressions.

The JSON expression tree format is used internally by the management group subsystem and is what a rule is returned as, if you use the Get-1ESLAManagementGroup cmdlet with the -IncludeRules flag. 
The New-1ESLAManagementGroup cmdlet automatically determines if a rule is in human-readable or JSON expression tree format. The latter is useful if you want to export a management group and its rules and import it on another system, or copy a management group and create a new one with the same rules.

The optional -ParentId parameter specifies the Id of a management group which is to be set as the parent to this group.

When assigning a group parent, the parent group must have been synchronised with Tachyon using the Sync-1ESLAManagementGroup cmdlet, otherwise a permission error is returned.

Remove-1ESLAManagementGroup -Id <id> [-Force] [-WhatIf]

This cmdlet deletes the SLA management group specified by the Id.

-Force and -Whatif were added for release 1.2.9 of the Toolkit.

If the management group has children, the delete will throw an error unless -Force is used. In that case all children and their children will be deleted as well.

To see which management groups would be deleted, use the -WhatIf parameter. This will return all the management groups that will be deleted but will not actually perform the deletion.

If an SLA management group that has been synchronized with the 1E Platform is deleted, it remains in the list of platform management groups until the Sync-1ESLAManagementGroup cmdlet is run against another existing SLA group. When this is done, the deleted group is removed from the platform's list of management groups.

You may receive an error indicating that the management group is in use. If this occurs, try running the Sync-1ESLAManagementGroup cmdlet, specifying the group you are trying to delete, then retry the delete operation.

Sync-1ESLAManagementGroup -Id <Id> -RepositoryId <RepositoryId>

This cmdlet synchronizes the 1E Platform's management group list with the SLA management group list. You must specify the Id of a valid SLA management group and the Id of a valid repository. Normally, this is the Default Inventory repository. To obtain repository Ids, use the Get-1ESLARepository cmdlet

When you synchronize, the following occurs:

  • Any new SLA management groups are added to the platform management group list. However these new groups do not have their members evaluated when they are added. You must explicitly synchronize these groups for that to occur.
  • Any deleted SLA management groups are removed from the platform management group list.
  • The specified management group in the Sync-1ESLAManagementGroup cmdlet is updated in the platform with a revised set of member devices which are defined by the management group rules.
  • Note that other management groups in SLA that are modified, are not resynchronized unless you explicitly invoke this cmdlet specifying their Ids.

Update-1ESLAManagementGroup -Id <id> [-Name <name>] [-Description <description>] [-Rules <rule expression>] [-ParentId <parentId>] [-RemoveParent]

This cmdlet updates the specified SLA management group. If any optional parameter is not supplied, then the current value for that parameter is left unchanged.

The -RemoveParent parameter allows any existing parent to be removed from the management group. Management groups without a parent are assumed to be children of the built-in All Devices group.

Refer to the New-1ESLAManagementGroup cmdlet above regarding the assignation of group parents.

The rule expression is either a human-readable management group rule expression (1E PowerShell Toolkit version 1.2.11+) or a JSON expression tree. For more information on human-readable management group rule expressions, refer to SLA management groups and rule expressions.

The JSON expression tree format is used internally by the management group subsystem and is what a rule is returned as, if you use the Get-1ESLAManagementGroup cmdlet with the -IncludeRules flag. 
The New-1ESLAManagementGroup cmdlet automatically determines if a rule is in human-readable or JSON expression tree format. The latter is useful if you want to export a management group and its rules and import it on another system, or copy a management group and create a new one with the same rules.

You must invoke the Sync-1ESLAManagementGroup cmdlet after making changes to the SLA management group for the changes to be propagated back to the platform from SLA.

If the management group is not rule-based (that is, a direct membership group), then an error is thrown. You update direct membership groups with the Set-1ESLADirectManagementGroup cmdlet.

If you have created a draft management group associated with this management group, then the draft is automatically deleted when you execute this cmdlet.

If another user has created a draft management group associated with this management group, you will receive an error if you attempt to update the management group with this cmdlet.

For more information, refer to Draft management groups.

Get-1ESLARepository

This cmdlet returns a list of all SLA repositories. You can use this cmdlet to obtain the appropriate repository Id for use with the Sync-1ESLAManagementGroup cmdlet. The repository Id is the Id member of the repository properties returned.

Get-1ESLAManagementGroupRuleAttribute

This cmdlet returns the valid SLA management group attributes that can be used in rule expressions, along with their data type and SLA record ID. Note that SLA record Ids are site-specific.

For more information on the use of management group rule attributes in rule expressions, refer to SLA management groups and rule expressions.

Get-1ESLAManagementGroupDevice -Id <id> -RepositoryId <RepositoryId>

This cmdlet returns a list of devices that are contained within the specified management group within the specified repository.

When a management group is synced with the 1E Platform, you should see the same device set reported when you use the Get-1ERespondingDevice cmdlet and specify a scope "managementgroup=nn" where nn is the platform Id for the management group.

An exception is currently thrown if the underlying group contains no devices. This is caused by the current API behavior and may change in a future release of the platform.

Set-1ESLADirectManagementGroup -Name <Name> [-Description <description>] -FqdnList <fqdn list>

This cmdlet creates or updates an SLA direct membership management group. The list of Fqdns which is to constitute the group membership is passed as an array.

Copy 
Set-1ESLADirectManagementGroup -Name DirectGroup -FqdnList @("urth-sql.urth.local", "urth-dev.urth.local")

A platform synchronization operation is triggered automatically when this cmdlet is run, unlike for rule-based management groups. During the synchronization, any other management group changes (new or deleted groups) will be propagated across as well.

It is not possible to assign a parent to a direct membership management group.

Get-1EManagementGroupDraft [ -Id <id>] [ -IncludeRules ]

This cmdlet retrieves the draft management group (if any) associated with the specified management group, or all draft management groups if -Id is not specified.

If there is no draft management group associated with the management group, an error is thrown.

If -IncludeRules is specified, then the rules for the draft management group or groups are returned.

Only drafts associated with the user who created them are returned. You cannot view drafts associated with a different user, even if you are authenticated in a role with full administrator rights.

New-1EManagementGroupDraft  -Id <Id> -Name <Name>  [ -Description <Description> ] [ -Rules <Rule expression> ] [ -ParentId <parentid> ]

This cmdlet creates a new draft management group and associates it with the management group whose Id is specified.

If any optional parameter is not specified, the draft management group inherits the associated property from the base management group.

Only one draft management group for one user can be associated with a management group tree. If a draft is associated with any level of a management group tree already, then an error is thrown when this cmdlet is executed.

Update-1EManagementGroupDraft -Id <Id>  [ -Name <Name> ] [ -Description <Description> ] [ -Rules <RuleExpression> ] [ -ParentId <parentId> ]

This cmdlet updates any or all of the name, description, rules, or parentId associated with the draft management group (if any) associated with the management group whose Id is specified.

If no draft management group is associated with the management group, or there is a draft management group associated with a parent or child management group of this management group, an error is thrown.

You cannot view draft management groups associated with another user (even if you have full admin rights on the platform). If you or another user has created a draft management group against any level of the tree in which this management group resides, you will receive an error if you run this cmdlet.

Update-1EManagementGroupfromDraft -Id <Id> [ -WhatIf ]

This cmdlet updates the management group specified from the attached draft management group (if any), copying over the name, description, and rules defined for that draft management group. The draft management group is then deleted.

An error is thrown if no draft management group is associated with the management group or if the draft management group associated with the management group was created by another user.

If the -WhatIf parameter is specified, then the draft management group attached to the management group is returned as the result of this cmdlet, including all rules. However no further action takes place and the draft management group is not deleted.

Remove-1EManagementGroupDraft -Id <Id>

This cmdlet deletes the draft management group (if any) associated with the specified management group Id.
An error is thrown if there is no draft management group or if the the draft management group was not created by the user running the remove-1EManagementGroupDraft cmdlet.

Get-1EManagementGroupRevisions -Id <Id> [ -Page <Page> ]  [ -Size <Size> ]

This cmdlet returns all revisions that have been made to the management group whose Id is specified. This provides an audit trail of changes to the management group.

The Page parameter specifies the page number for paged output starting with 0. The default value is 0 if the parameter is omitted. The Size parameter specifies number of rows in each page. Setting this to 0 results in all rows being returned.

Invoke-1EManagementGroupDraftSimulation -Id <Id>

This cmdlet causes a simulation to be run against the draft management group associated with the management group whose Id is specified so that the actual devices associated with the draft management group can be evaluated.

An error is thrown if there is no draft management group or if the draft management group was not created by the user running the Invoke-1EManagementGroupDraftSimulation cmdlet.

Get-ManagementGroupDraftSimulationStatus -Id <Id>

This cmdlet returns the current status of the simulation for the draft management group associated with the management group whose Id is specified.

An error is thrown if there is no draft management group or if the the draft management group was not created by the user running the Get-1EManagementGroupDraftSimulationStatus cmdlet.

Simulation is an asynchronous process and, consequently, the status returned after the cmdlet is called may not represent completion.

If you intend to invoke simulation and then update the base management group from the draft in a script, you should loop, calling this cmdlet after sleeping for a few seconds, until the simulation status goes to complete.

Note that some statuses shown in the list below are reserved for future use:

  • InProgress
  • NotStarted
  • Completed
  • Failed
  • Pending
  • Canceled

Get-1EManagementGroupDraftSimulateDevices -Id <Id>

This cmdlet returns a count of devices associated with the draft management group after a simulation run.

An error is thrown if there is no draft management group or if the draft management group was not created by the user running the Get-1EManagementGroupDraftSimulateDevices cmdlet.

You cannot currently retrieve an actual device list, only a count of devices. 

If no simulation has yet run for the draft management group, then you will get an exception while using this cmdlet.

Get-1EManagementGroupDraftLifetimeInHours

This cmdlet returns the configured lifetime for draft management groups (normally 72 hours). After this time period, any draft management groups are automatically deleted.