Данный конфигурационный файл metadata.json необходим для настройки доступа и обработки ViTalk групп показателей, измерений и атрибутов базы данных. Файл с настройками создается автоматически при первичной конфигурации после авторизации ViTalk от пользователя, указанного в connection.json.

Файл metadata.json обязателен к настройке, т.к. в этом файле, по умолчанию, отключена обработка всех атрибутов измерений. Приступить к настройке файла metadata.json возможно после настройки файла synonyms.json раздела Синонимы.

Перед настройкой необходимо ознакомиться со структурой файла для удобства редактирования.

Конфигурационный файл metadata.json состоит из:

Перечня групп показателей (секция "measure_groups")/
Перечня измерений (секция "dimensions")/

Настройка метаданных

Для настройки групп показателей и измерений в файле metadata,json необходимо:

Перейти по пути расположения файла:
```
/docker-volume/vitalk-core/configuration/metadata.json
```
Просмотреть файл и визуально определить, сколько групп показателей и измерений выгружено, и какие необходимо настроить.

Настройка групп показателей

Каждая группа показателей состоит из показателей в БД (real_measures) и виртуальных показателей (virtual_measures). Секция групп показателей в файле metadata.json имеет следующую структуру:

"measure_groups": {
	"<Название группы показателей из Базы Данных>": {
		"using (Флаг использования)": true/false,
		# Количество показателей в группе: XX,
		"real_measures": {
			"<название показателя из БД>": "<агрегация из БД>",
			"<название показателя из БД>": "<агрегация из БД>"
		}
		"virtual_measures": {
			"<новое название виртуального показателя>": {
				"<агрегация>": "<название показателя>"
			},
			...
		}
	},

	...
}

Чтобы настроить одну или несколько групп показателей в файле metadata.json, необходимо:

Ознакомиться с примером настройки для одной группы показателей, остальные группы показателей настраивать аналогично.
Перейти в секцию measure_groups, выбрать группу показателей.
Настроить для обработки ViTalk текущую группу показателей:
1. Установить значение поля "using": true для текущей группы показателей, если с ней должен работать ViTalk;
2. Установить значение поля "using": false для текущей группы показателей, если с ней не должен работать ViTalk;
3. Пример заполнения флага использования для одной группы показателей:
```
"measure_groups": { 
	"Бюджет доходов и расходов": { 
		"using": true, 
		... 
	},
 	... 
}
```
4. Проверить списки реальных показателей (real_measures) для текущей группы показателей. Для каждого показателя должна быть выгружена текущая агрегация из базы данных: "AVG", "SUM", "MIN", "MAX" или "COUNT". Например, так:
```
"Бюджет доходов и расходов": { 
	"using": true, 
	"real_measures": { 
		"Средний оборот": "AVG", 
		"Количество заявок": "COUNT", 
		... 
	}, 
}
```
5. Заполнить список виртуальных показателей (virtual_measures) для текущей группы показателей. Виртуальный показатель необходим для правильной работы ViTalk для показателей, у которых:
  - В названии встречаются общие слова/фразы с другими показателями.
  - В названии используется название агрегации.
  - Если вы хотите, чтобы к показателю автоматически применялись фильтры.
  Примеры показателей, для которых нужно завести виртуальные показатели: Минимальный оборот, Средний оборот, Средний максимальный оборот.
  
  Пример настройки виртуальных показателей для случая "один показатель-одна агрегация":

В разделе настроек virtual_measures для агрегации необходимо указывать название показателя из БД (см. раздел real_measures). Названия показателей должны полностью совпадать, включая регистр.

"Бюджет доходов и расходов": { 
	"using": true, 
    "real_measures": { 
		"Средний оборот": "AVG", 
		"Количество заявок": "COUNT", 
		"Максимальный оборот": "MAX"
            }, 
	"virtual_measures": { 
		"оборот": { 
			"AVG": "Средний оборот", 
			"MAX": "Максимальный оборот" 
		}, 
        "заявки": { 
			"COUNT": "Количество заявок" 
		}, 
     }, 
},

При работе с ViTalk, в зависимости от упомянутой пользователем (вместе с виртуальным показателем) агрегации (покажи число заявок) выбирается соответствующей показатель из БД. Если агрегация не упомянута (покажи заявки), то ViTalk выбирает показатель, указанный для спец. агрегации DEFAULT. Пример настройки виртуальных показателей для случая в названии показателя "один показатель-несколько агрегаций" и с виртуальной агрегацией DEFAULT:

В разделе настроек virtual_measures для агрегации необходимо указывать название существующего виртуального показателя (см. раздел virtual_measures). Названия показателей должны полностью совпадать, включая регистр, как в примере ниже с виртуальным показателем "Минимальный оборот".

"Оборотные средства": { 
	"using": true, 
    "real_measures": { 
		"Средний оборот": "AVG", 
		"Минимальный оборот": "MIN", 
		"Средний минимальный оборот": "AVG"
            }, 
	"virtual_measures": { 
		"оборот": { 
			"MIN": "Минимальный оборот", 
			"AVG": "Средний оборот", 
		}, 
		"Минимальный оборот": { 
			"AVG": "Средний минимальный оборот", 
           	"DEFAULT": "Минимальный оборот" 
     	}, 
	},
},

Настройка фильтров по умолчанию

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

"Показатели выполнения плана": {
	"using": true, 
	"real_measures": {
		"Прибыль": "SUM"
	}
	"virtual_measures": {
		"Плановая прибыль": {
			"DEFAULT": "Прибыль",
			"SUM": "Прибыль",
			"filters": [
				{
					"dimension_role": "Календарь", # или другое календарное ролевое измерение. Если измерение не ролевое, используется ключ "dimension"
					"type": "INCLUDE", # или EXCLUDE, если мы хотим исключить диапазон
					"dates": [
						{
							"from": {
								"position": "BEGIN", # позиции бывают BEGIN, END и CURRENT. 
								"year": 0 # Мы указываем, что хотим период с начала текущего года.
										  # 0 - это отступ от текущего года. Например, чтобы показать с начала прошлого года, 0 нужно заменить на -1
							},
							"to": {
								"position": "END",
								"month": -1 # до окончания прошлого месяца
							}
						}
					]
				}
			]
		}
	}
}

Таким образом, настраиваются фильтры на даты.

Некалендарные фильтры можно построить следующим образом.

"Финансовые показатели": {
	"using": true, 
	"real_measures": {
		"Прибыль": "SUM"
	}
	"virtual_measures": {
		"Столичная прибыль": {
			"DEFAULT": "Прибыль",
			"SUM": "Прибыль",
			"filters": [
				{
					"dimension_role": "Филиал", # у ГП должна быть связь с ролевым измерением "Филиал"
					"attribute": "Город", #
					"type": "INCLUDE", # или EXCLUDE
					"values": ["Москва", "Санкт-Петербург"]
				}
			]
		}
	}
}

Полученный показатель "столичная прибыль" при запросе будет автоматически отфильтровываться до филиалов в Москве и Санкт-Петербурге.

Настройка измерений

Используемые измерения описываются через их атрибуты и роли. Секция измерений имеет вид:

"dimensions": {
	"<название измерения>": {
		"using (Флаг использования)": true/false,
		"attributes": {
			"<название атрибута>": "<способ обработки атрибута: exact/soft/binary/ignore/only_splitting>",
			"<название атрибута>": "<способ обработки атрибута: exact/soft/binary/ignore/only_splitting>",
			...
		}
		"roles": {
			"<название группы показателей>": {
				# используется ли роль в ViTalk
				"<название роли измерения>": true/false,
				"<название роли измерения>": true/false,
				...
			},
			...
		}
	},
	...
}

Календарное измерение и его атрибуты обрабатываются ViTalk отдельно.

Не рекомендуется менять в настройках атрибутов Календарного измерения что-либо, кроме, возможно, настроек ролей.

Для настройки измерений необходимо:

Ознакомиться с примером настройки измерения, остальные измерения настраивать аналогично.
Для каждого измерения:
1. Указать, будет ли ViTalk обрабатывать измерение, при помощи флага using.
```
"dimensions": {
   "Заказы": {
     "using": true,
	 ....
	},
   .....
}
```
2. Настроить способы обработки атрибутов измерения.
  Для этого, в секции attributes выбранного измерения, для каждого атрибута необходимо выставить одну из четырёх настроек - exact, soft, binary, ignore или only_splitting:

Рекомендации настроек "exact", "soft", "ignore" и "only_splitting":

"exact" – для атрибутов с количеством значений больше 2000, при поиске важно точное совпадение. Например, точный "ИНН" "77001423876", или "Года выпуска автомобиля" (не связан в базе с Календарным измерением) требуется точное совпадения значения атрибута "1963".

"soft" – для атрибутов с количеством значений менее 2000, при поиске будет применяться контекстный поиск по смыслу словосочетания или слова.

"binary" – для атрибутов, имеющих лишь два противоположных значения ("True"/"False", "Да"/"Нет", "+"/"-", "Присутствует"/"Отсутствует", ...).

"ignore" – исключить измерение и атрибут из обработки ViTalk.

"only_splitting" – для атрибутов, по которым необходимо разбивать и детализировать выводимые значения, но нет необходимости искать точное значение атрибута, например,

"Единицы измерения", "Краткое наименование", "Валюты".

При первичной генерации файла metadata.json проставлены автоматически следующие настройки для измерений и атрибутов:

"ignore" – для всех атрибутов измерений.

с. Настроить роли измерения. Для каждой роли измерения в сгенерированном файле metadata.json необходимо указать либо значение true (роль используется в ViTalk), либо false (роль не используется в ViTalk). По умолчанию ViTalk работает со всеми ролями измерения.

d. Пример настроенного измерения:

{
 "dimensions": {
   "Заказы": {
     "using": true,
     "attributes": {
       "Регион, Город": "soft",
       "Заказы, Номер заказа": "exact",
       "Покупатель, Возраст покупателя": "ignore"
     },
     "roles": {
       "Бюджет доходов и расходов": {
         "Отправленные заказы": true,
         "Заказы, ожидающие отправления": false,
       }
     }
   }
 }
}

Завершение настройки ViTalk

После настройки измерений и групп показателей, можно приступить к завершающему этапу настройки ViTalk:

Сохранить изменения в файле metadata.json.
Перейти в браузер в открытую вкладку vitalk-client,.
Нажать кнопку "Обучить" под сообщением "Конфигурация метаданных загружена успешно. Ошибок не обнаружено...".
В случае необходимости конвертации данных нажать "Далее", дождаться окончания конвертации. Нажать "Далее" для дальнейшего обучения.

5. Подождать некоторое время (зависит от размера метаданных базы данных).

Для небольших баз данных с количеством значений атрибутов до 12000 процесс обучения может занимать от 1 минуты до 10 минут.

Для удобства отображается количество обработанных значений и всего значений метаданных.

6. Нажать "Далее" до тех пор, пока не появится сообщение "ViTalk успешно обучен....", как на рисунке:

7. Нажать кнопку "Запустить" инициализацию.

8. Нажать кнопку "Далее".

9. В браузере при успешной настройке ViTalk отображается сообщение "У вас нет прав доступа к данным...."

В процессе настройки ViTalk, в зависимости от действий пользователя и корректности заполнения настроек Администратором, неизвестные инциденты документируются. Перечень инцидентов при настройке ViTalk содержится в разделе Основные инциденты при настройке ViTalk.

Браузер не поддерживается