openFrameAPI - Client

  • Rversion finale: Washingtondc
  • Mis à jour 1 févr. 2024
  • 8 minutes de lecture

    • OpenFrame est un cadre omniprésent que les partenaires de communication peuvent utiliser pour intégrer leurs systèmes à la ServiceNow plate-forme.

    L’un des besoins de base est la capacité de connecter et de fournir du code provenant de différents domaines et pouvant se connecter de manière fluide aux sous-systèmes partenaires. Cette connexion inter-domaine est nécessaire pour maintenir les connexions et les rappels inscrits dans les systèmes de communication sans aucun problème inter-domaine.

    OpenFrame comporte deux parties importantes : une qui existe dans l’application ServiceNow (appelée TopFrame) et cette API, qui provient de l’application partenaire. Cette API possède les méthodes nécessaires pour communiquer avec TopFrame et contrôler les fonctionnalités visuelles d’OpenFrame.
    Remarque :
    Pour rester à jour vis-à-vis de la bibliothèque OpenFrame, utilisez la ressource URI suivante : https://[instance servicenow]/scripts/openframe/latest/openFrameAPI.min.js.

    openFrameAPI - hide()

    Masque l’OpenFrame dans le TopFrame.

    Tableau 1. Paramètres
    Nom Type Description
    Aucun
    Tableau 2. Renvoie
    Type Description
    nul 
    openFrameAPI.hide()

    openFrameAPI - init(configuration d’objet, fonction successCallback, fonction failureCallback)

    Initialiser OpenFrame doit être la première méthode appelée.

    Cette méthode initialise la communication vers TopFrame ainsi que tous les éléments visuels transmis dans le paramètre de configuration.

    Tableau 3. Paramètres
    Nom Type Description
    configuration Objet Un objet de paires de valeurs clés. Les clés peuvent être la hauteur, la largeur, le titre, le sous-titre et l’icône de titre. Toutes les clés sont facultatives.
    successCallback function La fonction de rappel utilisée si la méthode init réussit. La configuration openframe stockée dans le système est transmise comme paramètre de la fonction de rappel.
    failureCallback function La fonction de rappel utilisée si la méthode init échoue.
    Tableau 4. Renvoie
    Type Description
    nul 
    var config = {
height: 300,
width: 200
}
function handleCommunicationEvent(context) {
console.log("Communication from Topframe", context);
}
function initSuccess(snConfig) {
console.log("openframe configuration",snConfig);
//register for communication event from TopFrame
openFrameAPI.subscribe(openFrameAPI.EVENTS.COMMUNICATION_EVENT,
handleCommunicationEvent);
}
function initFailure(error) {
console.log("OpenFrame init failed..", error);
}
openFrameAPI.init(config, initSuccess, initFailure);

    openFrameAPI - isVisible(fonction de rappel)

    Vérifie si l’OpenFrame est visible dans le TopFrame.

    Tableau 5. Paramètres
    Nom Type Description
    rappel function La fonction de rappel reçoit un paramètre avec une valeur vrai ou faux. Vrai si OpenFrame est visible et faux si elle n’est pas visible.
    Tableau 6. Renvoie
    Type Description
    nul 
    function callback(isVisible) {
console.log(isVisible)
}
openFrameAPI.isVisible(callback)

    openFrameAPI - openCustomURL(détails de la chaîne)

    Ouvre une URL personnalisée dans l’interface UI16.

    Tableau 7. Paramètres
    Nom Type Description
    URL Chaîne Texte de l’URL personnalisée.

    Taille maximale : 2 083 caractères
    Tableau 8. Renvoie
    Type Description
    nul 
    openFrameAPI.openCustomURL('10_cool_things.do');

    openFrameAPI - openServiceNowForm(détails de l’objet)

    Ouvre une URL de formulaire.

    Lorsqu’un agent reçoit un appel entrant, la fenêtre OpenFrame affiche des informations telles que le compte, le contact ou le consommateur. Cliquer sur un lien dans la fenêtre OpenFrame affiche l’enregistrement correspondant.
    • Dans l’interface de la plateforme, cette API ouvre une URL de formulaire dans TopFrame.
    • Pour Espace de travail d'agent, cette API prend en charge la gestion de l’onglet d’interaction. Dans Espace de travail d'agent, un enregistrement d’interaction s’ouvre dans un onglet parent et l’enregistrement d’entité spécifié s’ouvre dans un onglet enfant sous l’onglet d’interaction.
    Tableau 9. Paramètres
    Nom Type Description
    Détails Objet Paires de valeurs clés qui identifient l’URL de formulaire à ouvrir. 
    "details": {
  "entity": "String";
  "interaction_sys_id": "String";
  "query": "String"
}
    details.entity Chaîne Nom de la table ou de l’entité.
    details.interaction_sys_id Chaîne Facultatif. Sys_id de l’enregistrement d’interaction à ouvrir en tant qu’onglet parent dans Espace de travail d'agent.
    Remarque :
    dans l’interface de la plateforme, le interaction_sys_id est ignoré.
    details.query Chaîne Requête pour identifier l’enregistrement à ouvrir, telle que : query:'sys_id=<record_sys_id>'.
    Tableau 10. Renvoie
    Type Description
    nul

    L’exemple suivant montre l’utilisation de base dans la plateforme :

    openFrameAPI.openServiceNowForm({entity:'customer_account', 
query:'sys_id=447832786f0331003b3c498f5d3ee452', 'interaction_sys_id':'3be092313b711300758ce9b534efc4dd'});

    L’exemple suivant montre comment utiliser le query paramètre pour créer un nouvel enregistrement avec les données fournies dans le formulaire à l’aide d’sysparm_query et d’une requête codée pour renseigner les champs Prénom et Nom de famille dans Workspace :

    openFrameAPI.openServiceNowForm({ entity: 'sys_user',
query: 'sys_id=-1&sysparm_query=first_name=Ivan^last_name=Greggor' });

    openFrameAPI : openServiceNowFormwithChildTabIf()

    Ouvre un ServiceNow formulaire avec un onglet enfant s’il est invoqué dans un espace de travail ou ouvre une entité s’il est invoqué dans l’interface UI16.

    Tableau 11. Paramètres
    Nom Type Description
    openServiceNowFormwithChildTab Objet Définit si l’API ouvre un ServiceNow formulaire avec un onglet enfant si elle est invoquée dans un espace de travail ou ouvre une entité si elle est invoquée dans l’interface UI16.
    openFrameAPI.openServiceNowFormwithChildTablf({
	entity: “String”,
	sys_id: “String”, 	
	parent_entity: “String”,	
	parent_entity_sys_id: “String”,
    openServiceNowFormwithChildTab.entity Chaîne Nom de la table.
    openServiceNowFormwithChildTab.sys_id Chaîne Sys_id de l’enregistrement à ouvrir.
    openServiceNowFormwithChildTab.parent_entity Chaîne Nom de la table à ouvrir en tant qu’onglet parent.
    openServiceNowFormwithChildTab.parent_entity_sys_id Chaîne Sys_id de l’enregistrement parent à ouvrir.
    Tableau 12. Renvoie
    Type Description
    Néant

    L’exemple suivant ouvre l’entité parente en tant qu’onglet parent sur un espace de travail configuré, ou ouvre uniquement l’entité si elle est invoquée dans UI16.

    openFrameAPI.openServiceNowFormwithChildTablf({
	entity: “customer_account”, 
	sys_id: “447832786f0331003b3c498f5d3ee452”, 	
	parent_entity: “interaction”, 
	parent_entity_sys_id: “3be092313b711300758ce9b534efc4dd”
});

    openFrameAPI - openServiceNowList(détails de l’objet)

    Ouvre une liste d’URL dans l’interface UI16.

    Tableau 13. Paramètres
    Nom Type Description
    Détails Objet Paires de valeurs clés qui décrivent le contenu à utiliser lors de l’ouverture de l’URL de la liste.

    Valeurs valides :
    Tableau 14. Renvoie
    Type Description
    nul 
    openFrameAPI.openServiceNowList({entity:'case', query:'active=true'});

    openFrameAPI - setFrameMode(mode)

    Définit le mode de l’OpenFrame.

    Le mode passé dans cette API :
    • définit l’icône appropriée dans l’en-tête : réduire ou développer
    • déclenche l’événement pertinent pour le CTI :
      • openFrameAPI.EVENTS.COLLAPSE
      • openFrameAPI.EVENTS.EXPAND
    Tableau 15. Paramètres
    Nom Type Description
    Mode Chaîne Définissez le mode de l’OpenFrame. Options énumérées :
    1. openFrameAPI.FRAME_MODE.COLLAPSE
    2. openFrameAPI.FRAME_MODE.EXPAND
    Tableau 16. Renvoie
    Type Description
    nul 
    openFrameAPI.setFrameMode(openFrameAPI.FRAME_MODE.COLLAPSE);

    openFrameAPI - setHeight(hauteur)

    Définit la hauteur de l’OpenFrame.

    Tableau 17. Paramètres
    Nom Type Description
    Hauteur Numéro Hauteur en pixels
    Tableau 18. Renvoie
    Type Description
    nul 
    openFrameAPI.setHeight(100);

    openFrameAPI - setIcons(icônes de tableau)

    Définit les icônes dans l’en-tête OpenFrame qui sont placées à côté de l’icône de fermeture.

    Tableau 19. Paramètres
    Nom Type Description
    icônes Tableau d’objets Une liste de configurations d’icônes, où chaque configuration d’icône est un objet avec des valeurs imageURLclés , imageTitle, et tout autre contexte nécessaire.

    Taille maximale : les icônes peuvent avoir un maximum de 16x16 pixels. Les images plus grandes sont automatiquement ajustées à ce maximum.
    Tableau 20. Renvoie
    Type Description
    nul 
    openFrameAPI.setIcons([{imageURL:'https://mydomian.com/image/mute.png',
imageTitle:'mute', id:101}, {imageURL:'https://mydomian.com/image/hold.png',
imageTitle:'hold', id:102}]);

    openFrameAPI - setPresenceIndicator(présence)

    Définit l’indicateur de présence pour qu’il affiche la disponibilité de l’agent dans un espace de travail.

    Pour plus d’informations sur la configuration d’OpenFrame, consultez Créer une configuration OpenFrame

    Tableau 21. Paramètres
    Nom Type Description
    État Chaîne État de présence de l’agent.

    États par défaut :

    • Disponible
    • Absent
    • Hors ligne

    Vous pouvez également indiquer des états personnalisés.
    couleur Chaîne Couleur de l’indicateur de présence dans l’espace de travail.

    Couleurs prises en charge :

    • rouge
    • orange
    • gris
    • vert
    Tableau 22. Renvoie
    Type Description
    nul 
    openframeAPI.setPresenceIndicator('Available', 'green');

    openFrameAPI - setSize(largeur en nombre, hauteur en nombre)

    Définit la taille de l’OpenFrame.

    Tableau 23. Paramètres
    Nom Type Description
    largeur Numéro Doit avoir une valeur supérieure à zéro.
    hauteur Numéro Doit avoir une valeur supérieure à zéro.
    Tableau 24. Renvoie
    Type Description
    nul 
    openFrameAPI.setSize(300, 370);

    openFrameAPI - setSubtitle(sous-titre de la chaîne)

    Définit le sous-titre d’OpenFrame.

    Tableau 25. Paramètres
    Nom Type Description
    sous-titre Chaîne Une chaîne de 256 caractères ou moins.
    Tableau 26. Renvoie
    Type Description
    nul 
    openFrameAPI.setSubtitle('+18888888888');

    openFrameAPI - setTitle(titre de la chaîne)

    Définit le titre de l’OpenFrame.

    Tableau 27. Paramètres
    Nom Type Description
    Titre Chaîne Une chaîne de 256 caractères ou moins.
    Tableau 28. Renvoie
    Type Description
    nul 
    openFrameAPI.setTitle('Incoming Call');

    openFrameAPI - setTitleIcon(icône d’objet)

    Définit l’icône de titre d’OpenFrame.

    Tableau 29. Paramètres
    Nom Type Description
    icône Objet Objet de paires de valeurs clés. Les clés incluent imageURL, imageTitle, et tout autre contexte nécessaire.

    Taille maximale : les icônes peuvent avoir un maximum de 16x16 pixels. Les images plus grandes sont automatiquement ajustées à ce maximum.
    Tableau 30. Renvoie
    Type Description
    nul 
    openFrameAPI.setTitleIcon({imageURL:'/my/image/path.png', imageTitle:'mute', id:101});
    openFrameAPI.setTitleIcon({imageURL:'https://mydomian.com/image/path.png',
imageTitle:'mute', id:101});

    openFrameAPI - setWidth(largeur)

    Définit la largeur de l’OpenFrame.

    Tableau 31. Paramètres
    Nom Type Description
    Largeur Numéro Largeur en pixels
    Tableau 32. Renvoie
    Type Description
    nul 
    openFrameAPI.setWidth(100);

    openFrameAPI - show()

    Rend l’OpenFrame visible dans le TopFrame.

    Tableau 33. Paramètres
    Nom Type Description
    Aucun
    Tableau 34. Renvoie
    Type Description
    nul 
    openFrameAPI.show()

    openFrameAPI - subscribe(événement openFrameAPIEVENT, fonction eventCallback)

    S’abonne à l’événement.

    Tableau 35. Paramètres
    Nom Type Description
    event openFrameAPIEVENT L’un des événements suivants :
    • openframe_agent_off_interaction : indique la présence d’un agent sur la messagerie instantanée comme étant désactivée ou disponible.
    • openframe_awa_agent_presence : dans Affectation de travail avancée (AWA), cet événement se produit lors d’un changement dans l’état de présence de l’agent. Les développeurs du couplage téléphonie-informatique (CTI) peuvent s’abonner à cet événement pour recevoir les changements d’état de présence.
    • openframe_awa_workitem_accepted : se produit lorsqu’un élément de travail est accepté par un agent.
    • openframe_awa_workitem_offered : se produit lorsqu’un élément de travail est proposé à un agent.
    • openframe_awa_workitem_rejected : se produit lorsqu’un élément de travail est rejeté par un agent.
    • openframe_before_destroy : se produit avant le déchargement du TopFrame.
    • openframe_collapse : se produit lorsque l’icône réduire est sélectionnée dans l’en-tête de l’OpenFrame.
    • openframe_communication : spécifique à l’application et peut être personnalisé.
    • openframe_communication_failure : se produit lorsque la communication vers TopFrame échoue.
    • openframe_expand : se produit lorsque l’icône développer est sélectionnée dans l’en-tête de l’OpenFrame.
    • openframe_header_icon_clicked : déconseillé. Utilisez openframe_icon_clicked ou openframe_title_icon_clicked à la place.
    • openframe_hidden : se produit lorsque la fenêtre OpenFrame est masquée.
    • openframe_icon_clicked : se produit lorsqu’une icône différente de l’icône de fermeture est sélectionnée dans le pied de page d’OpenFrame. Le rappel reçoit l’objet d’icône comme un paramètre.
    • openframe_shown : se produit lorsque la fenêtre OpenFrame est affichée.
    • openframe_title_icon_clicked : se produit lorsque l’icône de titre est sélectionnée dans OpenFrame. Le rappel reçoit l’objet d’icône de titre comme un paramètre.
    eventCallback function Fonction appelée lorsque l’événement spécifié se produit.
    Tableau 36. Renvoie
    Type Description
    Aucun sauf indications contraires. La plupart des abonnements d’événements n’ont pas de valeurs de retour, à l’exception des suivants :
    Dans AWA, l’événement openframe_awa_agent_presence renvoie l’objet de présence :
    • presence : Informations sur l’état et le canal de présence actuels d’un agent. exemple de sortie ci-dessous.
    • presence.name : Nom de l’état de présence de l’agent.
    • presence.sys_id : État de présence sys_id. Situé dans la table États de présence [awa_presence_state].
    • presence.available : Marqueur indiquant si l’agent est disponible.
    • presence.channels : Liste d’objets qui décrivent les canaux de communication disponibles avec l’agent.
    • presence.channels.name : Nom du canal, par exemple Messagerie instantanée ou Téléphone.
    • presence.channels.available : Marqueur indiquant si le canal est disponible.
    • presence.channels.sys_id : sys_id de canal. Situé dans la table Canaux de service [awa_service_channel].
    • presence.channels.restrict_update : Marqueur indiquant si l’utilisateur peut restreindre les mises à jour.

    Exemple

    function handleIconClick(context) {
console.log("Icon was clicked", context);
}
openFrameAPI.subscribe(openFrameAPI.events.openframe_awa_agent_presence, handleIconClick);

    Sortie

    // Sample presence object output
// openframe_awa_agent_presence event only

{
   "result":{
      "presence":{
         "name":"Available",
         "sys_id":"<SysID>",
         "available":true,
         "channels":[
            {
               "name":"Chat",
               "available":true,
               "sys_id":"<SysID>",
               "restrict_update":false
            },
            {
               "name":"Phone",
               "available":true,
               "sys_id":"<SysID>",
               "restrict_update":false
            }
         ]
      }
   }
}

    openFrameAPI - version()

    Renvoie la version de l’API OpenFrame.

    Tableau 37. Paramètres
    Nom Type Description
    Aucun
    Tableau 38. Renvoie
    Type Description
    Chaîne La version de l’API OpenFrame 
    var version = openFrameAPI.version();

console.log("API version " + version);