openFrameAPI – Client

  • Freigeben Version: Washingtondc
  • Aktualisiert 1. Februar 2024
  • 7 Minuten Lesedauer

    • OpenFrame ist ein häufiger Frame, mit dem Kommunikationspartner ihre Systeme in die ServiceNow-Plattform integrieren können.

    Eine der Hauptanforderungen ist die Fähigkeit, Code aus verschiedenen Domänen zu verbinden und bereitzustellen, die sich nahtlos mit Partner-Subsystemen verbinden können. Diese domänenübergreifende Verbindung ist erforderlich, um Verbindungen und Rückrufe in Kommunikationssystemen ohne domänenübergreifende Probleme zu registrieren.

    OpenFrame hat zwei wesentliche Teile: einen in der ServiceNow-Anwendung (als TopFrame bezeichnet) und diese API, die von der Partneranwendung bezogen wird. Diese API verfügt über die erforderlichen Methoden, um mit TopFrame zu kommunizieren und die visuellen Funktionen von OpenFrame zu steuern.
    Hinweis:
    Um in Bezug auf die OpenFrame-Bibliothek aktuell zu bleiben, verwenden Sie den folgenden Ressourcen-URI: https://[servicenow-Instanz]/scripts/openframe/latest/openFrameAPI.min.js.

    openFrameAPI – hide()

    Blendet den OpenFrame im TopFrame aus.

    Tabelle : 1. Parameter
    Name Typ Beschreibung
    Keine
    Tabelle : 2. Ergebnisse
    Typ Beschreibung
    void 
    openFrameAPI.hide()

    openFrameAPI – init(Object config, function successCallback, function failureCallback)

    Initialisieren von OpenFrame, muss die erste aufgerufene Methode sein.

    Diese Methode initialisiert die Kommunikation mit TopFrame und alle visuellen Elemente, die im config-Parameter übergeben werden.

    Tabelle : 3. Parameter
    Name Typ Beschreibung
    Konfiguration Objekt Ein Objekt von Schlüssel-Wert-Paaren. Die möglichen Schlüssel sind „height“, „width“, „title“, „subTitle“ und „titleIcon“. Alle Schlüssel sind optional.
    successCallback function Die Callback-Funktion wird verwendet, wenn die init-Methode erfolgreich ist. Die im System gespeicherte OpenFrame-Konfiguration wird als Parameter an die Callback-Funktion übergeben.
    failureCallback function Die Callback-Funktion wird verwendet, wenn die init-Methode fehlschlägt.
    Tabelle : 4. Ergebnisse
    Typ Beschreibung
    void 
    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(function callback)

    Überprüft, ob der OpenFrame im TopFrame sichtbar ist.

    Tabelle : 5. Parameter
    Name Typ Beschreibung
    callback function Die Callback-Funktion empfängt einen Parameter mit dem Wert „true“ oder „false“. „True“, wenn OpenFrame sichtbar ist, und „false“, wenn nicht sichtbar.
    Tabelle : 6. Ergebnisse
    Typ Beschreibung
    void 
    function callback(isVisible) {
console.log(isVisible)
}
openFrameAPI.isVisible(callback)

    openFrameAPI - openCustomURL(String details)

    Öffnet eine benutzerdefinierte URL in der UI16-Schnittstelle.

    Tabelle : 7. Parameter
    Name Typ Beschreibung
    URL Zeichenfolge Text der benutzerdefinierten URL.

    Maximale Größe: 2083 Zeichen
    Tabelle : 8. Ergebnisse
    Typ Beschreibung
    void 
    openFrameAPI.openCustomURL('10_cool_things.do');

    openFrameAPI – openServiceNowForm(Object details)

    Öffnet eine Formular-URL.

    Wenn ein Agent einen eingehenden Anruf erhält, werden im OpenFrame-Fenster Informationen wie Account, Kontakt oder Verbraucher angezeigt. Durch Klicken auf einen Link im OpenFrame-Fenster wird der entsprechende Datensatz angezeigt.
    • In der Plattform-Schnittstelle öffnet diese API eine Formular-URL im TopFrame.
    • Für Mitarbeiterbereich unterstützt diese API die Verwaltung der Interaktionsregisterkarte. In Mitarbeiterbereich wird ein Interaktionsdatensatz auf einer übergeordneten Registerkarte geöffnet, und der angegebene Entitätsdatensatz wird auf einer untergeordneten Registerkarte unter der Interaktionsregisterkarte geöffnet.
    Tabelle : 9. Parameter
    Name Typ Beschreibung
    details Objekt Schlüssel-Wert-Paare, die die zu öffnende Formular-URL identifizieren. 
    "details": {
  "entity": "String";
  "interaction_sys_id": "String";
  "query": "String"
}
    details.entity Zeichenfolge Tabellen- oder Entitätsname.
    details.interaction_sys_id Zeichenfolge Optional. Sys_id des Interaktionsdatensatzes, der als übergeordnete Registerkarte in Mitarbeiterbereichgeöffnet werden soll.
    Hinweis:
    In der Plattform-Schnittstelle wird interaction_sys_id ignoriert.
    details.query Zeichenfolge Abfrage, um den zu öffnenden Datensatz zu identifizieren, z. B.: query:'sys_id=<record_sys_id>'.
    Tabelle : 10. Ergebnisse
    Typ Beschreibung
    void

    Das folgende Beispiel zeigt die grundlegende Verwendung in Plattform:

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

    Das folgende Beispiel zeigt, wie Sie den Parameter query verwenden, um einen neuen Datensatz mit Daten zu erstellen, die im Formular bereitgestellt werden, indem sysparm_query und eine codierte Abfrage zum Ausfüllen der Felder für Vor- und Nachname im Arbeitsbereich verwendet werden:

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

    openFrameAPI – openServiceNowFormwithChildTabIf()

    Öffnet ein Formular ServiceNow mit einer untergeordneten Registerkarte, wenn es in einem Arbeitsbereich aufgerufen wird, oder öffnet eine Entität, wenn es in der UI16-Schnittstelle aufgerufen wird.

    Tabelle : 11. Parameter
    Name Typ Beschreibung
    Öffnen Sie ServiceNowFormularmitUntergeordneterRegisterkarte Objekt Definiert, ob die API ein Formular ServiceNow mit einer untergeordneten Registerkarte öffnet, wenn sie in einem Arbeitsbereich aufgerufen wird, oder eine Entität, wenn sie in der UI16-Schnittstelle aufgerufen wird.
    openFrameAPI.openServiceNowFormwithChildTablf({
	entity: “String”,
	sys_id: “String”, 	
	parent_entity: “String”,	
	parent_entity_sys_id: “String”,
    openServiceNowFormularwithChildTab.entity Zeichenfolge Name der Tabelle.
    openServiceNowFormwithChildTab.sys_id Zeichenfolge Sys_id des zu öffnenden Datensatzes.
    openServiceNowFormwithChildTab.parent_entity Zeichenfolge Name der Tabelle, die als übergeordnete Registerkarte geöffnet werden soll.
    openServiceNowFormwithChildTab.parent_entity_sys_id Zeichenfolge Sys_id des übergeordneten Datensatzes, der geöffnet werden soll.
    Tabelle : 12. Ergebnisse
    Typ Beschreibung
    Keine

    Das folgende Beispiel öffnet die übergeordnete Entität als übergeordnete Registerkarte in einem konfigurierten Arbeitsbereich oder öffnet nur die Entität, wenn sie in UI16 aufgerufen wird.

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

    openFrameAPI – openServiceNowList(Object details)

    Öffnet eine Listen-URL in der UI16-Schnittstelle.

    Tabelle : 13. Parameter
    Name Typ Beschreibung
    details Objekt Schlüssel-Wert-Paare, die den Inhalt beschreiben, der beim Öffnen der Listen-URL verwendet werden soll.

    Gültige Werte:
    Tabelle : 14. Ergebnisse
    Typ Beschreibung
    void 
    openFrameAPI.openServiceNowList({entity:'case', query:'active=true'});

    openFrameAPI - setFrameMode(mode)

    Legt den OpenFrame-Modus fest.

    Der in dieser API übergebene Modus:
    • Legt das entsprechende Symbol im Header fest: reduzieren oder erweitern.
    • Löst das relevante Event für CTI aus:
      • openFrameAPI.EVENTS.COLLAPSE
      • openFrameAPI.EVENTS.EXPAND
    Tabelle : 15. Parameter
    Name Typ Beschreibung
    Modus Zeichenfolge Legen Sie den OpenFrame-Modus fest. Aufgelistete Optionen:
    1. openFrameAPI.FRAME_MODE.COLLAPSE
    2. openFrameAPI.FRAME_MODE.EXPAND
    Tabelle : 16. Ergebnisse
    Typ Beschreibung
    void 
    openFrameAPI.setFrameMode(openFrameAPI.FRAME_MODE.COLLAPSE);

    openFrameAPI - setHeight(height)

    Legt die OpenFrame-Höhe fest.

    Tabelle : 17. Parameter
    Name Typ Beschreibung
    Höhe Nummer Höhe in Pixel
    Tabelle : 18. Ergebnisse
    Typ Beschreibung
    void 
    openFrameAPI.setHeight(100);

    openFrameAPI – setIcons(Array icons)

    Definiert Symbole im OpenFrame-Header, die neben dem Symbol zum Schließen platziert werden.

    Tabelle : 19. Parameter
    Name Typ Beschreibung
    icons Array von Objekten Eine Liste von Symbolkonfigurationen, wobei jede Symbolkonfiguration ein Objekt mit den Schlüsselwerten imageURL, imageTitleund einem anderen erforderlichen Kontext ist.

    Maximale Größe: Symbole dürfen maximal 16 x 16 Pixel groß sein. Größere Bilder werden automatisch an dieses Maximum angepasst.
    Tabelle : 20. Ergebnisse
    Typ Beschreibung
    void 
    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(presence)

    Legt den Anwesenheitsindikator fest, um die Agent-Verfügbarkeit in einem Arbeitsbereich anzuzeigen.

    Weitere Informationen zum Konfigurieren von OpenFrame finden Sie unter OpenFrame-Konfiguration erstellen

    Tabelle : 21. Parameter
    Name Typ Beschreibung
    state Zeichenfolge Anwesenheitsstatus des Agent.

    Standardstatus:

    • Verfügbar
    • Abwesend
    • Offline

    Sie können auch benutzerdefinierte Status angeben.
    color Zeichenfolge Farbe des Anwesenheitsindikators im Arbeitsbereich.

    Unterstützte Farben:

    • rot
    • Orange
    • grau
    • grün
    Tabelle : 22. Ergebnisse
    Typ Beschreibung
    void 
    openframeAPI.setPresenceIndicator('Available', 'green');

    openFrameAPI – setSize(Number width, Number height)

    Legt die OpenFrame-Größe fest.

    Tabelle : 23. Parameter
    Name Typ Beschreibung
    width Zahl Sollte größer als null sein.
    height Zahl Sollte größer als null sein.
    Tabelle : 24. Ergebnisse
    Typ Beschreibung
    void 
    openFrameAPI.setSize(300, 370);

    openFrameAPI – setSubtitle(String subTitle)

    Legt den OpenFrame-Untertitel fest.

    Tabelle : 25. Parameter
    Name Typ Beschreibung
    subTitle Zeichenfolge Eine Zeichenfolge mit maximal 256 Zeichen.
    Tabelle : 26. Ergebnisse
    Typ Beschreibung
    void 
    openFrameAPI.setSubtitle('+18888888888');

    openFrameAPI – setTitle(String title)

    Legt den OpenFrame-Titel fest.

    Tabelle : 27. Parameter
    Name Typ Beschreibung
    title Zeichenfolge Eine Zeichenfolge mit maximal 256 Zeichen.
    Tabelle : 28. Ergebnisse
    Typ Beschreibung
    void 
    openFrameAPI.setTitle('Incoming Call');

    openFrameAPI – setTitleIcon(Object icon)

    Legt das Titelsymbol von OpenFrame fest.

    Tabelle : 29. Parameter
    Name Typ Beschreibung
    icon Objekt Objekt von Schlüssel-Wert-Paaren. Schlüssel sind imageURL, imageTitleund jeder andere erforderliche Kontext.

    Maximale Größe: Symbole dürfen maximal 16 x 16 Pixel groß sein. Größere Bilder werden automatisch an dieses Maximum angepasst.
    Tabelle : 30. Ergebnisse
    Typ Beschreibung
    void 
    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(width)

    Legt die OpenFrame-Breite fest.

    Tabelle : 31. Parameter
    Name Typ Beschreibung
    Breite Nummer Breite in Pixel
    Tabelle : 32. Ergebnisse
    Typ Beschreibung
    void 
    openFrameAPI.setWidth(100);

    openFrameAPI – show()

    Macht den OpenFrame im TopFrame sichtbar.

    Tabelle : 33. Parameter
    Name Typ Beschreibung
    Keine
    Tabelle : 34. Ergebnisse
    Typ Beschreibung
    void 
    openFrameAPI.show()

    openFrameAPI – subscribe(openFrameAPIEVENT event, function eventCallback)

    Abonniert das Event.

    Tabelle : 35. Parameter
    Name Typ Beschreibung
    event openFrameAPIEVENT Eines der folgenden Events:
    • openframe_agent_off_interaction: Gibt die Anwesenheit eines Service Desk-Mitarbeiters im Chat als aus oder verfügbar an.
    • openframe_awa_agent_presence: In Erweiterte Arbeitszuweisung (AWA) tritt dieses Event auf, wenn sich der Anwesenheitsstatus des Agents ändert. Computer-Telefonie-Integration (CTI)-Entwickler können das Event abonnieren, um Änderungen am Anwesenheitsstatus zu erhalten.
    • openframe_awa_workitem_accepted: Tritt auf, wenn ein Service Desk-Mitarbeiter ein Arbeitselement akzeptiert.
    • openframe_awa_workitem_offered: Tritt auf, wenn einem Service Desk-Mitarbeiter ein Arbeitselement angeboten wird.
    • openframe_awa_workitem_rejected: Tritt auf, wenn ein Service Desk-Mitarbeiter ein Arbeitselement ablehnt.
    • openframe_before_destroy: Tritt ein, bevor der TopFrame entladen wird.
    • openframe_collapse: Tritt ein, wenn das Reduzieren-Symbol im OpenFrame-Header angeklickt wird.
    • openframe_communication: Anwendungsspezifisch und kann angepasst werden.
    • openframe_communication_failure: Tritt ein, wenn die Kommunikation mit TopFrame fehlschlägt.
    • openframe_expand: Tritt ein, wenn das Erweitern-Symbol im OpenFrame-Header angeklickt wird.
    • openframe_header_icon_clicked: Veraltet. Verwenden Sie stattdessen openframe_icon_clicked oder openframe_title_icon_clicked.
    • openframe_hidden: Tritt ein, wenn der OpenFrame ausgeblendet ist.
    • openframe_icon_clicked: Tritt ein, wenn auf ein anderes Symbol als das Schließsymbol in der OpenFrame-Fußzeile geklickt wird. Der Callback empfängt das Icon-Objekt als einen Parameter.
    • openframe_shown: Tritt ein, wenn der OpenFrame angezeigt wird.
    • openframe_title_icon_clicked: Tritt ein, wenn das Titelsymbol im OpenFrame angeklickt wird. Der Callback empfängt das titleIcon-Objekt als Parameter.
    eventCallback function Die Funktion wird aufgerufen, wenn das angegebene Event eintritt.
    Tabelle : 36. Ergebnisse
    Typ Beschreibung
    Keine, sofern nichts anderes beschrieben. Die meisten Event-Abonnements haben keine Rückgabewerte, mit den folgenden Ausnahmen:
    In AWA gibt das Event openframe_awa_agent_presence das Anwesenheitsobjekt zurück:
    • presence: Informationen über den aktuellen Anwesenheitsstatus und Kanal eines Service Desk-Mitarbeiters. Ausgabebeispiel unten.
    • presence.name: Name des Anwesenheitsstatus des Service Desk-Mitarbeiters.
    • presence.sys_id: Anwesenheitsstatus-sys_id. Befindet sich in der Tabelle „Anwesenheitsstatus“ [awa_presence_state].
    • presence.available: Kennzeichnung, die angibt, ob der Agent verfügbar ist.
    • presence.channels: Liste der Objekte, die die verfügbaren Kommunikationskanäle mit dem Service Desk-Mitarbeiter beschreiben.
    • Presence.Channels.Name:Kanalname, z. B. Chat oder Telefon.
    • presence.channels.available: Kennzeichnung, die angibt, ob der Kanal verfügbar ist.
    • presence.channels.sys_id: sys_id des Kanals. Befindet sich in der Tabelle „Servicekanäle“ [awa_service_channel].
    • presence.channels.restrict_update: Kennzeichnung, die angibt, ob der Benutzer Updates einschränken kann.

    Beispiel

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

    Ausgabe

    // 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()

    Gibt die OpenFrame-API-Version zurück.

    Tabelle : 37. Parameter
    Name Typ Beschreibung
    Keine
    Tabelle : 38. Ergebnisse
    Typ Beschreibung
    Zeichenfolge Die OpenFrame-API-Version 
    var version = openFrameAPI.version();

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