Getting started

Review the following information before you get started with SOAP and the Helix ALM SDK.

Before you start

If you are using the SDK for the first time, you must do the following.

1. Install a web server, such as Microsoft IIS or Apache on the computer that will host the SOAP server.

2. Install the SDK components on the SOAP server. See Getting started.

3. Configure the web server to run ttsoapcgi.exe when called from a URL. For example, https://SOAPServer/scripts/ttsoapcgi.exe.

4. Set up a SOAP development environment, retrieve the WSDL file from the SOAP server, and generate the WSDL stub code. See About the WSDL file.

5. Create a dedicated SOAP user and assign it to a security group with permission to log in to the Helix ALM Server via SOAP. See Creating a dedicated SOAP user.

6. Connect to the SOAP server. See Connecting to the SOAP server.

Installing the SDK

You can install the SDK during Helix ALM installation. Select the Helix ALM Server installation with web and SOAP components installation type. During installation, you enter the IP address or domain name of the computer hosting the SOAP CGI and set the location of the WSDL file. See the installation help for information about installing the SDK.

Creating a dedicated SOAP user

If your SOAP application runs in the background on a regular basis, we recommend creating a dedicated Helix ALM user for use only with the application. This offers the following benefits:

  • You can embed the username and password in your application's source code. If you embed the credentials for an administrative user, there is a potential security risk because unauthorized users could have administrative access to Helix ALM. In the Helix ALM desktop client, create the dedicated SOAP user and add it to a security group that can only log in via SOAP, not the desktop or web clients. See the Helix ALM help for information about managing security groups.
  • You can limit the dedicated SOAP user's security permissions to the specific actions performed by the application. Keep in mind that developers may not be able to extend the application functionality if the SOAP user does not have sufficient permissions.
  • When you review the Helix ALM history or audit trail, you can more easily distinguish between changes made by the SOAP application and manual changes other users made.
  • You can avoid situations where users must wait to log in to Helix ALM because the SOAP application is running in the background. You can also avoid the scenario where a user logs in to a Helix ALM client, forgets to log out, and inadvertently blocks the SOAP application from logging in because a license is not available.

Creating accounts and configuring security

  • Command-level security is enforced on each SOAP operation call. For example, if the Add Issue security command is not enabled for the SOAP user, calls that use the AddDefect operation fail.
  • Field security is not enforced for SOAP users. For example, if an issue entered by a user is hidden or read-only in the user's security group, the Entered by username is returned when viewing or editing the issue using the SDK.
  • When you create a local user account, do not set the LoginName field for the CUser object. This disables and prevents enabling and promoting the user account.

Logging in and out

  • A SOAP user must first log in to the Helix ALM Server with a valid username and password.
  • A successful login returns a cookie used for all subsequent connections. The cookie value is returned by the projectLogon function, which is then passed as an argument to most other functions so the SOAP server knows the request is from a logged in user and who that user is.
  • The username and password specified during the SOAP login fails if the user does not have appropriate command-level security. The user must be in a security group that allows login via SOAP.
  • The SOAP client should always call the databaseLogoff operation after completing tasks. If you do not log out, the SOAP connection remains open and uses a SOAP license. The connection is eventually dropped after a period of inactivity. You can change the session timeout limit in the Helix ALM Server Admin Utility. See the Server Admin help for information.
  • Every operation, except getProjectList and projectLogon, requires a cookie as an input parameter. Other operations fail if you do not obtain a valid cookie using the projectLogon operation. Call the getProjectList operation before logging in to retrieve a list of available projects.