Getting the User Access Log

Overview

Starting with version 2.5, every BlueID Access product supports the User Access Log (UAL) that serves as an incident log. To be more precise, the UAL contains the last (authorized or unauthorized) access attempts, where the maximum number of stored attempts depends on the hardware of the BlueID access product.

You can retrieve the UAL by using the command gual. Moreover, you can clear the log by using the command cual.

When you executed the command gual on the lock server, the CommandExecutionResponse you get contains a response object of type UserAccessLog. Within that object, you can iterate through the single entries. Every entry contains the following information:

ID of the mobile device
command used
communication channel used
timestamp of the access
authorization status of the access attempt

The authorization status tells you if the BlueID Token used was valid or invalid at the time of the command execution. A BlueID Token is invalid, if it was already revoked or if the time set on either the mobile device or the lock server was wrong. The attempt is logged in any case, but of course the command was only executed if the authorization status was valid. The entry list is sorted last-in-first-out, i.e. the first element is the newest.

The time needed to transfer the UAL from the lock server to the mobile device heavily depends on the number of entries stored on the lock server. But also the type of mobile device as well as the type of lock server has an influence. If the UAL contains 1000 entries, the transfer can take up to 1-2 minutes. Hence, please be patient, the connection is likely still active and transferring data.

Examples

The following short examples show you how to retrieve the user access log and print it to the debugging console.

Android

SecuredObject securedObject = sdk.getSecuredObjects().get(0);
Command command = securedObject.getCommandById("gual");
Channel channel = securedObject.getChannelsForCommand(command).iterator().next();

CommandExecutionResponse response = sdk.executeCommand(securedObject, channel, command);

UserAccessLog ual = (UserAccessLog) response.getResponseObject();

List<UserAccessLog.Entry> entries = ual.getEntries();

for (UserAccessLog.Entry entry : entries) {
    Log.d(TAG, "mobile device " + entry.getMobileDeviceId() +
              " executed command " + entry.getCommandId() +
              " using channel " + entry.getChannel() +
              " at " + new Date(entry.getTimestamp() * 1000) +
              ", authorization status = " + entry.getAuthorizationStatus());
}

The first three lines are quite similar to our first command execution example, except that we now explicitly request the command gual. In line 7, we see a new method introduced in the BlueID SDK 2.5, getResponseObject(): This method automatically converts known data types transferred from the lock server to the mobile device in objects that can be easily used by you. In our case here, the derived class from ResponseObject is UserAccessLog. It supplies a convenient access to the single log entries.

Please keep in mind that the method executeCommand can throw several exceptions (see Introduction to BlueID App Integration). If some kind of RemoteException was thrown (except ChannelNotAvailableException or ChannelNotSupportedException), you can retry the command execution. No data will be erased on the lock server in case of a failed attempt!

iOS

BlueIDSecuredObject *securedObject =
  [[BlueIDMobileDevice sharedInstance] getSecuredObjects][0];
BlueIDCommand *command = [securedObject getCommandById:@"gual"];
BlueIDChannel *channel = [securedObject getChannelsForCommand:command][0];
[[BlueIDMobileDevice sharedInstance] executeCommand:command
                                          onChannel:channel
                                    onSecuredObject:securedObject
                                  completionHandler:^
(BlueIDCommandExecutionResponse *commandExecutionResponse, NSError *error)
{
    [commandExecutionResponse parseResponseData:^(BlueIDResponseObject *responseObject, NSError *error) {
        BlueIDUserAccessLog *accessLog = (BlueIDUserAccessLog *)responseObject;

        for (BlueIDUserAccessLogEntry *entry in accessLog.entries) {
            NSLog(@"mobile device %@ executed command %@ using channel %@ at %@, authorization status = %@",
                entry.mobileDeviceId,
                entry.commandId,
                entry.channel,
                [NSDate dateWithTimeIntervalSince1970:entry.timestamp],
                @(entry.authorizationStatus));
        }
    }];
}];

The first lines are quite similar to our first command execution example, except that we now explicitly request the command gual. In line 11, we see a new method introduced in the BlueID SDK 2.5:

parseResponseData: This method automagically converts known data types transferred from the lock server to the mobile device in objects that can be easily used by you. In our case here, the derived class from BlueIDResponseObject is BlueIDUserAccessLog. It supplies a convenient access to the single log entries.

If the command execution fails, information about the failure is contained in the error parameter of the handler block of executeCommand:onChannel:onSecuredObject:completionHandler (see Introduction to BlueID App Integration). If the error parameter is not nil, you can retry the command execution. No data will be erased on the lock server in case of a failed attempt!