ApTest Manager documentation: RPC: rpc.mpl

rpc.mpl - an RPC interface for the ApTest Manager test execution area

http://example.com/atm/run/rpc.mpl?rpctoken=token&username=name& \
    suite=suiteName&command=commandName...

rpc.mpl provides a simple Remote Procedure Call interface to allow basic run operations to be performed over the internet by external tools.

Using your web browser, go to the Manage ApTest Manager screen, and click on Manage System Configuration. Enter a value for "What is the authentication token for users of the RPC interface?". You will not be able to use the RPC interface until a token is set.

Requests

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.

Login and authentication

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.

Return codes

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.

Available commands

createGroup: Create a set group.; Example: Create set group called "Group_C" within an existing set group called "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:
createSession: Create a test session, based on a test set. 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:
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.; 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":; Example: Change the atm_prid field in the "ATM_Administration/Help_Screen" test case to "42":; Example: Add a note - "Fixed" - to the test case with UUID AC2CD7D2-955D-11D8-A214-90E5C9F5B464:

Common arguments

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 are createGroup, createSet, createSession, and result.

Additional arguments: createGroup

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.

Additional arguments: createSet

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

Additional arguments: createSession

set (required): 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).
VAR_* (optional): Session variables for the session. Values are formatted as they would be when submitted from the HTML form at run/defineSet.mpl

Additional arguments: result

sess (required): The session number to operate on.
tid or id or uuid (one required)
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.

rpc.mpl

NAME

SYNOPSIS

DESCRIPTION

CONFIGURATION

USAGE