Skip Headers
Oracle® Retail POS Suite Implementation Guide, Volume 5 – Mobile Point-of-Service
Release 14.1
  Go To Table Of Contents


3 Mobile POS Server Overview

The Mobile POS server application provides a REST-based interface into the Oracle Retail Point-of-Service application. The application is comprised of six high-level component areas, as depicted in Figure 3-1.

Figure 3-1 Mobile POS Components

The components are deployed as a war file into a WebLogic application server that has been configured to support REST through the Jersey libraries. The war file contains a mobile POS tier that provides access to the tour engine and the tours used to support the programming API.

Solution Components

This section describes the components shown in Figure 3-1.

REST Interfaces and Service Implementations

The API is exposed through a REST-like API, allowing HTTP clients to easily access the services. These services are also available through a Java API that sits behind the REST interface. The service interface and implementation classes can be found in the oracle.retail.stores.mobilepos.web.service package and its sub-packages. The services are organized into seven service areas:

  • About for version information APIs

  • Auth for authentication APIs

  • Customer for customer APIs

  • Item for item lookup APIs

  • Order for order APIs

  • Register for register APIs

  • Transaction for retail transaction APIs

View Objects

The REST layer returns the results of each method call through a Status instance, marshaled to either JSON or XML, depending on the MIME-TYPE requested by the client. The view objects carry the data requested by the caller, as well as status information, in the form of error codes and their associated messages. These classes are in the oracle.retail.stores.mobilepos.status package and its sub-packages.

Access to Tours

The services use a mobile POS tier and the TourRunnerIfc to access POS tour code. A traditional POS tour map is a single connected graph of sites, organized into tours connected by transfer stations. See Figure 3-2.

Figure 3-2 Traditional POS Tour Map

Once the POS client tier is loaded, the initial tour is started and the thread of execution never leaves the tour engine. It transitions from site to site as letters are mailed and waits at each site until the next letter is processed.

Unlike traditional POS tours, Mobile POS service calls run a single branch of a tour, not the entire graph.

Figure 3-3 Tour Access

The following describes Figure 3-3:

  1. The Tour Runner acts as an entry point into a tour script, mimicking a transfer station to provide shuttle behavior for the tour.

  2. Each service API method runs a configured tour script and retrieves the tour results through configured shuttles. Input parameters for the service are packaged up into Tour Parameters and passed into the Tour Runner.

  3. The Tour Runner then loads the specified tour from the Tour Script and uses the Launch Shuttle to convert the Tour Parameter into the cargo used by the Tour.

  4. Once the tour completes its processing, the Return Shuttle is called with the populated cargo. The Return Shuttle converts the cargo into the Tour Results object. Those results are then returned to the calling service API.

The tours executed by the API are the same tours defined in a typical ORPOS client, some with minor modifications to support head-less operation. As such, the tours make use of existing Manager/Technician pairs and access the store server just like the register-base POS client. The classes used to launch and return from these tours are located in the package and its sub-packages. The mobile tier classes needed to run these tours are found in the oracle.retail.stores.mobilepos.manager.tier package.

Application State Management

This API is designed to keep the client application as thin as possible. To aid in that goal, the Mobile POS server tracks the state of key objects within the servlet container. Each authenticated user has a separate session space, and, within that space, the following information is tracked:

  • Register status

  • Store status

  • Authenticated operator

  • Current retail transaction

  • Most recently completed retail transaction, if available

Unlike traditional REST APIs, this API does not require that the client pass object state into the API. Instead, the API accepts parameters and returns the affected object's state to the caller. Once a user's session is terminated, either by logging out or due to inactivity, all objects in the session are discarded. When this happens, any active transactions are cancelled.

Because the API is stateful, there is a dependency order to some of the API calls.

Figure 3-4 Service Area Dependencies

These dependencies follow the service area boundaries closely. The Login and About service areas have no prerequisites. Their APIs can be called at any time. The Register and Item service areas require that the login API be called before accessing their APIs. And finally, the Transaction service APIs require that the open register API be called before trying to work with transactions.

Device Profiles

The Mobile POS API uses the concept of a device profile. These profiles include the mapping of a unique vendor ID to a store and register ID, store currency information, relevant parameter values, and other needed configuration information. The profiles are managed through Spring and can be found in the DeviceContext.xml file.


The register IDs used in the DeviceContext.xml file are assumed to be contiguous. When you are assigning IDs to the mobile registers, do not intersperse fixed register IDs with mobile register IDs.


All the mobile devices running on the same Mobile POS server share the same parameter values. If any parameter values are changed, all the mobile devices get the same updates.

Authentication and Authorization

The Mobile POS API uses two levels of authentication due to its unique deployment configuration. As a web application, the servlet container authenticates the request using the same custom plug-in the other POS Suite web applications use. Once the request is authenticated, the stateful services require that the user call the login API before several other API calls. This second authentication uses the existing POS login tour to establish the user in the session.

Authorization is handled by the tours, just as in the register-based POS client. In order to provide the credentials to the POS tour, HTTP Basic Authentication must be used when accessing the login API. All service APIs are protected resources, so authenticated sessions are required for access, but the login API requires HTTP Basic Authentication to succeed.

Due to the multi-client nature of the Mobile POS application, security access is managed by register. As a result, you must provide the register number as the appID to any cargo used by a Mobile POS tour. This ID maps the user credential to the active mobile session. Doing this insures that the proper user credential is checked by any Site needing to verify access permissions. Additionally, the AbstractRegisterWebService provides the checkAccess (Status status, int roleFunctionID, String registerID) API for checking permissions at the service layer.

Login Functionality Gap

Mobile Point-of-Service and Point-of-Service both use the same Password Policy system configurations including Employee Login Lockout. This system configuration sets the number of invalid login attempts allowed before locking the user out of the application.

In Mobile Point-of-Service, each invalid login attempt increments NUMB_FLD_PW in the PA_EM table by two instead of one. In this case, if the Employee Login Lockout system configuration is set to four, the user is locked out after two login attempts at Mobile Point-of-Service, but after four login attempts at Point-of-Service.

The Employee Login Lockout system configuration applies to both Mobile Point-of-Service and Point-of-Service and must be set appropriately to accommodate both applications. For more information on the system configuration, see the Oracle Retail POS Suite Configuration Guide.