Technology Blogs by Members
Explore a vibrant mix of technical expertise, industry insights, and tech buzz in member blogs covering SAP products, technology, and events. Get in the mix!
cancel
Turn on suggestions
Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
Showing results for 
Search instead for 
Did you mean: 

How to create an Agentry Client for iOS using SMP SDK SP10 and Xcode 7.0

Marçal_Oliveras
Active Contributor
‎10-13-2015 10:19 AM

Hi,

In this post I will describe how to create a basic Agentry client using OpenUI from SMP SDK SP10 and Xcode 7.0. The guide is written from a non Apple iOS developer point of view. Therefore if you have any kind of experience it may look extremely detailed. But even though I did some Cordova based application in the past, I'm not familiar at all with iOS and Xcode, and probably other Agentry developers will be under the same circumstances.

Why would you create an custom Agentry client?

There are several changes that we can introduce to the standard Agentry client available in the Appstore. Below a list of reasons and business needs I could think about:

  • Branding of your client: Changing the application icon, name and initial screens to fit your company
  • Control of version release: Appstore client is upgraded regularly, and sometimes includes new features that may introduce errors to your current deployment. Using a custom client, you can test the new version and deploy via MDM once it is safe.
  • Default connection values: The custom client can have a predefined URL for your SMP 3.0 endpoint. This way users only need to know their username and password to connect.
  • Pre-built database: In order to reduce the initial synchronization time, you can create a client including all the application definitions plus pre-filled complex tables.
  • Introduce native capabilities: With Open UI you can create fields controlled with native code allowing you to basically access to all the capabilities of your device. For instance ESRI GIS maps integration is done using this feature, Another example is accessing to the RFID scanner from an Android device: SMP 3.0: Custom Agentry Android client supporting native NFC (RFID) scanning capabilities.

This document has been elaborated following the build iOS client guide from help.sap.com. Unfortunately, SAP steps contains unprecise information or mistakes caused by changes in Apple software recent versions:

Prerequisites

  • An Apple computer with Mac OSX 10.11 and Xcode 7.0 installed is necessary to compile an iOS app.
  • Apple ID enrolled to an Apple Developer Enterprise Program in order to be able to sign the app and distribute it.
  • SMP 3.0 SDK SP10 downloaded from support.sap.com

Step-by-step guide

Create Xcode project

  • Extract the iOS libraries and framework from the SDK zip, and copy the file to your OSX computer. The complete path is SMPSDK30010_0-21011834.zip\ebf25340\SMP3SDKInstaller-win-3.0.10.0.zip\modules\AgentryOpenUISDK\SMPAgentryClientFramework-iOS-70.10.0.tgz

  • Create the Xcode project
    • Start Xcode 7.0
    • From menu, select File --> New --> Project…
    • Select Single View Application and click Next.

    • Enter the below details:
      • Product Name: CustomAgentryClient
      • Organization Name: Your company
      • Organization Identifier: com.yourcompany
      • Unmark Include Unit Tests and Include UI Tests and click Next.
      • Select the folder where you want to create your project and click Create.

Setup project for Agentry client creation

  • In General tab for project, change the Bundle Identifier to have it without capital letters, in Deployment Target set iOS 7.0 and also enable Upside Down flag for device orientation if you want.

  • Build Settings. Go to Build Settings tab, ensure that the header option All button is active instead of Basic, and perform the following actions:
    • Scroll down to Search Paths section, double-click to Framework Search Paths setting and enter the path to the framework:
      • <SDKFrameworkFolder>/iOS/**
    • Also in Search Paths section, double-click to Header Search Paths setting and enter the path to the headers:
      • <SDKFrameworkFolder>/iOS/SMPAgentryClient.framework/Versions/70.10.0.1/Headers/**

  • In section Linking, search for Other Linker Flags setting and set its value to:
    • -ObjC –framework SMPAgentryClient

  • In section Deployment, set Strip Linked Product to No
  • In section Build Options, set Enable Bitcode to No (I don't totally understand the consequences of doing so, I think it's irrelevant for the Agentry client but in xCode 7.0 the build process was failing without this change)

Build Phases:

  • Add libraries. Go to Build Phases tab, expand Link Binary With Libraries node and click the ‘+’ button. With “CMD” button pressed for multiple selection, add the libraries and frameworks below:
    • AudioToolbox.framework
    • AVFoundation.framework
    • CFNetwork.framework
    • CoreGraphics.framework
    • CoreLocation.framework
    • CoreMedia.framework
    • CoreText.framework
    • CoreVideo.framework
    • Foundation.framework
    • libc++.tbd
    • libiconv.tbd
    • libicucore.tbd
    • libxml2.tbd
    • QuartzCore.framework
    • Security.framework
    • UIKit.framework

Add resource bundle to the project and adjust files

  • From Xcode menu, select File Add Files to “CustomAgentryClient”… and select the bundle file from the Agentry framework.
    • <SDKFrameworkFolder>/iOS/SMPAgentryClient.framework/Versions/70.10.0.1/Resources/SMPAgentryClientResources.bundle

  • Modify main.m file placed under project folder CustomAgentryClient/Supporting Files. Replace the return statement:
    • Original: return UIApplicationMain(argc, argv, nil, NSStringFromClass([AppDelegate class]));
    • New: return UIApplicationMain(argc, argv,@"SMPAgentryApplication", @"SMPAgentryClientAppDelegate");

  • Add row to Info.plist file placed under project folder CustomAgentryClient. Right click and add row for property View controller-based status bar appearance with value set to NO.


  • Save modified files.
  • At this point, the application is ready to be tested in the simulator or a real device connected via USB. For distribution, and .ipa file with enterprise profiles are necessary.

Change App name

  • In Xcode project navigator, select the project root node.
  • Change the name in the Utilities screen, Identity and Type section. The number of characters is limited.
  • Select some other node in the project navigator and XCode will trigger the renaming tool. Accept all the changes and the application will display the new text under the icon once installed.

Set App Icons

  • Go to project General settings tab, and scroll to App Icons and Launch Images section
  • App Icons Source setting should be set to “AppIcon” and Launch Image Source to “Use Asset Catalog”

  • Click the small arrow next to App Icons Source dropdown and screen to define icons will appear. Drag&drop images from the Agentry bundle imported to the project navigator.

Set default server URL

This section has been elaborated with the help of the link below, but a few more details have been added: http://help.sap.com/saphelp_smp3010sdk/helpdata/en/40/946fddac4c4d90ac26470fd217adf3/content.htm

In order to specify the URL for the Agentry instance running on SMP 3.0 server, a property list XML file Branding.plist has to be created under the main application bundle.

  • On Xcode menu, click File -> New -> File…
  • Select Property List, Next and name it Branding.plist
  • Add a row to the file Root element. The item name must be agentryServerUrl, and the value the server url. For instance: https://hostname:8081/AGENTRY_APP

Change default client strings

The same Branding.plist file also allows overriding client strings, for instance the ones shown in the login screen. It’s important to know that after the initial synchronization, these screens may be overridden again from the Agentry server.

To know the ID of every possible string to be override, go to your SMP 3.0 server and open the ClientStringNames.ini file under <SMPInstall>\Server\configuration\com.sap.mobile.platform.server.agentry

Each string has a text ID linked to a number. The number is the item name to be used in our Branding.plist file. To know the current string values overridden by the Agentry server, you can examine the file ClientTextBase.ini placed in the deployment folder of a production Agentry instance. For instance: <SMPInstall>\Server\configuration\com.sap.mobile.platform.server.agentry.application.AGENTRY_APP

One of these strings is the header text showed in the login screen, its numberID is 6155, its text ID is AG3_LOGIN_DLGCAPTION and its value after synchronization will be “Welcome to %1”.

A new row will be added to Branding.plist to specify the value the first time the users starts the app (see the above screenshot):

  • Item name: 6155
  • Item value: HELLO CUSTOM AGENTRY CLIENT!

Adding a pre-built database

It is possible to create the iOS application with a pre-built database to reduce the initial synchronization time. The steps on how to do that are described in the answer for the following thread: http://scn.sap.com/thread/3758610

  • Publish your Agentry project with encrypt database flag disabled

  • Execute an initial synchronization with your iPad. Once it’s finished, go to the initial screen, tap on the information icon and then export the database. It will be created in the Documents folder.
  • Connect the device to iTunes and copy the db off.
  • Add the file to the main bundle of the XCode project (named Agentry-iPad.db or Agentry-iPhone.db)



Generate distributable app

Create Apple Application ID

*This part of the guide may not be 100% precise. I can’t really describe all the steps because my MacBook already had some profiles and certificates installed, plus I'm an "admin", a normal "member" won't be able to generate all the necessary stuff from Xcode. I only had to create the application identifier with the same Bundle ID specified in the Xcode project and then Archive it exporting for Enterprise to generate the signed .ipa file. I recommend the help of an iOS developer for this section.

  • Create a new iOS App ID, enter the description, the bundle ID and the services to be enabled (in this case only push)
  • Click the Xcode menu Product -> Archive
  • Once in the Archive screen you can enter a description and finally click the Export button.
  • In the Export screen, select Save for Enterprise Deployment and click Next.

  • Select your company Development Team.
    • Alert: After this step, if the valid Certificate for your company was not in the Macbook, it will be automatically imported without private key but Xcode will ask for regenerating it (DO NOT DO THIS OR YOU WILL REVOKE THE PREVIOUS CERTIFICATE, INVALIDATING ALL THE APPLICATIONS SIGNED WITH IT) or import the key. To proceed, you must install the private key to your computer key chain. It has to be exported from another Macbook that already has it.
  • Choose Export one app for all compatible devices
  • The summary screen should appear, click next and the .ipa file ready to be distributed will be generated in the Desktop.
  • Finally you can distribute your .ipa application file via your company MDM like Afaria, or use iTunes to test in your own devices. In iTunes, just drag the ipa file inside the applications, and then with your device connected, select install and apply.

Labels in this area
Popular Blog Posts