V2 Tracking API's

From Atomic Scope 7.0, we brought some fresh set of API's for logging activities. If you have any REST API application and you want to log activities to Atomic Scope you can make use of this API.

The new route for the API is http://localhost/atomicscope/api/tracking-v2/activities. You can do all the activities like Start/ Update / Exception / Archive from a single API now 😎

API Operation Type

To log the different type of activities you need to use this key called AS-Operation with corresponding values.

		Start = 0,
		Update = 1,
		Archive = 2,
		Exception =3,
		Log = 4

In our previous API's for tracking there was a confusion and it was not aligned properly. Some properties needed by Atomic Scope was asked to pushed within message body which was not a very good approach. In this implementation you don't have to modify your original message body.

All the properties which are needed for Atomic Scope to track is accepted in the HTTP-Headers as a Key-Value pair.

Stage Status

To Log the status of the stage you need to provide values with the key as-stagestatus with any below value.

Unknown = 0,
Success = 1,
Failure = 2,
InProgress = 3

Available Properties

		{"AS-ResourceId", true},
		{"AS-BusinessProcess",true},
		{"AS-BusinessTransaction",true},
		{"AS-CurrentStage",true},
		{"AS-StageStatus",false},
    {"AS-Operation",true},
		{"AS-PreviousStage",false},
		{"AS-StartedOn",false},
		{"AS-MainActivityId",false},
		{"AS-StageActivityId",false},
		{"AS-ArchiveMessage",false},
		{"AS-ExceptionMessage",false},
		{"AS-ExceptionCode",false}

All the available properties which you can send in the headers are mentioned above. You might be wondering what is that true/false flag next to the property name. It indicates whether a property is Mandatory or not.

If a property is marked as mandatory, without it Atomic Scope won't be able to track activities. But what if casually or unknowingly I missed some property which I am not aware of ?

You don't have to worry, as Atomic Scope will indicate you, what is gone wrong and what did you miss ? The below error is an example.

{
  "message": "An error has occurred.",
  "exceptionMessage": "Invalid Request : AS-ResourceId header is missing from the HTTP Request.",
  "exceptionType": "Kovai.AtomicScope.Core.Exceptions.InvalidRequestException",
  "stackTrace": "   at Kovai.AtomicScope.Engine.Services.ApiTrackingService.HasErrors(List`1 errors)\r\n   at Kovai.AtomicScope.Engine.Services.ApiTrackingService.GetPropertiesFromHeaders(NameValueCollection collection)\r\n   at Kovai.AtomicScope.Engine.Services.ApiTrackingService.<TrackActivities>d__8.MoveNext()"
}

Example Activity

In the headers you need to add the Mandatory properties. Refer Available Properties section to know which properties are mandatory.

Here the Receive Order is my first stage, so I'm start providing the Previous Stage as .

Once any activity is competed you will get the API response with the below json.

{
  "status": true,
  "data": {
    "mainActivityId": "94f797c6-6dc2-4b1d-84a3-ba95c3cdc43e",
    "stageActivityId": "e9ad872d-1b2f-45f7-97a3-1308e5645059"
  }
}

In order to do further activites like Update / Archive or Log Exception you will have to pass these values in the headers.

Log Activity

This is a one time request where Atomic Scope will automatically do Start / Update together. You need to make use of the AS-Operation flag with 4 for consuming this. You can also control whether to Archive the message or not by making use of As-ArchiveMessage set to true

Continuation

This is a brand new feature which we are bringing in Atomic Scope V7.0. In versions less than V7 , i.e .. current implementation, we won't we able to start a new stage on the same transaction without supplying MainActivityId and PreviousStage But from now on, you don't have to worry about them. You can Start/ Update an activity at any point of time without the above dependencies.

How can it be achieved ?

This is achieved with the help of Global properties. Imagine you are tracking a property called SenderId in your first stage. Now to achieve continuation for upcoming stages without providing MainActivityId and PreviousStage you need to add the same senderId property to the upcoming stages and mark Continuation property to TRUE.

Now you can simply try to initiate the activity, and we will automatically correlate it for you.

FAQ:

• In some cases where you might already have the same transaction with the same property tracked which is already available on the Atomic Scope database. Now when a new activity comes with the same property value, Atomic Scope will correlate it like below example
• If only 1 result is found = Directly used
• If more than 1 results are found = Atomic Scope picks the most recent one.
• If no results are found = Then it will be logged as a new transaction.
• It is up to the user to configure Atomic Scope correctly for whatever property to add for continuation.

What if multiple properties are configured with Continuation ?

If so, when a new activity comes the activity should contain values for all of the properties which are marked and the value should match. Even if one value doesn't match, then Atomic Scope will log the result as a new transaction.