assistants : Générateur d’IU

L’API des assistants fournit des fonctionnalités générales communes à tous les scripts de page, éliminant ainsi la nécessité d’écrire des scripts pour des fonctionnalités simples telles que l’ouverture et la fermeture d’un modal.

Cette API n’est disponible que pour les scripts de page, elle n’est pas disponible dans d’autres scripts UI Builder, notamment :

• Scripts des valeurs de propriété des composants
• Scripts de visibilité du composant
• Scripts de la charge utile de l’événement
• Includes de script client UX

helpers : helpers.modal.close(String modalId)

Ferme le modal spécifié sur la page actuelle.

Tableau 1. Paramètres

Nom	Type	Description
modalId	Chaîne	ID du composant modal du modal à fermer. Les ID de composants sont générés automatiquement lorsqu’un composant est glissé-déplacé sur l’étape Générateur d'IU . Vous pouvez localiser l’ID sur la page de la propriété.

Tableau 2. Renvoie

Type	Description
Aucun

Cet exemple montre la fermeture d’une fenêtre modale avec un ID de composant qui se termine par alert-modal.

function handler({api, event, imports, helpers}) {
  helpers.modal.close("[component-id$='alert_modal']")
}

helpers - helpers.modal.open(String modalId, options de l’objet)

Ouvre le modal spécifié sur la page actuelle.

Vous ne pouvez afficher qu’un seul modal à la fois dans une page. Si un modal est actuellement ouvert et que vous appelez cette méthode, le modal existant est masqué et le nouveau modal apparaît.

Tableau 3. Paramètres

Nom	Type	Description
modalId	Chaîne	ID du composant du modal à ouvrir. Les ID de composants sont générés automatiquement lorsqu’un composant est glissé-déplacé sur l’étape Générateur d'IU . Vous pouvez localiser l’ID sur la page de la propriété.
options	Objet	Facultatif. "options": { "content": "String", "contentFullWidth": Boolean, "headerLabel": "String", "size": "String" }
options.contenu	Chaîne	Contenu textuel pour le modal.
options.contentFullWidth	Booléen	Marqueur indiquant s’il faut supprimer le remplissage horizontal autour du corps du modal afin de s’adapter à un contenu plus large. Valeurs valides : true : supprimer le remplissage. false : Ne retirez pas le remplissage. Valeur par défaut : false
options.headerLabel	Chaîne	Contenu de texte pour l’en-tête modal.
options.taille	Chaîne	Taille du conteneur modal. La plupart des tailles s’agrandissent automatiquement pour remplir la fenêtre lorsque la taille de l’écran est petite. Valeurs valides : sm md lg Plein écran Par défaut : sm

Tableau 4. Renvoie

Type	Description
Aucun

Cet exemple montre l’ouverture d’une fenêtre modale avec un ID d’élément qui se termine par alerte-modale.

function handler({api, event, imports, helpers}) {
  helpers.modal.open("[component-id$='alert_modal']")
}

helpers : helpers.navigate.setRouteParams(Object params)

Transmet les paramètres spécifiés à d’autres composants sur la même page.

Utilisez cette méthode dans n’importe quel composant de page qui souhaite ajouter un paramètre dans une URL. Vous pouvez ajouter un paramètre à une URL lorsqu’un autre composant a besoin de connaître la valeur actuelle de ce paramètre lorsqu’il change, afin de pouvoir y réagir. Par exemple, utilisez cette méthode pour transmettre le selectedIndex d’un composant d’onglet afin qu’il soit reflété dans l’URL afin de donner le focus à cet onglet.

Tableau 5. Paramètres

Nom	Type	Description
paramètres	Objet	Paires clé-valeur de paramètres facultatifs à transmettre à d’autres composants. Il doit s’agir d’un objet simple et plat avec uniquement des valeurs primitives. Les références de tableau ou d’objet sont ignorées et ne sont pas ajoutées à l’URL. Toutes les clés spécifiées doivent faire partie des paramètres facultatifs dans la configuration de l’itinéraire ou elles sont également ignorées. Pour plus d’informations sur les paramètres facultatifs, voir Créer une page dans le générateur d’IU.

Tableau 6. Renvoie

Type	Description
Aucun

Cet exemple de code montre comment ajouter l’URL params/selected-tab-index/2. Notez que le paramètre dans l’URL réelle est changé de camel case à snake case, donc selectedTabIndex devient selected-tab-index.

function handler({api, event, helpers, imports}) {  
  helpers.navigate.setRouteParams({'params': {'selectedTabIndex':  2}});  
} 

helpers : helpers.navigate.to(itinéraire de chaîne, champs d’objet, paramètres d’objet, redirection booléenne, passifnavigation booléenne, chaîne targetRoute)

Navigue d’un écran à l’autre en fonction de l’itinéraire spécifié et des informations de champ. Les changements d’URL et les chargements d’écran correspondants sont observés.

Tableau 7. Paramètres

Nom	Type	Description
acheminement	Chaîne	Nom de l’itinéraire. Doit être une entrée valide de UX App Routes (sys_ux_app_route.list). Cette valeur est reflétée dans l’URL, et l’URL est créée en fonction des valeurs des route colonnes , fields, et optionalParams : /<route>/<field1Value>/{<field2Value>/params/<optionalParamKey1>/<optionalParamValue1>/<optionalParamKey2>/<optionalParamValue2> Par exemple : /record/incident/12345/params/selectedTabIndex/4
champs	Objet	Facultatif. Paires clé-valeur des paramètres requis. Par exemple : 'fields' : {'table' : 'incident', 'sysId' : '12345'}.
paramètres	Objet	Facultatif. Paires clé-valeur de paramètres facultatifs. Par exemple : 'params' : {'selectedTabIndex' : 4}.
Redirection	Booléen	Marqueur indiquant s’il faut supprimer la dernière entrée d’historique de l’historique du navigateur. Par exemple, si vous accédez aux sites A, B, puis C. Si redirect la valeur est définie sur vrai lors de la navigation vers C, l’entrée d’historique pour B est supprimée. L’historique du navigateur n’affiche que A et C. Valeurs valides : vrai : supprime la dernière entrée d’historique et redirige vers la dernière URL. false : ne supprime aucune entrée d’historique. Valeur par défaut : false
passiveNavigation	Booléen	Marqueur indiquant s’il faut effectuer une navigation en arrière-plan. La navigation en arrière-plan se produit lorsqu’une page est ouverte, mais qu’elle n’est pas active ou affichée. Par exemple, l’ouverture d’un onglet inactif pour la page, mais il n’est pas visible mais chargé en arrière-plan. Valeurs valides : vrai : permet d’effectuer une navigation en arrière-plan. false : n’effectuez pas de navigation en arrière-plan. Valeur par défaut : false
targetRoute	Chaîne ou objet	Sous-navigation vers une exploration vers le bas, un lien profond ou un sous-onglet. S’il est défini sur actuel, l’itinéraire actuel effectue une sous-navigation sous l’URL actuelle. Par exemple, si /record/incident/123 est l’URL actuelle et que l’appel suivant est effectué : helper.navigate.to('record', {'table' : 'problem', 'sysId' : '567'}, {}, false, false, 'current') ; L’URL suivante est générée : /record/incident/123/sub/record/problem/567 Remarque : targetRoute Il peut s’agir d’une chaîne telle que « current » ou d’un objet, tel que la navigation NAV_ITEM_SELECTED la charge utile.

Tableau 8. Renvoie

Type	Description
Aucun

Cet exemple montre comment accéder à une page en passant uniquement le route paramètre.

function handler({api, event, imports, helpers}) {
  helpers.navigate.to('test');
}

Cet exemple montre comment naviguer vers une page en passant les route paramètres and fields .

function handler({api, event, imports, helpers}) {
  helpers.navigate.to('test', {'key': 'value'});
}

Cet exemple montre comment naviguer vers une page en passant les routeparamètres , fields, et params .

function handler({api, event, helpers, imports}) {
  helpers.navigate.to('test', {'key': 'value'}, {'first': 'FirstName', 'last': 'Last Name'});
}

helpers : helpers.screen.updateStatus(Object statusObj)

Permet aux pages de signaler leurs mises à jour d’état, telles que les changements de titre, d’icône, d’état erroné, de message et d’erreur.

Les mises à jour d’état sont signalées à WorkspaceChrome ou AppShell, quelle que soit la couche externe, et agissent en tant qu’hôte.

Tableau 9. Paramètres

Nom	Type	Description
statusObj	Objet	Charge utile à envoyer à la page actuelle pour signaler que le contenu a été mis à jour. Valeurs valides : dirtyModalId: (Chaîne) ID du modal qui a changé. hasError: (booléen) Marqueur qui indique qu’il y a des erreurs sur la page. hasUpdate: (booléen) Marqueur qui indique que des mises à jour ont été apportées à la page. icon: (chaîne) nom de l’icône mise à jour ou nouvelle. isDirty: (booléen) Marqueur qui indique si la page est erronée (les valeurs ont changé). message: (Chaîne) Message mis à jour/nouveau. screenKey: (Chaîne) ID de l’écran sur lequel le changement s’est produit. Chaque écran a comme propriété sur screenKey le macroponent d’écran à l’intérieur de sn-canvas-screen. status: (Chaîne) opération d’état pour cette action. Cette valeur doit être l’une des suivantes : inséré, supprimé, enregistré ou fermé. title: (chaîne) Titre d’affichage mis à jour/nouveau. tooltipPreview: (JSON) Info-bulle mise à jour ou nouvelle. Par exemple, tooltipPreview : { primaryTitle, secondaryContent : {} }

Tableau 10. Renvoie

Type	Description
Aucun

screen.updateStatus({'dirtyModalId': 'customModalId', 'isDirty': true});

helpers - helpers.snHttp(String url, Object options)

Envoie une requête HTTP à l’instance ServiceNow et renvoie une promesse avec les résultats.

Remarque :

Il existe un problème connu où les objets nommés options sont omis de la réponse HTTP.

{
  options: {},
  otherFields: {}
}

becomes

{
  otherFields: {}
}

Tableau 11. Paramètres

Nom	Type	Description
URL	Chaîne	Point de terminaison HTTP relatif à l’URL de l’instance. Par exemple, /api/now/table/incident ou /api/now/table/incident/a83820b58f723300e7e16c7827bdeed.
options	Objet	Décrit le contenu de la requête HTTP. "options": { "batch": Boolean, "body": {Object}, "headers": {Object}, "method": "String" }
options.batch	Booléen	Facultatif. Marqueur indiquant si cette demande HTTP doit être regroupée avec d’autres requêtes HTTP adressées à l’instance. Valeurs valides : vrai : effectuer une demande dans le cadre d’une demande par lots. false : effectuer une demande dédiée. Valeur par défaut : true
options.corps	Objet	Facultatif. Données à envoyer en tant que corps de la demande. Applicable uniquement aux méthodes de demande PUT, POST et PATCH. Les éléments de l’objet dépendent du type de méthode HTTP. Pour en savoir plus, reportez-vous aux exemples de code ci-dessous. Par défaut : {}
options.en-têtes	Objet	Facultatif. En-têtes de demande HTTP supplémentaires. Par exemple : headers: { "Content-Type": "application/json", "Accept": "application/xml" }
options.méthode	Chaîne	Facultatif. Méthode HTTP. Valeurs valides : SUPPRIMER GET CORRECTIF POST PUT Par défaut : GET

Tableau 12. Renvoie

Type	Description
erreur	Objet qui décrit toute erreur renvoyée par l’API REST. Type de données : objet "error": { "data": "String", "message": "String", "options": {Object}, "status": Number, "statusText": "String" }
données.erreur	Réponse renvoyée par l’API HTTP. Type de données : défini par l’API REST
message.erreur	Message décrivant l’erreur rencontrée lors de la tentative de traitement de la demande HTTP. Remarque : Ce paramètre n’est pas toujours renvoyé. Type de données : chaîne
options.erreurs	Décrit la requête HTTP d’origine. Type de données : objet "options": { "headers": {Object}, "responseHeader": {Object} }
erreur.options.en-têtes	Objet contenant une liste de tous les en-têtes de demande envoyés dans la demande. Type de données : objet
error.options.responseHeaders	Objet contenant une liste de tous les en-têtes de réponse envoyés dans la demande. Type de données : objet
erreur.état	Code d’état d’erreur HTTP renvoyé, tel que 400, 405 ou 500. Type de données : nombre
error.statusText	Message d’état HTTP renvoyé, tel que Demande incorrecte. Type de données : chaîne
réponse	Renvoyé lorsque la requête HTTP réussit. La réponse à la requête HTTP. Type de données : N’importe lequel

L’exemple suivant montre comment appeler snHttp() qui retourne une promesse.

function handler({api, event, helpers, imports}) {
  helpers.snHttp('/api/now/table/u_movie', {method: 'GET'})
    .then(({response}) => {
      // do something with the table data
    })
    .catch(({error}) => {
      const message = `Error: ${error.data.error.message}`;
      console.error(message);
      api.emit('NOW_UXF_PAGE#ADD_NOTIFICATIONS', {
        id: 'alert5',
        status: 'high',
        icon: 'info-circle-outline',
        content: message,
        action: { type: 'dismiss' }
    });
  });
}

L’exemple suivant montre comment appeler snHttp() en utilisant async et await.

async function handler({helpers}) {
  try {
    const result = await helpers.snHttp('/api/now/table/u_movie', {method: 'GET'});
  } catch ({error}) {
      const message = `Error: ${error.data.error.message}`;
      console.error(message);
      api.emit('NOW_UXF_PAGE#ADD_NOTIFICATIONS', {
        id: 'alert5',
        status: 'high',
        icon: 'info-circle-outline',
        content: message,
        action: { type: 'dismiss' }
      });
  }
}

L’exemple suivant montre comment configurer une requête POST.

function handler({api, helpers, event, imports}) {
  helpers
    .snHttp("/api/now/table/incident", {
      method: "POST",
      body: {
        description: "Sample description",
        close_notes: "Sample close notes",
        order: "-1"
      }
    })
    .then(({ response }) => {
      // handle POST request response
    })
    .catch(({ error }) => {
      // handle POST request errors
    });
}

L’exemple suivant montre comment configurer une requête PUT.

function handler({api, helpers, event, imports}) {
  helpers
    .snHttp("/api/now/table/incident/a83820b58f723300e7e16c7827bdeed2", {
      method: "PUT",
      body: {
        activity_due: "1970-04-02 18:26:17"
      },
      headers: {
        "Content-Type": "application/json",
        "Accept": "application/xml"
      }
    })
    .then(({ response }) => {
      // handle PUT request response
    })
    .catch(({ error }) => {
      // handle PUT request errors
    });
}

helpers : helpers.timing.clearInterval(Number timeoutId)

Annule l’exécution de la fonction qui a été planifiée via un appel setInterval () précédent.

Tableau 13. Paramètres

Nom	Type	Description
timeoutId (en anglais seulement)	Numéro	Identificateur unique de la fonction planifiée à effacer. Cette valeur est renvoyée par l’appel setInterval() correspondant.

Tableau 14. Renvoie

Type	Description
Aucun

Cet exemple montre l’utilisation de clearInterval() pour annuler une opération de synchronisation qui a été précédemment définie à l’aide de la méthodesetInterval(). Cette fonction peut être invoquée par un utilisateur qui clique sur un bouton Désactiver l’actualisation automatique sur une page.

function handler({api, helpers}) {
  api.setState('intervalId', ({currentValue}) => {
    if (currentValue > -1) {
      helpers.timing.clearInterval(currentValue);
    }
    return -1;
  });
}

helpers : helpers.timing.clearTimeout(Number timeoutId)

Annule l’exécution de la fonction planifiée via un appel setTimeout() précédent.

Tableau 15. Paramètres

Nom	Type	Description
timeoutId (en anglais seulement)	Numéro	Identificateur unique de la fonction planifiée à effacer. Cette valeur est renvoyée par l’appel setTimeout() correspondant.

Tableau 16. Renvoie

Type	Description
Aucun

Cet exemple de code montre comment arrêter un minuteur avec le timeoutId spécifié.

function handler({api, helpers}) {
  api.setState('timeoutId', ({currentValue}) => {
    if (currentValue > -1) {
      helpers.timing.clearTimeout(currentValue);
    }
    return -1;
  });
}

helpers : helpers.timing.setInterval(Function fn, Number delay)

Exécute de manière répétée la fonction spécifiée, en utilisant la valeur de délai spécifiée comme intervalle entre les appels de fonction.

Contrairement à la méthode JavaScript native setInterval(), cette méthode ne prend pas en charge le passage d’une chaîne de code à évaluer en tant que premier argument. Tous les arguments supplémentaires sont transmis à la fonction elle-même.

Tableau 17. Paramètres

Nom	Type	Description
Fn	Fonction	Fonction à exécuter de manière répétée.
retarder	Numéro	Durée de l’intervalle de temps entre chaque exécution de fonction. Unité : Millisecondes

Tableau 18. Renvoie

Type	Description
Numéro	Identificateur unique de l’opération d’exécution de la fonction. Utilisez cette valeur dans la helpers : helpers.timing.clearInterval(Number timeoutId) méthode si vous devez annuler cette opération.

Cet exemple de code montre comment actualiser l’horodatage d’une page toutes les secondes. Cette fonction peut être invoquée par un utilisateur qui clique sur un bouton Activer l’actualisation automatique sur une page.

function handler({api, helpers}) {
  // Every one second, refresh the value of current timestamp client state parameter
  const intervalId = helpers.timing.setInterval(() => {
    api.setState('currentTimestamp', new Date().toString())
  }, 1000);

  // The interval ID is kept in state to use when calling the helpers.timing.clearInterval() method at a later point
  api.setState('intervalId', intervalId);
}

helpers - helpers.timing.setTimeout(Function fn, Number delay)

Exécute la fonction spécifiée après le délai spécifié.

Contrairement à la méthode JavaScript native setTimeout(), cette méthode ne prend pas en charge le passage d’une chaîne de code à évaluer en tant que premier argument. Tous les arguments supplémentaires sont transmis à la fonction elle-même.

Tableau 19. Paramètres

Nom	Type	Description
Fn	Fonction	Fonction à exécuter.
retarder	Numéro	Durée d’attente avant d’appeler la fonction spécifiée. Unité : Millisecondes

Tableau 20. Renvoie

Type	Description
Numéro	Identificateur unique de l’opération d’exécution de la fonction. Utilisez cette valeur dans la helpers : helpers.timing.clearTimeout(Number timeoutId) méthode si vous devez annuler cette opération.

Cet exemple de code montre comment définir une minuterie de 20 minutes. Vous pouvez associer cette fonction à un bouton Rappelez-moi dans 20 minutes.

function handler({api, helpers}) {
  const timeoutId = helpers.timing.setTimeout(() => {
    api.emit('NOW_UXF_PAGE#ADD_NOTIFICATIONS', {
      id: 'alert5',
      status: 'high',
      icon: 'info-circle-outline',
      content: 'Try to look away at something that is 20 feet away from you for a total of 20 minutes.',
      action: { type: 'dismiss' }
    });
  }, 20 * 60 * 1000);

  // The timeout ID is kept in state to use when calling the helpers.timing.clearTimeout() method at a later point
  api.setState('timeoutId', timeoutId);
}

helpers - helpers.translate(message de chaîne, jetons de chaîne)

Récupère et traduit de façon asynchrone le message spécifié en fonction de la langue de la session de l’utilisateur actuel.

Vous pouvez utiliser cette méthode avec le api : setState(String, stateParam, n’importe quelle valeur) pour lier la valeur traduite à d’autres champs de la page.

Remarque :

Vous pouvez appeler cette méthode à l’aide d’une promesse ou async et attendre. Les exemples de code ci-dessous montrent les deux implémentations.

Tableau 21. Paramètres

Nom	Type	Description
message	Chaîne	Message à traduire.
Jetons	Chaîne	Facultatif. Liste de paramètres séparés par des virgules à utiliser pour remplacer les variables de chaîne. Par exemple : helpers.translate('Text {0} {1}', 'to', 'translate');

Tableau 22. Renvoie

Type	Description
Chaîne	Chaîne de texte traduite.

L’exemple suivant montre comment transmettre des références de champ de table à intégrer dans les variables correspondantes d’une chaîne, à l’aide d’une promesse.

function handler ({api, helpers}) {
  helpers.translate('Welcome {0} {1}!', user.firstName, user.lastName)
    .then((translatedText) => {
      api.setState('greeting', translatedText);
    });
}

L’exemple suivant montre comment utiliser async et await dans votre fonction au lieu d’une promesse.

async function handler ({api, helpers}) {
  const translatedText = await helpers.translate('Welcome to {0}', 'ServiceNow');
    api.setState('greeting', translatedText);
}