Краткое описание как интегрировать внешнюю систему с вашей ITSM 365 через REST API
Как сделать интеграцию с ITSM 365
Известно, что сервисные компании часто работают не только напрямую с конечными заказчиками, но и на субподряде у именитых сервисных интеграторов.
Ведь крупные заказчики часто категорически отказываются работать с малоизвестными небольшими региональными компаниями по ряду причин. Часто это требование руководства, чтобы "качество сервиса и поставщик расходных материалов" был один по всем регионам присутствия компании. Либо это вынужденная мера, так как многие сетевые компании сами являются крупными налогоплательщиками и стоят на особом контроле у налоговой службы.
Что бы ни было причиной, но для крупных федеральных интеграторов даже большая розничная сеть, которой нужно заправлять картриджи в 32 регионах РФ, часто оказывается далеко не самым интересным клиентом и такие контракты как правило целиком, или частями передаются на субподряд небольшим региональным сервисным компаниям, или интеграторам поменьше.
В случае передачи контракта на субподряд возникает желание автоматизировать передачу и контроль обработки заявок партнерам. Но сами небольшие сервисные компании как правило оказываются не готовы к такому повороту событий.
В этой статье мы рассмотрим простой пример как из внешней системы работать с ITSM 365 через стандартный API и автоматизировать передачу заявок.
Ведь крупные заказчики часто категорически отказываются работать с малоизвестными небольшими региональными компаниями по ряду причин. Часто это требование руководства, чтобы "качество сервиса и поставщик расходных материалов" был один по всем регионам присутствия компании. Либо это вынужденная мера, так как многие сетевые компании сами являются крупными налогоплательщиками и стоят на особом контроле у налоговой службы.
Что бы ни было причиной, но для крупных федеральных интеграторов даже большая розничная сеть, которой нужно заправлять картриджи в 32 регионах РФ, часто оказывается далеко не самым интересным клиентом и такие контракты как правило целиком, или частями передаются на субподряд небольшим региональным сервисным компаниям, или интеграторам поменьше.
В случае передачи контракта на субподряд возникает желание автоматизировать передачу и контроль обработки заявок партнерам. Но сами небольшие сервисные компании как правило оказываются не готовы к такому повороту событий.
В этой статье мы рассмотрим простой пример как из внешней системы работать с ITSM 365 через стандартный API и автоматизировать передачу заявок.
На стороне ITSM 365 никаких доработок не требуется делать, просто создайте (или выберите существующую) учетную запись от имени которой будут создаваться заявки. Дайте ей роль администратора, создайте ключ авторизации
Чтобы работать через REST запросы нам потребуется создать ключ авторизации выбранного нами пользователя. Для этого в панели настройки перейдем в Консоль и выполним команду:
return api.auth.getAccessKey('sgorbunkov').setDeadlineDays(365).uuid
где 'sgorbunkov' - логин выбранного нами пользователя с ролью администратора. Система сгенерирует и вернет нам ключ вида:
accessKey=8a5d0671-ae00-4870-8751-269ed963932b
сохраним его
return api.auth.getAccessKey('sgorbunkov').setDeadlineDays(365).uuid
где 'sgorbunkov' - логин выбранного нами пользователя с ролью администратора. Система сгенерирует и вернет нам ключ вида:
accessKey=8a5d0671-ae00-4870-8751-269ed963932b
сохраним его
1. Определение параметров
Для создания заявки через API необходимо корректно передать ее параметры, которые требуется предварительно определить
1.1 Идентификация пользователя
Поиск пользователя по логину выполняем командой:
https://outsource-dev.itsm365.com/sd/services/rest/find/employee/{login:oorlova}?accessKey=8a5d0671-ae00-4870-8751-229ed963932b
где
oorlova - логин клиента
В отчет от сервера получаем JSON с данным пользователя (если он найден)
В нашем случае "UUID":"employee$1545902" - индентификатор пользователя employee$1545902
https://outsource-dev.itsm365.com/sd/services/rest/find/employee/{login:oorlova}?accessKey=8a5d0671-ae00-4870-8751-229ed963932b
где
oorlova - логин клиента
В отчет от сервера получаем JSON с данным пользователя (если он найден)
В нашем случае "UUID":"employee$1545902" - индентификатор пользователя employee$1545902
1.2 Определение компании клиента
Идентификатор клиента находится в параметре "parent":{"UUID":"ou$1546201" .. в JSON ответе сервера, полученном в п1.1
В нашем случае индентификатор компании клиента ou$1546201
В нашем случае индентификатор компании клиента ou$1546201
1.3 Определение сервисного контракта
Доступные пользователю сервисные контракты указаны в атрибуте "recipientAgreements":[{"UUID":"agreement$1492401","title":"Сервисный контракт №1","metaClass":"agreement$agreement"} … ]
В нашем случае возьмем сервисный контракт с идентификатором agreement$1492401
В нашем случае возьмем сервисный контракт с идентификатором agreement$1492401
1.4 Определение услуги
Для определения доступных услуг по выбранному в п.1.3 сервисному контракту выполним REST запрос чтобы получить список доступных услуг контракта
https://outsource-dev.itsm365.com/sd/services/rest/get/agreement$1492401/?accessKey=8a5d0671-ae00-4870-8751-229ed963932b
UUID услуг находятся в параметре services
"services":[{"UUID":"slmService$5602","title":"Интернет","metaClass":"slmService$slmService"},
В нашем случае возьмем услугу Интернет с идентификатором slmService$5602
https://outsource-dev.itsm365.com/sd/services/rest/get/agreement$1492401/?accessKey=8a5d0671-ae00-4870-8751-229ed963932b
UUID услуг находятся в параметре services
"services":[{"UUID":"slmService$5602","title":"Интернет","metaClass":"slmService$slmService"},
В нашем случае возьмем услугу Интернет с идентификатором slmService$5602
1.5 Выбор объекта обслуживания
Если пользователь создает заявку по своему же офису, то объектом обслуживания можно указать определенную в п.1.2 компанию ou$1546201
Если требуется создать заявку в рамках другого офиса клиента, то можно указать иной обслуживания (если вы ведете каталог объектов обслуживания в базе). Для просмотра доступных клиенту объектов обслуживания можно воспользоваться командой
https://outsource-dev.itsm365.com/sd/services/rest/find/ou/{parent:ou$1546201}?accessKey=8a5d0671-ae00-4870-8751-229ed963932b
Получим список доступных объектов обслуживания:
[{"parent":{"UUID":"ou$1546201","title":"ООО, Арко","metaClass":"ou$company"},"metaClass":"ou$company","title":"ООО, Арко - Воронеж","UUID":"ou$2283501","removed":false},...
Выберем объект ou$2283501
Если требуется создать заявку в рамках другого офиса клиента, то можно указать иной обслуживания (если вы ведете каталог объектов обслуживания в базе). Для просмотра доступных клиенту объектов обслуживания можно воспользоваться командой
https://outsource-dev.itsm365.com/sd/services/rest/find/ou/{parent:ou$1546201}?accessKey=8a5d0671-ae00-4870-8751-229ed963932b
Получим список доступных объектов обслуживания:
[{"parent":{"UUID":"ou$1546201","title":"ООО, Арко","metaClass":"ou$company"},"metaClass":"ou$company","title":"ООО, Арко - Воронеж","UUID":"ou$2283501","removed":false},...
Выберем объект ou$2283501
2. Регистрация заявки, получение номера заявки
Для регистрации новой заявки нам потребуется указать тип заявки. Доступны следующие типы:
Для регистрации новой заявки нам потребуется указать тип заявки. Доступны следующие типы:
Контактное лицо (атрибут clientEmployee) возьмем employee$1545902 - UUID пользователя, идентифицированного в п.1.1
Компания клиента (атрибут client) ou$1546201 - компания пользователя, идентифицированного в п.1.2
Сервисный контракт (атрибут agreement) agreement$1492401
- сервисный контракт, идентифицированный в п.1.3
Услуга (атрибут service) slmService$5602 - услуга сервисного контракта, полученная в п.1.4
Объект обслуживания (атрибут office) ou$2283501 - объект обслуживания, выбранный в п.1.5
Тема заявки (атрибут shortDescr) - тема заявки
Описание заявки (атрибут descriptionInRTF) - подробное описание заявки (не обязателен к заполнению)
Определив параметры формируем REST запрос с командой создания новой заявки:
https://outsource-dev.itsm365.com/sd/services/rest/create-m2m/serviceCall$serviceCall?accessKey=8a5d0671-ae00-4870-8751-229ed963932b&client=ou$1546201&clientEmployee=employee$1545902& office=ou$2283501&agreement=agreement$1492401&service=slmService$5602&shortDescr="тестовая заявка через REST"
в ответ получим JSON с данным о новой заявке (либо сообщение об ошибке)
в нашем случае параметры заявки
"UUID":"serviceCall$2441803" - идентификатор заявки (для дальнейшей работы)
"number":82 - номер заявки, присвоенный нашей системой
"title":"INC82" - наименование заявки
- serviceCall$serviceCall - тип заявки Инцидент, либо
- serviceCall$request - тип заявки Запрос
- serviceCall$call - тип Обращение (используйте этот тип когда заранее не известен тип и заявку нужно будет классифицировать перед обработкой, присвоив тип Запрос или Инцидент)
Контактное лицо (атрибут clientEmployee) возьмем employee$1545902 - UUID пользователя, идентифицированного в п.1.1
Компания клиента (атрибут client) ou$1546201 - компания пользователя, идентифицированного в п.1.2
Сервисный контракт (атрибут agreement) agreement$1492401
- сервисный контракт, идентифицированный в п.1.3
Услуга (атрибут service) slmService$5602 - услуга сервисного контракта, полученная в п.1.4
Объект обслуживания (атрибут office) ou$2283501 - объект обслуживания, выбранный в п.1.5
Тема заявки (атрибут shortDescr) - тема заявки
Описание заявки (атрибут descriptionInRTF) - подробное описание заявки (не обязателен к заполнению)
Определив параметры формируем REST запрос с командой создания новой заявки:
https://outsource-dev.itsm365.com/sd/services/rest/create-m2m/serviceCall$serviceCall?accessKey=8a5d0671-ae00-4870-8751-229ed963932b&client=ou$1546201&clientEmployee=employee$1545902& office=ou$2283501&agreement=agreement$1492401&service=slmService$5602&shortDescr="тестовая заявка через REST"
в ответ получим JSON с данным о новой заявке (либо сообщение об ошибке)
в нашем случае параметры заявки
"UUID":"serviceCall$2441803" - идентификатор заявки (для дальнейшей работы)
"number":82 - номер заявки, присвоенный нашей системой
"title":"INC82" - наименование заявки
3. Обработка заявки
Мы создали заявку, теперь рассмотрим основные действия с ней
3.1 Получение статуса заявки
Поиск заявок по номеру производится по аналогии командой:
https://outsource-dev.itsm365.com/sd/services/rest/find/serviceCall/{title:INC82}?accessKey=8a5d0671-ae00-4870-8751-229ed963932b
Получим массив заявок, удовлетворяющих запросу
[{"state":"registered","removed":false,"UUID":"serviceCall$2441803","metaClass":"serviceCall$serviceCall","title":"INC82","massProblem":false,"masterMassProblem":null,"massProblemSlaves":[]}]
state - это статус заявки
Таблица статусов заявки в типовой конфигурации ITSM 365 Outsource показана в таблице ниже. Если вы меняли настройки состояний, то актуальные идентификаторы состояний можно посмотреть в панели администратора в классе Заявка на вкладке Жизненный цикл.
https://outsource-dev.itsm365.com/sd/services/rest/find/serviceCall/{title:INC82}?accessKey=8a5d0671-ae00-4870-8751-229ed963932b
Получим массив заявок, удовлетворяющих запросу
[{"state":"registered","removed":false,"UUID":"serviceCall$2441803","metaClass":"serviceCall$serviceCall","title":"INC82","massProblem":false,"masterMassProblem":null,"massProblemSlaves":[]}]
state - это статус заявки
Таблица статусов заявки в типовой конфигурации ITSM 365 Outsource показана в таблице ниже. Если вы меняли настройки состояний, то актуальные идентификаторы состояний можно посмотреть в панели администратора в классе Заявка на вкладке Жизненный цикл.
3.2 Редактирование заявки и изменение статуса
При изменении заявки нам потребуется идентификатор заявки, определенный в п.2
Запрос начинается со строки https://outsource-dev.itsm365.com/sd/services/rest...$2441803/?accessKey=8a5d0671-ae00-4870-8751-229ed963932b
далее указываются атрибуты и значения в формате &attr1_code=attr1_value&attr2_code=attr2_value
Пример: завершение заявки
state=resolved - меняем статус на Завершен
codeOfClosing=resolved - код решения Успешно*
resultDescr=завершено - результат решения текстом
https://outsource-dev.itsm365.com/sd/services/rest/edit/serviceCall$2441803/?accessKey=8a5d0671-ae00-4870-8751-229ed963932b&state=resolved&codeOfClosing=resolved&resultDescr=завершено через рест запрос
*Возможные коды закрытия заявки:
Запрос начинается со строки https://outsource-dev.itsm365.com/sd/services/rest...$2441803/?accessKey=8a5d0671-ae00-4870-8751-229ed963932b
далее указываются атрибуты и значения в формате &attr1_code=attr1_value&attr2_code=attr2_value
Пример: завершение заявки
state=resolved - меняем статус на Завершен
codeOfClosing=resolved - код решения Успешно*
resultDescr=завершено - результат решения текстом
https://outsource-dev.itsm365.com/sd/services/rest/edit/serviceCall$2441803/?accessKey=8a5d0671-ae00-4870-8751-229ed963932b&state=resolved&codeOfClosing=resolved&resultDescr=завершено через рест запрос
*Возможные коды закрытия заявки:
- resolved - Решено
- rejected - Отклонено
- notINC - Не воспроизводится
3.3 Добавление комментария к заявке
https://outsource-dev.itsm365.com/sd/services/rest/create-m2m/comment?accessKey=8a5d0671-ae00-4870-8751-229ed963932b&source=serviceCall$2441803&author=employee$1545902&text=комментарий через REST запрос
где:
serviceCall$2441803 - UUID заявки
employee$1545902 - идентификатор сотрудника (чтобы комменты приходили от его имени)
text - текст комментария
где:
serviceCall$2441803 - UUID заявки
employee$1545902 - идентификатор сотрудника (чтобы комменты приходили от его имени)
text - текст комментария
Заключение
В данной статье мы рассмотрели пример как можно автоматизировать передачу запросов в ITSM365.Outsource из Service Desk клиента.
В статье мы разобрали живой пример. Для тех, кому захочется углубиться в механизмы интеграции предлагаем ознакомиться с официальной документацией по платформе Naumen SMP
В статье мы разобрали живой пример. Для тех, кому захочется углубиться в механизмы интеграции предлагаем ознакомиться с официальной документацией по платформе Naumen SMP