Аналитические дашборды
======================

Аналитические дашборды - это набор диаграмм, отображающих состояние
данных в различных представлениях и разрезах. Они предназначены для
упрощения работы по их оценке, обработке, прогнозированию дальнейшего
состояния и принятию решений.

Введение
--------

Для интеграции аналитических дашбордов в Synergy используется
комбинация инструментов **Elasticsearch** и **Kibana**.

`Elasticsearch (ES) <https://www.elastic.co/products/elasticsearch>`_ -
это мощный инструмент для полнотекстового поиска и анализа данных.
Он позволяет быстро загружать, выполнять поиск и анализировать
большие объемы данных. Однако ES не имеет специальной визуальной
оболочки, и его использование возможно с помощью набора специальных
API.

`Kibana <https://www.elastic.co/products/kibana>`_ - это платформа
для анализа и визуализации данных. Kibana обрабатывает данные,
загруженные в ES, и работает только параллельно с ним. Если
работа с ES предполагает использование специального синтаксиса
команд, то Kibana позволяет обрабатывать те же данные с
помощью визуального интерфейса. При этом Kibana содержит
интерпретатор, позволяющий использование всех возможностей и
специальных команд ES.

Индексация и обработка исходных данных Synergy производится с
помощью ES, дальнейший анализ и визуализация - с помощью Kibana.

В настоящем документе будут рассмотрены только некоторые из
возможностей этих инструментов, непосредственно относящиеся
к задаче визуализации данных. Для подробного изучения всех их
возможностей и способов использования рекомендуем обращаться
к официальной документации:

- `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-а также изменяется.

Структура документа в индексе
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Одна единица данных в индексе 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`

Типы данных и условия создания полей такие же, как и в текущем индексе.
