Download full document:

Launch

Request

URL (indicative only) Method Description
/resources/v2/{id}/launch/ica POST Attempt to launch the specified resource using the ICA protocol
/resources/v2/{id}/launch/rade POST Attempt to launch the specified resource using the Rade protocol
/resources/v2/{id}/launch/{protocol}/{retrykey} POST Retry the attempt to launch the specified resource using the specified protocol
Parameter Description
{id} The identifier of the associated resource. This is unique to the instance of the service.
{protocol} The protocol to be used to launch the resource ('ica' or 'rade')
{retrykey} The retry key used to identify a launch request that is not ready (see below)

Notes:

  • These requests require an Authorisation token.
  • The URLs given above are for illustrative purposes, the actual URLs used by a client should be taken from the result of a previous request (e.g. /resources/v2/ or /resources/v2/{id} for all launch urls apart from the retry url which should be returned in a launch retry response).
  • The launch requests require the specification of launch parameters, included as Xml in the POST body, described below.
  • If subscriptions are enabled, then unsubscribed resources are prevented from launching.

Launch Parameters

The following information is required by the launch process, which is sent as POSTed Xml, described by the schema: /Schemas/LaunchParams.xsd

Parameter Required Launch Type Description
clientName Optional All protocols A string identifying the client (any characters except null (0) or newline characters. It is the client's responsibility to use a value that will behave appropriately (see notes below)
clientAddress Optional All protocols The IPv4 or IPv6 address of the client, as claimed by the client
deviceId Optional All protocols A string identifying the client device
audio Optional ica and rade The audio settings for the session, one of the following:
[high|medium|low|off]
colourDepth Optional ica and rade The colour depth for the session, one of the following:
[16 | 256 | high | truecolor ]
display Optional ica and rade The display type for the session, one of the following:
[seamless | percent | absolute | fullscreen]
displayPercent Optional ica and rade Only if display=percent
The percentage of the screen to be used for the session
[ 0 < percent ≤ 100]
displayAbsolute Optional ica and rade Only if display=absolute
The x and y extents of the window to be used for the session
[ 0 < x,y]
transparentKeyPassthrough Optional ica and rade Set the behavior of the windows keys etc., one of the following:
[local | remote | fullscreenonly ]
specialFolderRedirection Optional ica and rade Are the special folders directed, one of the following:
[true | false ]
clearTypeRemoting Optional ica and rade Are ClearType fonts remoted, one of the following:
[true | false ]
showDesktopViewer Optional ica Should the desktop viewer be used as the ICA client.
[true | false ]
launcher Optional ica Identifier for the launcher program.
Any string is allowed, not including null (0) or newline characters.
virtualComPort Optional ica If specified, determines the value of the VirtualCOMPortEmulation setting in the WFClient section.
[true | false ]
comPortMapping Optional ica If specified, determines the value of the COMAllowed setting in the WFClient section.
[true | false ]
clientPrinter Optional ica If specified, determines the values of the CPMAllowed and VSLAllowed settings in the WFClient section.
[true | false ]

Notes:

  • The presence of the launch parameters shall be signaled by setting the Content-Type of the POST to be: application/vnd.citrix.launchparams+xml
  • The use of clientAddress is required to take advantage of the Zone Preference feature of XenApp.
  • For the Workspace control feature, either clientName or deviceId is required.
  • The clientName either identifies the client machine or the end-user, depending on the semantics required by the client and is usually one of the following:
    • The client hostname
    • A random string
    • A digest of username+domain (assumed by older versions of the XenApp Xml Service and XenApp for Unix versions)

Note: If the resources are being accessed through Access Gateway, then the clientName is specified by the gateway.

Response

Response Code Description
200 Success/Retry required/failure
401 Bad/Missing security token
(see CitrixAuth Authentication Scheme document [3])
404 Resource identified by {id} was not available for launch. The reason is indicated by the X-Citrix-Error-Reason header value in the HTTP response:
ResourceNotFound: No resource was found for the requesting user for the specified id.
ResourceDisabled: The resource was found but was not enabled.
UnsupportedOperation: ICA launch was not supported for this resource.
SubscriptionStatusInvalid: Workflow was enabled for the resource but was not in the subscribed state.
SubscriptionStatusUnknown: Workflow was enabled for the resource, but the system was unable to determine the subscription state.
Response Format Request Accept /Response Content-Type Header
Xml application/vnd.citrix.launchdata+xml

The response returns data regarding the launch request that can be categorised as: Success, Retry required, or Failure. A retry is required, for example, when a desktop has to be started before a connection can be made to it. The data returned in the response is Xml described by the schema: /Schemas/LaunchData.xsd.

ICA Launch Result

Successful ICA launch results contain the following data:

ica : The ICA file content.

logonTicket : Specifies any logon ticket that might have been generated for the current launch. This value could be parsed from the ICA file content, but is supplied as a convenience for clients. Clients are expected to use this as a security measure to allow any outstanding logon tckets to be cleaned up if the client is closed while launches are outstanding with logon tickets that might not have been redeemed.

Failed Launch Error Codes

If the response represents a failed launch (launch type ‘error’), then the contained error id will be one of the following values:

Launch error Id Description
AppRemoved The resource to launch no longer exists, is no longer enabled or is no longer visible to the current user.
NoMoreActiveSessions The user is not allowed any more active sessions. Currently applies to XenDesktop only.
NotLicensed The server does not have the required license to perform the requested activity.
UnavailableDesktop No workstations are available to service this request. Currently applies to XenDesktop only.
CouldNotConnectToWorkstation The server refused a connection. Currently applies to XenDesktop only.
WorkstationInMaintenance The requested workstation is in maintenance mode and cannot be used. Currently applies to XenDesktop only.
ResourceError
GeneralAppLaunchError
General error that cannot be further specified.

Retry Reason Codes

If the response represents a delayed launch (launch type ‘’retry”), then the contained retryReason will be one of the following values:

Launch retry reason Description
rebooting The requested workstation is rebooting.
resuming The requested workstation is resuming.
unknown Retry reason not covered by the other values.

Remedy Hint Codes

If the response represents a delayed or failed launch, then the response may contain a remedyHint value with one of the following values:

remdyHint values Description
restart-desktop The problem may be resolved by restarting the desktop.

Launch Examples

Example: Successful Ica launch

Request

POST https://www.example.com/Citrix/Store/resources/v2/Q2l0cml4Lk1QUy5BcHAu/launch/ica HTTP/1.1 Accept: application/vnd.citrix.launchdata+xml
Authorization: CitrixAuth H4sIAAAAAAAEAO29B2AcS/T+x8z9Ajw4AAA==
Content-Type: application/vnd.citrix.launchparams+xml
Content-Length: xxx
<?xml version="1.0" encoding="utf-16"?>
<launchparams xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xmlns:xsd=http://www.w3.org/2001/XMLSchema
xmlns="http://citrix.com/delivery-services/1-0/launchparams"> <deviceId>clientname</deviceId>
  <clientName>clientname</clientName>
</launchparams>

Response

HTTP/1.1 200 OK
Cache-Control: public, no-store, max-age=0 Content-Type: application/vnd.citrix.launchdata+xml Content-Length: xxxx
<?xml version="1.0" encoding="utf-8"?>
<launch status="success" xmlns="http://citrix.com/delivery-services/1-0/launch"> <result type="ica">
  <ica>...[ICA File Content]...</ica>
<logonTicket>+dPeXidrRyAgdyqJzX...</logonTicket> </result>
</launch>

Example: Failed Rade launch

Request

POST https://www.example.com/Citrix/Store/resources/v2/Q2l0cml4Lk1QUy5BcHAu/launch/rade HTTP/1.1 Host: www.example.com
Accept: application/vnd.citrix.launchdata+xml
Accept-Language: en-gb
Content-Type: application/vnd.citrix.launchparams+xml Content-Length: xxx
Authorization: CitrixAuth H4sIA....
<?xml version="1.0"?>
<launchparams xmlns="http://citrix.com/delivery-services/1-0/launchparams">
<deviceId>clientname</deviceId> <clientName>clientname</clientName> <clientAddress>127.0.0.1</clientAddress>
</launchparams>

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.citrix.launchdata+xml Content-Length: xxx
Cache-Control: no-cache
<?xml version="1.0"?>
<launch xmlns="http://citrix.com/delivery-services/1-0/launch"
        status="failure">
  <result type="error">
<error>
<id>ResourceUnavailable</id>
<text>The resource is unavailable</text>
    </error>
  </result>
</launch>

Example: ICA launch with retry

Request

POST http://www.example.com/Citrix/Store/resources/v2/Q2l0cm...Q-/launch/ica HTTP/1.1 Host: www.example.com
Accept: application/vnd.citrix.launchdata+xml
Accept-Language: en-gb
Content-Type: application/vnd.citrix.launchparams+xml
Content-Length: xxx
Authorization: CitrixAuth H4sIA....
<?xml version="1.0"?>
<launchparams xmlns="http://citrix.com/delivery-services/1-0/launchparams">
<deviceId>clientname</deviceId> <clientName>clientname</clientName> <clientAddress>127.0.0.1</clientAddress>
</launchparams>

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.citrix.launchdata+xml Content-Length: xxx
Content-Language: en-gb
Cache-Control: no-cache
<?xml version="1.0"?>
<launch status="retry" xmlns="http://citrix.com/delivery-services/1-0/launch">
  <result type="retry">
    <retry>
<url>http://www.example.com/Citrix/Store/resources/v2/Q2l0cm...Q-/launch/ica/bbb56</url> <after>30</after>
<reason>unknown</reason>
    </retry>
  </result>
</launch>

Note: The URL used in this next request is the one returned in the previous response, which includes the retry key: ‘bbb567’:

Request

POST http://www.example.com/Citrix/Store/resources/v2/Q2l0cm...Q-/launch/ica/bbb567 HTTP/1.1 Host: www.example.com
Accept: application/vnd.citrix.launchdata+xml
Accept-Language: en-gb
Content-Type: application/vnd.citrix.launchparams+xml Content-Length: xxx
Authorization: CitrixAuth H4sIA....
<?xml version="1.0"?>
<launchparams xmlns="http://citrix.com/delivery-services/1-0/launchparams">
<deviceId>clientname</deviceId> <clientName>clientname</clientName> <clientAddress>127.0.0.1</clientAddress>
</launchparams>

Response

HTTP/1.1 200 OK
Cache-Control: public, no-store, max-age=0 Content-Type: application/vnd.citrix.launchdata+xml Content-Length: xxxx
<?xml version="1.0" encoding="utf-8"?>
<launch status="success" xmlns="http://citrix.com/delivery-services/1-0/launch">
<result type="ica">
<ica>...[ICA File Content]...</ica> <logonTicket>85EB92973D2C3804F93A99AAEC232D</logonTicket>
 </result>
</launch>