Описание

JScript для взаимодействия с Redmine по средствам REST API в WSH среде операционной системы Windows. В первую очередь скрипт предназначен для использования в планировщике задач. С помощью скрипта можно организовать синхронизацию пользователей с Active Directory через LDAP и автоматическое изменение (закрытие) задач. Для взаимодействия с Redmine используется XML формат.

Использование

В командной строке Windows введите следующую команду:

cscript redmine.min.js <instance> <method> [... <param>]

• <instance> - Адрес для подключения к Redmine через REST API в формате url. Слэш в конце не обязателен, он добавляется автоматически. Можно указать логин и пароль для Basic Authentication или ключ доступа во фрагменте после #. Как включить REST API и посмотреть ключ пользователя для взаимодействия описано в официальной документации.
• <method> - Имя собственного метода, который нужно выполнить.
• ... <param> - Параметры для задачи.

Собственные методы

users.sync - Синхронизация пользователей с Active Directory через LDAP. Метод обновляет данные у пользователей Redmine, блокируя отключённых пользователей и добавляя новых. Пользователи Redmine, у которых нет соответствующих пользователей в контейнере Active Directory, не трогаются. Пользователи сопоставляются по первому полю в заданном синхронизируемом списке полей. Подключение к Active Directory идёт в контексте текущего пользователя, поэтому при запуске скрипта из планировщика задач не забудьте указать от имени какого пользователя запускать задачу.

cscript redmine.min.js <instance> users.sync <source> <fields> [<auth>]

• <source> - Адрес для подключения к Active Directory в формате url (поддерживается протокол ldap). Можно указать GUID, cn, distinguishedName, sAMAccountName или LDAP-SQL запрос с шаблонизацией и переменными {select}, {scheme}, {parent}. В качестве LDAP-SQL запроса можно указать часть запроса начиная с WHERE.
• <fields> - Соответствие идентификатора поля пользователя и его значения в формате ID:value;id:value с поддержкой шаблонизации Пользователи сопоставляются по первому полю в этом списке. Если в значении есть пробельные символы, то это значение нужно заключить в двойные кавычки. Для настраиваемых полей пользователей укажите идентификатор поля в виде числа.
• <auth> - Идентификатор режима аутентификации в приложении. Идентификаторы можно посмотреть на странице Режимы аутентификации (Администрирование - Авторизация с помощью LDAP) в Redmine.

issues.sync - Синхранизация задач в Cherwell. Поддерживается дополнительная фильтрация.

cscript redmine.min.js <instance> issues.sync <destination> <query> [<filters>] <fields>

• <destination> - Адрес для подключения к Cherwell через REST API в формате url. Слэш в конце не обязателен, он добавляется автоматически. Нужно указать логин, пароль и идентификатор клиента во фрагменте после #. Подробнее можно прочитать в официальной документации.
• <query> - Идентификатор сохранённого запроса для всех проектов. Запросы можно добавить на странице Задачи в Redmine. Запросы выводятся в правом блоке с заголовками Сохранённые запросы и Мои сохранённые запросы. Запрос должен быть виден из-под пользователя, который используется для взаимодействия с REST API. В настройках запроса обязательно должна стоять галочка Для всех проектов. Идентификатор запроса в Redmine должен совпадать с именем запроса в Cherwell в пространстве пользователя, который используется для взаимодействия с REST API.
• <filters> - Дополнительный фильтр для задач в формате id:value,value;id:value,value с поддержкой шаблонизации. Если в значении есть пробельные символы, то это значение нужно заключить в двойные кавычки. Можно указать несколько подходящих значений через запятую.
• <fields> - Соответствие идентификатора поля тикета в Cherwell и его значения в формате ID:value;id:value с поддержкой шаблонизации Тикеты и задачи сопоставляются по первому полю в этом списке. Если в значении есть пробельные символы, то это значение нужно заключить в двойные кавычки.

issues.change - Изменение задач. Метод изменяет данные в заданных полях. Поддерживается дополнительная фильтрация.

cscript redmine.min.js <instance> issues.change [<query>] [<filters>] <fields>

• <query> - Идентификатор сохранённого запроса для всех проектов. Запросы можно добавить на странице Задачи в Redmine. Запросы выводятся в правом блоке с заголовками Сохранённые запросы и Мои сохранённые запросы. Запрос должен быть виден из-под пользователя, который используется для взаимодействия с REST API. В настройках запроса обязательно должна стоять галочка Для всех проектов.
• <filters> - Дополнительный фильтр для задач в формате id:value,value;id:value,value с поддержкой шаблонизации. Если в значении есть пробельные символы, то это значение нужно заключить в двойные кавычки. Можно указать несколько подходящих значений через запятую.
• <fields> - Поля и их значения в формате id:value;id:value с поддержкой шаблонизации. Если в значении есть пробельные символы, то это значение нужно заключить в двойные кавычки. Для настраиваемых полей задачи укажите идентификатор поля в виде числа.

Шаблонизация

В параметрах и значениях, которые поддерживают шаблонизацию, можно указывать шаблоны. Шаблон из себя представляет строку, которая может содержать (а может и не содержать) один или несколько разделителей |. Разделитель делит строку на фрагменты. В фрагменте текста может содержаться (а может и не содержаться) один или несколько указателей на значение. Указатель на значение {object.key.id>filter(param)} представляет из себя последовательность ключей, по которым нужно пройти в объекте чтобы получить значение. Если значение отсутствует, то фрагмент удаляется (для удаления фрагмента значение должно именно отсутствовать, а не быть пустым). В качестве объекта используется сущность, с которой работает задача. Если нужно оставить значение разделителя, то поставьте разделитель два раза подряд.

"Текст для примера|| {author.name} проекта {project.name>normal}| {done_ratio} %|."

В указателях на значения можно указывать последовательность фильтров для изменения значений. Фильтры могут принимать дополнительные параметры в круглых скобках через запятые. Скобки не указываются если дополнительные параметры не передаются. Поддерживаются следующие фильтры:

• hash - Оставляет только часть значения, которая идёт после символа #.
• set - Возвращает строку true если передано не пустое значение, в противном случае false.
  • <true> - Возвращаемый текст вместо строки true. Если задать пустую строку, то будет возвращено значение поступившие в фильтр.
  • <false> - Возвращаемый текст вместо строки false. Если задать пустую строку, то ничего не возвращается.
• map - Заменяет значение на соответствующий подходящий текст. Если соответствие не найдено, то ничего не возвращается.
  • <relation> - Значение и её замена в формате id=value. Можно указать несколько таких связок через запятые. Символ * заменяет любое значение.
• replace - Заменяет все вхождения строки поиска на строку замены.
  • <search> - Искомая строка для замены.
  • <replacement> - Строка, на которую заменяется искомая.
• date - Преобразовывает и возвращает отформатированное строковое значение даты.
  • <format> - Формат возвращаемой даты по аналоги с PHP (по умолчанию Y-m-d).
  • <offset> - Дополнительное смещение в днях.
• phone - Оформляет значение как телефонный номер в формате +X (XXX) XXX-XX-XX.
• context - Определяет различные свойства контекста.
  • from - Окончание строки, начинающейся с From: или От:, которое может обрезаться символами < и > или конструкцией mailto: в скобках.
  • deadline - Окончание строки, начинающейся с Deadline: или Срок:.
• journal - Получает идентификатор пользователя, сделавшего последнее изменение. Можно задать атрибут и значение.
• user, issue, project - Получает по значению соответствующий объект или значение его свойства.
• normal - Делает первый символ заглавным и удаляет точку, восклицательный и вопросительный знак в конце, если он единственный. Так же удаляет FW: и RE: в начале значения.
• clear - Частично удаляет Markdown разметку. В частности, все символы * и все ссылки формата [text](url).
• crop - Удаляет блок, связанный с пересылкой письма и всё что идёт до него, а также удаляется подпись.

Примеры использования

Синхронизировать пользователей из контейнере Active Directory с GUID {8F640E75-C072-47CA-5DBD-66AFC5D7E38F} в приложение Redmine расположенное по адресу https://redmine.org используя ключ доступа пользователя 8dbfd7b0a9c9279a97fedfb82710aed96bcf53fc. В настраиваемое полей с идентификатором 12 записать фамилию руководителя пользователя. Указать режим аутентификации как 1.

cscript redmine.min.js https://redmine.org#8dbfd7b0a9c9279a97fedfb82710aed96bcf53fc users.sync ldap://{8F640E75-C072-47CA-5DBD-66AFC5D7E38F}
login:{sAMAccountName};firstname:{givenName};lastname:{sn};mail:{mail};12:"{manager.sAMAccountName>user.lastname}" 1

Синхронизировать задачи из приложения Redmine, расположенного по адресу https://redmine.org используя ключ доступа, и тикеты в Cherwell, расположенного по адресу https://ivanti.com/CherwellAPI используя логин и пароль. При синхронизации использовать сохранённый запрос с идентификатором 39, а также заданные поля с шаблонизированными значениями, с применением фильтров с дополнительными параметрами. Изменить идентификатор статуса на 8, процент выполнения на 10 и добавить комментарий с шаблонизацией для задач из сохранённого запроса с идентификатором 46, если описание задачи содержит заявка, настраиваемое поле с идентификатором 10 содержит серия, это не приватная задача и задача назначена автору. Для подключения к приложению Redmine использовать логин user и пароль password.

cscript redmine.min.js https://redmine.org#8dbfd7b0a9c9279a97fedfb82710aed96bcf53fc issues.sync https://user:password@ivanti.com/CherwellAPI#27f5c613-4392-c534-6fe9-ed646fe9ed64 39 SuppliersReference:{id};ServiceCountryCode:RUS;Description:"{description>set(,'Нет описания')}";CustomerDisplayName:"{author.id>user[15]}";Status:"{status.id>map(3=Resolved,4=Resolved)}";OwnedBy:"{assigned_to.id>user[15]}"

Изменить идентификатор статуса на 8, процент выполнения на 10 и добавить комментарий с шаблонизацией для задач из сохранённого запроса с идентификатором 46, если описание задачи содержит заявка, настраиваемое поле с идентификатором 10 содержит серия, это не приватная задача и задача назначена автору. Для подключения к приложению Redmine использовать логин user и пароль password.

cscript redmine.min.js https://user:password@redmine.org issues.change
46 description:заявка;10:серия;is_private:true;assigned_to.id:{author.id} status.id:8;done_ratio:10;notes:"{author.name}, ваша заявка автоматически зарегистрирована в системе."