CSV Connector

The CSV connector implements the Identity Java Connector Integration Framework’s DxmConnectorCore, DxmRequestor and DxmContext interfaces and writes and reads CSV files using the SuperCsv classes. Like all framework-based agents, it gets SPML requests from the Identity side by the join engine as part of the workflow engine hosted by the Java-based Server. It converts the SPML requests in order to read from and write to CSV files.

The CSV connector provides the functionality to:

Add any kind of object - especially user, account or group - to a CSV file.
Perform searches on a CSV file to import the objects to Identity.

Overview

The connector implements the API methods "add(…)" and "search(…)". They represent the corresponding SPML requests "AddRequest" and "SearchRequest".

Limitations

No handling for binary data and no handling for multi-value attributes is implemented.

Request and Response Handling

This section describes the supported requests and attributes for the CSV connector.

AddRequest

In an add request, the identifier is mandatory. The identifier is mapped to the column specified by the connection property namingAttribute. The connection property csvAttributes specifies the columns of the CSV file. The CSV connector writes to the CSV file. The export_file property of the connector specifies the CSV file name. If not specified, the file name is read from the framework context variable ts.channelName.env.export_file where channelName is retrieved from the operational attributes of the AddRequest.

Example request:

<?xml version="1.0" encoding="UTF-8" ?>
<spml:batchRequest xmlns="urn:oasis:names:tc:SPML:1:0"
xmlns:spml="urn:oasis:names:tc:SPML:1:0"
xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core"
requestID="batch-1"
processing="urn:oasis:names:tc:SPML:1:0#sequential"
execution="urn:oasis:names:tc:SPML:1:0#synchronous"
onError="urn:oasis:names:tc:SPML:1:0#exit">
<spml:addRequest requestID="add-1">
       <spml:identifier type="urn:oasis:names:tc:SPML:1:0#DN">
         <spml:id>cn=Tymchuk Antonio,ou=Product Testing,o=My-Company,cn=Users,cn=My-Company</spml:id>
      </spml:identifier>
      <spml:attributes>
         <dsml:attr name="c" xmlns="urn:oasis:names:tc:DSML:2:0:core">
               <dsml:value>DE</dsml:value>
         </dsml:attr>
         <dsml:attr name="o" xmlns="urn:oasis:names:tc:DSML:2:0:core">
            <dsml:value>My-Company</dsml:value>
         </dsml:attr>
         <dsml:attr name="ou" xmlns="urn:oasis:names:tc:DSML:2:0:core">
            <dsml:value>Product Testing</dsml:value>
         </dsml:attr>
         <dsml:attr name="l" xmlns="urn:oasis:names:tc:DSML:2:0:core">
            <dsml:value>My-Company Berlin</dsml:value>
         </dsml:attr>
         <dsml:attr name="employeeNumber" xmlns="urn:oasis:names:tc:DSML:2:0:core">
            <dsml:value>4873</dsml:value>
         </dsml:attr>
         <dsml:attr name="sn" xmlns="urn:oasis:names:tc:DSML:2:0:core">
            <dsml:value>Tymchuk</dsml:value>
         </dsml:attr>
         <dsml:attr name="givenName" xmlns="urn:oasis:names:tc:DSML:2:0:core">
            <dsml:value>Antonio</dsml:value>
         </dsml:attr>
         <dsml:attr name="cn" xmlns="urn:oasis:names:tc:DSML:2:0:core">
            <dsml:value>Tymchuk Antonio</dsml:value>
         </dsml:attr>
    </spml:attributes>
</spml:addRequest>
</spml:batchRequest>

Search Request

In a SPML search request, the CSV connector supports the elements searchBase and filter, and the operational attributes scope, pageSize, noattrs (if set to FALSE or not existing all attributes are retrieved) and channelName.

The join engine sets the operational attribute channelName only in a Java server workflow context. channelName is used to get the name of the source file for the SearchRequest if no file name was specified in the CSV connector’s <connection> filename property. The file name is then obtained from the framework context variable ts.*channelName.env.import_file*.

If the join engine calls the CSV connector’s search method in the context of a workflow running from Identity to the connected system (export mode), the CSV connector returns an empty search result to make the join engine produce an AddRequest resulting in writing a CSV row.

Example request:

<?xml version="1.0" encoding="UTF-8" ?>
<spml:searchRequest  xmlns="urn:oasis:names:tc:SPML:1:0"
    xmlns:spml="urn:oasis:names:tc:SPML:1:0"
    xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core"
    requestID="search_01"
    >
<spml:searchBase type = "urn:oasis:names:tc:SPML:1:0#DN">
  <spml:id>cn=users,cn=My-Company</spml:id>
</spml:searchBase>
  <spml:filter>
    <dsml:and>
      <dsml:equalityMatch name="ou">
      <dsml:value>Sales</dsml:value>
      </dsml:equalityMatch>
      <dsml:not>
      <dsml:present name="assistant" />
      </dsml:not>
    </dsml:and>
  </spml:filter>

<spml:operationalAttributes>
  <dsml:attr name="scope">
     <value>subtree</value>
  </dsml:attr>
  <dsml:attr name="pageSize">
     <value>0</value>
  </dsml:attr>
  <dsml:attr name="channelName">
     <value>users</value>
  </dsml:attr>
</spml:operationalAttributes>
<spml:attributes>
</spml:attributes>
</spml:searchRequest>

Configuration

Here is a sample configuration snippet for the CSV connector:

<connector
role="connector"
className=" siemens.dxm.connector.framework.csv.CsvConnector "
name="CSV Connector" version="1.00">
<connection type="file"
  filename="filename="C:/MetahubData/data.csv""
  <property name="csvAttributes" value="c, o, ou, DDN, l, employeeNumber, cn, title, salutation, sn, givenName, description"/>
  <property name=" export_file" value="C:/MetahubData/mydataConnector.csv"/>
  <property name="separator" value="|"/>
  <property name="hasHeader" value="true"/>
  <property name="namingAttribute" value="DDN"/>
</connection>
</connector>

Supported Connection Parameters

The following standard properties of the XML configuration file’s <connection> element are supported:

filename - (optional); one or more comma-separated file names used as the source file(s) for the search request (import file). In a Java-based workflow context, the framework context variable ts.channelName.env.import_file specifies the import file name if the filename property is not specified.

Non-standard supported properties:

csvAttributes - (optional); the columns of the CSV file. In a Java-based workflow context, the csvAttributes are taken from the mapped attributes.

export_file - (optional); the name of the file to which the CSV records are written. If not specified in a Java-based Server export workflow context, the framework context variable ts.channelName.env.export_file specifies the file name.

namingAttribute - The attribute that defines the identifier in the CSV file. For searches, this value identifies which column is used for matching the base node part of the filter and is used as the SPML identifier in the result. For Add request, it identifies the column to which the mapped identifier is written. Like the other parameters in a Java-based workflow context, it is retrieved from the framework context.

separator - The attribute that defines the separator of the CSV file. If not specified, a comma is assumed. Like the other parameters in a Java-based workflow context, it is retrieved from the framework context.

hasHeader - The attribute that defines whether the CSV file contains a header line. If not specified, no header line is assumed. Like the other parameters in a Java-based workflow context, it is retrieved from the framework context.

comment - If set, the given value is used to identify a comment line. Lines beginning with this value are skipped during read. This is not part of the CSV specification.

Parameters in a Java-based workflow context:

Here you can specify the parameters for every channel. You can have channels for different subtrees, different object types and so on. At a specific channel, you define the parameters needed for this channel. The parameters are configured as specific attributes. They have the same names as they do in the connection section. The join engine always treats these names as lowercase.