Pular para o conteúdo
AnnA Docs

AnnA Web Service

O AnnA Web Service é um recurso que possibilita a interação com a AnnA. Com ele, você pode compor os nós de um Fluxo de Trabalho da AnnA para que o bot possa ler e executar conforme desejar.

Como funciona

Ao criar um Web Service, você precisa registrá-lo na AnnA, para que ela gere as chaves necessárias para criptografia/descriptografia. Em seguida, adicione um nó de Web Service ao seu Fluxo de Trabalho da AnnA e selecione o Web Service que será executado.

Nosso sistema chamará o Web Service que você registrou e em seguida executará os contêiners na ordem que você os adicionou à estrutura.

Utilizando a classe AnnAWebService

Para o nó de Web Service da AnnA, você precisará da classe AnnaWebService para instanciar e adicionar contêiners a serem executados.

Exemplos:

  AnnaWebService annaWs = new AnnaWebService(encryptionKey, decryptionKey, iv);

Adicionando um contêiner de mensagem:

// O segundo parâmetro são as opções; se não deseja usá-las, basta passar nulo.
  annaWs.addMessageContainer("Hello", null);

Você pode fazer Encadeamento de Métodos ao adicionar contêiners (Como em um builder):

  annaWs
      .addMessageContainer("Hello", null)
      .addTimeContainer(5, null);
Código de exemplo
package center.anna.demoannaservices.annaws;


import center.anna.annawebservices.AnnaAlternative;
import center.anna.annawebservices.AnnaWebService;
import center.anna.annawebservices.options.*;
import org.springframework.http.*;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;


import java.nio.charset.StandardCharsets;
import java.util.ArrayList;


@RestController
@RequestMapping("/AnnaWS")
public class Sample {


    @PostMapping(value = "/", produces = MediaType.TEXT_PLAIN_VALUE)
    public ResponseEntity<String> annaWsTest(@RequestParam(name = "ANNAEXEC") String iv) {
        String encryptionKey = "YOUR_ENCRYPTION_KEY";
        String decryptionKey = "YOUR_DECRYPTION_KEY";


        AnnaWebService annaWs = new AnnaWebService(encryptionKey, decryptionKey, iv);


        annaWs
            .addMessageContainer("Hello",
                // Cada tipo de container possui um construtor de opções disponível.
                AnnaMessageContainerOptions.builder()
                    .Alias("Hello123")
                    .build()
            )
            .addQuestionContainer("1 + 1 = ?",
                AnnaQuestionContainerOptions.builder()
                    .Alias("Question123")
                    .RightAnswer("S")
                    .PossibleAnswers(new String[]{"dois", "two", "2"})
                    .build()
            );


        HttpHeaders httpHeaders = new HttpHeaders();
        httpHeaders.setContentType(new MediaType("text", "plain", StandardCharsets.UTF_8));


        var responseData = annaWs.getEncryptedContainers();


        return new ResponseEntity<>(responseData, httpHeaders, HttpStatus.OK);
    }
}

Adicionando contêiner de mensagem

Envia uma mensagem para o usuário

Parâmetros:

  • Message: Obrigatório. O texto que será enviado ao usuário, por exemplo, Olá Mundo!
  • Opções
    • Alias: Opcional. Use para identificar o contêiner após a execução do nó do Web Service, por exemplo, Hello123.
    • RestrictToGroup: Opcional. Preencha com os apelidos dos grupos de usuários registrados na empresa.
    • BeforeExecutionRule: Opcional. Deve ser uma expressão. Você pode usar Funções da AnnA que retornem “true” ou “false” para decidir se este contêiner deve ser executado.
Exemplo de utilização
  AnnaWebService annaWs = new AnnaWebService(encryptionKey, decryptionKey, iv);


  annaWs
      .addMessageContainer("Message container",
          // Caso queira utilizar as opções do contêiner, utilize este construtor; do contrário, apenas passe nulo.
          AnnaMessageContainerOptions.builder()
              .Alias("Hello123")
              .build()
      );

Adicionando contêiner ExecFunction

Executa uma ou mais Funções da AnnA.

Parâmetros:

  • Expression: Obrigatório. Escreva expressões com Funções da AnnA aqui, por exemplo, AddParm(Teste1,123) AddParm(Teste,456)
  • Opções
    • Alias: Opcional. Use para identificar o contêiner após a execução do nó do Web Service, por exemplo, Function123.
    • RestrictToGroup: Opcional. Preencha com os apelidos dos grupos de usuários registrados na empresa.
    • BeforeExecutionRule: Opcional. Deve ser uma expressão. Você pode usar Funções da AnnA que retornem “true” ou “false” para decidir se este contêiner deve ser executado.
Exemplo de utilização
  AnnaWebService annaWs = new AnnaWebService(encryptionKey, decryptionKey, iv);


  annaws.addExecFunctionContainer("ADDPARM(Teste,Hello)",
      // Caso queira utilizar as opções do contêiner, utilize este construtor; do contrário, apenas passe nulo.
      AnnaExecFunctionContainerOptions.builder()
          .Alias("ExecFunction123")
          .build()
  );

Adicionando contêiner de Tempo

Espere alguns segundos antes de prosseguir com o fluxo de execução dos contêineres.

Parâmetros:

  • TimeToWait: Obrigatório. Define o tempo em segundos para pausar a execução.
  • Opções
    • Alias: Opcional. Use para identificar o contêiner após a execução do nó do Web Service, por exemplo, Time123.
    • ShowMessage: Opcional. Se a mensagem deve ser exibida ou não. O padrão é ‘S’ (Mostrar a mensagem).
    • Message: Opcional. O texto que será enviado ao usuário, por exemplo, Olá Mundo!
    • RestrictToGroup: Opcional. Preencha com os apelidos dos grupos de usuários registrados na empresa.
    • BeforeExecutionRule: Opcional. Deve ser uma expressão. Você pode usar Funções da AnnA que retornem “true” ou “false” para decidir se este contêiner deve ser executado.
Exemplo de utilização
  AnnaWebService annaWs = new AnnaWebService(encryptionKey, decryptionKey, iv);


  annaWs.addTimeContainer(5,
      // Caso queira utilizar as opções do contêiner, utilize este construtor; do contrário, apenas passe nulo.
      AnnaTimeContainerOptions.builder()
              .Alias("Time123")
              .build()
  );

Adicionando contêiner Multimídia

Envia mídia para o usuário, como imagens, vídeos, áudios e documentos.

Parâmetros:

  • MediaURL: Obrigatório. O URL de download para um arquivo, por exemplo, https://your.domain/route/to/file.extension
  • Opções
    • Alias: Opcional. Use para identificar o contêiner após a execução do nó do Web Service, por exemplo, Media123.
    • Message: Opcional. O texto que será enviado ao usuário, por exemplo, Olá Mundo!
    • RestrictToGroup: Opcional. Preencha com os apelidos dos grupos de usuários registrados na empresa.
    • BeforeExecutionRule: Opcional. Deve ser uma expressão. Você pode usar Funções da AnnA que retornem “true” ou “false” para decidir se este contêiner deve ser executado.
Exemplo de utilização
  AnnaWebService annaWs = new AnnaWebService(encryptionKey, decryptionKey, iv);


  annaWs.addMultimediaContainer("https://learning.anna.center/Resources/AnnaIcon.png",
      // Caso queira utilizar as opções do contêiner, utilize este construtor; do contrário, apenas passe nulo.
      AnnaMultimediaContainerOptions.builder()
        .Alias("Media123")
        .Message("Message of the image")
        .build()
  );

Adicionando contêiner de Questão

Envia uma pergunta para o usuário

Parâmetros:

  • Question: Obrigatório. A pergunta que será enviada ao usuário
  • Opções
    • Alias: Opcional. Use para identificar o contêiner após a execução do nó do Web Service, por exemplo, Function123.
    • RestrictToGroup: Opcional. Preencha com os apelidos dos grupos de usuários registrados na empresa.
    • BeforeExecutionRule: Opcional. Deve ser uma expressão. Você pode usar Funções da AnnA que retornem “true” ou “false” para decidir se este contêiner deve ser executado..
    • Competence: Opcional. Uma competência já registrada na empresa. Uma nova competência será criada se não existir na empresa.
    • Subject: Opcional. Um assunto já registrado na empresa. Um novo assunto será criado se não existir na empresa.
    • Topic: Opcional. Um tópico dentro do assunto. Será criado se não existir.
    • IgnoreExecFluxo: Opcional. Ignora outras ações do usuário além de responder à pergunta atual ou encerrar todos os serviços.
    • SensitiveData: Opcional. Informe ‘S’ para criptografar a resposta usando a chave de criptografia da empresa. Observe que ao recuperar a resposta usando as Funções da AnnA, ela também estará criptografada. O padrão é ‘N’.
    • RightAnswer: Opcional. Ative este recurso se desejar verificar se a resposta está no array de respostas possíveis.
    • RightAnswerValue: Opcional. Os pontos que serão ganhos pelo usuário se ele responder corretamente.
    • AnswerType: Opcional. ‘N’ se não deseja enviar feedback sobre a resposta. ‘Q’ se deseja enviar feedback. Padrão é ‘N’.
    • CorrectAnswerComment: Opcional. Quando answerType for ‘Q’, use esta configuração para enviar um feedback positivo ao usuário.
    • IncorrectAnswerComment: Opcional. Quando o answerType for ‘Q’, use esta configuração para enviar um feedback negativo ao usuário.
    • DynamicValidations: Opcional. Escreva expressões usando Funções da AnnA que retornem TRUE ou FALSE. A execução continuará quando a expressão retornar TRUE.
    • ValidationError: Opcional. Defina uma mensagem para erros de validação quando dynamicValidations retornar FALSE.
    • ValidationMask: Opcional. Defina uma máscara para a resposta do usuário.
    • ExternalData: Opcional. Pode armazenar qualquer informação que você deseje recuperar com Funções da AnnA, por exemplo, “LastAnswerJSON()” ou “AnswersJSON()“.
    • PossibleAnswers: Opcional. Se “rightAnswer” estiver definido como “S”, então esta propriedade deve ser fornecida. Uma coleção de strings contendo as possíveis respostas corretas para a pergunta.
Exemplo de utilização
  AnnaWebService annaWs = new AnnaWebService(encryptionKey, decryptionKey, iv);


  annaWs.addQuestionContainer("1 + 1 = ?",
      AnnaQuestionContainerOptions.builder()
          .Alias("Question123")
          .RightAnswer("S")
          .PossibleAnswers(new String[]{"dois", "two", "2"})
          .build()
  );

Adicionando contêiner de Alternativa

Envia uma pergunta de múltipla escolha para o usuário.

Parâmetros:

  • Question: Obrigatório. A pergunta que será enviada ao usuário
  • Alternatives: Obrigatório. Array que contém as alternativas.
    • Alternative: Obrigatório. Texto da alternativa.
    • Alias: Opcional. Alias da alternativa, pode ser usado para identificar a resposta do usuário em nós subsequentes.
    • RestrictToGroup: Opcional. Preencha com os apelidos dos grupos de usuários registrados na empresa.
    • ExhibitionRule: Opcional. Use Funções da AnnA para escrever uma expressão que retorne TRUE ou FALSE. Se a expressão retornar TRUE, o contêiner será executado.
    • IsCorrectAnswer: Opcional. Disponível apenas quando a opção “rightAnswer” é definida como ‘S’. Use ‘S’ para marcar a alternativa como resposta correta.
    • AlternativeValue: Opcional. Um valor para as alternativas que será usado em estatísticas.
    • Order: Opcional. Ordem da alternativa.
    • Comment: Opcional. Mensagem que será enviada ao usuário depois que ele selecionar a alternativa.
  • Opções
    • Alias: Opcional. Use para identificar o contêiner após a execução do nó do Web Service, por exemplo, Function123.
    • RestrictToGroup: Opcional. Preencha com os apelidos dos grupos de usuários registrados na empresa.
    • BeforeExecutionRule: Opcional. Deve ser uma expressão. Você pode usar Funções da AnnA que retornem “true” ou “false” para decidir se este contêiner deve ser executado.
    • Competence: Opcional. Uma competência já registrada na empresa. Uma nova competência será criada se não existir na empresa.
    • Subject: Opcional. Um assunto já registrado na empresa. Um novo assunto será criado se não existir na empresa.
    • Topic: Opcional. Um tópico dentro do assunto. Será criado se não existir.
    • Enumeration: Opcional. Defina a enumeração das alternativas. N = Números, L = Letras, R = Romanos, I = Lista (Popup no WhatsApp), B = Botões (Botões no WhatsApp)
    • Randomize: Opcional. Informe ‘S’ para embaralhar as alternativas. Padrão é ‘N’.
    • RightAnswer: Opcional. Ative este recurso se desejar verificar se a resposta está no array de respostas possíveis.
    • AnswerType: Opcional. ‘N’ se não deseja enviar feedback sobre a resposta. ‘Q’ se deseja enviar feedback. Padrão é ‘N’.
    • AnswerTypeComment: Opcional. A mensagem que será enviada quando o usuário responder à pergunta.
    • ExternalData: Opcional. Pode armazenar qualquer informação que você deseje recuperar com Funções da AnnA, por exemplo, “LastAnswerJSON()” ou “AnswersJSON()“.
Exemplo de utilização
  var alternatives = new ArrayList<AnnaAlternative>();


  alternatives.add(
      AnnaAlternative.builder()
          .Alias("Alternative001")
          .Alternative("2 two")
          .Order("1")
          .IsCorrectAnswer("S")
          .build()
  );


  alternatives.add(
      AnnaAlternative.builder()
          .Alias("Alternative002")
          .Alternative("5 five")
          .Order("2")
          .build()
  );


  AnnaWebService annaWs = new AnnaWebService(encryptionKey, decryptionKey, iv);


  annaWs.addAlternativeContainer(
      "1 + 1 = ?",
      alternatives,
      AnnaAlternativeContainerOptions.builder()
          .Alias("Alternative123")
          .RightAnswer("S")
          .build()
  );