Server API reference › API reference › API implementation and reference

Release: Australia · Updated: 2026-03-12 · Official documentation · View source

Cloud Runner TestUserApi – Scoped, Global

Manages test user jobs to be executed in a cloud runner for Automated Test Framework (ATF). This API is part of the CloudRunnerApi script include.

You can use this API for the following tasks:

Start the user test job.
Set the cloud user.
Check if the user specified is valid.
Check the progress of the user test job.
Cancel the test job.

In global scope, this API is executed within the sn_atf_tg namespace. You must have the ATF Test Generator and Cloud Runner (sn_atf_tg) plugin activated to use this API.

TestUserApi – cancelJob(String snboqId)

Sets the test user job status in the Browser Orchestration Queue [sn_atf_tg_sn_boq] table to complete.

Name	Type	Description
snboqId	String	Required. The sys_id of the BOQ record in the Browser Orchestration Queue [sn_atf_tg_sn_boq] table.

Type Description

null Null if successful, error message otherwise.

Error

If unsuccessful, possible error messages:- No sys\_id passed in – The JSON object provided doesn’t have a BOQ ID entry. Verify that the JSON object is structured as `{snboqId: ""}`. - Invalid sys\_id passed in – The ID provided must be for a BOQ record in the Browser Orchestration Queue \[sn\_atf\_tg\_sn\_boq\] table.

The following example shows how to start a test user for the admin user, get the progress, and cancel the test user. After confirming the locked out user as a valid cloud user, the code sets the cloud user as an ITIL administrator. In the global scope, use the sn_atf_tg namespace.

var snboqId = CloudRunnerAPI.TestUserAPI.startJob({username: "abel.tuter"});

gs.info(JSON.stringify(CloudRunnerAPI.TestUserAPI.progress({snboqId: snboqId})));

CloudRunnerAPI.TestUserAPI.cancelJob({snboqId: snboqId});

gs.info(CloudRunnerAPI.TestUserAPI.isValidCloudUser({username: <name of the user who has been locked out>}));

CloudRunnerAPI.TestUserAPI.selectCloudUser({username: "itil_admin"});

Output:

{progress: 64, state: running}
User is missing the following criteria: 
    User is locked out
False

TestUserApi – isValidCloudUser(String username)

Checks whether a provided user is a valid cloud user.

Name	Type	Description
username	Object	Required. User ID of a valid user listed in the Users [sys_user] table. This value is provided as a string in a JSON object. For example, `{username: "abel.tuter"}`.

Type

Description

Boolean

Flag that indicates whether the user provided is a valid cloud user. Valid values: - true: The user provided is a valid cloud user. - false: The user provided is invalid for one or more of the following reasons: - The user wasn’t found. - The user is inactive. - The user is locked out. - The user needs a password reset. - The user doesn’t have an admin role. - The user has read-only access. - The user has web services only access.

The following example shows how to start a test user for the admin user, get the progress, and cancel the test user. After confirming the locked out user as a valid cloud user, the code sets the cloud user as an ITIL administrator. In the global scope, use the sn_atf_tg namespace.

var snboqId = CloudRunnerAPI.TestUserAPI.startJob({username: "abel.tuter"});

gs.info(JSON.stringify(CloudRunnerAPI.TestUserAPI.progress({snboqId: snboqId})));

CloudRunnerAPI.TestUserAPI.cancelJob({snboqId: snboqId});

gs.info(CloudRunnerAPI.TestUserAPI.isValidCloudUser({username: <name of the user who has been locked out>}));

CloudRunnerAPI.TestUserAPI.selectCloudUser({username: "itil_admin"});

Output:

{progress: 64, state: running}
User is missing the following criteria: 
    User is locked out
False

TestUserApi – progress(String snboqId)

Provides the status of each user test for a provided Browser Orchestration Queue (BOQ) record.

Name	Type	Description
snboqId	String	Required. The sys_id of the BOQ record in the Browser Orchestration Queue [sn_atf_tg_sn_boq] table.

Type Description

Object

JSON object indicating test progress.

{
  "progress": Number,
  "state": "String"
}

Object.progress Indicates test progress percentage complete.Type: Number

Object.state State of the record.Possible values: - `Pending`: The requested test activity has been created and is waiting to be executed. - `Processing`: The instance is scanning for records to ensure that the execution trackers are marked for cloud runner before the request is sent to the cloud infrastructure. - `Browsers requested`: A request has been sent to the cloud infrastructure to start browsers for test generation or test running. - `Running`: Cloud infrastructure browsers find and execute pending tests. - `Completed`: The test task is complete. - `Failed state`: The test task failed. Type: String

Error

If unsuccessful, possible error messages:- No sys\_id passed in – The JSON object provided doesn’t have a BOQ ID entry. Verify that the JSON object is structured as `{snboqId: ""}`. - Invalid sys\_id passed in – The ID provided must be for a BOQ record in the Browser Orchestration Queue \[sn\_atf\_tg\_sn\_boq\] table.

The following example shows how to start a test user for the admin user, get the progress, and cancel the test user. After confirming the locked out user as a valid cloud user, the code sets the cloud user as an ITIL administrator. In the global scope, use the sn_atf_tg namespace.

var snboqId = CloudRunnerAPI.TestUserAPI.startJob({username: "abel.tuter"});

gs.info(JSON.stringify(CloudRunnerAPI.TestUserAPI.progress({snboqId: snboqId})));

CloudRunnerAPI.TestUserAPI.cancelJob({snboqId: snboqId});

gs.info(CloudRunnerAPI.TestUserAPI.isValidCloudUser({username: <name of the user who has been locked out>}));

CloudRunnerAPI.TestUserAPI.selectCloudUser({username: "itil_admin"});

Output:

{progress: 64, state: running}
User is missing the following criteria: 
    User is locked out
False

TestUserApi – selectCloudUser(String username)

Starts an end-to-end test user job on cloud runner. If the user is able to log in correctly with the admin role, then the cloud user property is set as this user for future test runs and test generations on the cloud runner infrastructure.

Name	Type	Description
username	Object	Required. User ID of a valid user listed in the Users [sys_user] table. This value is provided as a string in a JSON object. For example, `{username: "abel.tuter"}`.

Type

Description

Null

Null if successful. Error message otherwise.`Unable to set cloud user as cloud user not valid` – This error indicates that the user provided is invalid for one or more of the following reasons: - The user wasn’t found. - The user is inactive. - The user is locked out. - The user needs a password reset. - The user doesn’t have an admin role. - The user has read-only access. - The user has web services only access.

The following example shows how to start a test user for the admin user, get the progress, and cancel the test user. After confirming the locked out user as a valid cloud user, the code sets the cloud user as an ITIL administrator. In the global scope, use the sn_atf_tg namespace.

var snboqId = CloudRunnerAPI.TestUserAPI.startJob({username: "abel.tuter"});

gs.info(JSON.stringify(CloudRunnerAPI.TestUserAPI.progress({snboqId: snboqId})));

CloudRunnerAPI.TestUserAPI.cancelJob({snboqId: snboqId});

gs.info(CloudRunnerAPI.TestUserAPI.isValidCloudUser({username: <name of the user who has been locked out>}));

CloudRunnerAPI.TestUserAPI.selectCloudUser({username: "itil_admin"});

Output:

{progress: 64, state: running}
User is missing the following criteria: 
    User is locked out
False

TestUserApi – startJob(String username)

Starts an end to end test user job on cloud runner.

Name	Type	Description
username	String	Required. User name of sys_user to test the end to end infrastructure of cloud runner.

Type	Description
String	The sys_id of the BOQ record in the Browser Orchestration Queue [sn_atf_tg_sn_boq] table.

The following example shows how to start a test user for the admin user, get the progress, and cancel the test user. After confirming the locked out user as a valid cloud user, the code sets the cloud user as an ITIL administrator. In the global scope, use the sn_atf_tg namespace.

var snboqId = CloudRunnerAPI.TestUserAPI.startJob({username: "abel.tuter"});

gs.info(JSON.stringify(CloudRunnerAPI.TestUserAPI.progress({snboqId: snboqId})));

CloudRunnerAPI.TestUserAPI.cancelJob({snboqId: snboqId});

gs.info(CloudRunnerAPI.TestUserAPI.isValidCloudUser({username: <name of the user who has been locked out>}));

CloudRunnerAPI.TestUserAPI.selectCloudUser({username: "itil_admin"});

Output:

{progress: 64, state: running}
User is missing the following criteria: 
    User is locked out
False