# Configuration

If the App requires configuration and defines configuration form in [configuration\_schema](https://docs.ergonode.com/apps2/manifest#configuration_schema) it has to appropriately handle the values.

It has to be able to validate and persist the configuration and also provide the configuration for reading.

To do so 2 endpoints implementation is necessary.

{% hint style="info" %}
Each endpoint receives an appropriate `X-APP-TOKEN` HTTP header with JWT that allows [authentication](https://docs.ergonode.com/apps2/authentication#authentication-of-the-incoming-request) of the caller.
{% endhint %}

#### \[GET] /configuration

The endpoint should return all so-far persisted schemas in update configuration steps in the form of an array of data - according to your schema.

For example for a simple configuration schema

```json
{
  "configuration_schema": [
    {
      "title": "Connection",
      "type": "object",
      "properties": {
        "token": {
          "type": "string",
          "title": "API token",
          "widget": "password",
          "propertyOrder": 1
        }
      },
      "required": [
        "token"
      ]
    },
    {
      "title": "Settings",
      "type": "object",
      "properties": {
        "setting1": {
          "type": "string",
          "title": "setting 1",
          "propertyOrder": 1
        },
        "setting2": {
          "type": "string",
          "title": "setting 2",
          "propertyOrder": 1
        }
      },
      "required": [
        "text"
      ]
    }
  ]
}
```

the expected response would be

```json
[
  {
    "token": "secret API token"
  },
  {
    "setting1": "user input text 1",
    "setting2": "user input text 2"
  }
]
```

{% hint style="info" %}
Every object represents single form step/one configuration schema.
{% endhint %}

{% hint style="info" %}
Preserving the configured objects under the same indexes as their definitions in the configuration schema is mandatory.
{% endhint %}

#### \[POST] /configuration

The endpoint accepts, validates, and persists in the configuration step.

payload

{% tabs %}
{% tab title="Example" %}

```json
{
  "index": 0,
  "configuration": {
    "text": "user input text"
  }
}
```

{% endtab %}

{% tab title="Schema" %}

```json
{
  "type": "object",
  "properties": {
    "index": {
      "type": "integer",
      "description": "The index of the configuration step from configuration schema."
    },
    "configuration": {
      "type": "object",
      "description": "The form data according to configuration schema."
    }
  },
  "required": [
    "index",
    "configuration"
  ]
}
```

{% endtab %}
{% endtabs %}

All 2xx responses will be treated as success.

#### Error handling

The forms are validated against configuration schema but not all validation can be performed based on JSON schema.

I.e. API token can only be verified in the App.

{% hint style="info" %}
Though the frontend application performs configuration validation on every step it is a good practice to perform full validation in the App as well to limit any potential errors.
{% endhint %}

To assign a custom error message to specific user form fields it is required to return an error response with code 422 and the payload

{% tabs %}
{% tab title="Example" %}

```json
{
  "title": "Form validation errors.",
  "detail": "Token for API is not valid",
  "violations": [
    {
      "propertyPath": "token",
      "title": "Token for API is not valid",
      "template": "Token for %parameter% is not valid",
      "parameters": {
        "%parameter%": "API"
      }
    }
  ]
}
```

{% endtab %}

{% tab title="Schema" %}

```json
{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "The title of an error."
    },
    "detail": {
      "type": "string",
      "description": "Detailed errors description."
    },
    "violations": {
      "type": "array",
      "description": "The list of violations.",
      "items": {
        "type": "object",
        "properties": {
          "propertyPath": {
            "type": "string",
            "description": "Path to the field the violation applies"
          },
          "title": {
            "type": "string",
            "description": "Ready to use message"
          },
          "template": {
            "type": "string",
            "description": "Template of the message"
          },
          "parameters": {
            "type": "object",
            "description": "Parameters of the template"
          }
        }
      }
    }
  },
  "required": [
    "index",
    "configuration"
  ]
}
```

{% endtab %}
{% endtabs %}

All other error codes will be treated with a generic error message.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ergonode.com/apps2/detailed-reference/configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.