ALM: User Guide

This example describes how to use DataService — a low-level ALM SOAP API service that can perform any action on data in ALM that the current user's permissions allow.

The ALM SOAP API is available by default in any ALM delivery, regardless of edition. The list of supported services is in the API documentation.

The example is meant to give you a basic understanding of how to use the ALM SOAP API. In a test (C#, nUnit) we create a new user in ALM with the specified attributes and check that this user can sign in.

 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");
     }
   }
 }

The namespaces DEVPROM.WebTest.devprom.api.security and DEVPROM.WebTest.devprom.api.model were generated automatically from the WSDL http://localhost/api/securityservice?wsdl and http://localhost/api/dataservice?wsdl respectively (Visual Studio — Project — Add Web Reference).

Creating a new user:

<?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;

Creating a Request and changing its status:

 <?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
      )
  );