--- title: Configure the server over REST description: IDM exposes configuration objects under the /openidm/config context path. component: pingidm version: 8.1 page_id: pingidm:setup-guide:configuring-over-rest canonical_url: https://docs.pingidentity.com/pingidm/8.1/setup-guide/configuring-over-rest.html keywords: ["Setup & Configuration", "REST"] --- # Configure the server over REST IDM exposes configuration objects under the `/openidm/config` context path. The optional `waitForCompletion` parameter is available to the `config` endpoint for create, update, and patch requests. Requests to the endpoint with `waitForCompletion=true` delay the response until an OSGi service event confirms the change has been consumed by the corresponding service or the request times out. The following server properties support additional configuration of the `waitForCompletion` behavior. For more information, refer to [Property value substitution](using-property-substitution.html). * `openidm.config.waitByDefault` Default Value: `false` Specifies whether to wait for the OSGi service event if the `waitForCompletion` parameter is missing from the request. * `openidm.config.waitTimeout` Default Value: `5000` The amount of time, in milliseconds, to wait for OSGi service events before timing out. To list the configuration on the local host, perform a GET request on `http://localhost:8080/openidm/config`. > **Collapse: Example GET Request** > > The following REST call includes excerpts of the default configuration for an IDM instance started with the `sync-with-csv` sample: > > ``` > curl \ > --request GET \ > --header "X-OpenIDM-Username: openidm-admin" \ > --header "X-OpenIDM-Password: openidm-admin" \ > --header "Accept-API-Version: resource=1.0" \ > http://localhost:8080/openidm/config > { > "_id": "", > "configurations": [ > { > "_id": "router", > "pid": "router", > "factoryPid": null > }, > { > "_id": "info/login", > "pid": "info.f01fc3ed-5871-408d-a5f0-bef00ccc4c8f", > "factoryPid": "info" > }, > { > "_id": "provisioner.openicf/csvfile", > "pid": "provisioner.openicf.9009f4a1-ea47-4227-94e6-69c345864ba7", > "factoryPid": "provisioner.openicf" > }, > { > "_id": "endpoint/usernotifications", > "pid": "endpoint.e2751afc-d169-4a23-a88e-7211d340bccb", > "factoryPid": "endpoint" > }, > ... > ] > } > ``` Single instance configuration objects are located under `openidm/config/object-name`. > **Collapse: Example Audit Output** > > The following example shows the `audit` configuration of the [sync-with -csv sample](../samples-guide/sync-with-csv.html). > > ``` > curl \ > --header "X-OpenIDM-Username: openidm-admin" \ > --header "X-OpenIDM-Password: openidm-admin" \ > --header "Accept-API-Version: resource=1.0" \ > "http://localhost:8080/openidm/config/audit" > { > "_id": "audit", > "auditServiceConfig": { > "handlerForQueries": "json", > "availableAuditEventHandlers": [ > "org.forgerock.audit.handlers.csv.CsvAuditEventHandler", > "org.forgerock.audit.handlers.jms.JmsAuditEventHandler", > "org.forgerock.audit.handlers.json.JsonAuditEventHandler", > "org.forgerock.audit.handlers.json.stdout.JsonStdoutAuditEventHandler", > "org.forgerock.openidm.audit.impl.RepositoryAuditEventHandler", > "org.forgerock.openidm.audit.impl.RouterAuditEventHandler", > "org.forgerock.audit.handlers.syslog.SyslogAuditEventHandler" > ], > "filterPolicies": { > "field": { > "excludeIf": [], > "includeIf": [] > } > }, > "caseInsensitiveFields": [ > "/access/http/request/headers", > "/access/http/response/headers" > ] > }, > "eventHandlers": [ > { > "class": "org.forgerock.audit.handlers.json.JsonAuditEventHandler", > "config": { > "name": "json", > "enabled": { > "$bool": "&{openidm.audit.handler.json.enabled|true}" > }, > "logDirectory": "&{idm.data.dir}/audit", > "buffering": { > "maxSize": 100000, > "writeInterval": "100 millis" > }, > "topics": [ > "access", > "activity", > "sync", > "authentication", > "config" > ] > } > }, > { > "class": "org.forgerock.audit.handlers.json.stdout.JsonStdoutAuditEventHandler", > "config": { > "name": "stdout", > "enabled": { > "$bool": "&{openidm.audit.handler.stdout.enabled|false}" > }, > "topics": [ > "access", > "activity", > "sync", > "authentication", > "config" > ] > } > }, > { > "class": "org.forgerock.openidm.audit.impl.RepositoryAuditEventHandler", > "config": { > "name": "repo", > "enabled": { > "$bool": "&{openidm.audit.handler.repo.enabled|false}" > }, > "topics": [ > "access", > "activity", > "sync", > "authentication", > "config" > ] > } > } > ], > "eventTopics": { > "config": { > "filter": { > "actions": [ > "create", > "update", > "delete", > "patch", > "action" > ] > } > }, > "activity": { > "filter": { > "actions": [ > "create", > "update", > "delete", > "patch", > "action" > ] > }, > "watchedFields": [], > "passwordFields": [ > "password" > ] > } > }, > "exceptionFormatter": { > "type": "text/javascript", > "file": "bin/defaults/script/audit/stacktraceFormatter.js" > } > } > ``` Multiple instance configuration objects are found under `openidm/config/object-name/instance-name`. > **Collapse: Example Multiple Instance Configuration** > > The following example shows the configuration for the CSV connector from the [sync-with-csv sample](../samples-guide/sync-with-csv.html). > > ``` > curl \ > --header "X-OpenIDM-Username: openidm-admin" \ > --header "X-OpenIDM-Password: openidm-admin" \ > --header "Accept-API-Version: resource=1.0" \ > "http://localhost:8080/openidm/config/provisioner.openicf/csvfile" > { > "_id": "provisioner.openicf/csvfile", > "connectorRef": { > "bundleName": "org.forgerock.openicf.connectors.csvfile-connector", > "bundleVersion": "[1.5.19.0,1.6.0.0)", > "connectorName": "org.forgerock.openicf.csvfile.CSVFileConnector" > }, > "operationTimeout": { > "CREATE": -1, > "VALIDATE": -1, > "TEST": -1, > "SCRIPT_ON_CONNECTOR": -1, > "SCHEMA": -1, > "DELETE": -1, > "UPDATE": -1, > "SYNC": -1, > "AUTHENTICATE": -1, > "GET": -1, > "SCRIPT_ON_RESOURCE": -1, > "SEARCH": -1 > }, > "configurationProperties": { > "csvFile": "&{idm.instance.dir}/data/csvConnectorData.csv" > }, > "resultsHandlerConfig": { > "enableAttributesToGetSearchResultsHandler": true > }, > "syncFailureHandler": { > "maxRetries": 5, > "postRetryAction": "logged-ignore" > }, > "objectTypes": { > "account": { > "$schema": "http://json-schema.org/draft-03/schema", > "id": "ACCOUNT", > "type": "object", > "nativeType": "ACCOUNT", > "properties": { > "description": { > "type": "string", > "nativeName": "description", > "nativeType": "string" > }, > "firstname": { > "type": "string", > "nativeName": "firstname", > "nativeType": "string" > }, > "email": { > "type": "string", > "nativeName": "email", > "nativeType": "string" > }, > "name": { > "type": "string", > "required": true, > "nativeName": "NAME", > "nativeType": "string" > }, > "lastname": { > "type": "string", > "required": true, > "nativeName": "lastname", > "nativeType": "string" > }, > "mobileTelephoneNumber": { > "type": "string", > "required": true, > "nativeName": "mobileTelephoneNumber", > "nativeType": "string" > }, > "roles": { > "type": "string", > "required": false, > "nativeName": "roles", > "nativeType": "string" > } > } > } > }, > "operationOptions": {} > } > ``` You can change the configuration over REST by using an HTTP PUT or HTTP PATCH request to modify the required configuration object. > **Collapse: Example PUT Request** > > The following example uses a PUT request to modify the configuration of the scheduler service, increasing the maximum number of threads that are available for the concurrent execution of scheduled tasks: > > ``` > curl \ > --header "X-OpenIDM-Username: openidm-admin" \ > --header "X-OpenIDM-Password: openidm-admin" \ > --header "Content-Type: application/json" \ > --header "Accept-API-Version: resource=1.0" \ > --request PUT \ > --data '{ > "threadPool": { > "threadCount": 20 > }, > "scheduler": { > "executePersistentSchedules": { > "$bool": "&{openidm.scheduler.execute.persistent.schedules}" > } > } > }' \ > "http://localhost:8080/openidm/config/scheduler" > { > "_id": "scheduler", > "threadPool": { > "threadCount": 20 > }, > "scheduler": { > "executePersistentSchedules": { > "$bool": "&{openidm.scheduler.execute.persistent.schedules}" > } > } > } > ``` > **Collapse: Example PATCH Request** > > The following example uses a PATCH request to reset the number of threads to their original value. > > ``` > curl \ > --header "X-OpenIDM-Username: openidm-admin" \ > --header "X-OpenIDM-Password: openidm-admin" \ > --header "Content-Type: application/json" \ > --header "Accept-API-Version: resource=1.0" \ > --request PATCH \ > --data '[ > { > "operation" : "replace", > "field" : "/threadPool/threadCount", > "value" : 10 > } > ]' \ > "http://localhost:8080/openidm/config/scheduler" > { > "_id": "scheduler", > "threadPool": { > "threadCount": 10 > }, > "scheduler": { > "executePersistentSchedules": { > "$bool": "&{openidm.scheduler.execute.persistent.schedules}" > } > } > } > ``` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | Multi-version concurrency control (MVCC) is not supported for configuration objects so you do not need to specify a revision during updates to the configuration, and no revision is returned in the output. | For more information about using the REST API to update objects, refer to the [REST API Reference](../rest-api-reference/preface.html).