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();

All calls additionally provide access to an IQueryable set of entities from UNIFYBroker's previously known state:

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

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.