elasticsearch/docs/reference/connector/apis/update-connector-configuration-api.asciidoc

[[update-connector-configuration-api]]
=== Update connector configuration API
++++
<titleabbrev>Update connector configuration</titleabbrev>
++++

beta::[]

Updates a connector's `configuration`, allowing for config value updates within a registered configuration schema.

To get started with Connector APIs, check out <<es-connectors-tutorial-api, our tutorial>>.


[[update-connector-configuration-api-request]]
==== {api-request-title}

`PUT _connector/<connector_id>/_configuration`

[[update-connector-configuration-api-prereq]]
==== {api-prereq-title}

* To sync data using self-managed connectors, you need to deploy the <<es-connectors-deploy-connector-service,Elastic connector service>>. on your own infrastructure. This service runs automatically on Elastic Cloud for Elastic managed connectors.
* The `connector_id` parameter should reference an existing connector.
* To update configuration `values`, the connector `configuration` schema must be first registered by a running instance of Elastic connector service.
* Make sure configuration fields are compatible with the configuration schema for the third-party data source. Refer to the individual <<es-connectors-refs,connector references>> for details.

[[update-connector-configuration-api-path-params]]
==== {api-path-parms-title}

`<connector_id>`::
(Required, string)

[role="child_attributes"]
[[update-connector-configuration-api-request-body]]
==== {api-request-body-title}

`values`::
(Optional, object) Configuration values for the connector, represented as a mapping of configuration fields to their respective values within a registered schema.

`configuration`::
(Optional, object) The configuration schema definition for the connector. The configuration field is a map where each key represents a specific configuration field name, and the value is a `ConnectorConfiguration` object. For connector management use `values` to pass config values. The `configuration` object is used by the Elastic connector service to register the connector configuration schema.


[[update-connector-configuration-api-response-codes]]
==== {api-response-codes-title}

`200`::
Connector configuration was successfully updated.

`400`::
The `connector_id` was not provided or the request payload was malformed.

`404` (Missing resources)::
No connector matching `connector_id` could be found.

[[update-connector-configuration-api-example]]
==== {api-examples-title}

The following example configures a `sharepoint_online` connector. Find the supported configuration options in the <<es-connectors-sharepoint-online,Sharepoint Online connector documentation>>, or by inspecting the schema in the connector's `configuration` field using the <<get-connector-api>>.

////
[source, console]
--------------------------------------------------
PUT _connector/my-spo-connector
{
  "index_name": "search-sharepoint-online",
  "name": "Sharepoint Online Connector",
  "service_type": "sharepoint_online"
}

PUT _connector/my-spo-connector/_configuration
{
    "configuration": {
        "tenant_id": {
          "default_value": null,
          "depends_on": [],
          "display": "textbox",
          "label": "Tenant ID",
          "options": [],
          "order": 1,
          "required": true,
          "sensitive": false,
          "tooltip": "",
          "type": "str",
          "ui_restrictions": [],
          "validations": [],
          "value": ""
        },
        "tenant_name": {
          "default_value": null,
          "depends_on": [],
          "display": "textbox",
          "label": "Tenant name",
          "options": [],
          "order": 2,
          "required": true,
          "sensitive": false,
          "tooltip": "",
          "type": "str",
          "ui_restrictions": [],
          "validations": [],
          "value": ""
        },
        "client_id": {
          "default_value": null,
          "depends_on": [],
          "display": "textbox",
          "label": "Client ID",
          "options": [],
          "order": 3,
          "required": true,
          "sensitive": false,
          "tooltip": "",
          "type": "str",
          "ui_restrictions": [],
          "validations": [],
          "value": ""
        },
        "secret_value": {
          "default_value": null,
          "depends_on": [],
          "display": "textbox",
          "label": "Secret value",
          "options": [],
          "order": 4,
          "required": true,
          "sensitive": true,
          "tooltip": "",
          "type": "str",
          "ui_restrictions": [],
          "validations": [],
          "value": ""
        },
        "site_collections": {
          "default_value": null,
          "depends_on": [],
          "display": "textarea",
          "label": "Comma-separated list of sites",
          "options": [],
          "order": 5,
          "required": true,
          "sensitive": false,
          "tooltip": "A comma-separated list of sites to ingest data from. Use * to include all available sites.",
          "type": "list",
          "ui_restrictions": [],
          "validations": [],
          "value": ""
        },
        "use_text_extraction_service": {
          "default_value": false,
          "depends_on": [],
          "display": "toggle",
          "label": "Use text extraction service",
          "options": [],
          "order": 6,
          "required": true,
          "sensitive": false,
          "tooltip": "Requires a separate deployment of the Elastic Data Extraction Service. Also requires that pipeline settings disable text extraction.",
          "type": "bool",
          "ui_restrictions": [
            "advanced"
          ],
          "validations": [],
          "value": false
        },
        "use_document_level_security": {
          "default_value": false,
          "depends_on": [],
          "display": "toggle",
          "label": "Enable document level security",
          "options": [],
          "order": 7,
          "required": true,
          "sensitive": false,
          "tooltip": "Document level security ensures identities and permissions set in Sharepoint Online are maintained in Elasticsearch. This metadata is added to your Elasticsearch documents, so you can control user and group read-access. Access control syncs ensure this metadata is kept up to date.",
          "type": "bool",
          "ui_restrictions": [],
          "validations": [],
          "value": false
        },
        "fetch_drive_item_permissions": {
          "default_value": true,
          "depends_on": [
            {
              "field": "use_document_level_security",
              "value": true
            }
          ],
          "display": "toggle",
          "label": "Fetch drive item permissions",
          "options": [],
          "order": 8,
          "required": true,
          "sensitive": false,
          "tooltip": "Enable this option to fetch drive item specific permissions. This setting can increase sync time.",
          "type": "bool",
          "ui_restrictions": [],
          "validations": [],
          "value": true
        },
        "fetch_unique_page_permissions": {
          "default_value": true,
          "depends_on": [
            {
              "field": "use_document_level_security",
              "value": true
            }
          ],
          "display": "toggle",
          "label": "Fetch unique page permissions",
          "options": [],
          "order": 9,
          "required": true,
          "sensitive": false,
          "tooltip": "Enable this option to fetch unique page permissions. This setting can increase sync time. If this setting is disabled a page will inherit permissions from its parent site.",
          "type": "bool",
          "ui_restrictions": [],
          "validations": [],
          "value": true
        },
        "fetch_unique_list_permissions": {
          "default_value": true,
          "depends_on": [
            {
              "field": "use_document_level_security",
              "value": true
            }
          ],
          "display": "toggle",
          "label": "Fetch unique list permissions",
          "options": [],
          "order": 10,
          "required": true,
          "sensitive": false,
          "tooltip": "Enable this option to fetch unique list permissions. This setting can increase sync time. If this setting is disabled a list will inherit permissions from its parent site.",
          "type": "bool",
          "ui_restrictions": [],
          "validations": [],
          "value": true
        },
        "fetch_unique_list_item_permissions": {
          "default_value": true,
          "depends_on": [
            {
              "field": "use_document_level_security",
              "value": true
            }
          ],
          "display": "toggle",
          "label": "Fetch unique list item permissions",
          "options": [],
          "order": 11,
          "required": true,
          "sensitive": false,
          "tooltip": "Enable this option to fetch unique list item permissions. This setting can increase sync time. If this setting is disabled a list item will inherit permissions from its parent site.",
          "type": "bool",
          "ui_restrictions": [],
          "validations": [],
          "value": true
        },
        "enumerate_all_sites": {
          "default_value": true,
          "depends_on": [],
          "display": "toggle",
          "label": "Enumerate all sites?",
          "options": [],
          "order": 6,
          "required": false,
          "sensitive": false,
          "tooltip": "If enabled, sites will be fetched in bulk, then filtered down to the configured list of sites. This is efficient when syncing many sites. If disabled, each configured site will be fetched with an individual request. This is efficient when syncing fewer sites.",
          "type": "bool",
          "ui_restrictions": [],
          "validations": [],
          "value": true
        },
        "fetch_subsites": {
          "default_value": false,
          "depends_on": [
            {
              "field": "enumerate_all_sites",
              "value": false
            }
          ],
          "display": "toggle",
          "label": "Fetch sub-sites of configured sites?",
          "options": [],
          "order": 7,
          "required": false,
          "sensitive": false,
          "tooltip": "Whether subsites of the configured site(s) should be automatically fetched.",
          "type": "bool",
          "ui_restrictions": [],
          "validations": [],
          "value": true
        }
    }
}
--------------------------------------------------
// TESTSETUP

[source,console]
--------------------------------------------------
DELETE _connector/my-spo-connector
--------------------------------------------------
// TEARDOWN
////

[source,console]
----
PUT _connector/my-spo-connector/_configuration
{
    "values": {
        "tenant_id": "my-tenant-id",
        "tenant_name": "my-sharepoint-site",
        "client_id": "foo",
        "secret_value": "bar",
        "site_collections": "*"
    }
}
----

[source,console-result]
----
{
    "result": "updated"
}
----


When you're first setting up your connector you'll need to provide all required configuration details to start running syncs.
But you can also use this API to only update a subset of fields.
Here's an example that only updates the `secret_value` field for a `sharepoint_online` connector.
The other configuration values won't change.

[source,console]
----
PUT _connector/my-spo-connector/_configuration
{
    "values": {
        "secret_value": "foo-bar"
    }
}
----

[source,console-result]
----
{
    "result": "updated"
}
----