AnnA Web Service

AnnA Web Service is a resource that makes possible for you to interact with AnnA. With it you can compose the nodes of an AnnA Workflow so the bot can read and execute as you will

How it works

When creating a Web Service, you need to register your Web Service in AnnA, so it will generate the keys needed for encryption/decryption. Then add a Web Service node to your AnnA Workflow, and select the Web Service that will be executed.

Our system will call the Web Service that you registered, then will execute the containers in the order you added to the structure.

Using AnnAWebService class

For the AnnA WebService node, you will need the AnnaWebService class to instantiate and add containers to be executed.

Examples:

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

Adding a message container:

// The second parameter are the options, if you don't want to use them, just pass null
  annaWs.addMessageContainer("Hello", null);

You can do Method-Chaining when adding containers (Just like a builder):

  annaWs
      .addMessageContainer("Hello", null)
      .addTimeContainer(5, null);

Sample Code

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",
                // Every type of container has an options builder available
                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);
    }
}

Add Message container

Sends a message to the user

Parameters:

Message: Required. The text that will be sent to the user, e.g., Hello World!
Options
- Alias: Optional. Use it to identify the container after the WebService node runs, e.g., Hello123.
- RestrictToGroup: Optional. Fill in the aliases of user groups that are registered within the company.
- BeforeExecutionRule: Optional. Should be an expression. You can use AnnA Functions that returns “true” or “false” to decide if this container should run

Usage example

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

  annaWs
      .addMessageContainer("Message container",
          // In case you want to use the options from the container, use this builder, else just pass null
          AnnaMessageContainerOptions.builder()
              .Alias("Hello123")
              .build()
      );

Add ExecFunction container

Executes one or more AnnA Functions

Parameters:

Expression: Required. Write expressions with AnnA Functions here, e.g., AddParm(Test1,123) AddParm(Test,456)
Options
- Alias: Optional. Use it to identify the container after the WebService node runs, e.g., Function123.
- RestrictToGroup: Optional. Fill in the aliases of user groups that are registered within the company.
- BeforeExecutionRule: Optional. Should be an expression. You can use AnnA Functions that returns “true” or “false” to decide if this container should run

Usage example

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

  annaws.addExecFunctionContainer("ADDPARM(Teste,Hello)",
      // In case you want to use the options from the container, use this builder, else just pass null
      AnnaExecFunctionContainerOptions.builder()
          .Alias("ExecFunction123")
          .build()
  );

Add Time container

Wait some seconds before proceeding the containers execution flow

Parameters:

TimeToWait: Required. Sets the time in seconds to pause the execution.
Options
- Alias: Optional. Use it to identify the container after the WebService node runs, e.g., Time123.
- ShowMessage: Optional. Whether the message should be displayed or not. Defaults to ‘S’ (Show the message)
- Message: Optional. The text that will be sent to the user, e.g., Hello World!
- RestrictToGroup: Optional. Fill in the aliases of user groups that are registered within the company.
- BeforeExecutionRule: Optional. Should be an expression. You can use AnnA Functions that returns “true” or “false” to decide if this container should run

Usage example

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

  annaWs.addTimeContainer(5,
      // In case you want to use the options from the container, use this builder, else just pass null
      AnnaTimeContainerOptions.builder()
              .Alias("Time123")
              .build()
  );

Add Multimedia container

Sends media to the user, e.g. images, videos, audios, and documents.

Parameters:

MediaURL: Required. The download URL for a file, e.g., https://your.domain/route/to/file.extension
Options
- Alias: Optional. Use it to identify the container after the WebService node runs, e.g., Media123.
- Message: Optional. The text that will be sent to the user, e.g., Hello World!
- RestrictToGroup: Optional. Fill in the aliases of user groups that are registered within the company.
- BeforeExecutionRule: Optional. Should be an expression. You can use AnnA Functions that returns “true” or “false” to decide if this container should run

Usage example

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

  annaWs.addMultimediaContainer("https://learning.anna.center/Resources/AnnaIcon.png",
      // In case you want to use the options from the container, use this builder, else just pass null
      AnnaMultimediaContainerOptions.builder()
        .Alias("Media123")
        .Message("Message of the image")
        .build()
  );

Add Question container

Sends a question to the user

Parameters:

Question: Required. The question that will be sent to the user
Options
- Alias: Optional. Use it to identify the container after the WebService node runs, e.g., Function123.
- RestrictToGroup: Optional. Fill in the aliases of user groups that are registered within the company.
- BeforeExecutionRule: Optional. Should be an expression. You can use AnnA Functions that returns “true” or “false” to decide if this container should run.
- Competence: Optional. A competence already registered in the company. A new competence will be created if it does not exist in the company.
- Subject: Optional. A subject already registered in the company. A new subject will be created if it does not exist in the company.
- Topic: Optional. A topic within the subject. It will be created if it does not exist.
- IgnoreExecFluxo: Optional. Ignores other actions from the user aside from answering the actual question or ending all services
- SensitiveData: Optional. Pass ‘S’ to encrypt the answer using the company encryption key. Note that when retrieving the answer using AnnA Functions it will be encrypted as well. Defaults to ‘N’
- RightAnswer: Optional. Enable this resource if you want to check if the answer is in the possible answers array
- RightAnswerValue: Optional. The points that will be earned by the user if he answers correctly
- AnswerType: Optional. ‘N’ if you don’t want to send feedback about the answer. ‘Q’ if you want to send feedback. Defaults to ‘N’
- CorrectAnswerComment: Optional. When answerType is ‘Q’ then use this config to send a positive feedback to the user
- IncorrectAnswerComment: Optional. When answerType is ‘Q’ then use this config to send a negative feedback to the user
- DynamicValidations: Optional. Write expressions using AnnA Functions that returns TRUE or FALSE. The execution will continue when the expression returns TRUE
- ValidationError: Optional. Set a message for validation errors when dynamicValidations returns FALSE
- ValidationMask: Optional. Set a mask for the user answer
- ExternalData: Optional. It can store any information that you may want to retrieve with AnnA Functions, e.g., “LastAnswerJSON()” or “AnswersJSON()“
- PossibleAnswers: Optional. If “rightAnswer” is set to “S” then this property should be provided. A collection of strings containing the possible right answers to the question

Usage example

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

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

Add Alternative container

Sends a multiple-choice question to the user.

Parameters:

Question: Required. The question that will be sent to the user
Alternatives: Required. Array that contains the alternatives
- Alternative: Required. Text of the alternative
- Alias: Optional. Alias of the alternative, can be used to identify the user answer in subsequent nodes
- RestrictToGroup: Optional. Fill in the aliases of user groups that are registered within the company.
- ExhibitionRule: Optional. Use AnnA Functions to write an expression that returns TRUE or FALSE. If the expression returns TRUE then the container will be executed.
- IsCorrectAnswer: Optional. Only available when the “rightAnswer” option is set to ‘S’. Use ‘S’ to mark the alternative as correct answer.
- AlternativeValue: Optional. A value to the alternatives that will be used in statistics.
- Order: Optional. Order of the alternative.
- Comment: Optional. Optional. Message that will be sent to the user after he select the alternative
Options
- Alias: Optional. Use it to identify the container after the WebService node runs, e.g., Function123.
- RestrictToGroup: Optional. Fill in the aliases of user groups that are registered within the company.
- BeforeExecutionRule: Optional. Should be an expression. You can use AnnA Functions that returns “true” or “false” to decide if this container should run
- Competence: Optional. A competence already registered in the company. A new competence will be created if it does not exist in the company.
- Subject: Optional. A subject already registered in the company. A new subject will be created if it does not exist in the company.
- Topic: Optional. A topic within the subject. It will be created if it does not exist.
- Enumeration: Optional. Set the enumeration of the alternatives. N = Numbers, L = Letters, R = Roman, I = List (WhatsApp Popup), B = Buttons (WhatsApp Buttons)
- Randomize: Optional. Pass ‘S’ to shuffle the alternatives. Defaults to ‘N’
- RightAnswer: Optional. Enable this resource if you want to check if the answer is in the possible answers array
- AnswerType: Optional. ‘N’ if you don’t want to send feedback about the answer. ‘Q’ if you want to send feedback. Defaults to ‘N’
- AnswerTypeComment: Optional. The message that will be sent when the user answers the question
- ExternalData: Optional. It can store any information that you may want to retrieve with AnnA Functions, e.g., “LastAnswerJSON()” or “AnswersJSON()“

Usage example

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