About OpenDJ Contact Manager

OpenDJ directory services give modern mobile applications easy access to directory data through a ForgeRock common REST interface. OpenDJ Contact Manager is an Android application that demonstrates use of OpenDJ directory server's REST interface to search for and to read user resources. When you retrieve the resource for a user from OpenDJ directory server, OpenDJ Contact Manager lets you do the following:

  • Add the user to your Android address book.
  • Place a call to the user.
  • Send email to the user.
  • Send a text message (SMS) to the user.
  • Geolocate the user's address.
  • Get the resource for the user's manager.
  • Supports voice search.
  • Supports filters search, i.e. search by manager, employee type...etc.

The directory data itself is exposed as REST resources over HTTP using the directory HTTP connection handler, with a mapping from LDAP entries to REST resources configured in a file called http-config.json. For details about the OpenDJ REST interface and for examples showing how to use it, see the OpenDJ Administration Guide chapter, Performing RESTful Operations.

To Build OpenDJ Contact Manager in Your IDE

  1. Checkout the sources for OpenDJ Contact Manager.

    $ svn co https://svn.forgerock.org/commons/mobile/contact-manager/trunk contact-manager

    In the AndroidManifest.xml file, note the value of the android:targetSdkVersion attribute on the <uses-sdk> element. You need to get this version of the Android SDK.

  2. Download and install Android SDK. See http://developer.android.com/tools/index.html for instructions.

    The minimum Android SDK version is 14. The target Android SDK version is the android:targetSdkVersion of the <uses-sdk> element. If you have installed a later version of the SDK, also install the target SDK version.

  3. Set up your development environment to be able to use Android SDK.

  4. Install and configure OpenDJ directory server.

    The minimum OpenDJ version is 2.6.0.

    1. Install OpenDJ as described in the Installation Guide, importing Example.ldif sample data.
    2. Configure the HTTP Connection Handler as described in the Administration Guide procedure, To Set Up REST Access to OpenDJ Directory Server.
    3. Stop OpenDJ directory server, apply the configuration, ext_resource/http-config.json, provided with OpenDJ Contact Manager source files, start OpenDJ directory server again, and then check that the REST interface is working.
      $ /path/to/opendj/bin/stop-ds
      Stopping Server...
      $ cp ext_resource/http-config.json /path/to/opendj/config/http-config.json
      $ /path/to/opendj/bin/start-ds
      ...The Directory Server has started successfully
      $ curl http://bjensen:hifalutin@opendj.example.com:8080/users/bjensen?_prettyPrint=true
      {
        "_rev" : "00000000265ab6d0",
        "schemas" : [ "urn:scim:schemas:core:1.0" ],
        "contactInformation" : {
          "telephoneNumber" : [ "+1 408 555 1862" ],
          "emailAddress" : [ "bjensen@example.com" ]
        },
        "_id" : "bjensen",
        "name" : {
          "familyName" : "Jensen",
          "givenName" : "Barbara"
        },
        "userName" : "bjensen@example.com",
        "displayName" : "Barbara Jensen",
        "contactAddress" : {
          "location" : "San Francisco",
          "postalAddress" : "500 3rd Street"
        },
        "manager" : [ {
          "_id" : "trigden",
          "displayName" : "Torrey Rigden"
        } ]
      }
      
  5. Import the OpenDJ Contact Manager project into your development environment.

    Make sure you have the correct Android SDK in the project SDK list.
    For example, your project configuration might look like this in IntelliJ IDEA if <uses-sdk android:targetSdkVersion="19" />:

    Import Wizard SDK Screen
  6. Configure your development environment to build the project.

    For example, if you use IntelliJ IDEA you configure a build that deploys the application into the Android emulator and launches the default activity.

    Build Configuration Screen
  7. Build the configuration, thereby starting the emulator with OpenDJ Contact Manager.

    The emulator shows OpenDJ Contact Manager with no search results.

    Import Wizard SDK Screen
  8. Configure the connection to OpenDJ directory server.

    1. Click Menu > Settings.
    2. On the Settings page, click Menu > Add.
    3. On the New Server page, provide a name and IP address:port combination.

      Server Connection Configuration Screen

      Use an IP address to access OpenDJ directory server from the emulator. For example, use the IP address assigned to your main network interface.

    4. Click Continue, and then enter a user name and password.

      Server Connection Authentication Screen

      If you imported Example.ldif data into OpenDJ directory server, then you can use bjensen with password hifalutin.

  9. With the connection properly configured, try some features.

    • Perform a search for "jensen".

      Search Result for jensen
    • Perform a search for "carter" and then add Sam Carter's entry to your address book.

      Adding Sam Carter to the address book

      The contacts you add show up in your Android address book.

      Adding Sam Carter to the address book

To Build OpenDJ Contact Manager on the Command Line

You can build OpenDJ Contact Manager by using Apache Maven. Follow these steps:

  1. Checkout the sources for OpenDJ Contact Manager.

    $ svn co https://svn.forgerock.org/commons/mobile/contact-manager/trunk contact-manager

    In the AndroidManifest.xml file, note the value of the android:targetSdkVersion attribute on the <uses-sdk> element. You need to get this version of the Android SDK.

  2. Download and install Android SDK. See http://developer.android.com/tools/index.html for instructions.

    The minimum Android SDK version is 14. The target Android SDK version is the android:targetSdkVersion of the <uses-sdk> element. If you have installed a later version of the SDK, also install the target SDK version.

  3. Build OpenDJ Contact Manager using Apache Maven.

    The ANDROID_HOME directory depends on where you installed Android SDK, and on your platform.
    The following example is from an installation on Mac OS X.

    $ ANDROID_HOME=~/Development/android-sdk-macosx \
     PATH=$ANDROID_HOME/tools:$ANDROID_HOME/platform_tools:$PATH \
     mvn -Pprecommit clean install
    [INFO] Scanning for projects...
    [INFO]
    [INFO] ------------------------------------------------------------------------
    [INFO] Building ContactManager 1.0.0-SNAPSHOT
    [INFO] ------------------------------------------------------------------------
    
    ...
    
    [INFO] --- maven-install-plugin:2.4:install (default-install) @ contactmanager ---
    [INFO] Installing ...target/contactmanager.apk to ...
    [INFO] Installing ...pom.xml to ...
    [INFO] Installing ...target/contactmanager.jar to ...
    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 31.816s
    [INFO] Finished at: Thu Nov 21 10:36:33 CET 2013
    [INFO] Final Memory: 37M/255M
    [INFO] ------------------------------------------------------------------------

    After a successful build, deploy the OpenDJ Contact Manager application, target/contactmanager.apk, on your Android device as described below.

To Deploy OpenDJ Contact Manager on an Android Device

To try OpenDJ Contact Manager on a physical device such as a phone, install the compiled .apk.

  1. Plug your device into your computer by USB cable, and use the device in USB mode.
  2. Copy target/contactmanager.apk to your device.
  3. Unmount the device, shut down the USB connection, and unplug your device.
  4. In the device Settings under Security > Device Administration, allow installation of applications from Unknown Sources.
  5. Open the .apk file and accept Android's prompt to install OpenDJ Contact Manager.