8 Service Consumption
8.2 Toolkit for Android (GWPA)
8.2.1 Creating a Starter Application Project for Android
You can create a starter application for an Andriod device based on one of the following templates:
● A List/Details Starter Application
Generates a starter application for utilizing SAP data in list and details screens.
● A Basic Starter Application
Generates a starter application for consuming the SAP NetWeaver Gateway service. The generated
application has a sample UI view, and contains a semantic proxy and a Request Handler that is responsible for the Gateway connectivity and parsing of the service data.
.
● A Workflow Starter Application
Generates a starter application which displays the Workflow task information and allows the user to make a decision on the task.
The templates of the starter application provide a best-practice for creating a business-scenario application.
In addition, the starter application wizard generates the resources required for an application to interface with SAP NetWeaver Gateway, including a proxy for the OData service that you select in the wizard.
To create your Android starter application:
1. From menu bar, select File New Other . The New wizard dialog is displayed.
2. Expand the OData Development node and select Starter Application Project.
3. Choose Next. The New Starter Application Project page is displayed.
4. In the Project name field, enter a new name for your project.
5. From the Create a new project for drop-down list, selectAndroid.
6. In the Application name field, specify the name of the application that will be displayed to users.
7. In the Build target field, specify the Android SDK version for the application. The minimum supported Android platform version is Android 2.2.
8. In the Package name field, specify a package that conforms to the Java packaging naming format. For example, sap.android.crm.
Note
Android requires that the given package name consists of at least TWO tokens.
9. In the Activity field,specify the main entry activity for the application.
10. Choose Next.
11. Select the desired template. The wizard provides different options depending on the template you select.
12. Choose Next. The Location of OData Service page is displayed.
13. Select the Remote location radio button.
14. Select the desired SAP NetWeaver Gateway service in one of the following ways:
○ In the Service URL field, enter the desired service’s URL and then choose Go.
○ Choose Catalog and select the desired SAP service using the Service Catalog dialog.
○ Select the File system radio button and browse for the relevant service metadata and service document.
15. If you selected the List/Details template, you must configure the application as described on steps 16 to 27 :
Note
The Workflow and the Basic templates do not require further configuration.
16. Click Next. The Activity Layout page is displayed.
17. In the Activity Title field, enter the name of the first activity.
18. From the Activity Type drop-down list, the List option is automatically selected.
19. From the Entity Set Navigation drop-down list, select the desired entity set.
20. Select additional operations you would like to support from the activity. For activities of type List the following options are available:
○ Select the Add Create Option checkbox if you would like to add to this list activity the option of creating new items.
○ Select the Add Edit Option checkbox if you would like to add to this list activity the option of deleting displayed items.
○ For views of type Details, select the Add Edit Option checkbox if you would like to add to this details activity the option of editing the displayed item.
Note
You can choose to add to the activity an option to perform an operation that is described above (creation, deletion or editing of the entity set items), only if this operation is supported by the selected entity set.
21. Choose Add (+) to see the fields available for the selected entity set. The Add Fields page is displayed.
22. Select the checkboxes of the desired fields for the activity.
Note
It is recommended not to include more than three or four fields in a list.
23. Click OK.
24. If needed, select a field and click Remove (-) to delete it.
25. Use the Up and Down arrows to change the positioning of the fields in the activity. The field positioned first in the list will appear bold in the relevant generated application’s list activity.
26. In the Views section, choose to Add (+) another activity.
27. Repeat this procedure to configure the additional activities.
28. Choose Finish. The project is created.
Android JUnit Project
A JUnit Test class is created in the JUNIT project under the specified package name for the basic application. The test class file is called DemoTest. Appended to the end of the package name is the term test.
Note
Available only when creating an Android application based on the Basic Starter Application template of the Toolkit for Android (GWPA).
8.2.1.1 Extending the Generated Android Starter Application
You can modify and extend the generated code for your Android starter application to suit your needs. Extending the List/Details Starter Application
The Android starter application files based on the List/Details Application template are created and located in the specified Android project in the Eclipse workspace.
The number of files created depends on the number of activities you defined in the wizard and the number of entity types defined in the selected service.
The generated List/Details application contains code for using the SUP client library.
The Settings screen has access from the Login screen and from the first screen. The Settings screen has two connection options: SAP NetWeaver Gateway and SUP.
To use the SAP NetWeaver Gateway connection, the user must configure the Gateway URL and Gateway client.
To use the SUP connection, the user must configure the SUP settings (Host, Port, Application ID, security configuration and Farm ID).
Extending the Basic Starter Application
You can modify and extend the generated code for the Basic Android application to suit your needs.
The generated code provides an example for reading properties from one of the addressable collections of the selected OData services.
Your Android application files based on the Basic Application template are created and located in the specified Android project in the Eclipse workspace. It includes code sample for using the generated proxy for the service in a user interface.
Also, the generated Android application contains commented code for using the SUP client library to showcase probable uses for the application.
To run the generated Android Basic application:
1. From the newly create Android project, go to the folder, src, expand your package and open the activity class, for example, <project_name>Activity.java
2. Go to the following line and replace the placeholder; <username> and <password> of the service with the actual logon credentials to your SAP system:
public class AndroidCustomActivity extends Activity {
private String userName = "<userName>";
private String password = "<password>";
3. Run the application.
The Settings screen has access from the Login screen and from the first screen. The Settings screen has two connection options: SAP NetWeaver Gateway and SUP.
To use the SAP NetWeaver Gateway connection, the user must configure the Gateway URL and Gateway client.
To use the SUP connection, the user must configure the SUP settings (Host, Port, Application ID, security configuration and Farm ID).
Extending the Workflow Starter Application
The generated Workflow Android application enables users to view and manage their Workflow tasks using an OData service for Workflow in the SAP NetWeaver Gateway server.
Depending on the Workflow service, your application is composed of four components:
● Splash Screen
The splash screen is used to notify the user that, the application is in the process of loading. It disappears when the application's main window displays.
The logic for the splash screen is handled by the code in the generated project within the class, SplashScreen.java.
● Login screen
The login screen handles the user authentication with the OData services in SAP NetWeaver Gateway.
Users must provide a user name and a password. The login and authentication logic is handled by the code of the login method in the class, LoginActivity.java.
● Workflow Task List
The main screen of the application displays the Workflow task list and access to the details of each task.
Note
When your application loads for the first time, it obtains the content of the task list from SAP NetWeaver Gateway.
The service provides the task priorities as numbers that are mapped to strings as follows:
Priority Description
The task priorities are also marked with colors: high priorities, one to four (1-4) in red, medium priority (5) in black, and low priorities six to nine (6-9) in grey.
Task Filter
Tasks can be filtered by task name, which usually represents the type of task, such as, Leave Request, Purchase Order, and many more.
To filter the tasks:
○ Choose Filter and select the task name, or select All to view all tasks. The filtered task list displays according to your selection.
○ Choose Cancel to exit the filter view.
Task Search
In the task list view, you can search for tasks using the task name or part of the name.
To perform a search:
1. Click the search field at the top of the view.
2. Type the search item or term. The search is performed on all presented properties and the results are displayed while typing the search item.
Note
Search is performed only on the tasks displayed in the list (which may be filtered).
● Workflow Task details
After selecting a task from the task list, a view opens displaying the task details and enabling users to make a decision regarding the task.
The task details displayed include the following:
○ Task subject – displayed at the top of the view as the task title.
○ Task properties - status, creation date, creator and priority.
○ Task extended properties (X-props). Note: Default extended properties are not displayed.
○ Links to additional related task details, such as, comments, participants and attachments.
The task details logic is handled by the code in the generated project within the class, TaskDetailsActivity.java.
Decisions
To make a decision regarding the task:
1. Choose Make Decision. The list of actions received from the service for the task displays.
2. Choose an action to apply it or choose Cancel to return to the task details. After selecting an action, you can add a comment to be sent together with the task.
3. Choose the button with the action name to apply it.
Choose Cancel to return to the task details without applying the action. After applying the action, the Details view is once more displayed.
Completed tasks do not appear in the task list, when the application loads the next time.
Viewing Task Attachments
The Details view includes a link to task attachments (if there are any), showing also the number of attachments included.
To view attachments:
1. Choose Attachments. A view showing the file names of the task’s attachments is displayed.
2. Choose an attachment. The attachment opens in the appropriate content viewer according to the file type,
Viewing Task Participants
The Details view includes a link to the task participants (if there are any). Also, it shows the number of participants included.
Choose Participants. A view showing the task participant names and types is displayed.
Viewing Task Comments
The Details view includes a link to the task comments (if there are any) showing also the number of comments included. Choose Comments. A view showing a list of task comments including each comment’s creator, creation date, and content is displayed.
Viewing Task Description
The Details view includes a link to the task description (if relevant). Choose Description. A view showing the task description is displayed.
● Settings Screen
The Settings screen has access from the Login screen and from the first screen. The Settings screen has two connection options: SAP NetWeaver Gateway and SUP.
To use the SAP NetWeaver Gateway connection, the user must configure the Gateway URL and Gateway client.
To use the SUP connection, the user must configure the SUP settings (Host, Port, Application ID, security configuration and Farm ID).
8.2.1.2 Extending the Generated Basic Application
Use the generated basic application to develop your own application using the Java library API to call SAP NetWeaver Gateway.
The following is an example of how to use the generated basic application.
First, determine the business scenario for your application. For example, your application will do the following:
● Enable users to search for flights from one location to another.
● Users should be able to get details about a flight, such as, city of origin, destination city, departure date, and arrival date.
The following is an example code that calls the OData Java library to consume the OData service, RMTSAMPLEFLIGHT in an SAP NetWeaver Gateway server:
● Creating the request URL.
String requestUrl = "/sap/opu/sdata/iwfnd/RMTSAMPLEFLIGHT/CarrierCollection (carrid='" + carrid + "')";
● Defining Gateway connection settings.
IServerConnectionParameters gateway = new ServerConnectionParameters ("<host>",
"<port>","<client_id>", <useSSL>);
● Create the authentication object.
The example below shows basic authentication implementation.
IAuthentication credentials = new
UsernamePasswordCredentials("<user>","<password>");
Note
You must replace <user>, <password> with the appropriate values.
You can add your own interceptors and authentication implementation.
Initializing the REST client based on the connection details. The following are the option for setting the representation: ATOM, or JSON.
IRestClient restClient = RestClientFactory.createInstance(gateway, credentials, Representation.ATOM);
● Executing the request.
IRestRequest request = new RestRequest(requestUrl);
IRestResponse response = restClient.execute(request);
return response.getBody();
● Example code for parsing returned response. Parsing the response string XML into an ODataEntry object.
ODataEntry carrierEntry =
ODataParserFactory.createInstance(Representation.ATOM).parseODataEntry(response);
● Getting the carrier properties and printing to the standard output.
ODataProperty[] properties = entry.getProperties();
for (ODataProperty oDataProperty : properties)
{ System.out.println(oDataProperty.getName() + ": " + oDataProperty.getValue());
} .
● Example code for using a function import: GetAvailableFlights Create the request URL.
String requestUrl = "/sap/opu/sdata/iwfnd/RMTSAMPLEFLIGHT/GetAvailableFlights?
cityfrom=" + cityFrom + "&cityto=" + cityTo + "&fromdate=" + fromDate +
"&todate=" + toDate;
● Defining Gateway connection details.
IServerConnectionParameters gateway = new ServerConnectionParameters ("<host>",
"<port>","<client_id>", <useSSL>);
● Initializing the REST client based on the connection settings.
IRestClient restClient = RestClientFactory.createInstance(gateway, credentials,Representation.ATOM); IAuthentication credentials = new UsernamePasswordCredentials("<user>","<password>");
● Calling the SAP NetWeaver Gateway server.
IRestRequest request = new RestRequest(requestUrl);
IRestResponse response = restClient.execute(request);
return response.getBody();
}