-

docs/dashboards.rst

@@ -40,3 +40,187 @@ API.
 - `Elasticsearch <https://www.elastic.co/guide/en/elasticsearch/reference/current/getting-started.html>`_;
 
 - `Kibana <https://www.elastic.co/guide/en/kibana/current/introduction.html>`_.
+
+Индексация данных форм в ARTA Synergy
+-------------------------------------
+
+Запись данных в индекс производится после сохранения данных по форме.
+Первичная загрузка данных в ES осуществляется с помощью процесса индексации
+данных форм (*Административное приложение -> Обслуживание системы -> Управление индексом форм*).
+В это время для каждой формы и каждого компонента этой формы в Synergy
+создается несколько индексов. Каждый из этих индексов будет отображен в
+Kibana со своим кодом, как используемое поле.
+
+Названия индексов и alias-ы
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Для всех данных по форме, принадлежащих реестру с идентификатором ``someRegistryID``,
+создаётся индекс с именем ``<index-prefix>-r-someRegistryID``.
+
+- Для всех данных по форме с идентификатором ``someFormID`` создаётся
+индекс с именем ``<index-prefix>-f-someFormID``.
+
+- Если итоговая длина названия индекса (как для форм, так и для реестров)
+превысит 255 байт, оно будет обрезано до 255 байт.
+
+Таким образом, для каждого реестра и для каждой формы, по которым есть данные,
+будет создано по индексу. Если по форме создан реестр, а также созданы какие-то
+данные вне реестра, то в этом случае будет создано два индекса:
+
+#. ``<index-prefix>-r-IdOfRegistryWithOtherForm``
+
+#. ``<index-prefix>-f-otherID``.
+
+.. note:: `Здесь <https://www.elastic.co/guide/en/elasticsearch/reference/current/_list_all_indices.html#_list_all_indices>`_
+          описано, как получить названия всех имеющихся индексов в Elasticsearch.
+
+Кроме этого, для удобства использования и возможности переноса конфигурации для
+каждого из вышеперечисленных индексов создаётся
+`alias <https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-aliases.html`_.
+Имена alias-ов формируются так:
+
+- Для данных реестров: ``r-нормализованный_код_реестра``
+
+- Для данных форм без реестров: ``f-нормализованный_код_формы``
+где ``нормализованый_код_реестра`` и ``нормализованный_код_формы`` - коды, соответственно,
+реестра и формы, в которых специальные символы \, ., [, ], {, }, (, ), +, -, ?, ^, $, |
+заменяются на _.
+
+.. warning::  При этом возможна ситуация, когда нормализованные коды разных реестров совпадут и alias
+              будет создан на на все соответветствующие индексы. Эта маловероятное затруднение может быть
+              решено изменением кодов соответствующих реестров или форм. В случае, если это невозможно,
+              необходимые alias-ы `можно создать вручную <https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-aliases.html>`_.
+
+              При изменении кода реестра или формы в Synergy имя соответствующего alias-а также изменяется.
+
+##### Структура документа в индексе {#sec.dashboards_form_indexator_doc_structure}
+
+Одна единица данных в индексе Elasticsearch называется *Документ*. Документ содержит
+поля определённых [типов](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-types.html).
+Каждый документ в текущем индексе соответствует одной единице данных по форме (=файлу по форме,
+записи реестра) и содержит следующие поля:
+
+- `asfDataId` - идентификатор данных по форме, тип `keyword`;
+
+- `formId` - идентификатор формы, тип `keyword`;
+
+- `formCode` - код формы, тип `keyword`;
+
+- `registryId` - идентификатор реестра, тип `keyword` (содержит значение `-1` для данных по
+форме, не связанных с реестром);
+
+- `documentId` - идентификатор документа Synergy, тип `keyword`;
+
+- `status` - статус записи реестра, тип `number`:
+
+	- 0 - "Подготовка" (`NO_ROUTE`) - это значение также устанавливается для данных по форме,
+не связанных с реестром
+
+	- 1 - "В процессе" (`STATE_NOT_FINISHED`)
+
+	- 2 - "Активная" (`STATE_SUCCESSFUL`)
+
+	- 3 - "Неуспешная" (`STATE_UNSUCCESSFUL`)
+
+- `deleted` - признак удаления записи реестра (0 - не удалено, 1 - удалено), тип `number`
+(0 для данных по форме, не связанных с реестром);
+
+- `created` - дата и время создания данных по форме, тип `date`;
+
+- `modified` - дата и время изменения данных по форме, тип `date`.
+
+Далее следуют поля, соответствующие компонентам формы:
+
+- Для каждого компонента формы создаётся несколько полей документа в индексе.
+
+- Название полей, соответствующих компоненту формы, формируется так:
+`идентфикаторкомпонентаформывнижнемрегистре_key_постфикс` и
+`идентфикаторкомпонентаформывнижнемрегистре_value_постфикс` (данные для которых берутся,
+соответственно, из полей
+[key и value](../../architecture/html/modules.html#components_format)
+данных по форме).
+
+- Для каждого поля `*_key` и `*_value` создаются поля с нижеперечисленными постфиксами.
+
+- Для компонентов, находящихся внутри динамической таблицы, а также компонентов с
+мультивыбором ("Объекты Synergy"), значения записываются в
+[`массив`](https://www.elastic.co/guide/en/elasticsearch/reference/current/array.html)
+для всех постфиксов с учетом типов компонентов.
+
+- Для компонентов, имеющих `key` и `value`, создается общее поле `*_object`
+([`Object`](https://www.elastic.co/guide/en/elasticsearch/reference/5.3/object.html)).
+
+*Постфиксы для полей `*_key`:*
+
+- `_exact` - поле содержит значение `key`, приведенное к нижнему регистру, тип `keyword`;
+
+- `_sort` - поле содержит точное значение `key`, тип `keyword`;
+
+- `_number` - поле содержит значение `key`, приведенное к числу, тип `number`;
+
+>> **Примечание:**
+
+>> Если поле `key` в документе пусто, в данное поле будет записано максимальное
+значение для типа `long`: 9 223 372 036 854 775 807
+
+- `_date` - поле содержит значение `key`, приведенное к дате; поле присутствует только для
+компонентов Synergy типа "Дата/время"; тип `date`;
+
+- `_double` - поле содержит значение `key`, приведенное к числу, тип `double`;
+
+>> **Примечание:**
+
+>> Данное поле создается только в том случае, если из значения `key` удалось
+выделить число (т.е. есть хотя бы один документ, использующий это поле,
+содержит числовое значение);
+
+- пустой постфикс - поле содержит n-граммы значения `key`, через пробел, тип `text`.
+
+*Постфиксы для полей `*_value`:*
+
+- `_exact` - поле содержит значение `value`, приведенное к нижнему регистру, тип `keyword`;
+
+- `_sort` - поле содержит точное значение `value`, тип `keyword`;
+
+- `_number` - поле содержит значение `value`, приведенное к числу, тип `number`;
+
+>> **Примечание:**
+
+>> Если поле `key` в документе пусто, в данное поле будет записано максимальное
+значение для типа `long`: 9 223 372 036 854 775 807
+
+- `_prefix` - поле содержит возможные префиксы из значения `value`, через пробел, тип `text`;
+
+- `_postfix` - поле содержит возможные постфиксы из значения `value`, через пробел, тип `text`;
+
+- пустой постфикс - поле содержит n-граммы значения `value`, через пробел, тип `text`.
+
+##### Индексы изменения данных (историчные индексы) {#sec.dashboards_form_indexator_history}
+
+Индексы изменения данных создаются только для тех форм и реестров, коды которых подпадают
+под шаблоны (секции в конфигурационном файле `arta/elasticConfiguration.xml`, см. описание выше).
+
+Имя индекса `<index-prefix>-rh-someRegistryID` и `<index-prefix>-fh-someFormID`, для реестров и
+форм, соответственно. Alias-ы: `rh-нормализованный_код_реестра` и `fh-нормализованный_код_формы`.
+
+Отличие индексов изменения данных от текущих индексов - на каждое изменение данных по форме
+создаётся новый документ в индексе. Кроме этого, для компонентов формы создаются только поля
+со следующими постфиксами:
+
+- Для `*_key`:
+
+	- `_exact`
+
+	- `_number`
+
+	- `_date`
+
+	- `_double`
+
+- Для `*_value`:
+
+	- `_exact`
+
+	- `_number`
+
+Типы данных и условия создания полей такие же, как и в текущем индексе.