RapidIdentity Product Guide

Design Considerations

When designing the actions for an adapter, it is important to keep the model consistent when at all possible. Consistency allows a user who is familiar with one adapter to learn to use new adapters in very little time.

In the following suggested action patterns that should be considered:

  • XXX represents the name of an adapter or connected system

  • YYY represents the name of an object type (e.g., User, Group)

  • System is used generically to refer to the connected system, protocol, or API the adapter is targeting.

Note

It is expected that some systems will require adaptation from the model specified here, but is recommended that the model be followed as closely as is practical for a given system.

  • openXXXConnection(…)

    • Opens a connection or session.

      • Used with systems, protocols, or APIs that are connection or session-based (e.g. LDAP, JDBC)

    • Input Properties:

      • Whatever is required to form a connection/session to the system.

    • Returns:

      • an object that represents the connection or session if successful, null or undefined otherwise

      • the returned object should have a no-argument close() method and be registered for cleanup

  • closeXXXConnection(connection)

    • Closes a connection opened with openXXXConnection()

    • Input Properties:

      • connection - the connection to close

    • Returns:

      • true if successful, false otherwise

      • unregisters the connection object from cleanup

  • defineXXXConnection(…)

    • Defines an object that holds the information necessary to communicate with

      • Used with systems that are not connection- or session-based but still need more than one piece of information in order to communicate with the system

    • Input Properties:

      • Whatever is required to communicate with the system.

    • Returns:

      • an object that encapsulates the input properties, null or undefined otherwise

  • Generic Object Type actions (used for systems that have a large and or extensible schema and all object types are dealt with generically by the protocol or API, e.g. LDAP, JDBC)

    • getXXXRecord(connection, objectType, id)

      • Gets a single record from the connected system

      • Input Properties:

        • connection - connection object created by openXXXConnection or defineXXXConnection

        • objectType - the type of object to get

          • this input property is only needed if the system requires it

        • id - the system specific unique id of the target object

      • Returns:

        • the record for id if successful, null or undefined otherwise

    • getXXXRecords(connection, objectType, filter, limit)

      • Gets a list of records from the system

      • Input Properties:

        • connection - connection object created by openXXXConnection or defineXXXConnection

        • objectType - the type of object to get

          • this input property is only needed if the system requires it or may be encoded in filter in some cases

        • filter - (optional: default all objects) system specific filter specification selecting which objects to get

          • some systems may not support this functionality

          • often useful to also accept a record that serves as an an example of what objects to get

        • limit - (optional: default no limit) the maximum number of records to get

          • some systems may not support this

      • Returns:

        • a (possibly empty) Array of records

    • saveXXXRecord(connection, objectType, record)

      • Creates or updates an object in the system.

      • Input Properties:

        • connection - connection object created by openXXXConnection or defineXXXConnection

        • objectType - the type of object to save

          • this input property is only needed if the system requires it or may be encoded in the record in some cases

        • record - the record representing the object to create or the fields to update

          • if system generates the unique id

            • a record without a unique id field in the record should cause a create

            • a record with a unique id field should cause an update

          • if the system uses user generated ids

            • object is created if there no existing object with the specified unique id

            • object is updated if there is an existing object with the specified unique id

          • when updating, should only update fields that are specified in the record (note that a field is still considered specified if it present but has no values)

      • Returns:

        • a copy of the new or updated object record (MUST if the system generates the unique id) -OR-

        • true if the create/update was successful, false otherwise

    • deleteXXXRecord(connection, objectType, id)

      • Input Properties:

        • connection - connection object created by openXXXConnection or defineXXXConnection

        • objectType - the type of object to delete

          • this input property is only needed if the system requires it

        • id - the system specific unique id of the target object

      • Returns:

        • true if the deletion was successful, false otherwise

    • renameXXXRecord(connection, objectType, id, newName)

      • Renames an object in the system

        • Doesn't make sense for some systems, may be combined with moveXXXRecord for others

      • Input Properties:

        • connection - connection object created by openXXXConnection or defineXXXConnection

        • objectType - the type of object to delete

          • this input property is only needed if the system requires it

        • id - the system specific unique id of the target object

        • newLocation - the system specific unique id of the target object

      • Returns:

        • true if the rename was successful, false otherwise

    • moveXXXRecord(connection, objectType, id, newlocation)

      • Moves an object in the system

        • Doesn't make sense for some systems, may be combined with renameXXXRecord for others

      • Input Properties:

        • connection - connection object created by openXXXConnection or defineXXXConnection

        • objectType - the type of object to delete

          • this input property is only needed if the system requires it

        • id - the system specific unique id of the target object

        • newLocation - the system specific unique id of the target object

      • Returns:

        • true if the rename was successful, false otherwise

    • openXXXRecordIterator (connection, objectType, filter)

      • Opens an iterator over the specified objectType in the system

      • Input Properties:

        • connection - connection object created by openXXXConnection or defineXXXConnection

        • objectType - the type of object to delete

          • this input property is only needed if the system requires it

        • filter - (optional: default all objects) system specific filter specification selecting which objects to get

          • some systems may not support this functionality

          • often useful to also accept a record that serves as an an example of what objects to get

      • Returns:

        • XXXRecordIterator object, which should be iterable both using additional methods and through an ECMAScript for each statement

    • hasNextXXXRecord (iterator)

      • Checks to see if any more records exist in the system for this iterator

      • Input Properties:

        • iterator: XXXRecordIterator object returned by openXXXRecordIterator

      • Returns:

        • true if there are more records, false if there are not

    • getNextXXXRecord (iterator)

      • Retrieves the next Record object from the system

      • Input Properties:

        • iterator: XXXRecordIterator object returned by openXXXRecordIterator

      • Returns:

        • Either the next Record object, or null if no more Record objects exist

    • closeXXXRecordIterator (iterator)

      • Closes any connections opened by iterator, and resets the iterator object

      • Input Properties:

        • iterator: XXXRecordIterator object returned by openXXXRecordIterator

      • Returns:

        • true if successful, false otherwise

  • Specific Object Type actions (used for systems that have a relatively fixed schema and/or each object type handled differently by the protocol or API)

    • Rather than the above listed generic actions, it is also reasonable to implement a set of actions for each object type, with the object type encoded in the name of the action (in place of “Record:) rather than being specified as an input parameter or being encoded in the record, e.g. getXXXUser() and getXXXGroup() instead of getXXXRecord().

In this section: