Assistants : UI Builder

L’API d’assistance 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 disponible dans aucun autre script UI Builder, notamment :

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

helpers : helpers.modal.close(String modalId)

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

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é et déposé 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
Néant

Cet exemple montre la fermeture d’un modal 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 la fenêtre modale spécifiée 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é et déposé 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 de texte pour le modal.
options.contentFullWidth	Booléen	Marqueur indiquant si le remplissage horizontal autour du corps du modal doit être supprimé afin d’adapter un contenu plus large. Valeurs valides : true : supprimer le remplissage. false : ne pas retirer 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 Fullscreen Valeur par défaut : sm

Tableau 4. Renvoie

Type	Description
Néant

Cet exemple montre l’ouverture d’un modal avec un ID d’utilisateur qui se termine par alerte-modal.

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 pour 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 de la configuration de l’acheminement, sinon elles sont également ignorées. Pour plus d’informations sur les paramètres facultatifs, consultez Créer une page dans UI Builder.

Tableau 6. Renvoie

Type	Description
Néant

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 modifié de camel case à snake case, de sorte que selectedTabIndex devient selected-tab-index.

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

helpers - helpers.navigate.to(String route, Object fields, Object params, Boolean redirect, Boolean passiveNavigation, String targetRoute)

Permet de naviguer 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 respectifs sont observés.

Tableau 7. Paramètres

Nom	Type	Description
routage	Chaîne	Nom de l’itinéraire. Doit être une entrée valide des itinéraires de l’application UX (sys_ux_app_route.list). Cette valeur est répercutée dans l’URL, et l’URL est créée en fonction des valeurs de colonne route , 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 si la dernière entrée d’historique doit être supprimée 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 : true : 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 si la navigation en arrière-plan doit être effectuée. 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, ouvrez un onglet inactif pour la page, mais il n’est pas visible mais chargé en arrière-plan. Valeurs valides : true : 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	Navigation secondaire vers une exploration vers le bas, un lien profond ou un sous-onglet. Si la valeur est définie sur actuelle, 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 « actuelle » ou d’un objet, tel qu’unenavigation NAV_ITEM_SELECTED une charge utile.

Tableau 8. Renvoie

Type	Description
Néant

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 accéder à une page en transmettant 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 le titre, l’icône, l’état erroné, le message et les changements d’erreur.

Les mises à jour d’état sont signalées à WorkspaceChrome ou AppShell, quelle que soit la couche externe, et agissant 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 indiquant 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 valeurs suivantes : insérée, supprimée, enregistrée ou fermée. 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
Néant

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

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

Envoie une demande 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 par rapport à l’URL d’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 effectuées sur l’instance. Valeurs valides : true : 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 comme corps de la demande. S’applique 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 plus d’informations, consultez les exemples de code ci-dessous. Valeur 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" }
méthode.options	Chaîne	Facultatif. Méthode HTTP. Valeurs valides : DELETE GET CORRECTIF POST PUT Valeur 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" }
erreur.données	Réponse renvoyée par l’API HTTP. Type de données : défini par l’API REST
message d’erreur	Message décrivant l’erreur rencontrée lors de la tentative de traitement de la requête HTTP. Remarque : Ce paramètre n’est pas toujours renvoyé. Type de données : chaîne
erreur.options	Décrit la demande 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
état erreur.état	Code d’état d’erreur HTTP renvoyé, tel que 400, 405 ou 500. Type de données : nombre
erreur.texted’état	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. Réponse à la demande 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() à l’aide de 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 planifiée via un appel setInterval() préalable.

Tableau 13. Paramètres

Nom	Type	Description
timeoutId	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
Néant

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	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
Néant

Cet exemple de code montre comment terminer 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 la fonction spécifiée de manière répété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 passés à la fonction elle-même.

Tableau 17. Paramètres

Nom	Type	Description
Fn	Fonction	Fonction à exécuter de manière répétée.
Retard	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 comme premier argument. Tous les arguments supplémentaires sont passés à la fonction elle-même.

Tableau 19. Paramètres

Nom	Type	Description
Fn	Fonction	Fonction à exécuter.
Retard	Numéro	Durée du temps 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 un minuteur de 20 minutes. Vous pouvez associer cette fonction à un bouton Rappeler 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 la api - setState(String stateParam, n’importe quelle valeur) méthode pour lier la valeur traduite à d’autres champs de la page.

Remarque :

Vous pouvez appeler cette méthode à l’aide d’une promesse ou d’une méthode asynchrone 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 à incorporer 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);
}