Criar um script de ação API

API scripts de ação é uma opção de Studio avançada. Eles são scripts de Studio especiais que são salvos como Studio ações de estrutura e podem ser acessados com REST API pontos de extremidade. Eles permitem que você crie suas próprias ações de Framework para usar em seus scripts.

Esta página descreve como criar e configurar um script de ação API. A lista a seguir fornece uma visão geral do processo. Todos os detalhes estão nas seções vinculadas de cada etapa de visão geral.

  1. Criar um script de ação API.
  2. Configure seu script de ação API para ser usado como uma ação do Studio Framework em outros scripts, como um REST API ponto de extremidade ou ambos. Em particular, certifique-se de definir os parâmetros e ramificações, pois eles determinam as informações que entram e saem do script, bem como os resultados da execução do script.
  3. Configure as ações no script de ação API para usar as ramificações definidas.
  4. Testar seu script de ação API. O método de teste dependerá da funcionalidade em seu script, bem como se você está usando-o como uma ação Framework ou um REST API. Se você usá-lo como uma ação do Framework, poderá testar e depurar no Studio.

As alterações demoram a entrar em vigor depois de salvar as alterações no script de ação API. Pode levar até cinco minutos após salvar as alterações antes que elas sejam refletidas no API.

Criar um script de ação API

Na primeira vez que você salva um script de ação API, uma ação personalizada é adicionada à guia Estrutura no Studio. Por padrão, a ação tem o mesmo nome do script de ação API e é salva em uma pasta \Pessoal. A pasta é criada automaticamente se ainda não existir. O script de ação API em si é salvo em seu sistema CXone Mpower como seus outros scripts.

  1. Em Studio, clique em Arquivo > Novo e selecione Estrutura em Modelos Disponível.
  2. Selecione API Ação como o tipo de script no campo do lado direito da janela.
  3. Clique em OK.
  4. Modifique o script. O modelo contém um BEGIN action, um CASE action e quatro RETURN actions. Ele também contém algumas NOTE ações que oferecem sugestões sobre como trabalhar com o script.

  5. Salve o seu script.

  6. Configure seu script para ser usado como uma ação do Studio Framework em outros scripts, como um REST API ponto de extremidade ou ambos.

Configure o REST API Configurações

Você só precisará definir as configurações API se planeja usar esse script como um API REST. Algumas das configurações se aplicam ao uso do script como um ponto de extremidade API REST e como uma ação do Framework.

As configurações relacionadas aos scripts de ação API são todas encontradas na seção Configurações das propriedades do script. Você pode aprender sobre as outras configurações de propriedade de script.

  1. No Studio, abra o script da ação API com o qual quer trabalhar. Você pode abri-lo como faria com outros scripts Studio, ou você pode ir à pasta Pessoal na guia Framework, clicar com o botão direito do mouse na ação API e clicar em Abrir script.

  2. Clique no espaço em branco na tela do script para ter certeza de que não há ações selecionadas. Isto permite que você veja as propriedades do script.

  3. Na guia Propriedades, expanda a seção Configurações.

  4. Configure a seção Parâmetros para definir os dados que o script manipula. Você pode definir as informações que entram no script, saem do script ou ambas.

  5. Crie ramificações para definir os resultados da execução do script.

  6. Clique na lista suspensa Verb para escolher o tipo de ação que esse REST API realizar.

  7. Defina configurações opcionais:

    • Atualize a Versão quando publicar uma nova versão do script, da mesma forma que faria com outras APIs.

    • Modificar o URI do REST API.

    • Defina Shared como True se você quiser que essa ação de script esteja disponível para outros usuários do Studio no seu CXone Mpower sistema.

    • Defina HasDefault como True se quiser que a ação Framework criada a partir deste script tenha um ramal Padrão. Caso não queira o ramal padrão, selecione False A prática recomendada para todas as ações Studio é ter um ramal Padrão.

  8. Salve o script.

Configurar a ação de estrutura Configurações

Você só precisará definir as configurações da ação API se planeja usar esse script como uma ação em outros scripts Studio.

  1. No Studio, abra o script da ação API com o qual quer trabalhar. Você pode abri-lo como faria com outros scripts Studio, ou você pode ir à pasta Pessoal na guia Framework, clicar com o botão direito do mouse na ação API e clicar em Abrir script.

  2. Clique no espaço em branco na tela do script para ter certeza de que não há ações selecionadas. Isto permite que você veja as propriedades do script.

  3. Na guia Propriedades, expanda a seção Configurações.

  4. Insira um Nome para a ação Framework criada a partir deste script. Você pode alterar este nome sem afetar o nome do script. O conteúdo deste campo é usado como a legenda padrão que aparece na tela do script quando você adiciona a ação de API para outro script Studio.

  5. Insira uma Descrição do script desta ação API. Este texto é usado como uma dica de ferramenta quando você passa o cursor do mouse sobre a ação Studio criada a partir deste script.

  6. Para alterar a pasta na guia Framework onde esta ação Framework se encontra, insira um nome na propriedade Categoria. Se o nome que você especificou ainda não existe, a pasta é automaticamente criada quando você salva este script e a ação é automaticamente movida para ela. O padrão é Pessoal.

  7. Para editar o ícone da ação padrão, clique nas reticências Uma série de três pontos. no campo Ícone para modificar o ícone padrão. Este ícone aparece na lista de ações na guia Framework no Studio e na tela do script quando você adiciona a ação a um script Studio.

  8. Defina HasDefault como True se quiser que a ação Framework criada a partir deste script tenha um ramal Padrão. Caso não queira o ramal padrão, selecione False A prática recomendada para todas as ações Studio é ter um ramal Padrão.

  9. Salve o script.

Criar Parâmetros

Parâmetros definir os dados que entram no script, saem do script ou ambos. Os parâmetros que você define são aplicados tanto para a ação Framework criada a partir deste script quanto para a REST API do script. Esses parâmetros se tornam as propriedades da ação Framework.

  1. No Studio, abra o script da ação API com o qual quer trabalhar. Você pode abri-lo como faria com outros scripts Studio, ou você pode ir à pasta Pessoal na guia Framework, clicar com o botão direito do mouse na ação API e clicar em Abrir script.

  2. Clique no espaço em branco na tela do script para ter certeza de que não há ações selecionadas. Isto permite que você veja as propriedades do script.

  3. Na guia Propriedades, expanda a seção Settings > Parameters. Os parâmetros atualmente definidos no script estão listados nesta seção.

  4. Clique no Uma série de três pontos. de reticências no campo Parameters.

  5. Para modificar um parâmetro existente, selecione-o na lista Members no lado esquerdo da janela.

  6. Para criar um novo parâmetro, clique em Add e selecione o novo parâmetro Unnamed na lista Members no lado esquerdo da janela.

  7. Na seção Básico em Propriedades sem nome, no lado direito da janela, insira uma nova Name para o parâmetro. Nomes não podem incluir espaços ou caracteres especiais, exceto sublinhado ( _ ).

  8. Selecione o Direction do parâmetro. Isso define se os dados estão entrando no script (In), saindo do script (Out) ou ambos (BiDirectional).

  9. Selecione o Type de dados do valor desse parâmetro. Você pode escolher entre String, Boolean, Number, Date Time, Custom Type, StringArray ou CustomArray.

  10. Insira um DefaultValue para o parâmetro, se ele tiver um. Esse é o valor que sempre é passado de volta se nenhum outro valor for atribuído à variável quando o script for chamado.

  11. Adicione uma Description do parâmetro para ajudar outros usuários a entendê-lo.

  12. Em Avançado, selecione uma opção na lista suspensa Nome do tipo personalizado. Você só precisará executar esta etapa se definir Tipo como Personalizado Tipo. As opções nesta lista são classes internas no CXone Mpower e só devem ser usadas se você estiver familiarizado com como usá-las.

  13. Em PropertyHelper, selecione um campo Tipo. Isso define o tipo de campo usado para a propriedade que corresponde a esse parâmetro na ação Studio criada a partir desse script. As opções disponíveis dependem do tipo de dados selecionado para esse parâmetro.

  14. Para configurar uma lista suspensa com uma lista estática de opções:
    1. Em PropertyHelper, verifique se Type está definido como Custom Suspenso.
    2. Selecione LiteralList na lista suspensa Fonte.
    3. Clique no Uma série de três pontos. de reticências no campo Conteúdo para abrir a janela Editor Coleção de Strings.
    4. No campo de texto, insira as opções que deseja que apareçam na lista suspensa. Liste cada opção em uma linha separada.
    5. Clique em OK.
  15. Para configurar uma lista suspensa para preencher com dados CXone Mpower:
    1. Em PropertyHelper, verifique se Type está definido como Custom Suspenso.
    2. Selecione Consulta na lista suspensa Fonte.
    3. Selecione uma opção na lista suspensa QueryCommand. As opções disponíveis correspondem a CXone Mpower dados usados em scripts, como habilidades de ACD, IDs de agente, scripts de Studio, música de espera e assim por diante.
    4. Clique em OK.
  16. Para configurar uma lista suspensa para preencher a partir de uma chamada de API personalizada:
    1. Em PropertyHelper, verifique se Type está definido como Custom Suspenso.
    2. Selecione Consulta na lista suspensa Fonte.
    3. Selecione API personalizado na lista suspensa QueryCommand.
    4. Digite o CustomAPIURI da chamada API que você deseja usar.
    5. Insira o nome do membro da cadeia de caracteres de resposta JSON com a qual você deseja preencher esta lista suspensa.
    6. Clique em OK.
  17. Para evitar a substituição de variáveis por esse parâmetro, defina AllowReferences como False. O padrão é True.
  18. Para tornar essa propriedade somente leitura, defina ReadOnly como True. As propriedades somente leitura ficam acinzentadas na lista de propriedades da ação criada a partir desse script. O padrão é False.
  19. Clique em OK.

Criar ramificação Condições

Ramais em scripts de ação de API são os mesmos que os ramais nas ações Studio. Eles são as condições de tomada de decisão que determinam o que acontece depois que o script é executado. A diferença é que, em scripts de ação de API, você cria os ramais. Você deve ter um ramal para erros, bem como para os outros possíveis resultados.

As ramificações se aplicam a ambos os usos de API scripts de ação: como uma ação Framework e como um REST API. Na ação Estrutura, elas são as ramificações que você usa para se conectar a outras ações no script em que você usa a ação. No API REST, eles são o código de status HTTP e a descrição que são retornados.

  1. No Studio, abra o script da ação API com o qual quer trabalhar. Você pode abri-lo como faria com outros scripts Studio, ou você pode ir à pasta Pessoal na guia Framework, clicar com o botão direito do mouse na ação API e clicar em Abrir script.

  2. Clique no espaço em branco na tela do script para ter certeza de que não há ações selecionadas. Isto permite que você veja as propriedades do script.

  3. Na guia Propriedades, expanda a seção Settings > Branches. As ramificações atualmente definidas no script estão listadas nesta seção.

  4. Clique na Uma série de três pontos. de reticências no campo Branches.

  5. Para modificar uma ramificação existente, selecione-a na lista Members no lado esquerdo da janela.

  6. Para criar uma nova ramificação, clique em Add e selecione o novo parâmetro Unnamed na lista Members no lado esquerdo da janela.

  7. Para configurar a condição de ramificação para a ação Framework, configure a seção Misc em _Name properties:
    1. Insira um Nome para a ramificação. Os nomes não podem incluir espaços ou qualquer caractere especial, exceto sublinhado ( _ ).
    2. Insira uma Descrição do ramal. A descrição se torna uma dica de ferramenta que aparece quando você passa o cursor sobre o ramal nas propriedades da ação Studio criada a partir desse script.

  8. Para configurar o código de status HTTP para o API REST, configure a seção Web em _Name propriedades:

    1. Digite o StatusCode. O código de status deve ser um valor numérico.

    2. Digite a Descrição que é retornada com o código.

  9. Na seção Configurações da guia Propriedades, insira um nome na propriedade CaseParameter. Isso define o nome da propriedade de saída que aparece quando você usa esse script como uma ação do Framework em outro script. O nome que você definir aparecerá na lista de propriedades da ação da estrutura personalizada com (out) depois dele. Por exemplo, se você definir CaseParameter como CustomResult, a lista de propriedades da ação da estrutura personalizada mostrará uma propriedade chamada CustomResult (out).

  10. Clique em OK.

Configurar as ações em um script de ação API

Você pode personalizar o comportamento que seu script de ação API executa quando é executado. As ações adicionadas devem ser suportadas em API scripts de ação.

Você deve configurar as ações RETURN em um script de ação API para usar as ramificações criadas nas configurações do script. O script precisa ter lógica que determine qual ramificação (RETURN ação) retornar quando o script for executado. No modelo de script padrão, a lógica é fornecida por CASE, mas você pode criar sua própria lógica.

  1. No Studio, abra o script da ação API com o qual quer trabalhar. Você pode abri-lo como faria com outros scripts Studio, ou você pode ir à pasta Pessoal na guia Framework, clicar com o botão direito do mouse na ação API e clicar em Abrir script.

  2. Configure o script conforme necessário, adicionando Studio ações e lógica de script entre as ações BEGIN e CASE. As ações adicionadas devem ser suportadas por API scripts de ação.
  3. Adicione ou remova RETURN ações conforme necessário, dependendo do número de ramificações que seu script possui.
  4. Para cada ação RETURN no seu script:
    1. Clique com o botão direito na ação e altere a propriedade Caption para indicar a ramificação retornada.
    2. Clique na lista suspensa ReturnValue e selecione a ramificação que deseja que essa ação retorne. As opções nesta lista suspensa são definidas na seção Ramos das propriedades do script de ação API.
  5. Substitua CASE se você criou sua própria lógica no script para determinar qual ramificação retornar. Conecte as ações adicionadas às ações RETURN para que o script possa retornar a resposta apropriada.
  6. Se você usar um CASE ação:
    1. Certifique-se de que seu script resulte em uma única variável que passe um valor para a ação CASE. O valor acionará CASE para escolher a ação RETURN apropriada a ser retornada.
    2. Selecione a ação CASE na tela do script e clique na guia Propriedades.
    3. Na propriedade Variável, insira o nome da variável que passa o valor da tomada de decisão para CASE.
    4. Clique na Uma série de três pontos. de reticências na propriedade CustomCases para abrir a janela do editor. Você precisa definir um caso para cada valor possível do Variável que você definiu. Você pode saber mais sobre como os casos funcionam na página de ajuda Declarações de tomada de decisão.
    5. Clique em Adicionar em Membros no lado esquerdo da janela.
    6. Selecione a entrada (Não atribuídos) na lista Membros.
    7. No campo Condição no lado direito da janela, insira o valor que aciona a ação para escolher esse caso.
    8. Selecione a opção na lista suspensa Destino que corresponde à ação RETURN para o resultado especificado.
    9. Quando terminar de adicionar casos, clique em Ok.
  7. Salve o seu script.

Personalizar o REST API URI

O URI padrão é o número da CXone Mpower unidade de negóciosClosed Alto nível de agrupamento organizacional usado para gerenciar o suporte técnico, cobrança e configurações globais para o seu ambiente CXone Mpower e o nome do script de ação API.

  1. No Studio, abra o script da ação API com o qual quer trabalhar. Você pode abri-lo como faria com outros scripts Studio, ou você pode ir à pasta Pessoal na guia Framework, clicar com o botão direito do mouse na ação API e clicar em Abrir script.

  2. Clique no espaço em branco na tela do script para ter certeza de que não há ações selecionadas. Isto permite que você veja as propriedades do script.

  3. Na guia Propriedades, expanda a seção Configurações.

  4. Clique na Uma série de três pontos. de reticências no campo URI.

  5. Clique em URI Namespace e selecione uma das opções. O padrão é o número da unidade de negócios CXone Mpower. A outra opção é o número da unidade de negócios prefixado por bus.

  6. Insira um identificador exclusivo para esta ação API no campo URI Fragment.

  7. Realce e copie o Full URI (example) para usá-lo ou testá-lo.

Personalizar o Studio da API Action Ícone

  1. No Studio, abra o script da ação API com o qual quer trabalhar. Você pode abri-lo como faria com outros scripts Studio, ou você pode ir à pasta Pessoal na guia Framework, clicar com o botão direito do mouse na ação API e clicar em Abrir script.

  2. Clique no espaço em branco na tela do script para ter certeza de que não há ações selecionadas. Isto permite que você veja as propriedades do script.

  3. Na guia Propriedades, expanda a seção Configurações.

  4. Clique no Uma série de três pontos. de reticências no campo Icon.

  5. Para usar uma imagem existente como ícone, clique em Arquivo > Abrir arquivo de imagem, selecione um arquivo e clique em Abrir. Você pode modificar a imagem selecionada, se desejar.
  6. Na janela Editor Ícone, escolha uma cor e clique na ferramenta lápis.
  7. Desenhe na imagem do lado direito do Ícone Editor janela.

  8. Para alterar as cores, clique na nova cor. O tipo de ferramenta não pode ser alterado. A única ferramenta que funciona é o lápis.

  9. Para salvar o arquivo de imagem no computador, clique em Arquivo > Salvar como, escolha um local e clique clique em Salvar.

  10. Para salvar a imagem em Studio, clique em Ok na janela Ícone Editor.

Obter o REST API Endpoint

Para usar uma ação de API como uma REST API ponto de extremidade, você precisa do URI completo, incluindo o nome do host. O nome do host a ser usado depende do cluster onde seu sistema CXone Mpower está localizado. A primeira etapa da tarefa a seguir mostra como fazer isso.

  1. Descubra o nome do host do seu sistema CXone Mpower. A seção Executar API Descoberta da página Introdução Um ícone de um quadrado com uma seta apontando do centro para o canto superior direito. do portal do desenvolvedor CXone Mpower descreve como fazer isso. Depois de seguir as etapas desta página, use o valor retornado no parâmetro api_endpoint na resposta à sua consulta de descoberta. Por exemplo, o valor pode ser https://api-na1.niceincontact.com.

  2. No Studio, abra o script da ação API com o qual quer trabalhar. Você pode abri-lo como faria com outros scripts Studio, ou você pode ir à pasta Pessoal na guia Framework, clicar com o botão direito do mouse na ação API e clicar em Abrir script.

  3. Clique no espaço em branco na tela do script para ter certeza de que não há ações selecionadas. Isto permite que você veja as propriedades do script.

  4. Na guia Propriedades, expanda a seção Configurações.

  5. Copie o valor da propriedade URI. Na imagem de exemplo da etapa anterior, o valor é /custom/4600738/APIActionScript.
  6. Combine o nome do host descoberto e o valor URI copiado do script de ação API. Por exemplo, se seu nome de host for https://api-na1.niceincontact.com e seu URI for /custom/4600738/APIActionScript, a URI completa será:
    https://api-na1.niceincontact.com/custom/4600738/APIActionScript
  7. Antes de usar o ponto de extremidade, verifique as configurações de script relacionadas ao API, como o verbo, parâmetros e ramificações.

Documente seu script de ação API

A documentação completa do seu script de ação API é importante para que seja fácil de usar mais tarde ou por outros usuários Studio. Ao criar e configurar seu script, certifique-se de que:

  • Escolha nomes descritivos e relevantes para parâmetros, ramificações e outras configurações no script.
  • Construa cuidadosamente as descrições de parâmetros, ramificações e assim por diante. Dependendo da configuração com a qual você está trabalhando, as descrições aparecem como dicas de ferramentas, na tela do script, na interface do usuário do Studio ou são retornadas com códigos de status. É importante que eles façam sentido fora do contexto do script de ação API e no contexto em que serão vistos por outros usuários. Eles devem ser curtos, mas fornecem informações importantes suficientes para ajudar um usuário não familiarizado com o script a entender a configuração.
  • Altere as legendas das ações no script de ação API. Use frases curtas e descritivas para indicar a finalidade que a ação serve no script.
  • Use Annotation ou Note ações no script de ação API. Documente completamente o script usando essas ações.
  • Adicione comentários em qualquer SNIPPET ações que você usar em seu script.

Além disso, convém documentar a ação Estrutura.

Trabalhe com sua ação de estrutura personalizada

Quando o script de ação API estiver concluído, você poderá usar a ação Framework personalizada em outros scripts Studio. Você pode encontrar a ação Framework na pasta \Personal na guia Framework em Studio a menos que um local personalizado tenha sido especificado. O local da ação é definido na propriedade Category na seção Configurações das propriedades do script.

Para usar sua ação personalizada do Framework:

  1. Dentro Studio, abra ou crie um script.
  2. Na guia Estrutura, localize a ação Estrutura personalizada e arraste-a para a tela do script como faria com qualquer outra ação.
  3. Selecione a ação e clique na guia Propriedades em Studio.
  4. Configure as propriedades da ação. As propriedades específicas dependem dos parâmetros definidos no script de ação API.
  5. Conecte a ação usando as condições de ramal disponíveis. Essas ramificações são definidas no script de ação API.

Todas as definições de propriedade do API Action Script

As propriedades do script de ação API são descritas nos segundos anteriores nesta página no contexto da configuração de um script de ação API para um uso específico como uma ação Framework ou um ponto de extremidade API. No entanto, se você quiser uma lista completa das propriedades, consulte a tabela nesta seção.

As únicas propriedades definidas nesta seção são aquelas localizadas na seção Configurações das propriedades do script, conforme mostrado na imagem a seguir. Você pode saber mais sobre as configurações nas outras seções da página de ajuda Trabalhe com Scripts.

campo Detalhes
Nome

Insira um nome para a ação Framework criada a partir deste script. Você pode alterar este nome sem afetar o nome do script. O conteúdo deste campo é usado como a legenda padrão que aparece na tela do script quando você adiciona a ação de API para outro script Studio.

Essa propriedade se aplica ao uso do script apenas como uma ação Framework.

Descrição

Insira uma descrição do script desta ação API. Este texto é usado como uma dica de ferramenta quando você passa o cursor do mouse sobre a ação Studio criada a partir deste script.

Essa propriedade se aplica ao uso do script apenas como uma ação Framework.

Categoria

A pasta na guia Framework no Studio onde a ação criada a partir deste script se encontra. O padrão é Pessoal. Insira um novo nome neste campo para especificar uma pasta diferente. Se ele ainda não existir, a pasta é automaticamente criada quando você salva este script e a ação é automaticamente movida para ela.

Essa propriedade se aplica ao uso do script apenas como uma ação Framework.

Versão

A versão do script. Atualize este campo quando publicar uma nova versão do script, da mesma forma que faria com outras APIs. Este é um campo opcional.

Você pode usar essa propriedade para controlar a versão do script para a ação Framework ou REST API, ou ambos.

IncludeInApi

Defina IncludeInAPI como True se quiser que a API dessa ação de script personalizado seja executável por meio de um navegador da Web.

Ícone

O ícone da ação Framework da API. Este ícone aparece na lista de ações na guia Framework no Studio e na tela do script quando você adiciona a ação a um script Studio.

Clique nas reticências Uma série de três pontos. no campo Ícone para modificar o ícone padrão.

Essa propriedade se aplica ao uso do script apenas como uma ação Framework.

Compartilhado

Esta propriedade não é suportada no momento.

CaseParameter

Isso define o nome da propriedade de saída que aparece quando você usa esse script como uma ação do Framework em outro script. O nome que você definir aparecerá na lista de propriedades da ação da estrutura personalizada com (out) depois dele. Por exemplo, se você definir CaseParameter como CustomResult, a lista de propriedades da ação da estrutura personalizada mostrará uma propriedade chamada CustomResult (out).

HasDefault

Selecione True se quiser que a ação Framework criada a partir deste script tenha um ramal Padrão. Caso não queira o ramal padrão, selecione False A prática recomendada para todas as ações Studio é ter um ramal Padrão.

Essa propriedade se aplica ao uso do script apenas como uma ação Framework.

Parâmetros

Define os dados que entram no script, no script ou em ambos. Os parâmetros que você define são aplicados tanto para a ação Framework criada a partir deste script quanto para a REST API do script. Esses parâmetros se tornam as propriedades da ação Framework.

Criar parâmetros para personalizar os dados que o script manipula.

Essa propriedade se aplica ao uso do script como uma ação Framework e como um REST API.

Ramais

Define o resultado da execução deste script levando em conta os vários resultados possíveis. Você deve ter um ramal para erros, bem como para os outros possíveis resultados.

Crie condições de ramal para personalizar os valores de retorno do script.

Essa propriedade se aplica ao uso do script como uma ação Framework e como um REST API.