Programming Guides › Connector Programming Guide › Connector Concepts › Recommended Implementation Steps

Recommended Implementation Steps

The following are the recommended steps for implementing a new connector:

1. Use a short indicative prefix for your connector and create a source directory for it under cs-sdk-home/connectors/ using the SDK connector's structure as a template.
   1. Determine whether any useful base classes exist for you to derive your connector and attribute-style processor classes from (this can mean extending an existing connector implementation).
   2. Create new derived classes as required, and verify that they are referenced properly in connector.xml.
   3. Derive basic metadata for the object classes managed by your connector, initially paying particular attention to the top-level namespace and directory level properties and associated metadata settings. In particular the choice of the implementationBundle=value, which must match the value for <property name="name"> your ImplBundle JavaBean in connector.xml.
2. Implement and test the connection to the endpoint, which requires connector-level metadata settings are complete and correct. Start a new JMeter file for your connector at this stage, and add test steps to it for each additional step. Such a test suite is invaluable, and easy to write if you add to it incrementally during the implementation process.
3. Implement and test ADD operation (no associations yet).
4. Implement and test LOOKUP operation (no associations yet). Implement and test early and carefully as the ApacheDS framework on which CA IAM CS is built uses lookup operations internally to verify the sanity of the other operations. Hence, any bugs at this stage are a road-block for the connector's implementation.

   When the array of requested attribute ids is null, all attributes (including expensive ones) should be returned. This behavior differs from the default semantics for search operations.

5. Implement and test DELETE operation (no associations yet).
6. Implement and test MODIFY operation (no associations yet). If any multivalued attributes are supported, then carefully consider whether using the forceModificationMode=REPLACE or forceModificationMode=DELTA metadata settings on them aid your implementation.
7. Implement and test SEARCH operation (no associations yet). Consider the following:
   • When the provided array of requested attribute ids is null, all attributes (excluding expensive ones) should be returned. This differs from the default semantics for lookup operations.
   • Can your connector use the CA IAM CS framework's search one class at a time support, to simplify implementation? If so, then isBehaviourSearchSingleClass() should return true.
   • NamingEnumeration (returned from search operations) base classes can be found in the com.ca.jcs.enumeration package. In particular RawNamingEnumeration takes care of handling size and time limits for its derived classes.
   • If the number of managed objects on the endpoint system could potentially be large, then a streaming solution is highly desirable. If your connector uses search one class at a time support, it can make sense to implement selective streaming searches on only the object types which can have large numbers of instances.
   • It is possible to implement non-streaming search logic first and then later move to streaming logic as required? However, when you have written streaming logic such a phased approach is unlikely to be required.
   • After getting searches on managed object classes working, implement searches targeting unmanaged object classes as these searches are often required when using the Provisioning Manager, as described in step 9.
8. We recommend that you start writing any custom validator and converter plug-ins required by any of your connector’s attributes at this point. As the set of attributes supported by your connector grows, you can add more as required.
9. Test the connector using the Provisioning Manager or Provisioning Server.

   Important! You could also do test incrementally if desired, but we recommend that you always use JMeter first. You could also delay this integration until the connector is fully implemented, and instead validate entirely using your JMeter test. However, as this integration point can produce problems we recommend that you test the implementation.

   • Populate the record of the endpoint type in the Provisioning Server. For DYN-based endpoint types, place a _uninst/*pop.ldif file in the connector's jar, and then running the CA IAM CS installer.

     Note: For more information about other endpoint types and details about writing parser tables and POP scripts, see the Programming Guide for Provisioning.

   • For all endpoint types (whether DYN based or not), the CA IAM CS installer can set up routing rules to your development CA IAM CS for your connector's endpoint type, if you stipulate that the endpoint type is registered. This can also be done manually using Connector Xpress at any stage.
10. Implement association handling logic in the same order as steps 2 - 7. If your connector uses direct associations, consider the following:
    • Can its attribute-style processor derive from com.ca.jcs.assoc.DefaultAssocDirectAttributeOpProcessor to do the heavy lifting? In any case, verify that DNs stored in membership attributes are being converted to and from connector terminology properly by com.ca.jcs.converter.connector.DNPropertyConverter.

      Note: This source code is bundled with the SDK.

    • Should your connector return true from isAutoDirectAssocRequired() so that com.ca.jcs.assoc.AssocAttributeOpProcessorProxy automatically takes care of reverse association handling?
    • If your connector returns true, is it necessary to exclude any operations from this automatic handling using getAutoDirectAssocExlusions()?
11. Implement and test MODIFYRN operation (including handling of associations), if implemented by your connector.
12. Implement and test MOVE operations (including handling of associations), if implemented by your connector.
13. Configure and test resiliency (that is, investigate exceptions and such). We recommend that you test to determine that your connector behaves properly when any of its connection-related attributes are modified at this stage of the implementation. Consider the following:
    • Activation is treated specially, that is, the ADD request for a connector instance is not retried. If connectivity cannot be established at this stage then the ADD fails, and the customer has to retry the ADD manually. The resiliency support comes into effect only after the first successful ADD for the connector instance (after a CA IAM CS restart).
    • Testing for resiliency involves trying to determine all the failure conditions your connector can encounter when communicating with the endpoint system, and categorizing them by their exception messages.
    • Results are captured in exceptionRetryMap entries in connector.xml, tying each exception message to appropriate retry settings. Common groupings are non-retriable exceptions (the default), transient failures, stale connections, and server too busy. Where configured, retrying is carried out by com.ca.jcs.processor.RetryOpProcessorProxy.
    • Connectors can also force retrying in cases where they have access to important context available only in their code.
    • Once resiliency has been correctly configured your connector should be able to reestablish connectivity with the endpoint system after transient failures. Configure retries to run for minutes rather than hours. At some point the connector needs to stop trying to reestablish connectivity and defer the job of retrying to a higher level of the provisioning architecture.

Note: The corresponding chapters of this documentation sometimes group multiple steps around their associated operation (for example, all aspects of implementing each operation are discussed in the same chapter).