---
sourceDocument: Référence de l’API Xanadu
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/fr-FR/xanadu/api-reference

 Release :

    - xanadu

ft:locale :

    - fr-FR

ft:publication_title :

    - Référence de l’API Xanadu

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# spUtil : Client

# spUtil : Client {#ariaid-title1}

* Rversion finale: Xanadu
* 
* Mis à jour 1 août 2024
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 7 minutes de lecture

L'API spUtil fournit des méthodes utilitaires permettant d'exécuter des fonctions courantes dans un Portail de services script client de widget.  
Ces fonctions sont les suivantes :

* Afficher un message d'erreur de notification. [spUtil : addErrorMessage(message de chaîne)](https://servicenow-prod.fluidtopics.net/TIDn~_TeeSJuFNml3FyShg#SPU-addErrorMessage_S "Affiche un message d’erreur de notification.")
* Affichez un message d'informations de notification. [spUtil : addInfoMessage(message de chaîne)](https://servicenow-prod.fluidtopics.net/TIDn~_TeeSJuFNml3FyShg#SPU-addInfoMessage_S "Affiche un message d’informations de notification.")
* Affichez un message de notification trivial. [spUtil : addTrivialMessage(message de chaîne)](https://servicenow-prod.fluidtopics.net/TIDn~_TeeSJuFNml3FyShg#SPU-addTrivialMessage_S "Affiche un message de notification trivial.")
* Créez un identificateur unique. [spUtil : createUid()](https://servicenow-prod.fluidtopics.net/TIDn~_TeeSJuFNml3FyShg#SPU-createUid "Créez un identificateur unique.")
* Formater une chaîne avec des variables. [spUtil - format(chaîne, modèle, objet, données)](https://servicenow-prod.fluidtopics.net/TIDn~_TeeSJuFNml3FyShg#SPU-format_S_O "Met en forme une chaîne qui contient des variables.")
* Incorporer un modèle de widget dans un script client de widget. [spUtil : obtenir (String, widgetId, Objet, données)](https://servicenow-prod.fluidtopics.net/TIDn~_TeeSJuFNml3FyShg#SPU-get_S "Incorpore un modèle de widget dans un script client de widget.")
* Récupérez tous les en-têtes à utiliser pour les appels d'API. [spUtil : getHeaders()](https://servicenow-prod.fluidtopics.net/TIDn~_TeeSJuFNml3FyShg#SPU-getHeaders "Récupère tous les en-têtes à utiliser pour les appels d’API.")
* Renvoyer le domaine d'hôte complet. [spUtil : getHost()](https://servicenow-prod.fluidtopics.net/TIDn~_TeeSJuFNml3FyShg#SPU-getHost "Renvoie le domaine hôte complet.")
* Exécutez le rappel avec réponse de préférence utilisateur en transmettant le nom de la préférence. [spUtil : getPreference(Préférence de chaîne, rappel de fonction)](https://servicenow-prod.fluidtopics.net/TIDn~_TeeSJuFNml3FyShg#SPU-getPreference "Exécute le rappel avec la réponse de préférence utilisateur en transmettant le nom de la préférence.")
* Renvoyer les informations actuelles de l'URL du portail de services. [spUtil : getURL()](https://servicenow-prod.fluidtopics.net/TIDn~_TeeSJuFNml3FyShg#SPU-getURL "Renvoie les informations URL actuelles du portail de services.")
* Vérifiez si le client actuel est un équipement mobile. [spUtil : isMobile()](https://servicenow-prod.fluidtopics.net/TIDn~_TeeSJuFNml3FyShg#SPU-isMobile "Vérifie si le client actuel est un équipement mobile.")
* Analysez les attributs séparés par des virgules dans une chaîne spécifiée. [spUtil : parseAttributes(attributs de chaîne)](https://servicenow-prod.fluidtopics.net/TIDn~_TeeSJuFNml3FyShg#SPU-parseAttributes "Analyse les attributs séparés par des virgules dans une chaîne spécifiée.")
* Surveillez les mises à jour d'une table ou d'un filtre et renvoie la valeur à partir de la fonction de rappel. [spUtil : recordWatch($scope d'objet, table de chaînes, filtre de chaîne, rappel de fonction)](https://servicenow-prod.fluidtopics.net/TIDn~_TeeSJuFNml3FyShg#SPU-recordWatch_O_S_S_F "Surveille les mises à jour d’une table ou d’un filtre et renvoie la valeur à partir de la fonction de rappel.")
* Appelez le serveur et remplacez les options et données actuelles par la réponse du serveur. [spUtil : refresh(objet $scope)](https://servicenow-prod.fluidtopics.net/TIDn~_TeeSJuFNml3FyShg#SPU-refresh_O "Appelle le serveur et remplace les options et données actuelles par la réponse du serveur.")
* Faites défiler l'écran jusqu'à l'élément avec le sélecteur spécifié, sur une période de temps spécifiée. [spUtil : scrollTo(Sélecteur de chaîne, nombre d'heures)](https://servicenow-prod.fluidtopics.net/TIDn~_TeeSJuFNml3FyShg#SPU-scrollTo "Défile jusqu’à l’élément avec le sélecteur spécifié, pendant une période de temps spécifiée.")
* Mettez à jour le fil d'Ariane de l'en-tête. [spUtil : setBreadCrumb(Object $scope, Tableau de fils d'Ariane)](https://servicenow-prod.fluidtopics.net/TIDn~_TeeSJuFNml3FyShg#SPU-setBreadCrumb "Met à jour le fil d’Ariane de l’en-tête.")
* Définissez une préférence utilisateur. [spUtil : setPreference(String pref, valeur de chaîne)](https://servicenow-prod.fluidtopics.net/TIDn~_TeeSJuFNml3FyShg#SPU-setPreference "Définit une préférence utilisateur.")
* Mettez à jour la page de recherche. [spUtil : setSearchPage(String searchPage)](https://servicenow-prod.fluidtopics.net/TIDn~_TeeSJuFNml3FyShg#SPU-setSearchPage "Met à jour la page de recherche.")
* Mettez à jour l'objet de données sur le serveur dans un périmètre donné. [spUtil : mettre à jour (objet $scope)](https://servicenow-prod.fluidtopics.net/TIDn~_TeeSJuFNml3FyShg#SPU-update_O "Met à jour l’objet de données sur le serveur dans un périmètre donné.")

Pour en savoir plus sur les widgets, consultez [Widgets du portail de services](https://www.servicenow.com/docs/access?context=service-portal-widgets&version=xanadu&pubname=xanadu-platform-user-interface&ft:locale=en-US).

## spUtil : addErrorMessage(message de chaîne) {#ariaid-title2}

Affiche un message d'erreur de notification.
{#SPU-addErrorMessage_S__table_yjp_zpz_31b__entry__3}

| Nom | Type | Description |
|-|-|-|
| message | Chaîne | Message d'erreur à afficher. |
[Tableau 1. Paramètres]

{#SPU-addErrorMessage_S__table_yjp_zpz_31b} {#SPU-addErrorMessage_S__table_zjp_zpz_31b__entry__2}

| Type | Description |
|-|-|
| nul |   |
[Tableau 2. Renvoie]

{#SPU-addErrorMessage_S__table_zjp_zpz_31b}  

    spUtil.addErrorMessage("There has been an error processing your request")

## spUtil : addInfoMessage(message de chaîne) {#ariaid-title3}

Affiche un message d'informations de notification.
{#SPU-addInfoMessage_S__table_b2m_bqz_31b__entry__3}

| Nom | Type | Description |
|-|-|-|
| message | Chaîne | Message à afficher. |
[Tableau 3. Paramètres]

{#SPU-addInfoMessage_S__table_b2m_bqz_31b} {#SPU-addInfoMessage_S__table_c2m_bqz_31b__entry__2}

| Type | Description |
|-|-|
| nul |   |
[Tableau 4. Renvoie]

{#SPU-addInfoMessage_S__table_c2m_bqz_31b}  

    spUtil.addInfoMessage("Your order has been placed")

## spUtil : addTrivialMessage(message de chaîne) {#ariaid-title4}

Affiche un message de notification trivial.
Les messages anodins disparaissent après un court laps de temps.
{#SPU-addTrivialMessage_S__table_kcx_dqz_31b__entry__3}

| Nom | Type | Description |
|-|-|-|
| message | Chaîne | Message à afficher. |
[Tableau 5. Paramètres]

{#SPU-addTrivialMessage_S__table_kcx_dqz_31b} {#SPU-addTrivialMessage_S__table_lcx_dqz_31b__entry__2}

| Type | Description |
|-|-|
| nul |   |
[Tableau 6. Renvoie]

{#SPU-addTrivialMessage_S__table_lcx_dqz_31b}  

    spUtil.addTrivialMessage("Thanks for your order")

## spUtil : createUid() {#ariaid-title5}

Créez un identificateur unique.
{#SPU-createUid__table_ccv_cbr_t2b__entry__3}

| Nom | Type | Description |
|-|-|-|
| Aucun |   |   |
[Tableau 7. Paramètres]

{#SPU-createUid__table_ccv_cbr_t2b} {#SPU-createUid__table_dcv_cbr_t2b__entry__2}

| Type | Description |
|-|-|
| Chaîne | Un ID unique de 32 caractères. |
[Tableau 8. Renvoie]

{#SPU-createUid__table_dcv_cbr_t2b}

## spUtil : obtenir (String, widgetId, Objet, données) {#ariaid-title6}

Incorpore un modèle de widget dans un script client de widget.
La fonction de rappel renvoie le modèle de widget complet. Pour en savoir plus sur les widgets, consultez [Widgets du portail de services](https://www.servicenow.com/docs/access?context=service-portal-widgets&version=xanadu&pubname=xanadu-platform-user-interface&ft:locale=en-US).
{#SPU-get_S__table_bcy_fqz_31b__entry__3}

| Nom | Type | Description |
|-|-|-|
| widgetId (en anglais seulement) | Chaîne | ID ou sys_id du widget à incorporer. |
| données | Objet | Facultatif. Paires nom/valeur de paramètres à transmettre au modèle de widget. |
[Tableau 9. Paramètres]

{#SPU-get_S__table_bcy_fqz_31b} {#SPU-get_S__table_ccy_fqz_31b__entry__2}

| Type | Description |
|-|-|
| Objet | Modèle du widget incorporé. |
[Tableau 10. Renvoie]

{#SPU-get_S__table_ccy_fqz_31b}  
Sans transmission de données.

    spUtil.get("widget-cool-clock").then(function(response) {
      c.coolClock = response;
    });

Une fois les données transmises.

    spUtil.get('pps-list-modal', {title: c.data.editAllocations, 
      table: 'resource_allocation', 
      queryString: 'GROUPBYuser^resource_plan=' + c.data.sysId, 
      view: 'resource_portal_allocations' }).then(function(response) {
        var formModal = response;
        c.allocationListModal = response;
      });  	

## spUtil : getHeaders() {#ariaid-title7}

Récupère tous les en-têtes à utiliser pour les appels d'API.
{#SPU-getHeaders__table_dns_ldr_t2b__entry__3}

| Nom | Type | Description |
|-|-|-|
| Aucun |   |   |
[Tableau 11. Paramètres]

{#SPU-getHeaders__table_dns_ldr_t2b} {#SPU-getHeaders__table_ens_ldr_t2b__entry__2}

| Type | Description |
|-|-|
| Objet | Tous les en-têtes à utiliser pour les appels d'API. |
[Tableau 12. Renvoie]

{#SPU-getHeaders__table_ens_ldr_t2b}

## spUtil : getHost() {#ariaid-title8}

Renvoie le domaine hôte complet.
{#SPU-getHost__table_olb_vkr_t2b__entry__3}

| Nom | Type | Description |
|-|-|-|
| Aucun |   |   |
[Tableau 13. Paramètres]

{#SPU-getHost__table_olb_vkr_t2b} {#SPU-getHost__table_plb_vkr_t2b__entry__2}

| Type | Description |
|-|-|
| Chaîne | Le domaine hôte complet, par exemple `hi.servicenow.com` |
[Tableau 14. Renvoie]

{#SPU-getHost__table_plb_vkr_t2b}

## spUtil : getPreference(Préférence de chaîne, rappel de fonction) {#ariaid-title9}

Exécute le rappel avec la réponse de préférence utilisateur en transmettant le nom de la préférence.
{#SPU-getPreference__table_rvb_34r_t2b__entry__3}

| Nom | Type | Description |
|-|-|-|
| préférence | Chaîne | Nom de la préférence. |
| rappel | Fonction | Définissez la fonction de rappel. |
[Tableau 15. Paramètres]

{#SPU-getPreference__table_rvb_34r_t2b} {#SPU-getPreference__table_svb_34r_t2b__entry__2}

| Type | Description |
|-|-|
| nul |   |
[Tableau 16. Renvoie]

{#SPU-getPreference__table_svb_34r_t2b}

## spUtil : getURL() {#ariaid-title10}

Renvoie les informations URL actuelles du portail de services.
{#SPU-getURL__table_sbh_dls_t2b__entry__3}

| Nom | Type | Description |
|-|-|-|
| Aucun |   |   |
[Tableau 17. Paramètres]

{#SPU-getURL__table_sbh_dls_t2b} {#SPU-getURL__table_tbh_dls_t2b__entry__2}

| Type | Description |
|-|-|
| Chaîne | URL actuelle du portail de services. |
[Tableau 18. Renvoie]

{#SPU-getURL__table_tbh_dls_t2b}

## spUtil - format(chaîne, modèle, objet, données) {#ariaid-title11}

Met en forme une chaîne qui contient des variables.
Utilisez cette méthode comme alternative à la concaténation de chaînes.
{#SPU-format_S_O__table_yrh_hqz_31b__entry__3}

| Nom | Type | Description |
|-|-|-|
| modèle | Chaîne | Modèle de chaîne qui contient des valeurs pour la substitution de variables. |
| données | Objet | Objet contenant les valeurs des variables définies dans la chaîne de modèle. |
[Tableau 19. Paramètres]

{#SPU-format_S_O__table_yrh_hqz_31b} {#SPU-format_S_O__table_zrh_hqz_31b__entry__2}

| Type | Description |
|-|-|
| Chaîne | Chaîne contenant les valeurs variables au lieu de la nomenclature des variables. |
[Tableau 20. Renvoie]

{#SPU-format_S_O__table_zrh_hqz_31b}  

    spUtil.format('An error ocurred: {error} when loading {widget}', {error: '404', widget: 'sp-widget'})

Sortie :

    'An error occurred: 404 when loading sp-widget'

## spUtil : isMobile() {#ariaid-title12}

Vérifie si le client actuel est un équipement mobile.
{#SPU-isMobile__table_gz2_pcd_v2b__entry__3}

| Nom | Type | Description |
|-|-|-|
| Aucun |   |   |
[Tableau 21. Paramètres]

{#SPU-isMobile__table_gz2_pcd_v2b} {#SPU-isMobile__table_hz2_pcd_v2b__entry__2}

| Type | Description |
|-|-|
| Booléen | Marqueur indiquant si le client actuel est un équipement mobile. Valeurs valides : * true : le client actuel est un équipement mobile. * false : le client actuel n'est pas un équipement mobile. {#SPU-isMobile__ul_fpx_gsv_fvb} |
[Tableau 22. Renvoie]

{#SPU-isMobile__table_hz2_pcd_v2b}

## spUtil : parseAttributes(attributs de chaîne) {#ariaid-title13}

Analyse les attributs séparés par des virgules dans une chaîne spécifiée.
{#SPU-parseAttributes__table_jkb_tvm_w2b__entry__3}

| Nom | Type | Description |
|-|-|-|
| attributs | Chaîne | Chaîne contenant des attributs séparés par des virgules, tels que le champ Attributs d'un enregistrement de dictionnaire. |
[Tableau 23. Paramètres]

{#SPU-parseAttributes__table_jkb_tvm_w2b} {#SPU-parseAttributes__table_kkb_tvm_w2b__entry__2}

| Type | Description |
|-|-|
| Tableau | Tableau d'objets contenant les attributs analysés. |
[Tableau 24. Renvoie]

{#SPU-parseAttributes__table_kkb_tvm_w2b}  

    function getRefQualElements() {
      var refQualElements = [];
      if (field && field.attributes && field.attributes.indexOf('ref_qual_elements') > -1) {
        var attributes = spUtil.parseAttributes(field.attributes);
        refQualElements = attributes['ref_qual_elements'].split(';');
      }
      return refQualElements;
    }

## spUtil : recordWatch($scope d'objet, table de chaînes, filtre de chaîne, rappel de fonction) {#ariaid-title14}

Surveille les mises à jour d'une table ou d'un filtre et renvoie la valeur à partir de la fonction de rappel.
Permet à un développeur de widget de répondre aux mises à jour de table en temps réel. Par exemple, en utilisant recordWatch(), le widget Simple List peut écouter les modifications apportées à sa table de données. Si des enregistrements sont ajoutés, supprimés ou mis à jour, le widget se met à jour automatiquement.  
Remarque :  
Lorsque vous passez l'argument `$scope` dans la fonction recordWatch(),`injectez-$scope` dans les paramètres de votre fonction de script client.
{#SPU-recordWatch_O_S_S_F__table_vys_mqz_31b__entry__3}

| Nom | Type | Description |
|-|-|-|
| $scope | Objet | Périmètre de l'objet de données mis à jour par la fonction de rappel. |
| table | Chaîne | Table surveillée. |
| filtre | Chaîne | Filtrez les champs à surveiller. |
| rappel | Fonction | Facultatif. Paramètre permettant de définir la fonction de rappel. |
[Tableau 25. Paramètres]

{#SPU-recordWatch_O_S_S_F__table_vys_mqz_31b} {#SPU-recordWatch_O_S_S_F__table_wys_mqz_31b__entry__2}

| Type | Description |
|-|-|
| Promesse | Valeur de retour de la fonction de rappel. |
[Tableau 26. Renvoie]

{#SPU-recordWatch_O_S_S_F__table_wys_mqz_31b}  

    //A simple recordWatch function.
    spUtil.recordWatch($scope, "live_profile", "sys_id=" + liveProfileId);

    //In a widget client script
    function(spUtil, $scope) {
      /* widget controller */
      var c =this;

      // Registers a listener on the incident table with the filter active=true, 
      // meaning that whenever something changes on that table with that filter, 
      // the callback function is executed.    
      // The callback function takes a single parameter 'response', which contains 
      // the property 'data'. The 'data' property contains information about the changed record. 
      spUtil.recordWatch($scope, "incident", "active=true", function(response) {
            
        // Returns the data inserted or updated on the table 
        console.log(response.data);   
        
        });
    }

## spUtil : refresh(objet $scope) {#ariaid-title15}

Appelle le serveur et remplace les options et données actuelles par la réponse du serveur.
L'appel de `spUtil.refresh()` est similaire à `l'appel de server.refresh().` Cependant, lorsque vous appelez `spUtil.refresh(),` vous pouvez définir l'objet $scope.
{#SPU-refresh_O__table_p2k_kqz_31b__entry__3}

| Nom | Type | Description |
|-|-|-|
| $scope | Objet | Champ d'application défini pour la mise à jour. |
[Tableau 27. Paramètres]

{#SPU-refresh_O__table_p2k_kqz_31b} {#SPU-refresh_O__table_q2k_kqz_31b__entry__2}

| Type | Description |
|-|-|
| Objet | Options et objets de données mis à jour. |
[Tableau 28. Renvoie]

{#SPU-refresh_O__table_q2k_kqz_31b}

## spUtil : scrollTo(Sélecteur de chaîne, nombre d'heures) {#ariaid-title16}

Défile jusqu'à l'élément avec le sélecteur spécifié, pendant une période de temps spécifiée.
{#SPU-scrollTo__table_drd_wzp_v2b__entry__3}

| Nom | Type | Description |
|-|-|-|
| sélecteur | Chaîne | Sélecteur vers lequel faire défiler. |
| Diagramme des séries chronologiques | Numéro | Temps nécessaire pour faire défiler jusqu'au sélecteur spécifié. Unité : Millisecondes |
[Tableau 29. Paramètres]

{#SPU-scrollTo__table_drd_wzp_v2b} {#SPU-scrollTo__table_erd_wzp_v2b__entry__2}

| Type | Description |
|-|-|
| nul |   |
[Tableau 30. Renvoie]

{#SPU-scrollTo__table_erd_wzp_v2b}

## spUtil : setBreadCrumb(Object $scope, Tableau de fils d'Ariane) {#ariaid-title17}

Met à jour le fil d'Ariane de l'en-tête.
{#SPU-setBreadCrumb__table_sqx_jkr_v2b__entry__3}

| Nom | Type | Description |
|-|-|-|
| $scope | Objet | Champ d'application défini pour la table. |
| Fils d'Ariane | Tableau | Conditions utilisées pour créer le filtre de fils d'Ariane. |
[Tableau 31. Paramètres]

{#SPU-setBreadCrumb__table_sqx_jkr_v2b} {#SPU-setBreadCrumb__table_tqx_jkr_v2b__entry__2}

| Type | Description |
|-|-|
| nul |   |
[Tableau 32. Renvoie]

{#SPU-setBreadCrumb__table_tqx_jkr_v2b}

## spUtil : setPreference(String pref, valeur de chaîne) {#ariaid-title18}

Définit une préférence utilisateur.
{#SPU-setPreference__table_m1m_1hl_w2b__entry__3}

| Nom | Type | Description |
|-|-|-|
| Pref | Chaîne | Nom de la préférence |
| valide | Chaîne | Valeur de préférence |
[Tableau 33. Paramètres]

{#SPU-setPreference__table_m1m_1hl_w2b} {#SPU-setPreference__table_n1m_1hl_w2b__entry__2}

| Type | Description |
|-|-|
| nul |   |
[Tableau 34. Renvoie]

{#SPU-setPreference__table_n1m_1hl_w2b}

## spUtil : setSearchPage(String searchPage) {#ariaid-title19}

Met à jour la page de recherche.
{#SPU-setSearchPage__table_hm4_v4l_w2b__entry__3}

| Nom | Type | Description |
|-|-|-|
| searchPage | Chaîne | Nom de la page de recherche. |
[Tableau 35. Paramètres]

{#SPU-setSearchPage__table_hm4_v4l_w2b} {#SPU-setSearchPage__table_im4_v4l_w2b__entry__2}

| Type | Description |
|-|-|
| nul |   |
[Tableau 36. Renvoie]

{#SPU-setSearchPage__table_im4_v4l_w2b}

## spUtil : mettre à jour (objet $scope) {#ariaid-title20}

Met à jour l'objet de données sur le serveur dans un périmètre donné.
Cette méthode est similaire à `server.update(),` mais inclut un paramètre $scope qui définit le périmètre à transmettre.
{#SPU-update_O__table_hpd_4qz_31b__entry__3}

| Nom | Type | Description |
|-|-|-|
| $scope | Objet | Champ d'application défini pour la mise à jour. |
[Tableau 37. Paramètres]

{#SPU-update_O__table_hpd_4qz_31b} {#SPU-update_O__table_ipd_4qz_31b__entry__2}

| Type | Description |
|-|-|
| Objet | Objet de données mis à jour. |
[Tableau 38. Renvoie]

{#SPU-update_O__table_ipd_4qz_31b}  
L'exemple suivant inclut un widget P1 qui surveille les changements apportés au champ d'état et utilise un filtre pour surveiller tous les P1 actifs et laisser la fonction de rappel déterminer s'il faut actualiser les données. La data.changes propriété contient un tableau de tous les champs mis à jour. Si l'état d'un champ a changé, les données sont mises à jour dans le widget.

    var q = "priority=1^active=true^EQ";
    spUtil.recordWatch($scope, "incident", q, function(event, data) {
       if (data.changes.includes("state")) { // only update if state was updated.
          spUtil.update($scope);
       }
    });