Первичные настройки
=================================

Для общей работоспособности
---------------------------------

В подсистеме администрирования:
    * обновить БД
    * завести пользователей и орг.структуру (Либо настроить синхронизацию с AD), в которой будут:
        * Системный пользователь (создается до установки Synergy ITSM, должен быть назначен на должность)
        * Инициаторы обращений
        * Операторы Первой линии
        * Исполнители Второй линии (Количество уровней исполнения можно увеличить).
    * Добавить пользователей в группы:
        * Первая линия - всех операторов первой линии
        * Вторая линия - всех исполнителей второй линии
        * itsm_group_reassign_access - Пользователи, которым предоставляется доступ к Переназначению обращений, находящихся на исполнении.
        * itsm_group_admin - Администраторы и системный пользователь.
        * itsm_group_button_rfc - пользователи, для которых доступна кнопка "Запрос на изменение" для создания запросов из обращений.  
        * itsm_group_priority_change - пользователи с доступом на смену приоритета обращения


*Примечание*. Обязательно необходимо добавить системного пользователя в группу itsm_group_admin. 

В Конфигураторе:

1. В справочник Форм завершения добавить новые формы завершения для обращения, проблемы, запроса на изменение и изменения, базы знаний следующим образом:

ФЗ инцидента: код **itsm_completion_form_new**

.. figure:: _static/Configurator_wcf.png

        Рис. 

ФЗ проблемы: код **itsm_problem_completion_form_new**

.. figure:: _static/Configurator_wcf_problem.png

        Рис. 

ФЗ запроса на изменение: код **itsm_rfc_completion_form_new**

.. figure:: _static/Configurator_wcf_rfc.png

        Рис. 

ФЗ изменения: код **itsm_change_completion_new**

.. figure:: _static/Configurator_wcf_change.png

        Рис. 
        
ФЗ базы знаний: код **itsm_knowledgebase_completion_new**

.. figure:: _static/knowledgebase_completion.jpg

        Рис. 
        
        

А также добавить форму завершения без подтверждения:

.. figure:: _static/completion_form.png


2. На формах:
    * в форме “Обращение” вставить значения оператора, исполнителя, системного пользователя по умолчанию
    * в форме “Проблема” вставить значения ответственного менеджера, исполнителя, системного пользователя по умолчанию
    * в форме “Изменение” вставить значение ответственного за координацию изменений в ИТ/администратора системы, владельца БП, ответственного за релиз, бизнес-аналитика, разработчика, тестировщика, системного пользователя по умолчанию
    * в форме "Запрос на изменение RFC" вставить значение ответственного за координацию изменений в ИТ/администратора системы, CAB, системного пользователя по умолчанию
    
3. Проверить/уточнить права на реестры, а также на фильтры реестров для правильного отображения на АРМ. Обязательно для пользователей, которые подают на портале обращения, дать права на реестр Обращения.

4. Сбросить значения счетчиков, либо при необходимости создать свои шаблоны номеров для идентификаторов и применить их в соответствующих формах

5. Прописать логин/пароль системного пользователя для всех скриптов Блокирующих процессов.

6. Для реестра "Заявка на права доступа" в маршруте активации для работы "Прошу назначить права доступа" указать требуемого ответственного.

7. Для реестра "База знаний" в маршруте активации для согласования "Прошу согласовать" указать требуемого ответственного.

8. Для внешнего модуля "Связи конфигурацинных единиц" указать группы доступа.



В пользовательской части:

1. Создать и заполнить одну запись в реестре “Настройки портала” и после этого для всех групп закрыть доступ на создание и удаление в этом реестре (необходимо для корректной работы портала):

.. figure:: _static/portal_settings.png

2. Создать и заполнить хотя бы одну запись реестра "Сервисы" для возможности запуска обращения по маршруту.

3. Для отправки уведомлений из системы настроить в системе администрирования "Настройки уведомлений", это описано в следующей главе "Настройка интеграции с почтой". Нужно создать одну запись реестра "Настройки уведомлений" и проверить, что уведомление к статусу "Ожидает ответа пользователя" (код 4) содержит в тексте `#>Описание:`.

4. Для настройки универсальных уведомлений создать и заполнить одну запись в реестре "Универсальные уведомления": указать код реестра, код поля (полей) пользователей/групп, на email'ы которых нужно отправить уведомления, а также тему и текст уведомления. В соответствующее место маршрута необходимо поставить блок-процесс `event.blocking.interpreter.notifications`.

.. figure:: _static/universal_notifications.png

5. Для работы АРМ необходимо создать одну запись реестра "Настройки АРМ" и для уведомления о заполнении дефолтными значениями указать ОК. После этого таблица "Настройки реестров" заполнится значениями.

.. figure:: _static/arm_settings.png  



Если в АРМ необходимо работать с оргстрктурурой - необходимо дополнительно добавить несколько строк в дин.таблицу:
 * Родительский объект `Оргструктура` (Родитель == да)
 * Дочерние реестры: 
     * Назначение на должность (`str_registry_appointment`), 
     * Перевод на новую должность (`str_registry_reassignment`), 
     * Увольнение с должности (`str_registry_dismissal`),
     * Создание подразделения (`str_registry_depart`),
     * Создание должности (`str_registry_position`).


При обновлении приложения АРМ 
-----------------------------------------
Если до обновления у вас уже был установлен Конструктор с приложением АРМ, код которого ``itsm-arm``, то из-за особенностей загрузки конфигурации в Конструкторе приложений 
после обновления будет 2 приложения: старое и новое. При этом по умолчанию активным будет именно старое приложение. Поэтому все следующие действия сводятся к трем шагам:

1. В старом приложении освободить дефолтные код и URL.

2. В новом приложении настроить дефолтные код и URL.

3. Передеплоить приложение со стороны сервера.

Во-вторых, настроить обновленное приложение в Конструкторе:

* Открыть Конструктор приложений по адресу ``http://адрес_сервера:порт/constructor`` (например: http://192.168.4.80:8080/constructor) и авторизоваться под Системным пользователем.

* Открыть старое приложение с кодом и URL ``itsm-arm`` и выполнить следующие действия в нем:

    * выбрать меню "Клиент" -> "Свойства";
    * изменить название на любое значение, отличное от исходного (для примера подойдет ``АРМ сотрудника ITSM Old``);
    * изменить код и URL на любое значение, отличное от исходного ``itsm-arm`` (для примера подойдет ``itsm-arm1``);
    * сохранить изменения.

* Открыть новое приложение с названием ``АРМ сотрудника ITSM_IMPORTED`` и выполнить следующие действия в нем:

    * выбрать меню "Клиент" -> "Свойства";
    * изменить название на любое значение, отличное от исходного ``АРМ сотрудника ITSM_IMPORTED`` (для примера подойдет название по умолчанию ``АРМ сотрудника ITSM``);
    * изменить код и URL строго на значение ``itsm-arm``;
    * сохранить изменения;
    * выбрать меню "Клиент" -> "Деплой".

В-третьих, передеплоить приложение со стороны сервера:

* Перейти в папку ``deployments``:

    .. code-block:: html 

	# cd /opt/synergy/jboss/standalone/deployments

* Выполнить команду:

    .. code-block:: html 

	# touch itsm-arm.war.dodeploy



Для работоспособности дашбордов:
-----------------------------------------


В интерфейсе Synergy:
    * создать хотя бы по одной тестовой записи в реестрах “Обращения” и “Проблемы”
    
В подсистеме администрирования:
    * проиндексировать данные форм
    
В конфигураторе:  
    * заменить во внешних модулях адрес приложения актуальной ссылкой на дашборды Kibana (полностью заменить ссылку):
    
        -  для “Аналитика по инцидентам” - дашборд "Аналитика по обращениям"
        -  для “Аналитика по проблемам” - дашборд "Проблемы"

В Kibana:
    * автоматически будут созданы шаблоны индексов: ``r-itsm_registry_incidents`` и ``r-itsm_registry_problems``, а также созданы дашборды по инцидентам и проблемам
    * проверить, что всё загрузилось, в дашбордах отсутствуют визуализации, помеченные «!» (при этом возможно наличие визуализаций со значениями “0”, “?”, “No results found”, и это всё не является ошибкой)

В клиентской части:
    * проверить работоспособность обоих дашбордов
    * для отображения дашбордов на АРМ необходимо создать записи в реестре Дашборды, указав: 
    
         * Название дашборда
         * URL дашборда
         * Есть ли выбор периода?
         * Показывать ли дашборд?
         * Группу доступа к данному дашборду (в виде группы, не пользователя)
   

    
Для реализации дашборда "Облако тегов"
-----------------------------------------

Данный дашборд отображает самые часто встречающиеся слова в поле "Тема"/"Описание" обращения, частота соответствует размеру текста. Чем чаще встречается то или иное слово, тем больше его шрифт. Таким образом, можно определить с чем чаще всего возникают проблемы.

Для того чтобы исключить слова, которые повторяются, но не несут важности для пользователя, создан "Реестр исключений". Примеры слов: доброе, утро, не, работает и т.д.

.. figure:: _static/exceptions.jpg

        Рис. Реестр исключений

Так как одно слово может быть использовано с разными окончаниями, для группирования создан "Реестр синонимов". Например, в обращении могут использоваться слова: принтер, принтеру, принтера. Чтобы все эти слова воспринимались на визуализации как "принтер", необходимо заполнить его в Реестре синонимов.

.. figure:: _static/synonyms.jpg

        Рис. Реестр синонимов

1. Заполнить по возможности Реестр синонимов и Реестр исключений.

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

2. Создать хотя бы одну запись реестра Обращений, заполнить тему, описание, запустить по маршруту активации.

3. Создать индекс ``itsm_incident_tagcloud`` в Kibana->Management->Index Patterns->Add new

.. figure:: _static/index.jpg

        Рис. Создание индекса

4. Загрузить  дашборд "Облако тегов и 2 визуализации "Облако тегов по теме", "Облако тегов по описанию". Архив можно скачать здесь_.

.. _здесь: _static/TagCloud.7z

Для загрузки его необходимо перейти в Kibana->Management->Saved Objects и загрузить нажав на Import. Загружать необхрдимо json файлы, а не архив.

5. После импорта можно перейти на дашборд и ознакомиться с результатами.

6. При необходимости создать внешний модуль в SynergyIDE и добавить ссылку на этот дашборд, дать права группам пользователей.


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

Реализовано уведомление для записей реестра Обращения в статусе "Зарегистрировано", которое отображается когда один пользователь открывает обращение, которое открыто у другого пользователя. Таким образом можно исключить одновременную работу над одним документом при распределении обращений.

Также бывают ситуации, когда пользователь закрывает сразу же страницу браузера и тем самым документ не закрывается. В базе данных документ остается открытым под данным пользователем. Реализовано несколько API методов для работы с открытыми документами:

1. GET `/itsm/rest/document/isopen?documentID={documentID}` - возвращает информацию по документу если он открыт, пример ответа:


{
    "errorCode": 0,
    "errorMessage": "OK",
    "data": {
        "userID": "1",
        "documentID": "bba1e996-c745-4d4f-b933-47aeef158ab2",
        "dataUUID": "63857",
        "date": "1577244327226"
    }
}


2. GET `/itsm/rest/document/list` - получает весь список открытых документов, пример ответа:

{
    "errorCode": 0,
    "errorMessage": "OK",
    "data": [
        {
            "userID": "f7abd6d9-7b92-4da4-a183-d53feaee2296",
            "documentID": "1b5f6d64-0d61-4f4c-b6a4-8fc80e6be177",
            "dataUUID": "63828",
            "date": "1577244489896"
        },
        {
            "userID": "1",
            "documentID": "bba1e996-c745-4d4f-b933-47aeef158ab2",
            "dataUUID": "63857",
            "date": "1577244327226"
        }
    ]
}


3. POST `/itsm/rest/document/remove/{documentID}` - удаляет из списка один документ, в ответ приходит 1 если был удален или 0 если в базе не найден данный документ, пример ответа:

{
    "errorCode": 0,
    "errorMessage": "OK",
    "data": 1
}


4. POST `/itsm/rest/document/removeAll` - удаляет из списка все документы, в ответ приходит количество удаленных записей, пример ответа:

{
    "errorCode": 0,
    "errorMessage": "OK",
    "data": 4
}


В случае если при выполнении любого из вышеперечисленных методов возникает ошибка, в ответ возвращается json:

{
    "errorCode": 13,
    "errorMessage": "сообщение, характеризующее ошибку"
}

Также для удобства реализован скрипт `closeOpenDocument.sh`, который проверяет и удаляет из базы открытые документы. Данный скрипт можно поставить в крон для автоматического удаления зависших документов (*для случаев когда событие закрытия документа из UI Synergy не может быть вызвано*). Скрипт содержит настройки, которые по необходимости изменить под потребности:
Скрипт находится в папке `/opt/synergy/apps/itsm/scripts`.

# кол-во часов, прошедших с даты открытия документа, по истечению которых нужно удалить документ из базы  

HOURS=5  
  
# mySQL настройки 

mysqlUser="root"   

mysqlPass="root"  

mysqlDB="synergy"  

mysqlHost="localhost"


Для того чтобы поставить в крон необходимо:

1. Подключиться по ssh и в терминале ввести команду 

`$ crontab -e`

2. Добавить текст

0 22 * * * /opt/synergy/apps/itsm/scripts/closeOpenDocument.sh

В данном случае скрипт будет запускаться каждый день в 22.00. При необходимости можно поменять сроки исполнения.

3. Сделать скрипт исполняемым:

$ chmod a+x /opt/synergy/apps/itsm/scripts/closeOpenDocument.sh



Для настройки иерархической эскалации по обращениям
-----------------------------------------


Для того чтобы поставить в крон необходимо:

1. Подключиться по ssh и в терминале ввести команду 

`$ crontab -e`

2. Добавить текст

0 22 * * * /opt/synergy/apps/itsm/scripts/appEscalationRun.sh

В данном случае скрипт будет запускаться каждый день в 22.00. При необходимости можно поменять сроки исполнения.

3. Сделать скрипт исполняемым:

$ chmod a+x /opt/synergy/apps/itsm/scripts/appEscalationRun.sh



Для  закрытия обращений, которые ожидают доработки со стороны инициатора
-----------------------------------------

Бывают ситуации, когда пользователь обратился с обращением, и после отправки обращения на доработку пользователь не отвечает (возможно обращение уже не актуально). Обращения так и находится в статусе "Ожидает ответа пользователя". И так может собираться большое количество обращений. Для того чтобы их закрывать реализован скрипт `close_incident.sh`, который позволит закрыть данные заявки, если с момента отправления на доработку прошло 16 рабочих часов. Для того чтобы этот скрипт исполнялся его необходимо поставить в крон.
Скрипт находится в папке `/opt/synergy/apps/itsm/scripts`. В скрипте имеются следующие настройки:

1. файл откуда берутся настройки соединения с synergy: source /opt/synergy/jboss/standalone/configuration/arta/apps/itsm/itsm.properties

2. подключение к базе mysql(при необходимости заменить в скрипте логин и пароль)

mysqlUser="User"  

mysqlPass="Pass"  

mysqlHost="127.0.0.1"  

3. расположение лог файла, код реестра инцидентов и комментарий по умолчанию:

logFile="/var/log/synergy/scripts.log"  

...  

registryCode="itsm_registry_incidents"  

comment="Закрыто по истечению времени на ожидание ответа пользователя"  

Для того чтобы его поставить в крон необходимо:

1. Подключиться по ssh и в терминале ввести команду 

`$ crontab -e`

2. Добавить текст

0 23 * * * /opt/synergy/apps/itsm/scripts/close_incident.sh

В данном случае скрипт будет запускаться каждый день в 23.00. При необходимости можно поменять сроки исполнения.

3. Сделать скрипт исполняемым:

$ chmod a+x /opt/synergy/apps/itsm/scripts/close_incident.sh

Для правильной работы скрипта с пакетом дополнительно будет установлена утилита ``jq``. Для проверки правильной установки утилиты можно выполнить в терминале следующую команду:

``jq --version``

В ответ вернется версия установленной утилиты. Например: ``jq-1.5-1-a5b5cbe``  



Для пересмотра и актуализации статей базы знаний
-----------------------------------------

Статьи в базе знаний со временем теряют свою актуальность, поэтому периодически их нужно актуализировать. Для этого реализован скрипт knowledgebase_update.sh . Для периодического запуска данного скрипта, его нужно поставить в крон. Скрипт находится здесь: /opt/synergy/apps/itsm/scripts/knowledgebase_update.sh .   

Для работы данного скрипта, его необходимо сделать исполняемым:  

$ chmod a+x /opt/synergy/apps/itsm/scripts/knowledgebase_update.sh

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

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

#Срок проверки статей

termyear=1    # год 

termmonth=2   # месяц 

termdays=10    # день   


Также есть следующие настройки, которые необходимо настроить под данные клиента:    

#Код реестра Базы знаний  

registryCode="itsm_registry_knowledgebase"  

#настройки mysql  

mysqlUser="root"  

mysqlPass="root"  

mysqlHost="127.0.0.1"  

#тут есть логин/пароль и хост синержи  

source /opt/synergy/jboss/standalone/configuration/itsm.properties  


Для уведомления определенных пользователей об окончании сроков документов по активам
-----------------------------------------

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

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

$ chmod a+x /opt/synergy/apps/itsm/scripts/contractExpirationNotice.sh  



Для регистрации обращений из внешних систем
-----------------------------------------------

Для регистрации обращений из внешних систем можно использовать кастомную API ${HOST}/itsm/rest/incident/create  

Для каждого описанного ниже апи, для авторизации необходимо передавать заголовок:  
"Authorization", "Basic " + btoa(unescape(encodeURIComponent(login + ":" + password)))  


1. вызвать метод для создания временного файла на сервере: ${HOST}/Synergy/rest/api/storage/start_upload (start_upload)  

Method: GET  

В ответе получаем путь до временного файла, пример ответа:  

{
   "errorCode": "0",
   "file": "/opt/synergy/jboss/standalone/tmp/Synergy/upload.tmp/96f50f11-17e7-4aa9-9798-cba4d81f4135"
}



2. Далее необходимо загрузить данные во временный файл с помощью метода ${HOST}/Synergy/rest/api/storage/upload_part (upload_part)  

Method: POST  

Enctype: multipart/form-data  

3. после загрузки файлов на сервер, необходимо вызвать метод создания обращения ${HOST}/itsm/rest/incident/create  

Method: POST  

Content Type: application/json; charset=utf-8  

пример передаваемых параметров:  

{
    "theme": "text theme",
    "description": "text description",
    "files": [
        {
            "name": "file.txt",
            "path": "/opt/synergy/jboss/standalone/tmp/Synergy/upload.tmp/96f50f11-17e7-4aa9-9798-cba4d81f4135"
        }
    ]
}

В параметр files передается массив объектов, в каждом объекте передается имя файла и путь до временного файла на сервере, который получается при выполнении апи rest/api/storage/start_upload
пример успешного ответа:  
{
    "regNumber": "inc-29181",
    "dataUUID": "67423",
    "documentID": "e924f754-d23e-4528-90a0-4b81d3085fd5"
}

Если необходимости в передачи файлов нет, то можно сразу вызвать апи ${HOST}/itsm/rest/incident/create без параметра files, пропустив первые 2 шага.
