MAGES 5 Analytics Architecture¶

MAGES 5 uses a T-SQL relational model to store analytics data.

Analytics data is stored based on the above relational diagram.

When uploading a session’s analytics, Analytics API stores the data as follows:

User Applications
Application Sessions
Sessions

Note

A User-Application relationship is one-to-many. A user may have analytics in many applications
An Application-Session relationship is one-to-many. An application has many sessions
Session holds the session analytics for each application

The base functionalities of Analytics API are

Upload Analytics
Get Analytics

Important

To use Analytics API for debugging and testing you will have to use a API debug tool like Postman

The request to upload analytics:

[HttpPost("uploadnxt/{version}")]
public async Task<IActionResult> UploadAnalyticsNXT([FromBody] string _analytics, [FromRoute] string version)
{
    string clientId = TokenHelper.GetClientId(User);
    if (!clientId.Equals("UnityModuleWithoutSSO") &&
        !clientId.Equals("SDKORamaVRUnityClient") &&
        !clientId.Equals("UnityModule"))
    {
        return Unauthorized();
    }

    var res = "";
    if ((res = await _uploadService.UploadAnalyticsNXT(_analytics, version)) != "true")
    {
        return BadRequest(res);
    }

    return Ok("Upload Complete");
}

This endpoint’s URL is:

http://localhost:5002/api/upload/uploadnxt

The request to retrieve a session:

[HttpGet("analyticsnxt")]
public async Task<IActionResult> GetNXTAnalytics(string username, string productName, int sessionNumber)
{
    var res = await _analyticsService.DownloadAnalyticsNXT(username, productName, sessionNumber);
    if (res == null)
        return BadRequest("No analytics found for user: " + username + " and product: " + productName);

    return Ok(res);
}

This endpoint’s URL is:

http://localhost:5002/analytics/analyticsnxt

Upload Analytics uses JSON formatted strings as arguments.

Hint

The following example demonstrates a single-player MAGES 5 session You can use this for testing on Analytics API but, in case you go with Postman, the JSON needs to be stringified first!

{
"Report": [
    {
    "OperationReport": [
        {
        "OperationName": "Example Project",
        "Username": "user1",
        "FinalScore": 69.44444,
        "Errors": 5,
        "Objectives": 7,
        "Events": 11,
        "Scores": 9,
        "Duration": 101.5
        }
    ]
    }
],
"Events": [
    {
    "SessionStartedEvent(1)": [
        {
        "Name": "SessionStartedEvent(1)",
        "Timestamp": 0.0
        }
    ],
    "ActionPerformedEvent(1)": [
        {
        "Name": "ActionPerformedEvent(1)",
        "Timestamp": 13.37,
        "Action": "Injection Question"
        }
    ],
    "ActionPerformedEvent(2)": [
        {
        "Name": "ActionPerformedEvent(2)",
        "Timestamp": 43.35,
        "Action": "Pour Alcohol on cotton ball"
        }
    ],
    "ActionPerformedEvent(3)": [
        {
        "Name": "ActionPerformedEvent(3)",
        "Timestamp": 59.16,
        "Action": "Disinfect skin area"
        }
    ],
    "ActionPerformedEvent(4)": [
        {
        "Name": "ActionPerformedEvent(4)",
        "Timestamp": 73.14,
        "Action": "Dispose the Cotton Ball"
        }
    ],
    "SessionEndedEvent(1)": [
        {
        "Name": "SessionEndedEvent(1)",
        "Timestamp": 101.5
        }
    ]
    }
],
"Errors": [
    {
    "Injection Question(1).Wrong Answer Error(1)": [
        {
        "Name": "Injection Question(1).Wrong Answer Error(1)",
        "Timestamp": 13.37,
        "Action": "Injection Question",
        "Type": "KnowledgeGap",
        "Penalty(%)": 100,
        "Info": "The wrong answer was chosen in the Injection Question"
        }
    ],
    "Pour Alcohol on cotton ball(1).CollisionError1(1)": [
        {
        "Name": "Pour Alcohol on cotton ball(1).CollisionError1(1)",
        "Timestamp": 22.28,
        "Action": "Pour Alcohol on cotton ball",
        "Type": "DecisionMaking",
        "Penalty(%)": 25,
        "Info": "Do not drop the cotton ball to the floor."
        }
    ],
    "Pour Alcohol on cotton ball(1).TimeLimitError(2)": [
        {
        "Name": "Pour Alcohol on cotton ball(1).TimeLimitError(2)",
        "Timestamp": 43.35,
        "Action": "Pour Alcohol on cotton ball",
        "Type": "Procedural",
        "Penalty(%)": 50,
        "Info": "Action took more than 10s."
        }
    ],
    "Disinfect skin area(1).TimeLimitError1(1)": [
        {
        "Name": "Disinfect skin area(1).TimeLimitError1(1)",
        "Timestamp": 59.16,
        "Action": "Disinfect skin area",
        "Type": "Procedural",
        "Penalty(%)": 50,
        "Info": "Action took more than 15s."
        }
    ],
    "Dispose the Cotton Ball(1).TimeLimitError1(1)": [
        {
        "Name": "Dispose the Cotton Ball(1).TimeLimitError1(1)",
        "Timestamp": 73.14,
        "Action": "Dispose the Cotton Ball",
        "Type": "Procedural",
        "Penalty(%)": 50,
        "Info": "Action took more than 5s."
        }
    ]
    }
],
"Objectives": [
    {
    "TimeLimitObjective1": [
        {
        "Name": "TimeLimitObjective1",
        "Timestamp": 101.5,
        "Succeeded": true,
        "Description": "Finish the operation in less than 2 minutes."
        }
    ],
    "TimeLimitObjective2": [
        {
        "Name": "TimeLimitObjective2",
        "Timestamp": 101.5,
        "Succeeded": false,
        "Description": "Finish the operation in less than 30 seconds."
        }
    ],
    "CollisionObjective1": [
        {
        "Name": "CollisionObjective1",
        "Timestamp": 101.5,
        "Succeeded": false,
        "Description": "Do not drop the cottom ball to the floor for the entire operation."
        }
    ],
    "PerformActionObjective1": [
        {
        "Name": "PerformActionObjective1",
        "Timestamp": 101.5,
        "Succeeded": true,
        "Description": "Disinfect the skin area of the patient."
        }
    ],
    "PerformActionObjective2": [
        {
        "Name": "PerformActionObjective2",
        "Timestamp": 101.5,
        "Succeeded": true,
        "Description": "Pour alcohol on the cotton ball."
        }
    ],
    "ScoreLimitObjective1": [
        {
        "Name": "ScoreLimitObjective1",
        "Timestamp": 101.5,
        "Succeeded": false,
        "Description": "Finish the operation with a score higher than 90%"
        }
    ],
    "ScoreLimitObjective2": [
        {
        "Name": "ScoreLimitObjective2",
        "Timestamp": 101.5,
        "Succeeded": true,
        "Description": "Finish the operation with a score higher than 50%"
        }
    ]
    }
],
"Scores": [
    {
    "Injection Question(1)": [
        {
        "Name": "Injection Question(1)",
        "Timestamp": 0.03,
        "count": 2,
        "initial": 11.1111107,
        "final": 0.0
        }
    ],
    "Cut the fake skin(1)": [
        {
        "Name": "Cut the fake skin(1)",
        "Timestamp": 0.06,
        "count": 1,
        "initial": 11.1111107,
        "final": 11.1111107
        }
    ],
    "Pour Alcohol on cotton ball(1)": [
        {
        "Name": "Pour Alcohol on cotton ball(1)",
        "Timestamp": 13.38,
        "count": 3,
        "initial": 11.1111107,
        "final": 2.77777767
        }
    ],
    "Disinfect skin area(1)": [
        {
        "Name": "Disinfect skin area(1)",
        "Timestamp": 43.36,
        "count": 2,
        "initial": 11.1111107,
        "final": 5.55555534
        }
    ],
    "Dispose the Cotton Ball(1)": [
        {
        "Name": "Dispose the Cotton Ball(1)",
        "Timestamp": 59.17,
        "count": 2,
        "initial": 11.1111107,
        "final": 5.55555534
        }
    ],
    "Insert the syringe into the arm(1)": [
        {
        "Name": "Insert the syringe into the arm(1)",
        "Timestamp": 73.15,
        "count": 1,
        "initial": 11.1111107,
        "final": 11.1111107
        }
    ],
    "Activate Syringe(1)": [
        {
        "Name": "Activate Syringe(1)",
        "Timestamp": 80.85,
        "count": 1,
        "initial": 11.1111107,
        "final": 11.1111107
        }
    ],
    "Remove the syringe from the arm(1)": [
        {
        "Name": "Remove the syringe from the arm(1)",
        "Timestamp": 85.11,
        "count": 1,
        "initial": 11.1111107,
        "final": 11.1111107
        }
    ],
    "Dispose the Syringe(1)": [
        {
        "Name": "Dispose the Syringe(1)",
        "Timestamp": 87.92,
        "count": 1,
        "initial": 11.1111107,
        "final": 11.1111107
        }
    ]
    }
],
"SessionParticipants": []
}

Hint

Example usage of Postman with Analytics API can be found here in the following section

Postman