Sun Identity Manager 8.1 Resources Reference

Chapter 14 Flat File Active Sync

The Flat File Active Sync adapter is defined in the com.waveset.adapter.FlatFileActiveSyncAdapter class.

Adapter Details

The flat file Active Sync adapter provides the ability to read from the following types of files:

Delimited files, such as those containing comma-separated values (CSV), or those delimited by pipes (|).
LDAP Data Interchange Format (LDIF), if the Netscape ldapjdk.jar is provided in the class path.

Custom parsers can also be used, if the parser class implements the com.waveset.util.FlatFileIterator interface.

This adapter is a source-only adapter. It will not write back out to a file.

The following cases are some examples in which it might be appropriate to use the Flat File Active Sync adapter:

A direct API or other programmatic interface does not exist.
No resource adapter exists for the specific resource.
Data stored in one or more resources must be pre-processed before being read into Identity Manager.
The resource owner does not allow direct connections to the resource.
No direct connectivity is available to the resource.

Resource Configuration Notes

The flat file to be read in by the adapter must be available to the application server (or all application servers, if running a cluster) on a local hard drive, network share, or mounted drive, depending on the platform. If synchronization logging is configured, the log directory must also be visible to the application server(s) and writable by the account under which the application server process is running.

The most reliable configuration (and recommended practice) is to store the flat file on a drive that is local to the application server. The log file should also be written to a local directory. If using multiple Identity Manager instances on different servers, choose one server on which to run the flat file Active Sync adapter, and specify that server on the Synchronization policy page of the Administration Interface. Setting this property will ensure that the polling operation on the adapter will always run on one or more particular servers.

Identity Manager Installation Notes

No additional installation procedures are required on this resource.

Usage Notes

This section provides configuration notes related to using the Flat File Active Sync resource adapter, which is organized into the following sections:

General Notes

If you are polling an LDIF file, the LDAP API converts attribute names to lower case. Therefore, if you have an attribute name that contains a capital letter, such as accountId, the LDAP API converts it to accountid. The following error is logged when you start Active Sync.

com.waveset.util.WavesetException: No name attribute found for user based 
on Resolve Identity Rule or schema map.

To correct this situation, in your schema map, set your resource user attribute to accountid.

You might encounter the same error message when you import a file that does not directly set the accountId by a column in the file. To avoid this error message, change the Active Sync User Form by adding a Field for global.accountId and adding logic to build the accountId within that field. The following example field sets accountId to be firstname.lastname, but only on create operations.

<Field name=’waveset.accountId’>
   <Expansion>
      <concat>
         <ref>activeSync.firstname</ref>
         <s>.</s>
         <ref>activeSync.lastname</ref>
      </concat>
   </Expansion>
   <Disable>
      <neq>
         <ref>feedOp</ref>
         <s>create</s>
      </neq>
   </Disable>
</Field>

Active Sync Configuration

The Flat File Active Sync adapter can track the timestamp of a flat file. In addition, the adapter can archive the last file processed and then compare it to the most recent version. Identity Manager will then act on the accounts that are different in the two files.

If these features are enabled, the first time Identity Manager polls the source flat file, the system copies the file and places it in the same directory. The copied (archived) file is named FFAS_timestamp.FFAS, with the timestamp indicating the last time the original file was changed. The format of the timestamp is determined by the operating system on which the source file resides.

On each subsequent poll, Identity Manager compares the timestamp on the original file with the most recent timestamp. If the new timestamp value is the same as the previous value, then the file has not changed, and no further processing is performed until the next poll. If the timestamp values are different, Identity Manager checks for the presence of the FFAS file. If the file does not exist, Identity Manager processes the updated source file as if it were a new file.

If the timestamps are different and the archived FFAS file exists, Identity Manager compares the source file with the archived file. The comparison will filter any users that have not changed. If a user has changed, then it will be sent through the adapter in the normal manner, and the configured process, correlation and delete rules determine what to do with the user.

To facilitate these rules, the adapter will add an additional attribute to indicate the situation discovered by the difference mechanism. If any users exist only in the newly updated source file, the user record will have an additional attribute diffAction which will have the value of create. If any entries were updated in the source file, the attribute diffAction will be added and the value set to update. If any users were deleted then diffAction will be delete.

After the comparison of the two files is complete and all account processing has taken place, Identity Manager deletes the original FFAS file and copies the current source file to a new FFAS file. The timestamp on this file will be different than the previous FFAS file.

Supported Example Files

The following example files are supported by the adapter.

The delimiter and text qualifier can be configured to be any single character. If a Unicode character is used for either, it can be entered in the /u#### format. Delimiters and text qualifiers are not applicable to the LDAP interchange format.

Comma-Delimited Values

In the following example, quotation marks (“ “) are used as the text qualifier. The string 1234 Pecan Ave., Ste 30 contains a comma. Therefore, the string must be qualified to prevent the system from interpreting Ste 30 as an attribute.

accountId,firstname,lastname,email,street address
kb323441,Kevin,Brown,Kevin.Brown@example.com,”1234 Pecan Ave., Ste 30”
pc432343,Penelope,Carter,Penelope.Carter@example.com,4234 Main St.

Pipe-Delimited

accountId|firstname|lastname|email|street address
kb323441|Kevin|Brown|Kevin.Brown@example.com|1234 Pecan Ave., Ste 30
pc432343|Penelope|Carter|Penelope.Carter@example.com|4234 Main St.

LDAP Interchange Format

dn: cn=Kevin Brown,ou=People,dc=example,dc=com
changetype: add
objectClass: top
objectClass: person
objectClass: organizationalperson
objectClass: inetorgperson
employeeNumber: kb323441
cn: Kevin Brown
sn: Brown
departmentNumber: 7013
description: Production
displayName: Kevin
givenName: Kevin
mail: Kevin.Brown@example.com
o: Acme
ou: Production
postalAddress: 1234 Pecan Ave., Ste 30
postalCode: 43231
st: CA
street: 1234 Pecan Ave, Ste 30
title: Production Assistant
jpegphoto: file:///c:/photos/Kevin.Brown.jpg

Security Notes

This section provides information about supported connections and privilege requirements.

Supported Connections

See the Resource Configuration Notes.

Required Administrative Privileges

The administrative user must have read and write access to the directory that contains the flat file. This user must also have delete access if the Process Differences Only Active Sync parameter is enabled.

In addition, the administrator account must have read, write, and delete permissions on the directory specified in the Active Sync Log File Path field.

Provisioning Notes

The following table summarizes the provisioning capabilities of this adapter.

Feature	Supported?
Enable/disable account	No
Rename account	No
Pass-through authentication	No
Before/after actions	No
Data loading methods	Active Sync Reconciliations is NOT supported.

Account Attributes

The resource adapter schema definition is dependent on the contents of the flat file. If no attributes are specified, the adapter will use the attribute names pulled from the flat file. In the case of a delimited file, these values will correspond to the column headings. If different Identity Manager attribute names should be mapped to the column names, specify one or more of those mappings in the schema map.

If the flat file format is LDIF, then binary attributes, such as graphics files, audio files, and certificates may be specified. Binary attributes are not supported for delimited files.

Resource Object Management

Not applicable

Identity Template

The identity template is ignored by this adapter.

Sample Forms

None

Troubleshooting

Use the Identity Manager debug pages to set trace options on the following class:

com.waveset.adapter.FlatFileActiveSyncAdapter