How to develop connectors using the SQL framework
|
Since 4.11
This functionality is available since version 4.11.
|
This section provides a reference and development guidance on building connectors with the Polygon SQL framework.
Like the SCIMREST framework, the SQL framework is designed using the terminology of the ConnId framework, so it is recommended to have a basic understanding of the ConnID architecture and terminology.
Documentation structure
The SQL connector tutorial is organized as progressive steps:
| Page | Description |
|---|---|
Reference for SQL framework connector configuration properties: JDBC connection, connection pool, scan filters, and development mode. |
|
How the SQL framework automatically discovers database tables and columns via JDBC metadata, maps them to ConnId object classes and attributes, and applies built-in mapping rules. |
|
Reference for the SQL schema script Groovy DSL: objectClass and sql blocks, attribute and connId blocks, SQL type specification, onlyExplicitlyListed and readOnly, read-only joined attributes, with complete examples. |
|
Declarative YAML support in the SQL Framework — connector manifest, native YAML schema documents, and operation documents as an alternative to Groovy scripts. |
|
How built-in search works in the SQL framework, the ConnId-to-SQL filter translation matrix, searching by UID, and refining the built-in WHERE clause. |
|
How to implement a custom SQL search query in an SQL framework connector with the full query DSL: table, select, from, where, orderBy, and filter value access. |
|
How the built-in SQL create operation works: UID handling, generated keys, emulated NAME, composite UIDs, transactional read-back, and enable/disable configuration. |
|
How the built-in SQL update operation applies ConnId deltas to a database row transactionally, which attributes are not updatable, and how to enable or disable update per object class. |
|
How the built-in SQL delete operation removes a row by exact UID transactionally, error handling, and enable/disable configuration per object class. |
|
How the SQL framework detects child-table and junction-table relationships from foreign keys and naming conventions, and how detected relationships are exposed as multi-valued attributes resolved at search time. |
|
How the SQL Framework writes child-table and junction-table rows through the parent object class during create, update, and delete — ordering, validations, and transaction semantics. |
|
How to build a custom SQL framework connector: manifest-based connectors, subclassing AbstractGroovySqlConnector, script loading, and packaging the connector bundle. |
|
Per-database differences and gotchas for the SQL Framework: dialect behavior, capabilities matrix, driver bundling, and connection URL tips. |
Initial development steps
If you are starting with the Polygon SQL framework, start building a connector capable only of the read operations. Then, continue with the more complex create, update, and delete operations.
Read-only connector
-
Obtain the documentation for the database/schema that the connector will read from
-
Determine the connection & authentication parameters (JDBC URL, user, password)
-
Implement (or configure) test connection using Connector configuration
-
Determine the list of object classes and their attributes - discovery is automatic, verify the discovered schema in development mode
-
SQL search and filter support - Verify search works for each object class, including searching by
__UID__ -
Determine relationships (child tables, references) between object classes, Multitable support: child tables and junction tables - verify detected relationships
-
(optional) SQL schema customization - customize naming or attribute set
Read-write connector
In addition to the read-only steps:
-
SQL create operation - Verify create works for writable object classes
-
SQL update operation - Verify update works for writable object classes
-
SQL delete operation - Verify delete works for writable object classes
-
Writing to child and junction tables - Verify writing to related (child/junction) tables for object classes with detected relationships
See also
-
Introduction to SCIMREST framework - The sibling SCIMREST framework for REST/SCIM 2.0 based connectors