Skip to content

Metaverse Attributes

The Metaverse Attribute cmdlets manage the attributes a Metaverse Object can hold: list, create, change and delete them, bind them to Metaverse Object Types, and order the Connected Systems that contribute a value to each. What Metaverse Attributes are is covered in Metaverse, and how contributions are ordered in Attribute Priority.

What stored values block on a custom Metaverse Attribute While any Metaverse Object holds a value for a custom Metaverse Attribute, Set-JIMMetaverseAttribute makes one schema change, widening it from single-valued to multi-valued with its type unchanged, which keeps every value, and refuses any other change of type or plurality; Remove-JIMMetaverseAttribute refuses to delete it; and Remove-JIMMetaverseObjectTypeAttribute refuses to unbind it from an Object Type whose objects hold a value. Once the values are cleared, any change of type or plurality is made; the deletion goes ahead, removing its Object Type bindings, Attribute Flows, Scoping Criteria and Object Matching Rules; and unbinding removes the Attribute Flows, Scoping Criteria and Object Matching Rules that use it in that Object Type's Synchronisation Rules. A built-in attribute cannot be changed, deleted or unbound either way. Get-JIMMetaverseAttributeDeletionPreview shows what a deletion would do. Values held by any Metaverse Object Values cleared none held Change type or plurality only single- to multi-valuedsame type, every value kept;anything else is refused any change Delete the attribute refusedclear the values first deleted with what uses itbindings, Attribute Flows, ScopingCriteria, Object Matching Rules Unbind froman Object Type refused, if that type's objects hold one unbound with what uses it therethat type's Attribute Flows, ScopingCriteria, Object Matching Rules A built-in attribute cannot be changed, deleted or unbound, whatever its objects hold What stored values block on a custom Metaverse Attribute While any Metaverse Object holds a value for a custom Metaverse Attribute, Set-JIMMetaverseAttribute makes one schema change, widening it from single-valued to multi-valued with its type unchanged, which keeps every value, and refuses any other change of type or plurality; Remove-JIMMetaverseAttribute refuses to delete it; and Remove-JIMMetaverseObjectTypeAttribute refuses to unbind it from an Object Type whose objects hold a value. Once the values are cleared, any change of type or plurality is made; the deletion goes ahead, removing its Object Type bindings, Attribute Flows, Scoping Criteria and Object Matching Rules; and unbinding removes the Attribute Flows, Scoping Criteria and Object Matching Rules that use it in that Object Type's Synchronisation Rules. A built-in attribute cannot be changed, deleted or unbound either way. Get-JIMMetaverseAttributeDeletionPreview shows what a deletion would do. Values held by any Metaverse Object Change type or pluralityonly single- to multi-valuedsame type, every value kept; anything else is refused Delete the attributerefusedclear the values first Unbind from an Object Typerefused, if that type's objects hold one Values cleared none held Change type or pluralityany change Delete the attributedeleted with what uses itbindings, Attribute Flows, ScopingCriteria, Object Matching Rules Unbind from an Object Typeunbound with what uses it therethat type's Attribute Flows, ScopingCriteria, Object Matching Rules A built-in attribute cannot be changed, deleted or unbound, whatever its objects hold

Get-JIMMetaverseAttribute

Gets Metaverse Attributes: one page of them by default, or one by ID or name.

Syntax

# List (default)
Get-JIMMetaverseAttribute [-Page <int>] [-PageSize <int>]

# ById
Get-JIMMetaverseAttribute -Id <int>

# ByName
Get-JIMMetaverseAttribute -Name <string>

Parameters

Name Type Required Default Description
Id int Yes (ById) The ID of the attribute to get. Accepts pipeline input by property name.
Name string Yes (ByName) The name of the attribute to get, matched exactly but ignoring case.
Page int No (List) 1 The page of attributes to return, counting from 1. At least 1.
PageSize int No (List) 100 How many attributes each page holds. From 1 to 1,000.

Output

By default, one page of attributes, each in summary with the Object Types it is bound to. With -Id or -Name, the attribute in full, with its rendering hint and Standard Mappings.

By default:

Property Type Description
Id int The unique identifier of the attribute.
Created datetime When the attribute was created (UTC).
Name string The attribute's name.
Type string The kind of value the attribute holds. One of NotSet, Text, Number, DateTime, Binary, Reference, Guid, Boolean, LongNumber or Decimal.
AttributePlurality string Whether the attribute holds one value or many. One of SingleValued or MultiValued.
BuiltIn bool Whether JIM provides the attribute. A built-in attribute cannot be changed or deleted.
MetaverseObjectTypes object[] The Object Types the attribute is bound to, each as a Key (the Object Type's ID) and a Value (its name). Each has Key and Value.

With -Id or -Name:

Property Type Description
Id int The unique identifier of the attribute.
Name string The attribute's name.
Created datetime When the attribute was created (UTC).
Type string The kind of value the attribute holds. One of NotSet, Text, Number, DateTime, Binary, Reference, Guid, Boolean, LongNumber or Decimal.
AttributePlurality string Whether the attribute holds one value or many. One of SingleValued or MultiValued.
BuiltIn bool Whether JIM provides the attribute. A built-in attribute cannot be changed or deleted.
RenderingHint string How the portal shows a multi-valued attribute's values. Ignored for a single-valued attribute. One of Default, Table, ChipSet or List.
ObjectTypes object[] The Object Types the attribute is bound to. Each has Id and Name.
StandardMappings object[] The attribute's counterparts in other standards, such as SCIM 2.0 and LDAP. They are guidance only; synchronisation never uses them. Each has Standard, CounterpartName and Notes.

Examples

List attributes
Get-JIMMetaverseAttribute
Get a specific attribute by name
Get-JIMMetaverseAttribute -Name "Display Name"
Page through attributes
Get-JIMMetaverseAttribute -Page 1 -PageSize 50

New-JIMMetaverseAttribute

Creates a custom Metaverse Attribute, optionally bound to Metaverse Object Types.

Syntax

New-JIMMetaverseAttribute -Name <string> -Type <string> [-AttributePlurality <string>] [-ObjectTypeIds <int[]>] [-ChangeReason <string>] [-WhatIf] [-Confirm]

Parameters

Name Type Required Default Description
Name string Yes The name of the new attribute. It must be unique, ignoring case.
Type string Yes The kind of value the attribute holds. Integer is the type JIM names Number. One of Text, Integer, LongNumber, Decimal, DateTime, Boolean, Reference, Guid or Binary.
AttributePlurality string No 'SingleValued' Whether the attribute holds one value or many. A Boolean holds one value, so JIM refuses MultiValued for a Boolean. One of SingleValued or MultiValued.
ObjectTypeIds int[] No The IDs of the Metaverse Object Types to bind the attribute to. It can also be bound later, with Add-JIMMetaverseObjectTypeAttribute.
ChangeReason string No An optional reason for the change, recorded in the attribute's Configuration Change History.

Output

The created attribute in full.

Properties as under Get-JIMMetaverseAttribute.

Examples

Create a simple text attribute
New-JIMMetaverseAttribute -Name "Cost Centre" -Type Text
Create a multi-valued reference attribute
New-JIMMetaverseAttribute -Name "Direct Reports" -Type Reference -AttributePlurality MultiValued
Create an attribute bound to two Object Types
$userType = Get-JIMMetaverseObjectType -Name "User"
$groupType = Get-JIMMetaverseObjectType -Name "Group"
New-JIMMetaverseAttribute -Name "Department" -Type Text -ObjectTypeIds @($userType.Id, $groupType.Id)

Set-JIMMetaverseAttribute

Changes a custom Metaverse Attribute: its name, rendering hint, Standard Mappings, data type or plurality. A built-in attribute cannot be changed.

Syntax

# ById (default)
Set-JIMMetaverseAttribute -Id <int> [-Name <string>] [-RenderingHint <string>] [-Type <string>] [-AttributePlurality <string>] [-StandardMappings <Array>] [-ChangeReason <string>] [-PassThru] [-WhatIf] [-Confirm]

# ByInputObject
Set-JIMMetaverseAttribute -InputObject <PSCustomObject> [-Name <string>] [-RenderingHint <string>] [-Type <string>] [-AttributePlurality <string>] [-StandardMappings <Array>] [-ChangeReason <string>] [-PassThru] [-WhatIf] [-Confirm]

Parameters

Name Type Required Default Description
Id int Yes (ById) The ID of the attribute to change. Accepts pipeline input by property name.
InputObject PSCustomObject Yes (ByInputObject) An attribute from the pipeline, for example from Get-JIMMetaverseAttribute. Accepts pipeline input.
Name string No A new name for the attribute. It must be unique, ignoring case.
RenderingHint string No How the portal shows a multi-valued attribute's values. Ignored for a single-valued attribute. One of Default, Table, ChipSet or List.
Type string No A new kind of value for the attribute; Integer is the type JIM names Number. JIM refuses a type change while any Metaverse Object holds a value for the attribute. A Boolean holds one value, so Boolean without -AttributePlurality also makes the attribute single-valued. One of Text, Integer, LongNumber, Decimal, DateTime, Boolean, Reference, Guid or Binary.
AttributePlurality string No Whether the attribute holds one value or many. While any Metaverse Object holds a value for the attribute, JIM allows only a change from SingleValued to MultiValued, which keeps every value; it refuses MultiValued to SingleValued, and refuses MultiValued for a Boolean. Giving the plurality the attribute already has changes nothing, so stored values never block it. One of SingleValued or MultiValued.
StandardMappings Array No The attribute's Standard Mappings, replacing any it has; @() clears them. Each is a hashtable with a Standard (Scim, Ldap or Jim), a CounterpartName (the attribute's name in that standard) and optional Notes. Standard Mappings are guidance only and never affect synchronisation.
ChangeReason string No An optional reason for the change, recorded in the attribute's Configuration Change History.
PassThru switch No Returns the updated attribute.

Output

With -PassThru, the updated attribute in full; otherwise nothing.

Properties as under Get-JIMMetaverseAttribute.

While any Metaverse Object holds a value for the attribute, the one schema change JIM makes is widening it from single-valued to multi-valued with its type unchanged, which keeps every value. It refuses any other change of -Type or -AttributePlurality until the values are cleared, and the cmdlet reports the refusal as an error. Giving the type and plurality the attribute already has is no change: it always succeeds, and nothing is recorded in the attribute's change history. Giving either parameter sends both, the other as the attribute has it now, except that -Type Boolean alone makes the attribute single-valued, since a Boolean holds one value. To bind the attribute to an Object Type or unbind it, use Add-JIMMetaverseObjectTypeAttribute and Remove-JIMMetaverseObjectTypeAttribute.

Examples

Rename an attribute
Set-JIMMetaverseAttribute -Id 42 -Name "costCentreCode" -PassThru
Set the rendering hint for a multi-valued attribute
Get-JIMMetaverseAttribute -Name "proxyAddresses" | Set-JIMMetaverseAttribute -RenderingHint List
Change an attribute's data type (refused if any object holds a value)
Set-JIMMetaverseAttribute -Id 42 -Type Integer
Widen a single-valued attribute to multi-valued, keeping its values
Set-JIMMetaverseAttribute -Id 42 -AttributePlurality MultiValued -ChangeReason "The directory now holds several values"
Record how a custom attribute corresponds to the SCIM 2.0 and LDAP standards
Set-JIMMetaverseAttribute -Id 42 -StandardMappings @(
    @{ Standard = 'Scim'; CounterpartName = 'costCenter'; Notes = 'SCIM Enterprise User extension.' },
    @{ Standard = 'Ldap'; CounterpartName = 'costCentre' }
)

Remove-JIMMetaverseAttribute

Deletes a custom Metaverse Attribute. A built-in attribute cannot be deleted.

Syntax

# ById (default)
Remove-JIMMetaverseAttribute -Id <int> [-ChangeReason <string>] [-Force] [-WhatIf] [-Confirm]

# ByInputObject
Remove-JIMMetaverseAttribute -InputObject <PSCustomObject> [-ChangeReason <string>] [-Force] [-WhatIf] [-Confirm]

It asks for confirmation before it acts: -WhatIf shows what it would do, and -Force or -Confirm:$false skips the prompt.

Parameters

Name Type Required Default Description
Id int Yes (ById) The ID of the attribute to delete. Accepts pipeline input by property name.
InputObject PSCustomObject Yes (ByInputObject) An attribute from the pipeline, for example from Get-JIMMetaverseAttribute. Accepts pipeline input.
ChangeReason string No An optional reason for the deletion, recorded in the attribute's Configuration Change History.
Force switch No Suppresses the confirmation prompt. The cmdlet still gives the name confirmation JIM requires before it removes configuration that uses the attribute.

Output

None.

JIM refuses the deletion while any Metaverse Object holds a value for the attribute; clear the values first. Otherwise the configuration that uses the attribute (its Object Type bindings, Attribute Flows, Scoping Criteria and Object Matching Rules) is removed with it, and each removal is recorded as an Activity. JIM asks for the attribute's name to confirm a deletion that removes configuration; the cmdlet gives it once you confirm, or with -Force. To see what a deletion would remove, use Get-JIMMetaverseAttributeDeletionPreview first.

Examples

Delete an attribute by ID
Remove-JIMMetaverseAttribute -Id 42
Delete an attribute without confirmation
Remove-JIMMetaverseAttribute -Id 42 -Force
Delete via pipeline
Get-JIMMetaverseAttribute -Name "legacyCode" | Remove-JIMMetaverseAttribute -Force

Test-JIMMetaverseAttributeName

Checks whether a name is free for a Metaverse Attribute. The check ignores case, so CostCentre is taken if costCentre exists.

Syntax

Test-JIMMetaverseAttributeName -Name <string> [-ExcludeId <int>]

Parameters

Name Type Required Default Description
Name string Yes The attribute name to test.
ExcludeId int No The ID of an attribute to leave out of the check. Pass the attribute's own ID when renaming it, so its current name does not count as taken.

Output

$true when the name is free, or $false when an attribute already has it.

Returns a bool.

Examples

Guard a create call with an availability check
if (Test-JIMMetaverseAttributeName -Name "costCentre") {
    New-JIMMetaverseAttribute -Name "costCentre" -Type Text
}
Check availability while renaming attribute 42
Test-JIMMetaverseAttributeName -Name "costCentre" -ExcludeId 42

Get-JIMMetaverseAttributeDeletionPreview

Shows what deleting a custom Metaverse Attribute would do, without deleting it: whether stored values block it, which Object Types hold them, and the configuration that would be removed with it. Remove-JIMMetaverseAttribute makes the same assessment before it deletes.

Syntax

# ById (default)
Get-JIMMetaverseAttributeDeletionPreview -Id <int>

# ByInputObject
Get-JIMMetaverseAttributeDeletionPreview -InputObject <PSCustomObject>

Parameters

Name Type Required Default Description
Id int Yes (ById) The ID of the attribute to assess. Accepts pipeline input by property name.
InputObject PSCustomObject Yes (ByInputObject) An attribute from the pipeline, for example from Get-JIMMetaverseAttribute. Accepts pipeline input.

Output

What deleting the attribute would do: whether stored values block it, how many Metaverse Objects of each Object Type hold one, and the configuration that would be removed with it.

Property Type Description
AttributeId int The unique identifier of the attribute.
AttributeName string The attribute's name.
BuiltIn bool True if the attribute is built-in. Built-in attributes can never be deleted.
TotalObjectsWithValues int The total number of Metaverse Objects (across all types) that hold a stored value for the attribute.
ObjectTypeValueCounts object[] The per-Object-Type breakdown of Metaverse Objects holding a stored value for the attribute. Each has MetaverseObjectTypeId, MetaverseObjectTypeName, MetaverseObjectTypePluralName and ObjectCount.
References object[] The configuration references (bindings, and Attribute Flows and Object Matching Rules that map the attribute directly) that would be cascade-removed, in dependency order, when the deletion proceeds. Empty when the attribute is unreferenced. Each has Kind, Id, Description, SyncRuleId, SyncRuleName, MetaverseObjectTypeId and MetaverseObjectTypeName.
Readers object[] The configuration that reads the attribute: Scoping Criteria comparing it or reading it in an Expression, and Expressions in Attribute Flows, Object Matching Rules and Example Data Templates. Any reader refuses the deletion; change or remove each one first. These are never removed for you, because a Scoping Criterion removed from under a Synchronisation Rule changes which objects it manages. Each has Kind, ItemId, ViaExpression, Expression, SyncRuleId, SyncRuleName, ExampleDataTemplateId, ExampleDataTemplateName and Description.
Deleted bool Whether the attribute was deleted: always false in a preview, and false when the deletion was refused.
BlockedByValues bool Whether stored values block the deletion. Clear them before deleting the attribute.
BlockedByReaders bool Whether configuration reads the attribute (see Readers), which refuses the deletion.
RequiresConfirmation bool Whether deleting would also remove configuration that uses the attribute, so JIM asks for the attribute's name to confirm it.

Examples

Preview the impact of deleting an attribute
Get-JIMMetaverseAttribute -Name "costCentre" | Get-JIMMetaverseAttributeDeletionPreview

Add-JIMMetaverseObjectTypeAttribute

Binds a custom Metaverse Attribute to a Metaverse Object Type, so that type's Metaverse Objects can hold it. Binding an attribute that is already bound does nothing. A built-in attribute's bindings cannot be changed.

Syntax

Add-JIMMetaverseObjectTypeAttribute -AttributeId <int> -ObjectTypeId <int> [-ChangeReason <string>] [-PassThru] [-WhatIf] [-Confirm]

Parameters

Name Type Required Default Description
AttributeId int Yes The ID of the attribute to bind. Accepts pipeline input by property name, AttributeId or Id.
ObjectTypeId int Yes The ID of the Metaverse Object Type to bind it to.
ChangeReason string No An optional reason for the change, recorded in the attribute's Configuration Change History.
PassThru switch No Returns the updated attribute.

Output

With -PassThru, the updated attribute in full; otherwise nothing.

Properties as under Get-JIMMetaverseAttribute.

Examples

Bind an attribute to an Object Type
Add-JIMMetaverseObjectTypeAttribute -AttributeId 42 -ObjectTypeId 1
Bind an attribute from the pipeline and return it
Get-JIMMetaverseAttribute -Name "costCentre" | Add-JIMMetaverseObjectTypeAttribute -ObjectTypeId 1 -PassThru

Remove-JIMMetaverseObjectTypeAttribute

Unbinds a custom Metaverse Attribute from a Metaverse Object Type. A built-in attribute cannot be unbound.

Syntax

Remove-JIMMetaverseObjectTypeAttribute -AttributeId <int> -ObjectTypeId <int> [-ChangeReason <string>] [-Force] [-WhatIf] [-Confirm]

It asks for confirmation before it acts: -WhatIf shows what it would do, and -Force or -Confirm:$false skips the prompt.

Parameters

Name Type Required Default Description
AttributeId int Yes The ID of the attribute to unbind. Accepts pipeline input by property name, AttributeId or Id.
ObjectTypeId int Yes The ID of the Metaverse Object Type to unbind it from.
ChangeReason string No An optional reason for the change, recorded in the attribute's Configuration Change History.
Force switch No Suppresses the confirmation prompt. The cmdlet still gives the name confirmation JIM requires before it removes configuration that uses the attribute on that Object Type.

Output

None.

JIM refuses while any Metaverse Object of that type holds a value for the attribute. Otherwise it removes the binding, with the Attribute Flows, Scoping Criteria and Object Matching Rules that use the attribute in Synchronisation Rules for that Object Type; JIM asks for the attribute's name to confirm, and the cmdlet gives it once you confirm, or with -Force. If the attribute is not bound to the Object Type, the cmdlet says so and changes nothing.

Examples

Unbind an attribute from an Object Type
Remove-JIMMetaverseObjectTypeAttribute -AttributeId 42 -ObjectTypeId 1
Unbind without a prompt
Remove-JIMMetaverseObjectTypeAttribute -AttributeId 42 -ObjectTypeId 1 -Force

Get-JIMMetaverseAttributePriority

Gets a Metaverse Attribute's priority order on one Metaverse Object Type: the Attribute Flows that contribute its value, highest priority first. How the order decides which value wins, and what Null is a value changes, are explained in Attribute Priority. An Attribute Flow whose Synchronisation Rule is disabled keeps its place but never contributes.

Syntax

Get-JIMMetaverseAttributePriority -AttributeId <int> -ObjectTypeId <int>

Parameters

Name Type Required Default Description
AttributeId int Yes The ID of the Metaverse Attribute. Accepts pipeline input by property name.
ObjectTypeId int Yes The ID of the Metaverse Object Type the priority order applies to. Accepts pipeline input by property name.

Output

The attribute's priority order on that Object Type: each contributing Attribute Flow, highest priority first.

Property Type Description
MetaverseObjectTypeId int The unique identifier of the Object Type the order applies to.
MetaverseAttributeId int The unique identifier of the attribute.
MetaverseAttributeName string The attribute's name; empty when nothing contributes to it.
Contributors object[] The Attribute Flows that contribute a value to the attribute, highest priority first; empty when none does. Each has MappingId, Priority, NullIsValue, SyncRuleId, SyncRuleName, SyncRuleEnabled, ConnectedSystemId and ConnectedSystemName.

Examples

Get the priority order for an attribute
Get-JIMMetaverseAttributePriority -AttributeId 12 -ObjectTypeId 1
List just the contributing Attribute Flows, in priority order
(Get-JIMMetaverseAttributePriority -AttributeId 12 -ObjectTypeId 1).Contributors

Set-JIMMetaverseAttributePriority

Replaces a Metaverse Attribute's whole priority order on one Metaverse Object Type. List every contributing Attribute Flow once, highest priority first; an Attribute Flow whose Synchronisation Rule is still being deleted may be left out, and stays at the bottom. JIM refuses an order that misses a contributor or names a mapping that is not one, and says which. To move a single Attribute Flow, use Move-JIMMetaverseAttributePriority.

Syntax

Set-JIMMetaverseAttributePriority -AttributeId <int> -ObjectTypeId <int> -MappingId <int[]> [-NullIsValueMappingId <int[]>] [-PassThru] [-WhatIf] [-Confirm]

Parameters

Name Type Required Default Description
AttributeId int Yes The ID of the Metaverse Attribute.
ObjectTypeId int Yes The ID of the Metaverse Object Type the priority order applies to.
MappingId int[] Yes Every contributing Attribute Flow mapping ID, once each, highest priority first. A mapping whose Synchronisation Rule is being deleted may be left out; it stays at the bottom.
NullIsValueMappingId int[] No The mapping IDs, from -MappingId, whose "Null is a value" flag is set, so that source can assert the attribute has no value rather than defer to the next source. Every other mapping has the flag cleared.
PassThru switch No Returns the resulting priority order.

Output

With -PassThru, the resulting priority order; otherwise nothing.

Properties as under Get-JIMMetaverseAttributePriority.

Examples

Set the full priority order
Set-JIMMetaverseAttributePriority -AttributeId 12 -ObjectTypeId 1 -MappingId 45, 12, 78
Set the order, and let the top source assert that there is no value
Set-JIMMetaverseAttributePriority -AttributeId 12 -ObjectTypeId 1 -MappingId 45, 12 -NullIsValueMappingId 45 -PassThru

Move-JIMMetaverseAttributePriority

Moves one Attribute Flow to a new position in a Metaverse Attribute's priority order, renumbering the others so the order stays without gaps.

Syntax

Move-JIMMetaverseAttributePriority -AttributeId <int> -ObjectTypeId <int> -MappingId <int> -Position <int> [-NullIsValue] [-PassThru] [-WhatIf] [-Confirm]

Parameters

Name Type Required Default Description
AttributeId int Yes The ID of the Metaverse Attribute.
ObjectTypeId int Yes The ID of the Metaverse Object Type the priority order applies to.
MappingId int Yes The ID of the contributing Attribute Flow mapping to move. Accepts pipeline input by property name.
Position int Yes The position to move it to, counting from 1 for the highest priority.
NullIsValue switch No Sets the moved mapping's "Null is a value" flag; -NullIsValue:$false clears it. Omit it to leave the flag as it is.
PassThru switch No Returns the resulting priority order.

Output

With -PassThru, the resulting priority order; otherwise nothing.

Properties as under Get-JIMMetaverseAttributePriority.

Examples

Move an Attribute Flow to the highest priority
Move-JIMMetaverseAttributePriority -AttributeId 12 -ObjectTypeId 1 -MappingId 78 -Position 1

See also