From 307fbd1174186543102b701456421b4c7fd42cb1 Mon Sep 17 00:00:00 2001 From: Thomas Georgios Giannos Date: Mon, 13 May 2024 12:23:22 +0300 Subject: [PATCH] Added docs for prefilling configurations --- .../blueprints/prefilling-configurations.md | 70 ++++++++++++++++++- .../administration/reference-types.md | 2 +- 2 files changed, 70 insertions(+), 2 deletions(-) diff --git a/docs/docs/documentation/administration/blueprints/prefilling-configurations.md b/docs/docs/documentation/administration/blueprints/prefilling-configurations.md index ef6b4ee0f..5d823359a 100644 --- a/docs/docs/documentation/administration/blueprints/prefilling-configurations.md +++ b/docs/docs/documentation/administration/blueprints/prefilling-configurations.md @@ -45,4 +45,72 @@ You can also clear any filters already applied, by pressing the `clear all filte ## Edit form -TODO: thgiannos \ No newline at end of file +Let's explore all the available configuration options for a prifilling source. The first thing we specify is a label for it. This label will be displayed on the prefilling source selection menus. All the other options are grouped in the following form parts. + +### Fixed value fields form + +Here we specify the static fields. These are the fields that relate with one of the available system targets, being `Label`, `Description` and `Tags`, or other custom static fields. We can add one or more fields by pressing the `Add Field` button. For every field we add, we can specify the following. + +- **System Target**: Specify the system target, if the field is related. +- **Semantic Target**: Please refer to the [semantics](/docs/documentation/administration/blueprints/semantics) section. +- **Trim Regex**: A regular expression used to trim the field value. +- **Fixed Value**: The value of the field. + +### API fields + +Here we specify the dynamic fields, coming from the API we will configure in the next sections of the form. We can add one or more fields by pressing the `Add Field` button. For every field we add, we can specify the following. + +- **Code**: An identifier for the field. +- **System Target**: Specify the system target, if the field is related. +- **Semantic Target**: Please refer to the [semantics](/docs/documentation/administration/blueprints/semantics) section. +- **Trim Regex**: A regular expression used to trim the field value. + +When we are done adding or updating our fields, we need to press the `Submit Fields` button in order to update an important part of our configurations form, the field mappings section of the source API configuration, coming up next. + +### Search source configuration + +Here we configure the API endpoint for the search queries + +- **Key**: An identification key for our source.
*Used internally by the system.* +- **Label**: A display name for our source. +- **Ordinal**: This specifies the order in which the source will be called. +- **Url**: The url of our source. +- **Pagination Path**: The path inside the response in which the pagination information is located. This is only needed if the results are coming paginated from the source. +- **Content Type**: The content type of the responses of the source.
*In most cases, this is `application/json`.* +- **First Page**: We can specify the first page to be different than the default 0. +- **HTTP Method**: The http method the source expects. This can either be `GET` or `POST`. +- **Filter Type**: How filtering is handled when this source is used. This can be set as `local` or `remote`.
*In most cases, this is `remote`, meaning that the source handles the filtering. If set to `null`, the filtering (if any) is also handled remotely by the source.* + +#### Field mappings section + +Here we specify where the fields we have specified above can be found on the API response body. + +- **Code**: The id of the field. +- **Pesponse Path**: The [JSONPath](https://goessner.net/articles/JsonPath/) on the sesponse, where this field maps to. + +#### Authentication section + +Some APIs require authentication. In this section we can specify the information about how our source API handles authentication. It is optional, and the form can be enabled by checking the `Authentication` checkbox. The options we have are the following: + +- **Url**: The url where the API listens for authentication. +- **HTTP Method**: The HTTP method for the authentication request. +- **Token Path**: The path of the token, concatinated after the token type.
*In most cases, it is `null`.* +- **Type**: The token type.
*In most cases, it is `Bearer`.* +- **Request Body**: The body contents of the request, if required. + +#### Queries section + +In this section we can specify query parameters we can apply to our requests. + +- Name: The name of the query parameter.
*For example, `like`.* +- Default Value: The default value of the parameter.
*This is optional.* + +### Get source configuration + +The contents of this form are identical with the previous section. The difference here, is that we configure the API endpoint that fetches a specific source item. We also specify the API field mappings as we do for the source configuration, if added previously. + +:::info + +This section is optional. It appears if we click the `Get Source Configuration` checkbox on the previous section, and is used if the API we configure supports this type of requests. + +::: \ No newline at end of file diff --git a/docs/docs/documentation/administration/reference-types.md b/docs/docs/documentation/administration/reference-types.md index 7a933c506..a5e24f9a3 100644 --- a/docs/docs/documentation/administration/reference-types.md +++ b/docs/docs/documentation/administration/reference-types.md @@ -134,7 +134,7 @@ In this section we can specify query parameters we can apply to our requests. :::tip -The path fields on this form are using the [JsonPath](https://github.com/json-path/JsonPath) format. +The path fields on this form are using the [JSONPath](https://goessner.net/articles/JsonPath/) format. :::