SMP 3.0: Custom Agentry Android client supporting native NFC (RFID) scanning capabilities.

[Former Member]

All.

In our company we are building a custom SAP Work Manager 6.1 solution for our Oil & Gas OffShore technicians, who are to be working in an ATEX Zone 2 environment, where explosion proof devices are mandatory.

Until recently we have been aiming at using the Getac Z710 device (http://en.getac.com/tablets/Z710/features.html) , for which we have already build an Agentry client supporting RFID scanning capabilities, using the proprietary Getac hardware RFID scanner, which exposes Java API's to trigger a scan.

Recently we have started investigating the Samsung Galaxy Tablet, which has been enhanced to an ATEX Zone1 and Zone2 tablet (http://hazardous-area-tablet.com).  This device provides an NFC (subprotocol of RFID) scanner, which is accessible via native Android APIs (https://developer.android.com/guide/topics/connectivity/nfc/index.html)

Please note that at the moment none of the devices have actually been certified for ATEX Zone 1 or 2, but the Zone 2 device is under certification, and is expected to be approved and released late January 2015. The Zone 1 certification is not expected until May 2015.

Also note that SAP has officially entered a collaboration agreement with Samsung, making this Samsung device a preferred/recommended device by SAP for Work Manager. http://www.news-sap.com/samsung-sap-announce-plans-collaborate-deliver-innovative-enterprise-solutio...

In this document I will show how to enhance the Agentry Client and Agentry application to support native Android NFC scanning capabilities to transfer NFC/RFID tag values to fields in Agentry. The client is tested on the above mentioned Samsung device, but should be usable on any Android device supporting NFC, as only native Android APIs have been used for the development.

The development has been done in cooperation with my collegue marshal.oliveras2 , who has done the Agentry application modifications needed as well as the changes needed to support the Getac device.

Disclaimer:
Just to set the records straight, I am a complete novice in Android development, so please feel free to comment if you see anything, that looks completely wrong in the Android modifications.

The UI will for the end user work like this:

1. Click a button in Agentry.
2. An overlay screen will appear that instruct the user to move his device to the proximity of an NFC tag.
3. When an NFC tag is read, the overlay screen closes and the tag value is displayed in a text field in Agentry.

The following steps are needed:

Prerequisites:

Install Eclipse Juno 4.2.2.

1. Add Android Eclipse plugin (https://dl-ssl.google.com/android/eclipse/)
2. Import the OpenUI toolkit of the SMP 3.0 SDK (preferably the newest version) - resolve reference errors.

Agentry Android Client changes:

1. Create a class that extends the Agentry class ButtonDisplayAdapter. This class will give us control over the behavior of an Agentry push button.
   1. Override method onClick and implement actions to perform when user clicks button.
   2. Override method getExtensionString() to pass the scanned value back to Agentry.
2. Create a class that extends the Android Activity class. This will represent the overlay screen.
   1. Display a text for the user.
   2. Enable foreground dispatch of NFC events (intents) from Android to this Activity.
   3. When an NFC event (intent) is caught, save its value and close the Activity.

Agentry application changes.

1. Create a button in a detail screen.
   1. In the "External Field" tab, add a reference to the class extending the Agentry class ButtonDisplayAdapter in the General Settings, Class Name field.
   2. In the "External Field" tab, add an external value.
2. Create a text field in the detail screen.
   1. In the Update Rule field of this, make a reference to external value in the above defined button.

Details.

Now to the details of the solution.

Prerequisites:

Install Eclipse Juno 4.2.2.

Go to http://eclipse.org and download the Eclipse Juno bundle for your OS.

Add Android Eclipse plugin

Choose Help->Install New Software and select the location https://dl-ssl.google.com/android/eclipse/ to install the Android SDK. As a minimum select the SDK Manager and Platform Tools.

As part of you post-process installation you must install packages related to the Android version for which you intend to build your client (in our case 4.4.2)

Import the OpenUI toolkit of the SMP 3.0 SDK

Go to https://support.sap.com/software/patches/a-z-index.html -> M -> SAP MOBILE PLATFORM SDK -> SAP MOBILE PLATFORM SDK 3.0 -> Installations and Upgrades (right side) -> Windows on x64 64bit

Download the newest SDK for SMP 3.0.

In the folder '…\modules\AgentryToolkit\OpenUISDK\Android" find and extract a zip archive containing all needed project folders for your Agentry Android project.

In Eclipse choose Import-> Existing projects into workspace, and copy all included projects.

After import some of the projects will have errors.

Choose Project->Clean.

Correct the errors from Properties -> Android, where the references to other projects will be in error. Just add the corresponding projects of your Eclipse environment via the Add button. The naming is not totally the same, but manageable by inspecting the paths.

In here remember to also specify your target Android version.

Agentry Android Client changes:

I am attaching the (most important) source code to this document, so you can examine the code in detail for yourself.

File: AndroidManifest.xml

We have to make a few changes here.

Targetversions needs to be increased slightly (from 9/10 to 11/11).

    <uses-sdk android:minSdkVersion="11" android:targetSdkVersion="11"/>

We need to add NFC capability.

    <uses-permission android:name="android.permission.NFC"/>

Support of new Android Activity.

  <activity android:name="dk.dongenergy.agentry.openui.nfchelper.NfcActivity"

            android:theme="@android:style/Theme.NoTitleBar.Fullscreen"/>

Class: NfcConstants.

Used to store some constant values used in the solution.

  public static final String MSG_TEXT = "Move your device to the NFC/RFID Tag";

  public static final int MSG_SIZE = 42;

  public static final String NFC_INITIAL_VALUE = "-";

Class: NfcUtils.

Utility class, for this moment just providing the ability to display an alert popup screen.

Class: NfcDataBean

This class is a static data bean class to store the scanned tag value.

  private static String NfcValue = null;

  public static void Initialize(){

    NfcValue = NfcConstants.NFC_INITIAL_VALUE;

  }

  public static String getNfcValue(){

    return NfcValue;

  }

  public static void setNfcValue(String value){

    NfcValue = value;

  }

As far as I understand this is not the normal Android way to pass values between Activities, but since I do not have access to override the Activity representing the Agentry detail screen I have been unable to get this to work via dispatch of Bundle objects (Android experts will know what this means, if you don't then just ignore it).

Class: Z_RFIDButtonAdapter.

The class must be created in the package com.sap.mobile.platform.client.openui.extensions, and will be referenced in the Agentry application.

As a template we have used the class MyButtonDisplayAdapter from the sample collection.

This is the class that will allow us to interact with the Android OS.

The most important changes are:

- Method Initialize.

The NfcDataBean is initialized.

  //Initialize DataBean to store NFC tag value.

  NfcDataBean.Initialize();

- Method onClick

The NfcDataBean is initialized.

  //Initialize DataBean to store NFC scanned value.

  NfcDataBean.Initialize();

We check if the device is capable of doing NFC scanning.

  //Check that NFC Adapter exists and is enabled.

  NfcAdapter nfcAdapter = NfcAdapter.getDefaultAdapter(_context);

  if (nfcAdapter==null) {

    NfcUtils.ShowDialog("Error!","NFC Adapter not found.",_context);

    return;

  }

  else if(!nfcAdapter.isEnabled()){

    NfcUtils.ShowDialog("Error!","NFC Adapter turned off.",_context);

    return;

  }

We start our custom Android Activity, which is an overlay screen, instructing the user to move the device to the NFC tag.

  //Open Activity to catch NFC intents.

  Activity activity = (Activity) _context;

  Intent intent = new Intent(activity, NfcActivity.class);

  _context.startActivity(intent);

- Method getExtensionString

Allow Agentry to extract the defined External Value of the Agentry Button.

  String value = "";

  if (name.equals("ExtRFID"))

  {

    value = NfcDataBean.getNfcValue();

  }

  return value;

- Method onResume

Called when the overlay screen is closed and control is handed back to the detail screen.

The method uses statement _model.processInput();, to execute any update rules in the detail screen, here by updating the tag value in the text field.

Class: NfcActivity

This class represents the overlay screen, which will catch the NFC scan event (intent) and store the tag value.

- Method: onCreate.

This method will get the default NFC adapter instance.

  // Grab a hold of the nfc sensor

  this.nfcAdapter = NfcAdapter.getDefaultAdapter(this);

Furthermore it will setup a text to be displayed in the center of the overlay screen, instructing the user to move the device to an NFC tag (a lot of coding lines to achieve a simple task).

- Method: onResume.

Here we setup the Activity to respond to events (intents) from the NFC scanner.

  if (this.nfcAdapter != null) {

    // We setup this Activity to react to any NFC tag scanned - no

    // matter which type.

    nfcAdapter.enableForegroundDispatch(

            this,

      PendingIntent.getActivity(this, 0, new Intent(this, getClass())

        .addFlags(Intent.FLAG_ACTIVITY_SINGLE_TOP), 0),

      null, null);

  }

- Method: onPause.

When the Activity is not showing we don't want it to react on NFC scanning events.

  if (this.nfcAdapter != null) {

    this.nfcAdapter.disableForegroundDispatch(this);

  }

- Method: onNewIntent

This code is executed every time an NFC tag is scanned which adheres to the filters specified in the onResume method. In our case no filters has been defined, meaning the method onNewIntent is called for all NFC tags, but we could have defined filters for supported tags.

The tag ID is retrieved, converted to Hex format, and is stored in the NfcDataBean.

The last command (finish()) will close the activity screen and the onResume method of the Z_RFIDButtonAdapter class will be called, which will again refresh controls of the detail screen.

  if (intent != null && intent.getAction() == NfcAdapter.ACTION_TAG_DISCOVERED)
  {

    //Get tag value

    Tag tag = intent.getParcelableExtra(NfcAdapter.EXTRA_TAG);

    byte[] tagID = tag.getId();

    //Convert to HEX string

    String hex = getHex(tagID);

    //Store value in static data bean.

    NfcDataBean.setNfcValue(hex);

    //Close the Activity screen.

       finish();

  }

Deploying the client.

The client installable AgentryAndroidClientSolution.apk, will be put in the "bin" folder of the Android project (AgentryAndroidClientSolution) when the project is build.

You can copy this to the client, and install from here.

You can also connect the device to your PC, turn on USB debugging on the client, and choose Run As->Android Application from Eclipse this will install and launch the application directly.

Note also that to avoid having to do initial synchs every time you deploy, you can export the Agentry.db after first initial synch, from your device to the folder "assets" in the Android project. This will enable you to transfer all data to the client while deploying. You must set the Agentry Application to not encrypt data on the client for this to work.

Agentry application changes.

Now we need to modify our detail screen in the Agentry Application to use our new Button control.

Configuring the button Control

We define a button called Z_RFIDButton.

In the External Field settings we register our class for the customized button, and the External Value.

Configuring the Text field.

To display the value of the NFC tag, we define a Text field.

For the Update Rule we specify a direct link to the External Value of our custom button.

Resulting client.

The resulting UI works as follows.

We have modified the Add Transaction screen for NotificationAdd, where a field RFID has been introduced. To the left is the Text Field, and on the right side is the push button.

When the push button is clicked, this screen is overlaying the Agentry screen, and the user is instructed to move the device to the NFC tag. He can cancel the screen by applying the back button on his device.

When a tag is successfully scanned, the overlay screen is automatically closed, and the tag value is transferred to the text field.

In our Transaction screen we have setup update rules for the Functional Location and Equipment fields, so they will match any RFID value assigned to them. For above tag, no match was found.

That's it.

I hope it proves useful to someone.

Søren Hansen