openconnector

Interface Connector

All Known Implementing Classes:

AbstractConnector

public interface Connector

A Connector serves as a common interface for low-level communication to a resource. The methods in this interface fits into one of the following categories:

• Connector capabilities: These provide information about what types of objects a connector can manage with and which features are supported for each object type. These are the only methods that do not require a fully configured connector.
  • getSupportedObjectTypes()
  • getSupportedFeatures(String)
• Connector Lifecycle: A connector is stateful, in that it must be configured before it can be used and eventually closed. These methods define that lifecycle.
  • configure(ConnectorConfig, Log)
  • setObjectType(String)
  • close()
• Connector Utilities: These methods test a connector.
  • testConnection()
  • discoverSchema(String)
  • authenticate(String, String)
• Object access: These method allows you to create, update, and delete resource objects.
  • read(String)
  • iterate(Filter)
  • provision(Plan)

A Connector MUST implement all "Connector Capabilities" method, "Connector Lifecycle" methods, and the testConnection(). All other methods are optional. If supported, a method should be declared as supported by returning the appropriate Feature from getSupportedFeatures(String). Otherwise, the method should throw and UnsupportedOperationException. Rather than implementing the Connector interface directly, it is recommended that the AbstractConnector be extended.

As mentioned previously, Connectors are stateful, in that they must be configured, used, and closed. The connector keeps state about how it was configured, dynamic settings such as object type, and any internal connection state to the underlying resource. Every caller must take care to close the Connector to release any resources. Here is a typical pattern for using a Connector:

   Connector conn = new MyConnector();
   try {
       conn.configure(config, log);
       Map<String,Object> account = conn.read("myaccountid");
   }
   finally {
       conn.close();
   }
 

Object Types

A Connector declares what types of objects it can manage through getSupportedObjectTypes. These are typically either accounts or groups (see the OBJECT_TYPE_* constants), but a connector can claim support for other non-standard types (for example - roles, etc...). The default object type for a new connector is OBJECT_TYPE_ACCOUNT. You can change the object type by calling setObjectType Once set, the object type influences the behavior of the read and iterate methods.

Data

Resource objects (accounts, groups, etc.) are modeled as Maps with the map keys representing the object attribute names. Map values will usually be String or List<String> but they can be of any type defined by Schema.Type. When you build a Plan, the values in the plan should match what is expected by the connector. Though it is recommended that connectors do type coercion this is not required.

Configuration

Each connector will require different configuration information that dictates how to connect to the resource and specifics about connector behavior. This information is defined in the ConnectorConfig. The configuration should include a list of Schema objects defining the attributes of each of the objects that are managed by the connector. Schemas are optional for simple connectors in which the object schemas are fixed.

Exceptions

The connector methods will either throw an UnsupportedOperationException, a checked exception that indicates an expected error condition (such as ObjectNotFoundException), or a generic unchecked exception that indicates some other type of resource failure (ConnectorException).

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Connector.Feature An enumeration of features that a Connector can choose to support.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	ARG_CURRENT An argument that can be passed in the Item for ATT_PASSWORD that contains what is believed to be the current password.
static java.lang.String	ARG_EXPIRATION An argument that can be passed in the Item for the ATT_PASSWORD attribute to indicate that the password should expire.
static java.lang.String	ARG_PARTITION
static java.lang.String	ATT_DELETED A reserved attribute name used to indiciate that this object has been deleted.
static java.lang.String	ATT_DISABLED A reserved attribute name used to convey disabled status.
static java.lang.String	ATT_LOCKED A reserved attribute name used to convey lock status.
static java.lang.String	ATT_PASSWORD A reserved attribute name used to convey an account password.
static java.lang.String	ATT_PERMISSIONS A reserved attribute name used to pass a List of Permission objects.
static java.lang.String	OBJECT_TYPE_ACCOUNT Object type representing an account on a resource.
static java.lang.String	OBJECT_TYPE_GROUP Object type representing an group on a resource.
static java.lang.String	OBJECT_TYPE_TICKET Object type representing an group on a resource.

Method Summary

Modifier and Type	Method and Description
java.util.Map<java.lang.String,java.lang.Object>	authenticate(java.lang.String accountId, java.util.Map<java.lang.String,java.lang.Object> options) Attempt to authenticate to the underlying resource using the given accountId and password.
java.util.Map<java.lang.String,java.lang.Object>	authenticate(java.lang.String identity, java.lang.String password) Attempt to authenticate to the underlying resource using the given identity and password.
Result	checkStatus(java.lang.String id) Using the id passed into this method check the request to see if has completed.
void	close() Close the underlying resources that are being held by this connector.
void	configure(ConnectorConfig config, Log log) Configure the connector with connection parameters and optional schemas.
void	destroy(java.util.Map<java.lang.String,java.lang.Object> optionsMap) Called by aggregator at the end of aggregation
Schema	discoverSchema() Discover the Schema for the currently configured object type.
java.util.Map	doHealthCheck(java.util.Map<java.lang.String,java.lang.Object> options) Light Weight Test Connection API.Test the connection to the application ,Returns nothing on success and throws an exception (as detailed as possible) when there is a problem
java.util.Iterator<java.util.Map<java.lang.String,java.lang.Object>>	getChangeLogExtract(java.util.Map<java.lang.String,java.lang.Object> requestParams) This method will be called to fetch Change log extract from ERP Systems.
ConnectorConfig	getConfig()
java.util.Map<java.lang.String,java.lang.Object>	getConfigOptions(java.lang.String configOptionsKey)
ConnectorServices	getConnectorServices()
java.util.List<java.util.Map<java.lang.String,java.lang.Object>>	getExtractPartitions(java.util.Map<java.lang.String,java.lang.Object> requestParams, java.lang.String extractType) This method will be called to get extract Partition for ARM extract requests if user has no required permissions to fetch Security extract from underlying tables it will throw InsufficientPermissionException
java.util.List<Partition>	getIteratorPartitions(int suggestedPartitionCount, Filter filter, java.util.Map<java.lang.String,java.lang.Object> ops) Return the list of partitions for a connector.
Log	getLog()
java.lang.String	getObjectType()
java.util.Iterator<java.util.Map<java.lang.String,java.lang.Object>>	getSecurityExtract(java.util.Map<java.lang.String,java.lang.Object> requestParams) This method will be called to fetch Security extract from ERP Systems.
java.util.List<Connector.Feature>	getSupportedFeatures(java.lang.String objectType) Return the list of Features that are supported for the given object type.
java.util.List<java.lang.String>	getSupportedObjectTypes() Return a list of the object types supported by this connector.
java.util.Iterator<java.util.Map<java.lang.String,java.lang.Object>>	getUtilizationExtract(java.util.Map<java.lang.String,java.lang.Object> requestParams) This method will be called to fetch Utilization extract from ERP Systems requestParams has required details to fetch Utilization extract data.
java.util.Iterator<java.util.Map<java.lang.String,java.lang.Object>>	iterate(Filter filter) Return an iterator over the objects of the configured object type that match the given filter (or all objects if no filter is specified).
java.util.Iterator<java.util.Map<java.lang.String,java.lang.Object>>	iterate(Partition parition) Method used to iterate over the object in chunks that can be processed in different threads or machine pools.
void	notifyListeners() Notify listeners on application config changes
void	provision(Plan plan) Evaluate a provisioning plan that specifies operations to be performed on one or more objects.
java.util.Map<java.lang.String,java.lang.Object>	read(java.lang.String id) Return the object of the configured object type that has the given native identifier.
void	registerListener(ConnectorStateChangeListener listener) Register listener to listen to openconnector app config changes
void	saveConnectorState() Save new connector state values into the app config
void	setConnectorServices(ConnectorServices connServices) Sets the ConnectorServices object.
void	setConnectorState(java.lang.String attribute, java.lang.Object val) Interface to set new connector config value
void	setObjectType(java.lang.String objectType) Change the target object type for connector methods.
void	setStatisticsCollector(StatisticsCollector statisticsCollector) Set the StatisticsCollector object require for underlying connector to push the aggreagtion statistics.
boolean	supportsPartitionedDeltaAggregation() Gets if the connector supports partitioned delta aggregation
void	testConnection() Test the configured to see if a connection can be made.

Field Detail

OBJECT_TYPE_ACCOUNT

static final java.lang.String OBJECT_TYPE_ACCOUNT

Object type representing an account on a resource.

See Also:

Constant Field Values

OBJECT_TYPE_GROUP

static final java.lang.String OBJECT_TYPE_GROUP

Object type representing an group on a resource.

See Also:

Constant Field Values

OBJECT_TYPE_TICKET

static final java.lang.String OBJECT_TYPE_TICKET

Object type representing an group on a resource.

See Also:

Constant Field Values

ATT_PASSWORD

static final java.lang.String ATT_PASSWORD

A reserved attribute name used to convey an account password. This is a write-only attribute, connectors are not expected to return this from a read().

See Also:

Constant Field Values

ATT_DISABLED

static final java.lang.String ATT_DISABLED

A reserved attribute name used to convey disabled status. Setting this to true disables the object, false enables the object. Connectors are also expected to return this in the Map returned by the read() method to convey the current status.

See Also:

Constant Field Values

ATT_LOCKED

static final java.lang.String ATT_LOCKED

A reserved attribute name used to convey lock status. Setting this to true locks the object, false unlocks the object. Note that most connectors only allow you to unlock objects, locking is done as a side effect of some other action, such as failing to supply a correct password.

Connectors are also expected to return this in the Map returned by the read() method to convey the current status.

See Also:

Constant Field Values

ATT_PERMISSIONS

static final java.lang.String ATT_PERMISSIONS

A reserved attribute name used to pass a List of Permission objects.

See Also:

Constant Field Values

ATT_DELETED

static final java.lang.String ATT_DELETED

A reserved attribute name used to indiciate that this object has been deleted. This is set only when doing delta aggregation and the connector supports detection of native deletes.

Note that ResourceObject has a few other flags for special situations like incomplete, incremental, remove, and missing. These were only used by SMConnector and are not expected to be applicable for OpenConnectors.

See Also:

Constant Field Values

ARG_EXPIRATION

static final java.lang.String ARG_EXPIRATION

An argument that can be passed in the Item for the ATT_PASSWORD attribute to indicate that the password should expire. This is expected to be a java.util.Date.

See Also:

Constant Field Values

ARG_CURRENT

static final java.lang.String ARG_CURRENT

An argument that can be passed in the Item for ATT_PASSWORD that contains what is believed to be the current password. This should be passed from above if the resource requires the current password in order to change the password.

In theory this could be used for other attributes besides passwords.

See Also:

Constant Field Values

ARG_PARTITION

static final java.lang.String ARG_PARTITION

See Also:

Constant Field Values

Method Detail

getSupportedObjectTypes

java.util.List<java.lang.String> getSupportedObjectTypes()

Return a list of the object types supported by this connector. This list can contain any of the OBJECT_TYPE_* constants or any arbitrary type that is supported by the connector.

getSupportedFeatures

java.util.List<Connector.Feature> getSupportedFeatures(java.lang.String objectType)

Return the list of Features that are supported for the given object type. If a Feature is returned, the corresponding method should not throw an UnsupportedOperationException for the given object type.

configure

void configure(ConnectorConfig config,
               Log log)
        throws java.lang.IllegalArgumentException

Configure the connector with connection parameters and optional schemas. Once configured you select the desired target object type by calling setObjectType. The default object type after configuration is OBJECT_TYPE_ACCOUNT.

Parameters:

config - The ConnectorConfig that specifies connection parameters and schemas.

log - An implementation of Log that the connector can use for logging.

Throws:

java.lang.IllegalArgumentException - If config is null.

getConfig

ConnectorConfig getConfig()

Returns:

the ConnectorConfig that was used to configure this connector.

registerListener

void registerListener(ConnectorStateChangeListener listener)

Register listener to listen to openconnector app config changes

Parameters:

listener - The listener that is interested in listening to connector config changes

notifyListeners

void notifyListeners()

Notify listeners on application config changes

setConnectorState

void setConnectorState(java.lang.String attribute,
                       java.lang.Object val)

Interface to set new connector config value

Parameters:

attribute - The attribute that needs to be set a new value

val - The value to set against the attribute

saveConnectorState

void saveConnectorState()

Save new connector state values into the app config

setObjectType

void setObjectType(java.lang.String objectType)
            throws java.lang.IllegalArgumentException

Change the target object type for connector methods. The default object type after initial configuration is OBJECT_TYPE_ACCOUNT. This will influence the behavior of the read() and iterate() methods.

Parameters:

objectType - The target object type for future method calls. This can be one of the OBJECT_TYPE_* constants or any supported object type.

Throws:

java.lang.IllegalArgumentException - If type is null.

getObjectType

java.lang.String getObjectType()

Returns:

the current target object type.

getLog

Log getLog()

Returns:

the Log to use for this connector.

setConnectorServices

void setConnectorServices(ConnectorServices connServices)

Sets the ConnectorServices object.

getConnectorServices

ConnectorServices getConnectorServices()

Returns:

the ConnectorServices object.

close

void close()

Close the underlying resources that are being held by this connector. Clients MUST call this when they are done with a connector or else there can be resource leaks.

testConnection

void testConnection()
             throws ConnectorException

Test the configured to see if a connection can be made. This should throw exceptions if the configuration is not complete, has invalid values, the resource cannot be contacted. If the connection succeeds, no exceptions are thrown.

Throws:

ConnectorException

discoverSchema

Schema discoverSchema()
               throws ConnectorException,
                      java.lang.UnsupportedOperationException

Discover the Schema for the currently configured object type.

Throws:

ConnectorException - If the operation fails.

java.lang.UnsupportedOperationException - If the DISCOVER_SCHEMA feature is not supported.

read

java.util.Map<java.lang.String,java.lang.Object> read(java.lang.String id)
                                               throws ConnectorException,
                                                      ObjectNotFoundException,
                                                      java.lang.UnsupportedOperationException

Return the object of the configured object type that has the given native identifier.

Parameters:

id - A unique identifier for the object.

Returns:

The object that was read from the resource, or null if an object with the given id was not found.

Throws:

ConnectorException - If the operation fails.

java.lang.UnsupportedOperationException - If the GET feature is not supported.

ObjectNotFoundException

iterate

java.util.Iterator<java.util.Map<java.lang.String,java.lang.Object>> iterate(Filter filter)
                                                                      throws ConnectorException,
                                                                             java.lang.UnsupportedOperationException

Return an iterator over the objects of the configured object type that match the given filter (or all objects if no filter is specified).

Parameters:

filter - The possibly null filter to use to constrain which objects are returned.

Returns:

An iterator over the object of the configured object type that match the given filter.

Throws:

ConnectorException - If the operation fails.

java.lang.UnsupportedOperationException - If the ITERATE feature is not supported.

getIteratorPartitions

java.util.List<Partition> getIteratorPartitions(int suggestedPartitionCount,
                                                Filter filter,
                                                java.util.Map<java.lang.String,java.lang.Object> ops)
                                         throws ConnectorException,
                                                java.lang.UnsupportedOperationException

Return the list of partitions for a connector.

The partitions returned here simple objects that hold a name, size, objectType and an attributes map for additional information.

The caller will take each partition and treat it as a single unit of work that will be distributed among the cluster of servers and or threads.

Each object in the list should contain enough about the partition so the calls to iterateObjects have information to process a single partition.

A unique name (within the list) and the objectType is required to be returned with each partition.

The caller will give hints to the suggestedPartitionCount based on processors and cores but the Application config should ultimately determine how many partitions should be returned.

Parameters:

suggestedPartitionCount - The caller will calculate the optimal number of partitions and pass it into the connector.

filter - The possibly null filter to help constrain which options are returned.

ops - The possibly null map will provides additional options for future expansion.

Returns:

List of Objects used to configure each partition, returning

Throws:

ConnectorException

java.lang.UnsupportedOperationException

See Also:

Partition

iterate

java.util.Iterator<java.util.Map<java.lang.String,java.lang.Object>> iterate(Partition parition)
                                                                      throws ConnectorException,
                                                                             java.lang.UnsupportedOperationException

Method used to iterate over the object in chunks that can be processed in different threads or machine pools.

Parameters:

parition - One of the objects built in getIteratorPartitions that will drive which objects get returned by the iterator.

Returns:

Iterator over the object for a Partition

Throws:

ConnectorException

java.lang.UnsupportedOperationException

See Also:

Partition

authenticate

java.util.Map<java.lang.String,java.lang.Object> authenticate(java.lang.String identity,
                                                              java.lang.String password)
                                                       throws ConnectorException,
                                                              AuthenticationFailedException,
                                                              ExpiredPasswordException,
                                                              ObjectNotFoundException,
                                                              java.lang.UnsupportedOperationException

Attempt to authenticate to the underlying resource using the given identity and password. The identity may be the value of the identity attribute, but could also be a value that can be used to search for the account (for example - sAMAccountName, full name, etc...). If successful, this returns the account that was authenticated to.

Parameters:

identity - A value for an identifying attribute of the account to authenticate with.

password - The password to use to authenticate.

Returns:

The authenticated account if authentication was successful.

Throws:

ConnectorException - If the operation fails.

AuthenticationFailedException - If authentication failed.

ExpiredPasswordException - If authentication failed because of an expired password.

ObjectNotFoundException - If an object that matches the given identity could not be found.

java.lang.UnsupportedOperationException - If the AUTHENTICATE feature is not supported.

authenticate

java.util.Map<java.lang.String,java.lang.Object> authenticate(java.lang.String accountId,
                                                              java.util.Map<java.lang.String,java.lang.Object> options)
                                                       throws ConnectorException,
                                                              AuthenticationFailedException,
                                                              ExpiredPasswordException,
                                                              ObjectNotFoundException,
                                                              java.lang.UnsupportedOperationException

Attempt to authenticate to the underlying resource using the given accountId and password. The accountId may be the value of the identity attribute, but could also be a value that can be used to search for the account (for example - sAMAccountName, full name, etc...). If successful, this returns the account that was authenticated to.

Parameters:

accountId - A value for an identifying attribute of the account to authenticate with.

options - Additional options to consider during authentication including the password.

Returns:

The authenticated account if authentication was successful.

Throws:

ConnectorException - If the operation fails.

AuthenticationFailedException - If authentication failed.

ExpiredPasswordException - If authentication failed because of an expired password.

ObjectNotFoundException - If an object that matches the given identity could not be found.

java.lang.UnsupportedOperationException - If the AUTHENTICATE feature is not supported.

provision

void provision(Plan plan)
        throws ConnectorException,
               java.lang.UnsupportedOperationException

Evaluate a provisioning plan that specifies operations to be performed on one or more objects. The plan is expected to be modified as a side effect and contain one or more Result objects.

Parameters:

plan - The plan to evaluate.

Throws:

ConnectorException - If the operation fails.

ObjectAlreadyExistsException - If an object already exists on the resource.

java.lang.UnsupportedOperationException - If the an operation in the plan is not supported.

checkStatus

Result checkStatus(java.lang.String id)
            throws ConnectorException,
                   ObjectNotFoundException,
                   java.lang.UnsupportedOperationException

Using the id passed into this method check the request to see if has completed.

This method will be called one time for each ProvisioningResult returned in the ProvisioningPlan during provisioning. The provision method can store results at either the plan, account request or the attribute request level.

The new status, returned result's errors, and warnings will be merged back into the main project.

Returning a null result will have no change on the request and it will remained queued.

Parameters:

id -

Returns:

Result

Throws:

ConnectorException

ObjectNotFoundException

java.lang.UnsupportedOperationException

getConfigOptions

java.util.Map<java.lang.String,java.lang.Object> getConfigOptions(java.lang.String configOptionsKey)
                                                           throws ConnectorException,
                                                                  ObjectNotFoundException,
                                                                  java.lang.UnsupportedOperationException

Parameters:

configOptionsKey -

Returns:

Return a map for config options

Throws:

ConnectorException

ObjectNotFoundException

java.lang.UnsupportedOperationException

supportsPartitionedDeltaAggregation

boolean supportsPartitionedDeltaAggregation()

Gets if the connector supports partitioned delta aggregation

Returns:

true, if connector supports partitioned delta aggregation

destroy

void destroy(java.util.Map<java.lang.String,java.lang.Object> optionsMap)
      throws ConnectorException

Called by aggregator at the end of aggregation

Parameters:

optionsMap - Map of options sent by aggregator

Throws:

ConnectorException

doHealthCheck

java.util.Map doHealthCheck(java.util.Map<java.lang.String,java.lang.Object> options)
                     throws ConnectorException,
                            java.lang.UnsupportedOperationException

Light Weight Test Connection API.Test the connection to the application ,Returns nothing on success and throws an exception (as detailed as possible) when there is a problem

Parameters:

options - : kept null as of now as testConnection() is void Returning , can be used for future extension

Returns:

Map

Throws:

ConnectorException

java.lang.UnsupportedOperationException

setStatisticsCollector

void setStatisticsCollector(StatisticsCollector statisticsCollector)

Set the StatisticsCollector object require for underlying connector to push the aggreagtion statistics. The Object resposible for pushing the aggreagtion statistical data. This is cross cutting concern of recording the statistics which will help in analysis of aggregation performance.

getUtilizationExtract

java.util.Iterator<java.util.Map<java.lang.String,java.lang.Object>> getUtilizationExtract(java.util.Map<java.lang.String,java.lang.Object> requestParams)
                                                                                    throws ConnectorException,
                                                                                           java.lang.UnsupportedOperationException

This method will be called to fetch Utilization extract from ERP Systems requestParams has required details to fetch Utilization extract data.

Parameters:

requestParams - params which will contain information to fetch data from ERP systems.

Returns:

Iterator> iterator which holds actual data returned from connector

Throws:

ConnectorException - instance of ConnectorException in case of failure

java.lang.UnsupportedOperationException - instance of UnsupportedOperationException in case method is not implemented by connectors.

getSecurityExtract

java.util.Iterator<java.util.Map<java.lang.String,java.lang.Object>> getSecurityExtract(java.util.Map<java.lang.String,java.lang.Object> requestParams)
                                                                                 throws ConnectorException,
                                                                                        java.lang.UnsupportedOperationException

This method will be called to fetch Security extract from ERP Systems. requestParams has required details to fetch Security extract data.

Parameters:

requestParams - params which will contain information to fetch data from ERP systems.

Returns:

Iterator

Throws:

sailpoint.connector.ConnectorException - instance of ConnectorException in case of failure

java.lang.UnsupportedOperationException - instance of UnsupportedOperationException in case method is not implemented by connectors.

ConnectorException

getChangeLogExtract

java.util.Iterator<java.util.Map<java.lang.String,java.lang.Object>> getChangeLogExtract(java.util.Map<java.lang.String,java.lang.Object> requestParams)
                                                                                  throws ConnectorException,
                                                                                         java.lang.UnsupportedOperationException

This method will be called to fetch Change log extract from ERP Systems. requestParams has required details to fetch Change log extract data.

Parameters:

requestParams - params which will contain information to fetch data from ERP systems.

Returns:

Iterator

Throws:

sailpoint.connector.ConnectorException - instance of ConnectorException in case of failure

java.lang.UnsupportedOperationException - instance of UnsupportedOperationException in case method is not implemented by connectors.

ConnectorException

getExtractPartitions

java.util.List<java.util.Map<java.lang.String,java.lang.Object>> getExtractPartitions(java.util.Map<java.lang.String,java.lang.Object> requestParams,
                                                                                      java.lang.String extractType)
                                                                               throws ConnectorException,
                                                                                      java.lang.UnsupportedOperationException,
                                                                                      InsufficientPermissionException

This method will be called to get extract Partition for ARM extract requests if user has no required permissions to fetch Security extract from underlying tables it will throw InsufficientPermissionException

Parameters:

requestParams - has required details to fetch extract Partition data

extractType - this contains extract type

Returns:

List

Throws:

ConnectorException - instance of ConnectorException in case of failure

java.lang.UnsupportedOperationException - instance of UnsupportedOperationException in case method is not implemented by connectors.

InsufficientPermissionException - instance of ConnectorException in case of insufficient permissions