StoreFront Store Services API
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) |
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-->
Copied!
Failed!