Данный конфигурационный файл 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": "Количество заявок" 
		}, 
     }, 
},

Пример настройки виртуальных показателей для случая в названии показателя "один показатель-несколько агрегаций" и с виртуальной агрегацией DEFAULT:

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

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

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

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

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

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

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

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

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

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

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

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

"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

Метаданные

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

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

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

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