StoreFront Store Services API

Activity Manager

November 28, 2023

Contributed by:

The Activity Manager APIs added in the CR 2311 release are a set of APIs for managing HDX sessions. Using the APIs the client has the ability to:

List all user sessions
Logoff specific sessions
Disconnect specific sessions
Shutdown a specific machine running a user’s session
Power Off a specific machine running a user’s session

Note that the session listing API will list all of a user’s sessions including those which the calling client may not be capable of connecting to. This is unlike the /sessions/v1/available sessions service API which only returns sessions which the client is capable of connecting to.

The Activity Manager APIs do not offer a way of reconnecting to a session. Reconnecting to a session should be performed by using the Sessions Service APIs to list and then connect to the available sessions for the client. An alternative is to use the resources listing (/resources/v2) API to find the associated launch url for an application running within a session. The application IDs should be the same.

Endpoints Summary

URL	Method	Request content-type	Response content-type	Description
/usersessions/list	POST	application/vnd.citrix.usersessionsparams+xml	application/vnd.citrix.usersessionsresults+xml	Returns the session and machine IDs to use with the other APIs, plus additional session meta data
/usersessions/logoff	POST	application/vnd.citrix.usersessionactionresults+xml	application/vnd.citrix.usersessionactionrequest+xml	Logoff the requested sessions
/usersessions/disconnect	POST	application/vnd.citrix.usersessionactionresults+xml	application/vnd.citrix.usersessionactionrequest+xml	Disconnect the requested sessions
/machinecontrol/poweroff	POST	Machine Id	Machine control operation result	Power off the requested machines
/machinecontrol/shutdown	POST	Machine Id	Machine control operation result	Shut down the requested sessions

Note:

All requests require an Authorization token

The APIs all use XML as the content format for POST requests and all responses.

List Endpoint

The list endpoint can be queried to return session information for all sessions or for a specific set of sessions. The list endpoint needs to be called to get the session and machine IDs before the other APIs can be called.

Note that this API can return all users sessions if specific session IDs are omitted. By comparison the Sessions Service /sessions/v1/available API will only return sessions the client is capable of connecting to.

Request

URL	Method	Content-Type	Description
/usersessions/list	POST	application/json	Returns a list of all the user’s sessions metadata, the applications running in the sessions and the machines the sessions are running on.

XML Node / attribute	Type	Description
sessionIds	Array of strings with element name sessionId	Specific known session IDs to query for an update or leave empty to get all sessions
clientName	string	The name of the client
clientAddress	string	The address of the client

Example Request

POST http://www.example.com/Citrix/store/usersessions/list HTTP/1.1
Host: www.example.com
Accept: application/vnd.citrix.usersessionsresults+xml
Content-Type: application/vnd.citrix.usersessionsparams+xml
Authorization: CitrixAuth H4s...
Citrix-TransactionId: 694d2f87-b557-40dd-838f-f95eab67d23d
Content-Length: 327
<!--NeedCopy-->

<?xml version="1.0" encoding="utf-8"?>
<listusersessions xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://citrix.com/delivery-services/1-0/userlistsessions">
  <sessionIds />
  <clientName>WR_MO-969cDcqgF</clientName>
  <clientAddress>::1</clientAddress>
</listusersessions>
<!--NeedCopy-->

Response

Response code	Response Format	Content-Type header	Description
200	XML Sessions response	application/vnd.citrix.usersessionsresults+xml	Success
401			Bad/Missing security token (see CitrixAuth Authentication Scheme document [3] )

The response XML is part of the http://citrix.com/delivery-services/2-0/usersessions namespace.

XML Node / attribute	Type	Description
userSessions	Array of userSession	Root document node
userSessions: enumerationType	string	Failed - All farms failed to return resources Partial Some, but not all, farms returned resources. Full, All farms
userSessions/userSession	userSessions array element	Holds information about a user session
userSession: sessionId	string	Identifier for session used with othe APIs	returned resources
userSession: userSessionType	string	“Desktop”, “Application”
userSession: sessionStartTime	string	The session start time in ISO 8601 UTC format
userSession: clientName	string	The name of the client which launched the session if available. Same as the deviceId for Web Browser launched sessions
userSession: deviceId	string	The browser or client identifier which launched the session
userSession: deviceType	string	The client that launched the session’s type identifier. One of “Windows”, “Console”, “Text”, “MVGA”, “EPOC”, “OS/2”, “DOS32”, “Unix / Linux”, “Macintosh”, “iOS”, “Android”, “Blackberry”, “Windows RT”, “Windows Mobile”, “Blackberry Playbook”, “HTML5”, “Java”, “Windows CE”, “ThinOS”
userSession: clientType	string	The session’s connection type. One of “ica30”, “rdp”
userSession: connectionState	string	The connection status. One of “connected”, “disconnected”, “console”
userSession/machineData		Node holding the session host’s metadata
userSession/machineData:machineId	string	This is the ID used with the machine control APIs
userSession/machineData:machineName	string	The hostname of the machine
userSession/machineData:registrationState	string	The VDA registration status. “Registered”, “Unregistered”,”Initializing”, “AgentError”
userSession/machineData:powerState	string	The power state of the VDA. Typically “Unmanaged” or “On” unless transitioning from VM hybernation. Possible values are “Unmanaged”,”Unknown”,”Unavailable”,”Off”,”On”,”Suspended”,”TurningOn”,”TurningOff”,”Suspending”,”Resuming”,”NotSupported”,”VirtualMachineNotFound”
userSession/machineData:sessionSupport	string	Whether the VDA is a “SingleSession” VDI worker or a “MultiSession” capable RDS server
userSession/machineData:suspendSupported	string	Whether the machine supports hibernation. “true” or “false”
userSession/machineData:shutDownSupported	string	Whether the client may shut down the host machine. “true” or “false”
userSession/machineData:turnOffSupported	string	Whether the client may power off the host machine. “true” or “false”
userSession/applications	Array of application	Array root node containing the applications running in the session
application:id	string	The application resource ID
application:name	string	The name of the application
application:imageUrl	string	The URL for the application’s icon.

Example Response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store
Pragma: no-cache
Authorization: CitrixAuth H4sIAA.....
Content-Type: application/vnd.citrix.usersessionsresults+xml
Expires: -1
Server: Microsoft-IIS/10.0
Date: Thu, 23 Nov 2023 16:50:14 GMT
Content-Length: 1246
<!--NeedCopy-->

<?xml version="1.0" encoding="utf-8"?>
<userSessions enumerationType="Full" xmlns="http://citrix.com/delivery-services/2-0/usersessions">
  <userSession 
    sessionId="Q29udHJvbGxlci5TLTEtNS0yMS0zNzI5NzkyOTc4LTI2NDE5MDU2NjUtMjU3OTAwNzQ1OS0xMTA1LmRhOGFmNzQ1LTU3ODgtNGJlMy04MmJjLTJiMDAwMGFiYTg5OQ--"
    userSessionType="Application" 
    sessionStartTime="2023-11-23T16:45:00.343Z" 
    clientName="WR_MO-969cDcqgF" 
    deviceId="WR_MO-969cDcqgF" 
    deviceType="Windows" 
    clientType="ica30" 
    connectionState="connected">
    <machineData 
      machineId="Controller.S-1-5-21-3729792978-2641905665-2579007459-1105" 
      machineName="STOREFRONT-DEV\CVAD-01" 
      registrationState="Registered" 
      powerState="Unmanaged" 
      sessionSupport="MultiSession" 
      suspendSupported="false" 
      shutDownSupported="false" 
      turnOffSupported="false" />
    <applications>
      <application 
        id="Controller.Calculator" 
        name="Calculator" 
        imageUrl="http://www.example.com//resources/v2/TGx6YUNid1NWbXIwaVB3NjJrTzBxOFdhOEo4PQ--/image?resourceId=Q29udHJvbGxlci5DYWxjdWxhdG9y" />
      <application 
        id="Controller.WordPad" 
        name="WordPad" 
        imageUrl="http://www.example.com//resources/v2/K1lmSmpqL0U3ZDdYR09xZ0FWYnZ1emdaRXA0PQ--/image?resourceId=Q29udHJvbGxlci5Xb3JkUGFk" />
    </applications>
  </userSession>
</userSessions>
<!--NeedCopy-->

Sessions Logoff and Disconnect API

The /usersessions/logoff and /usersessions/disconnect APIs use a similar protocol and only differ by URL path.

The logoff API will end the users sessions and all applications in the session are terminated. The disconnect API closes the HDX connections to the given sessions but keeps the applications in them running.

URL	Method	Request content-type	Response content-type	Description
/usersessions/logoff	POST	application/vnd.citrix.usersessionactionrequest+xml	application/vnd.citrix.usersessionactionresults+xml	Logoff the requested sessions
/usersessions/disconnect	POST	application/vnd.citrix.usersessionactionrequest+xml	application/vnd.citrix.usersessionactionresults+xml	Disconnects the requested sessions

Request

XML Node / attribute	Type	Description
listusersessions	Top level node	Root document node
listusersessions/clientName	string	The name of the client
listusersessions/clientAddress	string	The IP address the client
listusersessions/sessionIds	Array of sessionId	The array of session ID strings to logoff
listusersessions/sessionIds/sessionId	string	A specific session ID to logoff

Example Request

POST http://www.example.com/Citrix/store/usersessions/logoff HTTP/1.1
Accept: application/vnd.citrix.usersessionactionresults+xml
Content-Type: application/vnd.citrix.usersessionactionrequest+xml
Authorization: CitrixAuth H4sIAA.....
Citrix-TransactionId: d515c582-1130-4267-bae8-2e5d65ea14d2
Host: www.example.com
Content-Length: 489
<!--NeedCopy-->

<?xml version="1.0" encoding="utf-8"?>
<listusersessions xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://citrix.com/delivery-services/1-0/userlistsessions">
  <sessionIds>
    <sessionId>Q29udHJvbGxlci5TLTEtNS0yMS0zNzI5NzkyOTc4LTI2NDE5MDU2NjUtMjU3OTAwNzQ1OS0xMTA1LmRhOGFmNzQ1LTU3ODgtNGJlMy04MmJjLTJiMDAwMGFiYTg5OQ--</sessionId>
  </sessionIds>
  <clientName>WR_MO-969cDcqgF</clientName>
  <clientAddress>::1</clientAddress>
</listusersessions>
<!--NeedCopy-->

Response

XML Node / attribute	Type	Description
responses	Top level node	Root document node
sessions	Array of sessions elements	The results of the operations to log off the specified sessions
sessions/sessions	Collection of elements describing the result
sessions/sessions/id	string	The session ID
sessions/sessions/issuccess	string	Whether the operation succeeded. “true” or “false”
sessions/sessions/failurereason	string	A nullable field. The reason for the failure if available.

Example Response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store
Pragma: no-cache
Content-Type: application/vnd.citrix.usersessionactionresults+xml
Expires: -1
Server: Microsoft-IIS/10.0
Date: Thu, 23 Nov 2023 17:05:36 GMT
Content-Length: 430
<!--NeedCopy-->

<?xml version="1.0" encoding="utf-8"?>
<responses xmlns="http://citrix.com/delivery-services/1-0/usersessioncontrolresponse">
  <sessions>
    <sessions>
      <id>Q29udHJvbGxlci5TLTEtNS0yMS0zNzI5NzkyOTc4LTI2NDE5MDU2NjUtMjU3OTAwNzQ1OS0xMTA1LmRhOGFmNzQ1LTU3ODgtNGJlMy04MmJjLTJiMDAwMGFiYTg5OQ--</id>
      <issuccess>true</issuccess>
      <failurereason d4p1:nil="true" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance" />
    </sessions>
  </sessions>
</responses>
<!--NeedCopy-->

Machine Shutdown and PowerOff APIs

The machine shutdown and power off APIs use a similar API protocol that only differs by endpoint URL path.

The shutdown API is called for the the single machine with a machineId returned from a prior usersessions/list request. Note that shutting down a machine may take a long time to finish as it is dependent on the underlying operating system completing the shutdown request.

The PowerOff API uses a similar protocol to the shutdown API but will cause the machine to be powered off without a graceful OS shutdown.

If the response is contains a continuationToken then the API should be polled with the token so the caller can tell when the operation has completed.

Request

URL	Method	Request content-type	Response content-type	Description
/machinecontrol/shutdown	POST	application/vnd.citrix.machinecontroloperationparams+xml	application/vnd.citrix.machinecontroloperation+xml	Shut down the requested sessions
/machinecontrol/poweroff	POST	application/vnd.citrix.machinecontroloperationparams+xml	application/vnd.citrix.machinecontroloperation+xml	Shut down the requested sessions

Request Parameters

XML Node / attribute	Type	Description
machinecontroloperationparams	Top level node	Root document node
machinecontroloperationparams/machineid	string	The machine identifier to perofrm the operation on
machinecontroloperationparams/continuationToken	string	The continuation token returned as the continuationid in a prior API response.

Note that machineid and continuationToken are mutually exclusive options.

Example Request

POST http://www.example.com/Citrix/store/machinecontrol/shutdown HTTP/1.1
Accept: application/vnd.citrix.machinecontroloperation+xml
Content-Type: application/vnd.citrix.machinecontroloperationparams+xml
Authorization: CitrixAuth H4sIAAAA.....
Citrix-TransactionId: d7f9bf67-1fdf-4e88-897d-3f30a259bd4b
Host: www.example.com
Content-Length: 489
<!--NeedCopy-->

Machine identifier request payload

<?xml version="1.0" encoding="utf-8"?>
<machinecontroloperationparams xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://citrix.com/delivery-services/1-0/machinecontroloperationparams">
  <machineid>Controller.S-1-5-21-3729792978-2641905665-2579007459-1105</machineid>
</machinecontroloperationparams>
<!--NeedCopy-->

Continutation request payload

<?xml version="1.0" encoding="utf-8"?>
<machinecontroloperationparams xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://citrix.com/delivery-services/1-0/machinecontroloperationparams">
  <continuationToken>c4068ad9-e9f2-48c3-9c1e-d6ae87006e7e.3621</continuationToken>
</machinecontroloperationparams>
<!--NeedCopy-->

Response

The API calling pattern is an initial request or continuation rqeuest which results in a response with a payload containing:

isSuccess is true indicating success
isSuccess is empty and the continuationid not empty indicating a slow operation that needs to be polled with the continuation request variant.
isSuccess is empty and errorid is non empty indicating a failure.

Response Parameters

Example Response

HTTP/1.1 200 OK Cache-Control: no-cache, no-store Pragma: no-cache Content-Type: application/vnd.citrix.machinecontroloperation+xml Expires: -1 Server: Microsoft-IIS/10.0 Date: Thu, 23 Nov 2023 17:06:57 GMT Content-Length: 371

Successful operation completed response

<?xml version="1.0" encoding="utf-8"?>
<machinecontroloperation xmlns="http://citrix.com/delivery-services/1-0/machinecontroloperation">
  <status>Success<status/>
  <actionstatus>Completed<actionstatus/>
  <isSuccess>true<isSuccess/>
  <continuationid><continuationid/>
  <errorvalue><errorvalue/>
  <retrydelayhint><retrydelayhint/>  
<machinecontroloperation/>
<!--NeedCopy-->

Operation in progress response

<?xml version="1.0" encoding="utf-8"?>
<machinecontroloperation xmlns="http://citrix.com/delivery-services/1-0/machinecontroloperation">
  <status>Success<status/>
  <actionstatus>Pending<actionstatus/>
  <isSuccess><isSuccess/>
  <continuationid>c4068ad9-e9f2-48c3-9c1e-d6ae87006e7e.3621<continuationid/>
  <errorvalue><errorvalue/>
  <retrydelayhint>30<retrydelayhint/>  
<machinecontroloperation/>
<!--NeedCopy-->

Operation failed response

<?xml version="1.0" encoding="utf-8"?>
<machinecontroloperation xmlns="http://citrix.com/delivery-services/1-0/machinecontroloperation">
  <status>Failure<status/>
  <actionstatus>Started<actionstatus/>
  <isSuccess><isSuccess/>
  <continuationid><continuationid/>
  <errorid>13<errorid/>
  <errorvalue><errorvalue/>
  <retrydelayhint><retrydelayhint/>  
<machinecontroloperation/>
<!--NeedCopy-->

An unknown machineid or continuationId was provided

HTTP/1.1 404 OK X-Citrix-Error-Reason: Machine not found with requested machineid or continuationId Cache-Control: no-cache, no-store Pragma: no-cache Expires: -1 Server: Microsoft-IIS/10.0 Date: Thu, 23 Nov 2023 17:06:57 GMT

An invalid format machineid or continuationId was supplied

HTTP/1.1 400 OK X-Citrix-Error-Reason: Invalid machineId or continuationId supplied Cache-Control: no-cache, no-store Pragma: no-cache Expires: -1 Server: Microsoft-IIS/10.0 Date: Thu, 23 Nov 2023 17:06:57 GMT

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

Activity Manager

November 28, 2023

Contributed by:

November 28, 2023

Contributed by:

Activity Manager

Endpoints Summary

List Endpoint

Request

Example Request

Response

Example Response

Sessions Logoff and Disconnect API

Request

Example Request

Response

Example Response

Machine Shutdown and PowerOff APIs

Request

Example Request

Response

Response Parameters

Example Response

In this article