RPC calls can be made using GET or POST requests. POST is suggested if you wish to keep the RPC authentication token out of the server's access logs. POST is required for the attachFile command because the form must be 'multipart/form-data' encoded.

External tools pass in an authentication token to verify that they can access the RPC interface. There is a single token for all tools. The tool also passes a username. Assuming the tool authenticated correctly, it performs its actions as the specified user. The user will need to have at least "run" access to the suite being operated on.

The server will return a response of type text/plain. The first line will be a numeric return code (currently 0 for success or 1 for an error) followed by zero or more message lines. In the event of an error, the message will detail the error.

assignSession

Assign tests in a test session.

The message line of the return value will be confirmation of the new assignment.

Example: Assign tests in session 123 to tester1 and tester2

rpc.mpl?rpctoken=token&username=lake&suite=Example&command=assignSession& \ sessNum=123&assignTo=tester1,tester2

assignSet

Assign tests in a test set.

The message line of the return value will be confirmation of the new assignment.

Example: Assign tests in set group1/set1 to tester1 and tester2

rpc.mpl?rpctoken=token&username=lake&suite=Example&command=assignSet& \ set=group1/set1&assignTo=tester1,tester2

attachFile

Attach a file to the note associated with a test case in a test session.

Example: Attach a file to the test case with UUID AC2CD7D2-955D-11D8-A214-90E5C9F5B464:

rpc.mpl?rpctoken=token&username=lake&suite=Example&command=attachFile& \ sess=00001&uuid=AC2CD7D2-955D-11D8-A214-90E5C9F5B464&fileName=log.txt

createGroup

Create a set group.

Example: Create set group called "Group_C" within an existing set group called "Group_A/Group_B":

rpc.mpl?rpctoken=token&username=lake&suite=Example&command=createGroup& \ name=Group_C&setGroup=Group_A/Group_B

createSet

Create a test set, optionally setting test case and requirement selectors, and default schedules and session variable settings.

The message line of the return value will be the number of tests selected in the new set.

Example: Create a set called "My_Set" in set group "Group_A/Group_B" containing high priority test cases:

rpc.mpl?rpctoken=token&username=lake&suite=Example&command=createSet& \ set=My_Set&setGroup=Group_A/Group_B&SCHEMA_priority=high

Note that when selecting tests by individual test case, you must set the 'testPickedBy' parameter to 'test'. If selecting test cases by folder, set the 'testPickedBy' parameter to 'folder'.

Similarly, if you are selecting test cases by related requirements and you want to reference individual requirements, you must set the 'reqPickedBy' parameter to 'requirement'. If selecting test cases by related requirements and referencing requirements by folder, set the 'reqPickedBy' parameter to 'folder'.

createSession

Create a test session. Optionally set schedules and session variables.

The message line of the return value will be the session number of the new session.

Example: Create a session from Group_A/Group_B/My_Set, scheduled to start on 1 February 2009, for Mac OS 9:

rpc.mpl?rpctoken=token&username=lake&suite=Example&command=createSession& \ set=Group_A/Group_B/My_Set&startdateplanned=1233446400&VAR_os=Mac_OS_9

deleteSession

Delete a test session.

Example: Remove session 10

rpc.mpl?rpctoken=token&username=lake&suite=Example&command=DeleteSession&sessNum=10

deleteSet

Delete a test set.

Example: Remove set 'theSet'

rpc.mpl?rpctoken=token&username=lake&suite=Example&command=DeleteSet&set=theSet

getReqUUID

Fetch the UUID associated with a requirement.

The message line of the return value will be the UUID for the named requiement, or empty of the requirement was not found.

Example: Get the UUID for a requirement using outline numbering with number '1.0.1'

rpc.mpl?rpctoken=token&username=lake&suite=Example&command=getReqUUID& \ name=1.0.1

getSessionDetails

Retrieves as many details as possible regarding a specified session. The return value is a text block.

Example: Get details regarding session number 0057

rpc.mpl?rpctoken=token&username=lake&suite=Example&command=getSessionDetails&sessNum=0057

getSessionList

Fetch the list of sessions in a test suite.

The message lines of the return value will be a test session number separated from the test session's 'name' with a semicolon.

The list may be filtered in various ways - see the specific special options list below.

getSessionResults

Fetch the results of one or more sessions in a test suite.

The message lines of the return value will be a test session number separated from the test session's 'name' with a semicolon, followed by the number of tests with each defined result for the test suite.

The list may be filtered in various ways - see the specific special options list below.

getSessionStatus

Fetch the status of a test session.

The message line of the return value will be a collection of semi-colon separated key / value pairs reporting the number of tests in the session, and the number of tests that have each result defined for the suite.

Example: Get the status for session 2

rpc.mpl?rpctoken=token&username=lake&suite=Example&command=geSessionStatus& \ sessnum=2

getSetList

Fetch the list of test sets in a suite.

The message lines of the return value will report each test set in the suite, one per line.

getSuiteList

Fetch a list of test suites accessible by a specific user.

The message lines of the return value will report each test suite in the system to which the user has at least 'run' level access.

getTestList

Fetch the list of Test Cases associated with a session or set.

The message lines of the return value will a test case ID or UUID, one per line, for each test case included in the requested test session or set.

Example: Get the list from set 'performance' in UUID form

rpc.mpl?rpctoken=token&username=lake&suite=Example&command=getTestList& \ set=performance&byUUID=1

getTestsSuiteByName

Return a list of all test cases in a Suite, represtend by their name. Each name will occupy a line, separated from the next by one newline (\n):

Example:

rpc.mpl?rpctoken=token&username=lake&suite=Example&command=getTestsSuiteByname

getTestsSuiteByUUID

Return a list of all test cases in a Suite, represtend by their UUID. Each UUID will occupy a line, separated from the next by one newline (\n):

Example:

rpc.mpl?rpctoken=token&username=lake&suite=Example&command=getTestsSuiteByUUID

getTestCaseDetails

Query any available information for a specified test case by way of either the UUID or the name.

Example: Get all available information for test case 'foo', in suite 'Example'

rpc.mpl?rpctoken=token&username=lake&suite=Example&command=getTestCaseDetails&uuid=foo

Example: Get all available information for named test case 'bar'

rpc.mpl?rpctoken=token&username=lake&suite=Example&command=getTestCaseDetails&name=bar.bts

getTestCaseResult

Retrieve the result of a test based on a specified session and test case. The return value is a text string representing the result.

Example: Look up the result of test (UUID) 'foo' in session 'bar'

rpc.mpl?rpctoken=token&username=lake&suite=Example&command=getTestCaseResult&uuid=foo&sessNum=bar

Example: The same result, but requested by name

rpc.mpl?rpctoken=token&username=lake&suite=Example&command=getTestCaseResult&name=foo&sessNum=bar

getTestResultData

Retrieve all of the data about one or more tests in a session.

Example: Look up the result data of test (UUID) 'foo' in session '123'

rpc.mpl?rpctoken=token&username=lake&suite=Example&command=getTestResultData&uuid=foo&sessNum=123

Example: The same information, but requested by name

rpc.mpl?rpctoken=token&username=lake&suite=Example&command=getTestResultData&name=foo&sessNum=123

getTestUUID

Fetch the UUID associated with a test case.

The message line of the return value will be the UUID for the named test case, or empty of the test case was not found.

Example: Get the UUID for a test case using 'plain' naming with a name of 'test/more/foo'

rpc.mpl?rpctoken=token&username=lake&suite=Example&command=getTestUUID& \ name=test/more/foo

lockSession

Lock a test session.

Example: Lock session 5

rpc.mpl?rpctoken=token&username=lake&suite=Example&command=lockSession&sessNum=5

lockSet

Lock a test set.

Example: Lock set named "theset"

rpc.mpl?rpctoken=token&username=lake&suite=Example&command=lockSet&set=theset

result

Set a result and/or notes and execution data for a test in a session.

If a result is specified, the entry will be classified as a "test execution"; if no result is specified, the entry will be classified as a "note".

Note that any existing values in execution data fields will be preserved when setting a result or note using this command, so you can use it to change the value of an execution data field without having to resubmit all the current execution data.

If a note or result is supplied, then the default time stamp for the result will be the time the result/note is submitted. You can override this via the execdata_when parameter - execdata_when takes seconds since the epoch.

If a note or result is supplied, then the default user to associate with it will be the value of the required username parameter. You can override this via the execdata_user parameter.

The message line of the return value will be an HTML fragment describing the note or result.

Example: Set the result of the first test case in the session to "retest":

rpc.mpl?rpctoken=token&username=lake&suite=Example&command=result& \ sess=00001&tid=0&result=retest

Example: Change the atm_prid field in the "ATM_Administration/Help_Screen" test case to "42":

rpc.mpl?rpctoken=token&username=lake&suite=Example&command=result& \ sess=00001&id=ATM_Administration.dir/Help_Screen.bts& \ EXECDATA_prid=42

Example: Add a note - "Fixed" - to the test case with UUID AC2CD7D2-955D-11D8-A214-90E5C9F5B464:

rpc.mpl?rpctoken=token&username=lake&suite=Example&command=result& \ sess=00001&uuid=AC2CD7D2-955D-11D8-A214-90E5C9F5B464&note=Fixed

It is also possible to add more than one result at a time. This is normally achieved through a web- or similar interface which save and communicate with rpc.mpl in a JSON format.

The general case looks as follows:

rpc.mpl?rpctoken=token&username=lake&suite=Example& \ sess=00001&command=result& \ result={"label":[ {"tid":"0","result":"foo"},{"tid":"1","result":"bar"}]}

If you wish to add two results:

rpc.mpl?rpctoken=token&username=lake&suite=Example& \ sess=00001&command=result& \ result={"tid_1":[ {"tid":"0","result":"foo"},{"tid":"1","result":"bar"}]}

The above code sample will add the result 'foo' to tid 0, and 'bar' to tid 1. Other fields can be set in the same way:

rpc.mpl?rpctoken=token&username=lake&suite=Example&command=result& \ sess=00001& \ result={ "label": [{"id":"ATM_Administration.dir/Help_Screen.bts", \ "EXECDATA_prid":"42", \ "EXECDATA_foo":"bar", \ "EXECDATA_assignedto":"user"} ] }

unlockSession

Unlock a test session.

Example: Unlock session 5

rpc.mpl?rpctoken=token&username=lake&suite=Example&command=unlockSession&sessNum=5

unlockSet

Unlock a test set.

Example: Unlock set named "theset"

rpc.mpl?rpctoken=token&username=lake&suite=Example&command=unlockSet&set=theset

The following arguments are common to all requests, and are mandatory.

rpctoken

The authentication token for RPC tools, as set in the System Configuration (described above).

username

The ApTest Manager username of the user in whose name the command will be executed. The user must have at least run access to the suite in question.

suite

The suite to operate on.

command

The command to execute. Each command has specific additional arguments. Available commands with additional arguments are listed below:

returnJSON

An optional boolean. If set to 1, each command will return there result with content type 'application/json' and return a json structure with properties 'result' indicating success or failure, and 'data' that contains either a scalar or a structure of command-specific information.

file (required)

The name of the file to attach. The contents of the file must also be included in a separate part using multipart/form-data encoding.

sess (required)

The session number to operate on.

tid or id or uuid (one required)

tid

The test case index in the session (zero-indexed - first test is 0, second is 1, etc.).

id

The ID of the test case (the path to the test case in the file system, e.g. "Example.dir/Test_case.bts").

uuid (recommended)

The UUID of the test case. This uniquely identifies the test case within the suite, and so is a reliable identifier which will not be affected by renaming the test case or reordering the session.

The UUID of a test case is one of the parameters that may be passed to a bug-tracking system in the bug-tracking system integration link.

note (optional)

A note to associate with the file - the link to the file will be placed at the end of the note text.

name (required)

The name of the set group to create.

desc (optional)

Set group description

setGroup (optional)

The name of the group to create the new group in. Defaults to the root set group.

set (required)

The name of the set to create

setGroup (optional)

The name of the set group to create the set in. Defaults to the root set group.

desc (optional)

The description to add to the set.

startdateplanned, enddateplanned (optional)

Default planned start and end dates for sessions created from the set.

Value is in "seconds since the epoch".

startdatewindow, enddatewindow (optional)

Default start and end date "on time" windows for sessions created from the set.

Valid values are 14400, 28800, 57600, 86400, 172800, 259200, and 604800 (4, 8, 16, and 24 hours, and 2, 3, and 7 days respectively).

SCHEMA_* (optional)

Test case field selectors. Values are formatted as they would be when submitted from the HTML form at run/defineSet.mpl

REQ_* (optional)

Requirement field selectors. Values are formatted as they would be when submitted from the HTML form at run/defineSet.mpl

VAR_* (optional)

Default session variables for sessions created from this set. Values are formatted as they would be when submitted from the HTML form at run/defineSet.mpl

set (optional)

The name of the set in which to create the session.

name (optional)

A name to give the session.

desc (optional)

A description for the session.

startdateplanned, enddateplanned (optional)

Planned start and end dates for the session.

Value is in "seconds since the epoch".

startdatewindow, enddatewindow (optional)

Start and end date "on time" windows for the session.

Valid values are 14400, 28800, 57600, 86400, 172800, 259200, and 604800 (4, 8, 16, and 24 hours, and 2, 3, and 7 days respectively).

testnames (optional)

A comma separated list of test case names to use when creating the session.

testUUIDs (optional)

A comman separated list of test case UUIDs to use when creating the sessiom.

VAR_* (optional)

Session variables for the session. Values are formatted as they would be when submitted from the HTML form at run/defineSet.mpl

name (required)

The name of the requirement. If the suite's requirements are in auto-outline mode, then this is the outline number. Otherwise it is the name of the requirement, including the path (e.g. top/sub/requirement_name).

date (optional)

A filter to indicate either that there is a date range ("range") or a number of seconds before now to filter on. Only sessions that have been modified within the number of seconds specified or within the range will be reported.

startDate (optional)

Used in conjunction with a date of "range". The number of seconds since the epoch that is the start of the range to check. If omitted, defaults to the start of the epoch.

endDate (optional)

Used in conjunction with a date of "range". The number of seconds since the epoch that is the end of the range to check. If omitted, defaults to now.

locked (optional)

A filter to only report sessions with a certain lock status. "locked" will report only locked sessions. "unlocked" will report only unlocked sessions.

run (optional)

A filter to select which sort of sessions to return: "run" - the session is complete, "needit" - incomplete or unstarted, "some" - already started and possibly complete, "partial" - partially run only, or "notrun" - never started.

sets (optional)

zero or more test set names - only sessions in these set(s) will be reported. Additional sets are specified with multiple sets arguments.

VAR_* (optional)

Any session variable can filtered on using the values defined for those session variables.

Example: Retrieve some test case and result fields for all tests in all sessions in a set named 'theset'

rpc.mpl?rpctoken=token&username=lake&suite=Example&command=getSessionResults \ &sets=theset&resultFields=when,results,assignedto&testFields=atm_reqlink&returnJSON=1

date (optional)

A filter to indicate either that there is a date range ("range") or a number of seconds before now to filter on. Only sessions that have been modified within the number of seconds specified or within the range will be reported.

startDate (optional)

Used in conjunction with a date of "range". The number of seconds since the epoch that is the start of the range to check. If omitted, defaults to the start of the epoch.

endDate (optional)

Used in conjunction with a date of "range". The number of seconds since the epoch that is the end of the range to check. If omitted, defaults to now.

locked (optional)

A filter to only report sessions with a certain lock status. "locked" will report only locked sessions. "unlocked" will report only unlocked sessions.

run (optional)

A filter to select which sort of sessions to return: "run" - the session is complete, "needit" - incomplete or unstarted, "some" - already started and possibly complete, "partial" - partially run only, or "notrun" - never started.

sets (optional)

zero or more test set names - only sessions in these set(s) will be reported. Additional sets are specified with multiple sets arguments.

VAR_* (optional)

Any session variable can filtered on using the values defined for those session variables.

includeVariables (optional)

If this is set to 1, then the session variable values for each session will be included in the output.

everyTest (optional)

If this is set to 1, then each test in each matching session will also include individual result and execution variable information for each test in addition to the aggregate result information. This parameter requires that returnJSON be set to 1. NOTE: all result fields from the test session will be included by default. This can be limited using the resultFields parameter.

resultFields (optional)

If this parameter is supplied, it is a comma-separated list of test result field names that can be included in the per-test-case output. This parameter requires that everyTest be set to 1 and that returnJSON is also set to 1.

includeTests (optional)

If this is set to 1, then each test in each matching session will also include the definition of the test case in a testFields object. This parameter requires that everyTest be set to 1 and that returnJSON is also set to 1. NOTE: all fields from the test case will be included by default. This can be limited using the testFields parameter.

testFields (optional)

If this parameter is supplied, it is a comma-separated list of test case field names that can be included in the per-test-case output. This parameter requires that everyTest be set to 1 and that returnJSON is also set to 1.

sessNum (required)

The number of the test session on which to report.

sessnum (deprecated)

The number of the test session on which to report. NOTE: This was deprecated because it is inconsistent with the argument in other similar requests.

children (optional)

Set to 1 if you want the sets in the group and all child groups.

group (optional)

Only sets within the specified set group will be reported. If no group option is specified, then all sets are reported.

name | uuid (required)

The name of the test case or its UUID.

field (optional)

A specific field from the test case to fetch.

sessnum | sessNum | set (required)

The session number or the complete set name (including folders) to list.

byUUID (optional)

A boolean. If true, return the list of test case UUIDs. If false, return the list of test case IDs. Defaults to false.

name (required)

The name of the test case. If the suite's test cases are in auto-outline mode, then this is the outline number. Otherwise it is the name of the test case, including the path (e.g. top/sub/test_name).

sess (required)

The session number to operate on.

name | uuid | testUUIDs | testnames (one required)

The name, uuid, comma-separated list of UUIDs or comma-separated list of testnames.

sess (required)

The session number to operate on.

tid or id or uuid (one required)

tid

The test case index in the session (zero-indexed - first test is 0, second is 1, etc.).

id

The ID of the test case (the path to the test case in the file system, e.g. "Example.dir/Test_case.bts").

uuid (recommended)

The UUID of the test case. This uniquely identifies the test case within the suite, and so is a reliable identifier which will not be affected by renaming the test case or reordering the session.

The UUID of a test case is one of the parameters that may be passed to a bug-tracking system in the bug-tracking system integration link.

note (optional)

A note to apply. Defaults to an empty string.

result (optional)

A result to set. If omitted, the change will be marked as a "note" rather than a test execution.

EXECDATA_* (optional)

Execution data field values, formatted as if submitted from a web form.