API du tableau de bord : ServiceNow Fluent

  • Rversion finale: Australia
  • Mis à jour 12 mars 2026
  • 10 minutes de lecture

    • L’API de tableau de bord définit des tableaux de bord [par_dashboard] pour organiser et partager visuellement des données.

    Remarque :
    Pour obtenir la documentation et des exemples d’API les plus récents ServiceNow Fluent , consultez les ServiceNow Fluent Référence API et référentiel d’exemples de SDK ServiceNow sur GitHub.

    Un tableau de bord se compose d’onglets, de widgets, de visibilités et d’autorisations. Chaque onglet contient des widgets qui affichent des visualisations de données, des en-têtes, du texte enrichi et d’autres composants.

    Les tableaux de bord peuvent être utilisés comme page d’accueil d’un espace de travail en faisant référence à un ou plusieurs espaces de travail à partir du tableau de visibilités de l’objet Tableau de bord . Pour créer un espace de travail, reportez-vous à la section Espace de travail API : ServiceNow Fluent.

    Pour des informations générales sur les tableaux de bord, reportez-vous à la section Dashboards in Platform Analytics.

    Objet de tableau de bord

    Créer un tableau de bord partageable [par_dashboard] avec des visualisations de données, des filtres, des onglets, des widgets, des autorisations et des règles de visibilité.

    Tableau 1. Propriétés
    Nom Type Description
    $id Chaîne ou numéro Requis. ID unique pour l’objet de métadonnées. Lorsque vous créez l’application, cet ID est haché en une sys_id unique. Pour en savoir plus, consultez ServiceNow Fluent Constructions linguistiques.

    Format : Now.ID['chaîne' ou numéro]
    nom Chaîne Requis. Un nom à afficher pour le tableau de bord.
    actif Booléen Marqueur indiquant si le tableau de bord est actif.

    Par défaut : true
    Onglets Tableau Liste des onglets à afficher dans le tableau de bord. Pour plus d'informations, consultez Tableau d’onglets.
    permissions Tableau Une liste des autorisations utilisateur requises pour accéder au tableau de bord. Pour plus d'informations, consultez Tableau des autorisations.
    Visibilités Tableau Liste des règles de visibilité qui contrôlent quelles expériences UX affichent le tableau de bord. Pour plus d'informations, consultez Tableau des visibilités.

    Par défaut : une règle de visibilité par défaut avec sys_id 08c73d60537101100834ddeeff7b1287 est utilisée.
    $meta Objet Métadonnées pour les métadonnées de l’application.
    Avec la propriété installMethod , vous pouvez mapper les métadonnées d’application à un répertoire de sortie qui ne se charge que dans des circonstances spécifiques.
    $meta: {
      installMethod: 'String'
}
    Valeurs valides pour installMethod :
    • demo : génère les métadonnées de l’application dans le répertoire metadata/unload.demo à installer avec l’application lorsque l’option Charger les données de démonstration est sélectionnée.
    • première installation : génère les métadonnées de l’application dans le répertoire metadata/unload à installer uniquement la première fois qu’une application est installée sur une instance.
    		 
    import { Dashboard } from "@servicenow/sdk/core";

Dashboard({
  $id: Now.ID["incident_management_dashboard"],
  name: "Incident Management Dashboard",
  tabs: [
    {
      $id: Now.ID["incident_overview_tab"],
      name: "Overview",
      widgets: [
        // Single Score: Total Open Incidents
        {
          $id: Now.ID["total_open_incidents_widget"],
          component: "single-score",
          componentProps: {
            dataSources: [
              {
                label: "Incident",
                sourceType: "table",
                tableOrViewName: "incident",
                filterQuery: "",
                reportSourceSysId: "d94d6f62d7632100b96d45a3ce6103d2",
                id: "dGFibGVpbmNpZGVudDE3NjMzOTI0OTY5ODE="
              }
            ],
            headerTitle: "Open Incidents",
            metrics: [
              {
                dataSource: "dGFibGVpbmNpZGVudDE3NjMzOTI0OTY5ODE=",
                id: "ZEdGaWJHVnBibU5wWkdWdWRERTNOak16T1RJME9UWTVPREU9MTc2MzM5MjQ5Nzc5OQ==",
                aggregateFunction: "COUNT",
                axisId: "primary"
              }
            ],
            sortBy: "value"
          },
          height: 14,
          width: 14,
          position: { x: 0, y: 0 }
        },
        // Vertical Bar: Incidents by Priority
        {
          $id: Now.ID["incidents_by_priority_widget"],
          component: "vertical-bar",
          componentProps: {
            dataSources: [
              {
                label: "Incident",
                sourceType: "table",
                tableOrViewName: "incident",
                filterQuery: "",
                reportSourceSysId: "d94d6f62d7632100b96d45a3ce6103d2",
                id: "dGFibGVpbmNpZGVudDE3NjI3OTU4OTg3NDA="
              }
            ],
            headerTitle: "Incidents by Priority",
            metrics: [
              {
                dataSource: "dGFibGVpbmNpZGVudDE3NjI3OTU4OTg3NDA=",
                id: "ZEdGaWJHVnBibU5wWkdWdWRERTNOakkzT1RVNE9UZzNOREE9MTc2Mjc5NTg5OTM5OA==",
                aggregateFunction: "COUNT",
                axisId: "primary"
              }
            ],
            groupBy: [
              {
                groupBy: [
                  {
                    dataSource: "dGFibGVpbmNpZGVudDE3NjI3OTU4OTg3NDA=",
                    groupByField: "priority"
                  }
                ],
                maxNumberOfGroups: 10,
                numberOfGroupsBasedOn: "NO_OF_GROUP_BASED_ON_PER_METRIC",
                showOthers: false,
                disableRanges: false
              }
            ],
            sortBy: "value"
          },
          height: 14,
          width: 17,
          position: { x: 14, y: 0 }
        },
        // Vertical Bar: Incidents by State
        {
          $id: Now.ID["incidents_by_state_widget"],
          component: "vertical-bar",
          componentProps: {
            dataSources: [
              {
                label: "Incident",
                sourceType: "table",
                tableOrViewName: "incident",
                filterQuery: "",
                reportSourceSysId: "d94d6f62d7632100b96d45a3ce6103d2",
                id: "dGFibGVpbmNpZGVudDE3NjI3OTU4OTg3NDA="
              }
            ],
            headerTitle: "Incidents by State",
            metrics: [
              {
                dataSource: "dGFibGVpbmNpZGVudDE3NjI3OTU4OTg3NDA=",
                id: "ZEdGaWJHVnBibU5wWkdWdWRERTNOakkzT1RVNE9UZzNOREE9MTc2Mjc5NTg5OTM5OA==",
                aggregateFunction: "COUNT",
                axisId: "primary"
              }
            ],
            groupBy: [
              {
                groupBy: [
                  {
                    dataSource: "dGFibGVpbmNpZGVudDE3NjI3OTU4OTg3NDA=",
                    groupByField: "state"
                  }
                ],
                maxNumberOfGroups: 10,
                numberOfGroupsBasedOn: "NO_OF_GROUP_BASED_ON_PER_METRIC",
                showOthers: false,
                disableRanges: false
              }
            ],
            sortBy: "value"
          },
          height: 14,
          width: 17,
          position: { x: 31, y: 0 }
        }
      ]
    },
    {
      $id: Now.ID["incident_trends_tab"],
      name: "Trends",
      widgets: [] // Can be populated later or left empty
    }
  ],
  visibilities: [
    {
      $id: Now.ID["incident_dashboard_visibility"],
      experience: incidentWorkspace
    }
  ],
  permissions: []
})
    L’espace de travail référencé est défini à l’aide de l’objet Workspace :
    import { Workspace } from "@servicenow/sdk/core";

export const myWorkspace = Workspace({
  $id: Now.ID["my_workspace"],
  title: "My Workspace",
  path: "my-workspace",
  tables: ["incident"],
  listConfig: myListConfig
})

    Tableau d’onglets

    Créez des onglets [par_dashboard_tab] contenant des widgets pour un tableau de bord.

    Dans un tableau de bord, les onglets sont classés en fonction de leur position dans le tableau.

    Tableau 2. Propriétés
    Nom Type Description
    $id Chaîne ou numéro Requis. ID unique pour l’objet de métadonnées. Lorsque vous créez l’application, cet ID est haché en une sys_id unique. Pour en savoir plus, consultez ServiceNow Fluent Constructions linguistiques.

    Format : Now.ID['chaîne' ou numéro]
    nom Chaîne Requis. Un nom à afficher sur l’onglet.
    actif Booléen Marqueur indiquant si l’onglet est actif.

    Par défaut : true
    widgets Tableau Une liste des widgets à afficher dans l’onglet. Pour plus d'informations, consultez Tableau de widgets. 
    tabs: [
    {
      $id: Now.ID["my_dashboard_tab1"],
      name: "Overview",
      widgets: [
        {
          $id: Now.ID["my_dashboard_widget_1"],
          component: "single-score",
          componentProps: {
            dataSources: [
              {
                label: "Incident",
                sourceType: "table",
                tableOrViewName: "incident",
                filterQuery: "",
                reportSourceSysId: "d94d6f62d7632100b96d45a3ce6103d2",
                id: "dGFibGVpbmNpZGVudDE3NjMzOTI0OTY5ODE="
              }
            ],
            headerTitle: "Open Incidents",
            metrics: [
              {
                dataSource: "dGFibGVpbmNpZGVudDE3NjMzOTI0OTY5ODE=",
                id: "ZEdGaWJHVnBibU5wWkdWdWRERTNOak16T1RJME9UWTVPREU9MTc2MzM5MjQ5Nzc5OQ==",
                aggregateFunction: "COUNT",
                axisId: "primary"
              }
            ],
            sortBy: "value"
          },
          height: 14,
          width: 14,
          position: { x: 0, y: 0 }
        }
      ]
    }
]

    Tableau de widgets

    Créer des widgets [par_dashboard_widget] dans un onglet sous forme de grille.

    Les tableaux de bord utilisent un système de grille à 48 points pour positionner les widgets.

    Tableau 3. Propriétés
    Nom Type Description
    $id Chaîne ou numéro Requis. ID unique pour l’objet de métadonnées. Lorsque vous créez l’application, cet ID est haché en une sys_id unique. Pour en savoir plus, consultez ServiceNow Fluent Constructions linguistiques.

    Format : Now.ID['chaîne' ou numéro]
    composant Référence ou chaîne Requis. Nom d’un composant (tel que ligne ou score unique) ou sys_id d’un composant de la table Définition du macroponent UX [sys_ux_macroponent] à afficher en tant que widget.

    Les noms des composants ne sont pas sensibles à la casse et sont résolus à leur sys_ids pendant le processus de génération.
    hauteur Numéro Requis. Hauteur du widget en unités de grille.
    largeur Numéro Requis. Largeur du widget en unités de grille.

    Valeur maximale : 48
    position Objet Requis. Position du widget dans la mise en page de grille avec les propriétés x et y . Par exemple, une valeur de { x : 0, y : 0 } positionne le widget dans le coin supérieur gauche de la grille.
    componentProps Objet La configuration des propriétés d’un composant. Pour plus d'informations, consultez Objet componentProps. 
    widgets: [
              {
                  $id: Now.ID['incident-count-chart'],
                  component: 'vertical-bar', // Vertical bar chart
                  componentProps: {
                      title: 'Incident Count',
                      dataSource: 'incident',
                      aggregation: 'count'
                  },
                  height: 8,
                  width: 6,
                  position: { x: 0, y: 0 },
              },
              {
                  $id: Now.ID['recent-incidents-list'],
                  component: 'list', // List component
                  componentProps: {
                      table: 'incident',
                      filter: 'active=true',
                      limit: 10,
                      columns: ['number', 'short_description', 'priority', 'state']
                  },
                  height: 8,
                  width: 6,
                  position: { x: 6, y: 0 },
              }
          ],
      },
      {
          $id: Now.ID['analytics'],
          name: 'Analytics',
          widgets: [
              {
                  $id: Now.ID['metrics-widget'],
                  component: 'single-score', // Single score component
                  componentProps: {
                      title: 'Key Metrics',
                      scoreSize: 'large'
                  },
                  height: 12,
                  width: 12,
                  position: { x: 0, y: 0 },
              }
]

    Objet componentProps

    Configurer les propriétés des widgets [par_dashboard_widget].

    Les propriétés disponibles sont déterminées par le composant spécifié avec la propriété de composant de l’objet Tableau de bord .

    • Les composants de données de tendance nécessitent les propriétés dataSources, metrics et trendBy . La propriété groupBy est facultative.
    • Les composants de données de groupe nécessitent les propriétés dataSources, metrics et groupBy . La propriété trendBy n’est pas prise en charge dans ces visualisations.
    • Les composants de données simples nécessitent les propriétés dataSources et mesures . Les propriétés groupBy et trendBy ne sont pas prises en charge dans ces visualisations.
    Tableau 4. Propriétés
    Nom Type Description
    dataSources Tableau Une liste des sources de données pour le composant. Par exemple :
    dataSources: [
  {
    label: "Incident", // Human-readable label
    sourceType: "table", // Type of data source
    tableOrViewName: "incident", // ServiceNow table name
    filterQuery: "", // Optional encoded query filter
    id: "data_source_1" // Unique data source ID
  },
...
]
    headerTitle Chaîne Un titre à afficher avec le widget.
    metrics Tableau Une liste de mesures à mesurer pour la source de données. Par exemple :
    metrics: [
    {
        dataSource: 'data_source_1',  // Must match dataSource id
        id: 'metric_1',  // Unique metric ID
        aggregateFunction: 'AVG',  // COUNT, SUM, AVG, MIN, MAX, COUNT_DISTINCT
        aggregateField: 'business_duration'  // Field to be used for aggregation.
        axisId: 'primary',  // Which axis to display the series
    },
...
]
    groupBy Tableau Liste des configurations de regroupement et d’organisation des données par source de données. Par exemple :
    groupBy: [
  {
    groupBy: [
      {
        dataSource: "data_source_1", // Must match dataSource id
        groupByField: "state" // Field to group by
      }
    ],
    maxNumberOfGroups: 10, // Maximum categories to show
    showOthers: false // Show "Others" category
  },
...
]
    trendBy Objet Configuration des graphiques de tendance. Par exemple :
    trendBy: {
  "trendByFrequency": "year", // Frequency of the trend (date, week, month, year)
  "trendByFields": [
    {
      "field": "sys_created_on", // Field to trend on (from the table of the dataSource)
      "metric": "metric_1" // ID of the metric
    }
  ]
}
    sortBy Chaîne Méthode de tri des données.
    Valeurs valides :
    • valide
    • étiquette
    • Champ
    Dans l’exemple suivant, le composant ligne , qui est une visualisation de type de données de tendance, est utilisé pour montrer comment une mesure change au fil du temps.
    {
    component: 'line',
    componentProps: {
        dataSources: [
            {
                label: 'Incident',
                sourceType: 'table',
                tableOrViewName: 'incident',
                filterQuery: '',
                id: 'data_source_1',
            },
        ],
        headerTitle: 'Incidents by State',
        metrics: [
            {
                dataSource: 'data_source_1',
                id: 'metric_1',
                aggregateFunction: 'COUNT',
                axisId: 'primary',
            },
        ],
        trendBy: {
            trendByFrequency: "year",
            trendByFields: [
                {
                    field: "sys_created_on",
                    metric: "metric_1"
                }
            ]
        },
    },
    height: 14,
    width: 17,
    position: { x: 0, y: 0 },
}
    Dans l’exemple suivant, le composant à score unique , qui est une visualisation de type de données simple, est utilisé pour afficher une mesure de nombre unique.
    {
    component: 'single-score',
    componentProps: {
        dataSources: [
            {
                label: 'Incident',
                sourceType: 'table',
                tableOrViewName: 'incident',
                filterQuery: '',
                id: 'data_source_1',
            },
        ],
        headerTitle: 'Open Incidents',
        metrics: [
            {
                dataSource: 'data_source_1',
                id: 'metric_1',
                aggregateFunction: 'COUNT',
                axisId: 'primary',
            },
        ]
    },
    height: 14,
    width: 14,
    position: { x: 0, y: 0 },
}

    Tableau des autorisations

    Définissez les autorisations [par_dashboard_permission] pour lire, modifier et partager un tableau de bord.

    Au moins une des propriétés utilisateur,groupe ou rôle doit être spécifiée pour chaque autorisation du tableau.

    Tableau 5. Propriétés
    Nom Type Description
    $id Chaîne ou numéro Requis. ID unique pour l’objet de métadonnées. Lorsque vous créez l’application, cet ID est haché en une sys_id unique. Pour en savoir plus, consultez ServiceNow Fluent Constructions linguistiques.

    Format : Now.ID['chaîne' ou numéro]
    utilisateur Référence ou chaîne Identificateur de variable ou sys_id d’un utilisateur [sys_user] auquel accorder des autorisations. Pour définir un utilisateur, utilisez l’option API d’enregistrement : ServiceNow Fluent.
    groupe Référence ou chaîne Identificateur ou sys_id de variable d’un groupe d’utilisateurs [sys_user_group] auquel accorder des autorisations. Pour définir un utilisateur, utilisez l’option API d’enregistrement : ServiceNow Fluent.
    rôle Référence ou chaîne Identificateur de variable ou sys_id d’un rôle [sys_user_role] auquel accorder des autorisations. Pour définir un utilisateur, utilisez l’option API du rôle : ServiceNow Fluent.
    canRead Booléen Marqueur indiquant si l’utilisateur, le groupe ou le rôle peut afficher le tableau de bord.

    Par défaut : true
    canWrite Booléen Marqueur indiquant si l’utilisateur, le groupe ou le rôle peut modifier le tableau de bord.

    Valeur par défaut : false
    canShare Booléen Marqueur indiquant si l’utilisateur, le groupe ou le rôle peut partager le tableau de bord.

    Valeur par défaut : false
    propriétaire Booléen Marqueur indiquant si l’utilisateur, le groupe ou le rôle est le propriétaire du tableau de bord. Pour au moins un utilisateur, la propriété du propriétaire doit être définie sur true.

    Valeur par défaut : false

    		 
    permissions: [
        {
            $id: Now.ID['manager-user-permission'],
            user: 'a8f98bb0eb32010045e1a5115206fe3a', // sys_id of manager user
            canRead: true,
            canWrite: true,
            owner: true,
        },
        {
            $id: Now.ID['itil-role-permission'],
            role: '2831a114c611228501d4ea6c309d626d', // sys_id of itil role
            canRead: true,
            canWrite: false,
        },
        {
            $id: Now.ID['support-group-permission'],
            group: 'd625dccec0a8016700a222a0f7900d06', // sys_id of Service Desk group
            canRead: true,
            canWrite: false,
        }
]

    Tableau des visibilités

    Définissez des règles de visibilité [par_dashboard_visibility] pour lesquelles les expériences UX affichent le tableau de bord.

    Tableau 6. Propriétés
    Nom Type Description
    $id Chaîne ou numéro Requis. ID unique pour l’objet de métadonnées. Lorsque vous créez l’application, cet ID est haché en une sys_id unique. Pour en savoir plus, consultez ServiceNow Fluent Constructions linguistiques.

    Format : Now.ID['chaîne' ou numéro]
    expérience Référence ou chaîne Requis. Identificateur de variable d’un objet d’espace de travail ou d’un sys_id d’une application UX [sys_ux_page_registry]. Pour plus d'informations, consultez Espace de travail API : ServiceNow Fluent. 
    visibilities: [
  {
    $id: Now.ID["dashboard_visibility_1"],
    experience: myWorkspace // Reference to Workspace object
  }
]