openFrameAPI - Cliente

  • Versão de lançamento: Washingtondc
  • Atualizado 1 de fev. de 2024
  • 8 min. de leitura

    • O OpenFrame é um quadro onipresente que os parceiros de comunicação podem usar para integrar seus sistemas na plataforma ServiceNow.

    Um dos principais requisitos é a capacidade de conectar e servir código de diferentes domínios que podem se conectar perfeitamente com subsistemas de parceiros. Essa conexão entre domínios é necessária para manter conexões e retornos de chamada registrados em sistemas de comunicação sem problemas entre domínios.

    O OpenFrame tem duas partes significativas: uma que reside na aplicação ServiceNow (conhecida como TopFrame) e esta API que é originada da aplicação do parceiro. Esta API tem os métodos necessários para se comunicar com o TopFrame e controlar os recursos visuais do OpenFrame.
    Nota:
    Para se manter atualizado com referência à biblioteca OpenFrame, use o seguinte URI de recurso: https://[servicenow instance]/scripts/openframe/latest/openFrameAPI.min.js.

    openFrameAPI - ocultar ()

    Oculta o OpenFrame no TopFrame.

    Tabela 1. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 2. Retorna
    Tipo Descrição
    vazio 
    openFrameAPI.hide()

    openFrameAPI - init(objeto de configuração, função de sucessoCallback, função de retorno de chamada)

    Inicialize o OpenFrame, deve ser o primeiro método chamado.

    Este método inicializa a comunicação com o TopFrame e inicializa todos os elementos visuais passados no parâmetro de configuração.

    Tabela 3. Parâmetros
    Nome Tipo Descrição
    config Objeto Um objeto de pares de chave-valor. As chaves possíveis são altura, largura, título, subTitle e titleIcon. Todas as chaves são opcionais.
    sucessoRetorno de chamada função A função de retorno de chamada usada se o método de inicialização for bem-sucedido. A configuração openframe armazenada no sistema é passada como um parâmetro para a função de retorno de chamada.
    falhaRetorno de chamada função A função de retorno de chamada usada se o método de inicialização falhar.
    Tabela 4. Retorna
    Tipo Descrição
    vazio 
    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(retorno de chamada da função)

    Verifica se o OpenFrame está visível no TopFrame.

    Tabela 5. Parâmetros
    Nome Tipo Descrição
    retorno de chamada função A função de retorno de chamada recebe um parâmetro com um valor verdadeiro ou falso. Verdadeiro se o OpenFrame estiver visível e falso se não estiver visível.
    Tabela 6. Retorna
    Tipo Descrição
    vazio 
    function callback(isVisible) {
console.log(isVisible)
}
openFrameAPI.isVisible(callback)

    openFrameAPI - openCustomURL(cadeia de caracteres "Detalhes")

    Abre um URL personalizado na interface UI16.

    Tabela 7. Parâmetros
    Nome Tipo Descrição
    Url Cadeia de caracteres Texto do URL personalizado.

    Tamanho máximo: 2083 caracteres
    Tabela 8. Retorna
    Tipo Descrição
    vazio 
    openFrameAPI.openCustomURL('10_cool_things.do');

    openFrameAPI - openServiceNowForm(Detalhes do objeto)

    Abre um URL de formulário.

    Quando um agente recebe uma chamada, a janela do OpenFrame exibe informações como conta, contato ou consumidor. Clicar em um link na janela do OpenFrame exibe o registro correspondente.
    • Na interface da plataforma, essa API abre um URL de formulário no TopFrame.
    • Para Espaço do agente, esta API oferece suporte ao gerenciamento da guia de interação. Em Espaço do agente, um registro de interação é aberto em uma guia primária e o registro de entidade especificado é aberto em uma guia secundária na guia de interação.
    Tabela 9. Parâmetros
    Nome Tipo Descrição
    detalhes Objeto Pares de chave-valor que identificam o URL do formulário a ser aberto. 
    "details": {
  "entity": "String";
  "interaction_sys_id": "String";
  "query": "String"
}
    detalhes.entidade Cadeia de caracteres Nome da tabela ou da entidade.
    details.interaction_sys_id Cadeia de caracteres Opcional. Sys_id do registro de interação a ser aberto como guia primária em Espaço do agente.
    Nota:
    Na interface da plataforma, o interaction_sys_id é ignorado.
    details.query Cadeia de caracteres Consulta para identificar o registro a ser aberto, como: query:'sys_id=<record_sys_id> ' .
    Tabela 10. Retorna
    Tipo Descrição
    vazio

    O exemplo a seguir mostra o uso básico na plataforma:

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

    O exemplo a seguir mostra como usar o parâmetro query para criar um novo registro com dados fornecidos no formulário usando sysparm_query e uma consulta codificada para preencher os campos de nome e sobrenome no espaço:

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

    openFrameAPI - openServiceNowFormwithChildTabIf()

    Abre um formulário ServiceNow com uma guia secundária se invocado em um espaço ou abre uma entidade se invocado na interface UI16.

    Tabela 11. Parâmetros
    Nome Tipo Descrição
    openServiceNowFormwithChildTab Objeto Define se a API abre um formulário ServiceNow com uma guia secundária se invocada em um espaço ou abre uma entidade se invocada na interface UI16.
    openFrameAPI.openServiceNowFormwithChildTablf({
	entity: “String”,
	sys_id: “String”, 	
	parent_entity: “String”,	
	parent_entity_sys_id: “String”,
    openServiceNowFormwithChildTab.entity Cadeia de caracteres Nome da tabela.
    openServiceNowFormwithChildTab.sys_id Cadeia de caracteres Sys_id do registro a ser aberto.
    openServiceNowFormwithChildTab.parent_entity Cadeia de caracteres Nome da tabela a ser aberta como guia primária.
    openServiceNowFormwithChildTab.parent_entity_sys_id Cadeia de caracteres Sys_id do registro primário a ser aberto.
    Tabela 12. Retorna
    Tipo Descrição
    Nenhum

    O exemplo a seguir abre a entidade primária como uma guia primária em um espaço configurado ou abre apenas a entidade se invocada em UI16.

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

    openFrameAPI - openServiceNowList(Detalhes do objeto)

    Abre um URL de lista na interface UI16.

    Tabela 13. Parâmetros
    Nome Tipo Descrição
    detalhes Objeto Pares de chave-valor que descrevem o conteúdo a ser usado ao abrir o URL da lista.

    Valores válidos:
    Tabela 14. Retorna
    Tipo Descrição
    vazio 
    openFrameAPI.openServiceNowList({entity:'case', query:'active=true'});

    openFrameAPI - setFrameMode(mode)

    Define o modo OpenFrame.

    O modo aprovado nesta API:
    • Define o ícone apropriado no cabeçalho: recolher ou expandir
    • Gera o evento relevante para CTI:
      • openFrameAPI.EVENTOS.COLLAPSE
      • openFrameAPI.EVENTOS.EXPAND
    Tabela 15. Parâmetros
    Nome Tipo Descrição
    Modo Cadeia de caracteres Defina o modo OpenFrame. Opções enumeradas:
    1. openFrameAPI.FRAME_MODE.COLLAPSE
    2. openFrameAPI.FRAME_MODE.EXPAND
    Tabela 16. Retorna
    Tipo Descrição
    vazio 
    openFrameAPI.setFrameMode(openFrameAPI.FRAME_MODE.COLLAPSE);

    openFrameAPI - setHeight(height)

    Define a altura do OpenFrame.

    Tabela 17. Parâmetros
    Nome Tipo Descrição
    Altura Número Altura em pixels
    Tabela 18. Retorna
    Tipo Descrição
    vazio 
    openFrameAPI.setHeight(100);

    openFrameAPI - setIcons(Ícones de matriz)

    Define os ícones no cabeçalho do OpenFrame que são colocados ao lado do ícone de fechamento.

    Tabela 19. Parâmetros
    Nome Tipo Descrição
    ícones Matriz de objetos Uma lista de configurações de ícone, em que cada configuração de ícone é um objeto com valores de chave imageURL, imageTitlee qualquer outro contexto necessário.

    Tamanho máximo: os ícones podem ter no máximo 16x16 pixels. Imagens maiores são ajustadas automaticamente para este máximo.
    Tabela 20. Retorna
    Tipo Descrição
    vazio 
    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(presença)

    Define o indicador de presença para exibir a disponibilidade do agente em um espaço.

    Para obter mais informações sobre como configurar o OpenFrame, consulte Criar uma configuração OpenFrame.

    Tabela 21. Parâmetros
    Nome Tipo Descrição
    Estado Cadeia de caracteres Estado de presença do agente.

    Estados padrão:

    • Disponível
    • Ausente
    • Off-line

    Você também pode especificar estados personalizados.
    cor Cadeia de caracteres Cor do indicador de presença no espaço.

    Cores compatíveis:

    • vermelho
    • laranja
    • cinza
    • verde
    Tabela 22. Retorna
    Tipo Descrição
    vazio 
    openframeAPI.setPresenceIndicator('Available', 'green');

    openFrameAPI - setSize(largura do número, altura do número)

    Define o tamanho do OpenFrame.

    Tabela 23. Parâmetros
    Nome Tipo Descrição
    largura Número Deve ser maior que zero.
    altura Número Deve ser maior que zero.
    Tabela 24. Retorna
    Tipo Descrição
    vazio 
    openFrameAPI.setSize(300, 370);

    openFrameAPI - setSubtitle(cadeia de caracteres subTitle)

    Define a legenda do OpenFrame.

    Tabela 25. Parâmetros
    Nome Tipo Descrição
    subTitle Cadeia de caracteres Uma cadeia de caracteres de 256 caracteres ou menos.
    Tabela 26. Retorna
    Tipo Descrição
    vazio 
    openFrameAPI.setSubtitle('+18888888888');

    openFrameAPI - setTitle(cadeia de caracteres "title")

    Define o título do OpenFrame.

    Tabela 27. Parâmetros
    Nome Tipo Descrição
    título Cadeia de caracteres Uma cadeia de caracteres de 256 caracteres ou menos.
    Tabela 28. Retorna
    Tipo Descrição
    vazio 
    openFrameAPI.setTitle('Incoming Call');

    openFrameAPI - setTitleIcon(ícone do objeto)

    Define o ícone de título do OpenFrame.

    Tabela 29. Parâmetros
    Nome Tipo Descrição
    ícone Objeto Objeto de pares de chave-valor. As chaves incluem imageURL, imageTitlee qualquer outro contexto necessário.

    Tamanho máximo: os ícones podem ter no máximo 16x16 pixels. Imagens maiores são ajustadas automaticamente para este máximo.
    Tabela 30. Retorna
    Tipo Descrição
    vazio 
    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)

    Define a largura do OpenFrame.

    Tabela 31. Parâmetros
    Nome Tipo Descrição
    Largura Número Largura em pixels
    Tabela 32. Retorna
    Tipo Descrição
    vazio 
    openFrameAPI.setWidth(100);

    openFrameAPI - mostrar ()

    Torna o OpenFrame visível no TopFrame.

    Tabela 33. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 34. Retorna
    Tipo Descrição
    vazio 
    openFrameAPI.show()

    openFrameAPI -subscribe(evento openFrameAPIEVENT, função eventCallback)

    Assina o evento.

    Tabela 35. Parâmetros
    Nome Tipo Descrição
    evento openFrameAPIEVENT Um dos seguintes eventos:
    • openframe_agent_off_interaction: indica a presença de um agente no bate-papo como desativado ou disponível.
    • openframe_awa_agent_presence: em Advanced Work Assignment (AWA), este evento ocorre quando há alguma mudança no estado de presença do agente. Os desenvolvedores de Integração de telefonia e computação (CTI) podem assinar este evento para receber mudanças de estado de presença.
    • openframe_awa_workitem_accepted: ocorre quando um item de trabalho é aceito por um agente.
    • openframe_awa_workitem_offered: ocorre quando um item de trabalho é oferecido a um agente.
    • openframe_awa_workitem_rejected: ocorre quando um item de trabalho é rejeitado por um agente.
    • openframe_before_destroy: ocorre antes que o TopFrame seja descarregado.
    • openframe_collapse: ocorre quando o ícone de recolhimento é clicado no cabeçalho do OpenFrame.
    • openframe_communication: específico da aplicação e pode ser personalizado.
    • openframe_communication_failure: ocorre quando a comunicação com o TopFrame falha.
    • openframe_expand: ocorre quando o ícone de expansão é clicado no cabeçalho do OpenFrame.
    • openframe_header_icon_clicked: obsoleto. Em vez disso, use openframe_icon_clicked ou openframe_title_icon_clicked.
    • openframe_hidden: ocorre quando o OpenFrame está oculto.
    • openframe_icon_clicked: ocorre quando qualquer ícone diferente do ícone de fechar é clicado no rodapé do OpenFrame. O retorno de chamada recebe o objeto de ícone como um parâmetro.
    • openframe_shown: ocorre quando o OpenFrame é mostrado.
    • openframe_title_icon_clicked: ocorre quando o ícone do título é clicado no OpenFrame. O retorno de chamada recebe o objeto titleIcon como um parâmetro.
    eventCallback função Função chamada quando ocorre o evento especificado.
    Tabela 36. Retorna
    Tipo Descrição
    Nenhum, a menos que seja descrito de outra forma. A maioria das assinaturas de evento não tem valores de retorno, com as seguintes exceções:
    Em AWA, o evento openframe_awa_agent_presence retorna o objeto de presença:
    • presença: Informações sobre o estado de presença atual e o canal de um agente. Exemplo de saída abaixo.
    • presence.name: Nome do estado de presença do agente.
    • presença.sys_id: sys_id do estado de presença. Localizado na tabela Estados de presença [awa_presence_state].
    • presença.disponível: Sinalizador que indica se o agente está disponível.
    • presença.canais: Lista de objetos que descrevem os canais de comunicação disponíveis com o agente.
    • presence.channels.name: Nome do canal, como Bate-papo ou Telefone.
    • presença.canais.disponível: Sinalizador que indica se o canal está disponível.
    • presença.canais.sys_id: sys_id do canal. Localizado na tabela Canais de serviço [awa_service_channel].
    • presença.channels.restrict_update: Sinalizador que indica se o usuário pode restringir atualizações.

    Exemplo

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

    Saída

    // 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 - versão ()

    Retorna a versão da API do OpenFrame.

    Tabela 37. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 38. Retorna
    Tipo Descrição
    Cadeia de caracteres A versão da API do OpenFrame 
    var version = openFrameAPI.version();

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