Oracle Waveset 8.1.1 Deployment Guide

Preparing for Adapter Development

Some preparation is necessary before you actually start writing a custom adapter. This section describes how to prepare for adapter development, and the tasks include:

Become Familiar with Adapter Source Code

Before you can create a custom adapter, you must become familiar with the components in a resource adapter’s source code. This section describes the following components, which are common to most adapters:

Standard Java Header Information

Standard Java header information identifies the parent class of the new adapter class file you are creating, constructors, and imported files.

This header information is representative of the standard Java files (including public class declaration and class constructors). You must edit the sections of the file that list the constructors and public classes, and, if necessary, the imported files.

PrototypeXML String

The prototypeXML string in the adapter Java file is the XML definition of a resource. This string must contain the resource name and all of the resource attributes that you want to display in the Waveset user interface. The prototypeXML string also defines resource objects stored in the Waveset repository.

The following table describes the different prototypeXML information types that you use to define a resource in Waveset.

Note –

Some of these information types are specific to Active Sync-enabled adapters.

Table 10–3 prototypeXML Information Types




Defines top-level characteristics of the resource. Keywords include: 

  • syncSource: If true, then adapter must be Active Sync-enabled.

  • facets: Specifies the modes enabled for this resource.

Resource attributes

XML elements that are defined with the <ResourceAttribute> element and used by Waveset to configure the resource.

For more information, see Resource Attributes.

Account attributes

Defines the default schema map for basic user attributes. 

You use the <AccountAttribute> element to define account attributes. You map standard Waveset account attribute types differently than you map custom attributes.

For more information about mapping account attributes to resource attributes, see Map the Attributes.

Identity template

Defines how the account name for the user is built. Use the <Template> tag to define this template. Account names are typically in one of the following forms:

  • An accountId is typically used for resources with a flat namespace such as Oracle.

  • A complete distinguished name (DN) of the user in the form: cn=accountId,ou=sub-org,ou=org,o=company. Use this form for hierarchical namespaces such as directories.

    For more information, see Identity Template.

Login configuration

(Standard resource adapter only) Defines values to support pass-through authentication for the resource. Use the <LoginConfigEntry> element to define this value.

For more information about pass-through authentication, see the Resource Reference. 


(Active Sync-enabled adapters only) Designates a form object that processes data from the Active Sync-enabled adapter before the data is integrated into Waveset. A form is optional, but in most cases a form provides flexible changes in the future and can be used to transform incoming data, map data to other user attributes on other resource accounts, and cause other actions in Waveset to occur.

Resource Attributes

Only available to Administrators defining the resource.

Resource attributes define the connection information on the resource being managed. Resource attributes typically include the resource host name, resource administrator name and password, and the container information for directory-based resources. Waveset attributes such as the list of resource approvers and the number of times to retry operations on the resource are also considered resource attributes.

When writing custom adapters, you use resource attributes to define:

You can modify these values from the Waveset interface when creating a specific instance of this resource type.

Defining Resource Attributes

You use the <ResourceAttribute> element, as shown in the following example, to define resource attributes in the prototypeXML string of the adapter Java file:

<ResourceAttribute name=’"+RA_HOST+"’ type=’string’ multi=’false’\n"+
description=’&lt;b&gt;host&lt;/b&gt;&lt;br&gt;Enter the resource host name.’>\n"+

Where the description field identifies the item-level help for the RA_HOST field and must not contain the < character. In the preceding example, the < characters are replaced by &lt; and &apos;.

The following table describes the keywords you can use in <ResourceAttribute> element.

Table 10–4 <ResourceAttribute> Element Keywords




Identifies the name of the attribute. 

NOTE: The name keyword is a reserved word in views and should not be used as a Identity System User Attribute on resource schema maps.


Identifies the data type used. 


Specifies whether multiple values can be accepted for the attribute. If true, a multi-line box displays.


Identifies the item-level help for the RA_HOST field. Waveset displays help with the item being described (host in this case) in bold text. Because the HTML brackets necessary to do this (< and >) interfere with XML parsing, they are replaced by &lt; and &gt;. After the binary is translated, the description value looks like:

Description=’<b>host</b> Enter the resource host name.’


Specifies the usage of this resource attribute. Valid values are 

  • provision: Used in standard processing (default value).

  • activesync: Used in Active Sync processing for an Active Sync-enabled adapter.

The ResourceAttribute> element may also contain a ValidationPolicy element. A validation policy ensures the value a user specifies on the Resource Parameters page meets the requirements defined in a separate policy object.

The following sample causes the adapter to use the Port Policy to ensure the specified value is valid. The default Port Policy checks the value is an integer between 1 and 65536.

 <ResourceAttribute name='Port' value='123'>
      <ObjectRef type='Policy' id='#ID#PortPolicy' name='Port Policy'/>

Overwriting Resource Attributes

When you are working with resource adapters and adapter parameters, you can use one of the following strategies to overwrite resource attributes:

In the following example, the user form must override the resource attribute value for template during the creation of each user. When implementing similar code in a production environment, you would probably include more detailed logic to calculate this template value within your user form.

Example 10–1 Overwriting the Resource Attribute Value for template

<Field name=’template’>
   <Display class=’Text’>
      <Property name=’title’ value=’NDS User Template’/>
<!-- Change NDS for the name of your NDS resource -->
<!-- Template is the name of the attribute field, as viewed in the resource xml -->
<Field name=’accounts[NDS].resourceAttributes.Template’>

Required Resource Attributes

The following table describes required resource attributes that are supplied in the skeleton adapter files.

Table 10–5 Resource Attributes in Skeleton Adapter Files

Required Resource Attribute 



Resource host name. This attribute corresponds to the Host field on the Resource Parameters page. 


Port number used to communicate with the resource. This attribute corresponds to the Port field on the Resource Parameters page. 


Name of a user account that has permission to connect to the resource. The field name varies on the Resource Parameters page. 


Password for the account specified by RA_USER. This attribute corresponds to the Host field on the Resource Parameters page.

The next table describes required Active Sync-specific attributes that are defined in the ACTIVE_SYNC_STD_RES_ATTRS_XML string of the Active Sync class.

Table 10–6 Active Sync-Specific Attributes Defined in ACTIVE_SYNC_STD_RES_ATTRS_XML

Required Resource Attribute  



Waveset administrator for authorization and logging. This attribute corresponds to the Proxy Administrator field in the Waveset display. You do not define this value in the adapter Java file. Instead, an administrator enters this information when defining a specific instance of this resource type. 


Form that processes incoming attributes and maps them to view attributes. This attribute corresponds to the Input Form field. 


Specifies the number of log files to retain. 

  • If you specify 0, then a single log file is re-used.

  • If you specify -1, then log files are never discarded.


Specifies the maximum time before a log file is archived. 

  • If you specify zero, then no time-based archival occurs.

  • If the RA_MAX_ARCHIVES value is zero, then the active log is truncated and reused after this time period.


Specify seconds, minutes, hours, days, weeks, or months. Use this value with RA_MAX_AGE_LENGTH.


Logging level (0 disabled; 4 very verbose). This attribute corresponds to the Log Level field in the Waveset display. 


Absolute or relative path for the log file. This attribute corresponds to the Log File Path field in the Waveset display. 


Maximum log file size. This attribute corresponds to the Maximum Log File Size field in the Waveset display. 


Pop-up menu of the supported scheduling intervals (second, minute, hour, day, week, month). 


Number of intervals between scheduled periods (for example, 10 minutes has an interval count of 10 and an interval of minute). Not necessary for Active Sync-enabled adapters. 


Time of the day to run. For example, if you specify 13:00 and set the interval to week, the adapter runs at 1 P.M. once a week. Not necessary for Active Sync-enabled adapters. 


Date to start scheduling. Setting date to 20020601, the interval to month, and the time to 13:00 starts the adapter on June 1st and runs once a month at 1 P.M. Not necessary for Active Sync-enabled adapters.

This table describes required Active Sync-specific attributes that are defined in the ACTIVE_SYNC_EVENT_RES_ATTRS_XML string of the Active Sync class.

Table 10–7 Active Sync-Specific Attributes Defined in ACTIVE_SYNC_EVENT_RES_ATTRS_XML

Required Resource Attribute 



Name of a TaskDefinition or a rule that returns the name of a TaskDefinition to run for every record in the feed. This attribute overrides all others.


Rule that returns a list of strings of potentially matching users/accountIDs, based on the resource account attributes in the account namespace. 


Rule that confirms whether a user is a match. 


Rule that determines whether a delete detected on the resource is processed as an IAPI delete event, or as an IAPI update event. 


  • If set to true, creates unmatched accounts.

  • If false, do not create the account unless the process rule is set and the workflow it identifies determines that a create is warranted. Default is true.


Rule that determines the workflow to run when there are multiple matches using the confirmation rule on the results of the correlation rule. 


Indicates whether to populate the global namespace in addition to the activeSync namespace. Default is false.

Waveset Account Attributes

Only available to Administrators defining the resource.

Waveset account attributes describe the default user attributes supported for the resource.

With an Active Sync-enabled adapter, account attributes are the attributes that are available to update the Waveset user account. The Active Sync-enabled adapter collects these attributes and stores them in the global area for the input form.

Waveset supports the following types of account attributes:

Binary attributes include graphic files, audio files, or certificates. Not all adapters support binary account attributes. Generally, only certain directory, flat file, and database adapters can process binary attributes.

Note –

You define Waveset account attributes in the AttributeDefinition object of the resource’s schema map, and use the prototypeXML string in the adapter file to map incoming resource attributes to account attributes in Waveset. For example, you would map the LDAP sn resource attribute to the lastname attribute in Waveset. Waveset account attributes include

Standard Adapter Schema Maps

You use the Account Attributes page, or schema map, to map Waveset account attributes to resource account attributes. The list of attributes varies for each resource. You generally remove all unused attributes from the schema map page. If you add attributes, you will probably need to edit user forms or other code.

The attribute mappings specified in the resource schema map determine which account attributes can be requested when you are creating a user. Based on the role selected for a user, you will be prompted for a set of account attributes that are the union of attributes of all resources in the selected role.

Note –

To view or edit the Waveset schema for users or roles, you must be a member of the IDM Schema Configuration AdminGroup and you must have the IDM Schema Configuration capability.

Active Sync-Enabled Adapter Schema Maps

The Active Sync resource schema map is an optional utility that enables you to edit inputs to an Active Sync-enabled adapter, which are often database column names or directory attribute names. Using the schema map and an Active Sync form, you can implement Java code to handle a resource type, defining details of the resource configuration in the map and form.

Waveset uses an Active Sync resource’s schema map in the same way that it uses a typical schema map. The schema map specifies which attributes to fetch from the resource and their local names. All attribute names that are listed in the schema map (that is, all attributes that exist on the resource) are made available to the Active Sync form and the user form with the attribute. If the Active Sync resource does not use a form, all attributes are named global to ensure that all attributes automatically propagate to attributes with the same name on all resources. Use a form rather than the global namespace.

Tip –

Do not put the accountId attribute in the global namespace because this special attribute is used to identify

If you are creating the resource account for the first time, the accountId attribute also becomes a resource’s accountId directly and it bypasses the identity template.

For example, if a new Waveset user is created through the Active Sync-enabled adapter and that user has an LDAP account assigned to it, the LDAP accountID will match the global.accountId instead of the correct DN from the DN template.

Using the Schema Map

After creating a resource instance, administrators can subsequently use a schema map to:

You can view Waveset account attributes from the Edit Schema page in the Waveset user interface by clicking the Edit Schema button located at the bottom of the Edit/Create Residenource page.

For more information about creating a resource or editing a resource schema map, see the Business Administrator's Guide.

Identity Template

Note –

An identity template is only available to Administrators who are defining the resource.

To view or edit the Waveset schema for Users or Roles, you must be a member of the IDM Schema Configuration AdminGroup and you must have the IDM Schema Configuration capability.

You use the identity template (or account DN) to define a user’s default account name syntax when creating the account on the resource. The identity template translates the Waveset user account information to account information on the external resource.

You can use any schema map attribute (an attribute listed on the left side of the schema map) in the identity template, and you can overwrite the user identity template from the User form, which is commonly done to substitute organization names.

Waveset users have an identity for each of their accounts, and this identity can be the same for some or for all of these accounts. The system sets the identity for an account when the account is provisioned. The Waveset user object maintains a mapping between a user’s identities and the resources to which they correspond.

The user has a primary accountId in Waveset that is used as a key and as a separate accountId for each of the resources on which that user has an account. The accountId is denoted in the form of accountId:<resource name>, as shown in the following table.

Table 10–8 accountID Examples











Account user names are in one of two forms:

Flat Namespaces

You typically use the accountId attribute for systems with a flat namespace, which include:

For resources with flat namespaces, the identity template can simply specify that the Waveset account name be used.

Hierarchical Namespaces

You use distinguished names (DNs) for systems with a hierarchical namespace. DNs can include the account name, organizational units, and organizations.

Account name syntax is especially important for hierarchical namespaces. For resources with hierarchical namespaces, the identity template can be more complicated than that of a flat namespace, which allows you to build the full, hierarchical name. The following table shows examples of hierarchical namespaces and how they represent DNs.

Table 10–9 Hierarchical Namespace Examples


Distinguished Name String 



Novell NDS 


Microsoft Windows 2000 


For example, you can specify the following for a resource identity template with a hierarchical namespace such as LDAP:



Login Configuration

Login Configuration defines parameters that are used if you are going to use the resource for pass-through authentication. Typically, these parameters are username and password, but some resources use different parameters. For example, SecurId uses user name and passcode.

The Login Configuration information type helps define the resource, but it is not easily modified by administrators.

For more information about pass-through authentication, see Enabling Pass-Through Authentication for Resource Types and the Resource Reference.

Resource Methods

Resource methods write information from Waveset into the external resource.

Note –

You must be familiar with the resource to write customized methods.

You categorize resource methods by task. When developing your own custom adapters, you must determine which categories your adapter needs to meet the goals of your development. For example,

How you answer these questions determines which resource methods must be completed.

The following table describes resource methods categories. (Additional information about each functional category is discussed later in this chapter.)

Table 10–10 Resource Methods Categories




Provide the basic methods for connecting to the resource and performing simple actions 

Bulk operations 

Provide bulk operations to get all the users from the resource 

Active Sync 

Provides the methods to schedule the adapter. 

Object management 

Provides the methods to manage groups and organizations on your resources. Helps define the resource, but is not easily modified by administrators.

In Active Sync-enabled adapters, resource methods

Considerations for Standard Resource Adapters

The following considerations are specific to account attributes in standard resource adapters:

User Identity Template

Note –

To view or edit the Waveset schema for Users or Roles you must be a member of the IDM Schema Configuration AdminGroup and you must have the IDM Schema Configuration capability.

The user identity template establishes the account name to use when creating the account on the resource. This template translates Waveset user account information to account information on the external resource.

You can use any schema map attribute (an attribute listed on the left side of the schema map) in the identity template.

You can overwrite the user identity template from the User form, which is commonly done to substitute organization names.

Creating an Identity Template Out of Multiple User Attributes

You can create an identity template out of a portion of multiple user attributes. For example, a template might consist of the first letter of the first name plus seven characters of the last name. In this case, you can customize the user form to perform the desired logic and then override the identity template that is defined on the resource.

Login Configuration and Pass-Through Authentication

The <LoginConfigEntry> element specifies the name and type of login module as well as the set of authentication properties required by this resource type to complete successful user authentication.

The <LoginConfig> and <SupportedApplications> sections of the adapter file specify whether the resource will be included in the options list on the Login Module configuration pages. Do not change this section of the file if you want the resource to appear in the options list.

Each <AuthnProperty> element contains the following attributes.

Table 10–11 <AuthnProperty> Element Attributes




Specifies the source for the value of this property. Data sources for this property value include: 

  • user (Default): Value provided by the user at login time.

  • http attribute: Value provided by the specified http session attribute.

  • http header: Value provided by the specified http header.

  • http remote user: Value provided by the http request’s remote user property.

  • http request: Value provided by the specified http request parameter.

  • resource attribute (Active Directory only): Value allows you to specify an extra authentication attribute for the specific adapter. This attribute is only valid for the resource on which it is defined, and it cannot be manipulated by the user.

  • x509 certificate: Value is the X509 client certificate (only valid for requests made using https).


Specifies the value to use when this property is added as an HTML item to the Login form. 


Specifies whether to map to a LoginConfigEntry.


Specifies the data type that can be either text or password. This type is used to control whether data input in the HTML field associated with this property is visible (text) or not (password)


Specifies whether this property value should be mapped to the Waveset accountID. For example, a property should not be mapped if the property value is an X509 certificate.


Identifies the internal authentication property name. 

User management across forests is only possible when multiple gateways, one for each forest, are deployed. In this case, you can configure the adapters to use a predefined domain for authentication per adapter without requiring the user to specify a domain as follows:

ProcedureTo Manage Users Across Forests

  1. Add the following authentication property to the <AuthnProperties> element in the resource object’s XML:

    <AuthnProperty name=’w2k_domain’ dataSource=’resource attribute’ value=’MyDomainName’/>

  2. Replace MyDomainName with the domain that authenticates users.

    Note –

    For more information about this property, see the Active Directory resource adapter documentation in Resource Reference.

    Most resource login modules support both the Waveset Administrative interface and User interface. The following example shows how implements the <LoginConfigEntry> element:

    <LoginConfigEntry name=’"+Constants.WS_RESOURCE_LOGIN_MODULE+"’ type=’"+RESOURCE_NAME+"’ 
      "  <AuthnProperties>\n"+
      "     <AuthnProperty name=’"+LOGIN_USER+"’ displayName=’"+DISPLAY_USER+"’ formFieldType=’text’ isId=’true’/>\n"+
      "     <AuthnProperty name=’"+LOGIN_PASSWORD+"’ displayName=’"+DISPLAY_PASSWORD+"’ formFieldType=’password’/>\n"+
      "  </AuthnProperties>\n"+
      "  <SupportedApplications>\n"+
      "     <SupportedApplication name=’"+Constants.ADMINCONSOLE+"’/>\n"+
      "     <SupportedApplication name=’"+Constants.SELFPROVISION+"’/>\n"+
      "  </SupportedApplications>\n"+

    The following example defines the supported LoginModule DATA_SOURCE options. In this example, a LoginConfig entry is taken from the LDAP resource adapter supplied by Waveset. The entry defines two authentication properties whose dataSource value, if not specified, is supplied by the user.

    public static final String USER_DATA_SOURCE = "user";
    public static final String HTTP_REMOTE_USER_DATA_SOURCE = "http remote user";
    public static final String HTTP_ATTRIBUTE_DATA_SOURCE = "http attribute";
    public static final String HTTP_REQUEST_DATA_SOURCE = "http request";
    public static final String HTTP_HEADER_DATA_SOURCE = "http header";
    public static final String HTTPS_X509_CERTIFICATE_DATA_SOURCE = "x509 certificate";
    " <LoginConfigEntry name=’"+WS_RESOURCE_LOGIN_MODULE+"’
    " <AuthnProperties>\n"+
    " <AuthnProperty name=’"+LDAP_UID+"’ displayName=’"+Messages.UI_USERID_LABEL+"’
    formFieldType=’text’ isId=’true’/>\n"+
    " <AuthnProperty name=’"+LDAP_PASSWORD+"’
    " </AuthnProperties>\n"+
    " </LoginConfigEntry>\n"+

    The next example shows a Login Config entry where the authentication property’s dataSource value is not supplied by the user. In this case, the value is derived from the HTTP request header.

    " <LoginConfigEntry name=’"+Constants.WS_RESOURCE_LOGIN_MODULE+"’
    |type=’"+RESOURCE_NAME+"’ displayName=’"+RESOURCE_LOGIN_MODULE+"’>\n"+
    " <AuthnProperties>\n"+
    " <AuthnProperty name=’"+LOGIN_USER+"’ displayName=’"+DISPLAY_USER+"’
    formFieldType=’text’ isId=’true’ dataSource=’http header’/>\n"+
    " </AuthnProperties>\n"+|
    " </LoginConfigEntry>\n"+

Example Object Resource Attribute Declaration

The following example shows how prototypeXML defines fields displayed on the Create/Edit Resource page.

Example 10–2 prototypeXML Defining Fields Displayed on Create/Edit Resource Page

   <ResourceAttribute name=’Host’ description=’The host name running the resource
      agent.’ multi=’false’ value=’n’>
   <ResourceAttribute name=’TCP Port’ description=’The TCP/IP port used to communicate
      with the LDAP server.’ multi=’false’ value=’9278’>
   <ResourceAttribute name=’user’ description=’The administrator user name with which
      the system should authenticate.’ multi=’false’ value=’Administrator’>
   <ResourceAttribute name=’password’ type=’encrypted’ description=’The password that
      should be used when authenticating.’ multi=’false’ value=’VhXrkGkfDKw=’>
   <ResourceAttribute name=’domain’ description=’The name of the domain in which
      accounts will be created.’ multi=’false’ value=’AD’>

The Waveset Administrative interface displays the resource attributes for the default resource as specified.

Profile the Resource

The following sections describe how to profile and define prerequisites for standard resource adapters and Active Sync-enabled adapters.

Profiling a Standard Resource Adapter

Use the following information to create a profile and define prerequisites for a standard resource adapter:

Profiling an Active Sync-Enabled Resource Adapter

When profiling an Active Sync-Enabled resource adapter, use the following information in addition to the considerations described in Profiling a Standard Resource Adapter:

Decide Which Classes and Methods to Include

After profiling the resource, identify classes and methods needed in your adapter:

Review the REF Kit

The Sun Resource Extension Facility Kit (REF Kit) is supplied in the /REF directory on the Waveset CD or install image. You can use the sample files and other tools in this REF Kit to jump-start the process of creating your own custom adapter.

The following table describes the contents of the REF Kit.

Table 10–12 REF Kit Components






Sample custom audit publishers. 



Warehouse interface code source code that allows you to rebuild the warehouse interface to let Data Exporter export to something other than the warehouse relational database. 



Generated javadoc that describes the classes you need to write a custom adapter. To view the javadoc, point your browser to:




Jar files that you need to compile and test a custom adapter. 



Examples of commonly developed resource adapter source files and skeleton files to use as a basis for adapter development and testing, including:

  • for Database accounts

  • for Database tables

  • for File-based accounts

  • for simple methods when developing custom LDAP resource adapters

  • for complex changes when developing custom LDAP resource adapters

  • for developing UNIX accounts

  • for standard resources

  • for standard and Active Sync-enabled resources

  • for Active Sync-only resources

  • to create unit tests for a custom adapter



Sample resource adapter test source files that you can use as a basis for a custom adapter. 






Sample implementation of a transactionsigner PKCS11KeyProvider.



Outlines information you must collect before you customize an adapter. 



Sample Ant Build script for building, testing, and distributing a project.



Document that describes the basic architecture and design of a resource adapter. 



Document describing the Waveset REF Kit.


Copy of the properties file you need to test a custom adapter. 

Set Up the Build Environment

This section contains instructions for setting up your build environment.


You must install the JDK version required for your Waveset version. See “Supported Software and Environments” in the Waveset Release Notes for information.

After installing the JDK, you must install the REF Kit by copying the entire /REF directory to your system.

On Windows

If you are working on Microsoft Windows operating system, use the following steps to set up your build environment:

ProcedureTo Set Up Your Build Environment in Windows

  1. Change directories to a new directory.

  2. Create a file called ws.bat.

  3. Add the following lines to this file:

    set WSHOME=<Path where REF Kit is installed>
    set JAVA_HOME=<Path where JDK is installed>
    set PATH=%PATH%;%JAVA_HOME%\bin

    Where you set:

    • JAVA_HOME to the path to where the JDK is installed.

    • WSHOME to the path to where the REF Kit is installed.

  4. Save and close the file.


If you are working on a UNIX operating system, use the following steps to set up your build environment:

ProcedureTo Set Up Your Build Environment in UNIX

  1. Change directories to a new directory.

  2. Create a file called

  3. Add the following lines to this file:


    Where you set:

    • WSHOME to the path to where the REF Kit is installed.

    • JAVA_HOME to the path to where JDK is installed.

  4. Save and close the file.