Use custom checks and alerts with Smart Check



Smart Check includes a default set of checks you can use with your Site: Site Health Checks, Apps and Desktops Checks, and Updates Checks. If you currently use custom 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. Create custom alerts. To do this, you define the alerts using a templated format and upload them to Smart Tools.
  2. Add a script to Smart Tools that:
    • Generates 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. 
    • Uploads the JSON file to Citrix Insight Services.
  3. Create a blueprint that will deploy your custom tools and add the script that will generate and upload the JSON file.  
  4. Deploy the 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. 

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 deploy your scripts and tools to trigger the alerts and view the alert output in Smart Check.

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 five (5) alerts to the Alert Definition Template. 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. 

To create custom alerts

  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 your custom alerts, you update the Alert Definition template that you previously uploaded and upload your changes to Smart Tools. Smart Tools overwrites all your previously uploaded alerts with the alerts in the updated template. 

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 copies of your previous uploads. 

Back to top

Create custom checks to trigger custom alerts

After you create custom alerts and upload them to Smart Tools, you can reference them in a script that you include in the blueprint that will deploy your custom tools. By using a blueprint to deploy your custom tools, you are creating a custom check that will trigger the custom alerts you defined earlier. To do this, you perform the following tasks:

  1. Add a script to Smart Tools that will generate a JSON file and upload it to Citrix Insight Services. The JSON file specifies the alert IDs you want to raise or lower and Site components you want to target. For instructions to create a new script, see Add a new script
  2. Create a new Smart Tools blueprint that will deploy your custom tool or use an existing blueprint you have already created for this purpose. 
  3. Add the clmCisUploadToken parameter to your blueprint and enable it to be hidden during blueprint deployment.
  4. Add the script you created in Step 1 to the blueprint you created in Step 2.

Script output and behavior

The script you add to Smart Tools to generate the JSON file should create output that follows this format:

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

The script should also upload the generated JSON file to Citrix Insight Services.  For more information about the JSON format objects used to generate this output, see JSON format objects reference.

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.

Blueprint parameters

When you create the blueprint to deploy your custom tool, you will need to add a hidden parameter called clmCisUploadToken. This enables Smart Tools to generate a CIS upload token as part of the blueprint deployment process, so Citrix Insight Services will accept the JSON file that your script generates.

To add this parameter to your blueprint:

  1. From the Smart Tools menu, click Smart Build > New Blueprint or select an existing blueprint you want to use for deploying your custom tool.
  2. In the Blueprint Designer, click the Deploy tab and then click the Blueprint Inputs tab.
  3. In the Key column, enter clmCisUploadToken.
  4. In the Visible column, clear the checkbox. This hides the parameter so it won't display during the blueprint configuration.


To reference this parameter in your script, add the parameter definition as shown in the example below:



Back to top