BAM dotnet library

This article describes how to track activities from your dotnet applications using a dotnet library. Currently with services like Logic Apps, Microsoft Flow and Powerapps we provide a custom connector which you can deploy in your subscription if you want to track activities. For other services you can use our Azure Functions to track activities. But since it is hard for every customer to implement their own logic for comminicating our APIs we have decided to build this library ourself and make it publicly available for all our customers.

We think this library can reduce your development effort significantly

Scenarios

This SDK will work on your applications irrespective of where or how the application is run. The only requirement is the application that is hosting the library needs to have access to Azure. Since the library is build on .Net standard you can use this library in any operating system (Windows, Linux, Mac).

Prerequisites

1. Install the Bam package in your application

>Install-Package Kovai.Serverless360.Bam

2. Copy the access key from the Serverless360 portal

Getting Started

To follow this step by step guide please import the business process configuration in your Serverless360 subscription.

Once you have package and the key. Instantiate the ActivityService class with the following code

var processor = new LogisticsProcessor(new ActivityService("Pass your access code"));

Start Activity

var receiveResponse = _service.StartActivity(new StartActivityRequest
{
    BusinessProcess = "Ship Any Where Logistics",
    BusinessTransaction = "Booking Request",
    CurrentStage = "Receive",
    PreviousStage = ".",
    IsArchiveEnabled = true,
    MessageBody = "{\"some\":1}",
    MessageHeader = "{\"some\":1}",
})

The StartActivity requires the following parameters

Business Process - Business Process name that is configured in the portal
Business Transaction - Business Transaction name that is configured in the portal
Current Stage - Current Stage name that you want to start
Previous Stage - Previous Stage name which happened before the current stage. If this stage is the first stage in the transaction flow you can leave this property or just pass (.)
IsArchiveEnabeld - This flag is used to enable and disable the archive capability.
Message Body - Used to archive message body. Remember that if you have json message make sure you deserialize it before passing them to the methods
Message Header - Used to archive the message context.
MainActivityId - If this is the first stage in the transaction you dont need to pass this parameter, but if you want to associate this stage with an already existing transaction you need to pass the MainActivityId that is returned from the previous transaction.

By default whenever you start an activity it will be marked as in progress until you issue an update activity request.

Update Activity

Once a stage is stage is started you can perform one or more updates to the same stage activity using the Update Activity API

_service.UpdateActivity(new UpdateActivityRequest()
{
    BusinessProcess = "Ship Any Where Logistics",
    BusinessTransaction = "Booking Request",
    CurrentStage = "Receive",
    MainActivityId = receiveResponse.MainActivityId,
    StageActivityId = receiveResponse.StageActivityId,
    Status = StageStatus.Success,
    MessageBody = "{\"some\":1}",
    MessageHeader = "{\"some\":1}",
});

Update activity is similar to start activity except you need to provide two additional fields StageActivityId and Status

Log Exception Activity

This action allows you to log a business exception against a particular stage

_service.LogExceptionActivity(new LogExceptionActivityRequest
{
    BusinessProcess = "Ship Any Where Logistics",
    StageActivityId = sendResponse.StageActivityId,
    ExceptionMessage = "Sample Error Message",
    ExceptionCode = "ERR001"
});

ExceptionCode - An exception code that maps to a particular business exception
Exception Message - More details business exception description

How to use the library in Azure Function

As we already seen in the getting started section installing Kovai.Serverless360.Bam is pretty straight forward in Azure Function as well. In your Azure Function project

1. Install the Bam package in your application

>Install-Package Kovai.Serverless360.Bam

2. Use the Activity Service to start logging activities to the portal

namespace Kovai.Samples.FuncApp
{
    public static class Logistics
    {
        [FunctionName("BookingRequest")]
        public static async Task<IActionResult> Run(
        [HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = null)] HttpRequest req,
        ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

            IActivityService service = new ActivityService("V9sOiZ6eE0jDjq25zFpKEzejlk2jAija4cCqU290b15qcoi8/iynvw==");
            var response = await service.StartActivity(new StartActivityRequest()
            {
            BusinessProcess = "Ship Any Where Logistics",
            BusinessTransaction = "Booking Request",
            CurrentStage = "Receive",
            PreviousStage = ".",
            IsArchiveEnabled = true,
            MessageBody = "{\"some\":1}",
            MessageHeader = "{\"some\":1}",
            });

            return new OkObjectResult(response);
        }
    }
}

Logging

The library is designed in a way that it will not throw any exceptions if something goes wrong in the BAM processing since we don't want to disrupt the actual business process flow.

However if something goes wrong you would want to get notified or perhaps you might want to log it somewhere so that you can go and look at a later point of time. To handle this the library has a logging interface which you can make use of.

If you want to have some king of logging when you are a instantiating you can pass a IBamActivityLogger interface to the ActivityService instance.

For example let say you have log4net in your application and you want Bam library to use the log4net and write to files. You can wrap you log4net logging as IBamActivityLogger

public class MyCustomLogger : IBamActivityLogger
{
    private static readonly log4net.ILog log = log4net.LogManager.GetLogger(System.Reflection.MethodBase.GetCurrentMethod().DeclaringType);
    public void Debug(string message)
    {
        log.Debug(message);
    }
    public void Info(string message)
    {
        log.Info(message);
    }
    public void Warning(string message)
    {
        log.Warn(message);
    }
    public void Error(string message)
    {
        log.Error(message);
    }
    public void Fatal(string message)
    {
        log.Fatal(message);
    }
}

and when you are instantiating a Activity Service object you can use the overload for accpeting custom logging component.

IActivityService service = new ActivityService("you key", new MyCustomLogger());