Citrix ITSM Adapter service

Custom activities in Citrix ITSM connector

July 31, 2023

Contributed by:

As an IT administrator, you can use custom activities in the Citrix ITSM connector to create or customize your own workflows in ServiceNow.

This section describes input variables, output variables, and returned results of the custom activities.

The following activities are available from version 2110.1.0 of the Citrix ITSM connector plug-in.

Get Sessions

This activity retrieves sessions that match specific variable values. If no variables are specified, the activity enumerates all sessions.

Input variables

Specify the variable values to filter target sessions.

Variable	Type	Value	Description
UserName	String	Optional	Specify the user name that the sessions are assigned to.
CatalogName	String	Optional	Specify the catalog name that the sessions belong to.
DesktopGroupName	String	Optional	Specify the name of the desktop group that the sessions are associated with. Desktop groups are also known as delivery groups
MachineName	String	Optional	Specify the name of the machine where the sessions are started. Format: DOMAIN\machine.
DesktopKind	String	Optional	Specify the type of the desktop where the sessions are started. Valid values include Private and Shared.
SessionType	String	Optional	Specify the session type. Valid values include Application and Desktop.
SessionState	String	Optional	Specify the session state. Valid values include Other, PreparingNewSession, Connected, Active, Disconnected, Reconnecting, NonBrokeredSession, and Unknown.
Customer	String	Required	Specify the ID of the Citrix Cloud account that the sessions belong to.

Output variables

Variable	Type	Description
Result	String	Shows the activity result: true or false.
Sessions	String	Shows the detailed session information, as shown in the following JSON string.

Return results

[{
        "SessionKey":"string",
        "SessionType":"string",
        "ApplicationsInUse":["string"],
        "SessionState":"string",
        "LaunchedViaHostName":"string",
        "StartTime":"string",
        "LaunchedViaPublishedName":"string",
        "MachineName":"string",
        "OSType":"string",
        "SiteId":"string",
        "SiteName":"string"
    }]
<!--NeedCopy-->

Reset User Session

This activity resets user sessions that match specific variable values.

Input variables

Specify the variable values to filter target sessions.

Variable	Type	Value	Description
site_id	String	Optional	Specify the site ID where the session is started.
session_id	String	Required	Specify the session ID.
customer	String	Required	Specify the ID of the Citrix Cloud account that the session belongs to.

Output variables

Variable	Type	Description
result	String	Shows the activity result: success or failure.

Get Machines

This activity retrieves machines that match specific variable values. If no variables are specified, the activity enumerates all machines.

Input variables

Specify the input variables to filter target machines.

Variable	Type	Value	Description
CatalogName	String	Optional	Specify the name of the catalog that the machines belong to.
CatalogUid	String	Optional	Specify the UID of the catalog that the machines belong to.
DeliveryGroup	String	Optional	Specify the name of the delivery group that the machines are associated with.
RegistrationState	String	Optional	Specify the registration state of the machines. Valid values include Unregistered, Initializing, Registered, and AgSpecifyror.
PowerManagementSupport	Boolean	Optional	Specify whether the machines support power management or not.
Uuid	String	Optional	Specify the machine UUID.
AssignedUserName	String	Optional	Specify the user name that machines are assigned to.
Customer	String	Required	Specify the ID of the Citrix Cloud account that the machines belong to.

Output variables

Variable	Type	Description
Result	String	Shows the result of the activity: true or false.
Machines	String	Shows the detailed machine information as shown in the following JSON string.

Return results

[{
        "MachineName": "string",
        "uid": "string",
        "uuid": "string",
        "SID": "string",
        "osType": "string",
        "ZoneName": "string",
        "catalogName": "string",
        "deliveryGroup": "string",
        "registrationState": "string",
        "supportedPowerActions": ["string"],
        "powerState": "string"
    }]
<!--NeedCopy-->

Update Power Action

This activity applies power actions to machines.

Input variables

Use the input variables to specify the machine and power action.

Variable	Type	Value	Description
MachineName	String	Required	Specify the machine name in the format of DOMAIN\machine.
DNSName	String	Required	Specify the FQDN of the machine.
PowerAction	String	Required	Specify the power action. Valid values include Turn on, Turn off, Shut down, Reset, and Restart.
SiteId	String	Optional	Specify the site ID that the machine belongs to.
Customer	String	Required	Specify the ID of the Citrix Cloud account that the machine belongs to.

Output variables

Variable	Type	Description
Result	String	Shows the activity result: success or failure.
MachineInfo	String	Shows the detailed information about the machine as shown in the following JSON string.

Return results

{
    "siteId": {
        "machineName": {
            "machineName": "string",
            "action": "string",
            "actionStartTime": "string",
            "actionCompletionTime": "string",
            "state": "string"
        }
    }
}
<!--NeedCopy-->

Deprovision VDI

This activity removes a specific VDI desktop from your cloud deployment or retains the desktop but remove the current user’s access rights.

Input variables

Use the input variables to specify the machine and removal mode.

Variable	Type	Value	Description
MachineSID	String	Required	Specify the machine SID.
MachineName	String	Required	Specify the machine name.
DNSName	String	Required	Specify the FQDN of the machine.
RemoveUserAccessOnly	Boolean	Required	Specify the removal mode. True means to retain a specific VDI desktop but remove the current user’s access rights. False means to remove a specific VDI desktop from your cloud deployment.
Customer	String	Required	Specify the ID of the Citrix Cloud account that the machine belongs to.

Output variables

Variable	Type	Description
Result	String	Shows the activity result: success or failure.

Get Applications

This activity retrieves applications that match specific variable values. If no variables are specified, the activity enumerates all applications.

Input variables

Specify the variable values to filter target applications.

Variable	Type	Value	Description
Name	String	Optional	Specify the name of the application.
PublishedName	String	Optional	Specify the published name of the application.
AssociatedApplicationGroupName	String	Optional	Specify the application group name.
AssociatedDesktopGroupName	Boolean	Optional	Specify the name of the desktop group (also known as delivery group).
AssociatedUser	String	Optional	Specify the name of the user who is assigned the specific application.
Customer	String	Required	Specify the ID of the Citrix Cloud account that the application belongs to.

Output variables

Variable	Type	Description
Result	Boolean	Shows the activity result: true or false.
Applications	String	Shows the detailed application information as shown in the following JSON string.

Return results

[
    {
        "Name": "string",
        "PublishedName": "string",
        "DesktopGroup": [
            {
                "Name": "string",
                "ADGroups": ["string"],
                "DeliveryType": "string",
                "AllocationType": "string",
                "DesktopsUnregistered": "string",
                "DesktopsAvailable": "string",
                "DesktopsInUse": "string",
                "Sessions": "string",
                "TotalDesktops": "string",
                "SessionSupport": "string",
                "IsRemotePC": "string",
                "DesktopAssignments": [
                    {
                        "Name": "string",
                        "ADGroups": [
                            "string"
                        ]
                    }
                ]
            }
        ],
        "ApplicationGroup": [{
          "AGName":"string",
          "ADGroups":["string"],
          "DGGroups":["string"]
        }],
        "AssociatedADGroups": ["string"],
        "SiteId": "string",
        "SiteName": "string"
    }]
<!--NeedCopy-->

Assign User To Group

This activity assigns a user to a delivery group, an application group, or both.

Input variables

Use the input variables to specify the user and the groups you want to assign to them.

Variable	Type	Value	Description
users	String	Optional	Specify the user name.
delivery_group	String	Required	Specify the delivery group name that you want to assign to the users.
application_group	String	Required	Specify the application group name that you want to assign to the user.
site_id	String	Optional	Specify the site ID that the user belongs to.
customer	String	Required	Specify the ID of the Citrix Cloud account that the user belongs to.

Output variables

Variable	Type	Description
result	String	Shows the activity result: success or failure.

Create MCS Task

This activity creates the Add MCS-created machines task.

Input variables

Use the input variables to configure the task based on your needs.

Variable	Type	Value	Description
CatalogName	String	Required	Specify the name of the machine catalog that you want to add the machines to.
SiteName	String	Optional	Specify the name of the site that you want to add the machines to.
DesktopGroupName	String	Optional	Specify the name of the desktop group (also known as delivery group) you want to add the machines to.
Quantity	String	Optional	Specify the number of the machines that you want to create.
PowerOn	String	Optional	Specify whether to power on the machines after they are created. Valid values: True, False.
AdminAccount	String	Optional	Specify the name of the admin account that you want to create on the machines.
AdminPassword	String	Optional	Specify the password of the admin account that you want to create on the machines.
Customer	String	Required	Specify the ID of the Citrix Cloud account where the task is created.

Output variables

Variable	Type	Description
Result	String	Shows the activity result: True or False.
TaskUuid	String	Shows the Universally Unique Identifier (UUID) of the task.

Retrieve MCS Task Status

This activity retrieves the status of an MCS task.

Input variables

Use the input variables to specify the task ID.

Variable	Type	Value	Description
TaskUuid	String	Optional	Specify the UUID of an MCS task.
Customer	String	Required	Specify the ID of the Citrix Cloud account where the task is created.

Output variables

Variable	Type	Description
Result	String	Shows the status of the specified MCS task. Valid values: Success, Working, or Failed.

Send Message to Session

This activity sends a message to the specified sessions.

Input variables

Use the input variables to specify the sessions and message details.

Variable	Type	Value	Description
SessionUids	Array	Required	Specify the UIDs of the sessions that you want to send a message to.
MessageStyle	String	Required	Specify the style of the message box that you want to use. Valid values: Critical, Question, Exclamation, or Information.
Title	String	Required	Specify the text that you want to display in the title bar of the message box.
Text	String	Required	Specify the text that you want to display in the message box.
SiteId	String	Optional	Specify the site ID that the sessions belong to.
Customer	String	Required	Specify the Citrix Cloud account ID that the sessions belong to.

Output variables

Variable	Type	Description
Result	String	Shows the activity status: Success or Failure.

Update Maintenance Mode

This activity turns on or off maintenance mode for the specified machines.

Input variables

Use the input variables to specify the machines and maintenance mode.

Variable	Type	Value	Description
MachineUids	Array	Optional	Specify the UIDs of the machines where you want to turn on or off maintenance mode.
MachineNames	Array	Optional	Specify the computer names of the machines where you want to turn on or off maintenance mode.
DNSNames	Array	Optional	Specify the FQDN of the machines where you want to turn on or off maintenance mode.
MaintenanceMode	String	Required	Specify whether to turn on maintenance mode for the specified machines. Valid values: On or Off. Note: Machines in maintenance mode can neither receive new sessions nor be power-managed.
SiteId	String	Optional	Specify the ID of the site where the machines belong to.
Customer	String	Required	Specify the Citrix Cloud account ID that the machines belong to.

Output variables

Variable	Type	Description
Result	String	Shows the activity status: Success or Failure.

Run PowerShell scripts on a machine

This activity runs a PowerShell script on a specified machine.

Input variables

Use the input variables to specify the machine name, script content, and information to access the machine.

Variable	Type	Value	Description
MachineName	String	Required	Specify the name of the machine where you want to run the script.
UserName	String	Required	Specify the name of the user who is assigned to the machine.
Password	String	Required	Specify the password that the user uses to access the machine.
ScriptContent	String	Required	Specify the PowerShell script that you want to run on the specified machine.
ResourceLocationId	String	Optional	Specify the ID of the resource location to which the machine belongs.
Customer	String	Required	Specify the ID of the Citrix Cloud account that the machine belongs to.

Output variables

Variable	Type	Description
TaskId	String	Shows the ID of the task created to run the script.
Response	String	Shows the response from the PowerShell script.
Status	String	Shows the status of the task.
ResourceLocationId	String	Shows the ID of the resource location that the machine belongs to.

Get PowerShell Output

This activity retrieves the output of a PowerShell script based on the task ID.

Input variables

Use the input variables to specify the task ID.

Variable	Type	Value	Description
TaskId	String	Specify the ID of the task created to run the script.
Customer	String	Required	Specify the ID of the customer.

Output variables

Variable	Type	Description
Response	String	Shows the response of the PowerShell script.
Status	String	Shows the status of the task.

Get Failure Sessions

This activity retrieves the specified failed sessions.

Input variables

Use the input variables to specify the delivery group, user, and customer ID to retrieve the failed sessions.

Variable	Type	Value	Description
DeliveryGroup	String	Required	Specify the name of the delivery group that the failed sessions belong to.
User	String	Required	Specify the user that the sessions are assigned to.
Customer	String	Required	Specify the ID of the customer.

Output variables

Variable	Type	Description
Result	String	Shows the activity status: Success or Failure.
FailureSessions	String	Shows the detailed session information as shown in the following JSON string.

Return results

[{
 "Id":"long",
 "FailureReason":"string",
 "FailureDate":"DateTime",
 "SessionType":"string",
 "User":{
  "Id":"long",
  "Sid":"string",
  "Upn":"string",
  "UserName":"string",
  "FullName":"string",
  "Domain":"string",
  "CreatedDate":"DateTime",
  "ModifiedDate":"DateTime"
 },
 "Session":{
  "SessionKey":"string",
  "LogOnDuration":"int",
  "StartDate":"DateTime",
  "EndDate":"DateTime",
  "ExitCode":"int",
  "FailureDate":"DateTime",
  "ConnectionState":"string",
  "SessionIdleTime":"DateTime",
  "ConnectionStateChangeDate":"DateTime",
  "LifecycleState":"string",
  "CurrentConnectionId":"long",
  "UserId":"long",
  "MachineId":"string",
  "SessionType":"string",
  "IsAnonymous":"bool"
 },
 "Machine":{
  "Id":"string",
  "Sid":"string",
  "Name":"string",
  "DnsName":"string",
  "LifecycleState":"string",
  "IPAddress":"string",
  "HostedMachineId":"string",
  "HostingServerName":"string",
  "HostedMachineName":"string",
  "IsAssigned":"bool",
  "IsInMaintenanceMode":"bool",
  "IsPendingUpdate":"bool",
  "AgentVersion":"string",
  "AssociatedUserNames":"string",
  "CurrentRegistrationState":"string",
  "RegistrationStateChangeDate":"DateTime",
  "LastDeregisteredCode":"string",
  "LastDeregisteredDate":"DateTime",
  "CurrentPowerState":"string",
  "CurrentSessionCount":"int",
  "ControllerDnsName":"string",
  "FunctionalLevelCode":"int",
  "FailureDate":"DateTime",
  "WindowsConnectionSetting":"string",
  "IsPreparing":"bool",
  "FaultState":"int",
  "OSType":"string",
  "CatalogId":"string",
  "DesktopGroupId":"string",
  "HypervisorId":"string",
  "MachineRole":"string",
  "CreatedDate":"DateTime",
  "ModifiedDate":"DateTime"
 },
 "DeliveryGroup":{
  "Id":"string",
  "Name":"string",
  "IsRemotePC":"bool",
  "DesktopKind":"string",
  "LifecycleState":"string",
  "SessionSupport":"string",
  "DeliveryType":"string",
  "IsInMaintenanceMode":"bool",
  "CreatedDate":"DateTime",
  "ModifiedDate":"DateTime"
 }
}]
<!--NeedCopy-->

Run a Citrix Health Check test

This activity runs a citrix health check (CHC) test on a specified machine.

Input variables

Use the input variables to specify the machine UUID, site ID, and customer ID to run the test.

Variable	Type	Value	Description
MachineUuid	String	Required	Specify the name of the machine where you want to run the CHC test.
DNSName	String	Required	Specify the FQDN of the machine where you want to run the CHC test.
SiteId	String	Optional	Specify the site ID that the machine belongs to.
Customer	String	Required	Specify the ID of the customer.

Output variables

Variable	Type	Description
Result	String	Shows the activity status: Success or Failure.

Get CHC Report

This activity retrieves the latest CHC report of a specified machine.

Input variables

Use the input variables to specify the machine UUID, site ID, and customer ID to retrieve the report.

Variable	Type	Value	Description
MachineUuid	String	Required	Specify the UUID of the machine where you want to run the CHC test.
MachineName	String	Required	Specify the name of the machine where you want to run the CHC test.
DNSName	String	Required	Specify the FQDN of the machine where you want to run the CHC test.
SiteId	String	Optional	Specify the site ID that the machine belongs to.
Customer	String	Required	Specify the ID of the customer.

Output variables

Variable	Type	Description
Result	String	Shows the activity status: Success or Failure.
Report	String	Shows the detailed report information as shown in the following JSON string.

Return results

[{
 "CustomerId": "string",
 "Site": "string",
 "MachineId": "string",
 "MachineName": "string",
 "Status": "string",
 "StatusMessage": "DateTime",
 "UpdatedAt": "DateTime",
 "ReportName": "string",
 "ReportIssues": "string",
 "ReportLocation": "string"
}]
<!--NeedCopy-->

VDI Assignment

This activity assigns a VDA to a specified user.

Input variables

Use the input variables to specify the user name, machine name, and site ID to assign the VDA.

Variable	Type	Value	Description
UserName	String	Required	Specify the name of the user that the machine is assigned to.
MachineName	String	Required	Specify the name of the machine that you want to assign.
SiteId	String	Optional	Specify the site ID that the machine belongs to.
Customer	String	Required	Specify the ID of the customer.

Output variables

Variable	Type	Description
Result	String	Shows the activity status: Success or Failure.
Machine	String	Shows the detailed machine information as shown in the following JSON string.

Return results

[{
    "MachineName": "string",
    "uid": "string",
    "uuid": "string",
    "SID": "string",
    "osType": "string",
    "ZoneName": "string",
    "catalogName": "string",
    "deliveryGroup": "string",
    "registrationState": "string",
    "supportedPowerActions": ["string"],
    "powerState": "string"
}]
<!--NeedCopy-->

Get License Usage Data

This activity retrieves the license usage data of a specified customer.

Input variables

Use the input variables to specify the customer and the license mode.

Variable	Type	Value	Description
Customer	String	Required	Specify the ID of the customer.
LicenseMode	String	Required	Specify the license mode. Valid values include UserDevice, Concurrent, and Mixed.

Output variables

Variable	Type	Description
Result	String	Shows the activity status: Success or Failure.
LicenseUsageData	String	Shows the detailed license usage data as shown in the following JSON string.

Return results

{
    "customerId": "string",
    "dailyHistoricalActiveUse": [
        {
            "activeUseCount": int,
            "activeUsePercentage": "string",
            "deviceActiveUseCount": int,
            "deviceActiveUsePercentage": "string",
            "recordingTimeStamp": "string",
            "licenseType": "string",
            "totalLicenseCount": int,
            "totalUsage": int
        }
    ]
}
<!--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

Custom activities in Citrix ITSM connector

July 31, 2023

Contributed by:

July 31, 2023

Contributed by:

Get Sessions
Reset User Session
Get Machines
Update Power Action
Deprovision VDI
Get Applications
Assign User To Group
Create MCS Task
Retrieve MCS Task Status
Send Message to Session
Update Maintenance Mode
Run PowerShell scripts on a machine
Get PowerShell Output
Get Failure Sessions
Run a Citrix Health Check test
Get CHC Report
VDI Assignment
Get License Usage Data

Was this helpful

Custom activities in Citrix ITSM connector

Get Sessions

Input variables

Output variables

Return results

Reset User Session

Input variables

Output variables

Get Machines

Input variables

Output variables

Return results

Update Power Action

Input variables

Output variables

Return results

Deprovision VDI

Input variables

Output variables

Get Applications

Input variables

Output variables

Return results

Assign User To Group

Input variables

Output variables

Create MCS Task

Input variables

Output variables

Retrieve MCS Task Status

Input variables

Output variables

Send Message to Session

Input variables

Output variables

Update Maintenance Mode

Input variables

Output variables

Run PowerShell scripts on a machine

Input variables

Output variables

Get PowerShell Output

Input variables

Output variables

Get Failure Sessions

Input variables

Output variables

Return results

Run a Citrix Health Check test

Input variables

Output variables

Get CHC Report

Input variables

Output variables

Return results

VDI Assignment

Input variables

Output variables

Return results

Get License Usage Data

Input variables

Output variables

Return results

In this article