Обмен данными между web-приложением и MantisBT

Используя Mantis для учета заявок от абонентов, часто приходилось сталкиваться со следующими сложностями:
1) При добавлении новой заявки приходится вносить или копипастить часть информации из карточки клиента в Mantis, что во-первых, лень, а во-вторых, потенциально может привести к искажению информации.
2) Не всегда получается оперативно прочитать предыдущие заявки по этому абоненту, во-первых, потому что лень, во-вторых, см. пункт первый, относительно искаженной информации.

Для решения этой задачи, воспользуемся API от Mantis — mantisconnect.php.

Начало

Упоминание об этом API проскакивало и на хабре, и на форуме mantisbt, но проблема заключалось в том, что все разговоры останавливались на том, что «там все просто», а для меня как не программиста, было не очень-то и просто понять с чего начинать. Забегая вперед, могу сказать, что там действительно все просто, попытаюсь рассказать об этом.

API у Мантиса работает по протоколу SOAP. Для работы с ним нам потребуется либо внешняя библиотека NuSOAP, либо можно воспользоваться стандарнтым расширением php_soap. Посмотреть что есть в этом API есть можно тут:
http://www.mantisbt.org/bugs/api/soap/mantisconnect.php ^[1]
http://www.mantisbt.org/bugs/api/soap/mantisconnect.php?wsdl ^[2]

Теперь разберемся, что со всем этим богатством делать.

Нам нужно написать php скрипт в котором:
1) Создать SOAP-клиент

$client = new nusoap_client($WSDL_POINT, false);

$WSDL_POINT — это url расположения mantisconnect.php в вашем трекере, http://[сайт]/api/soap/mantisconnect.php?wsdl

2) Использовать созданный клиент в наших корыстных целях. В качестве примера используем самую простую функцию — просмотра версии (mc_version)

$result = $client->call('mc_version', 'http://localhost/mantis/api/soap/mantisconnect.php', 'http://soap.amazon.com');

Результатом нам будет строка с версией багтрекера.

Если попробовать получить информацию о конкретном инциденте. Получим такой скрипт:

<?php
require_once('nusoap-0.9.5/lib/nusoap.php');

$WSDL_POINT = "http://localhost/mantis/api/soap/mantisconnect.php";
$username = 'administrator';
$password = 'root';
$issue_id = 1;

$params = array(
	'username' => $username,
	'password' => $password,
	'issue_id' => $issue_id
);
$client = new nusoap_client($WSDL_POINT, false);
$result = $client->call('mc_issue_get', $params, 'http://localhost/mantis/api/soap/mantisconnect.php', 'http://soap.amazon.com');

echo "<pre>";
print_r ($result);
echo "</pre>";
?>

$params — массив входных переменных. Для получения инцидента, как видно из описания в api, нам требуется имя пользователя, пароль, и номер инцидента.

Результатом нам будет ассоциативный массив со всеми данными, относящимися с данному инциденту. Посмотреть его можно функцией print_r(). Нужные же поля мы можем забрать как элементы массива.

Тут мы вполне возможно можем столкнуться с проблемой — вместо массива с инцидентом нам может прилететь массив с ошибкой.

Array
(
    [faultcode] => Server
    [faultactor] => 
    [faultstring] => Error Type: SYSTEM NOTICE,
Error Description:
Use of undefined constant ERROR_DUPLICATE_FILE - assumed 'ERROR_DUPLICATE_FILE',)

Проблема появляется, если в настройках учетной записи пользователя, чей логин/пароль используется для «общения» c Мантисом, в языковых настройках указан любой язык кроме английского. Связано это с тем, что код с мантисе поменяли, а файлы локализации не поправили.

Исправить ситуацию можно следующими способами:

1) установить английский язык в настройках
2) дождаться версии 1.2.11, где обещают исправить, или проапгрейдиться ночной сборкой
3) исправить файл локализации /lang/strings_russian.txt самостоятельно — заключив ERROR_DUPLICATE_FILE в одинарные кавычки.

Создание заявки

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

Предположим для создания заявки, из карточки абонента нам нужно:

1) его ФИО
2) логин

Плюс причина обращения

Логин мы поместим в специально созданное поле login
Получим такой массив:

$issue_data = array(
	'project' => array (
			'id' => 1 
		),
	'category' => "general",
	'reporter' => array (
			'id' => $reporter_id
		),
	'summary' => $summary,
	'description' => $description,
	'custom_fields' => array ($sequence_login_field => array (
					'field' => array (
						'id' => $login_field_id 
							),
					'value' => $login 
			              ),
			)
);

project_id = 1 — id проекта, к который мы добавляем инцидент
$reporter_id — Да, мы можем в этом месте подставить любого пользователя, удобно, т.к. нам не нужно будет знать пароли
всех сотрудников
$summary — состоит из ФИО и возможно ещё доп. информации
$description — причина обращения
$sequence_login_field, $login_field_id — беруться из Мантиса
$login — логин абонента из карточки клиента

Далее этот массив мы укладываем в $params

$params = array(
    'username' => $username,
    'password' => $password,
    'issue' => $issue_data
);

и смело отправляем. В ответ нам вернется номер созданного инцидента.

Информация о созданных инцидентах

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

К сожалению такого запроса, что бы можно было искать в базе мантиса нет, но можно использовать заранее созданный готовый фильтр. В моем случае, я создал фильтр на 1000 инцидентов со всеми статусами кроме «closed» и отсортированных в порядке возрастания времени последнего изменения инцедента.

$params = array(
    'username' => $username,
    'password' => $password,
    'project_id' => 1,
    'filter_id' => $filter_id,
    'page_number' => 1,
    'per_page' => 100	
); 

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

Автор: triple0zero