Обмен данными между 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
http://www.mantisbt.org/bugs/api/soap/mantisconnect.php?wsdl

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

Нам нужно написать 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 инцидентов, и мне остается только вывести на экран те, у которых логин совпадает с тем, который указан в данной карточке клиента.