Use custom checks and alerts with Smart Check

This page has moved to You can now find all Smart Tools documentation at the Citrix Product Documentation site. Please update any page links to the new URL:



Smart Check includes a default set of checks you can use with your Site: Site Health Checks, Apps and Desktops Checks, Updates Checks, and LTSR Checks. If you currently use custom PowerShell scripts and tools for health checks, you can deploy them to your Site as a custom check, using a Smart Tools blueprint. You can also add custom alerts that are triggered with your custom checks. When triggered, these alerts are displayed on the Site's Health Alerts page, alongside Smart Check's existing alerts.

To use custom checks and alerts with Smart Check, you perform the following tasks:

  1. Register your custom alerts. To do this, you define the alerts using a templated format and upload them to Smart Tools.
  2. Enable your script or tool to perform the following actions:
    • Generate a JSON file that specifies the alert(s) to raise or lower and the Site components for which the alerts should appear in Smart Check, such as a specific machine, Site, or Delivery Group. See JSON format objects reference for a complete list of the JSON objects you can use in the script or tool.
    • Upload the JSON file to Citrix Insight Services.
  3. Create a check blueprint that will deploy your custom tools.  
  4. Deploy the check blueprint. The blueprint deploys your custom tool and executes the script, generating the JSON file and uploading it to Citrix Insight Services for analysis.

After your JSON file has been analyzed, Citrix Insight Services signals to Smart Tools that the Site has new information to display. When you click the Smart Check tab and select your Site, the Health Alerts page displays the results of the custom alert script. To view the specific alerts for a targeted component, click the component on the Health Alerts page. 

Back to top

Create custom alerts

To create custom alerts, you perform the following tasks: 

  1. Download and complete the Smart Check Alert Definition template.   
  2. Upload the template to Smart Tools. After uploading, Smart Tools adds your alert content to the Smart Check Alerts database.

After you upload your custom alerts, you can trigger them by creating a custom check to deploy your scripts and tools to your Site. For more information, see Create custom checks in this topic. 

Back to top

Alert Definition Template

The Alert Definition template is a CSV file that includes all the required fields for the alert. You download the template through the Add Smart Check Alerts wizard. You can access the wizard from the following places:

  • Your Library page: Click Smart Build and then select Add Smart Check Alerts from the menu button.

  • Blueprint Designer: Click Smart Build > New Blueprint, click the plus button, and then select Add Smart Check Alerts

You can add up to 500 alerts to to your Smart Tools account. When completing the template, you provide the following information for each alert entry: 

  • ID: Required. The universally unique identifier (UUID) for the alert. To generate a UUID for your custom alert, you can use a UUID generator such as the one at
  • Title: Required. A short description of the issue that triggers the alert. Text is formatted with Markdown.
  • Description: Required. A detailed description of the issue triggering the alert. Text is formatted with Markdown.
  • Instance description: Optional. Additional alert information that includes environment-specific data such as a XenDesktop service instance, a server name, or a user account SID. Text is formatted with Markdown and instance data is defined with Mustache. Examples:
    • "The unregistered service instance is {{serviceinstance}}."
    • "The database server {{dbServerName}} has not been backed up for {{numberofdays}} days."
  • Content credit: Optional. If you include third-party content describing the alert or fix, use this field to display the contributor's name and title on the alert in Smart Check. You can also include a link to the contributor's web site in Markdown format. Example: [John Smith](, Citrix Technology Professional
  • Fix description: Optional. A detailed description of the issue's resolution, including any step-by-step instructions and any links to helpful resources. Text is formatted with Markdown.
  • Severity: Required. The severity level of the alert. Depending on your alert, enter Warning or Error
  • Notes: Optional. Used for any additional information about the alert, but is not displayed in Smart Check. 

Your custom alerts are available only to users in your Smart Tools account. You cannot make your custom alerts available to users of other Smart Tools accounts. 

Important: Do not delete or rearrange any of the columns in the Alert Definition Template. If you remove columns or do not provide required data, Smart Check displays an error and does not upload your template. 

Back to top

To add new custom alerts

Smart Check recognizes new custom alerts when you upload alerts with new UUIDs. If you upload new alerts with the same UUIDs as existing custom alerts, Smart Check overwrites the existing alerts with the uploaded ones. If you attempt to upload new alerts that will exceed your limit of 500, Smart Check displays a warning that you will exceed your alerts limit and shows you the number of alerts you have already uploaded.

  1. From the Smart Tools menu bar, click Smart Build.
  2. From the Library, click the menu button and select Add Smart Check Alerts
  3. From the Add Smart Check Alerts dialog, click Alert Definition Template .CSV to download the Smart Check Alert template.
  4. In a text editor or CSV-compatible application, edit the template, completing all fields for each alert you want to add. Save the template.
  5. In the Add Smart Check Alerts dialog, click Select File and locate the completed template.
  6. Click Add. Smart Tools uploads the file and displays the entries you uploaded.
  7. Click Done to close the dialog.

Back to top

Modify custom alerts

To modify custom alerts that you've already uploaded, you complete the Alert Definition template, using the same UUID for each existing alert that you want to modify. When you upload the Alert Definition template, Smart Check recognizes the UUIDs and overwrites the existing alerts with the uploaded ones.

Important: Citrix strongly recommends maintaining your completed Smart Check Alert template in a version control system, so you can keep track of the alerts you've created outside of Smart Tools. Smart Tools does not keep records of your previous uploads and does not provide a method for retrieving a list of your existing custom alerts. 

Back to top

Create custom checks

After you create custom alerts and upload them to Smart Tools, you can trigger those alerts by creating a custom check. Custom checks use Smart Tools check blueprints to deploy your custom tools. The check blueprint you build for your custom check must be able to generate a JSON file defining the Smart Check alerts you want to raise or lower and the Site components you want to target. The blueprint also must be able to upload the JSON file to Citrix Insight Services. After Citrix Insight Services evaluates the file, Smart Check displays the results on the Site's Health Alerts page.

To build your custom check, you perform the following tasks:

  1. Enable your script or tool to generate a JSON file and upload it to Citrix Insight Services. To do this, you can use one of the following methods:
    • Modify your script or tool to enable it to generate the JSON output and upload it to Citrix Insight Services.
    • Create a separate script that converts the native output from your script or tool to JSON and uploads to Citrix Insight Services. 
  2. In your custom tool or in the separate script defining your alerts, add the parameters required for Smart Tools to upload the JSON file successfully to Citrix Insight Services:
    • clmCisXdSiteId
    • clmCisXdAgentFqdn
    • clmCisUploadTag
    • clmCisUploadToken
  3. Add the script(s) that comprise your custom tool to Smart Tools, as described in Add a new script. If you created a separate script to generate the JSON file defining your alerts, add this script to Smart Tools as well. All the scripts that you include in your custom check must be in your Smart Tools library so you can add them easily to the blueprint you will create.
  4. Create a new check blueprint and add the scripts for your custom tool to the blueprint. 
  5. If you created a separate script for converting your custom tool's output to JSON, add this script to the blueprint. 

After you create your custom check, you can publish it to the Checks and Blueprints catalog and limit access only to the Smart Tools users you specify. When you add the check from the Checks and Blueprints catalog, your custom check appears in Smart Check's Perform Check menu, alongside Citrix Recommended Checks.

Back to top

JSON script output and behavior

When generating the JSON file, ensure your tool or script creates output in the following format: 

  "alerts": {
    "ref": 0,
    "alrtId": "ee55b223-38eb-430f-bfc3-2cc157425472"
  "machines": {
    "ref": 0,
    "fqdn": ""
  "activateAlerts": 0

For complete details about the JSON objects you can use, see JSON format objects reference.

Additionally, ensure your tool or script will upload the generated JSON file to Citrix Insight Services.   

The alert IDs you specify for the JSON file can be:

  • The UUIDs you assigned to the custom alerts that you uploaded to Smart Tools.
  • The UUIDs assigned to the Citrix-provided alerts in the Smart Check alert database. This allows you to use Citrix-provided alert content, provided it is applicable for your custom tool. For a current list of alerts in the Smart Check alert database, see Smart Check alert reference.

Back to top

Required script and blueprint parameters

To successfully upload the JSON file to Citrix Insight Services, you will need to include required parameters in your custom tool or script.

In your custom tool or script, include the the following parameters:

  • clmCisXdSiteId
  • clmCisXdAgentFqdn
  • clmCisUploadTag
  • clmCisUploadToken

All of these parameters generate the information required for Citrix Insight Services to accept the JSON file that Smart Tools will upload when the check is run.

To reference these parameters in your custom tool or script, add the parameter definitions as shown in the example below:


To create a check blueprint

  1. From the Smart Tools menu, click Smart Build, click the menu button, and then select New Check.
  2. On the Overview tab, enter the following details:
    • Name: Enter a friendly name for the check. If you choose to publish your custom check, Smart Tools displays this name in the Checks and Blueprints catalog.
    • Description (optional): Enter a description of the check, such as what the check does and what happens when it's run. If you choose to publish your check, Smart Tools displays this description in the Checks and Blueprints catalog and in Smart Check. 
    • Applicable targets: Select Delivery Controllers or VDAs to indicate the components the check will evaluate.
    • Prerequisites (optional): Enter any items that are required to be present on the targeted machines or in the Site for the check to run successfully. Currently, Smart Check does not display this information when the check is configured for a Site. 
  3. In the left pane of the Blueprint Designer, expand My Script or Shared Script and drag and drop the scripts (for the JSON file and your custom tool) to the Scripts section of the Blueprint Designer. 
  4. Click Save

Back to top 

Publish custom checks 

After you create your check blueprint, you can publish it and share with other Smart Tools users using their email address. After publishing, your check appears in the Community section of the Checks and Blueprints catalog only for the users you've specified. No other Smart Tools users can see your custom check in the catalog. When users add the custom check to their account, Smart Tools adds it to Smart Check so they can launch or schedule it as they would any other health check.

To publish your custom check

  1. From the Smart Tools menu, click Smart Build, point to the check blueprint you want to share and then click Actions > View.
  2. From the Blueprint Designer, click Publish.
  3. On the Overview page, click Next.
  4. On the Check Details page, enter the following details:
    • Publish to: By default, Community is selected. Currently, you can only publish check blueprints to the Community category.
    • Allow editing: Select whether or not to allow other users to modify your check blueprint.
    • Publish check for: In the text field, enter the email addresses of the Smart Tools users who can access your check blueprint in the Checks and Blueprints catalog. If you want to allow all Smart Tools users to use your custom check in Smart Check, contact Citrix Technical Support for permission to publish to all Smart Tools users. 
  5. Click Finish.

After the check is published to the Checks and Blueprints catalog, the users you specified will see it in the Community section when they access the Checks and Blueprints catalog. If you make any updates to the check after users have added it to Smart Check, Smart Tools automatically updates the check in the background for those users. This background process runs every four hours.

Back to top 

Remove custom checks

If you no longer want others to use a custom check you created, you can use the following methods to remove it:

After the check is unpublished or deleted, the custom check no longer appears in the Checks and Blueprints catalog. Users who have already added the check to Smart Check can no longer use it with their Site because it no longer appears in the Perform Checks menu. Smart Tools removes the check and any associated schedules from those users' accounts during Smart Tools' Site sync operation which occurs every four hours. However, any manual uploads and reports resulting from the check are retained. 

If a check is unpublished or deleted while a user is attempting to run it, Smart Tools displays a message to the user that the check has been removed and advises the user to sync their Site data (Smart Check > View Site > Site Details > Sync Site Data).  

Back to top