The TDConnection object is the object instantiated at the beginning of an Open Test Architecture application run. Nearly all other objects can be created from the TDConnection object or from objects created from the TDConnection object. A small number of utility objects are the only objects created without reference to the TDConnection object.
First, set up the connection object in one of the following ways:
Single sign -on
SSO introduced in ALM 15
Available in versions: ALM 15 and later
To initiate the connection and authenticate with an API Key in SSO mode, call the InitConnectionWithApiKey Method or InitConnectionWithApiKeyEx Method.
External Authentication (by using CAC and SiteMinder)
Available in versions: ALM 12.5x and 12.6x.
Before initiating the connection, you can configure it for single sign on using the SetBasicAuthHeaderMode Method and the SetServerCredentials Method.
To initiate the connection, call the InitConnectionEx Method.
Identity Provider (IdP)
Available in versions: ALM 14.x
The login and authentication processes are handled by an external Identity Provider (IdP). Supported authentication types: Basic authentication (username & password) and certificate-based authentication.
Use a WS-Trust authentication flow to acquire the LWSSO token you need for ALM, and then use it in a call to the InitConnectionWithCookiesEx Method to initiate the connection. For details, see Acquire an authentication token to use for ALM APIs.
API key
Available in versions: ALM 14.00 Patch 2 and later, ALM 12.60 and later.
Call the InitConnectionWithApiKey Method or InitConnectionWithApiKeyEx Method to initiate the connection and authenticate with an API key that you obtain from ALM administration. For details, see How to Manage API Keys.
Call the InitConnectionEx Method to initiate the connection and then authenticate a user with the Login Method.
Next, connect the user session to a project with the Connect Method. Call the Disconnect Method at the end of each project session.
Before the application exits, call the ReleaseConnection Method.
States after method calls
This table shows the status of some TDConnection properties from the initial state (new TDConnection) until the connection is released. The columns are the states after the invocation of the method in the top row.
Method Property | (Initial) | Init- ConnectionEx | Login | Connect | Disconnect | Logout | Release- Connection |
LoggedIn | Error | False | True | True | True | False | Error |
Connected | False | True | True | True | True | True | False |
ServerName | Empty String | Server name | Server name | Server name | Server name | Server name | Empty String |
ProjectName | Error | Empty String | Empty String | Project name | Empty String | Empty String | Error |
Project- Connected | Error | False | False | True | False | False | Error |
Implemented Interface | Description |
---|---|
ITDConnection_SendMailWithCC | Send Email |
// configure connection settings ConnectionSettings cs = new ConnectionSettings(); cs.ExecutionMode = TDAPI_EXECUTION_MODES.EXECUTION_MODE_INTERACTIVE; cs.BasicAuthHeaderMode = TDAPI_BASIC_AUTH_HEADER_MODES.HEADER_MODE_ONCE; cs.SetWebServerCredentials("login", "pass"); // import to OTA Connection TDConnection otaConnection = new TDConnection(); otaConnection.ImportConnectionSettings(cs); // pre-configure the connection to add Basic Auth Header at first request otaConnection.SetBasicAuthHeaderMode(TDAPI_BASIC_AUTH_HEADER_MODES.HEADER_MODE_ONCE); // set user credentials otaConnection.SetServerCredentials("Login", "Password"); // init connect to ALM server otaConnection.InitConnection("http://<server URL>/qcbin");
ApplyClientCert | Apply client certificate to connection, the parameter should be valid CERT_CONTEXT structure. |
ApplyCookie | Applies cookie to connection |
ChangePassword | Deprecated. Changes the password for the currently logged in user. |
Connect | Connects the logged-in user to the specified project in the domain. |
ConnectToVCSAs | Obsolete. Do not invoke. |
CreateBSTRMap | Create an IBSTRMap, If you create it you must release it. In C#: System.Runtime.InteropServices.Marshal.ReleaseComObject(map); |
CreateSession | Creates application session on server, similar to login operation but for SSO configuration. |
Disconnect | Disconnects the user from the currently connected project. |
DisconnectProject | Disconnects from the project. |
GetAllVisibleProjectDescriptors | The list of project descriptors under all domains that the current logged in user is allowed to connect to. |
GetApprovalId | Obtain approval token. |
GetAuthenticationToken | Get access token by approval token. |
GetCommonFavoriteFactory | Returns the factory that manages favorites. |
GetCommonFavoriteFolderFactory | Returns the factory that manages favorite folders. |
GetLicenses | Allocates multiple licenses types according to the LicensesType parameter. |
GetLicensesEx | Allocates multiple licenses types according to the LicensesType parameter. |
GetLicenseStatus | The license status for the specified client type. |
GetLinkedProjects | The project list of linked projects to this project. |
GetTDParamsNames | Returns the names of the site's parameters. |
GetTDVersion | The major and minor versions of the OTA API. |
GetTDVersionEx | The major, minor, minor-minor versions and build number of the OTA API. |
ImportConnectionSettings | Import of connection settings to connection |
ImportConnectionSettings2 | Import extended settings to connection. |
InitAndCheckServerCompatibility | Initialize connection and check whether server version is compatible with OTA |
InitConnectionEx | Initializes the connection. |
InitConnectionWithCookies | Initialize connection with provided SSO token cookie |
InitConnectionWithCookiesEx | Initialize the connection with an ALM server using a LWSSO token you acquired from the IdP and IdM that manage authentication. For details, see Acquire an authentication token to use for ALM APIs. IdP is supported only in ALM 14.x. |
IsSSPREnabled | Returns whether Self-Service Password Reset is enabled. |
Login | Authorizes the user. On success, the user is logged in and can connect to projects. In ALM 14.x, the authorization is not handled by ALM but by an external Identity Manager (IdM) and Identity Provider (IdP). The Login method is supported for backward compatibility and requires referencing IdmClientSdk.dll and IdmSdkWrapper.dll. To use the ALM 14.x authentication mechanism, develop your own authentication flow to acquire a LWSSO token from the IdP and IdM that manage authentication (see Acquire an authentication token to use for ALM APIs). Use the token you acquire to call InitConnectionWithCookiesEx Method instead of using this Login method. |
Logout | Terminates the user's session on this TDConnection. |
PurgeRuns | Deletes the specified runs. |
PurgeRuns2 | Deletes the specified runs. |
RefreshConnectionState | Refreshes the connection state: updates the Connected, LoggedIn, and ProjectConnected properties. |
ReleaseConnection | Releases the COM pointer created when the connection is initialized. |
SendFramedMail | Sends Mail. |
SendFramedMailEx | Sends Mail. |
SendMail | Sends Mail. |
SendMailEx | Sends Mail. |
SendMailWithCC | Sends Mail. |
SetBasicAuthHeaderMode | Set basic auth header mode |
SetConnectionSettingsLockKey | Set connection settings lock key. |
SetExecutionMode | Set execution mode to WebClient |
SetProxyCredentials | Sets credentials for authentication on proxy. |
SetServerCredentials | Sets credentials for authentication on server. |
SSPRChangePassword | Send the new password, SSPR_CIPHER, name (the user name that user entered in change password window, if it is impersonate this may be different from the real user name), to the server. |
SSPRSendMail | Send email that contain SSPR_LINK (URL + Cipher (user name + GUID) ) for change password window. |
SynchronizeFollowUps | Obsolete. Do not invoke. |
UseInstanceCache | Use instance cache of settings storages |
ActionPermission | The ActionPermission object for this connection. |
AlertManager | The AlertManager object for this connection. |
AssetRelationFactory | The AssetsRelationFactory object for this connection. |
AssetRepositoryItemFactory | The AssetRepositoryItemFactory object for this connection. |
AsyncMailEnabled | Checks if asynchronous mailing is enabled for the project. |
AuditPropertyFactory | The global AuditProperty factory, not associated with a specific entity. |
AuditRecordFactory | The global AuditRecord factory, not associated with a specific entity. |
BPComponentFactory | The BPComponentFactory object for this connection. |
BPIterationFactory | The BPIterationFactory object for this connection. |
BPIterationParamFactory | Get BPIterationParamFactory object for this connection. |
BPModelElementFactory | The BPModelElementFactory object for this connection. |
BPModelFactory | The BPModelFactory object for this connection. |
BPModelFolderFactory | The BPModelFolderFactory object for this connection. |
BPModelPathFactory | The BPModelPathFactory object for this connection. |
BPParamFactory | Get BPParamFactory object for this connection. |
BugFactory | The Bug Factory object for this connection. |
CheckoutRepository | The path of the checkout repository. |
Command | The Command object for this connection. |
CommonSettings | The Settings object for all users in this connection. |
ComponentFolderFactory | The Component Folder Factory object for this connection. |
ComponentParamFactory | The ComponentParamFactory object for this connection. |
ComponentStepFactory | The ComponentStepFactory object for this connection. |
Connected | Checks if the Open Test Architecture API server connection is initialized. |
CoverageFactory | The CoverageFactory for the connection. |
Customization | The Customization object for this connection. |
DBName | The name of the database. |
DBType | The database type. |
DeletedAssetInfoFactory | The DeletedAssetInfoFactory object for this connection. |
DesignStepFactory | The DesignStepFactory object for this connection. |
DirectoryPath | The path of the server side repository directory for the database repository type. |
DomainName | The current domain. |
DomainsList | The domain names for this site. |
ExtendedStorage | Disabled by default security settings. Use the entity-level extended storage property. |
ExternalAuthenticationEnabled | Checks if external authentication enabled on server |
Fields | A list of fields for the table specified in the DataType argument. |
GraphBuilder | The GraphBuilder object for the connection. |
HostFactory | The Hosts Factory object for this connection. |
HostGroupFactory | The HostGroupFactory object for this connection. |
IgnoreHtmlFormat | Indicates if formatted memo and description fields are returned as plain text without HTML tags. |
IsSearchSupported | Checks if the search function is enabled for the project. |
IsServerCompatible | Get Compatibility of OTA to Server |
LoggedIn | Checks if the user is currently logged in on this TDConnection. |
LoginMetadata | Gets metadata on different project types. |
LoginSessionId | The login session ID. |
MailConditions | The TDMailConditions object for this connection. |
ModuleVisible | Checks if the specified module is visible to the connected user. This property is used for Quality Center UI programming and has no function in third-party applications. |
PolicyStatus | The Policy Enforcement Status object of the connected project. |
ProductInfo | An IProductInfo reference pointing to the current build information. |
ProjectConnected | Checks if the TDConnection is connected to a project. |
ProjectName | The name of the connected project. |
ProjectProperties | The ProjectProperties object for this connection. |
ProjectSessionId | The project session ID. |
ProjectsList | The projects that are available in the domain to which Quality Center is connected. |
ProjectsListEx | The projects available within the specified domain. |
QCResourceFactory | The QC resource factory object for this connection. |
QCResourceFolderFactory | The QC resource folder factory object for this connection. |
ReleaseFolderFactory | The factory that manages release folders. |
ReportRole | The report role of the connected user. |
ReqFactory | The ReqFactory object for this connection. |
Rules | The RuleManager object for this connection. |
RunCriterionFactory | The RunCriterionFactory object for this connection. |
RunFactory | The RunFactory object for this connection. |
RunIterationFactory | The RunIterationFactory object for this connection. |
ServerName | The name of the connected Open Test Architecture API server. |
ServerTime | The time and date of the application server. |
ServerURL | The URL of the connected server. |
ServiceChangeFactory | The service change factory object for this connection. |
ServiceFactory | The service factory object for this connection. |
ServiceFolderFactory | The service folder factory object for this connection. |
ServiceGroupFactory | The service group factory object for this connection. |
StepFactory | The Step Factory for this connection. |
TDParams | Gets the value of the parameter whose name is specified by Request. |
TemplateManager | The Template Manager object of the connected project. |
TestConfigFactory | The TestConfigFactory object for this connection. |
TestCriterionFactory | The TestCriterionFactory object for this connection. |
TestFactory | The Test Factory object for this connection. |
TestFolderFactory | The TestFolderFactory object for this connection. |
TestLabFolderFactory | The TestLabFolderFactory object for this connection. |
TestRepository | The path of the tests directory of the connected project. |
TestSetFactory | The Test Set Factory object for this connection. |
TestSetTreeManager | The TestSetTreeManager object for this connection. |
TreeManager | The TreeManager object for the system tree. |
TSTestFactory | The factory that manages test instances in test sets. |
UserAssetFactory | The UserAssetFactory object for this connection. |
UserGroupsList | The names of the user groups of the currently connected project. |
UserName | The user connected to the project. |
UserSettings | The Settings object for the logged-on user. |
UsersList | The names of the users of the currently connected project. |
UsingProgress | Indicates if a progress bar is displayed. |
VcsDbRepository | The path of the VCS database of the connected project. |
VisibleDomains | The list of domain names that the current logged in user is permitted to view. |
VisibleProjects | The list of projects in the specified domain that the current logged in user is allowed to connect to. |