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

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

preview::[]

Updates a connector's `configuration`, allowing for complete schema modifications or individual value updates within a registered configuration schema.


[[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 connectors, it's essential to have the Elastic connectors service running.
* The `connector_id` parameter should reference an existing connector.
* The configuration fields definition must be compatible with the specific connector type being used.

[[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 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.

Each `ConnectorConfiguration` object contains the following attributes:

* `category` (Optional, string) The category of the configuration field. This helps in grouping related configurations together in the user interface.

* `default_value` (Required, string | number | bool) The default value for the configuration. This value is used if the value field is empty, applicable only for non-required fields.

* `depends_on` (Required, array of `ConfigurationDependency`) An array of dependencies on other configurations. A field will not be enabled unless these dependencies are met. Each dependency specifies a field key and the required value for the dependency to be considered fulfilled.

* `display` (Required, string) The display type for the UI element that represents this configuration. This defines how the field should be rendered in the user interface. Supported types are: `text`, `textbox`, `textarea`, `numeric`, `toggle` and `dropdown`.

* `label` (Required, string) The display label for the configuration field. This label is shown in the user interface, adjacent to the field.

* `options` (Required, array of `ConfigurationSelectOption`) An array of options for list-type fields. These options are used for inputs in the user interface, each having a label for display and a value.

* `order` (Required, number) The order in which this configuration appears in the user interface. This helps in organizing fields logically.

* `placeholder` (Required, string) Placeholder text for the configuration field. This text is displayed inside the field before a value is entered.

* `required` (Required, boolean) Indicates whether the configuration is mandatory. If true, a value must be provided for the field.

* `sensitive` (Required, boolean) Indicates whether the configuration contains sensitive information. Sensitive fields may be obfuscated in the user interface.

* `tooltip` (Optional, string) Tooltip text providing additional information about the configuration. This text appears when the user hovers over the info icon next to the configuration field.

* `type` (Required, string) The type of the configuration field, such as `str`, `int`, `bool`, `list`. This defines the data type and format of the field's value.

* `ui_restrictions` (Required, array of strings) A list of UI restrictions. These restrictions define where in the user interface this field should be available or restricted.

* `validations` (Required, array of `ConfigurationValidation`) An array of rules for validating the field's value. Each validation specifies a type and a constraint that the field's value must meet.

* `value` (Required, string | number | bool) The current value of the configuration. This is the actual value set for the field and is used by the connector during its operations.

`ConfigurationDependency` represents a dependency that a configuration field has on another field's value. It contains the following attributes:

* `field` (Required, string) The name of the field in the configuration that this dependency relates to.

* `value` (Required, string | number | bool) The required value of the specified field for this dependency to be met.

`ConfigurationSelectOption` defines an option within a selectable configuration field. It contains the following attributes:

* `label` (Required, string) The display label for the option.

* `value` (Required, string) The actual value associated with the option.

`ConfigurationValidation` specifies validation rules for configuration fields. Each ConfigurationValidation instance enforces a specific type of validation based on its type and constraint. It contains the following attributes:

* `constraint` (Required, string | number) The validation constraint. The nature of this constraint depends on the validation type. It could be a numeric value, a list, a regular expression pattern.

* `type` (Required, ConfigurationValidationType) The type of validation to be performed. Possible values include: `less_than`, `greater_than`, `list_type`, `included_in`, `regex` and `unset`.


[[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 updates the `configuration` for the connector with ID `my-connector`:

////
[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": {
        "client_id": {
            "default_value": null,
            "depends_on": [],
            "display": "text",
            "label": "Client ID",
            "options": [],
            "order": 3,
            "required": true,
            "sensitive": false,
            "tooltip": null,
            "type": "str",
            "ui_restrictions": [],
            "validations": [],
            "value": null
        },
        "secret_value": {
            "default_value": null,
            "depends_on": [],
            "display": "text",
            "label": "Secret value",
            "options": [],
            "order": 4,
            "required": true,
            "sensitive": true,
            "tooltip": null,
            "type": "str",
            "ui_restrictions": [],
            "validations": [],
            "value": null
        }
    }
}
--------------------------------------------------
// TESTSETUP

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

This example demonstrates how to register a `sharepoint_online` connector configuration schema. Note: The example does not cover all the necessary configuration fields for operating the Sharepoint Online connector.

[source,console]
----
PUT _connector/my-spo-connector/_configuration
{
    "configuration": {
        "client_id": {
            "default_value": null,
            "depends_on": [],
            "display": "text",
            "label": "Client ID",
            "options": [],
            "order": 3,
            "required": true,
            "sensitive": false,
            "tooltip": null,
            "type": "str",
            "ui_restrictions": [],
            "validations": [],
            "value": null
        },
        "secret_value": {
            "default_value": null,
            "depends_on": [],
            "display": "text",
            "label": "Secret value",
            "options": [],
            "order": 4,
            "required": true,
            "sensitive": true,
            "tooltip": null,
            "type": "str",
            "ui_restrictions": [],
            "validations": [],
            "value": null
        }
    }
}
----

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

An example to update configuration values for the `sharepoint_online` connector:

[source,console]
----
PUT _connector/my-spo-connector/_configuration
{
    "values": {
        "client_id": "my-client-id",
        "secret_value": "super-secret-value"
    }
}
----

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


An example to update single configuration field of the `sharepoint_online` connector. In this case other configuration values won't change:

[source,console]
----
PUT _connector/my-spo-connector/_configuration
{
    "values": {
        "secret_value": "new-super-secret-value"
    }
}
----

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