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