Using the RPS API

Note

Find-Rps* Cmdlets have been deprecated and renamed to Get-Rps* with the same functionality, Find verb will be removed in a feature release.

Target Items

Create Target Items

Tip

Target Items can also be created via Set-RpsTargetItem.

Create a new target item

$computer = New-RpsTargetItem -Type "Computer" -Name "Win137"

Create a new target item child

Specify the parent item when creating a child item. You can nest target items as deep as necessary.

$nic = New-RpsTargetItem -Type "NetworkInterface" -Name "137-NIC1" -ParentItem $computer

Create a new target item with Properties

Use a PowerShell Hashtable to pass properties when creating a new target item.

$platform = @{
    Architecture = "x64"
    OSVersion = "8.1"
    OSType = "Windows"
}
$computer = New-RpsTargetItem -Type "Computer" -Name "Win137" -Properties $platform

Create a target item for a different Node

By default, RPS will create new target items for the current node, but you can supply an alternative node.

$site2 = Get-RpsNode -Name "Site 2"
New-RpsTargetItem -Type "Computer" -Name "Win137" -Node $site2

Get Target Items

Use the Get-RpsTargetItem cmdlet to retrieve target items from RPS. Retrieve a single item using the -Id parameter, or retrieve multiple items using any combination of parameters.

Get target items by type

$allRouters = Get-RpsTargetItem -Type "Router"

Get target items by property value

Target Items can be filtered by a specific property or properties.

$deviceByMac = Get-RpsTargetItem -Filter @{ "MacAddress" = "00:11:22:33:44:55" }

Get target items by property

Target Items can be retrieved which have any value for a specific property. To retrieve items with a property, use $null for the value in the -Filter parameter.

$allDevicesWithMac = Get-RpsTargetItem -Filter @{ "MacAddress" = $null }

Get target items by Node

Target items can be retrieved for a specific node.

Tip

The Node parameter is currently limited to just selecting root target items within the specified node. A future update may expand the search to all items within the Node, including child items.

$site2Computers = Get-RpsTargetItem -Node $site2 -Type "Computer"

Update Target Items

Update target items using the Set-RpsTargetItem cmdlet. The Set-Rps* cmdlets will also create items if they don't exist.

The standard way to update an item uses the item's logical identifier, which is Type and Name. To update an existing target item, supply the -Type and -Name parameters and any additional parameters you wish to change.

Update an existing target item

$computer = Set-RpsTargetItem -Type "Computer" -Name "Win137" -IsActive $false

Resource Items

Create Resource Items

Create a new resource item

$resourceItem = Set-RpsResourceItem -Type "type" -Name "name"

Update an existing resource item

$resourceItem = Set-RpsResourceItem -Type "type" -Name "name" -IsActive $false

Get Resource Items

Get all resource items

$allItems = Get-RpsResourceItem

Get resource items by properties

$foundItemsWithSpecificKBNumber = Get-RpsResourceItem -Filter @{"KbNumber" = "3135782"}
$foundAllItemsWithKBNumber = Get-RpsResourceItem -Filter @{"KbNumber" = $null}

Get resource items by role

Resource Items can be retrieved by Role, which is a special property designated for tracking the purpose of a resource item or it's relationship to a target item. To get resource items that have a specific role or have an assignment with a specific role, use the -MatchAssignmentRole parameter. See the section below on Resource Assignments for more info.

$clientAuthCerts = Get-RpsResourceItem -Type Certificate -Role "ClientAuth"
$localAdmins = Get-RpsResourceItem -TargetItem $computer -Type Credential -Role "LocalAdministrator" -MatchAssignmentRole

Target / Resource Groups

Get target groups by name and properties : Sample 1

$foundGroupByName = Get-RpsTargetGroup -Name "Target Group Name"
$foundGroups = Get-RpsTargetGroup -Filter @{"Color" = "Yellow"; "Food" = "Apples"; }
$foundAllGroupsWithColor = Get-RpsTargetGroup -Filter @{"Color" = $null}

Get resource groups by Id. : Sample 1

$foundGroup = Get-RpsResourceGroup -Id $resourceGroup.Id

Get resource groups by properties. : Sample 2

 $foundGroups = Get-RpsResourceGroup -Filter @{"Color" = "Yellow"}
 $foundAllGroupsWithColor = Get-RpsResourceGroup -Filter @{"Color" = $null}

Add resource group

 $resourceGroup = New-RpsResourceGroup -Type "testGroupType" -Name "GroupName" 

Add resource group with properties

 $resourceGroup = New-RpsResourceGroup -Type "testGroupType" -Name "GroupName" -Properties @{ "Prop1" = 'Prop1' }

Add Resource Item to Resource Group

There are two methods to add a Resource Item to a Resource Group. A Resource Item can be assigned to a Resource Group during its initialization. The Resource Group must exist prior to assigning a Resource Item to a Resource Group during its initialization, as shown in the first example.

Add Resource Item in Resource Group in initialization

$resourceItem = New-RpsResourceItem -Type "testType" -Name "TestResourceItem" -ResourceGroup $TestResourceGroup

Additionally, if the Resource Item and the Resource Group already exist, the Resource Item can be added to the Resource Group, as shown in the next example.

Add Resource Item to Resource Group via API

$testResourceGroup = Get-RpsResourceGroup -Name "TestResourceGroup"
$testResourceItem = Get-RpsResourceItem -Name "TestResourceItem"
$testResourceGroup.AddChildItem($testResourceItem)
$testResourceGroup.Update()

Add Target Item to Target Group

There are two methods to add a Target Item to a Target Group. A Target Item can be assigned to a Target Group during its initialization. The Target Group must exist prior to assigning a Target Item to a Target Group during its initialization, as shown in the first example.

Add New Target Item to Target Group

$targetItem = New-RpsTargetItem -Type "Computer" -Name "Server 150" -TargetGroup $servers

Additionally, if the Target Item and the Target Group already exist, the Target Item can be added to the Target Group, as shown in the next example.

Add Target Item to Target Group via API

$testTargetGroup = Get-RpsTargetGroup -Name "TestTargetGroup"
$testTargetItem = Get-RpsTargetItem -Name "TestTargetItem"
$testTargetGroup.AddChildItem($testTargetItem)
$testTargetGroup.Update()

Resource Assignment

A Resource Assignment is the assignment of a specific Resource Item to a specific Target Item. The assocation between the two items can contain Properties, a Status, and other useful information for automations. For example, a resource assignment can track the assignment of a Software Package (Resource) to a Computer (Target). The status may be used to indicate if that software is approved, installed, or up to date.

For convenience, you can specify a resource group in order to quickly assign multiple resources to a target. You can also specify a target group, or both!

Note

As of Release 2.2, duplicate assignments are not allowed. While allowing the assignment to groups, we are enforcing constraints to prevent duplicatous Assignments.

Create Resource Assignments

Assign a Resource Item to Target Item

$assign = New-RpsResourceAssignment -ResourceItem $software -TargetItem $computer

Assign a Resource Item to Resource Source

$assign = New-RpsResourceAssignment -ResourceItem $resourceItem -TargetItem $targetItem -ResourceState $approved

Assign multiple Resource Items to Target Items using Groups

$assignments = New-RpsResourceAssignment -ResourceGroup $securityHotfixes -TargetGroup $allComputers

Get Resource Assignments

Use the Get-RpsResourceAssignment cmdlet to retrieve assignments.

Get Assignments for a Target Item

$computer = Get-RpsTargetItem -Type "Computer" -Name "Win137"
$assignedCredentials = Get-RpsResourceAssignment -TargetItem $computer -Type $rps.ResourceTypes.Credential

Get Assignments by Role

Role is a special property used frequently in RPS to track the purpose of the resource item's association to a target item. The Role property can be placed on a Resource Item or the Resource Assignment, and can hold multiple values separated by the | symbol.

In this example, a Credential (Resource) is assigned to a Computer (Target). The assignment is given a Role of "LocalAdministrator". We can retrieve the designated Local Administrator credential for the computer by using the -Role parameter.

# assign credential and set roles
$computer = Get-RpsTargetItem -Type "Computer" -Name "Win137"
$credential = Get-RpsResourceItem -Type "Credential" -Name "RpsAdministrator"
$assignedCredential = New-RpsResourceAssignment -TargetItem $computer -ResourceItem $credential
$assignedCredential.Role = "LocalAdministrator|RpsUser"
$assignedCredential.Update()

# retrieve the LocalAdmin credential for the computer
$localAdminAssignment = Get-RpsResourceAssignment -TargetItem $computer -Role "LocalAdministrator"```

Update Resource Assignments

Like Task Assignments, Resource Assignments track the history of State changes. Update a resource assignment with the Update-RpsResourceAssignment cmdlet.

Update state of the patch assignment to Denied

The system default of a Resource Assignment is Approved. Here, we want to be able to set whether an administrator is going to Approve or Deny the patch. To manually update the Resource State for the patch, we run the following:

$assignment.ResourceState = "Denied"
Update-RpsResourceAssignment -ResourceAssignment $assignment

Create Patch Group

An updated feature for Release 2.2 is the ability to create Patch Groups. With Patch Groups, a user can add multiple children (members) to the group. This allows for the deployment of multiple patches, simultaneously.

Here, we are creating a new RPS Resource Group, called: $patchGroup.

# Creating patch group
$patchGroup = New-RpsResourceGroup -Type Patch -Name DemoPatches

# Add children to the patch group
$patchGroup.AddChildren($hotfixJuly, $patch2, $patch3)

# Run update on the patch group

$patchGroup.Update()

Now that we have created our patch group and added our 3 children, we can assign our updated Patch to the Target Item.

Assign group of patches to a laptop

Assign the updated Patch Group to the Target Item, $demoLaptop.

New-RpsResourceAssignment -ResourceGroup $patchGroup -TargetItem $demoLaptop

Protected Properties

A Protected Property is a property in any property list that is marked as protected. Once a property is marked as protected, the data is encrypted and the property is marked as protected. To create a Protected Property use the cmdlet Set-Rps ProtectedProperty described below. To retrieve the value from a Protected Property use the cmdlet Get-RpsProtectedProperty as described below.

Get a Protected Property

Retrive a protected property from a Rps item by passing in the item and name of the property. The cmdlet returns a SecureString.

$name = 'Property Name'
$secureResult = Get-RpsProtectedProperty -TargetItem $targetItem -Name $name 
$secureResult = Get-RpsProtectedProperty -ResourceItem $resourceItem -Name $name 
$secureResult = Get-RpsProtectedProperty -Node $node -Name $name 
$secureResult = Get-RpsProtectedProperty -TaskMapAssignment $taskMapAssignment -Name $name 
$secureResult = Get-RpsProtectedProperty -ResourceGroup $resourceGroup -Name $name 
$secureResult = Get-RpsProtectedProperty -TargetGroup $targetGroup -Name $name 

# return variable to plain text
$plainText = ConvertFrom-SecureString $secureResult

Set a Protected Property

To add or update a protected property to any Rps properties collection by passing in the item, name of the property, and a SecureString for the value. The cmdlet returns a true if successful.

#setup
$securePwd = ConvertTo-SecureString "Password" -AsPlainText -force

$result = Set-RpsProtectedProperty -TargetItem $targetItem -Name "Password" -Value $securePwd
Set-RpsProtectedProperty -TargetItem $targetItem -Name $name -Value $securePwd
Set-RpsProtectedProperty -ResourceItem $resourceItem -Name $name  -Value $securePwd
Set-RpsProtectedProperty -Node $node -Name $name -Value $securePwd
Set-RpsProtectedProperty -TaskMapAssignment $taskMapAssignment -Name $name -Value $securePwd
Set-RpsProtectedProperty -ResourceGroup $resourceGroup -Name $name -Value $securePwd
Set-RpsProtectedProperty -TargetGroup $targetGroup -Name $name -Value $securePwd

Password Policy

A Password Policy is a set of password guidelines for a particular system or group of systems. The policy is saved in the database as a Resource Item.

• The default minimum password length is 16 characters
• The default maximum password length is 64 characters
• A WhiteList, when specified, denotes the only characters allowed in a password
• A BlackList, when specified, denotes the only characters disallowed from the standard list, which can be found by executing the code below PowerShell $charList = [Rps.Api.Utils.PasswordUtils]::DefaultPasswordCharacters

Set Password Policy

The following code creates a password policy with a minimum and maximum length and saves that policy to the connected data store

$policy = Set-RpsPasswordPolicy -Name WindowsPasswordPolicy -MinLength 8 -MaxLength 16 

Get Password Policy

The following code retrieves the policy that was previously created

$retrievedPolicy = Get-RpsPasswordPolicy -Name WindowsPasswordPolicy

Password

A Password is a secret string of characters used to gain access to something

Generate Password

A password can be generated using default parameters or by specifying a Password Policy to use. The password can be returned as either a plaintext or secure string by using the AsSecureString switch. Passwords are not persisted to the data store by default.

$newPassword = New-RpsPassword -AsSecureString

$policy = Set-RpsPasswordPolicy -MinLength 20 -MinUppers 5 -MinNumbers 3
$newPassword = New-RpsPassword -PasswordPolicy $policy

Instance Definition

Instance Definitions are pre-defined data sets that consist of various Type Definitions, Items, and Associations between Items that can be used to create complex concrete objects.

Create Instance Definition

Creates an Instance Definition by providing a Name, Properties, and a Parent Node

$nodeId = "81B8272D-B49C-4350-A8F4-ABBB9CE29C68"
$hs = @{
    Prop1 = "value1"
    Prop2 = "value2"
}
New-RpsInstanceDefinition -Name testName -Properties $hs -ParentNodeId $nodeId

Get Instance Definition

Retrieves an Instance Definition by ID or Name

Get-RpsInstanceDefinition -Id "8825A09C-CCE3-4BB0-BCE1-03B4729AC423"
Get-RpsInstanceDefinition -Name testName

Set Instance Definition

Creates or Updates Instance Definitions, associated Properties, and associated parent Node.

Set-RpsInstanceDefinition -Name $Name1
Set-RpsInstanceDefinition -Name $Name1 -Properties @{Prop1 = "Value1"}
Set-RpsInstanceDefinition -Name $Name1 -Properties @{Prop1 = "Value1"} -ParentNodeId $nodeId

Remove Instance Definition

Removes an Instance Definition by ID or by object

Remove-RpsInstanceDefinition -Id "8825A09C-CCE3-4BB0-BCE1-03B4729AC423"
Remove-RpsInstanceDefinition -InstanceDefDefinition $InstanceDefinition

Invoke an Instance Definition

Creates an instance from the definition using settings stored in a resource item.

Invoke-RpsInstanceDefItem -Settings $resourceItem -InstanceDef $instanceDefinition

Get Instance Definition Reference

Retrieves an Instance Definition Reference by providing an Instance Definition and an Instance Definition Item.

    $instanceDef = Get-RpsInstanceDefinition -Name "MyDefinition"
    $instanceDefItem = Get-RpsInstanceDefinitionItem -Name "MyItem"
    $reference = Get-RpsInstanceDefinitionReference -Name "name" -InstanceDefinition $instanceDef -InstanceDefinitionItem $instanceDefItem

New Instance Definition Reference

Creates a new Instance Definition Reference.

    $instanceDef = Get-RpsInstanceDefinition -Name "MyDefinition"
    $instanceDefItem = Get-RpsInstanceDefinitionItem -Name "MyItem"
    $taskMapIDs = "5b8b0340-091f-4823-b2f9-de937b5b4114", "a83b5445-3cc0-433e-b5e0-0fcf70389988"
    $reference = New-RpsInstanceDefinitionReference -Name "name" -InstanceDefinition $instanceDef -InstanceDefinitionItem $instanceDefItem -TaskMapIDs $taskMapIDs

Remove Instance Definition Reference

Removes an Instance Definition Reference by Instance Definition and Instance Definition Item.

    $instanceDef = Get-RpsInstanceDefinition -Name "MyDefinition"
    $instanceDefItem = Get-RpsInstanceDefinitionItem -Name "MyItem"
    Remove-RpsInstanceDefinitionReference -Name "name" -InstanceDefinition $instanceDef -InstanceDefinitionItem $instanceDefItem

Instance Definition Item

An Instance Definition Item is a part of an Instance Definition that can be used to create concrete items such as Target Items, Resource Items, etc.

Get Instance Definition Item

Retrieves an Instance Definition Item by ID, by Name, or by Resource Item.

Get-RpsInstanceDefinitionItem -Id "8825A09C-CCE3-4BB0-BCE1-03B4729AC423"
Get-RpsInstanceDefinitionItem -Name MyInstanceDefItem
Get-RpsInstanceDefinitionItem -ResourceItem $resourceItem -Filter $filterHashtable

Create Instance Definition Item

Creates a new Instance Definition Item by providing an Entity Name, Name, Properties, and Type Definition ID

New-RpsInstanceDefinitionItem -EntityName testEntityName -Name name2 -Properties @{Prop1 = "Value1"} -TypeDefinitionId $typedefinition.id

Set Instance Definition Item

Creates or Updates Instance Definition Items and associated Properties.

Set-RpsInstanceDefinitionItem -Name $Name1 -TypeDefinitionId $id -EntityName $entityName
Set-RpsInstanceDefinitionItem -Name $Name1 -TypeDefinitionId $id -Properties @{Prop1 = "Value1"} -EntityName $entityName 

Remove Instance Definition Item

Removes an instance definition item by either its Id or the instance definition item

Remove-RpsInstanceDefinitionItem -Id "8825A09C-CCE3-4BB0-BCE1-03B4729AC423"
Remove-RpsInstanceDefinitionItem -InstanceDefinitionItem $InstanceDefinitionItem

Instance Definition Node

Create an Instance Definition Node

An Instance Definition Node is a wrapper for an RPS type and associated Properties.

New-RpsInstanceDefinitionNode -EntityName testEntityName -Name name2 -Hostname hostname -IPAddress 1.1.1.1 -SyncEndpointUrl syncEndpoint -certificateThumbprint certThumbprint -pollingInterval 1

Set Instance Definition Node

Creates or updates an Instance Definition Node.

Set-RpsInstanceDefinitionNode -Name name1 -EntityName testEntityName2 -Hostname hostname2 -IPAddress 2.2.2.2 -SyncEndpointUrl syncEndpoint2 -certificateThumbprint certThumbprint2 -pollingInterval 2

Get Instance Definition Node

Get an Instance Definition Node by name.

Get-RpsInstanceDefinitionNode -Name name1 

Remove Instance Definition Node

Removes an Instance Definition Node by ID or by object

Remove-RpsInstanceDefinitionNode -Id "8825A09C-CCE3-4BB0-BCE1-03B4729AC423"
Remove-RpsInstanceDefinitionNode -InstanceDefDefinitionNode $InstanceDefinitionNode

Remove Instance Definition Association

Removes an Instance Definition Association by ID or by object

$instanceDef = Get-RpsInstanceDefinition -Name "MyDefinition"
$instanceDefItem = Get-RpsInstanceDefinitionItem -Name "MyItem"
$instanceDefItem2 = Get-RpsInstanceDefinitionItem -Name "MyItem2"
Remove-RpsInstanceDefinitionAssociation-InstanceDefinition $instanceDef -PrimaryReference $instanceDefItem -Secondaryreference $instanceDefItem2

New Instance Definition Association

Creates an Instance Definition Association by ID or by object

$instanceDef = Get-RpsInstanceDefinition -Name "MyDefinition"
$instanceDefItem = Get-RpsInstanceDefinitionItem -Name "MyItem"
$instanceDefItem2 = Get-RpsInstanceDefinitionItem -Name "MyItem2"
New-RpsInstanceDefinitionAssociation-InstanceDefinition $instanceDef -PrimaryReference $instanceDefItem -Secondaryreference $instanceDefItem2

Get Instance Definition Association

Creates an Instance Definition Association by ID or by object

$instanceDef = Get-RpsInstanceDefinition -Name "MyDefinition"
$instanceDefItem = Get-RpsInstanceDefinitionItem -Name "MyItem"
$instanceDefItem2 = Get-RpsInstanceDefinitionItem -Name "MyItem2"
Get-RpsInstanceDefinitionAssociation-InstanceDefinition $instanceDef -PrimaryReference $instanceDefItem -Secondaryreference $instanceDefItem2

Types

Set Target Type

To Create or Update a RPS Target Type.

Set-RpsTargetType -Name Computer -IsRoot 

Set Resource Type

To Create or Update a RPS Resource Type.

Set-RpsResourceType -Name Host -IsRoot -EnableSubType 

Set Sub Type

To Create or Update a RPS Sub Type.

Set-RpsSubType -Parent $patchDef -SubType 'CAB' 

Set Child Type

To Create or Update a RPS Child Type.

 Set-RpsChildType -Parent $def -ChildType $Rps.TargetTypes.NIC
    -DisplayName 'Network Adapters' -IsRequired -AllowMultiples 

Set Type Property

To Create or Update a RPS Type Propery template.

New-RpsTypeProperty -Parent $template -Name VmType -PropertyType Text -IsRequired -DefaultValue 2012R2 

Set Type Resource Assignment

Creates or updates a Resource Assignment template.

Set-RpsTypeRA -Parent $template -ResourceType 'Host' -DisplayName 'Hypervisor Host' -IsRequired 

Set Target Action

Associates an action (TaskMap Type) with a Target Type definition.

 Set-RpsTargetAction -Parent $template -TaskMapType 'Provision-Vehicle' -Description 'Provision SNE'

Set Resource Group Type

Creates or updates a Resource Group Type

 Set-RpsResourceGroupType -Name MyResourceGroupType -IsGroupReference

Set Target Group Type

Creates or updates a Target Group Type

 Set-RpsTargetGroupType -Name MyTargetGroupType -IsGroupReference