PowerShell Connector Entities

Overview

An entity is a generic representation of an object in the target system being described by the connector. For instance - in a database containing students - an entity may describe a single student.

Each entity has a series of values which are described by the schema of the connector. These values should represent the corresponding data in target system.

Implementation

Entities may either be provided (exports), or need to be created (imports). The way entities are handled is specific to the particular operation being run, so refer to the particular operation documentation.

However, generically, export operations provide a series of entities in:

$components.InputEntities

which can be iterated to export the pending exports:

ForEach ($entity in $components.InputEntities) {
  # Add / Update / Delete the entity corresponding to the $entity.
}

And generically, Imports require entities to be committed, which can be achieved by creating entities, populating them with data and committing them:

$entity = $entities.Create(); $entity['Field'] = 'Value'; $entity.Commit();

Entity Object

The entity object is a dictionary (containing a set of name-value pairs). Values can be inserted into the entity through the indexer:

$entity['name'] = 'value';

And correspondingly, values can be accessed through the indexer:

$value = $entity['name']; # IValue wrapper object 
$value = $entity['name'].Value; # Raw value

Values inserted into an entity may be of any type, and depending on the type of the field, the entity will attempt to convert the value provided.

e.g.

$entity['Number'] = 1;
$entity['Number'] = '1';
$entity['Number'] = $true;

However, when a value is returned by the entity, it is of a particular implementation of the IValue interface, including:

• StringValue
• IntegerValue
• BooleanValue
• DateValue
• MultiValue<StringValue>
• etc.

Each of these IValue implementations have a corresponding 'Value' property which exposes the underlying system value. The below example describes how to access the raw system values of single- and multi-valued attributes, where single-value-key is a string-typed attribute and multi-value is a multi-valued integer-type

foreach ($entity in $components.InputEntities) {
  $key = $entity['single-value-key'].Value; # Raw .Net string
  $values = $entity['multi-value'].Value; # List of IntegerValue
  $count = 0; $values | % { $count += $_.Value } # Sums raw .Net integer values into $count
}

Schema

The accepted values of an entity are defined by the schema of the connector. For more information on how to configure a schema see PowerShell Connector Schema and Entity Schema.

Method Reference

All calls provide access to ContextEntities, which allows interaction with entities from UNIFYConnect's previously stored state using a variety of methods:

GetEntitiesOrderedAscending

IEnumerable<IEntity> GetEntitiesOrderedAscending(string schemaFieldName)

Retrieves existing connector context entities ordered ascending by a certain field.

ForEach ($entity in $components.ContextEntities.GetEntitiesOrderedAscending("name")) {
  # Do something with the $entity
}

GetEntitiesOrderedDescending

IEnumerable<IEntity> GetEntitiesOrderedDescending(string schemaFieldName)

Retrieves existing connector context entities ordered descending by a certain field.

ForEach ($entity in $components.ContextEntities.GetEntitiesOrderedDescending("name")) {
  # Do something with the $entity
}

GetEntitiesByFieldValues

IEnumerable<IEntity> GetEntitiesByFieldValues(string schemaFieldName, IEnumerable<IValue> values)

Retrieves existing connector context entities where the given field's value equals any of the given values. The values are of type IValue.

# find context entities whose value for "Id" field equals to 1 or 2 
$values = [System.Collections.Generic.List[Unify.Framework.Value.Interfaces.IValue]]::New() 
$values.Add([Unify.Framework.Value.IntegerValue]1);
$values.Add([Unify.Framework.Value.IntegerValue]2); 
$entities = $components.ContextEntities.GetEntitiesByFieldValues("Id", $values); 
ForEach ($entity in $entities) 
{ 
    # Do something with the $entity 
}

GetEntitiesByFieldContainsAny

IEnumerable<IEntity> GetEntitiesByFieldContainsAny(string schemaFieldName, IEnumerable<IValue> values)

Gets entities whose multi-valued field values contain any of the given values. The values are of type IValue.

# find context entities whose values for "MemberOf" multi-valued field contain 1 or 2 
$values= [System.Collections.Generic.List[Unify.Framework.Value.Interfaces.IValue]]::New() 
$values.Add([Unify.Framework.Value.IntegerValue]1) 
$values.Add([Unify.Framework.Value.IntegerValue]2); 
$entities = $components.ContextEntities.GetEntitiesByFieldContainsAny("MemberOf", $values); 
ForEach ($entity in $entities) 
{ 
    # Do something with the $entity 
}

GetAllEntities

PowerShellEntityPage GetAllEntities(int skip, int take)

Retrieves all entities from the existing context, in pages. The HasMore property on the result can be used to determine if another page of entities is available for retrieval.

[bool]$hasMore = $true
[int]$pageNumber = 0
[int]$take = 100

while ($hasMore) {
    $skip = ($pageNumber * $take)
    $output = $components.GetAllEntities($skip, $take)
    foreach($Entity in $output.Entities) {
        # do something with the entity
    }        
    $hasMore = $output.HasMore
    $pageNumber++
}