What is a Resource Adapter?

A resource adapter serves as a proxy between Waveset and an external resource, such as an application or database. The adapter defines the essential characteristics of the resource type, and this information is saved in the Waveset repository as a resource object. Waveset resource adapters are standard or Active Sync-enabled adapters.

This section contains the following topics:

• What Are Standard Resource Adapters?

• What Are Active Sync-Enabled Resource Adapters?

• What is a Resource Object?

• What is a Resource Adapter Class?

What Are Standard Resource Adapters?

Standard resource adapters provide a generic interface to resource types that are supported by Waveset; such as Web servers, Web applications, databases, and even legacy applications and operating systems. In Java terms, standard resource adapters extend the ResourceAdapterBase class.

These adapters push account information changes from Waveset to their managed, external resources and typically perform the following administrative activities:

• Connect to and disconnect from a resource

• Create, delete, or modify users

• Enable, disable, or get users

• Authenticate users

• Manage objects such as group membership or directory organization structure

Standard resource adapters generally follow these steps when pushing information from Waveset to the resource managed by Waveset:

1. Waveset server initializes the resource manager.

   All available resource types are registered through the Resource Adapter interface. As part of the registration process, the resource adapter provides a prototype XML definition.

2. User initiates process of creating a new resource.

   When an Waveset administrator creates a new resource, the task that creates the form to display the resource type’s prototype definition is queried for the resource attribute fields. Waveset uses these attributes to display a form in the browser. The user who is creating the new resource fills in the information and clicks Save.

3. Waveset saves the information provided, along with the other resource fields in the resource object repository under the name of the new resource object.

   When the user clicks Save during resource creation, the creation task gathers the entered data, executes any necessary validation, then serializes the data using XML before writing the serialized object to the object repository.

4. Waveset displays the list of available resources in a multi-selection box when an Waveset user is created or modified.

   Selecting a resource causes Waveset to query the resource object for the available account attribute fields. Waveset uses these field descriptions to display a form that contains the attribute fields, which the user can fill in with the appropriate data.

5. The resource object is queried for the connection information when this form is saved, and a connection is established with the resource.

6. The adapter sends the command to perform the intended action on the account on the resource over this connection.

7. If this request is a create request, the adapter updates the Waveset user object with the resource account information.

   When user account information is displayed, Waveset requests the list of resources on which the user has accounts from the saved account object. For each resource, Waveset queries the resource object and uses the connection information to establish a connection to the resource.

   The adapter sends a command over this connection to retrieve account information for the user, and it uses the retrieved information to fill in the attribute fields that are defined in the resource object. The system creates a form to display these values.

What Are Active Sync-Enabled Resource Adapters?

Active Sync-enabled adapters are an extension of a standard resource adapter and they are used to implement the Active Sync interface for some common resources, such as Active Directory. These adapters pull data changes directly from the resource to initiate the following activities in Waveset:

• Polling or receiving change event notification

• Issuing actions to create, update, or delete resource accounts

• Editing or creating users with a custom form

• Saving the resource changes

• Logging progress information and errors

Active Sync-enabled adapters are particularly suitable for supporting the following resource types:

• Applications with audit or notification interfaces

  Some applications, such as Microsoft Active Directory and PeopleSoft, have external interfaces. You can configure these application interfaces to add events to an audit log or to notify other applications when certain changes occur.

  For example, you can configure the interface to record an transaction in the audit log whenever a user account is modified natively on the Active Directory server. You can configure the Waveset Active Directory resource to review this log every 30 minutes and trigger events in Waveset when any changes occur. You can register other Active Sync-enabled adapters with the resource through an API, and use event messages to notify the adapter when changes occur. These event messages can reference the item that changed, the information that was updated, and frequently the user who made the change.

• Databases populated with update information

  You can manage database resources by generating a table of deltas and generate this table in several different ways. For example, you can compare a snapshot of the database to current values and create a new table with the differences. The adapter pulls rows from the table of deltas, processes them, and subsequently marks them when completed.

• Databases with modification timestamps

  You can create Active Sync-enabled queries for database entries that have been modified after a particular time. The adapters run updates and then poll for new queries. By storing the last successfully processed row, Waveset can perform a “starts with” query to minimize the polling impact. Only those changes made to the resource since the previous set of modifications were made are returned for processing.

• Resources with change-log entries

  Most LDAP servers provide a change-log mechanism that you can use to track changes, optionally constrained to sections of interest in the DIT. By periodically querying the change-log entries, the LDAP resource adapter can update Waveset with detected changes; including creates, deletes, and updates.

Active Sync-enabled adapters generally follow these steps when listening or polling for changes to the resource managed by Waveset. When the adapter detects that a resource has changed, the Active Sync-enabled adapter:

1. Extracts the changed information from the resource.

2. Determines which Waveset object is affected.

3. Builds a map of user attributes to pass to the IAPIFactory.getIAPI method, along with a reference to the adapter and a map of any additional options, which creates an Identity Application Programming Interface (IAPI) object.

4. Sets the logger on the IAPI event to the adapter’s Active Sync logger.

5. Submits the IAPI object to the Active Sync Manager.

6. Active Sync Manager processes the IAPI object and returns a WavesetResult object to the adapter. The WavesetResult object informs the Active Sync-enabled adapter if the operation succeeds.

   The WavesetResult object might contain many results from the various steps the Waveset system used to update the identity. Typically, a workflow also handles errors within Waveset, often ending up as an Approval for a managing administrator.

7. Exceptions are logged in the Active Sync and Waveset tracing logs with the ActiveSyncUtil.logResourceException method.

   When Active Sync-enabled adapters detect a change to an account on a resource, the adapter maps the incoming attributes to an Waveset user or, if the adapter cannot match the user account, creates an Waveset user account.

The following rules and parameters determine what happens when a change is detected.

Parameter	Description
Confirmation Rule	Rule that is evaluated for all users returned by a correlation rule. For each user, the full User view of the correlation Waveset identity and the resource account information (placed under the “account.” namespace) are passed to the confirmation rule. The confirmation rule is then expected to return a value which may be expressed like a Boolean value. For example, “true” or “1” or “yes” and “false” or “0” or null.  For the Database Table, Flat File, and PeopleSoft Component Active Sync adapters, the default confirmation rule is inherited from the reconciliation policy on the resource.  The same confirmation rule can be used for reconciliation and Active Sync.
Correlation Rule	If no Waveset user’s resource information is determined to own the resource account, the Correlation Rule is invoked to determine a list of potentially matching users/accountIDs or attribute conditions, used to match the user, based on the resource account attributes (in the account namespace). Returns one of the following types of information that can be used to correlate the entry with an existing Waveset account:  Waveset user name WSAttributes object (used for attribute-based search) List of AttributeCondition or WSAttribute-type items (AND-ed attribute-based search) List of String-type items (each item is the Waveset ID or the user name of an Waveset account) If more than one Waveset account can be identified by the correlation rule, a confirmation rule or resolve process rule is required to handle the matches. For the Database Table, Flat File, and PeopleSoft Component Active Sync adapters, the default correlation rule is inherited from the reconciliation policy on the resource. The same correlation rule can be used for reconciliation and Active Sync.
Create Unmatched Accounts	If set to true, creates an account on the resource when no matching Waveset user is found. If false, the account is not created unless the process rule is set and the workflow it identifies determines that a new account is warranted. The default is true.
Delete Rule	A rule that can expect a map of all values with keys of the form activeSync. or account. pulled from an entry or line in the flat file. A LighthouseContext object (display.session) based on the proxy administrator’s session is made available to the context of the rule. The rule is then expected to return a value which may be expressed like a Boolean value. For example, “true” or “1” or “yes” and “false” or “0” or null. If the rule returns true for an entry, the account deletion request will be processed through forms and workflow, depending on how the adapter is configured.
Populate Global	If set to true, populates the global namespace in addition to the ActiveSync namespace. The default value is false.
Process Rule	Either the name of a TaskDefinition or a rule that returns the name of a TaskDefinition, to run for every record in the feed. The Process rule gets the resource account attributes in the Active Sync namespace, as well as the resource ID and name. A Process rule controls all functionality that occurs when the system detects any change on the resource. It is used when full control of the account processing is required. As a result, a process rule overrides all other rules. If a Process rule is specified, the process will be run for every row regardless of any other settings on this adapter.  At minimum, a process rule must perform the following functions:  Query for a matching User view. If the User exists, checkout the view. If not, create the User. Update or populate the view. Checkin the User view. It is possible to synchronize objects other than User, such as LDAP Roles.
Resolve Process Rule	Name of the TaskDefinition or a rule that returns the name of a TaskDefinition to run in case of multiple matches to a record in the feed. The Resolve Process rule gets the resource account attributes as well as the resource ID and name. This rule is also needed if there were no matches and Create Unmatched Accounts was not selected.  This workflow can be a process that prompts an administrator for manual action.

---

Note –

If present, a Process rule determines whether the adapter uses IAPIProcess or attempts to use IAPIUser. If the adapter cannot use IAPIUser because a Correlation or Confirmation rule does not uniquely identify an Waveset user for the event (given the other parameter settings), and a Resolve Process rule is configured, the adapter uses the Resolve Process rule to create an IAPIProcess event. Otherwise, the adapter reports an error condition.

IAPIUser checks out a view and makes this view available to the User form.

• For creates and updates, IAPIUser checks out the User view.

• For deletes, IAPIUser checks out the Deprovision view.

However, a User view is not checked out or available with IAPIProcess. Either a Process rule has been set or a Resolve Process rule is invoked.

---

What is a Resource Object?

Resource objects define the capabilities and configuration of the resource you are managing in Waveset, including the information described in the following table.

Table 10–2 Information Defined by Resource Objects

Type of Information	Sample Attributes
Connection information	Host name Administrative account name Administrative account Password
User attributes	First name Last name Phone numbers
Waveset attributes	List of approvers Password policy for the resource How many times to repeat attempts when contacting the resource

You must define a resource object in Waveset for every resource that Waveset communicates with or manages.

---

Note –

You can view resource objects from Waveset’s Debug pages:

http://host:port/idm/debug/

Where:

• host is the local server on which Waveset is running.

• port is the TCP port number on which the server is listening.

  The session.jsp page gives you the option of listing objects of type Resource. See Viewing and Editing a Resource Object for more information.

---

What is a Resource Adapter Class?

A resource adapter class implements methods that

• Register the resource object in the Waveset repository

• Enable you to manage the external resource

• Push information from Waveset to the resource

• (Optional) Pull information from the resource into Waveset

  This optional pull capability is known as Active Sync, and a resource adapter with Active Sync capability is referred to as Active Sync-enabled. See What Are Active Sync-Enabled Resource Adapters? for more information.