AnnA.Services
1.0.1
See the version list below for details.
dotnet add package AnnA.Services --version 1.0.1
NuGet\Install-Package AnnA.Services -Version 1.0.1
<PackageReference Include="AnnA.Services" Version="1.0.1" />
paket add AnnA.Services --version 1.0.1
#r "nuget: AnnA.Services, 1.0.1"
// Install AnnA.Services as a Cake Addin #addin nuget:?package=AnnA.Services&version=1.0.1 // Install AnnA.Services as a Cake Tool #tool nuget:?package=AnnA.Services&version=1.0.1
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
});
string response = template.SendNotifications(); // Send the notifications and returns a JSON
Note: If the phonelist contains a large number of entries, notifications will be queued, and the response will be an empty array
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- RestSharp (>= 110.2.0)
- System.Text.Json (>= 7.0.3)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
The SendNotifications method now returns a JSON with the status of the notifications.