AnnA.Services 1.0.0

A simple library to integrate with AnnA application

AnnA Web Service Integration

Using AnnAWebService class

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

Notes:

• Encryption and decryption keys are required
• The Initialization Vector (IV) value is sent to your Web Service in the ANNAEXEC post variable

Examples:

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

or

var annaWs = new AnnaWebService();
annaWS.EncryptionKey = YourEncryptionKey;
annaWS.DecryptionKey = YourDecryptionKey;
annaWS.InitializationVector = ivFromANNAEXEC;

or

var annaWs = new AnnaWebService(
    new AnnaWebServiceConfig() 
    { 
        EncryptionKey = YourEncryptionKey, 
        DecryptionKey = YourDecryptionKey, 
        InitializationVector = ivFromANNAEXEC
    }
);

Adding a message container:

annaWs.AddMessageContainer("Hello AnnA!");

You can do Method-Chaining when adding containers:

annaWs.AddMessageContainer("Hello AnnA!").AddTimeContainer(5);

Sample code

// Encryption and Decryption keys are available when you register a new Web Service in AnnA
string encryptionKey = "YOUR_ENCRYPTION_KEY";
string decryptionKey = "YOUR_DECRYPTION_KEY";
string iv = form.Get("ANNAEXEC"); // form is a FormDataCollection, the IV will be sent to your API Route in the ANNAEXEC post variable

// Create a new AnnaWS object then add some containers to it
var annaWs = new AnnaWebService(encryptionKey, decryptionKey, iv);
annaWs
    .AddMessageContainer("Hello AnnA!")
    .AddQuestionContainer("What is 1 + 1?", new QuestionContainerOptions
    {
        RightAnswer = "S",
        PossibleAnswers = new string[] { "2", "two" }
    });

// Now get the encrypted containers
string encryptedContainers = annaWs.GetEncryptedContainers();

// Send the response back to AnnA
// Note: In .NET 5+ applications it is not required to create the HttpResponseMessage object,
// simply returning "encryptedContainers" will produce the same results
var response = new HttpResponseMessage(HttpStatusCode.OK);
response.Content = new StringContent(encryptedContainers, Encoding.UTF8, "text/plain");
return response;

AddMessageContainer

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

var annaWs = new AnnaWebService(encryptionKey, decryptionKey, iv);
annaWs.AddMessageContainer("Hello AnnA!");

AddExecFunctionContainer

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

var annaWs = new AnnaWebService(encryptionKey, decryptionKey, iv);
annaWS.AddExecFunctionContainer("AddParm(Test1,123) AddParm(Test2,456)");

AddTimeContainer

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

var annaWs = new AnnaWebService(encryptionKey, decryptionKey, iv);
annaWs.AddTimeContainer(5); // Wait 5 seconds

AddMultimediaContainer

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

var annaWs = new AnnaWebService(encryptionKey, decryptionKey, iv);
annaWS.AddMultimediaContainer("https://learning.anna.center/Resources/AnnaIcon.png", new MultimediaContainerOptions
{
    Message = "Message of the image"
});

AddQuestionContainer

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

var annaWs = new AnnaWebService(encryptionKey, decryptionKey, iv);
annaWS.AddQuestionContainer("What is 1 + 1?", new QuestionContainerOptions
{
    RightAnswer = "S",
    PossibleAnswers = new string[] { "2", "two" }
});

AddAlternativeContainer

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

List<AnnaAlternative> alternatives = new List<AnnaAlternative>()
{
    new AnnaAlternative
    {
        Alias = "Alternative001",
        Alternative = "2 two",
        Order = "1",
        IsCorrectAnswer = "S"
    },
    new AnnaAlternative
    {
        Alias = "Alternative002",
        Alternative = "5 five",
        Order = "2",
        IsCorrectAnswer = "N"
    }
};

var annaWs = new AnnaWebService(encryptionKey, decryptionKey, iv);
annaWS.AddAlternativeContainer("What is 1 + 1?", alternatives);

AnnA Templates - Sending Active Notifications

Using AnnaTemplate class

This class will provide you a simple way to send active notifications to your clients

Notes:

• Encryption and decryption keys are required
• The base URL of your AnnA environment is required
  • Example of AnnA environment base URL: https://learning.anna.center

Examples:

var template = new AnnaTemplate("YOUR_ANNA_ENVIRONMENT_BASE_URL");
template.CompanyHash = "YOURCOMPANYHASH";
template.EncryptionKey = "YOUR_TEMPLATES_ENCRYPTION_KEY";
template.DecryptionKey = "YOUR_TEMPLATES_DECRYPTION_KEY";
template.TemplateName = "TEMPLATE_NAME";
template.TemplateNamespace = "TEMPLATE_NAMESPACE";
template.Notifications = new List<AnnaNotification>(); // List of notification objects that contains PhoneList, PropKeys and PropParms

or

var template = new AnnaTemplate("YOUR_ANNA_ENVIRONMENT_BASE_URL", new AnnaTemplateConfig
{
    CompanyHash = "YOURCOMPANYHASH",
    EncryptionKey = "YOUR_TEMPLATES_ENCRYPTION_KEY",
    DecryptionKey = "YOUR_TEMPLATES_DECRYPTION_KEY",
    TemplateName = "TEMPLATE_NAME",
    TemplateNamespace = "TEMPLATE_NAMESPACE",
    Notifications = new List<AnnaNotification>() // List of notification objects that contains PhoneList, PropKeys and PropParms
});

Usage example

// Create notification
var notification = new AnnaNotification
{
    PhoneList = new List<string> { "5511111111111", "5522222222222" }, // List of phonenumbers
    PropKeys = new List<string> { "Variable 1" }, // List with the values of variables from the template
    PropParms = new List<PropParm> 
    { 
        new PropParm { Alias = "parm1", Value = "value1" },
        new PropParm { Alias = "parm2", Value = "value2" }
    }
};

// Add notification to the list
var notificationsList = new List<AnnaNotification> { notification };

// Create the template, set the configurations and notifications list
var template = new AnnaTemplate("YOUR_ANNA_ENVIRONMENT_BASE_URL", new AnnaTemplateConfig
{
    CompanyHash = "YOURCOMPANYHASH",
    EncryptionKey = "YOUR_TEMPLATES_ENCRYPTION_KEY",
    DecryptionKey = "YOUR_TEMPLATES_DECRYPTION_KEY",
    TemplateName = "TEMPLATE_NAME",
    TemplateNamespace = "TEMPLATE_NAMESPACE",
    Notifications = notificationsList
});

template.SendNotifications(); // Send the notifications