[[update-connector-configuration-api]] === Update connector configuration API ++++ Update connector configuration ++++ 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//_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} ``:: (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" } ----