SecurityService API

Используйте данный веб-сервис для авторизации в проекте и получения авторизационного ключа, используемого для работы с остальными веб-сервисами Devprom ALM.

Протокол: SOAP, WebService

Ссылка: http://<host>/api/securityservice

WSDL описание (document/literal): http://<host>/api/securityservice?wsdl

WSDL описание (rpc/encoded): http://<host>/api/securityservice?wsdl&style=rpc&use=encoded

Методы

Название Возвращаемое значение Назначение

login (string userName, string userPassword, string projectName)

Token

Выполняет авторизацию пользователя в проекте.

  • переменная projectName может содержать кодовое название проекта. В этом случае осуществляется авторизация внутри проекта и пользователь может получить данные из проекта: задачи, пожелания и т.п.
  • если переменная projectName содержит пустую строку, то пользователь авторизуется в системе, но не может получить данные проекта.

Возвращает объект, содержащий авторизационные данные.

Классы

Название Атрибут Назначение

Token

Key

Ключ для авторизации пользователя при выполнении методов веб-сервисов.

Примеры (C#)

// авторизуемся в проекте
 security.SecurityService api = new security.SecurityService() { 
      Url = 'http://<host>/api/securityservice'
 };
 
 security.Token _token = api.login("guest", "guest", "development");

TestService API

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

Протокол: SOAP, WebService

Ссылка: http://<host>/api/testservice

WSDL описание (document/literal): http://<host>/api/testservice?wsdl

WSDL описание (rpc/encoded): http://<host>/api/testservice?wsdl&style=rpc&use=encoded

Методы

Название Возвращаемое значение Назначение

Create (string token.Key, TestScenario object)

TestScenario

Создание нового раздела тестовой документации, привязанного к корневому узлу тестовой документации. Атрибуты нового раздела передаются в параметре object. Возвращает объект, описывающий созданный тестовый раздел.

Find (string token.Key, TestScenario object)

TestScenario

Загрузка атрибутов раздела тестовой документации по заданным параметрам, определенным в object. Если задать значение object.Id, то метод выполнит поиск по идентификатору тестового раздела. Если указать значение атрибута object.Caption, то - найдет раздел по его названию. Возвращает объект, описывающий искомый тестовый раздел.

Append (string token.Key, TestScenario parent, TestScenario object)

TestScenario

Создает новый подраздел тестовой документации в существующем разделе, идентифицируемом параметром parent. Возвращает объект, описывающий созданный тестовый подраздел.

Run (string token.Key, TestScenario object, string version, Environment environment)

TestExecution

Запускает на тестирование переданный в качестве параметра object тестовый раздел документации. Если у переданного тестового раздела есть дочерние разделы, то в тест будет включать в себя все дочерние разделы. При создании теста можно указать версию тестируемого приложения, а также окружение, на котором осуществляется тестирование. Окружение идентифицируется атрибутов environment.Caption. Необходимо заранее настроить справочник окружений в проекте. Метод возвращает объект, описывающий тест.

ReportResult(string token.Key, TestExecution execution, TestScenario object, TestExecutionResult result)

Отметка о результате тестирования тестового раздела (object) в составе теста (execution). Результат выполнения идентифицируется атрибутом result.ReferenceName.

ReportIssue (string token.Key, TestExecution execution, TestScenario object, Request request)

Request

Регистрация в проекте ошибки, полученной в результате тестирования раздела (object) в составе теста (execution). Параметры ошибки, например, название, содержание и т.п. задается в атрибутах объекта request. В результате выполнения метода возвращается объект Request, описывающий созданное пожелание.

ReportFile (string token.Key, TestExecution execution, TestScenario object, Attachment file)

Загрузка в проект файла, связанного с результатами тестирования раздела (object) в составе теста (execution). Вы можете загрузить связанный с результатом снимок экрана, дамп или лог-файл.

GetResult (string token.Key, TestExecution execution)

TestExecutionResult

Возвращает текущий результат выполнения теста в виде объекта TestExecutionResult.

Классы

Название Атрибут Назначение

TestScenario

Id

Идентификатор объекта

Caption

Название тестового раздела

Content

Содержание тестового раздела

ParentPage

Идентификатор родительского тестового раздела

Environment

Id

Идентификатор объекта

Caption

Название окружения, уникальное значение, используемое для идентификации окружения

TestExecutionResult

Id

Идентификатор объекта

Caption

Отображаемое название результата

ReferenceName

Кодовое название результата, уникальное значение, используемое для идентификации типа результата

Request

Id

Идентификатор объекта

Caption

Название пожелания/ошибки

Description

Описание пожелания/ошибки

Attachment

Id

Идентификатор объекта

FilePath

Название файла, которое будет отображаться в проекте

FileExt

MIME-тип файла

File

Текстовое поле типа base64binary, содержащее тело файла в кодировке base64

Примеры (C#)

 // авторизуемся в проекте
 security.SecurityService api = new security.SecurityService() { 
      Url = 'http://<host>/api/securityservice'
 };
 
 security.Token _token = api.login("guest", "guest", "development");
 
 // создаем тестовый раздел документации
 testing.TestService _api = new testing.TestService() { 
      Url = 'http://<host>/api/testservice'
 };
 
 testing.testscenario root = new testing.testscenario { Caption = "Название 1"};
 root = _api.Create(_token.Key, root);
 
 // добавляем дочерний раздел
 testing.testscenario child = new testing.testscenario { Caption = "Название 2", Content = "Содержание 2" };
 child = _api.Append(_token.Key, root, child);
 
 // запускаем тест на выполнение
 testing.testexecution execution =
      _api.Run(_token.Key, root, "1.1", new testing.environment { Caption = "Windows XP" } );
 
 // устанавливаем результат тестирования по дочернему разделу
 _api.ReportResult(_token.Key, execution, child,
      new testing.testexecutionresult { ReferenceName = "failed" });
 
 // регистрируем ошибку
 testing.request bug = new testing.request { Caption = "Ошибка в тесте 2" };
 bug = _api.ReportIssue(_token.Key, execution, child, bug);
 
 // загружаем файл, например, дамп
 string fileName = Environment.GetEnvironmentVariable("windir") + "\\notepad.exe";
 FileStream fs = File.Open(fileName, FileMode.Open, FileAccess.Read);
 
 byte[] fileBytes = new byte[fs.Length];
 fs.Read(fileBytes, 0, (int)fs.Length);
 fs.Close();
 
 testing.attachment file = testing.attachment
 {
     FilePath = "notepad.exe",
     FileExt = (new FileInfo(fileName)).Extension,
     File = fileBytes
 };
 
 _api.ReportFile(_token.Key, execution, child, file);

SupportService API

Используйте данный веб-сервис для программного добавления доработок или регистрации ошибок. Использование сервиса доступно после авторизации. Все методы сервиса в качестве первого параметра принимают ключ, полученный после авторизации.

Протокол: SOAP, WebService

Ссылка: http://<host>/api/supportservice

WSDL описание (document/literal): http://<host>/api/supportservice?wsdl

WSDL описание (rpc/encoded): http://<host>/api/supportservice?wsdl&style=rpc&use=encoded

Методы

Название Возвращаемое значение Назначение

RaiseIssue (string token.Key, request issue)

request

Создание пожелания с параметрами, заданными в качестве значений атрибутов переменной issue.

AttachFile (string token.Key, request issue, attachment file)

attachment

Прикрепляет файл к пожеланию, идентифицируемому полем issue.Id. Атрибуты файла, равно как и тело файла содержится в значениях переменной file.

Классы

Название Атрибут Назначение

Request

Id

Идентификатор объекта

Caption

Название пожелания/ошибки

Description

Описание пожелания/ошибки

Attachment

Id

Идентификатор объекта

FilePath

Название файла, которое будет отображаться в проекте

FileExt

MIME-тип файла

File

Текстовое поле типа base64binary, содержащее тело файла в кодировке base64

Примеры (C#)

// авторизуемся в проекте
 security.SecurityService api = new security.SecurityService() { 
      Url = 'http://<host>/api/securityservice'
 };
 support.SupportService _supportService = new support.SupportService() { 
      Url = 'http://<host>/api/securityservice'
 };
 
 security.Token _token = api.login("guest", "guest", "development");
 
 var issue = new support.request() {
     Caption = "Краткое описание ошибки",
     Description = "Подробное описание ошибки"
 };
 
 issue = _supportService.RaiseIssue(_token.Key, issue);
 
 // загружаем файл, например, дамп
 string fileName = Environment.GetEnvironmentVariable("windir") + "\\notepad.exe";
 FileStream fs = File.Open(fileName, FileMode.Open, FileAccess.Read);
 
 byte[] fileBytes = new byte[fs.Length];
 fs.Read(fileBytes, 0, (int)fs.Length);
 fs.Close();
 
 support.attachment file = support.attachment
 {
     FilePath = "notepad.exe",
     FileExt = (new FileInfo(fileName)).Extension,
     File = fileBytes
 };
 
 _supportService.AttachFile(_token.Key, issue, file);

DataService API

Используйте данный веб-сервис для программного доступа к данным, хранящимся в Devprom ALM, например, с целью интеграции с другими инструментами, используемыми в работе. Все методы сервиса в качестве первого параметра принимают ключ, полученный после авторизации.

Протокол: SOAP, WebService

Ссылка: http://<host>/api/dataservice

WSDL описание (rpc/encoded): http://<host>/api/dataservice?wsdl

WSDL описание (document/literal): http://<host>/api/dataservice?wsdl&style=document&use=literal

Методы

Название Возвращаемое значение Назначение

<класс>RemoteAdd (string token.Key, <класс> object)

<класс>

Создание экземпляра <класс> с атрибутами по умолчанию, заданными в переменной object. Возвращает созданный экземпляр с заполненными полями Id и т.п.

<класс>RemoteAddBatch(string token.Key, <класс>[] objects)

<класс>

Создание экземпляров <класс> из вектора. Возвращает вектор созданных экземпляров с заполненными полями Id и т.п.

<класс>RemoteLoad (string token.Key, string id)

<класс>

Возвращает экземпляр <класс> загруженный по идентификатору id.

<класс>RemoteStore (string token.Key, string id, <класс> object)

Сохраняет атрибуты экземпляра <класс> идентифицируемого по id.

<класс>RemoteStoreBatch(string token.Key, <класс>[] objects)

Сохраняет атрибуты экземпляров типа <класс>, идентифицируемых значениями атрибутов Id.

<класс>RemoteDelete(string token.Key, string id)

Удаляет экземпляр <класс> идентифицируемый по id.

<класс>RemoteDeleteBatch(string token.Key, <класс>[] objects)

Удаляет экземпляры типа <класс>, идентифицируемых значениями атрибутов Id.

<класс>RemoteGetAll(string token.Key)

<класс>[]

Возвращает все сохраненные экземпляры <класс> в виде массива объектов.

<класс>RemoteFind (string token.Key, <класс> object)

<класс>[]

Выполняет поиск объектов по точному совпадению значений атрибутов object. Например, для поиска по названию, необходимо задать значение атрибута object.Caption и т.д. В результате возвращается массив экземпляров <класс>, удовлетворяющих критериям поиска

Классы

Название Атрибут Назначение

task

Id

Идентификатор объекта

Caption

Заголовок задачи

Priority

Идентификатор приоритета (ссылка на priority)

TaskType

Идентификатор типа задачи (ссылка на tasktype)

Release

Идентификатор итерации (спринта), в которую включена задачи (ссылка на iteration)

State

Текстовое значение текущего состояния задачи, например, submitted или resolved

Assignee

Идентификатор исполнителя (ссылка на paticipant)

ChangeRequest

Идентификатор исходного пожелания (ссылка на request)

Planned

Плановая трудоемкость по задаче в часах

LeftWork

Оставшаяся трудоемкость по задаче в часах

Fact

Фактически затраченное время на задачу в часах

Comments

Комментарий к задаче

RecordCreated

Дата и время создания задачи

RecordModified

Дата и время последней модификации задачи

Result

Текстовое значение результата выполнения задачи

priority

Id

Идентификатор объекта

Caption

Отображаемое название приоритета

tasktype

Id

Идентификатор объекта

Caption

Отображаемое название типа задачи

ReferenceName

Кодовое имя типа задачи, например, testdesign

iteration

Id

Идентификатор объекта

ReleaseNumber

Отображаемое название итерации

StartDate

Дата начала итерации

StartDate

Дата окончания итерации

IsActual

Признак актуальности итерации, "N" - итерация устарела

InitialVelocity

Начальная скорость команды для данной итерации

RecordCreated

Дата и время создания итерации

RecordModified

Дата и время последней модификации итерации

participant

Id

Идентификатор объекта

Caption

Отображаемое имя участника проекта

Email

Адрес электронной почты участника (readonly)

Login

Системное имя участника (readonly)

SystemUser

Идентификатор пользователя в системе (ссылка на user)

request

Id

Идентификатор объекта

Caption

Отображаемое имя пожелания (или истории пользователя)

requirement

Id

Идентификатор объекта

Caption

Отображаемое имя раздела требования

ParentPage

Ссылка на объект типа requirement, являющийся родительской страницей

PageType

Ссылка на объект типа wikipagetype, определяющий тип раздела требований

Content

Содержимое раздела требований

Примеры (C#)

// авторизуемся в проекте
 security.SecurityService api = new security.SecurityService() { 
      Url = 'http://<host>/api/securityservice'
 };
 data.DataService _dataService = new data.DataService() { 
      Url = 'http://<host>/api/dataservice'
 };
 
 security.Token _token = api.login("guest", "guest", "development");
 
 data.participant[] participants = _dataService.participantRemoteFind(
     _token.Key, new data.participant() { Caption = "Ivan Ivanovich" } );

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

C#

Данный пример описывает использование DataService - низкоуровневого сервиса Devprom SOAP API, позволяющего выполнять любые действия над данными в Devprom, которые разрешены правами доступа текущего пользователя.

Devprom SOAP API по-умолчанию доступен в любой поставке Devprom, независимо от ее редакции. Перечень поддерживаемых сервисов доступен в документации программных интерфейсов.

Пример предназначен для того, чтобы сформировать у вас базовое понимание принципов использования Devprom SOAP API. В формате теста (C#, nUnit) мы создадим нового пользователя в Devprom с заданным атрибутами и проверим, что этот пользователь может войти в систему.

 using DEVPROM.WebTest.Core;
 using NUnit.Framework;
 using DEVPROM.WebTest.devprom.api.security;
 using DEVPROM.WebTest.devprom.api.model;
 
 namespace DEVPROM.WebTest.Api
 {
   [TestFixture]
   public class ApiUser
   {
     [Test]
     public void TestCreateUser()
     {
       // login under administrator
       var securityService = new SecurityService() { Url = TestUtils.GetAppConfigurationItem("HostUrl") + "/api/securityservice" };
       var token = securityService.login(TestHelper.appUserName, TestHelper.appUserPassword, null);
 
       // low-level API data service
       var dataService = new DataService() { Url = TestUtils.GetAppConfigurationItem("HostUrl") + "/api/dataservice" };
 
       // create new user
       var testUser = new user()
       {
         Caption = "Api Test User",
         Description = "",
         Email = "apitestuser@devprom.ru",
         IsAdmin = "N", // Y or N
         Login = "ApiUser",
         Skype = "api_test",
         Phone = "+7910xxxxxxx",
         Password = "testpass"
       };
 
       var createdUser = dataService.userRemoteAdd(token.Key, testUser);
 
       // assert user created
       Assert.IsNotNull(createdUser.Id); // now we have user ID
       Assert.AreEqual(testUser.Caption, createdUser.Caption);
       Assert.AreEqual(testUser.Email, createdUser.Email);
 
       // assert user can login
       token = securityService.login(testUser.Login, testUser.Password, null);
       Assert.IsNotNullOrEmpty(token.Key, "Can't login under new user");
     }
   }
 }

Пространства имен (namespaces) DEVPROM.WebTest.devprom.api.security и DEVPROM.WebTest.devprom.api.model были автоматически созданы на основе WSDL http://localhost/api/securityservice?wsdl и http://localhost/api/dataservice?wsdl соответственно (Visual Studio - Project - Add Web Reference).

PHP

Создание нового пользователя:

<?php
 $security = new SoapClient(
     'https://demo.myalm.ru/api/securityservice?wsdl',
     array(
         'soap_version'=>SOAP_1_1,
         'cache_wsdl' => WSDL_CACHE_NONE,
         'trace'=>true
     )
 );
 $result = $security->login(
     array(
         'username' => '***',
         'userpass' => '***',
         'project' => '')
 );
 $token = $result->return;
 
 $data = new SoapClient(
     'https://demo.myalm.ru/api/dataservice?wsdl',
     array(
         'soap_version'=>SOAP_1_1,
         'cache_wsdl' => WSDL_CACHE_NONE,
         'trace'=>true
     )
 );
 
 $user = $data->__soapCall('user.RemoteAdd',
     array (
         'token' => $token->Key,
         'parms' => array (
              'Caption' => 'New user',
              'Password' => 'test',
              'AskChangePassword' => 'Y',
              'Language' => 1,
              'Email' => '',
              'Login' => '',
              'Description' => '',
              'Phone' => '',
              'Photo' => '',
              'PhotoExt' => '',
              'PhotoPath' => '',
              'NotificationTrackingType' => '',
              'NotificationEmailType' => '',
              'OrderNum' => '',
              'RecordCreated' => '',
              'RecordModified' => '',
              'Id' => '',
              'GroupId' => '',
              'ClassName' => '',
              'RecordVersion' => '',
              'Url' => ''
         )
     )
 );
 
 echo $user->Id;

Создание заявки и изменение ее статуса:

 <?php
  $security = new SoapClient(
      'https://demo.myalm.ru/api/securityservice?wsdl',
      array(
          'soap_version'=>SOAP_1_1,
          'cache_wsdl' => WSDL_CACHE_NONE,
          'trace'=>true
      )
  );
  $result = $security->login(
      array(
          'username' => '*****',
          'userpass' => '****',
          'project' => '****')
  );
  $token = $result->return;
  
  $data = new SoapClient(
      'https://demo.myalm.ru/api/dataservice?wsdl',
      array(
          'soap_version'=>SOAP_1_1,
          'cache_wsdl' => WSDL_CACHE_NONE,
          'trace'=>true
      )
  );
  
  $request = $data->__soapCall('request.RemoteAdd',
      array (
          'token' => $token->Key,
          'parms' => array (
              'Caption' => 'New request',
              'Description' => 'test',
              'Environment' => '',
              'Priority' => '',
              'Estimation' => '',
              'State' => 'submitted',
              'Type' => '',
              'Function' => '',
              'Author' => '',
              'Owner' => '',
              'Project' => '',
              'SubmittedVersion' => '',
              'ClosedInVersion' => '',
              'PlannedRelease' => '',
              'LifecycleDuration' => '',
              'StartDate' => '',
              'FinishDate' => '',
              'DeliveryDate' => '',
              'Fact' => '',
              'FactTasks' => '',
              'OrderNum' => '',
              'RecordCreated' => '',
              'RecordModified' => '',
              'RecordVersion' => '',
              'Attachment' => '',
              'Tags' => '',
              'Links' => '',
              'ProjectPage' => '',
              'Question' => '',
              'DueWeeks' => '',
              'Watchers' => '',
              'Id' => '',
              'ClassName' => '',
              'Url' => ''
          )
      )
  );
  
  echo $request->Id;
 
  $request->State = 'planned';
  $request = $data->__soapCall('request.RemoteStore',
      array (
          'token' => $token->Key,
 	 'id' =>  $request->Id,
          'parms' => $request
      )
  );