add asciidoc pages

openidm-doc/pom.xml

@@ -51,6 +51,24 @@
                                     <goal>release</goal>
                                 </goals>
                             </execution>
+                            <execution>
+                                <id>build-man-pages-asciidoc</id>
+                                <phase>package</phase>
+                                <goals>
+                                    <goal>asciidoc-pre-process</goal>
+                                    <goal>antora</goal>
+                                    <goal>asciidoc-to-pdf</goal>
+                                </goals>
+                                <configuration>
+                                    <documents>
+                                        <document>getting-started</document>
+                                        <document>install-guide</document>
+                                        <document>samples-guide</document>
+                                        <document>integrators-guide</document>
+                                        <document>connectors-guide</document>
+                                    </documents>
+                                </configuration>
+                            </execution>
                         </executions>
                         <configuration>
                             <projectName>OpenIDM</projectName>

openidm-doc/src/main/asciidoc/connectors-guide/appendix-interfaces.adoc

@@ -0,0 +1,138 @@
+////
+  The contents of this file are subject to the terms of the Common Development and
+  Distribution License (the License). You may not use this file except in compliance with the
+  License.
+
+  You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
+  specific language governing permission and limitations under the License.
+
+  When distributing Covered Software, include this CDDL Header Notice in each file and include
+  the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
+  Header, with the fields enclosed by brackets [] replaced by your own identifying
+  information: "Portions copyright [year] [name of copyright owner]".
+
+  Copyright 2017 ForgeRock AS.
+  Portions Copyright 2024 3A Systems LLC.
+////
+
+:figure-caption!:
+:example-caption!:
+:table-caption!:
+
+
+[appendix]
+[#appendix-interfaces]
+== OpenICF Interfaces
+
+This chapter describes all of the interfaces supported by the OpenICF framework, along with notes about their implementation. Specific connectors may support only a subset of these interfaces.
+
+[#interface-attributeNormalizer]
+=== AttributeNormalizer
+
+Normalize attributes to ensure consistent filtering.
+
+
+[#interface-AuthenticationApiOp]
+=== Authenticate
+
+Provides simple authentication with two parameters, presumed to be a user name and password. If the connector does not implement the AuthenticateOp interface it can not be used in OpenIDM to provide pass-through authentication.
+
+
+[#interface-BatchApiOp]
+=== Batch
+
+Execute a series of operations in a single request. If a resource does not support batch operations, the connector will not implement the batch operation interface. The OpenICF framework will still support batched requests but the operations will be executed iteratively through the connector.
+
+
+[#interface-ConnectorEventSubscriptionApiOp]
+=== Connector Event
+
+Subscribe for notification of any specified event on the target resource. This operation can be used in the context of IoT device reports, to receive notification of events such as low battery signals, inactive devices, and so on.
+
+
+[#interface-CreateApiOp]
+=== Create
+
+Create an object and return its uid.
+
+
+[#interface-DeleteApiOp]
+=== Delete
+
+Delete an object by its uid.
+
+
+[#interface-GetApiOp]
+=== Get
+
+Get an object by its uid.
+
+
+[#interface-PoolableConnector]
+=== PoolableConnector
+
+Use pools of target resources.
+
+
+[#interface-ResolveUsernameApiOp]
+=== Resolve Username
+
+Resolve an object to its uid based on its username.
+
+
+[#interface-SchemaApiOp]
+=== Schema
+
+Describe supported object types, operations, and options.
+
+
+[#interface-ScriptOnConnectorApiOp]
+=== Script on Connector
+
+Allow script execution on connector.
+
+
+[#interface-ScriptOnResourceApiOp]
+=== Script On Resource
+
+Allow script execution on the resource.
+
+
+[#interface-SearchApiOp]
+=== Search
+
+Allow searches for resource objects.
+
+Connectors that implement __only__ this interface can only be used for reconciliation operations.
+
+
+[#interface-SyncApiOp]
+=== Sync
+
+Poll for synchronization events, which are native changes to target objects.
+
+
+[#interface-SyncEventSubscriptionApiOp]
+=== Sync Event
+
+Subscribe for notification of synchronization events, which are native changes to target objects.
+
+
+[#interface-TestApiOp]
+=== Test
+
+Test the connection configuration, including connecting to the resource.
+
+
+[#interface-UpdateApiOp]
+=== Update
+
+Allows an authorized caller to update (modify or replace) objects on the target resource.
+
+
+[#interface-UpdateAttributeValuesOp]
+=== Update Attribute Values
+
+Allows an authorized caller to update (modify or replace) attribute values on the target resource. This operation is more advanced than the `UpdateOp` operation, and provides better performance and atomicity semantics.
+
+

openidm-doc/src/main/asciidoc/connectors-guide/appendix-options.adoc

@@ -0,0 +1,101 @@
+////
+  The contents of this file are subject to the terms of the Common Development and
+  Distribution License (the License). You may not use this file except in compliance with the
+  License.
+
+  You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
+  specific language governing permission and limitations under the License.
+
+  When distributing Covered Software, include this CDDL Header Notice in each file and include
+  the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
+  Header, with the fields enclosed by brackets [] replaced by your own identifying
+  information: "Portions copyright [year] [name of copyright owner]".
+
+  Copyright 2017 ForgeRock AS.
+  Portions Copyright 2024 3A Systems LLC.
+////
+
+:figure-caption!:
+:example-caption!:
+:table-caption!:
+
+
+[appendix]
+[#appendix-options]
+== OpenICF Operation Options
+
+This chapter describes all of the predefined operation options by the OpenICF framework, along with notes about their use. Specific connectors may support only a subset of these options.
+
+[#operation-option-scope]
+=== Scope
+
+An option to use with Search (in conjunction with link:#operation-option-container[Container]) that specifies how far beneath the specified container to search. Must be one of the following values:
+
+* SCOPE_OBJECT
+
+* SCOPE_ONE_LEVEL
+
+* SCOPE_SUBTREE
+
+
+
+[#operation-option-container]
+=== Container
+
+An option to use with Search that specifies the container under which to perform the search. Must be of type QualifiedUid. Should be implemented for those object classes whose ObjectClassInfo.isContainer() returns true.
+
+
+[#operation-option-run-as-user]
+=== Run as User
+
+An option to use with Script on Resource and possibly others that specifies an account under which to execute the script/operation. The specified account will appear to have performed any action that the script/operation performs.
+
+
+[#operation-option-run-with-password]
+=== Run with Password
+
+An option to use with Script on Resource and possibly others that specifies a password under which to execute the script/operation.
+
+
+[#operation-option-attributes-to-get]
+=== Attributes to Get
+
+Determines which attributes to retrieve during Search and Sync. This option overrides the default behavior, which is for the connector to return exactly the set of attributes that are identified as returned by default in the schema for that connector. This option allows a client application to request additional attributes that would not otherwise not be returned (generally because such attributes are more expensive for a connector to fetch and to format) and/or to request only a subset of the attributes that would normally be returned.
+
+
+[#operation-option-paged-results-cookie]
+=== Paged Results Cookie
+
+An option to use with Search that specifies an opaque cookie which is used by the connector to track its position in the set of query results.
+
+
+[#operation-option-paged-results-offset]
+=== Paged Results Offset
+
+An option to use with Search that specifies the index within the result set of the first result which should be returned.
+
+
+[#operation-option-page-size]
+=== Page Size
+
+An option to use with Search that specifies the requested page results page size.
+
+
+[#operation-option-sort-keys]
+=== Sort Keys
+
+An option to use with Search that specifies the sort keys which should be used for ordering the ConnectorObject returned by search request.
+
+
+[#operation-option-fail-on-error]
+=== Fail on Error
+
+This option is used with the Batch operation, to specify whether the batch process should be aborted when the first error is encountered. The default behavior is to continue processing regardless of errors.
+
+
+[#operation-option-require-serial]
+=== Require Serial
+
+This option instructs the connector to execute batched requests in a serial manner if possible. The default behavior of the Batch operation is to execute requests in parallel, for speed and efficiency. In either case the task ID must be reflected in the response for each task, so that tasks can be correctly reordered.
+
+

openidm-doc/src/main/asciidoc/connectors-guide/appendix-pooling.adoc

@@ -0,0 +1,45 @@
+////
+  The contents of this file are subject to the terms of the Common Development and
+  Distribution License (the License). You may not use this file except in compliance with the
+  License.
+
+  You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
+  specific language governing permission and limitations under the License.
+
+  When distributing Covered Software, include this CDDL Header Notice in each file and include
+  the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
+  Header, with the fields enclosed by brackets [] replaced by your own identifying
+  information: "Portions copyright [year] [name of copyright owner]".
+
+  Copyright 2017 ForgeRock AS.
+  Portions Copyright 2024 3A Systems LLC.
+////
+
+:figure-caption!:
+:example-caption!:
+:table-caption!:
+
+
+[appendix]
+[#appendix-pooling]
+== Connection Pooling Configuration
+
+Certain connectors support the ability to be pooled. For a pooled connector, OpenICF maintains a pool of connector instances and reuses these instances for multiple provisioning and reconciliation operations. When an operation must be executed, an existing connector instance is taken from the connector pool. If no connector instance exists, a new instance is initialized. When the operation has been executed, the connector instance is released back into the connector pool, ready to be used for a subsequent operation.
+
+For an unpooled connector, a new connector instance is initialized for every operation. When the operation has been executed, OpenICF disposes of the connector instance.
+
+Because the initialization of a connector is an expensive operation, reducing the number of connector initializations can substantially improve performance.
+
+To configure connection pooling, set the following values in the connector configuration file `poolConfigOptions` property:
+
+* `"maxObjects"` - the maximum number of connector instances in the pool (both idle and active). The default value is `10` instances.
+
+* `"maxIdle"` - the maximum number of idle connector instances in the pool. The default value is `10` idle instances.
+
+* `"maxWait"` - the maximum period to wait for a free connector instance to become available before failing. The default period is `150000` milliseconds, or 15 seconds.
+
+* `"minEvictableIdleTimeMillis"` - the minimum period to wait before evicting an idle connector instance from the pool. The default period is `120000` milliseconds, or 12 seconds.
+
+* `"minIdle"` - the minimum number of idle connector instances in the pool. The default value is `1` instance.
+
+