How to Configure RPS-Mapped Parameters
Last updated on September 23, 2021.
Document Status: Document Developer Quality Pending.
Scalar Parameters
Simple [string], [int] and [bool] parameters, such as $IPAddress and $OutputPath, are supplied by RPS by convention.
When RPS is publishing the Partial assigned to a target, it begins with the ResourceAssignment representing the assignment
between the partial config and the computer it's publishing to or when Rps is deploying the Packaging Script Provider
it begins with the TargetItem it is applying the package to.
RPS follows these steps, in order, to find a value for $OutputPath:
- Look for a property on the ResourceAssignment named "OutputPath" (When used in a Partial Configuration.)
- Next, look for a property on the TargetItem named "OutputPath"
- Next, look for a property on the TargetItem's parent named "OutputPath"
- Traverse the parent items until reaching the root TargetItem
- Finally, look to the Node for a property named "OutputPath"
Note
Supplying RPS data to the parameters allows an Administrator to structure data in a more natural way. For example, the OutputPath is common for the Node, so it can be specified once, instead of on every computer within the Node.
PSCredential Parameters
Nearly every partial config will require the use of credentials. To simplify usage, RPS will automatically supply a parameter
of type [PSCredential] by finding a corresponding Credential ResourceItem in RPS.
Using the example below, RPS follows these steps to find a value for $DomainAdmin:
[Parameter(Mandatory = $true)]
[pscredential]
$DomainAdmin,
- Look for a "Credential" ResourceItem assigned to the Target computer with a "Role" matching the parameter's name, "DomainAdmin"
- Next, look for a "Credential" ResourceItem assigned to the Target computer with a "ResourceState" matching the parameter's name
Hashtable Parameters
[Hashtable] parameters allow mapping configuration items in RPS into structured data that PowerShell can easily consume.
Because there are many options for supplying complex data to a parameter, a parameter uses attributes to indicate to RPS how to supply
the values.
The required $DSCEncryptionCertificate parameter is an example.
RPS will find a Certificate ResourceItem assigned to the computer with a Role which includes "DSCEncryption".
That Certificate info, if found, will be supplied to the partial automatically as a Hashtable.
[Parameter(Mandatory = $true)]
[ResourceItemMapping(EntityType = [ResourceTypes]::Certificate, Role = 'DSCEncryption')]
[Hashtable]
$DSCEncryptionCertificate
Entity Mappings
The [ResourceItemMapping] attribute indicates that this parameter is mapped to a ResourceItem in RPS. Supported mappings are:
| Entity | Attribute | Example |
|---|---|---|
| ResourceItem | [ResourceItemMapping] |
[ResourceItemMapping(EntityType = [ResourceTypes]::Certificate, Role = 'DSCEncryption')] |
| TargetItem | [TargetItemItemMapping] |
[TargetItemMapping(EntityType = "NetworkConfig")] |
| ResourceGroup | [ResourceGroupMapping] |
[ResourceGroupMapping(EntityType = "ADGroup", IsAssigned = $true)] |
| ResourceAssignment | [ResourceAssignmentMapping] |
[ResourceAssignmentMapping(EntityType = "SoftwarePackage")] |
Mapping Properties
The following properties are used to filter the mappings:
| Property | Description | Required | Applies To |
|---|---|---|---|
| EntityType | Indicates to RPS to filter based on the item's type. | Yes | All |
| Role | Indicates to RPS to filter based on items that contain the specified Role. | No | ResourceItems |
| IsAssigned | Indicates to RPS to only consider items assigned to the target. Defaults to $true |
No | ResourceItems, ResourceGroups |
| EntityIsActive | Indicates to RPS to only consider active items. Defaults to $null |
No | ResourceItems, TargetItems, ResourceGroups |
Hashtable Array Parameters
Similar in behavior to Hashtables, except these parameters will find zero or more matches in RPS and return them as an array of Hashtables.