StoreFront Store Services API

Sessions service

August 16, 2023

Contributed by:

There are methods available through the NFuse protocol for tracking ICA sessions not connected to by the current client. These may be disconnected or connected to by other clients. Methods are provided to allow the client to:

Disconnect the currently connected session(s) with support for logon tickets.
LogOff the currently connected session(s) with support for logon tickets.
List any disconnected sessions.
List any sessions connected to other clients (although this disconnects those sessions as an unavoidable side-effect!).
Connect to a disconnected session.

As the current behavior is neither safe nor idempotent, all requests require the use of the POST verb.

Request

URL (indicative only)	Method	Request content-type	Response content-type	Description
/sessions/v1/available	POST	Session Parameters	Session State	Returns data on sessions which are available for connection from the client. Note that with the exception of XenDesktop 7 (and later), this has a side-effect of disconnecting sessions if ‘active’ sessions are queried.
/sessions/v1/disconnect/	POST	Session Parameters	Session Result	Disconnect the requested sessions
/sessions/v1/logoff/	POST	Session Parameters	Session Result	Logoff the requested sessions
/sessions/v1/{session-id}/launch/ica	POST	Launch Parameters	Launch Data	Attempt to launch the specified session using the ICA protocol.

Parameter	Description
{session-id}	The identifier of the session.

Note:

These requests require an Authorization token.

Requesting ‘active’ session types will actively disconnect those sessions from other clients as a side-effect while returning the session details. This is a limitation of the underlying XenApp API.

The Launch Parameters are described by the schema: /Schemas/LaunchParams.xsd and the response Launch Data is described by the schema: /Schemas/LaunchData.xsd.

The launch URL value is obtained by the client from the results of the available session requests.

The other URLs are obtained via the endpoints service (see Endpoints section below).

Request parameters

The following information is required by the requests to the session service. The data is sent as XML in the body of the POST described by the schema: /Schemas/SessionParameters.xsd.

Parameter	Required	Description
clientName	Yes	A string identifying the client. It is the client’s responsibility to use a value that will behave appropriately (see notes in Launch section)
deviceId	No	Identifies the device, if specified, it overrides the clientName in identifying the end-point.
includeActiveSessions	No	A boolean specifying whether to include active sessions. The value is true or false.
appSessionsOnly	No	A Boolean specifying whether to only return only application sessions. A value of true will list app sessions from any XD7 farm and pre- XD7 XenApp app hosting farm. Pre XD7 XenDesktop hosting farms will not be queried so as not to disconnect active desktops (a side effect of querying sessions). Where a XenApp hosts both apps and desktops the session queries will continue to disconnect a users active desktop. Farm exclusion based on version can be overridden to list all farm application sessions by setting the LegacyWorkspaceControl value to on (off is the default) in the Store `farm/>` element. The value is true or false, with the default being false.
tickets	No	This parameter is only used in LogOff and Disconnect session services and represents a list of tickets that will be invalidated by the server.

Note:

The presence of the session parameters shall be signaled by setting the content-type of the POST to be: application/vnd.citrix.sessionparams+xml

Response

Response code	Description
200	Success/Failure
401	Bad/Missing security token (see CitrixAuth Authentication Scheme document [3])
404	Session identified by {session-id} was not found
400	POSTed data missing or invalid
406	Unrecognized Accepts Header

Response Format	Request Accept /Response Content-Type Header
Session State	application/vnd.citrix.sessionstate+xml

Note:

The response to the request for session information returns session data, the schema for which can be found at: /Schemas/SessionState.xsd.

The response to the request to disconnect or logoff returns session result data, that describes the success or failure of the entire operation. This data is XML, described by the schema: /Schemas/SessionResult.xsd.

Endpoints

URL (indicative only)	Id	Capabilities
/sessions/v1/available	ListSessions	listSessions
/sessions/v1/disconnect	DisconnectSessions	disconnectSessions
/sessions/v1/logoff	LogOffSessions	logOffSessions

Example: Request session information

In this example all sessions are requested by not qualifying the server and client types.

Request

POST http://www.example.com/Store/sessions/v1/available HTTP/1.1 Host: www.example.com
Accept: application/vnd.citrix.sessionstate+xml
Content-Type: application/vnd.citrix.sessionparams+xml Content-Length: xxx
Authorization: CitrixAuth ...
<!--NeedCopy-->

<?xml version="1.0"?>
<sessionparams xmlns="http://citrix.com/delivery-services/1-0/sessionparams">
<clientName>xxxxxxxxx</clientName> <deviceId>xxxxxxxxx</deviceId> <includeActiveSessions>true</includeActiveSessions>
</sessionparams>
<!--NeedCopy-->

Response

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

<?xml version="1.0"?>
<sessionState xmlns="http://citrix.com/delivery-services/1-0/sessionstate"
             enumeration="full">
  <sessions>
    <session id="zyxw9876">
      <serverType>win32</serverType>
      <launchIca>
<url>http://www.example.com/Store/session/v1/zyxw9876/launch/ica</url> </launchIca>
<initialapp>MSPaint</initialapp> <initialappresourceaggregated>false</initialappresourceaggregated> <initialappresourceid>XA1.MSPaint</initialappresourceid> <publishername>Farm1</publishername>
    </session>
    <session id="3e4d5f6g">
      <serverType>win32</serverType>
      <launchIca>
<url>http://www.example.com/Store/session/v1/3e4d5f6g/launch/ica</url> </launchIca>
<initialapp>Notepad</initialapp> <initialappresourceaggregated>false</initialappresourceaggregated> <initialappresourceid>XA1.Notepad</initialappresourceid> <publishername>Farm1</publishername>
    </session>
  </sessions>
</sessiondata>
<!--NeedCopy-->

Example: Disconnect

Request

POST http://www.example.com/Store/sessions/v1/disconnect HTTP/1.1 Host: www.example.com
Accept: application/vnd.citrix.sessionresults+xml
Content-Type: application/vnd.citrix.sessionparams+xml Content-Length: xxx
Authorization: CitrixAuth ...
<!--NeedCopy-->

<?xml version="1.0"?>
<sessionparams xmlns="http://citrix.com/delivery-services/1-0/sessionparams">
  <clientName>xxxxxxxxx</clientName>
  <deviceId>xxxxxxxxx</deviceId>
  <tickets>
<ticket>85EB92973D2C3804F93A99AAEC232D</ticket> </tickets>
</sessionparams>
<!--NeedCopy-->

Response

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

<?xml version="1.0"?>
<sessionResults xmlns="http://citrix.com/delivery-services/1-0/sessionresult" status="success" />
<!--NeedCopy-->

Example: Log off

Request

POST http://www.example.com/Store/sessions/v1/logoff HTTP/1.1 Host: www.example.com
Accept: application/vnd.citrix.sessionresults+xml Content-Type: application/vnd.citrix.sessionparams+xml Content-Length: xxx
Authorization: CitrixAuth ...
<!--NeedCopy-->

<?xml version="1.0"?>
<sessionparams xmlns="http://citrix.com/delivery-services/1-0/sessionparams">
  <clientName>xxxxxxxxx</clientName>
  <deviceId>xxxxxxxxx</deviceId>
  <tickets>
    <ticket>85EB92973D2C3804F93A99AAEC232D</ticket>
    <ticket>85EB92973D2C3804F93A99AAEC232A</ticket>
  </tickets>
</sessionparams>
<!--NeedCopy-->

Response

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

<?xml version="1.0"?>
<sessionResults xmlns="http://citrix.com/delivery-services/1-0/sessionresult" status="success" />
<!--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

Sessions service

August 16, 2023

Contributed by:

August 16, 2023

Contributed by:

Sessions service

Request

Request parameters

Response

Endpoints

Example: Request session information

Request

Response

Example: Disconnect

Request

Response

Example: Log off

Request

Response

In this article