Triggering Scheduled Runs with APIs
Trigger your schedules from the comfort of your systems using curl commands. We hear your feedback and wish to make your automation process as swift and effective as possible.
For all commands, you will need your Sofy authentication key handy. Here's how to find it:
- x-sofy-auth-key: To retrieve your subscription key, navigate to Account > Account Settings > API Key.
Guide: Running Scheduled Runs Using cURL Commands
Follow these steps to fetch your data and trigger scheduled runs on Sofy devices using cURL commands. Ensure you replace placeholder values with actual data from your subscription.
1. Fetch the List of All Applications and Builds for Your Subscription
Use this command to retrieve details about all applications and their respective builds in your subscription:
curl --location 'https://public.sofy.ai/application-microservice/public/applications' \
--header 'x-sofy-auth-key: <your-auth-key>'
Example Response:
{
"data": [
{
"application_guid": "6448AE05-AE5E-48C0-A1B1-B1E7266CDA6C",
"platform_name": "ANDROID",
"application_friendly_name": null,
"application_builds": [
{
"app_hash": "4dde068421cce336876808763aa19239",
"build_id": "2.3.6(203060)",
"build_friendly_name": null,
"build_package_name": "io.bramerz.kfc"
},
{
"app_hash": "0c979ce52c65d5f0b26a01df1cdbd1d7",
"build_id": "2.3.2(203020)",
"build_friendly_name": null,
"build_package_name": "io.bramerz.kfc"
}
]
}
],
"message": "Fetched 2 record(s)"
}Possible Error Responses:
Error 401
{
"error": {
"message": "Invalid Auth Key.",
"details": "Provided Auth key is invalid, please ensure you're using the provided Auth key correctly.",
"timestamp": "2023-10-23T09:23:51.845Z"
}
}Error 500
{
"error": {
"message": "Internal Server Error.",
"details": "Validation failed for parameter 'subscriptionAuth'. Invalid GUID."
"timestamp": "2023-10-23T09:23:51.845Z"
}
}Error 400
{
"error": {
"message": "Missing required headers.",
"details": "Kindly provide valid authentication headers.",
"timestamp": "2023-10-23T09:23:51.845Z"
}
}2. Fetch the List of Available Devices by OS
Retrieve details of all devices in your subscription (including offline devices), such as OS version, manufacturer, name, and device ID. Replace ANDROID with the appropriate OS if needed:
curl --location 'https://public.sofy.ai/device-microservice/public/devices/ANDROID' \
--header 'x-sofy-auth-key: <your-auth-key>'
Example Response:
{
"data": [
{
"os_version": "T13",
"manufacturer": "Google",
"device_name": "Google Pixel 6",
"device_serial": "xxxxxxxxxxxxx",
"STATE": "ONLINE"
},
{
"os_version": "15",
"manufacturer": "Google",
"device_name": "Google Pixel 8",
"device_serial": "xxxxxxxxxxxxx",
"STATE": "ONLINE"
},
{
"os_version": "S12",
"manufacturer": "Google",
"device_name": "Google Pixel 3a XL",
"device_serial": "xxxxxxxxxxxxx",
"STATE": "ONLINE"
}
],
"message": "Devices fetched successfully"
}Possible Errors:
Error 401
{
"error": {
"message": "Invalid Auth Key.",
"details": "Provided Auth key is invalid, please ensure you're using the provided Auth key correctly.",
"timestamp": "2023-10-23T09:23:51.845Z"
}
}Error 500
{
"error": {
"message": "Internal Server Error.",
"details": "Validation failed for parameter 'subscriptionAuth'. Invalid GUID."
"timestamp": "2023-10-23T09:23:51.845Z"
}
}Error 400
{
"error": {
"message": "Missing required headers.",
"details": "Kindly provide valid authentication headers.",
"timestamp": "2023-10-23T09:23:51.845Z"
}
}Error 400
{
"error": {
"message": "The specified platform name does not exist. Please use IOS or ANDROID.",
"details": "Invalid platform name.",
"timestamp": "2023-10-23T09:23:51.845Z"
}
}Error 500
{
"message": "Requested route doesn't exist. please contact Sofy Middleware team for further details.",
"userMessage": "Internal server error."
}3. Retrieve All ScheduledRunGUIDs for Each App
To retrieve the ScheduledRunGUIDs for a specific build, replace appHash with the actual App Hash from Step 1:
curl --location 'https://ca-pub-gateway-stag-eastus2-001.happyriver-eac353b2.eastus2.azurecontainerapps.io/scheduler-microservice/public/via-app/8CBF99C0-BCF5-48E1-AF2B-7453FBC1A70F' \
--header 'x-sofy-auth-key: <your-auth-key>'
Example Response:
{
"data": [
{
"scheduled_guid": "5822858B-D15E-42F9-A555-032C8508765F",
"name": "scenario-63"
}
],
"message": "Fetched 1 record(s)."
}Possible Errors:
Error 401
{
"error": {
"message": "Invalid Auth Key.",
"details": "Provided Auth key is invalid, please ensure you're using the provided Auth key correctly.",
"timestamp": "2023-10-23T09:23:51.845Z"
}
}Error 500
{
"error": {
"message": "Internal Server Error.",
"details": "Validation failed for parameter 'subscriptionAuth'. Invalid GUID."
"timestamp": "2023-10-23T09:23:51.845Z"
}
}Error 400
{
"error": {
"message": "Missing required headers.",
"details": "Kindly provide valid authentication headers.",
"timestamp": "2023-10-23T09:23:51.845Z"
}
}4. Trigger a Scheduled Run
To execute a scheduled run with selected devices and build parameters, replace the following placeholders in the command:
:scheduledGUIDwith the ScheduledRunGUID from Step 3 or Step 4:appHashwith the Application Hash from Step 1:deviceSerialswith a comma-separated list of device IDs from Step 2
curl --location --request POST 'https://public.sofy.ai/scheduler-microservice/scheduled-runs/:scheduledGUID/execute?appHash=:appHash&deviceSerials=:deviceSerials' \
--header 'x-sofy-auth-key: <your-auth-key>'
Example Response:
{
"data": [
{
"testGroupsRunId": "xxxxxx"
}
],
"message": "Test runs are scheduled and in queue. Login to https://portal.sofy.ai for more info."
}General Error Response:
{
"error": {
"message": "Error message.",
"details": "Error details.",
"timestamp": "2023-10-23T09:23:51.845Z"
}
}Error Codes When Triggering Scheduled Runs
- Error Message: "The scheduledRunGuid is either invalid or not found."
- Status Code: 400
- Reason: Scheduled run not found.
- Resolution: Ensure that the provided scheduled run GUID is correct and that the scheduled run is active.
- Error Message: "Unable to extract application details for the scheduled automated test run. Either appHash is invalid or application does not exist."
- Status Code: 400
- Reason: Application details not found.
- Resolution: Ensure that the provided application hash is correct, and that the application is active.
- Error Message: "Release is either expired or does not exist."
- Status Code: 400
- Reason: Release not found.
- Resolution: Create a new release from the Sofy portal.
- Error Message: "The testRunGroupId is either invalid or not found."
- Status Code: 400
- Reason: Test run group not found.
- Resolution: Make sure that the test run group id is correct and belongs to the scheduled automated test run in context.
- Error Message: "Missing required headers." *
- Status Code: 500
- Reason: The required headers were not passed to the microservice from gateway.
- Resolution: Contact Sofy support.
Notes
- Ensure all placeholder values are replaced with actual data before executing commands.
- If you encounter any issues, check the API documentation or contact support for assistance.
- The list of devices retrieved includes both online and offline devices. Make sure the selected devices are online for successful execution.
By following these steps, you can efficiently manage and execute scheduled runs using cURL commands on Sofy.
