Введение

В предыдущей статье мы рассмотрели способ быстрого развертывания Redmine на сервере Vscale и базовые настройки системы. Теперь рассмотрим как внедрить эту систему в действующую IT-инфраструктуру компании. Мы научим Redmine авторизовывать пользователей по протоколу LDAP. Удобство такого подхода сложно переоценить - ведь зачем заносить всех пользователей в систему, когда они уже есть в службе каталогов. К тому же это обезопасит от ситуации, что какую-либо учетную запись забудут удалить, например, при увольнении сотрудника. Помимо этого рассмотрим как можно управлять Redmine с помощью RestAPI.

Предварительные условия:

В качестве примера предположим, что в организации есть:

сервер с операционной системой Windows Server;
настроенная служба каталогов Active Directory с отдельным пользователем, от имени которого будет устанавливаться соединение;
сервер с развернутым Redmine.

Ниже мы опишем, как настроить Redmine для работы с сервером авторизации.

Настройка авторизации по LDAP

Для соединения с сервером необходимо выполнить следующие действия:

Войти в Redmine с правами администратора.
Выбрать раздел “Администрирование” ➝ “Авторизация с помощью LDAP”➝ “Новый режим аутентификации”.

Откроется новая страница с полями для параметров доступа к серверу:

В открывшейся странице заполняем поля в соответствии с настройками LDAP-сервера:

Имя (имеется в виду имя соединения).
Компьютер (имеется в виду адрес сервера).
Порт (если сервер LDAP настраивался стандартно, то укажите порт 389).
Учетная запись (пользователя LDAP в формате имя@домен).
Пароль (пользователя LDAP).
BaseDN (в формате DC=company,DC=com).
Атрибут Login (укажите логин пользователя в формате для старых систем - менее 20 символов, уникальный для всех объектов домена).

При необходимости можно поставить галочку на пункт “Создание пользователя на лету”, если эта возможность требуется в текущей ситуации.

Обязательно сохраните внесенные изменения.

Если все данные были внесены правильно, то пользователи Active Directory смогут заходить в Redmine, используя единые учетные данные LDAP.

Применение RestAPI для интеграции

Одной из важнейших задач в работе любой компании является эффективное получение обратной связи от клиентов. Сбор данных производится по-разному, но зачастую их обработка представляет собой существенную сложность. В лучшем случае есть несколько сотрудников, которые такие отзывы читают, причем в обработку попадают лишь очень немногие.

Было бы более эффективно, чтобы все отзывы попадали из веб-сайта компании сразу в Redmine в виде задач и назначались на отдел, занимающийся их обработкой. Это легко реализовать с помощью RestAPI. В упрощенном виде это можно представить как небольшую веб-форму, которую можно внедрить в код любого сайта. При нажатии на кнопку отправки отзыва, сервер сгенерирует POST-запрос, который автоматически создаст новую задачу и назначит его на нужный отдел. Такой подход позволяет уделить максимальное внимание проблемам клиентов, которые оставили отзыв.

Отправить сформированный запрос можно несколькими способами, например через cURL. Разработчики мобильных приложений для Android могут использовать HttpClient и HttpPost для формирования и отсылки такого запроса. Для мобильной платформы Apple IOS можно воспользоваться классами NSURLSession и NSURLConnection.

Готовим систему к работе:

Создадим новый трекер:

“Администрирование” ➝ “Трекер” ➝ “Новый трекер”. Зададим ему имя и статус, который будет присваиваться всем новым задачам после их создания. В примере этот трекер будет называться Feedback. Отметим нужные нам поля галочками. Сохраняем трекер, нажатием на кнопку “Сохранить”.
Переходим к созданию проекта:

“Администрирование” ➝ “Проекты” ➝ “Новый проект”. Заполняем поля “Имя” и “Уникальный идентификатор”. Для примера у нас будет проект будет называться также как и трекер - “Feedback” с уникальным идентификатором “feed”. Не забываем отметить галочками только нужные нам модули и наш трекер. Подтверждаем создание проекта, нажав на “Создать”.
Заведем пользователя, от имени которого будут создаваться автоматические задачи.

Назовем его, к примеру, Feedback Bot. Создадим его локально: “Администрирование” ➝ “Пользователи” ➝ “Новый пользователь”. Заполняем необходимые поля и нажимаем “Создать”.
Добавим созданного пользователя в проект и дадим ему соответствующую роль.

Для этого заходим в “Администрирование” ➝ “Проекты” ➝ “Feedback”, переходим на вкладку “Участники” и нажимаем “Новый участник”. Отмечаем галочками Feedback BOT и роль (например Reporter). Завершаем нажатием кнопки “Добавить”.
Включаем поддержку RestAPI (по-умолчанию эта опция отключена).

“Администрирование” ➝ “Настройки” ➝ вкладка “API”. Ставим галочку напротив “Включить веб-сервис REST” и нажимаем “Сохранить”. Этим мы активируем на сервере возможность обращаться к серверу c HTTP-запросами, используя RestAPI и получать от него ответы в формате XML.

Также Redmine поддерживает JSONP (JSON-pure API), который удобно использовать во многих случаях. Пару лет назад на Хабрахабре публиковался перевод статьи Michael S. Mikowski “RESTful APIs, the big lie”, в которой автор аргументированно доказывает, что использование RestAPI как механизма взаимодействия с сервером достаточно затруднительно и предлагает JSONP как альтернативу. Прочитать об этом можно в статье https://habrahabr.ru/post/265845/. Для понимания того, как работает механизм обмена данными и как его автоматизировать, мы выбрали RestAPI в качестве примера.

Со стороны сервера мы станем использовать связку Apache + PHP с установленным cURL. Создадим простую веб-форму, данные из которой будут передаваться php-скрипту, который сгенерирует из них XML с нужными параметрами, а затем отправит его методом POST на сервер с Redmine. Сервер обработает подобный запрос как команду на создание новой задачи.

Код веб-формы:

<html>
    <head>
        <title>POST-form test</title>
    </head>
    <body>
        <h1 align=left>This is test feedback form</h1>
        <form method="post" action="post.php">
            Subject:<br>
            <input type="text" name="subj"><br>
            Your e-mail address:<br>
            <input type="text" name="mail"><br>
            Say something:</br>
            <textarea name="feedback" cols="80" rows="10"></textarea><br><br>
            <input type="submit" value="Send feedback to us"><br>
        </form>
    </body>
</html>

В созданной форме у нас есть три поля, которые мы будем использовать в качестве источника информации для будущих задач в Redmine. Им присваиваются три соответствующие переменные и по нажатию кнопки с типом “submit” они будут переданы PHP-скрипту post.php.

Обращаем внимание, что приведенный ниже пример является образцом и перед его использованием в небезопасных сетях необходимо позаботиться о его безопасности (например, внедрить механизм CAPTCHA и проверку вводимой информации).

Код post.php

<?php

$isubj = $_POST["subj"];
$imail = $_POST["mail"];
$ifeedback = $_POST["feedback"];
$icont = $isubj . " via " . $imail;

$xml = new DomDocument('1.0', 'UTF-8');
$xml->formatOutput=true;

   $issues = $xml->createElement("issue");
    $xml->appendChild($issues);
    $subj = $xml->createElement("subject",$icont);
    $issues->appendChild($subj);
    $projid = $xml->createElement("project_id","2");
    $issues->appendChild($projid);
    $tracid = $xml->createElement("tracker_id","1");
    $issues->appendChild($tracid);
    $descr = $xml->createElement("description",$ifeedback);
    $issues->appendChild($descr);

$xml->preserveWhiteSpace = false;
$xml->formatOutput = true;
$postdata = $xml->saveXML();

$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml'));
curl_setopt($ch, CURLOPT_URL, "http://IP_адрес_сервера_Redmine/issues.xml?format=xml&key=Ключ_API");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postdata);
$content=curl_exec($ch);
curl_close($ch);

?>

Как это работает

Рассмотрим, что делает вышеуказанный скрипт на языке PHP. Для того, чтобы Redmine создал новую задачу, необходимо передать ему две вещи:

авторизационные данные пользователя;
подготовленный XML-код, в котором будут заданы все ее основные параметры.

В начале статьи мы создали пользователя Feedback Bot, от имени которого и будут приходить запросы.

Чтобы авторизоваться в Redmine для выполнения запроса, можно либо отправить в параметрах логин и пароль пользователя, либо же отправить API-ключ. Использовать второй способ проще.

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

Войти в систему.
Перейти по ссылке “Моя учетная запись” в правом верхнем углу.
На открывшейся странице щелкнуть “Показать” под надписью “Ключ доступа к API”.

В коде скрипта выполнены следующие задачи:

Заданы параметры XML для отправки серверу $xml - new DomDocument('1.0', 'UTF-8').
Создана древовидная структура, в соответствие со структурой RestAPI Redmine.
Сгенерирован XML-код для передачи серверу Redmine.
Создан и отправлен POST-запрос.

Описание структуры можно найти непосредственно в wiki-разделе сайта redmine.org. Единственное, что можно заметить в нашем примере - параметры <project_id> и <tracker_id> заданы статично и в числовом виде. Поскольку Redmine использует базу данных PostgreSQL, определить их номера можно с помощью соответствующего клиента базы данных.

Пример сгенерированного XML-кода:

<?xml version="1.0" encoding="UTF-8"?>
<issue>
     <subject>Прекрасный продукт via client@gmail.com</subject>
     <project_id>2</project_id>
     <tracker_id>1</tracker_id>
     <description>Спасибо за прекрасный продукт, все замечательно. </description>
</issue>

Соединение с сервером и передачу данных будем осуществлять с помощью cURL. Поскольку мы планируем оперировать с задачами, HTTP-запросы следует отправлять на issues.xml вместе с API-ключом. Заполнение веб-формы и нажатие на кнопку отправки отзыва вызовет автоматическое создание задачи в нужном нам проекте и с нужным нам трекером.

Все вышеперечисленное позволило сразу увидеть обратную связь от клиента и теперь ее можно сразу обработать, либо направить профильным специалистам. Точно таким же образом через RestAPI/JSONP можно получать количество открытых/закрытых задач, формировать статистику в реальном времени в нужном приложении или на определенной веб-странице. Подобный подход можно рассматривать как универсальный механизм взаимодействия, хотя и требующий некоторого времени на изучение.

Заключение

Мы показали, как можно начать интегрировать Redmine в уже существующую инфраструктуру. Поддержка технологий HTTP-запросов позволяет выполнять самые разные задачи, при этом гибко встраиваясь в действующие системы без необходимости их существенного изменения.

Наш сервис Vscale позволит легко попробовать Redmine в действии. А если возникнут вопросы, то мы будем рады на них ответить в комментариях.

Интеграция Redmine c текущей инфраструктурой