Managing objects of the Organization Directory

The previous section presented information about how to navigate the PowerShell drive and how to retrieve and display objects resp. how to use filters to reduce the amount of retrieved objects. You are now enabled to discover lots of useful information about the current state of your DSM 2019.1 environment.


Until now you have accessed the DSM 2019.1 environment only in a read only manner, that is you have not created new objects or manipulated existing objects. In this section we will change that by introducing some write operations.


First you will learn how to create, to modify and to delete objects of the Organization Directory. In a live system, this is probably the most popular use case of the PowerShell Extensions for Ivanti DSM, because the ORG Directory (ODS) is the part of the DSMDB with the highest rate of change. Typically you have to create new or delete Organizational Units, you have to insert Computers or import them from other data sources. You have to move, reinstall or delete Computers and to create new groups or manipulate the group memberships of users and computers.


Change to the base directory "Managed Users & Computers", if it is not your current working directory yet, by executing the command:


cd "emdb:\rootDSE\Managed Users & Computers"


Creating Organizational Units and Computer objects

In this step we want to create an Organizational Unit named "Rom". The most simple command to achieve this task is by typing


New-EmdbOrganizationalUnit "Rom"


Hint: In the context of the Organization Directory the command mkdir is an alias for the cmdlet New-OrganizationalUnit, therefore the command mkdir "Rom" is synonymous.


Now change into the newly created OU:


cd "Rom"


Next we want to populate the OU with a new computer named "XP99". Use the cmdlet New-EmdbComputer to create it:


New-EmdbComputer "XP99"


Now switch to the DSMC and make sure the Organizational Unit and the computer were created. Notice the inactive state (except you had changed the Initial Computer Activation plan) of the computer.


We assume the computer "XP99" to be a notebook and DSM 2019.1 should reflect this. Furthermore we want a meaningful description like "Managed with PowerShell" associated with this computer. Switch back to the PowerShell console and execute the following commands:


$MyComputer = Get-EmdbComputer "XP99"

$MyComputer.ComputerType = "Laptop"

$MyComputer.Description = "Managed with PowerShell"

$MyComputer.Update()


As you can see, the changes of the computer's properties are not immediately activated. You have to call the method Update() to write the changes back to the DSMDB.


In contrast to the modification of properties, calls to methods are executed immediately. To illustrate this behaviour activate a computer with the following command:


$MyComputer.Activate()


Hint: An alternative approach for activating a computer is to use the corresponding property OperationMode. Valid values for this property are (among others) the plain text labels associated with this property in the DSMC. As an example you can set the property with the command $MyComputer.OperationMode = "Prepare for Reinstall" and write it back to the DSMDB with a subsequent call to the Update()-method.  


Creating and managing group objects

Next we want to populate the Organizational Unit with a static computer group. We utilize the cmdlet New-EmdbGroup with parameters supplying the name of the group and the category of the group's members:


New-EmdbGroup "Laptops Rom" -TargetCategory "Computer"


Switch to the DSMC and check the successful creation of the group. Now the computer "XP99" should become a member of the group "Laptops Rom". We can use the cmdlet Add-EmdbGroupmember to perform this task. A list of groups and a list of objects of the approbiate type to become members of the groups are expected as input parameters. The lists might consist of only a single object each as the following example shows:


$MyGroup = Get-EmdbGroup "Laptops Rom"

Add-EmdbGroupMember -Group $MyGroup -Member $MyComputer


Using lists containing multiple objects as input parameters a computer can become the member of several groups with only a single call to the cmdlet. In this example the computer "XP99" should become a member of the computer group "Laptops Rom" and (the still to create) computer group "Laptops Berlin":


$grpList = @("Laptops Rom", "Laptops Berlin")

Add-EmdbGroupMember -Group $grpList -Member $MyComputer


Alternatively group memberships can be created by calling the method AddMember() of a group object. The computer that should gain the membership is given as the parameter:


$MyGroup = Get-EmdbGroup "Laptops Rom"

$MyGroup.AddMember($MyComputer)


Because AddMember() is a method, the changes are written back to the DSMDB immediately. Refer to the DSMC to check the group memberships.


The cmdlet Get-EmdbGroupmember allows to identify the members of a group. It has to be parametrised with the name of the group or an object of type "Group":


Get-EmdbGroupMember -Group "Laptops Rom"


If the cmdlet is parametrised with a list of group names or objects of type "group" the cmdlet delivers all member of this groups with a single invocation of the cmdlet:


$grpList = @("Laptops Rom", "Laptops Berlin")

Get-EmdbGropMember -Group $grpList


Alternatively the members of a group can be identified by calling the method GetMembers() of a group object:


$MyGroup.GetMembers()


Removing members from a group is similar to adding them, except the cmdlet Remove-EmdbGroupmember is used:


Remove-EmdbGroupMembership -Group $MyGroup -Member $MyComputer)


Similar to the other cmdlets Remove-EmdGroupMembership supports object lists as input parameters. Alternatively group membership can be discarded by calling the method RemoveMember() of a object of type "Group":


$MyGroup.RemoveMember($MyComputer)


The creation of a Dynamic Group requires two additional parameters: -Dynamic to request the creation of a Dynamic Group and -Filter to specify the LDAP filter describing the groups members:


New-EmdbGroup "Laptops" -TargetCategory "Computer" -Dynamic -Filter "Computer.ComputerType=Laptop"


Hint: More information about filtering is available in the section Using Filters.


Assigning software packages to external groups (e.g. Active Directory groups) is a common task in DSM 2019.1 environments. This leads to the need to import Active Directory groups into DSM 2019.1. The PowerShell Extensions for Ivanti DSM provide assistance to fulfill this task. As a prerequisite you need to know the SID of the group you want to import.


First determine the SID of the Active Directory group you want to import


$MyADGroup = New-Object System.Security.Principal.NTAccount("Adobe Reader 9.0 Group")

$MySID = $MyADGroup.Translate([System.Security.Principal.SecurityIdentifier]).ToString()


and then import the group using the following command:


New-EmdbExternalGroup "Adobe Reader 9.0 Group" -UniqueID $MySID -IDProvider "AD"


Hint: For a successful execution of the above commands make sure a group named "Adobe Reader 9.0 Group" exists in your Active Directory.


The creation resp. the import of an external group requires the parameters group name, unique ID and the so called ID provider. The latter has to be "AD" for Active Directory groups. You can choose any name for the imported group that is valid in this context. But we suggest to use the same name as in the Active Directory.