Documente Academic
Documente Profesional
Documente Cultură
TestDirector Site Administrator Client API Guide, Version 8.0 This manual, and the accompanying software and other documentation, is protected by U.S. and international copyright laws, and may be used only in accordance with the accompanying license agreement. Features of the software, and of other products and services of Mercury Interactive Corporation, may be covered by one or more of the following patents: U.S. Patent Nos. 5,701,139; 5,657,438; 5,511,185; 5,870,559; 5,958,008; 5,974,572; 6,138,157; 6,144,962; 6,205,122; 6,237,006; 6,341,310; 6,360,332, 6,449,739; 6,470,383; 6,477,483; 6,549,944; 6,560,564; and 6,564,342.6,564,342; 6,587,969; 6,631,408; 6,631,411; 6,633,912 and 6,694,288. Other patents pending. All rights reserved. Mercury, Mercury Interactive, the Mercury Interactive logo, LoadRunner, LoadRunner TestCenter, QuickTest Professional, SiteScope, SiteSeer, TestDirector, Topaz and WinRunner are trademarks or registered trademarks of Mercury Interactive Corporation or its subsidiaries, in the United States and/or other countries. The absence of a trademark from this list does not constitute a waiver of Mercury Interactives intellectual property rights concerning that trademark. All other company, brand and product names are registered trademarks or trademarks of their respective holders. Mercury Interactive Corporation disclaims any responsibility for specifying which marks are owned by which companies or which organizations. Mercury Interactive Corporation 379 North Whisman Road Mountain View, CA 94043 Tel: (650) 603-5200 Toll Free: (800) TEST-911 Customer Support: (877) TEST-HLP Fax: (650) 603-5300 2004 Mercury Interactive Corporation, All rights reserved
If you have any comments or suggestions regarding this document, please send them via e-mail to documentation@mercury.com.
TDSACG8.0/02
Table of Contents
Welcome to the TestDirector Site Administrator Client API ...............v Using This Guide ..................................................................................vi TestDirector Documentation Set..........................................................vi Online Resources .................................................................................vii Documentation Updates ................................................................... viii Typographical Conventions.................................................................ix Chapter 1: Introduction......................................................................1 Working with the Site Administrator API.............................................2 API Functions ........................................................................................3 Chapter 2: Alphabetical Reference ....................................................9 ActivateProject.....................................................................................10 ActivateSendAllQualified ....................................................................14 AddDBServer........................................................................................18 Connect ...............................................................................................19 ContinueProject ..................................................................................22 CreateDomain .....................................................................................26 CreateProject .......................................................................................29 CreateProjectCopy...............................................................................35 CreateSiteSingleParam.........................................................................43 CreateUser ...........................................................................................45 DeactivateProject.................................................................................48 DeactivateSendAllQualified.................................................................52 DeleteDomain......................................................................................56 DeleteProject........................................................................................58 DeleteSiteSingleParam .........................................................................60 DeleteUser............................................................................................61 DisableVersionControl ........................................................................62 Disconnect...........................................................................................66 DisconnectDomain..............................................................................67 DisconnectAll ......................................................................................68 DisconnectProject................................................................................69
iii
DisconnectUser ...................................................................................71 EnableVersionControl .........................................................................72 GetAllDomainProjects.........................................................................76 GetAllDomains ....................................................................................80 GetAllUsers ..........................................................................................84 GetConnections ..................................................................................87 GetConnectionsCount ........................................................................90 GetDcUsers ..........................................................................................92 GetDomain ..........................................................................................95 GetProject ............................................................................................99 GetProjectExtendedData ...................................................................103 GetSiteAllParams ...............................................................................109 GetSiteSingleParam ...........................................................................112 GetUser ..............................................................................................114 MoveProjectToDomain .....................................................................117 RemoveDBServer ...............................................................................122 RemoveProject...................................................................................123 RestoreProject ....................................................................................125 RunQuery ..........................................................................................130 SendAllQualifiedNow ........................................................................136 SetDomainProperty ...........................................................................138 SetProjectProperty .............................................................................142 SetSiteSingleParam ............................................................................148 SetUserProperty .................................................................................150 TestConnection .................................................................................153 UpgradeProject ..................................................................................155 Index..................................................................................................157
iv
Note: New API examples are continuously being added to the Knowledge Base on the Mercury Customer Support Web site. To search the TestDirector Knowledge Base for new information, select Using the Site Administrator Client - API from the Topic list.
Chapter 1
Introduction
Provides an overview of the Site Administrator Client API. It also provides a list of API functions grouped according to the Site Administrator Client objects. Functions are arranged alphabetically within each category, and a brief description of each function is included.
Chapter 2
Alphabetical Reference
Lists all API functions alphabetically. A description and complete syntax are provided. The definition of the functions parameters, its return values, and examples of the functions use are also described.
vi
TestDirector Open Test Architecture Guide explains how to use TestDirectors open test architecture to integrate your own configuration management, defect tracking, and home-grown testing tools with a TestDirector project. It includes a complete reference to the TestDirector COM-based API.
Online Resources
TestDirector includes the following online resources: Readme provides last-minute news and information about TestDirector. Books Online displays the complete documentation set in .PDF format. Online books can be read and printed using Adobe Acrobat Reader 5.0, which can be downloaded from the Adobe Web site (http://www.adobe.com/products/acrobat/readstep2.html). TestDirector Online Help provides immediate answers to questions that arise as you work with TestDirector. It describes menu commands and dialog boxes, and shows you how to perform TestDirector tasks. Check Mercury Interactives Customer Support Web site (http://support.mercury.com) for updates to TestDirector help files. Customer Support Online uses your default Web browser to open Mercury Interactives Customer Support Web site. This site enables you to browse the knowledge base and add your own articles, post to and search user discussion forums, submit support requests, download patches and updated documentation, and more. The URL for this Web site is http://support.mercury.com. Mercury Interactive on the Web uses your default Web browser to open Mercury Interactives home page. This site provides the most up-to-date information on Mercury Interactive and its products. This includes new application releases, seminars and trade shows, customer support, educational services, and more. The URL for this Web site is http://www.mercury.com.
vii
Documentation Updates
Mercury Interactive is continuously updating its product documentation with new information. You can download the latest version of this document from the Customer Support Web site (http://support.mercury.com). To download updated documentation: 1 In the Customer Support Web site, click the Documentation link. 2 Under Select Product Name, select TestDirector. Note that if TestDirector does not appear in the list, you must add it to your customer profile. Click My Account to update your profile. 3 Click Retrieve. The Documentation page opens and lists the documentation available for the current release and for previous releases. If a document was recently updated, Updated appears next to the document name. 4 Click a document link to download the documentation.
viii
Typographical Conventions
This book uses the following typographical conventions: 1, 2, 3 > Stone Sans Bold numbers indicate steps in a procedure. Bullets indicate options and features. The greater than sign separates menu levels (for example, File > Open). The Stone Sans font indicates names of interface elements (for example, the Run button) and other items that require emphasis. Bold text indicates function and object names. Italic text indicates property and parameter names. The Arial font is used for examples and statements that are to be typed in literally. The Courier New font is used for syntax examples in the object reference. The Courier New italic font is used for comments within examples.
Bold Italics
ix
1
Introduction
The TestDirector Site Administrator Client application program interface (API) enables you to integrate your custom and third-party tools with the TestDirector Site Administrator, enabling you to manage and control your projects from a remote site. The Site Administrator Client is a COM-based API that helps you organize, manage, and maintain all users, projects, domains, connections, and site configuration parameters in your application. The following diagram illustrates the process of integrating your application with the Site Administrator:
Network Network
The Site Administrator user interface uses the same API for all of its operations, such as connecting to a project, importing information from external applications to a project, and exporting information from a project to an external application. After you have installed TestDirector, you can use the Site Administrator Client API to create a TestDirector project. A TestDirector project is a database for collecting and storing data relevant to a testing process. A TestDirector project can work on Microsoft Access, Oracle, Sybase, or Microsoft SQL. You can create an empty TestDirector project, or you can copy the content of an existing project to a new project. You can also restore access to an existing project.
After you create a project, you can query the contents of a project by defining and running SQL statements, and activating/deactivating access to a project. You can also upgrade a project from a previous TestDirector version to the current TestDirector version. TestDirector projects are grouped by domain. A domain contains a group of related TestDirector projects and assists you in organizing and managing a large number of projects. For example, you may wish to create one domain for business process projects and another domain for IT development projects. Once your projects and domains are set, you need to add or import new TestDirector users, and define user properties. You can also monitor the users currently connected to the TestDirector server. For more information on TestDirector Site Administrator features, refer to the TestDirector Administrators Guide.
Chapter 1 Introduction
API Functions
This section groups the API functions according to the following Site Administrator Client subjects: Users Projects Domains Connections Site Configuration Parameters Database Servers
Users
You can define users on the TestDirector server by adding or importing them. You can also set user properties and get user information from all of the available domains. You can manage users with the following functions:
See Page 45 61 84 92 114 150
Description Creates a new user. Deletes a user from the user list. Gets all users and their properties from the server. Gets user information from domains. Gets the user properties. Sets a specific user property.
Projects
A TestDirector project is a database for collecting and storing data relevant to a testing process. You can manage projects with the following functions:
See Page 10 14 22 29 35
Description Activates the project. Activates the SEND ALL QUALIFIED option for a specific project. Continues an interrupted project creation. Creates a new project. Creates a new project by copying some, or all, data and properties from an existing project. Deactivates a project. Deactivates the SEND ALL QUALIFIED option for a specific project. Deletes a project. Disables project version control (if version control available). Enables project version control. Gets the properties of all projects in a domain. Gets the properties of a project. Gets the project extended data (all project properties and database information). Moves a project to another domain.
48 52 58 62 72 76 99 103
MoveProjectToDomain
117
Chapter 1 Introduction
Description Removes a project from a domain without deleting the project. Restores an existing project to a domain. Runs the SQL statement on the project database and returns results. Sends an email to all qualified personnel immediately. Sets the project property to a selected value. Tests a projects current database connection. Upgrades an existing project to the latest version.
Domains
TestDirector projects are grouped by domain. A domain contains a group of related TestDirector projects and assists you in organizing and managing a large number of projects. You can manage domains with the following functions:
See Page 26 56 80 95 138
Description Creates a new domain. Deletes a domain. Gets all domains, projects, and their properties. Gets the properties of all projects in a domain. Sets a domain property.
Connections
You can manage connections to the TestDirector server. Each time you open a new TestDirector browser, a new connection to the server is established You can manage connections with the following functions:
See Page 66 68 67 69 71
Description Disconnects a specific connection to the TestDirector server. Disconnects all connections to the TestDirector server. Disconnects all connections to a domain. Disconnects all connections to a project. Disconnects all connections for a given user from the TestDirector server. Gets the properties of all connections to the TestDirector server. Gets the connection count to the TestDirector server.
GetConnections GetConnectionsCount
87 90
Chapter 1 Introduction
Description Creates a new site configuration parameter. Deletes a site configuration parameter. Gets the properties of all site configuration parameters. Gets the properties of one site configuration parameter. Sets the properties of one site configuration parameter.
Database Servers
You can define new database servers and remove old ones. You can manage the database servers with the following functions:
See Page 18 122
Description Defines a new database server. Deletes a database server from the database server list.
2
Alphabetical Reference
This chapter contains an alphabetical reference of all Site Administrator Client functions in TestDirector. The following information is provided for each function: description syntax parameters return values examples
ActivateProject
Activates the project.
Syntax
ActivateProject ( BSTR DomainName, BSTR ProjectName )
Parameters
Name DomainName ProjectName Type String String Description The domain name. The project name.
Return Values
If the function is successful, an XML string with project properties is returned. The following is a general example of the XML string format:
10
11
CREATE_FROM_PROJECT CREATE_FROM_DOMAIN PHYSICAL_DIRECTORY DB_USER DB_USER_PASS DBSERVER_NAME DBCONNSTR_FORMAT DB_ENCRYPTED_CONNSTR PR_IS_ACTIVE SAQ_IS_ACTIVE
String String String String String String String String String String
12
Name PR_HAS_VCSDB
Type String
Description Indicates if the project includes version control: (Y)es, (N)o, (D)isabled. This field appears only if version control is available. The maximum number of concurrent connections. -1 indicates an unlimited number of connections. The version of the project. Repository for VMWare integration.
USERS_QUOTA
Number
VERSION VM_REPOSITORY
String String
Activate Example
The following Visual Basic example activates the project: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sDomainName As String Dim sProjectName As String Dim sReply As String On Error GoTo err sDomainName = "MyDomain" sProjectName = "MyProject" sReply = m_SAClient.ActivateProject(sDomainName, sProjectName) MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
13
ActivateSendAllQualified
Activates the SEND
ALL QUALIFIED
Syntax
ActivateSendAllQualified ( BSTR DomainName, BSTR ProjectName )
Parameters
Name DomainName ProjectName Type String String Description The domain name. The project name.
Return Values
If the function is successful, an XML string with project properties is returned. The following is a general example of the XML string format:
14
15
CREATE_FROM_PROJECT CREATE_FROM_DOMAIN PHYSICAL_DIRECTORY DB_USER DB_USER_PASS DBSERVER_NAME DB_CONNSTR_FORMAT DB_ENCRYPTED_CONNSTR PR_IS_ACTIVE SAQ_IS_ACTIVE
String String String String String String String String String String
16
Name PR_HAS_VCSDB
Type String
Description Indicates if the project includes version control: (Y)es, (N)o, (D)isabled. This field appears only if version control is available. The maximum number of concurrent connections. -1 indicates an unlimited number of connections. The version of the project. Repository for VMWare integration.
USERS_QUOTA
Number
VERSION VM_REPOSITORY
String String
ActivateSendAllQualified Example
The following Visual Basic example activates the SendAllQualified function: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sDomainName As String Dim sProjectName As String Dim sReply As String On Error GoTo err sDomainName = "MyDomain" sProjectName = "MyProject" sReply = m_SAClient.ActivateSendAllQualified _ (sDomainName, sProjectName) MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
17
AddDBServer
Defines a new database server.
Syntax
AddDBServer ( long DbType, BSTR DBServerName, BSTR DBAdminUser, BSTR DBAdminPassword, BSTR DbUserPassword, BSTR ConnectionStringFormat )
Parameters
Name DBType Type Number Description The type of database. Use the following constants or their values: SA_ACCESS_DB_TYPE (value: 1) SA_MSSQL_DB_TYPE (value: 2) SA_ORACLE_DB_TYPE (value: 3) SA_SYBASE_DB_TYPE (value: 4). DBServerName DBAdminUser DBAdminPassword DBUserPassword ConnectionStringFormat String String String String String The database server name. The database administrator. The database administrator password. The TestDirector user password. The projects ADO connection string.
Return Values
If the function is successful, an XML string with project properties is returned.
18
Connect
Connects the server to the Site Administrator client.
Note: This function must be run before calling any another function.
Syntax
Connect ( BSTR domainserver, BSTR password, BSTR * Response )
Parameters
Name DomainName ProjectName Type String String Description The name of the server to connect. The site administrator password.
Return Values
If the function is successful, 1 is returned.
19
Connect Example
The following Visual Basic example establishes a connection to the Site Administrator client. 1 Create a new standard EXE project by selecting File > New Project and Standard EXE. 2 Add a reference to the OTA API by selecting Project > References, and choosing the SAClient 1.0 Type Library reference. 3 Add a command button to the form. 4 Add the following code:
Private Sub Command1_Click() Dim sServerName As String Dim sPassword As String Dim sReply As String Create instance of Site Administrator API Dim m_SAClient As New SAapi On Error GoTo Connect_err sServerName = "MyServer" sPassword = "MyPassword" sReply = m_SAClient.Connect(sServerName, sPassword) MsgBox "Program succeeded" Exit Sub Connect_err: MsgBox "Program failed:" + Err.Description End Sub
20
Base Example
The following Visual Basic example serves as a base for most of the other examples. 1 Create a new standard EXE project. Choose File > New Project and select Standard.EXE. Click OK. 2 Choose Project > References and check the SAClient 1.0 Type Library reference. Click OK. 3 Add a command button to the form. 4 Add the following code:
Dim m_SAClient As SAapi Private Sub Form_Load() Dim sServerName As String Dim sPassword As String Dim sReply As String Create instance of Site Administrator API Set m_SAClient = New SAapi On Error GoTo Connect_err sServerName = "MyServer" sPassword = "MyPassword" sReply = m_SAClient.Connect(sServerName, sPassword) Exit Sub Connect_err: MsgBox "Program failed:" + Err.Description End Sub Private Sub Form_Unload(Cancel As Integer) m_SAClient.DisconnectAll End Sub
21
ContinueProject
Continues an interrupted project creation.
Syntax
ContinueProject ( BSTR DomainName, BSTR ProjectName )
Parameters
Name DomainName ProjectName Type String String Description The domain name. The project name.
Return Values
If the function is successful, an XML string with project properties is returned. The following is a general example of the XML string format:
22
23
CREATE_FROM_PROJECT CREATE_FROM_DOMAIN PHYSICAL_DIRECTORY DB_USER DB_USER_PASS DBSERVER_NAME DBCONNSTR_FORMAT DB_ENCRYPTED_CONNSTR PR_IS_ACTIVE SAQ_IS_ACTIVE
String String String String String String String String String String
24
Name PR_HAS_VCSDB
Type String
Description Indicates if the project includes version control: (Y)es, (N)o, (D)isabled. This field appears only if version control is available. The maximum number of concurrent connections. -1 indicates an unlimited number of connections. The version of the project. Repository for VMWare integration.
USERS_QUOTA
Number
VERSION VM_REPOSITORY
String String
ContinueProject Example
The following Visual Basic example activates the project: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sDomainName As String Dim sProjectName As String Dim sReply As String On Error GoTo err sDomainName = "MyDomain" sProjectName = "MyProject" sReply = m_SAClient.ContinueProject _ (sDomainName, sProjectName) MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
25
CreateDomain
Creates a new domain.
Syntax
CreateDomain ( BSTR DomainName, BSTR ContactName, BSTR ContactEmail, long UserQuota )
Parameters
Name DomainName ContactName ContactEmail UserQuota Type String String String Number Description The domain name. The contact name. The contact email. The user connection number quota. -1 indicates an unlimited number of connections.
Return Values
If the function is successful, an XML string with domain information is returned. The following is a general example of the XML string format:
26
DEFECTS_QUOTA
Number
27
Description Not in use. Not in use. For internal use. The domain projects are in this list. (This list is always empty when creating a domain.)
CreateDomain Example
The following Visual Basic example creates a new domain: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim Dim Dim Dim sDomainName As String sContactName As String sContactEmail As String sReply As String
On Error GoTo err sDomainName = "MyNewDomain" sContactName = "John Q. Public" sContactEmail = "jpublic@isp.net" sReply = m_SAClient.CreateDomain _ (sDomainName, sContactName, sContactEmail, 500) MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
28
CreateProject
Creates a new project.
Syntax
CreateProject ( BSTR DomainName, BSTR ProjectName, long DbType, BSTR DbServerName, BSTR AdminUser, BSTR AdminPassword, BSTR TableSpace, BSTR TempTableSpace, long TableSpaceSize, long TempTableSpaceSize, long CreationOptions )
Parameters
Name DomainName ProjectName DbType Type String String Number Description The domain of the new project. The new project name. The type of database. Use the following constants or their values: SA_ACCESS_DB_TYPE (value: 1) SA_MSSQL_DB_TYPE (value: 2) SA_ORACLE_DB_TYPE (value: 3) SA_SYBASE_DB_TYPE (value: 4). DbServerName AdminUser AdminPassword TableSpace TempTableSpace TableSpaceSize String String String String String Number The database server name. User name of project administrator. Administrator password. Storage on disk of Oracle database tables. If not Oracle, pass empty string (). Temporary storage location on disk for Oracle. If not Oracle, pass empty string (). Size of space allocated tables for Oracle. If not Oracle, pass zero (0).
29
Description Size of temporary storage space for Oracle. If not Oracle, pass zero (0). Specifies flags that control project creation. Use the following constants or their values: When no options are selected: SA_PROJECT_CREATION_NONE (value: 0) When activating a created project: SA_ACTIVATE_NEW_PROJECT (value: 1) When enabling version control (if available): SA_CREATE_VERSION_CONTROL_DB (value: 2)
Return Values
If the function is successful, an XML string with project properties is returned. The following is a general example of the XML string format:
30
31
CREATE_FROM_PROJECT CREATE_FROM_DOMAIN PHYSICAL_DIRECTORY DB_USER DB_USER_PASS DBSERVER_NAME DB_CONNSTR_FORMAT DB_ENCRYPTED_CONNSTR PR_IS_ACTIVE SAQ_IS_ACTIVE
String String String String String String String String String String
32
Name PR_HAS_VCSDB
Type String
Description Indicates if the project includes version control (Y/N/D) yes/no/disabled. Field appears only if version control is available. The maximum number of concurrent connections. -1 indicates an unlimited number of connections. The version of the project. Repository for VMWare integration.
USERS_QUOTA
Number
VERSION VM_REPOSITORY
String String
33
CreateProject Example
The following Visual Basic example creates a new project in an existing domain: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sDomainName As String Dim sProjectName As String Dim sServerName As String Dim CreateOptions As Long Dim sReply As String On Error GoTo err sDomainName = "MyNewDomain" sProjectName = "MyNewProject" sServerName = "MyServerName" CreateOptions = SA_ACTIVATE_NEW_PROJECT sReply = m_SAClient.CreateProject _ (sDomainName, sProjectName, SA_ACCESS_DB_TYPE, _ sServerName, "admin", "swordfish", _ "", "", 0, 0, _ CreateOptions) MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
34
CreateProjectCopy
Creates a new project by copying some, or all, data and properties from an existing project.
Note: The source project must be deactivated before this function is called.
Syntax
CreateProjectCopy ( BSTR DomainName, BSTR NewProjectName, int NewDbType, BSTR SourceDomainName, BSTR SourceProjectName, BSTR DbServerName, BSTR AdminUser, BSTR AdminPassword, BSTR TableSpace, BSTR TempTableSpace, long TableSpaceSize, long TempTableSpaceSize, long CopyOptions, long CreationOptions )
Parameters
Name DomainName NewProjectName NewDbType Type String String Number Description The domain of the new project. The new project name. The type of database. Use the following constants or their values: SA_ACCESS_DB_TYPE (value: 1) SA_MSSQL_DB_TYPE (value: 2) SA_ORACLE_DB_TYPE (value: 3) SA_SYBASE_DB_TYPE (value: 4). SourceDomainName SourceProjectName DbServerName AdminUser String String String String The domain of the existing project. The name of the existing project. The database server name. User name of project administrator.
35
Description Administrator password. Storage on disk of Oracle database tables. If not Oracle, pass empty string (). Temporary storage location on disk for Oracle. If not Oracle, pass empty string (). Size of space allocated tables for Oracle. If not Oracle, pass zero (0). Size of temporary storage space for Oracle. If not Oracle, pass zero (0).
36
Name CopyOptions
Type Number
Description Specifies flags that control project creation. Flags can be ORed together to specify multiply options. Use the following constants or their values: For no copying : SA_COPY_PROJECT_NONE (value: 0) For copying project customization: SA_COPY_PROJECT_CUSTOMIZATION (value: 1) SA_COPY_PROJECT_REQUIREMENTS (value: 2) SA_COPY_PROJECT_TESTS (value: 4) SA_COPY_PROJECT_TEST_SETS (value: 8) SA_COPY_PROJECT_RUNS (value: 16) SA_COPY_PROJECT_DEFECTS (value: 32) For copying the history of /reqs/tests/testset/runs/defects: SA_COPY_PROJECT_INCLUDE_HISTORY (value: 64) SA_COPY_PROJECT_PUBLIC_ FAVORITES_VIEW(value: 128) SA_COPY_PROJECT_USERS_AND_ GROUPS(value: 256) SA_COPY_PROJECT_PRIVATE_FAVORITES_ VIEW(value: 512) SA_COPY_PROJECT_MAIL_CONDITIONS (value: 1024) Copies all available data from the source project: SA_COPY_ALL (value: 2048)
37
Name CreationOptions
Type Number
Description Specifies flags that control project creation. Use the following constants or their values: For no options selected: SA_PROJECT_CREATION_NONE (value: 0) For activating a created project: SA_ACTIVATE_NEW_PROJECT (value: 1) For enabling version control (if available): SA_CREATE_VERSION_CONTROL_DB (value: 2)
Return Values
If the function is successful, an XML string with project properties is returned. The following is a general example of the XML string format:
38
39
CREATE_FROM_PROJECT CREATE_FROM_DOMAIN PHYSICAL_DIRECTORY DB_USER DB_USER_PASS DBSERVER_NAME DB_CONNSTR_FORMAT DB_ENCRYPTED_CONNSTR PR_IS_ACTIVE SAQ_IS_ACTIVE
String String String String String String String String String String
40
Name PR_HAS_VCSDB
Type String
Description Indicates if the project includes version control: (Y)es, (N)o, (D)isabled. This field appears only if version control is available. The maximum number of concurrent connections. -1 indicates an unlimited number of connections. The version of the project. Repository for VMWare integration.
USERS_QUOTA
Number
VERSION VM_REPOSITORY
String String
CreateProjectCopy Example
The following Visual Basic example creates a new project in an existing domain by copying the customization requirements and users from an existing project: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sDomainName As String Dim sNewProjectName As String Dim sProjectName As String Dim sServerName As String Dim CreateOptions As Long Dim CopyOptions As Long Dim sReply As String On Error GoTo err sDomainName = "MyNewDomain" sNewProjectName = "MyBrandNewProject" sProjectName = "MyNewProject" sServerName = "MyServerName" Deactivate source project Call m_SAClient.DeactivateProject(sDomainName, sProjectName)
41
TestDirector Site Administrator Client API Guide Copy from source project to new project CreateOptions = SA_ACTIVATE_NEW_PROJECT CopyOptions = SA_COPY_PROJECT_CUSTOMIZATION _ + SA_COPY_PROJECT_REQUIREMENTS _ + SA_COPY_PROJECT_USERS_AND_GROUPS sReply = m_SAClient.CreateProjectCopy _ (sDomainName, sNewProjectName, SA_ACCESS_DB_TYPE, _ sDomainName, sProjectName, _ sServerName, "admin", "swordfish", _ "", "", 0, 0, _ CopyOptions, CreateOptions) Reactivate source project Call m_SAClient.ActivateProject(sDomainName, sProjectName) MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
42
CreateSiteSingleParam
Creates a new site configuration parameter.
Syntax
CreateSiteSingleParam ( BSTR ParamName, BSTR ParamValue, BSTR ParamDescription )
Parameters
Name ParamName ParamValue ParamDescription Type String String String Description The parameter name. The new parameter value. The new parameter description.
Return Values
If the function is successful, 1 is returned.
43
CreateSiteSingleParam Example
The following Visual Basic example creates a new site configuration parameter: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sReply As String On Error GoTo err sReply = m_SAClient.CreateSiteSingleParam _ ("MaxReqsPerBranch", "500", "Max Requirements per branch") MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
44
CreateUser
Creates a new user.
Syntax
CreateUser ( BSTR UserName, BSTR FullName, BSTR Email, BSTR Phone, BSTR Description, BSTR Password )
Parameters
Name UserName FullName Email Phone Description Password Type String String String String String String Description The new user name. The full name of the user. The new user email. The new user phone. The new user description. The new user password.
Returned values
If the function is successful, an XML string with project properties is returned. The following is a general example of the XML string format:
45
46
CreateUser Example
The following Visual Basic example creates a new user: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sReply As String On Error GoTo err sReply = m_SAClient.CreateUser("alex_td", "Alex Dashevsky", _ "alex_td@tgg.com", "301-3432778", "TestDirector_Demo", _ "alexPassword") MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
47
DeactivateProject
Deactivates a project.
Note: The source project must be deactivated before this function is called.
Syntax
DeactivateProject ( BSTR DomainName, BSTR ProjectName )
Parameters
Name DomainName ProjectName Type String String Description The domain name. The project name.
Return Values
If the function is successful, an XML string with project properties is returned. The following is a general example of the XML string format:
48
49
The following table displays the property details of the XML example:
Name PROJECT_ID PROJECT_NAME DESCRIPTION DOMAIN_ID DOMAIN_NAME DB_NAME DB_TYPE Type Number String String Number String String Number Description The ID number of the project. The project name. The project description. The domain ID number. The domain name. The database name. The database type number: MS Access (1), MS SQL (2), Oracle(3), and Sybase(4). The source project of the created project. The source domain of the created project. The physical directory of the project. The database administrator user name. The database administrator password. The database server name. The database connection string. For internal use. Indicates if the project is active (Y/N). Indicates if SEND ALL QUALIFIED is active (Y/N).
CREATE_FROM_PROJECT CREATE_FROM_DOMAIN PHYSICAL_DIRECTORY DB_USER DB_USER_PASS DBSERVER_NAME DB_CONNSTR_FORMAT DB_ENCRYPTED_CONNSTR PR_IS_ACTIVE SAQ_IS_ACTIVE
String String String String String String String String String String
50
Name PR_HAS_VCSDB
Type String
Description Indicates if the project includes version control: (Y)es, (N)o, (D)isabled. This field only appears if version control is available. The maximum number of concurrent connections. -1 indicates an unlimited of connections. The version of the project. Repository for VMWare integration.
USERS_QUOTA
Number
VERSION VM_REPOSITORY
String String
Deactivate Example
The following Visual Basic example deactivates the project: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sDomainName As String Dim sProjectName As String Dim sReply As String On Error GoTo err sDomainName = "MyNewDomain" sProjectName = "MyNewProject" sReply = m_SAClient.DeactivateProject _ (sDomainName, sProjectName) MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
51
DeactivateSendAllQualified
Deactivates the SEND ALL QUALIFIED option for a specific project.
Parameters
Name DomainName ProjectName Type String String Description The domain name. The project name.
Return Values
If the function is successful, an XML string with project properties is returned. The following is a general example of the XML string format:
52
53
The following table displays the property details of the XML example:
Name PROJECT_ID PROJECT_NAME DESCRIPTION DOMAIN_ID DOMAIN_NAME DB_NAME DB_TYPE Type Number String String Number String String Number Description The ID number of the project. The project name. The project description. The domain ID number. The domain name. The database name. The database type number: MS Access (1), MS SQL (2), Oracle(3), and Sybase(4). The source project of the created project. The source domain of the created project. The physical directory of the project. The database administrator user name. The database administrator password. The database server name. The database connection string. For internal use. Indicates if the project is active (Y/N). Indicates if SEND ALL QUALIFIED is active (Y/N).
CREATE_FROM_PROJECT CREATE_FROM_DOMAIN PHYSICAL_DIRECTORY DB_USER DB_USER_PASS DBSERVER_NAME DB_CONNSTR_FORMAT DB_ENCRYPTED_CONNSTR PR_IS_ACTIVE SAQ_IS_ACTIVE
String String String String String String String String String String
54
Name PR_HAS_VCSDB
Type String
Description Indicates if the project includes version control: (Y)es, (N)o, (D)isabled. This field only appears if version control is available. The maximum number of concurrent connections. -1 indicates an unlimited number of connections. The version of the project. Repository for VMWare integration.
USERS_QUOTA
Number
VERSION VM_REPOSITORY
String String
DeactivateSendAllQualified Example
The following Visual Basic example deactivates the SendAllQualified function: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sDomainName As String Dim sProjectName As String Dim sReply As String On Error GoTo err sDomainName = "MyDomain" sProjectName = "MyProject" sReply = m_SAClient.DeactivateSendAllQualified _ (sDomainName, sProjectName) MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
55
DeleteDomain
Deletes a domain.
Syntax
DeleteDomain ( BSTR DomainName )
Parameters
Name DomainName Type String Description The domain name.
Return Values
If the function is successful, 1 is returned.
56
DeleteDomain Example
The following Visual Basic example deletes an empty domain: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sDomainName As String Dim sReply As String On Error GoTo err sDomainName = "MyDomain" sReply = m_SAClient.DeleteDomain(sDomainName) MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
57
DeleteProject
Deletes a project.
Parameters
Name DomainName ProjectName AdminName AdminPassword Type String String String String Description The domain name. The project name. The database administrator user name. The database administrator password.
Return Values
If the function is successful, 1 is returned.
58
DeleteProject Example
The following Visual Basic example deletes a project: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sDomainName As String Dim sProjectName As String Dim sReply As String On Error GoTo err sDomainName = "MyDomain" sProjectName = "MyProject" sReply = m_SAClient.DeleteProject _ (sDomainName, sProjectName, "Admin", "Swordfish") MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
59
DeleteSiteSingleParam
Deletes a site configuration parameter.
Parameters
Name ParamName Type String Description The parameter name.
Return Values
If the function is successful, 1 is returned.
DeleteSiteSingleParam Example
The following Visual Basic example deletes a parameter from the site: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sReply As String On Error GoTo err sReply = m_SAClient.DeleteSiteSingleParam _ ("MaxReqsPerBranch") MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
60
DeleteUser
Deletes a user from the user list.
Syntax
DeleteUser ( BSTR UserName )
Parameters
Name UserName Type String Description The user name.
Return Value
If the function is successful, 1 is returned.
DeleteUser Example
The following Visual Basic example deletes a user: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sReply As String On Error GoTo err sReply = m_SAClient.DeleteUser("alex_td") If (sReply = "1") Then MsgBox "User Deleted" End If Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
61
DisableVersionControl
Disables project version control (if version control available).
Syntax
DisableVersionControl ( BSTR DomainName, BSTR ProjectName )
Parameters
Name DomainName ProjectName Type String String Description The domain name. The project name.
Return Values
If the function is successful, an XML string with project properties. The following is a general example of the XML string format:
62
63
The following table displays the property details of the XML example:
Name PROJECT_ID PROJECT_NAME DESCRIPTION DOMAIN_ID DOMAIN_NAME DB_NAME DB_TYPE Type Number String String Number String String Number Description The ID number of the project. The project name. The project description. The domain ID number. The domain name. The database name. The database type number: MS Access (1), MS SQL (2), Oracle(3), Sybase(4). The source project of the created project. The source domain of the created project. The physical directory of the project. The database administrator user name. The database administrator password. The database server name. The database connection string. For internal use. Indicates if the project is active (Y/N). Indicates if SEND ALL QUALIFIED is active (Y/N).
CREATE_FROM_PROJECT CREATE_FROM_DOMAIN PHYSICAL_DIRECTORY DB_USER DB_USER_PASS DBSERVER_NAME DB_CONNSTR_FORMAT DB_ENCRYPTED_CONNSTR PR_IS_ACTIVE SAQ_IS_ACTIVE
String String String String String String String String String String
64
Name PR_HAS_VCSDB
Type String
Description Indicates if the project includes version control: (Y)es, (N)o, (D)isabled. This field only appears if version control is available. The maximum number of concurrent connections. -1 indicates an unlimited number of connections. The version of the project. Repository for VMWare Integration.
USERS_QUOTA
Number
VERSION VM_REPOSITORY
String String
DisableVersionControl Example
The following Visual Basic example disables version control of a deactivated project: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sDomainName As String Dim sProjectName As String Dim sReply As String On Error GoTo err sDomainName = "MyDomain" sProjectName = "MyProject" sReply = m_SAClient.DisableVersionControl _ (sDomainName, sProjectName) MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
65
Disconnect
Disconnects a specific connection to the TestDirector server.
Syntax
Disconnect ( long ConnectionId )
Parameters
Name ConnectionId Type Number Description The connection ID to be disconnected.
Return Values
If the function is successful, 1 is returned.
Disconnect Example
The following example disconnects a specific connection to the TestDirector server: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sReply As String On Error GoTo err sReply = m_SAClient.Disconnect(12433736) MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
66
DisconnectDomain
Disconnects all connections to a domain.
Syntax
DisconnectDomain ( BSTR DomainName )
Parameters
Name DomainName Type String Description The domain name.
Return Values
If the function is successful, 1 is returned.
DisconnectDomain Example
The following Visual Basic example disconnects all domain connections: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sDomainName As String Dim sReply As String On Error GoTo err sDomainName = "MyDomain" sReply = m_SAClient.DisconnectDomain(sDomainName) MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
67
DisconnectAll
Disconnects all connections to the TestDirector server.
Syntax
DisconnectAll
Parameters
None
Return Values
If the function is successful, 1 is returned.
DisconnectAll Example
See the Base Example on page 21.
68
DisconnectProject
Disconnects all connections to a project.
Syntax
DisconnectProject ( BSTR DomainName, BSTR ProjectName )
Parameters
Name DomainName ProjectName Type String String Description The domain name. The project name.
Return Values
If the function is successful, 1 is returned.
69
DisconnectProject Example
The following Visual Basic example disconnects all project connections: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sDomainName As String Dim sProjectName As String Dim sReply As String On Error GoTo err sDomainName = "MyDomain" sProjectName = "MyProject" sReply = m_SAClient.DisconnectProject _ (sDomainName, sProjectName) MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
70
DisconnectUser
Disconnects all connections for a given user from the TestDirector server.
Syntax
DisconnectUser ( BSTR UserName )
Parameters
Name UserName Type String Description The user name.
Return Values
If the function is successful, 1 is returned.
DisconnectUser Example
The following Visual Basic example disconnects all user connections: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sReply As String On Error GoTo err sReply = m_SAClient.DisconnectUser("alex_td") MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
71
EnableVersionControl
Enables project version control.
Note: The source project must be deactivated before this function is called.
Syntax
EnableVersionControl ( BSTR DomainName, BSTR ProjectName )
Parameters
Name DomainName ProjectName Type String String Description The domain name. The project name.
Return Values
If the function is successful, an XML string with project properties is returned. The following is a general example of the XML string format:
72
73
The following table displays the property details of the XML example:
Name PROJECT_ID PROJECT_NAME DESCRIPTION DOMAIN_ID DOMAIN_NAME DB_NAME DB_TYPE Type Number String String Number String String Number Description The ID number of the project. The project name. The project description. The domain ID number. The domain name. The database name. The database type number: MS Access (1), MS SQL (2), Oracle(3), and Sybase(4). The source project of the created project. The source domain of the created project. The physical directory of the project. The database administrator user name. The database administrator password. The database server name. The database connection string. For internal use. Indicates if the project is active (Y/N). Indicates if SEND ALL QUALIFIED is active (Y/N).
CREATE_FROM_PROJECT CREATE_FROM_DOMAIN PHYSICAL_DIRECTORY DB_USER DB_USER_PASS DBSERVER_NAME DB_CONNSTR_FORMAT DB_ENCRYPTED_CONNSTR PR_IS_ACTIVE SAQ_IS_ACTIVE
String String String String String String String String String String
74
Name PR_HAS_VCSDB
Type String
Description Indicates if the project includes version control: (Y)es, (N)o, (D)isabled. This field only appears if version control is available. The maximum number of concurrent connections. -1 indicates an unlimited number of connections. The version of the project. Repository for VMWare integration.
USERS_QUOTA
Number
VERSION VM_REPOSITORY
String String
EnableVersionControl Example
The following Visual Basic example enables version control: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sDomainName As String Dim sProjectName As String Dim sReply As String On Error GoTo err sDomainName = "MyDomain" sProjectName = "MyProject" sReply = m_SAClient.EnableVersionControl _ (sDomainName, sProjectName) MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
75
GetAllDomainProjects
Gets the properties of all projects in a domain.
Syntax
GetAllDomainProjects ( BSTR DomainName )
Parameters
Name DomainName Type String Description The domain name.
Return Values
If the function is successful, an XML string with project properties is returned. The following is a general example of the XML format:
76
77
The following table displays the property details of the XML example:
Name PROJECT_ID PROJECT_NAME DESCRIPTION DOMAIN_ID DOMAIN_NAME DB_NAME DB_TYPE Type Number String String Number String String Number Description The ID number of the project. The project name. The project description. The domain ID number. The domain name. The database name. The database type number: MS Access (1), MS SQL (2), Orale(3), and Sybase(4). The source project of the created project. The source domain of the created project. The physical directory of the project. The database administrator user name. The database administrator password. The database server name. The database connection string. For internal use. Indicates if the project is active (Y/N). Indicates if SEND ALL QUALIFIED is active (Y/N).
CREATE_FROM_PROJECT CREATE_FROM_DOMAIN PHYSICAL_DIRECTORY DB_USER DB_USER_PASS DBSERVER_NAME DB_CONNSTR_FORMAT DB_ENCRYPTED_CONNSTR PR_IS_ACTIVE SAQ_IS_ACTIVE
String String String String String String String String String String
78
Name PR_HAS_VCSDB
Type String
Description Indicates if the project includes version control: (Y)es, (N)o, (D)isabled. This field appears only if version control is available. The maximum number of concurrent connections. -1 indicates an unlimited number of connections. The version of the project. Repository for VMWare integration.
USERS_QUOTA
Number
VERSION VM_REPOSITORY
String String
GetAllDomainProjects Example
The following Visual Basic example gets the projects and their properties from the MyDomain domain: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sDomainName As String Dim sReply As String On Error GoTo err sDomainName = "MyDomain" sReply = m_SAClient.GetAllDomainProjects _ (sDomainName) MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
79
GetAllDomains
Gets all domains, projects, and their properties.
Syntax
GetAllDomains
Parameters
None
Return Values
If the function is successful, an XML string with project properties is returned. The following is a general example of the XML string format:
80
Example of XML String In the following example there are two domains. The first is the DEFAULT domain, which contains two projects: ff_copy and f_copy1. The second domain is Domain2, which does not contain a project.
<GetAllDomains> <TDXItem> <DOMAIN_ID>1</DOMAIN_ID> <DOMAIN_NAME>DEFAULT</DOMAIN_NAME> <PASSWORD /> <ADMIN_PASSWORD /> <PHYSICAL_DIRECTORY>C:\TD_Dir\Default\</PHYSICAL_DIRECTORY> <COMPANY_NAME /> <CONTACT_NAME /> <CONTACT_EMAIL /> <USERS_QUOTA>-1</USERS_QUOTA> <DEFECTS_QUOTA>0</DEFECTS_QUOTA> <PROJECTS_QUOTA>0</PROJECTS_QUOTA> <FILESYSTEM_QUOTA>0</FILESYSTEM_QUOTA> <PROJECTS_LIST> <TDXItem> <PROJECT_NAME>ff_copy</PROJECT_NAME> <PR_IS_ACTIVE>N</PR_IS_ACTIVE> <SAQ_IS_ACTIVE>N</SAQ_IS_ACTIVE> </TDXItem> <TDXItem> <PROJECT_NAME>f_copy1</PROJECT_NAME> <PR_IS_ACTIVE>N</PR_IS_ACTIVE> <SAQ_IS_ACTIVE>Y</SAQ_IS_ACTIVE> </TDXItem> </PROJECTS_LIST> <USERS_VERSION>0</USERS_VERSION> </TDXItem> <TDXItem> <DOMAIN_ID>13</DOMAIN_ID> <DOMAIN_NAME>Domian2</DOMAIN_NAME> <PASSWORD /> <ADMIN_PASSWORD /> <PHYSICAL_DIRECTORY>C:\TD_Dir\UUU\</PHYSICAL_DIRECTORY> <COMPANY_NAME />
81
TestDirector Site Administrator Client API Guide <CONTACT_NAME>tom</CONTACT_NAME> <CONTACT_EMAIL>tom@anywhere</CONTACT_EMAIL> <USERS_QUOTA>20</USERS_QUOTA> <DEFECTS_QUOTA>100000</DEFECTS_QUOTA> <PROJECTS_QUOTA>30</PROJECTS_QUOTA> <FILESYSTEM_QUOTA>51200</FILESYSTEM_QUOTA> <PROJECTS_LIST /> <USERS_VERSION>0</USERS_VERSION> </TDXItem> </GetAllDomains>
The following table displays the domain details of the XML example:
Name DOMAIN_ID DOMAIN_NAME PASSWORD ADMIN_PASSWORD PHYSICAL_DIRECTORY COMPANY_NAME CONTACT_NAME CONTACT_EMAIL USERS_QUOTA Type Number String String String String String String String Number Description The domain ID. The domain name. Not in use. Not in use. The physical directory of the domain. The company name. The contact name. The contact email. The maximum number of concurrent connections to all Projects in domain. -1 indicates an unlimited number of connections. Not in use. Not in use. Not in use. For internal use. The domain projects are in this list.
82
GetAllDomains Example
The following Visual Basic example gets all the domains and their properties: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sReply As String On Error GoTo err sReply = m_SAClient.GetAllDomains MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
83
GetAllUsers
Gets all users and their properties from the server.
Syntax
GetAllUsers
Parameters
None
Return Values
If the function is successful, an XML string with user properties is returned. The following is a general example of the XML string format:
84
85
The following table displays the property details of the XML example:
Name USER_ID USER_NAME ACC_IS_ACTIVE FULL_NAME DOMAIN_ID DOMAIN_NAME EMAIL USER_PASSWORD DESCRIPTION PHONE_NUMBER Type Number String String String String String String Description The new user ID number. The user name. For internal use. The full name of the user. For internal use. For internal use. The email of the user. The encryption of the user password. The description of the user. The phone number of the user.
GetAllUsers Example
The following Visual Basic example gets all the users and their properties: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sReply As String On Error GoTo err sReply = m_SAClient.GetAllUsers MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
86
GetConnections
Gets the properties of all connections to the TestDirector server.
Syntax
GetConnections
Parameters
None
Return Values
If the function is successful, an XML string with connection properties is returned. The following is a general example of the XML string format:
87
The following table displays the connection details of the XML example:
Name Domain Project UserName LoginTime HostName LastAction TdapiObjId Defects Type String String String String String String Number Number Description The domain name. The project name. The user name. The login time. The host name. The time of the last action. The connection ID. The fixed value of 0. Item appears only if the Defects module is licensed.
88
Name TestLab
Type Number
Description The fixed value of 0. Item appears only if the TestLab module is licensed. The fixed value of 0. Item appears only if the Requirements module is licensed.
Requirements
Number
GetConnections Example
The following Visual Basic example gets all connections to a TestDirector server: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sReply As String On Error GoTo err sReply = m_SAClient.GetConnections MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
89
GetConnectionsCount
Gets the connection count to the TestDirector server.
Syntax
GetConnectionsCount ( BSTR DomainName, BSTR ProjectName )
Parameters
Name DomainName ProjectName Type String String Description The domain name. The project name.
Return Values
If the function is successful, the number of connections is returned as a string.
90
GetConnectionsCount Example
The following Visual Basic example counts the connections to all projects in the MyDomain domain: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sDomainName As String Dim sProjectName As String Dim sReply As String Dim ReturnVal as Integer On Error GoTo err sDomainName = "MyDomain" sProjectName = "MyProject" returnVal = m_SAClient.GetConnectionsCount _ (sDomainName, sProjectName, sReply) MsgBox "Number of connections: " + sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
91
GetDcUsers
Gets user information from domains.
Syntax
GetDcUsers ( BSTR DomainName, BSTR UserName )
Parameters
Name DomainName UserName Type String String Description The domain name. Use only if you want a specific domain name. Reserved for future use.
Return Values
If the function is successful, an XML string, which holds domains and users is returned.
92
The following is a general example of the XML string format: Example of XML String
<GetDcUsers> <TDXItem> <NET_DOMAIN>Moon</NET_DOMAIN> <USERS> <TDXItem> <USER_NAME>steve</USER_NAME> <FULL_NAME>Steve Smith</FULL_NAME> <DESCRIPTION>Intern. Headquater</DESCRIPTION> </TDXItem> <TDXItem> <USER_NAME>mary</USER_NAME> <FULL_NAME>Mary Johnson</FULL_NAME> <DESCRIPTION>G&A USA</DESCRIPTION> </TDXItem> </USERS> </TDXItem> <TDXItem> <NET_DOMAIN>Moon1</NET_DOMAIN> <USERS>N</USERS> </TDXItem> <TDXItem> <NET_DOMAIN>Moon2</NET_DOMAIN> <USERS>N</USERS> </TDXItem> </GetDcUsers>
93
GetDcUsers Example
The following Visual Basic example gets users of all available domains. To get users from a specific domain, specify the domain name. 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sReply As String On Error GoTo err sReply = m_SAClient.GetDcUsers("", "") MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
94
GetDomain
Gets the properties and projects of a domain.
Syntax
GetDomain ( BSTR DomainName )
Parameters
Name DomainName Type String Description The domain name.
Return Values
If the function is successful, the XML string, which holds domain information is returned. The following is a general example of the XML string format:
95
The following table displays the domain details of the XML example:
Name DOMAIN_ID DOMAIN_NAME PASSWORD ADMIN_PASSWORD PHYSICAL_DIRECTORY COMPANY_NAME CONTACT_NAME CONTACT_EMAIL Type Number String String String String String String String Description The domain ID. The domain name. Not in use. Not in use. The physical directory of the domain. The company name. The contact name. The contact email.
96
Name USERS_QUOTA
Type Number
Description The maximum number of concurrent connections in all projects of domain. -1 indicates an unlimited number of connections. Not in use. Not in use. Not in use. For internal use. The projects list.
97
GetDomain Example
The following Visual Basic example gets the properties and projects of a domain: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sDomainName As String Dim sReply As String On Error GoTo err sDomainName = "MyDomain" sReply = m_SAClient.GetDomain(sDomainName) MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
98
GetProject
Gets the properties of a project.
Syntax
GetProject ( BSTR DomainName, BSTR ProjectName )
Parameters
Name DomainName ProjectName Type String String Description The domain name. The project name.
Return Values
If the function is successful, the XML string, which holds project information, is returned. The following is a general example of the XML string format:
99
100
The following table displays the property details of the XML example:
Name PROJECT_ID PROJECT_NAME DESCRIPTION DOMAIN_ID DOMAIN_NAME DB_NAME DB_TYPE Type Number String String Number String String Number Description The ID number of the project. The project name. The project description. The domain ID number. The domain name. The database name. The database type number: MS Access (1), MS SQL (2), Oracle(3), and Sybase(4). The source project of the created project. The source domain of the created project. The physical directory of the project. The database administrator user name. The database administrator password. The server name of the database The database connection string. For internal use. Indicates if the project is active (Y/N). Indicates if SEND ALL QUALIFIED is active (Y/N).
CREATE_FROM_PROJECT CREATE_FROM_DOMAIN PHYSICAL_DIRECTORY DB_USER DB_USER_PASS DBSERVER_NAME DB_CONNSTR_FORMAT DB_ENCRYPTED_CONNSTR PR_IS_ACTIVE SAQ_IS_ACTIVE
String String String String String String String String String String
101
Name PR_HAS_VCSDB
Type String
Description Indicates if the project includes version control: (Y)es, (N)o, (D)isabled. This field appears only if version control is available. The maximum number of concurrent connections. -1 indicates an unlimited number of connections. The version of the project. Repository for VMWare integration.
USERS_QUOTA
Number
VERSION VM_REPOSITORY
String String
GetProject Example
The following Visual Basic example gets the properties of a project: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sDomainName As String Dim sProjectName As String Dim sReply As String On Error GoTo err sDomainName = "MyDomain" sProjectName = "MyProject" sReply = m_SAClient.GetProject _ (sDomainName, sProjectName) MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
102
GetProjectExtendedData
Gets the project extended data (all project properties and database information).
Syntax
GetProjectExtendedData ( BSTR DomainName, BSTR ProjectName, int GetSchema, int GetVersion )
Parameters
Name DomainName ProjectName GetSchema Type String String Number Description The domain name. The project name. If the schema (database tables) is returned you can use the following constants or their values: SA_FALSE (value: 0) SA_TRUE (value: 1) GetVersion Number If the project version and language is returned you can use the following constants or their values: SA_FALSE (value: 0) SA_TRUE (value: 1)
103
Return Values
If the function is successful, the XML string, which holds project properties, is returned. The extended data is optional and returns only if selected by the user. The following is a general example of the XML string format:
104
105
The following table displays the property details of the XML example:
Name PROJECT_ID PROJECT_NAME DESCRIPTION DOMAIN_ID DOMAIN_NAME DB_NAME DB_TYPE Type Number String String Number String String Number Description The ID number of the project. The project name. The project description. The domain ID number. The domain name. The database name. The database type number: MS Access (1), MS SQL (2), Oracle(3), and Sybase(4). The source project of the created project. The source domain of the created project. The physical directory of the project. The database administrator user name. The database administrator password. The database server name. The database connection string. For internal use. Indicates if the project is active (Y/N). Indicates if SEND ALL QUALIFIED is active (Y/N).
CREATE_FROM_PROJECT CREATE_FROM_DOMAIN PHYSICAL_DIRECTORY DB_USER DB_USER_PASS DBSERVER_NAME DB_CONNSTR_FORMAT DB_ENCRYPTED_CONNSTR PR_IS_ACTIVE SAQ_IS_ACTIVE
String String String String String String String String String String
106
Name PR_HAS_VCSDB
Type String
Description Indicates if the project includes version control: (Y)es, (N)o, (D)isabled. This field appears only if version control is available. The maximum number of concurrent connections. -1 indicates an unlimited number of connections. The version of the project. Repository for VMWare integration.
USERS_QUOTA
Number
VERSION VM_REPOSITORY
String String
107
GetProjectExtendedData Example
The following Visual Basic example gets the project properties, table schema, version of project version, and language: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sDomainName As String Dim sProjectName As String Dim sReply As String On Error GoTo err sDomainName = "MyDomain" sProjectName = "MyProject" sReply = m_SAClient.GetProjectExtendedData _ (sDomainName, sProjectName, SA_TRUE, SA_TRUE) MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
108
GetSiteAllParams
Gets the properties of all site configuration parameters.
Syntax
GetSiteAllParams
Parameters
None
Return Values
If the function is successful, the XML string, which holds the properties, is returned. The following is a general example of the XML string format:
109
The following table displays the property details of the XML example:
Name PARAM_NAME PARAM_VALUE PARAM_DESCRIPTION PARAM_IS_SYSTEM Type Number String String String Description The parameter name. The parameter value. The parameter description. For internal use.
110
GetSiteAllParams Example
The following Visual Basic example gets the properties of all the parameters: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sReply As String On Error GoTo err sReply = m_SAClient.GetSiteAllParams MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
111
GetSiteSingleParam
Gets the properties of one site configuration parameter.
Syntax
GetSiteSingleParam ( BSTR ParamName)
Parameters
Name ParamName Type String Description The parameter name.
Return Values
If the function is successful, the XML string, which holds the properties, is returned. The following is a general example of the XML string format:
112
The following table displays the property details of the XML example:
Name PARAM_NAME PARAM_VALUE PARAM_DESCRIPTION PARAM_IS_SYSTEM Type Number String String String Description The parameter name. The parameter value. The parameter description. For internal use.
GetSiteSingleParam Example
The following Visual Basic example gets the properties of the ACI_SERVER parameter: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sReply As String On Error GoTo err sReply = m_SAClient.GetSiteSingleParam _ ("ACISERVER") MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
113
GetUser
Gets the user properties.
Syntax
GetUser ( BSTR UserName )
Parameters
Name UserName Type String Description The user name.
Return Values
If the function is successful, the XML string, which holds the user properties, is returned. The following is a general example of the XML string format:
114
The following table displays the property details of the XML example:
Name USER_ID USER_NAME ACC_IS_ACTIVE FULL_NAME DOMAIN_ID DOMAIN_NAME EMAIL USER_PASSWORD DESCRIPTION PHONE_NUMBER Type Number String String String String String String Description The new user ID number. The user name. For internal use. The full name of the user. For internal use. For internal use. The email of the user. The encryption of the user password. The description of the user. The phone number of the user.
115
GetUser Example
The following Visual Basic example gets the properties of a user: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sReply As String On Error GoTo err sReply = m_SAClient.GetUser("alex_td") MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
116
MoveProjectToDomain
Moves a project to another domain.
Syntax
MoveProjectToDomain ( BSTR SourceDomain, BSTR ProjectName, BSTR DestinationDomain )
Parameters
Name DomainName ProjectName DestinationDomain Type String String String Description The domain name. The project name. The destination domain.
Return Values
If the function is successful, an XML string with project properties is returned. The following is a general example of the XML string format:
117
118
CREATE_FROM_PROJECT CREATE_FROM_DOMAIN PHYSICAL_DIRECTORY DB_USER DB_USER_PASS DBSERVER_NAME DB_CONNSTR_FORMAT DB_ENCRYPTED_CONNSTR PR_IS_ACTIVE SAQ_IS_ACTIVE
String String String String String String String String String String
119
Name PR_HAS_VCSDB
Type String
Description Indicates if the project includes version control: (Y)es, (N)o, (D)isabled. This field appears only if version control is available. The maximum number of concurrent connections. -1 indicates an unlimited number of connections. The version of the project. Repository for VMWare integration.
USERS_QUOTA
Number
VERSION VM_REPOSITORY
String String
120
MoveProjectToDomain Example
The following Visual Basic example moves a project from "MyDomain" to "MyNewDomain": 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sSourceDomainName As String Dim sDestinationDomainName As String Dim sProjectName As String Dim sReply As String On Error GoTo err sSourceDomainName = "MyDomain" sDestinationDomainName = "MyNewDomain" sProjectName = "MyProject" sReply = m_SAClient.MoveProjectToDomain _ (sSourceDomainName, sProjectName, _ sDestinationDomainName) MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
121
RemoveDBServer
Deletes a database server from the database server list.
Syntax
RemoveDBServer ( BSTR DBServerName, long DBType )
Parameters
Name DBServerName DBType Type String Number Description The database server name. Returns the type of database. Use the following constants or their values: SA_ACCESS_DB_TYPE (value: 1) SA_MSSQL_DB_TYPE (value: 2) SA_ORACLE_DB_TYPE (value: 3) SA_SYBASE_DB_TYPE (value: 4) Response String [retval] Returns a value.
Return Values
If the function is successful, an XML string with project properties is returned.
122
RemoveProject
Removes a project from a domain without deleting the project.
Syntax
RemoveProject ( BSTR DomainName, BSTR ProjectName )
Parameters
Name DomainName ProjectName Type String String Description The domain name. The project name.
Return Values
If the function is successful, 1 is returned.
123
RemoveProject Example
The following Visual Basic example removes a project from the domain: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sDomainName As String Dim sProjectName As String Dim sReply As String On Error GoTo err sDomainName = "MyDomain" sProjectName = "MyProject" sReply = m_SAClient.RemoveProject _ (sDomainName, sProjectName) MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
124
RestoreProject
Restores an existing project to a domain.
Syntax
RestoreProject ( BSTR DomainName, BSTR ProjectName, int DbType, BSTR PhysicalDirectory, BSTR DbName, BSTR DbServerName, BSTR SourceDomainName, BSTR SourceProjectName )
Parameters
Name DomainName ProjectName DbType Type String String Number Description The domain name. The project name. The type of database. Use the following constants or their values: SA_ACCESS_DB_TYPE (value: 1) SA_MSSQL_DB_TYPE (value: 2) SA_ORACLE_DB_TYPE (value: 3) SA_SYBASE_DB_TYPE (value: 4) PhysicalDirectory DbName DbServerName SourceDomainName SourceProjectName String String String String The physical location of the project. The database name. The database server name. The source domain name (for recording history only). The source project name (for recording history only).
String
125
Return Values
If the function is successful, an XML string with the restored project properties is returned. The following is a general example of the XML string format: Example of XML String
<Root> <PROJECT_ID>79</PROJECT_ID> <PROJECT_NAME>a3</PROJECT_NAME> <DESCRIPTION>Created 28 August, 2002 </DESCRIPTION> <DOMAIN_ID>1</DOMAIN_ID> <DOMAIN_NAME>DEFAULT</DOMAIN_NAME> <DB_NAME>default_a3_db</DB_NAME> <DB_TYPE>1</DB_TYPE> <CREATE_FROM_PROJECT>source proj</CREATE_FROM_PROJECT> <CREATE_FROM_DOMAIN>default</CREATE_FROM_DOMAIN> <PHYSICAL_DIRECTORY>C:\TD_Dir\Default\a3\</PHYSICAL_DIRECTORY> <DB_USER /> <DB_USER_PASS /> <DBSERVER_NAME>LOCAL</DBSERVER_NAME> <DB_CONNSTR_FORMAT>PROVIDER=Microsoft.Jet.OLEDB.4.0;USER ID=;PASSWORD=;DATA SOURCE=%MDB_FILENAME%</DB_CONNSTR_FORMAT> <DB_ENCRYPTED_CONNSTR>PROVIDER=Microsoft.Jet.OLEDB.4.0; USERID=;PASSWORD=; DATASOURCE=C:\TD_Dir\Default\a3\\TestDir.MDB </DB_ENCRYPTED_CONNSTR> <PR_IS_ACTIVE>Y</PR_IS_ACTIVE> <SAQ_IS_ACTIVE>N</SAQ_IS_ACTIVE> <PR_HAS_VCSDB>Y</PR_HAS_VCSDB> <USERS_QUOTA>-1</USERS_QUOTA> <VERSION>76</VERSION> <VM_REPOSITORY/> </Root>
126
CREATE_FROM_PROJECT CREATE_FROM_DOMAIN PHYSICAL_DIRECTORY DB_USER DB_USER_PASS DBSERVER_NAME DB_CONNSTR_FORMAT DB_ENCRYPTED_CONNSTR PR_IS_ACTIVE SAQ_IS_ACTIVE
String String String String String String String String String String
127
Name PR_HAS_VCSDB
Type String
Description Indicates if the project includes version control: (Y)es, (N)o, (D)isabled. This field appears only if version control is available. The maximum number of concurrent connections. -1 indicates an unlimited number of connections. The version of the project. Repository for VMWare integration.
USERS_QUOTA
Number
VERSION VM_REPOSITORY
String String
128
RestoreProject Example
The following Visual Basic example restores a project that was saved in the MyProject subdirectory: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sDomainName As String Dim sProjectName As String Dim sServerName As String Dim CreateOptions As Long Dim sReply As String On Error GoTo err sDomainName = "MyDomain" sProjectName = "MyProject" sServerName = "MyServerName" sReply = m_SAClient.RestoreProject( _ sDomainName, sProjectName, SA_ACCESS_DB_TYPE, _ "C://TD_Dir/MYDOMAIN/MyProject", sProjectName, _ sServerName, "MyOriginalDomain", "MyOriginalProject") MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
129
RunQuery
Runs the SQL statement on the project database and returns results.
Syntax
RunQuery ( BSTR DomainName, BSTR ProjectName, BSTR SqlQuery, long MaxRecords, long FromRecord )
Parameters
Name DomainName ProjectName SqlQuery MaxRecords FromRecord Type String String String Number Number Description The domain name. The project name. The SQL statement. The maximum number of records to return. The number of records returned.
Return Values
If the function is successful, an XML string, which hold selected records according to the SQL statement, is returned. ColumnLables show all columns, numbers, and names. DataRows show all the rows that return results. For each row that returns results, only the columns containing data are shown.
130
The following is a general example of the XML string format: Example of XML String
<RunQuery> <ColumnLables> <TDXItem> <_0>RQ_REQ_ID</_0> <_1>RQ_FATHER_ID</_1> <_2>RQ_ORDER_ID</_2> <_3>RQ_ISTEMPLATE</_3> <_4>RQ_REQ_COMMENT</_4> <_5>RQ_REQ_REVIEWED</_5> <_6>RQ_REQ_PATH</_6> <_7>RQ_REQ_STATUS</_7> <_8>RQ_REQ_PRIORITY</_8> <_9>RQ_REQ_TYPE</_9> <_10>RQ_REQ_PRODUCT</_10> <_11>RQ_REQ_NAME</_11> <_12>RQ_REQ_AUTHOR</_12> <_13>RQ_USER_01</_13> <_14>RQ_USER_02</_14> <_15>RQ_USER_03</_15> <_16>RQ_USER_04</_16> <_17>RQ_USER_05</_17> <_18>RQ_USER_06</_18> <_19>RQ_USER_07</_19> <_20>RQ_USER_08</_20> <_21>RQ_USER_09</_21> <_22>RQ_USER_10</_22> <_23>RQ_USER_11</_23> <_24>RQ_USER_12</_24> <_25>RQ_REQ_VER_STAMP</_25> <_26>RQ_ATTACHMENT</_26> <_27>RQ_REQ_DATE</_27> <_28>RQ_REQ_TIME</_28> <_29>RQ_NO_OF_SONS</_29> <_30>RQ_IS_FOLDER</_30> <_31>RQ_VTS</_31> <_32>RQ_USER_13</_32> <_33>RQ_USER_14</_33> <_34>RQ_USER_15</_34> <_35>RQ_USER_16</_35> <_36>RQ_USER_17</_36> <_37>RQ_USER_18</_37> <_38>RQ_USER_19</_38>
131
TestDirector Site Administrator Client API Guide <_39>RQ_USER_20</_39> <_40>RQ_USER_21</_40> <_41>RQ_USER_22</_41> <_42>RQ_USER_23</_42> <_43>RQ_USER_24</_43> </TDXItem> </ColumnLables> <Rows> <TDXItem> <_0>1</_0> <_1>-1</_1> <_2>1</_2> <_5>Not Reviewed</_5> <_6>AAA</_6> <_7>Not Covered</_7> <_8>3-High</_8> <_11>Requirement 1</_11> <_12>admin</_12> <_25>5</_25> <_27>8/26/2002</_27> <_28>09:32:27</_28> <_29>0</_29> <_30>Y</_30> <_31>2002-09-02 14:15:03</_31> </TDXItem>
132
Chapter 2 Alphabetical Reference <TDXItem> <_0>2</_0> <_1>-1</_1> <_2>2</_2> <_5>Not Reviewed</_5> <_6>AAB</_6> <_7>Not Covered</_7> <_11>Requirement 2</_11> <_12>admin</_12> <_25>3</_25> <_27>9/2/2002</_27> <_28>14:13:42</_28> <_29>0</_29> <_30>N</_30> <_31>2002-09-02 14:13:57</_31> </TDXItem> </Rows> </RunQuery>
The following table displays the column item properties (under ColumnLables):
Name _0 _1 ... _N Type String String String String Description The column 0 name in the SQL results. The column 1 name in the SQL results. The column ... name in the SQL results. The column N name in the SQL results.
133
The following table displays the row item properties (under Rows):
Name _0 Type String or Number. (The type varies according to the type of value returned.) String or Number. (The type varies according to the type of value returned.) String or Number. (The type varies according to the type of value returned.) String or Number. (The type varies according to the type of value returned.) Description The column 0 value in the current row of the SQL results. The column will not be displayed if the value returned is NULL. The column 1 value in current row of the SQL results. The column will not be displayed if the value returned is NULL. The column ... value in current row of the SQL results. The column will not be displayed if the value returned is NULL. The column N value in current row of the SQL results. The column will not be displayed if the value returned is NULL.
_1
...
_N
134
RunQuery Example
The following Visual Basic example runs an SQL statement showing the first 25 row results: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sDomainName As String Dim sProjectName As String Dim sSql As String Dim sReply As String On Error GoTo err sDomainName = "MyDomain" sProjectName = "MyProject" sSql = "SELECT * FROM REQ" sReply = m_SAClient.RunQuery _ (sDomainName, sProjectName, sSql, 25, 0) MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
135
SendAllQualifiedNow
Sends an email to all qualified personnel immediately.
Syntax
SendAllQualifiedNow ( BSTR DomainName, BSTR ProjectName )
Parameters
Name DomainName ProjectName Type String String Description The domain name. The project name.
Return Values
If the function is successful, 1 is returned.
136
SendAllQualifiedNow Example
The following Visual Basic example sends an email to all qualified personnel: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sDomainName As String Dim sProjectName As String Dim sReply As String On Error GoTo err sDomainName = "MyDomain" sProjectName = "MyProject" sReply = m_SAClient.SendAllQualifiedNow _ (sDomainName, sProjectName) MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
137
SetDomainProperty
Sets a domain property.
Syntax
SetDomainProperty ( BSTR DomainName, long PropertyNumber, BSTR PropertyValue )
Parameters
Name DomainName PropertyNumber Type String number Description The domain name. The property number you want to change. You can use the following constants or their values: SA_DOMAIN_PHYSICAL_DIRECTORY (value :3) SA_DOMAIN_COMPANY_NAME (value :4) SA_DOMAIN_CONTACT_NAME (value :5) SA_DOMAIN_CONTACT_EMAIL (value :6) SA_DOMAIN_USERS_QUOTA (value :7) For a complete list, see the
SA_DOMAIN_PROPERTY_OPTIONS
enum in the object browser in any project with a reference to SAClient 1.0 Type
Library
PropertyValue String The property value.
Return Values
If the function is successful, an XML string with domain information is returned.
138
The following is a general example of the XML string format: Example of XML String
<SetDomainProperty> <DOMAIN_ID>17</DOMAIN_ID> <DOMAIN_NAME>TEST</DOMAIN_NAME> <PASSWORD>455704</PASSWORD> <ADMIN_PASSWORD>455362</ADMIN_PASSWORD> <PHYSICAL_DIRECTORY>66666\</PHYSICAL_DIRECTORY> <COMPANY_NAME>Mercury</COMPANY_NAME> <CONTACT_NAME>Paul</CONTACT_NAME> <CONTACT_EMAIL>paul@anywhere.com</CONTACT_EMAIL> <USERS_QUOTA>-1</USERS_QUOTA> <DEFECTS_QUOTA>13</DEFECTS_QUOTA> <PROJECTS_QUOTA>14</PROJECTS_QUOTA> <FILESYSTEM_QUOTA>51201</FILESYSTEM_QUOTA> <PROJECTS_LIST> <TDXItem> <PROJECT_NAME>test_project</PROJECT_NAME> <PR_IS_ACTIVE>N</PR_IS_ACTIVE> <SAQ_IS_ACTIVE>N</SAQ_IS_ACTIVE> </TDXItem> </PROJECTS_LIST> <USERS_VERSION>0</USERS_VERSION> </SetDomainProperty>
139
The following table displays the domain details of the XML example:
Name DOMAIN_ID DOMAIN_NAME PASSWORD ADMIN_PASSWORD PHYSICAL_DIRECTORY COMPANY_NAME CONTACT_NAME CONTACT_EMAIL USERS_QUOTA Type Number String String String String String String String Number Description The domain ID. The domain name. Not in use. Not in use. The physical directory of the domain. The company name. The contact name. The contact email. The maximum number of concurrent connections in all projects of the domain. -1 indicates an unlimited number of connections. Not in use. Not in use. Not in use. For internal use. The domain projects are in this list.
140
The following table displays the domain properties of the displayed projects:
Name PROJECT_NAME PR_IS_ACTIVE SAQ_IS_ACTIVE Type String String String Description The project name. Indicates if the project is active (Y/N). Indicates if SEND ALL QUALIFIED is active (Y/N).
SetDomainProperty Example
The following Visual Basic example changes the contact name in the domain property: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sDomainName As String Dim sReply As String On Error GoTo err sDomainName = "MyDomain" sReply = m_SAClient.SetDomainProperty(sDomainName, _ SA_DOMAIN_CONTACT_NAME, "Alex") MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
141
SetProjectProperty
Sets the project property to a selected value.
Note: Some properties require the project to be deactivated before calling this function (see PropertyValue below).
Syntax
SetProjectProperty ( BSTR DomainName, BSTR ProjectName, long PropertyNumber, BSTR PropertyValue )
Parameters
Name DomainName ProjectName Type String String Description The domain name. The project name.
142
Name PropertyNumber
Type number
Description The property number you wish to change. You can use the following constants or their values: SA_PROJECT_DB_CONNECT_STRING (value: 1) SA_PROJECT_DB_USER_PASSWORD (value: 2) SA_PROJECT_ACTIVE (value: 3) SA_PROJECT_NAME (value: 4) SA_PROJECT_SEND_ALL_QUALIFIED (value: 5) SA_PROJECT_USER_QUOTA (value: 6) SA_PROJECT_DESCRIPTION (value: 7) SA_PROJECT_VM_REPOSITORY (value: 8)
PropertyValue
String
The property value. The project must be deactivated in order to change the following properties: SA_PROJECT_DB_CONNECT_STRING, SA_PROJECT_NAME. The following properties apply to Oracle databases only: SA_PROJECT_DB_USER_PASSWORD.
Return Values
If the function is successful, an XML string with project properties is returned. The following is a general example of the XML string format:
143
144
The following table displays the properties details of the XML example:
Name PROJECT_ID PROJECT_NAME DESCRIPTION DOMAIN_ID DOMAIN_NAME DB_NAME DB_TYPE Type Number String String Number String String Number Description The ID number of the project. The project name. The project description. The domain ID number. The domain name. The database name. The database type number: MS Access (1), MS SQL (2), Oracle(3), Sybase(4). The source project of the created project. The source domain of the created project. The physical directory of the project. The database administrator user name. The database administrator password. The database server name. The database connection string. For internal use. Indicates if the project is active (Y/N). Indicates if SEND ALL QUALIFIED is active (Y/N).
CREATE_FROM_PROJECT CREATE_FROM_DOMAIN PHYSICAL_DIRECTORY DB_USER DB_USER_PASS DBSERVER_NAME DB_CONNSTR_FORMAT DB_ENCRYPTED_CONNSTR PR_IS_ACTIVE SAQ_IS_ACTIVE
String String String String String String String String String String
145
Name PR_HAS_VCSDB
Type String
Description Indicates if the project includes version control: (Y)es, (N)o, (D)isabled. This field appears only if version control is available. The maximum number of concurrent connections. -1 indicates an unlimited number of connections. The version of the project. Repository for VMWare integration.
USERS_QUOTA
Number
VERSION VM_REPOSITORY
String String
146
SetProjectProperty Example
The following Visual Basic example sets the property for a project name. First the project is deactivated (see DeactivateProject), then renamed, and then reactivated: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sDomainName As String Dim sProjectName As String Dim sReply As String On Error GoTo err sDomainName = "MyDomain" sProjectName = "MyProject" sReply = m_SAClient.DeactivateProject _ (sDomainName, sProjectName) sReply = m_SAClient.SetProjectProperty _ (sDomainName, sProjectName, _ SA_PROJECT_NAME, "YourProject") MsgBox sReply sReply = m_SAClient.ActivateProject _ (sDomainName, "YourProject") Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
147
SetSiteSingleParam
Sets the properties of one site configuration parameter.
Syntax
SetSiteSingleParam ( BSTR ParamName, BSTR ParamValue, BSTR ParamDescription )
Parameters
Name ParamName ParamValue ParamDescription Type String String String Description The parameter name. The new parameter value. The new parameter description.
Return Values
If the function is successful, 1 is returned.
148
SetSiteSingleParam Example
The following Visual Basic example sets the properties of an existing parameter: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sReply As String On Error GoTo err sReply = m_SAClient.SetSiteSingleParam("MAIL_FORMAT", _ "HTML", "The mail format ") MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
149
SetUserProperty
Sets a specific user property.
Syntax
SetUserProperty ( BSTR UserName, long PropertyNumber, BSTR PropertyValue )
Parameters
Name UserName PropertyNumber Type String Number Description The user name. The property number you wish to change. You can use the following constants or their values: SA_USER_FULL_NAME (value: 3) SA_USER_EMAIL (value: 4) SA_USER_PHONE_NUMBER (value: 5) SA_USER_DESCRIPTION (value: 6) SA_USER_PASSWORD (value: 7) SA_USER_DOM_AUTH (value: 8) SA_USER_REPORT_ROLE (value: 9) PropertyValue String The property value. If you are setting the user password, it will automatically be encrypted and sent to the server. (When you get the password back from the server, in GetUser for example, you will see the encrypted value.)
150
Return Values
If the function is successful, an XML string with the user properties is returned. The following is a general example of the XML string format: Example of XML String
<GetUser> <USERS_VERSION>752</USERS_VERSION> <USER_ID>10</USER_ID> <USER_NAME>alex_td</USER_NAME> <ACC_IS_ACTIVE>Y</ACC_IS_ACTIVE> <FULL_NAME> Alex Dashevsky </FULL_NAME> <DOMAIN_ID>0</DOMAIN_ID> <DOMAIN_NAME>TEMPLATES</DOMAIN_NAME> <EMAIL>alex_td@tgg.com</EMAIL> <USER_PASSWORD>456469</USER_PASSWORD> <DESCRIPTION>TestDirector_Demo</DESCRIPTION> <PHONE_NUMBER>301-3432778</PHONE_NUMBER> </GetUser>
151
SetUserProperty Example
The following Visual Basic example sets the value of an existing users full name and password: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sReply As String On Error GoTo err sReply = m_SAClient.SetUserProperty("alex_td", _ SA_USER_FULL_NAME, "Alex Dashevsky") MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
152
TestConnection
Tests a projects current database connection.
Syntax
TestConnection ( BSTR DomainName, BSTR ProjectName, BSTR ConnectString )
Parameters
Name DomainName ProjectName ConnectString Type String String String Description The domain name. The project name. If a string is specified, it tests the database with the specified connection string. If the string is not specified (empty string), it tests the database with the current connection string.
Return Values
If the function is successful, 1 is returned.
153
TestConnection Example
The following Visual Basic example upgrades a project to the latest version. 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sDomainName As String Dim sProjectName As String Dim sReply As String On Error GoTo err sDomainName = "MyDomain" sProjectName = "MyProject" sReply = m_SAClient.TestConnection _ (sDomainName, sProjectName, "") MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
154
UpgradeProject
Upgrades an existing project to the latest version.
Syntax
UpgradeProject ( BSTR DomainName, BSTR ProjectName, long UpgradeOptions )
Parameters
Name DomainName ProjectName UpgradeOptions Type String String Number Description The domain name. The project name. Specifies flags that control project creation. Use the following constants or their values: SA_PROJECT_UPGRADE_NONE (value: 0) Force upgrade even if project of latest version SA_PROJECT_UPGRADE_FORCE (value: 1).
155
Return Values
If the function is successful, 1 is returned.
UpgradeProject Example
The following Visual Basic example tests a projects current connection string: 1 Follow the procedure in Base Example on page 21. 2 Add the following code:
Private Sub Command1_Click() Dim sDomainName As String Dim sProjectName As String Dim nUpgradeOptions As Long Dim sReply As String On Error GoTo err sDomainName = "MyDomain" sProjectName = "MyProject" nUpgradeOptions = SA_PROJECT_UPGRADE_FORCE sReply = m_SAClient.UpgradeProject _ (sDomainName, sProjectName, nUpgradeOptions) MsgBox sReply Exit Sub err: MsgBox "Program failed:" + err.Description End Sub
156
Index
A
ActivateProject function 10 ActivateSendAllQualified function 14 AddDBServer function 18 documentation set for TestDirector vi documentation updates viii Domains object CreateDomain function 5 DeleteDomain function 5 GetAllDomains function 5 GetDomain function 5 SetDomainProperty function 5
C
Connections object Disconnect function 6 DisconnectAll function 6 DisconnectDomain function 6 DisconnectProject function 6 DisconnectUser function 6 GetConnections function 6 GetConnectionsCount function 6 ContinueProject function 22 conventions. See typographical conventions CreateDomain function 26 CreateProject function 29 CreateProjectCopy function 35 CreateSiteSingleParam function 43 CreateUser function 45 customer support online vii
E
EnableVersionControl function 72
G
GetAllDomainProjects function 76 GetAllDomains function 80 GetAllUsers function 84 GetConnections function 87 GetConnectionsCount function 90 GetDcUsers function 92 GetDomain function 95 GetProject function 99 GetProjectExtendedData function 103 GetSiteAllParams function 109 GetSiteSingleParam function 112 GetUser function 114
D
DeactivateSendAllQualified function 52 DeleteDomain function 56 DeleteProject function 58 DeleteSiteSingleParam function 60 DeleteUser function 61 DisableVersionControl function 61 Disconnect function 66 DisconnectAll function 68 DisconnectDomain function 67 DisconnectProject function 69 DisconnectUser function 71
M
Mercury Interactive on the Web vii MoveProjectToDomain function 117
157
O
objects Connections 6 Domains 5 Projects 4 Site Configuration Parameters 7 Users 3 online resources vii
P
Projects object ActivateProject function 4 ActivateSendAllQualified function 4 ContinueProject function 4 CreateProject function 4 CreateProjectCopy function 4 DeactivateProject function 4 DeactivateSendAllQualified function 4 DeleteProject function 4 DisableVersionControl function 4 EnableVersionControl function 4 GetAllDomainProjects function 4 GetProject function 4 GetProjectExtendedData function 4 MoveProjectToDomain function 4 RemoveProject function 5 RestoreProject function 5 RunQuery function 5 SendAllQualifiedNow function 5 SetProjectProperty function 5 TestConnection function 5 UpgradeProject function 5
Site Administrator Client objects Connections 6 Domains 5 Projects 4 Site Configuration Parameters 7 Users 3 Site Configuration Parameters object CreateSiteSingleParam function 7 DeleteSiteSingleParam function 7 GetSiteAllParams function 7 GetSiteSingleParam function 7 SetSiteSingleParam function 7
T
TestConnection function 153 TestDirector documentation set vi TestDirector online resources vii typographical conventions in this guide ix
U
updates, documentation viii UpgradeProject function 155 Users object CreateUser function 3 DeleteUser function 3 GetAllUsers function 3 GetDcUsers function 3 GetUser function 3 SetUserProperty function 3
R
RemoveDBServer function 122 RestoreProject function 125 RunQuery function 130
S
SendAllQualifiedNow function 136 SetDomainProperty function 138 SetProjectProperty function 142
158