Virtual Data Transformations

Virtual
data transformations create a virtual data view from a physical data view.
Practically, you never define a virtual data view. Instead, you specify the
transformations that you require and define these on an existing physical
data view. A transformation performs a specific action in
a certain direction. The direction of a transformation
determines the transformation model. When you define a virtual data transformation,
you create a virtual attribute that exists only in the context of the virtual
data view.

A transformation is defined on a data view, by using the dpconf command
as follows:

The view-name refers to the data view on
which the transformation is defined. The attr-name refers
to the virtual attribute that is created. The model, action, and additional
parameters are described in the following sections.

The name of the virtual transformation can be set by using the following
command:

Transformation Models

The transformation model is determined by the direction of a transformation,
in other words, whether the transformation is applied during the request,
during the response, or both.

In this sense, transformations can be categorized into the following
types:

Mapping transformations (bidirectional transformations)

Write transformations (inbound transformations)

Read transformations (outbound transformations)

Mapping Transformations

The
most common transformation is a bidirectional (mapping) transformation. A
mapping transformation is applied during the request, and its inverse is applied
during the response. These transformations are called mappings because
in effect, an attribute or entry in the physical data view maps to an attribute
or entry in the virtual data view. Mapping transformations enable you to process
existing values before assigning them to a DN component, an attribute type
or value, or an object class.

The following diagram illustrates the principals of a mapping transformation.

Figure 18–2 Mapping Transformation

A mapping transformation is defined on a data view, by running the dpconf command as follows:

Example 18–1 When Would You Use a Mapping Transformation?

Imagine, for example, an organization has a physical data source that
contains entries with the attributes surname and givename. The organization has a client application that requires entries
to have a cn (common name) attribute of the form givenname
surname.

The client application sends a search request for an entry of the form cn=Carlos Fuentes. A transformation is defined that extracts the
name and surname during this request and transforms the request to one of
the form surname=Fuentes, givenname=Carlos. The corresponding
entry is located in the data source. Before returning this entry to the client
application, the inverse transformation is performed. The client application
receives the entry as cn=Carlos Fuentes, which it understands.

This request is transformed to be of the form surname=Fuentes,
givenname=Carlos. Similarly, the client application sends a modify
request to change the cn attribute of an entry to Lisa
Davis. The request is transformed so that the givenname attribute
of the physical entry is modified to Lisa and the surname attribute is modified to Davis.

Write Transformations

A write
transformation is applied during the request, but not during the response.
A write transformation changes the physical data in storage.

The following diagram illustrates the principals of a write transformation.

Figure 18–3 Write Transformation

A write transformation is defined on a data view, by using the dpconf command as follows:

Example 18–2 When Would You Use a Write Transformation

Imagine an organization has a legacy application whose function is to
add person entries to a data source. The application adds the entries without
the telephoneNumber attribute. The physical data source
has been upgraded and the telephoneNumber is now a mandatory
attribute for person entries. The transformation required here is to add the telephoneNumber attribute during the add request. This transformation
changes the entry that is written to the database. No reverse transformation
is required.

Read Transformations

A read
transformation is applied only during the response to a request. No transformation
is applied during the request and the physical data is not changed.

The following diagram illustrates the principals of a read transformation.

Figure 18–4 Read Transformation

A read transformation is defined on a data view, by using the dpconf command as follows:

Example 18–3 When Would You Use a Read Transformation

Imagine an organization has a legacy application whose function is to
display person entries. The application does not support entries that do not
contain a mail attribute. The physical data source has
been upgraded and the email attribute no longer exists
for person entries (e-mail addresses are constructed using other attributes).

The transformation required here is to add the mail attribute
during the search response. This transformation changes the entry that is
read from the database and adds a mail attribute whose
value is givenname.surname@example.com. No reverse transformation is required and the physical data is
not changed.

Note that with the above transformation, the mail attribute
makes no sense in a search request filter. Search request filters must contain
physical attributes.

Transformation Actions

Transformation actions describe what a transformation does to
its target entry or entries. The following transformation actions are possible:

Construct an attribute. This
action enables you to construct a virtual attribute that does not actually
exist in the physical data source but is required by a client application.
The action can also be used to alter an add or modify request to construct
an attribute that is required by the physical data source.

To
construct the attribute, use the add-attr transformation
action.

Remove an attribute. This
action enables you to delete an attribute from a client request if that attribute
is not permitted by the schema on the physical data source. The action can
also be used to remove an attribute from the response sent to a client application
if the client application does not require that attribute.

To
remove an attribute, use the remove-attr transformation
action.

Construct an attribute value. This
action enables you to create an attribute value from other attribute values.

To create an attribute value, use the add-attr-value transformation
action.

Delete an attribute value. This
action enables you to remove the value from an attribute. It is usually used
to remove one or more values from a multi-valued attribute if either the client
application or the data source schema does not permit multi-valued attributes.

To remove an attribute value, use the remove-attr-value transformation
action.

Add a default value to an attribute. This
action enables you to add a default value to an attribute, if no value exists.

To add a default value to an attribute, use the def-value transformation
action.

Map one attribute value to another. This
action enables you to have two different values for an attribute, depending
on whether the attribute is being written to a data source or returned to
a client application.

To map attribute values, use the attr-value-mapping transformation action, with the internal-value and view-value parameters.

The results of a transformation action depend on the transformation
model.

Transformation Parameters

Transformation parameters provide the value of a virtual attribute.
This value can either be a default value, or rule that creates the value from
other attribute values.

The following transformation parameters are accepted:

value. This parameter is applied
to all transformation actions that add an attribute value, other than the attr-value-mapping action.

internal-value:value. This parameter
applies only to the attr-value-mapping action, and to the remove-attr-value action when used with the mapping model.
It describes the value of the attribute that is written to or read from the
physical data source.

view-value:value. This parameter
applies only to the attr-value-mapping action, and to the remove-attr-value action when used with the mapping model.
It describes the value of the attribute that is returned to or sent by the
client application.

Transformation parameters take the following syntaxes:

Constant. Used to generate
an attribute with a static default value.

For example, the parameter 0800–5994654 might be used to provide a default telephone
number.

Attribute value. Used to
create a new attribute from an existing attribute in the entry that is being
processed.

For example, the parameter \${cn} specifies
that the value of the new attribute must be taken from the value of the cn attribute The escape character is required before the $.

Constant and attribute value. Used
to create a new attribute by combining an existing attribute and a static
value.

For example, the parameter \${cn}@example.com specifies
that the value of the new attribute must be taken from the value of the cn attribute and a static domain name.

Macro. Used to create an
attribute by manipulating the value of an existing attribute.

Transformation Examples

The following sections provide use cases in which virtual data
views are required, and the combination of transformation models and actions
required to implement the use cases.

Example 18–4 Adapting an ADAM Object Class For
LDAP Compliance

An organization, Example A, stores its users in an LDAP directory. Example
A acquires another company, Example B, which stores its users in an ADAM directory.

In Example A's LDAP directory, a user is stored as an inetOrgPerson. In Example B's directory, a user is stored as a user.
A transformation is required that maps the ADAM user object
class to the LDAP inetOrgPerson object class.

The following transformation is defined on the physical data view of
Example A's directory:

Example 18–5 Constructing an Attribute With a Write
Transformation

Example A stores user entries in its directory. All user entries require
a mail attribute. If user entries without a mail attribute
are added, a schema violation error is returned. Example A has a client application
that adds user entries to the directory. Some user entries do not contain
a mail attribute and the client application is incapable of generating one.
To avoid schema violations when a user entry is added, a transformation is
defined that adds the mail attribute to an add request. The value of the mail attribute is taken from the uid provided
in the client add request, with the addition of @example.com.

The following diagram indicates the transformation that occurs on an
add request.

This transformation is defined on the physical data view by using the
following dpconf command.

In this command, \${uid} means the value of the uid attribute for that entry.

Example 18–6 Constructing an Attribute With a Read
Transformation

Example A does not store the mail addresses of its users in its directory.
However, a new client application requires that a user's mail address be returned
with the user entry.

All mail addresses in the organization take the form firstname.lastname@example.com.
The organization defines a virtual view in which the mail attribute is added
to each user entry for reads only. The value of the mail attribute is generated
by taking the value of the givenName and sn attributes
that already exist in the user entry.

The following diagram indicates the transformation that occurs on user
entries when they are returned in a search.

This transformation is defined on the physical data view by using the
following dpconf command.

Example 18–7 Adding a Default Attribute Value

Example A stores a number of products in its directory. In the past,
each product was associated with a support person, an employee responsible
for handling all support calls for that product. In the physical data store,
each product is therefore associated with a supportPerson attribute,
whose value is the DN of an employee in the organization.

The organization has changed its business process for support queries
and now sends all product queries to a central hotline. To handle this change
without changing the physical data, the organization defines a virtual data
view where all product entries do not have a supportPerson attribute,
but have a hotline attribute instead. The value of the hotline attribute is an 0800 number that is the same for all products.

The following diagram indicates the transformation that occurs on product
entries when they are returned in a search.

This transformation is defined on the physical data view by using the
following dpconf commands:

Example 18–8 Using a Virtual Transformation to Rename
a DN

Example A has a client application that needs to sort entries according
to their object class.

To do this, Example A defines a virtual transformation that rewrites
the RDN of entries to include the object class of the entry along with its cn, whenever an entry is returned to that specific client application.

The following transformation is defined on the physical data view of
Example A's directory: