Citrix Virtual Apps and Desktops REST APIs

How to trigger test on a site and get the test results

Use REST APIs to trigger test on a site and get the test results.

Follow the prerequisites and examples to get started with this API.

You can make API requests using the PowerShell code, C# code, Python, or any tool that supports invoking the REST API.

Prerequisites to trigger test on a site and get the test results

Trigger test on a site and get the test results using any REST API tool

Learn from the following example to trigger test on a site and get the test results using any REST API tool.

Request for triggering test

POST https://[DdcServerAddress]/cvad/manage/sites/{siteid}/$test HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
Authorization: CWSAuth bearer=<token-from-prerequisites>
Citrix-CustomerId: loy6oujtu6a4

<!--NeedCopy-->

Response for triggering test

HTTP/1.1 200 OK
citrix-transactionid: 68c3afb4-0b5d-4cb6-99c7-106d220b591e}
content-Length: 88
content-Type: application/json; charset=utf-8
date: "Tue, 28 Dec 2020 15:23:07 GMT"

{
  "Site": {
    "Id": "320e9cfc-5cf6-4799-ab12-875cabb7fb98",
    "Uid": 0,
    "Name": "cloudusersite"
  },
  "NumPassed": 13,
  "NumWarnings": 2,
  "NumFailures": 1
}
<!--NeedCopy-->

Request for getting test results

GET https://[DdcServerAddress]/cvad/manage/sites/{siteid}/testreport HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
Authorization: CWSAuth bearer=<token-from-prerequisites>
Citrix-CustomerId: loy6oujtu6a4

<!--NeedCopy-->

Response for getting test results

HTTP/1.1 200 OK
citrix-transactionid: ce0d3943-e294-4fc8-b2c6-85271d4a0c3b
content-Length: 11602
content-Type: application/json; charset=utf-8
date: "Tue, 28 Dec 2020 16:18:57 GMT"
Location: https://[DdcServerAddress]/cvad/manage/Jobs/81c05d9f...

{
    "TestType": "Site",
    "CreatedBy": "3cc212a0-b9a3-41e4-9f7f-9aed208e144a",
    "ReportTime": "12/28/2020 6:40:18 AM",
    "TestResults": [
        {
            "TestName": "Check Read Committed Snapshot is enabled.",
            "TestDescription": "Check if the Read Committed Snapshot database option is enabled.",
            "TestStartTime": "12/28/2020 6:26:51 AM",
            "TestEndTime": "12/28/2020 6:26:53 AM",
            "TestServiceTarget": "AD Identity",
            "TestComponentStatus": "Successful",
            "TestScope": "Site",
            "TestComponents": [
                {
                    "TestComponentTarget": "r22622-68-2.example.com",
                    "TestComponentStartTime": "12/28/2020 6:26:51 AM",
                    "TestComponentEndTime": "12/28/2020 6:26:53 AM",
                    "TestComponentStatus": "Successful",
                    "ResultDetails": []
                }
            ]
        },
        ...
        {
            "TestName": "Check HTTP/HTTPS namespace reservation.",
            "TestDescription": "Check that required URL endpoints have been reserved in the HTTP/HTTPS namespace.",
            "TestStartTime": "12/28/2020 6:27:12 AM",
            "TestEndTime": "12/28/2020 6:27:13 AM",
            "TestServiceTarget": "Orchestration",
            "TestComponentStatus": "Failed",
            "TestScope": "Controller",
            "TestComponents": [
                {
                    "TestComponentTarget": "r22622-68-2.example.com",
                    "TestComponentStartTime": "12/28/2020 6:27:12 AM",
                    "TestComponentEndTime": "12/28/2020 6:27:13 AM",
                    "TestComponentStatus": "Failed",
                    "ResultDetails": [
                        {
                            "ServiceSource": "Orchestration",
                            "Serverity": "Error",
                            "Explanation": "Required service endpoint http://+:443/Citrix/Orchestration/PowerShellSdk/v1 is not registered in the HTTP/HTTPS namespace.",
                            "Action": "Rerun Post Install Pre-Configuration (PIPC)."
                        },
                        {
                            "ServiceSource": "Orchestration",
                            "Serverity": "Error",
                            "Explanation": "Required service endpoint https://+:443/Citrix/Orchestration/IServiceControl/v1 is not registered in the HTTP/HTTPS namespace.",
                            "Action": "Rerun Post Install Pre-Configuration (PIPC)."
                        },
                        {
                            "ServiceSource": "Orchestration",
                            "Serverity": "Error",
                            "Explanation": "Required service endpoint https://+:443/Citrix/Orchestration/EnvTestApi/v1 is not registered in the HTTP/HTTPS namespace.",
                            "Action": "Rerun Post Install Pre-Configuration (PIPC)."
                        },
                        {
                            "ServiceSource": "Orchestration",
                            "Serverity": "Error",
                            "Explanation": "Required service endpoint https://+:19098/citrix/orchestration/api is not registered in the HTTP/HTTPS namespace.",
                            "Action": "Rerun Post Install Pre-Configuration (PIPC)."
                        }
                    ]
                }
            ]
        }
    ]
}
<!--NeedCopy-->

Trigger test on a site and get the test results using PowerShell

Learn from the following example to trigger test on a site and get the test results using any PowerShell code.

function RunSiteTests {
    param (
        [Parameter(Mandatory=$true)]
        [string] $customerid,
        [Parameter(Mandatory=$true)]
        [string] $sitenameorid,
        [Parameter(Mandatory=$true)]
        [string] $bearerToken
    )
    $requestUri = [string]::Format("https://[DdcServerAddress]/cvad/manage/sites/{0}/`$test", $sitenameorid)
    $headers = @{
        "Accept" = "application/json";
        "Authorization" = "CWSAuth Bearer=$bearerToken";
        "Citrix-CustomerId" = $customerid;
    }

    $response = Invoke-RestMethod -Uri $requestUri -Method POST -Headers $headers
    return $response
}

function GetSiteTestReport {
    param (
        [Parameter(Mandatory=$true)]
        [string] $customerid,
        [Parameter(Mandatory=$true)]
        [string] $sitenameorid,
        [Parameter(Mandatory=$true)]
        [string] $bearerToken
    )
    $requestUri = [string]::Format("https://[DdcServerAddress]/cvad/manage/sites/{0}/`$testreport", $sitenameorid)
    $headers = @{
        "Accept" = "application/json";
        "Authorization" = "CWSAuth Bearer=$bearerToken";
        "Citrix-CustomerId" = $customerid;
    }

    $response = Invoke-RestMethod -Uri $requestUri -Method GET -Headers $headers
    return $response
}

$customerid = "n2ypkklgy6cv"
$siteid = "12f7438-bf8e-42ba-b1b3-2eb75d098f57"
$bearerToken = "eyJ..."
$response = RunSiteTests $customerid $siteid $bearerToken 
$response = GetSiteTestReport $customerid $siteid $bearerToken 
<!--NeedCopy-->

Trigger test on a site and get the test results using C# code

Learn from the following example to trigger test on a site and get the test results using any C# code.

public static async Task<string> RunSiteTests(
    string customerid,
    string sitenameorid,
    string bearerToken)
{
    var requestUri = string.Format("https://[DdcServerAddress]/cvad/manage/sites/{0}/$test", sitenameorid);
    using (var client = new HttpClient())
    {
        client.DefaultRequestHeaders.Accept.ParseAdd("application/json");
        client.DefaultRequestHeaders.Add("Citrix-CustomerId", customerid);
        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("CWSAuth Bearer=" + bearerToken);

        var response = await client.PostAsync(requestUri null);

        if (response != null)
        {
            var content = await response.Content.ReadAsStringAsync();
            return content;
        }

        return null;
    }
}

public static async Task<string> GetSiteTestReport(
    string customerid,
    string sitenameorid,
    string bearerToken)
{
    var requestUri = string.Format("https://[DdcServerAddress]/cvad/manage/sites/{0}/testreport", sitenameorid);
    using (var client = new HttpClient())
    {
        client.DefaultRequestHeaders.Accept.ParseAdd("application/json");
        client.DefaultRequestHeaders.Add("Citrix-CustomerId", customerid);
        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("CWSAuth Bearer=" + bearerToken);

        var response = await client.GetAsync(requestUri);

        if (response != null)
        {
            var content = await response.Content.ReadAsStringAsync();
            return content;
        }

        return null;
    }
}
<!--NeedCopy-->

Trigger test on a site and get the test results using Python

Learn from the following example to trigger test on a site and get the test results using Python.

import requests 

def RunSiteTests(bearerToken, customerid, sitenameorid):
    request_uri = "https://[DdcServerAddress]/cvad/manage/sites/{0}/$test".format(sitenameorid)
    headers = {
                'Authorization': 'CWSAuth Bearer=%s' % bearerToken,
                'Citrix-CustomerId': customerid,
                'Content-Type': 'application/json',
                'Accept': 'application/json'
              }

    response = requests.post(request_uri, headers = headers)

    return response.json()

def GetSiteTestReport(bearerToken, customerid, sitenameorid):
    request_uri = "https://[DdcServerAddress]/cvad/manage/sites/{0}/testreport".format(sitenameorid)
    headers = {
                'Authorization': 'CWSAuth Bearer=%s' % bearerToken,
                'Citrix-CustomerId': customerid,
                'Content-Type': 'application/json',
                'Accept': 'application/json'
              }

    response = requests.get(request_uri, headers = headers)

    return response.json()
<!--NeedCopy-->
Resources
Citrix Virtual Apps and Desktops REST APIs OpenAPI Specification
Copy Download
How to trigger test on a site and get the test results