Skip to content

Schema

Jump to bottom
Søren Granfeldt edited this page Mar 27, 2024 · 8 revisions

You can define the exact schema needed for your Management Agent (MA). The schema script is typically determined by the data source or system that the scripts communicate with. Therefore, it's up to the user of this MA to define the schema (and anchor value) by creating a schema definition script.

The MA expects the schema script to return at least one object (PSCustomObject) per object type (object class) that you want to support with the MA. The object returned must include a value for ‘objectClass’ and at least one anchor attribute specified with the prefix ‘Anchor-‘, indicating it as an anchor attribute (the prefix text will be automatically removed from the attribute name upon schema discovery).

Below is a sample schema script that defines a 'user' object type / object class -

param
(
	$Username,
	$Password,
	$Credentials,
	$AuxUsername,
	$AuxPassword,
	$AuxCredentials,
	$ConfigurationParameter
)
$obj = New-Object -Type PSCustomObject
$obj | Add-Member -Type NoteProperty -Name "Anchor-Id|String" -Value 1
$obj | Add-Member -Type NoteProperty -Name "objectClass|String" -Value "user"
$obj | Add-Member -Type NoteProperty -Name "AccountName|String" -Value "SG"
$obj | Add-Member -Type NoteProperty -Name "FirstName|String" -Value "Soren"
$obj | Add-Member -Type NoteProperty -Name "LastName|String" -Value "Granfeldt"
$obj | Add-Member -Type NoteProperty -Name "DisplayName|String" -Value "Soren Granfeldt"
$obj | Add-Member -Type NoteProperty -Name "Description|String" -Value "Standard User"
$obj | Add-Member -Type NoteProperty -Name "ImportOnly-ObjectSID|Binary" -Value 0x10
$obj | Add-Member -Type NoteProperty -Name "ExportOnly-Password|String" -Value 'dummy'
$obj | Add-Member -Type NoteProperty -Name "DateValue|String" -Value (Get-Date)
$obj | Add-Member -Type NoteProperty -Name "JustABoolean|Boolean" -Value $true
$obj | Add-Member -Type NoteProperty -Name "Manager|Reference" -Value 2
$obj | Add-Member -Type NoteProperty -Name "MemberOf|Reference[]" -Value (2,3)
$obj | Add-Member -Type NoteProperty -Name "MyMultiValue|String[]" -Value ("S1", "S2")
$obj

If the property is an anchor attribute (only one anchor can be specified per object type), it must be prefixed with the case-sensitive text ‘Anchor-‘. An anchor cannot be of type Reference or Boolean.

You can mark an attribute for ImportOnly or ExportOnly by prefixing the attribute name with the text ‘ImportOnly-‘ or ‘ExportOnly-‘, i.e. as shown in the sample above for the ObjectSID and the Password attributes (the prefix text will be automatically removed from the attribute name upon schema discovery). These prefixes cannot be combined and they cannot be done for the attribute marked as anchor. These prefixes are supported from version 5.6.4.2022 and later.

As can be seen from the sample above, the name of each property of the object returned must be on the form '|', i.e. ‘AccountName|String’. Supported types are -

  • String
  • Integer
  • Boolean
  • Binary
  • Reference

If the property is multi-valued, it should be followed by brackets ‘[]’. Please note that only type String and Reference can be multi-valued.

Below you'll find what some may consider a simpler sample version of a schema script -

new-object -typename psobject -prop @{
 "anchor-id|string" = ""
 "objectclass|string" = "user"
 "username|string" = ""
 "userobjectsid|string" = ""
 "userdescription|string" = ""
}

Using the schema (the $Schema parameter)

The Import and Export scripts receive a parameter named $Schema that has a PSCustomObject describing the schema. You can use this object in your scripts to make them more generic. The schema object is made up of nested PSCustomObjects and follows this structure (depending on your schema) -

  • The root object will have one or more NoteProperties with name like the available objectclasses/types, i.e. person

And under each of the above objectclass property is a PSCustomObject with these NoteProperties -

  • ObjectType - a string with the name of the object type
  • PossibleDNComponentsForProvisioning - a list of elements for building DN's
  • Anchors - a PSCustomObject with a NoteProperty for each anchors available for that particular objectclass
  • Attributes - a PSCustomObject with a NoteProperty for each attribute available for that particular objectclass

Each anchor and attribute NoteProperty is of type SchemaAttribute (from FIM/MIM) and has the following information -

  • Name - The name of the attribute
  • IsMultiValued - a boolean indicating if it is multivalued
  • IsAnchor - a boolean indicating if it is an anchor
  • DataType - an AttributeType object indicating the type of attribute, i.e. String (use .ToString() in PowerShell to get value)
  • AllowedAttributeOperation - a string telling the allowed operations. This is supported from version 5.6.4.2022 and later.
  • HiddenByDefault - a boolean telling if the attribute should be hidden in the GUI. This is not currently used or supported for ECMA2 MA.

Below is a sample output of a $Schema object with a person objectclass/type -

<?xml version="1.0"?>
<Object Type="System.Management.Automation.PSCustomObject">
  <Property Name="person" Type="System.Management.Automation.PSCustomObject">
    <Property Name="ObjectType" Type="System.String">person</Property>
    <Property Name="PossibleDNComponentsForProvisioning" Type="System.Collections.Generic.List`1[System.String]" />
    <Property Name="Anchors" Type="System.Management.Automation.PSCustomObject">
      <Property Name="UserName" Type="Microsoft.MetadirectoryServices.SchemaAttribute">
        <Property Name="Name" Type="System.String">UserName</Property>
        <Property Name="IsMultiValued" Type="System.Boolean">False</Property>
        <Property Name="IsAnchor" Type="System.Boolean">True</Property>
        <Property Name="DataType" Type="Microsoft.MetadirectoryServices.AttributeType">String</Property>
        <Property Name="AllowedAttributeOperation" Type="Microsoft.MetadirectoryServices.AttributeOperation">ImportExport</Property>
        <Property Name="HiddenByDefault" Type="System.Boolean">False</Property>
      </Property>
    </Property>
    <Property Name="Attributes" Type="System.Management.Automation.PSCustomObject">
      <Property Name="FirstName" Type="Microsoft.MetadirectoryServices.SchemaAttribute">
        <Property Name="Name" Type="System.String">FirstName</Property>
        <Property Name="IsMultiValued" Type="System.Boolean">False</Property>
        <Property Name="IsAnchor" Type="System.Boolean">False</Property>
        <Property Name="DataType" Type="Microsoft.MetadirectoryServices.AttributeType">String</Property>
        <Property Name="AllowedAttributeOperation" Type="Microsoft.MetadirectoryServices.AttributeOperation">ImportExport</Property>
        <Property Name="HiddenByDefault" Type="System.Boolean">False</Property>
      </Property>
      <Property Name="Department" Type="Microsoft.MetadirectoryServices.SchemaAttribute">
        <Property Name="Name" Type="System.String">Department</Property>
        <Property Name="IsMultiValued" Type="System.Boolean">False</Property>
        <Property Name="IsAnchor" Type="System.Boolean">False</Property>
        <Property Name="DataType" Type="Microsoft.MetadirectoryServices.AttributeType">String</Property>
        <Property Name="AllowedAttributeOperation" Type="Microsoft.MetadirectoryServices.AttributeOperation">ImportExport</Property>
        <Property Name="HiddenByDefault" Type="System.Boolean">False</Property>
      </Property>
      <Property Name="LastName" Type="Microsoft.MetadirectoryServices.SchemaAttribute">
        <Property Name="Name" Type="System.String">LastName</Property>
        <Property Name="IsMultiValued" Type="System.Boolean">False</Property>
        <Property Name="IsAnchor" Type="System.Boolean">False</Property>
        <Property Name="DataType" Type="Microsoft.MetadirectoryServices.AttributeType">String</Property>
        <Property Name="AllowedAttributeOperation" Type="Microsoft.MetadirectoryServices.AttributeOperation">ImportExport</Property>
        <Property Name="HiddenByDefault" Type="System.Boolean">False</Property>
      </Property>
      <Property Name="UserName" Type="Microsoft.MetadirectoryServices.SchemaAttribute">
        <Property Name="Name" Type="System.String">UserName</Property>
        <Property Name="IsMultiValued" Type="System.Boolean">False</Property>
        <Property Name="IsAnchor" Type="System.Boolean">True</Property>
        <Property Name="DataType" Type="Microsoft.MetadirectoryServices.AttributeType">String</Property>
        <Property Name="AllowedAttributeOperation" Type="Microsoft.MetadirectoryServices.AttributeOperation">ImportExport</Property>
        <Property Name="HiddenByDefault" Type="System.Boolean">False</Property>
      </Property>
    </Property>
  </Property>
</Object>

Refreshing the schema

If the schema needs modifications later, you can alter the schema script and perform a ‘Refresh Schema’ on the defined MA.

Clone this wiki locally