StoreFront Store Services API

Launch

August 16, 2023

Contributed by:

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)

Note:

These requests require an authorization 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. The setting is one of the following: `[high \\| medium \\| low \\| off]`
colourDepth	Optional	ICA and Rade	The color 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, one of the following: `[ 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, one of the following: `[ 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, one of the following: `[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. One of the following: `[true \\| false ]`
comPortMapping	Optional	ICA	If specified, determines the value of the COMAllowed setting in the WFClient section. One of the following: `[true \\| false ]`
clientPrinter	Optional	ICA	If specified, determines the values of the CPMAllowed and VSLAllowed settings in the WFClient section. One of the following: `[true \\| false ]`

Note:

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 host name

A random string

A digest of user name+domain (assumed by older versions of the XenApp XML Service and XenApp for Unix versions) 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 categorized 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 can 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 tickets 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 is 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
<!--NeedCopy-->

<?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>
<!--NeedCopy-->

Response

HTTP/1.1 200 OK
Cache-Control: public, no-store, max-age=0 Content-Type: application/vnd.citrix.launchdata+xml Content-Length: xxxx
<!--NeedCopy-->

<?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>
<!--NeedCopy-->

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....
<!--NeedCopy-->

<?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>
<!--NeedCopy-->

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.citrix.launchdata+xml Content-Length: xxx
Cache-Control: no-cache
<!--NeedCopy-->

<?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>
<!--NeedCopy-->

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....
<!--NeedCopy-->

<?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>
<!--NeedCopy-->

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.citrix.launchdata+xml Content-Length: xxx
Content-Language: en-gb
Cache-Control: no-cache
<!--NeedCopy-->

<?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>
<!--NeedCopy-->

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....
<!--NeedCopy-->

<?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>
<!--NeedCopy-->

Response

HTTP/1.1 200 OK
Cache-Control: public, no-store, max-age=0 Content-Type: application/vnd.citrix.launchdata+xml Content-Length: xxxx
<!--NeedCopy-->

<?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>
<!--NeedCopy-->

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Launch

August 16, 2023

Contributed by:

August 16, 2023

Contributed by:

Launch

Request

Launch parameters

Response

ICA launch result

Failed launch error codes

Retry reason codes

Remedy hint codes

Launch examples

Example: successful ICA launch

Request

Response

Example: failed Rade launch

Request

Response

Example: ICA launch with retry

Request

Response

Request

Response

In this article