Activity Manager
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
- Suspend/Hibernate 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 | Poweroff the requested machine |
/machinecontrol/shutdown | POST | Machine Id | Machine control operation result | Shutdown the requested machine |
/machinecontrol/suspend | POST | Machine Id | Machine control operation result | Suspend the requested machine |
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, PowerOff And Suspend 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.
The Suspend API uses a similar protocol to the shutdown API but will cause the machine to be placed in stand-by
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 | Shutdown the requested machine |
/machinecontrol/poweroff | POST | application/vnd.citrix.machinecontroloperationparams+xml | application/vnd.citrix.machinecontroloperation+xml | Poweroff the requested machine |
/machinecontrol/suspend | POST | application/vnd.citrix.machinecontroloperationparams+xml | application/vnd.citrix.machinecontroloperation+xml | Suspend the requested machine |
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
|XML Node / attribute|Type|Description| |—|—|—| |machinecontroloperation|Top level node| Root document node | |machinecontroloperation/status|string| "Success" or "Failure" at processing the request. | |machinecontroloperation/actionstatus|string| This is the status of the possibly ongoing operation. One of "Pending", "Started", "Completed", "Failed", "Canceled", "Deleted", "Lost" | |machinecontroloperation/isSuccess|string| If "true" the operation has completed and was successful. Otherwise empty or failure has occurred | |machinecontroloperation/continuationid|string| If set then delay and re-poll the API with this continuationToken set in the request | |machinecontroloperation/errorvalue|string| A description of the error | |machinecontroloperation/errorid|string| The error ID | |machinecontroloperation/retrydelayhint|int| This is obsolete. Use appropriate client logic for back off and retry polling to check the operation status |
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