Internal data model: Entries, Attributes and Values

When Security Directory Integrator components access information from connected systems, they convert the data from system-specific types to an internal representation using Java objects. On output, components convert the other way, going from this internal data model to the native types of the target system. This same internal representation is used when we wish to pass data to and from AssemblyLines. It is therefore vital that you understand how the IBM Security Directory Integrator internal data model works. Looking in detail at when a data value is received by a component, a corresponding IBM Security Directory Integrator Attribute object is created using the name of the attribute being read. The data value itself (or values, if it is a multi-valued attribute) are converted to appropriate Java objects—like Java.lang.String or java.sql.Timestamp —and assigned to the Attribute. If you take a look in the IBM Security Directory Integrator API documentation, you will see that the Attribute object provides a number of useful methods, like getValue(), addValue() and size(). This allows you to create, enumerate and manipulate the values of an Attribute directly from script. We can also instantiate new Attribute objects as needed, as shown in this Attribute Map example for advanced mapping the objectClass attribute of a directory:

var oc = system.newAttribute( "objectClass" );
 
oc.addValue( "top" );
oc.addValue( "person" );
oc.addValue( "organizationalPerson" );
oc.addValue( "inetOrgPerson" );
 
ret.value = oc;

Attributes themselves are collected in a data storage object called an entry object. The entry is the primary data carrier object in the system and IBM Security Directory Integrator gives you access to important entry objects by registering them as script variables. A prime example is the Work entry object in the AssemblyLine, used to pass data between AL components (as well as between AssemblyLines). This entry object is local to each AssemblyLine and available as the script variable work. IBM Security Directory Integrator provides some shortcuts and convenience features when working in JavaScript, so the above specific advanced mapping can be simply coded as follows:

ret.value = [ "top", "person", "organizationalPerson", "inetOrgPerson" ];

The advanced mapping feature supports JavaScript arrays and Entries for passing multiple attribute values. For example, in an Input Attribute Map (which causes mapped Attributes to show up in the work Entry on return), suppose you have the assignment

ret.val = anentry;

for the Attribute called "last". Let us further assume that work is empty to start with, and anentry contains the Attributes "cn", "sn" and "mail". After attribute mapping work will contain "cn", "sn" and "mail" attributtes, not a single Attribute called "last" with "anentry" as value. In essence, what happens in Attribute mapping is that when an attribute map returns an Entry object, it is merged with the receiving Entry – either work or conn, depending on what map it is (Input or Output).¹ Looking at the Javadocs, you will see that the entry object offers various functions for working with Entries and their Attributes and values, including getAttributeNames(), getAttribute() and setAttribute(). If you wanted to create and add an Attribute to the AssemblyLine Work entry, you could use the following script, for example, in a Hook or a Script Component:

var oc = system.newAttribute( "objectClass" );
 	
oc.addValue( "top" );
oc.addValue( "organizationalUnit" )
 
work.setAttribute( oc );

Note that in this case we do not have the option of using a JavaScript array to set the value:

oc.addValue( ["top", "organizationalUnit"] ); // Does not work like Advanced Mapping

This code will result in the oc attribute getting a single value, which in turn is an array of strings.

Entry objects can also contain properties. Properties are data containers like Attributes, except that they are only single-valued. While Attributes are used to store data content, properties hold parametric information, allowing you to keep this information separated. Properties do not show up for attribute map selection or in the Work entry list, but can be accessed much like Attributes from script. entry functions like getProperty() and setProperty() are used for this, and these work directly with Property values, which can be any type of Java object, just like Attribute values. There is no intermediate Property object as there is when you work with Attributes.

In many cases, we can restrict the data model to an entry containing zero or more Attributes, each with zero or more values—a flat schema.

This is one of the strengths of IBM Security Directory Integrator: simplifying and harmonizing data representations and schema. It also represents a challenge when you need to handle information with a more complex structure. However, since an Attribute value can be any type of Java object, including another entry object (with its own Attributes and values), IBM Security Directory Integrator allows you to work with hierarchically structured data.

This more elaborate and structured way of handling hierarchical objects is described in Working with hierarchical Entry objects.

• Working with hierarchical Entry objects
  An alternative way of working with hierarchically structured data is to take advantage of the support for hierarchical objects in the IBM Security Directory Integrator entry object.

Parent topic:

Scripting in SDI

¹ In IBM Security Directory Integrator v7.2, taking advantage of hierarchical objects, we can circumvent this behavior by first encapsulating an Entry in an Attribute before Attribute Mapping takes place. For example,

// this is the entry to return
e = system.newEntry();
e.setAttribute("some", "value");

// Create an Attribute object. We don't need to provide a name since the mapping will use current map's name.
attr = system.newAttribute(null);

// add the entry to the Attribute object and return that instead of the Entry object
attr.addValue(e);

return attr;

If this was entered as the Advanced Attribute Map for the "last" Attribute, then after Attribute Mapping, the work Entry will now contain an Attribute called "last". This Attribute is an Entry, in turn comprised of two attributes called "some" and "value".