TDConnection Object
Members 
Description
Represents a single server connection.
Remarks

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:

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
Interfaces
Implemented Interface Description
ITDConnection_SendMailWithCC Send Email
Example
// 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");
Public Methods
Public Method ApplyClientCert Apply client certificate to connection, the parameter should be valid CERT_CONTEXT structure.
Public Method ApplyCookie Applies cookie to connection
Public Method ChangePassword Deprecated. Changes the password for the currently logged in user.
Public Method Connect Connects the logged-in user to the specified project in the domain.
Public Method ConnectToVCSAs Obsolete. Do not invoke.
Public Method CreateBSTRMap Create an IBSTRMap, If you create it you must release it. In C#: System.Runtime.InteropServices.Marshal.ReleaseComObject(map);
Public Method CreateSession Creates application session on server, similar to login operation but for SSO configuration.
Public Method Disconnect Disconnects the user from the currently connected project.
Public Method DisconnectProject Disconnects from the project.
Public Method GetAllVisibleProjectDescriptors The list of project descriptors under all domains that the current logged in user is allowed to connect to.
Public Method GetApprovalId Obtain approval token.
Public Method GetAuthenticationToken Get access token by approval token.
Public Method GetCommonFavoriteFactory Returns the factory that manages favorites.
Public Method GetCommonFavoriteFolderFactory Returns the factory that manages favorite folders.
Public Method GetLicenses Allocates multiple licenses types according to the LicensesType parameter.
Public Method GetLicensesEx Allocates multiple licenses types according to the LicensesType parameter.
Public Method GetLicenseStatus The license status for the specified client type.
Public Method GetLinkedProjects The project list of linked projects to this project.
Public Method GetTDParamsNames Returns the names of the site's parameters.
Public Method GetTDVersion The major and minor versions of the OTA API.
Public Method GetTDVersionEx The major, minor, minor-minor versions and build number of the OTA API.
Public Method ImportConnectionSettings Import of connection settings to connection
Public Method ImportConnectionSettings2 Import extended settings to connection.
Public Method InitAndCheckServerCompatibility Initialize connection and check whether server version is compatible with OTA
Public Method InitConnectionEx Initializes the connection.
Public Method InitConnectionWithCookies Initialize connection with provided SSO token cookie
Public Method 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.

Public Method IsSSPREnabled Returns whether Self-Service Password Reset is enabled.
Public Method 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.

Public Method Logout Terminates the user's session on this TDConnection.
Public Method PurgeRuns Deletes the specified runs.
Public Method PurgeRuns2 Deletes the specified runs.
Public Method RefreshConnectionState Refreshes the connection state: updates the Connected, LoggedIn, and ProjectConnected properties.
Public Method ReleaseConnection Releases the COM pointer created when the connection is initialized.
Public Method SendFramedMail Sends Mail.
Public Method SendFramedMailEx Sends Mail.
Public Method SendMail Sends Mail.
Public Method SendMailEx Sends Mail.
Public Method SendMailWithCC Sends Mail.
Public Method SetBasicAuthHeaderMode Set basic auth header mode
Public Method SetConnectionSettingsLockKey Set connection settings lock key.
Public Method SetExecutionMode Set execution mode to WebClient
Public Method SetProxyCredentials Sets credentials for authentication on proxy.
Public Method SetServerCredentials Sets credentials for authentication on server.
Public Method SSPRChangePassword Send the new password, SSPR_CIPHER, name (the user name that user entered in change password window, if it is impersonate this meby different from the real user name), to the server.
Public Method SSPRSendMail Send email that contain SSPR_LINK (URL + Cipher (user name + GUID) ) for change password window.
Public Method SynchronizeFollowUps Obsolete. Do not invoke.
Public Method UseInstanceCache Use instance cache of settings storages
Public Properties
Public Property ActionPermission The ActionPermission object for this connection.
Public Property AlertManager The AlertManager object for this connection.
Public Property AssetRelationFactory The AssetsRelationFactory object for this connection.
Public Property AssetRepositoryItemFactory The AssetRepositoryItemFactory object for this connection.
Public Property AsyncMailEnabled Checks if asynchronous mailing is enabled for the project.
Public Property AuditPropertyFactory The global AuditProperty factory, not associated with a specific entity.
Public Property AuditRecordFactory The global AuditRecord factory, not associated with a specific entity.
Public Property BPComponentFactory The BPComponentFactory object for this connection.
Public Property BPIterationFactory The BPIterationFactory object for this connection.
Public Property BPIterationParamFactory Get BPIterationParamFactory object for this connection.
Public Property BPModelElementFactory The BPModelElementFactory object for this connection.
Public Property BPModelFactory The BPModelFactory object for this connection.
Public Property BPModelFolderFactory The BPModelFolderFactory object for this connection.
Public Property BPModelPathFactory The BPModelPathFactory object for this connection.
Public Property BPParamFactory Get BPParamFactory object for this connection.
Public Property BugFactory The Bug Factory object for this connection.
Public Property CheckoutRepository The path of the checkout repository.
Public Property Command The Command object for this connection.
Public Property CommonSettings The Settings object for all users in this connection.
Public Property ComponentFolderFactory The Component Folder Factory object for this connection.
Public Property ComponentParamFactory The ComponentParamFactory object for this connection.
Public Property ComponentStepFactory The ComponentStepFactory object for this connection.
Public Property Connected Checks if the Open Test Architecture API server connection is initialized.
Public Property CoverageFactory The CoverageFactory for the connection.
Public Property Customization The Customization object for this connection.
Public Property DBName The name of the database.
Public Property DBType The database type.
Public Property DeletedAssetInfoFactory The DeletedAssetInfoFactory object for this connection.
Public Property DesignStepFactory The DesignStepFactory object for this connection.
Public Property DirectoryPath The path of the server side repository directory for the database repository type.
Public Property DomainName The current domain.
Public Property DomainsList The domain names for this site.
Public Property ExtendedStorage Disabled by default security settings. Use the entity-level extended storage property.
Public Property ExternalAuthenticationEnabled Checks if external authentication enabled on server
Public Property Fields A list of fields for the table specified in the DataType argument.
Public Property GraphBuilder The GraphBuilder object for the connection.
Public Property HostFactory The Hosts Factory object for this connection.
Public Property HostGroupFactory The HostGroupFactory object for this connection.
Public Property IgnoreHtmlFormat Indicates if formatted memo and description fields are returned as plain text without HTML tags.
Public Property IsSearchSupported Checks if the search function is enabled for the project.
Public Property IsServerCompatible Get Compatibility of OTA to Server
Public Property LoggedIn Checks if the user is currently logged in on this TDConnection.
Public Property LoginMetadata Gets metadata on different project types.
Public Property LoginSessionId The login session ID.
Public Property MailConditions The TDMailConditions object for this connection.
Public Property 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.
Public Property PolicyStatus The Policy Enforcement Status object of the connected project.
Public Property ProductInfo An IProductInfo reference pointing to the current build information.
Public Property ProjectConnected Checks if the TDConnection is connected to a project.
Public Property ProjectName The name of the connected project.
Public Property ProjectProperties The ProjectProperties object for this connection.
Public Property ProjectSessionId The project session ID.
Public Property ProjectsList The projects that are available in the domain to which Quality Center is connected.
Public Property ProjectsListEx The projects available within the specified domain.
Public Property QCResourceFactory The QC resource factory object for this connection.
Public Property QCResourceFolderFactory The QC resource folder factory object for this connection.
Public Property ReleaseFolderFactory The factory that manages release folders.
Public Property ReportRole The report role of the connected user.
Public Property ReqFactory The ReqFactory object for this connection.
Public Property Rules The RuleManager object for this connection.
Public Property RunCriterionFactory The RunCriterionFactory object for this connection.
Public Property RunFactory The RunFactory object for this connection.
Public Property RunIterationFactory The RunIterationFactory object for this connection.
Public Property ServerName The name of the connected Open Test Architecture API server.
Public Property ServerTime The time and date of the application server.
Public Property ServerURL The URL of the connected server.
Public Property ServiceChangeFactory The service change factory object for this connection.
Public Property ServiceFactory The service factory object for this connection.
Public Property ServiceFolderFactory The service folder factory object for this connection.
Public Property ServiceGroupFactory The service group factory object for this connection.
Public Property StepFactory The Step Factory for this connection.
Public Property TDParams Gets the value of the parameter whose name is specified by Request.
Public Property TemplateManager The Template Manager object of the connected project.
Public Property TestConfigFactory The TestConfigFactory object for this connection.
Public Property TestCriterionFactory The TestCriterionFactory object for this connection.
Public Property TestFactory The Test Factory object for this connection.
Public Property TestFolderFactory The TestFolderFactory object for this connection.
Public Property TestLabFolderFactory The TestLabFolderFactory object for this connection.
Public Property TestRepository The path of the tests directory of the connected project.
Public Property TestSetFactory The Test Set Factory object for this connection.
Public Property TestSetTreeManager The TestSetTreeManager object for this connection.
Public Property TreeManager The TreeManager object for the system tree.
Public Property TSTestFactory The factory that manages test instances in test sets.
Public Property UserAssetFactory The UserAssetFactory object for this connection.
Public Property UserGroupsList The names of the user groups of the currently connected project.
Public Property UserName The user connected to the project.
Public Property UserSettings The Settings object for the logged-on user.
Public Property UsersList The names of the users of the currently connected project.
Public Property UsingProgress Indicates if a progress bar is displayed.
Public Property VcsDbRepository The path of the VCS database of the connected project.
Public Property VisibleDomains The list of domain names that the current logged in user is permitted to view.
Public Property VisibleProjects The list of projects in the specified domain that the current logged in user is allowed to connect to.
See Also