Application Overview - User Lookup iPhone Application Overview

User Lookup iPhone Application Overview

Contents Purpose Application Overview Application Screens Project Structure Implementation Files Installation and configuration guidelines Prerequisites Preparing Web Services - Web Service Functionality overview - SOAP Web Service Interface - REST Web Service Interface - Configuring Authentication Installing an Application on the iPhone Simulator Installing an Application on iPhone or iPod Touch Installing a Provisioning Profile on iPhone - Installing a Provisioning Profile Using iTunes - Installing a Provisioning Profile Using xCode. - Installing a Provisioning Profile Using the iPhone Configuration Utility - Build and Go Configuring an Application Introducing an Application Settings Installing Digital Certificates on iPhone. - Installing Certificates Using Mail - Installing Certificates Using Safari - Installing Certificates Using iPhone Configuration Utility Additional Information

Purpose
This document presents overview of a Sample User Lookup iPhone application.
Applicable application version 1.0

Application Overview
User Lookup application is a simple application for demonstrating how to implement SOAP and REST web services calls from the iPhone application and handle the following aspects: Basic authentication Client certificate authentication SOAP/XML response parsing REST/JSON response parsing Application specific settings

User Lookup Sample iPhone Application Overview

Page 1 of 16

Application Overview - User Lookup iPhone Application Overview

Application Screens
Description Image A user has to specify a user ID. Depending on a web service type specified in application settings, an application performs SOAP or REST web service request.

If a user has specified a wrong user name or/and password for the Basic authentication type, he gets a prompt asking for authentication credentials.

When an application receives response from a web service, the details screen appears. Depending on a web service type, an application receives SOAP or JSON response. The response is beeing parsed by application and presented to user.

User Lookup Sample iPhone Application Overview

Page 2 of 16

Application Overview - User Lookup iPhone Application Overview

Description Image Error prompt is shown when user enters invalid User ID.

Web Service Type - A user can choose between two web service types. SOAP and REST. SOAP URL - A user has to specify a SOAP service URL. The URL has to be specified without a protocol. (http:// or https:// ) REST URL - A user has to specify a REST service URL. The URL has to be specified without protocol. (http:// or https:// ) SAP Logon Ticket - A user can choose whether to use the SAP Logon Ticket or not. Authentication Type - A user can choose between two authentication types. Basic and Client Certificate authentication. Basic Authentication Settings - A user has to specify a user name and password.

Project Structure
Classes All implementation classes Utils Utility Classes Model Model implementation classes - DataObjects - Service Implementations Web service implementations implementation classes - REST The REST service implementation classes, including data parsing - SOAP The SOAP service implementation classes, including data parsing - Common Common (Abstract) service implementation classes for REST and SOAP View Controllers UI implementation Third Party Libraries JSON Third party JSON parser library Other Sources Other classes including constants Resources NIB Files All *.xib files used in application Settings Configuration files Images All images used in application Frameworks Frameworks included in project Products Compiled application files

User Lookup Sample iPhone Application Overview

Page 3 of 16

Application Overview - User Lookup iPhone Application Overview

Implementation Files
Table below outlines all class files used in an application and their functional area:
Module Delegate Location Classes File UserLookupSampleAppDelegate Description The Application Delegate is a class that receives the applicationlevel messages. It is a subclass of NSObject, which implements UIApplicationDelegate delegate. A utility class that implements interaction with user preferences. Including setting default values when application is installed on a device for the first time. A utility class that implements common methods used in all applications. A data object class that represents a request data object. A data object class that represents a response data object. A subclass of AbstractServiceProvider that implements the specific functionality for a REST web service data request. This class also implements the JSON response parsing using a third-party parser. A subclass of AbstractServiceProvider and it implements specific functionality for a SOAP web service data request. This class also implements an XML response parsing. Delegate protocol for AbstractServiceProvider. An abstract web service provider that has to be extended. This class implements common functionality for the SOAP and REST web service data request, including passing data back to its delegate. Implements user interface for the User Lookup application first screen. It provides capability for a user to enter a User ID and perform the data request. It also informs a user about the asynchronous activity. Implements user interface for the User Lookup application details screen. It provides capability for a user to see the response data. Defines the common constants used in all applications.

Utility Class

Classes/Utils

SettingsManager

Utility Class

Classes/Utils

Utils

Data Object Data Object Model

Classes/Model/Data Objects Classes/Model/Data Objects Classes/Model/Service Implementations/REST

RequestDO ResponseDO GetUserDetailsRESTService

Model

Classes/Model/Service Implementations/SOAP

GetUserDetailsSOAPService

Protocol Model

Classes/Model/Service AbstractServiceProviderDelegate Implementations/Common Classes/Model/Service AbstractServiceProvider Implementations/Common

Controller

Classes/View Controllers

RootViewController

Controller

Classes/View Controllers

DetailsViewController

Utility Class

Other Sources

Constants

Installation and configuration guidelines

Below are provided guidelines for preparing application testing environment and installing application.

User Lookup Sample iPhone Application Overview

Page 4 of 16

Application Overview - User Lookup iPhone Application Overview

Prerequisites
User Lookup iPhone application is build as a standard iPhone application using iPhone SDK 3.1. Application is targeted to running on 3.0 or 3.1 iPhone OS (iPhone or iPod Touch), but the Base SDK used here is 3.0.
For application to be used with real data additional web services must be created, deployed and configured on testing environment. For more details refer to Preparing Web Services section

Preparing Web Services

For application to be used with real data, a web services must be created, deployed and configured on testing environment. Implemented web services may use R3 system to get data (complete end-to-end scenario), or return predefined data without using SAP R3 system. SAP NetWeaver 7.0 or 7.1 may be required for integrating with SAP R3 system.

Web Service Functionality overview

A web service should BAPI_USER_GET_DETAIL RFC from ABAP system to get user first and last using provided user name. User name is passed using USERNAME input parameter, while user first and last name are returned inside ADDRESS structure in FIRSTNAME and LASTNAME fields. In case of an error, error message is returned inside RETURN table parameter, using MESSAGE field.

SOAP Web Service Interface

Application expects SOAP web service to have following format:
Request Sample

<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Body> <yq1:getUserDetails xmlns:yq1="http://www.sap.com/caf/demo.sap.com/userlookup/modeled"> <username>JOHND</username> </yq1:getUserDetails> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Response Sample

<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Body> <yq1:getUserDetailsResponse xmlns:yq1="http://www.sap.com/caf/demo.sap.com/userlookup/modeled"> <outputParameter1 xmlns:ns2="http://www.sap.com/caf/demo.sap.com/userlookup/modeled"> <ns2:firstName>John</ns2:firstName> <ns2:lastName>Doe</ns2:lastName> </outputParameter1> </yq1:getUserDetailsResponse> </SOAP-ENV:Body>

User Lookup Sample iPhone Application Overview

Page 5 of 16

Application Overview - User Lookup iPhone Application Overview

Response Sample
</SOAP-ENV:Envelope>

Error Sample

<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:SOAP-ENV="http://schemas.xmlsoap.org /soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Body> <SOAP-ENV:Fault> <faultcode>SOAP-ENV:Server</faultcode> <faultstring>User SOME does not exist</faultstring> </SOAP-ENV:Fault> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

For web service sample implementation please see Enterprise MicroApplications Technical Users Guide for Netweaver 7.0 or 7.1, section Appendix - Creating a Data Service. Guide is available for download under https:// wiki.sdn.sap.com/wiki/display/Img/MicroApplications

REST Web Service Interface

Application expects REST web service to have following format:
Request Sample Single URL that accepts username as URL parameter, for example http://myhost/mywebservice?username=JOHND Response Sample

"UserDetails":{ "firstName":"First Name", "lastName":"Last Name" }

Error Sample

{ }

"error":"User SOME does not exist"

Following web service can be implemented using SAP NetWeaver 7.0 or 7.1, by creating J2EE web application that have servlet acting as endpoint to web service and uses JCo library for accessing SAP backend system. Following could be basic implementation of required functionality:

try{

IFunctionTemplate getUserDetailsFunction = mRepository.getFunctionTemplate("BAPI_USER_GET_DETAIL"); function = getUserDetailsFunction.getFunction();

User Lookup Sample iPhone Application Overview

Page 6 of 16

Application Overview - User Lookup iPhone Application Overview

if (function == null) { throw new Exception("BAPI_USER_GET_DETAIL could not be found"); } function.getImportParameterList().setValue(username, "USERNAME"); mConnection.execute(function); JCO.Structure returnStructure = function.getExportParameterList().getStructure("ADDRESS"); String firstName = returnStructure.getString("FIRSTNAME"); String lastName = returnStructure.getString("LASTNAME");

if(firstName.equals("") && lastName.equals("")){ JCO.Table errorMessage = function.getTableParameterList().getTable("RETURN"); throw new Exception(errorMessage.getString("MESSAGE")); }else{ response.getWriter() .print("{\"UserDetails\":" + "{"+"\"firstName\":\"" + firstName + '"' + "," + "\"lastName\":\"" + lastName + '"' + "}}"); } } catch (Exception ex) { response.setStatus(500); response.getWriter().print("{\"error\":\"" + ex.getMessage()+ "\"}"); ex.printStackTrace(); } finally { mConnection.disconnect(); }

Configuring Authentication
This application demonstrates usage of Basic and Client certificate authentication, as well as SAP Logon ticket. For supporting desired authentication way, web service security must be additionally configured. For complete functionality a web service must have following security mechanisms configured: Basic Authentication Client Certificate SAP Logon Ticket (Create and evaluate) Following is an example of login module configuration:
Login Module Name EvaluateTicketLoginModule com.sap.engine.services.security.server.jaas.ClientCertLoginModule CreateTicketLoginModule BasicPasswordLoginModule CreateTicketLoginModule Flag SUFFICIENT OPTIONAL SUFFICIENT OPTIONAL SUFFICIENT

For web service configuration sample please see Enterprise MicroApplications Technical Users Guide for Netweaver 7.0 or 7.1, section Appendix - Configuring a Data Service.

Installing an Application on the iPhone Simulator

To deploy an application on the iPhone simulator, open the project, select the Active SDK version and click Build and Go.

User Lookup Sample iPhone Application Overview

Page 7 of 16

Application Overview - User Lookup iPhone Application Overview

To build an application using different iPhone SDK version, select Groups & Files > Right click on project > Get Info > Build > iPhone OS Deployment Target.

User Lookup Sample iPhone Application Overview

Page 8 of 16

Application Overview - User Lookup iPhone Application Overview

Installing an Application on iPhone or iPod Touch

In order to deploy developed applications on an iPhone device, a user need to be enrolled into iPhone Developer Program. To deploy the application, the following steps must be completed: Create a development certificate (How to?) Register a device on the developers program (How To?) Generate an App ID (How to?) Download and install a provisioning profile on the device (How to?) "Build and Go"

Installing a Provisioning Profile on iPhone

The provisioning profile can be installed on iPhone using the following installation methods: Install a provisioning profile using iTunes. Install a provisioning profile using xCode. Install a provisioning profile using iPhone Configuration Utility (Download Windows, Mac OS X)

Installing a Provisioning Profile Using iTunes

Simply drag and drop a provisioning profile on the iTunes icon.

Installing a Provisioning Profile Using xCode.

In the xCode toolbar, select the Windows toolbar item. Select the Organizer menu item. Click Add .

Installing a Provisioning Profile Using the iPhone Configuration Utility

Select the Provisioning Profiles tab. Click Add in the top left corner.

User Lookup Sample iPhone Application Overview

Page 9 of 16

Application Overview - User Lookup iPhone Application Overview

Select the device, and select the Provisioning Profiles tab. Select a provisioning profile from the list, and click Install.

User Lookup Sample iPhone Application Overview

Page 10 of 16

Application Overview - User Lookup iPhone Application Overview

Build and Go
Before deploying an application to the device, the following must be performed: Set the code signing identity. Select a project in Groups & Files > Right click on project > Get Info > Build > Code Signings Identity. Select the appropriate development profile. Set the appropriate App Id In the project, find the Info.plist file, and in the Bundle identifier row, specify the App ID.

Configuring an Application
This section presents an application settings that must be configured before the application can be used.

Introducing an Application Settings

All application settings are saved in the application preferences. To open the User Lookup application preferences screen, on the device Home Screen, select Settings > User Lookup. When an application is deployed for the first time, the preferences screen is populated with the default values. To set the default values, select UserLookupSample > Resources > Settings > Settings.bundle, open *.plist files in the xCode project, and set the default values in the XML property list.

Settings.bundle contains two files. The Root.plist file represents the main screen of preferences, but the BasicAuthenticationSettings.plist file represents screen where a user enters a user name and password. The Root.plist file
# Item 1 Settings Parameter Key Type PSGroupSpecifier Description A group item preference. A group type is a method for organizing groups of preferences on a single page. Used to separate Web Service Settings from Authentication Settings Used for a preference that supports a set of mutually exclusive values. A numeric value, that can contain either 0(SOAP) or 1 (REST). Displays an optional title and an editable text field. Must contain a SOAP URL. Displays an optional title and an editable text field. Must contain a REST URL. The RA group item preference. A group type is a method for organizing groups

Item 2

wsType

PSMultiValueSpecifier

Item 3 Item 4 Item 5

soapUrl restUrl

PSTextFieldSpecifier PSTextFieldSpecifier PSGroupSpecifier

User Lookup Sample iPhone Application Overview

Page 11 of 16

Application Overview - User Lookup iPhone Application Overview

# Settings Parameter Key Type Description of preferences on a single page. Used to separate Web Service Settings from Authentication Settings Item 6 Item 7 logonTicket authType PSToggleSwitchSpecifier Typically used to represent preferences containing Boolean values. Used for a preference that supports a set of mutually exclusive values. A numeric value that can contain either 0(Basic Authentication) or 1 (Client Certificate Authentication). PSChildPaneSpecifier Used to link to a new page of preferences. Links to the BasicAuthenticationSettings.plist file.

Item 8

The BasicAuthenticationSettings.plist file

# Item 1 Settings Parameter Key Type PSGroupSpecifier Description A group item preference. A group type is a method for organizing groups of preferences on a single page. Used to set a group title. Displays an optional title and an editable text field. Used to specify a user name. Displays an optional title and an editable text field. Used to specify a password. The IsSecure parameter property value is set to TRUE.

Item 2

username

PSTextFieldSpecifier

Item 3

password

PSTextFieldSpecifier

Installing Digital Certificates on iPhone.

iPhone supports X.509 certificates with RSA keys. iPhone recognizes .cer, .crt, .der, .p12and .pfx file formats. Certificates can be installed as follows: Installing certificates using Mail Installing certificates using Safari Installing certificates using iPhone Configuration Utility

Installing Certificates Using Mail

Send certificate files to required email account accessible from the device. Then open the email and select the appropriate certificate.

User Lookup Sample iPhone Application Overview

Page 12 of 16

Application Overview - User Lookup iPhone Application Overview

When the certificate link is clicked in iPhone, it asks whether to install it. The certificate will most likely not be verified by another party.

If the certificate is protected with a password, iPhone asks to enter it. Once the password is entered, the certificate is to be installed on the device.

User Lookup Sample iPhone Application Overview

Page 13 of 16

Application Overview - User Lookup iPhone Application Overview

Installing Certificates Using Safari

Safari can be used to download certificates from a web page. Host a certificate on a website and install them on the device in the same way as from mail.

Installing Certificates Using iPhone Configuration Utility

To install a configuration profile: Select the Configuration Profiles tab. In the credentials section, click Add and add certificates.

User Lookup Sample iPhone Application Overview

Page 14 of 16

Application Overview - User Lookup iPhone Application Overview

Select the device. Select the Configuration Profiles tab. Select a configuration profile from the list and click Install. To install the profile, on the device, tap Install.

User Lookup Sample iPhone Application Overview

Page 15 of 16

Application Overview - User Lookup iPhone Application Overview

Additional Information
For more information and other sample applications please refer to:
Location MicroApps Home Page MicroApps Code Samples URL http://wiki.sdn.sap.com/wiki/display/Img/MicroApplications/Code+Samples http://wiki.sdn.sap.com/wiki/display/Img/MicroApplications/Code+Samples

User Lookup Sample iPhone Application Overview

Page 16 of 16