OSBCore SDK Overview

©
Copyright 2014 PROLOGA GmbH. All rights reserved.

No part of this publication may be reproduced or transmitted in any form or for any purpose without
the express permission of PROLOGA GmbH. The information contained herein may be changed without
prior notice.

Some software products marketed by PROLOGA GmbH and its distributors may contain proprietary
software components of other software vendors.

Microsoft®, WINDOWS®, NT®, EXCEL®, Word®, PowerPoint® and SQL Server® are registered trademarks
of Microsoft Corporation.

IBM®, DB2®, DB2 Universal Database, OS/2®, Parallel Sysplex®, MVS/ESA, AIX®, S/390®, AS/400®,
OS/390®, OS/400®, iSeries, pSeries, xSeries, zSeries, z/OS, AFP, Intelligent Miner, WebSphere ®,
Netfinity®, Tivoli®, Informix and Informix® Dynamic ServerTM are trademarks of IBM Corporation in USA
and/or other countries.

Oracle® is a registered trademark of Oracle Corporation.

UNIX®, X/Open®, OSF/1®, and Motif® are registered trademarks of the Open Group.

Citrix®, ICA®, Program Neighbourhood®, Meta frame®, WinFrame®, Video Frame®, and MultiWin® are
trademarks or registered trademarks of Citrix Systems, Inc.

HTML, XML, XHTML and W3C are trademarks or registered trademarks of the W3C®, World Wide Web
Consortium, Massachusetts Institutes of Technology.

Java® is a registered trademark of Sun Microsystems, Inc.

Javascript® is a registered trademark of Sun Microsystems, Inc., used under license for technology
invented and implemented by Netscape.

MaxDB® is a trademark of MySQL OFF, Sweden.

SAP, SAP Logo, R/2, R/3, mySAP, mySAP.com, and other SAP products and services mentioned herein as
well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and in
several other countries all over the world.

All other products and service names mentioned are the trademarks of their respective companies.

These materials are provided by PROLOGA GmbH for informational purposes only, without representation
or warranty of any kind and PROLOGA GmbH shall not be liable for errors or omissions with respect to
the materials. These materials are subject to change without notice. The only warranties for PROLOGA
products and services are those that are set forth in the express warranty statements accompanying such
products and services, if any. Nothing herein should be construed as constituting an additional warranty.
National product specifications may vary.

The original text of this document has been written in German. An English language translation has been
provided as courtesy. In case of any conflict, it is agreed that the German version is the official original
version and text and shall prevail in all respects and that no translated language shall be offered as
evidence of the meaning of the German original.

© PROLOGA GmbH Page 2 of 15

Mobile On-Site Billing OSBCore SDK Overview
Document Version 1
Document History

Before you start the implementation, make sure you have the
latest version of this document.

The following table provides an overview of the most important document changes.

Version Important Changes

1 Created
2 Added Document upload
Table 1: Most important document changes

Table of Content

1 Introduction ................................................................................................................... 5
2 Login .............................................................................................................................. 6
3 Business Objects ............................................................................................................ 7
3.1 Meter Reader .................................................................................................................... 7
3.2 Tour................................................................................................................................. 7
3.3 Order ............................................................................................................................... 8
3.3.1 Online Billing..................................................................................................................... 9
3.3.2 Offline Billing .................................................................................................................... 9
3.4 Order Item ....................................................................................................................... 9
3.5 Invoice ........................................................................................................................... 10
3.6 Document ....................................................................................................................... 10
3.7 Inheritance ..................................................................................................................... 10
4 Workflow ...................................................................................................................... 11
5 Communication ............................................................................................................. 12
5.1 RequestData ................................................................................................................... 12
5.2 SendData ....................................................................................................................... 12
5.3 Gateway Data Classes ...................................................................................................... 12
5.3.1 Receiving Classes ............................................................................................................ 13
5.3.2 Result Classes ................................................................................................................. 13
5.3.3 Online Invoicing Process Data Classes ................................................................................ 13
6 Configuration ................................................................................................................ 15
6.1 Configuration Process ....................................................................................................... 15
6.2 Configuration Setting Format ............................................................................................ 15
6.3 Configuration Settings for OSBCore ................................................................................... 15

Table of Tables

Table 1: Most important document changes ..................................................................................... 3

Table 2: Business Objects of the OSBCore ....................................................................................... 7
Table 3: BOTours ......................................................................................................................... 8
Table 4:BOOrder .......................................................................................................................... 8
Table 5: Results of Online Billing .................................................................................................... 9
Table 6: Detailed Information for Offline Billing ................................................................................ 9
Table 7: BODocument ................................................................................................................. 10
Table 8: Receiving Classes ........................................................................................................... 13
Table 9: Result Classes ............................................................................................................... 13
Table 10: Online Invoicing Process Data Classes ............................................................................. 14
Table 11: Configuration Setting Format ......................................................................................... 15
Table 12: Configuration Setting for OSBCore .................................................................................. 15

© PROLOGA GmbH Page 3 of 15

Mobile On-Site Billing OSBCore SDK Overview
Document Version 1
 Glossary

Attention

Note

© PROLOGA GmbH Page 4 of 15

Mobile On-Site Billing OSBCore SDK Overview
Document Version 1
1 Introduction

This document describes basic concepts and objects used in OSBCore SDK. It contains an overview of
the following topics:

 Login process
 The different business objects of OSBCore
 The general workflow of an OSBCore application
 The communication with the SAP system
 The configuration

For more in-depth information please refer to the different How-to documents or the interface
description.

© PROLOGA GmbH Page 5 of 15

Mobile On-Site Billing OSBCore SDK Overview
Document Version 1
2 Login

A login on the SAP system is mandatory; otherwise the OSBCore cannot be used. Without a login, there
is no communication and also no current meter reader available.

A login can be done as:

 Online login (the login/password is verified in SAP)
 Offline login (the login/password is checked against local data store)

An offline login is possible if the meter reader was previously logged on on the client. The password is
stored in the memory to allow the communication. However, the password is not persistent, only a hash
(to check the password against) is stored. An offline login will only be processed after an online login was
not successful (because of connection issues).

If the login is not valid anymore the communication methods will throw an OSBException with ID
LOGIN_FORBIDDEN (see chapter 5).

A logoff functionality is also available (e.g. for switching to another user). For both processes see the
class BLMeterReader.

Before the meter reader can do a login the OSBCore must be initialized.

© PROLOGA GmbH Page 6 of 15

Mobile On-Site Billing OSBCore SDK Overview
Document Version 1
3 Business Objects

Business objects contain data of an entity and also define the logic applied to manipulate those data. All
business objects have the prefix BO. The following business objects are defined within the OSBCore:

Business Object Name Description

BOAcknowledgeData Stores received acknowledges to send back to SAP

BOBinaryMasterData Different master data for offline billing, stored as MMP formatted blob
BODocument Represents a document to be send to SAP
BODocumentLink Connects documents with one or more business objects
BOInvoice Manages data for an invoice. An order can have multiple invoices
BOMeterReader Manages meter reader data and user information
BOMeterReaderNote Stores meter reader notes
BOOrder Manages order data. Can have multiple order items and invoices.
BOOrderAddress Address data for an order
BOOrderItem Manages order item data. An order item represents a single register of the
meter
BOOrderNote Contains notes for an order (e.g. read from the business partner object in SAP)
BOResultData Stores the result data to send back to the SAP system
BOTour Manages tour data. A tour has one or more orders
Table 2: Business Objects of the OSBCore

All business classes have BOBase as a parent class. BOBase implements the data store logic (like
Load/Get, Save etc.) and has the property ID, which is the primary key for all business objects. SQLite is
the underlying database. There is no need to directly access the database; all necessary data can be
received via its business object.

Persistent properties are marked with the Field attribute. All other properties are not stored in the
database. In order to create an instance for a business object, use the class BOFactory. BOFactory has a
single instance, which is accessible via the static property Current. The method to create an instance is
called CreateBO.

All business objects can be inherited to change the logic or to add new properties. To enable the OSBCore
to use the derived class you need to register the class in the BOFactory before initializing the OSBCore.

3.1 Meter Reader

The meter reader business object represents the current user. The current logged in meter reader is
accessible via the CurrentMeterReader property of OSBCore. Meter readers are versioned (see document
Object Versions Documentation.docx).

3.2 Tour

A tour is the collection of associated orders. Tours are versioned (see document Object Versions
Documentation.docx).

The tour contains a status property. The status changes to

 New if all orders of the tour are imported
 Started if the method start is called
 Finished if the method finish is called

© PROLOGA GmbH Page 7 of 15

Mobile On-Site Billing OSBCore SDK Overview
Document Version 1
It is possible to have more than one tour with the status started.

BOTour publishes three events:

Event Description

OnAfterTourNew Is raised if a new tour was received from SAP

OnAfterTourChanged Is raised, if:
- The status of a tour changes
- Changes from SAP where received (e.g. new orders) or
- An order was finished
OnAfterTourDeleted Is raised if:
- A tour is deleted by SAP or
- The method finish of a tour is called
Table 3: BOTours

3.3 Order

OSB supports four different types of orders:

 Online: The order can be billed (after successful reading) via SAP
 Offline: The order can be billed (after successful reading) via SAP or local without connection to
the SAP
 NoInvoice: The order has no invoice and can only be used to collect the reading data
 PrintOnly: The order has no order items and can only be used to print prepared invoices

An order has four statuses:

 New: The order is not started or not all registers (order items) are read yet
 Read: All registers have an valid result
 ReadyToPrint: For offline/online orders: The invoice is calculated and can be printed
 Finished: The order is completed and will be deleted

BOOrder publishes three events for change notifications:

Event Description

OnAfterOrderNew Is raised if a new order was received from SAP

OnAfterOrderChanged Is raised if:
- The order status changes
- Changes from SAP where received or
- An order was finished
OnAfterOrderDeleted Is raised if:
- An order is deleted by SAP or
- The method finish of an order is called
Table 4:BOOrder

If the method finish is called, the order and its dependent results (e.g. order item or invoice results) are
sent back to SAP and the order is deleted from the data store.
An order can contain:
 One or more order items
 One or more invoices
 One or more notes
 An address object.

© PROLOGA GmbH Page 8 of 15

Mobile On-Site Billing OSBCore SDK Overview
Document Version 1
3.3.1 Online Billing
To start the online process you can call StartBillOnline. The order needs to have the type online or offline
and must be set on Read. On StartBillOnline the OrderKindResult is set to online.

Online/offline orders have a special status to represent the online billing process:
 None: There was no online billing started
 Request: The order was marked for online billing
 Delivered: The reading results are sent to the SAP
 Activated The billing/invoicing was triggered in SAP
 Finished: The online process is finished (successful or not)

For the online billing process it is necessary to have a connection to the SAP and to call RequestData/
SendData regularly (see chapter 5 for more details).

Since the online billing process is asynchronous, you can register two events to get informed about the
result of this process:

Event Description

OnOnlineInvoiceResult The invoice was created by the SAP and sent to the mobile client, the order has the
status ReadyToPrint
OnOnlineInvoiceFailed The online billing/invoicing was not successful, if Rejected is true the billing process
was not started on SAP side
Table 5: Results of Online Billing

On order level you can subscribe to those events, which belong to exactly this order. On class BLImport
you can subscribe to the same events for all orders.

If you want to cancel the online billing process (e.g. because the maximal waiting time is over) call the
method CancelBillOnline.

If the SAP billing process failed the OrderKindResult is set to NoInvoice.

3.3.2 Offline Billing

To start the offline billing you can call BillOffline. The order needs to have the type offline and must set to
Read or ReadyToPrint.

You can subscribe to the following events for detailed information about the process:

Event Description

OnBillingEngineAfterSetValue Get results of assigning the meter reading result of every billing relevant
register
OnBillingEngineAfterValidateValue Get results of the validation of every billing relevant register
Table 6: Detailed Information for Offline Billing

If the process was successful the orders status switches to ReadyToPrint and some properties of the
invoice are updated (NetAmount, TaxAmount, Currency and Hash). The OrderKindResult is also set to
offline.

3.4 Order Item

Although the order item represents the meter register and therefore is a central component of the OSB
the BOOrderItem has no events or status. Moreover, the order items have no version (see document
Object Versions Documentation.docx). The order item is managed via its order.

© PROLOGA GmbH Page 9 of 15

Mobile On-Site Billing OSBCore SDK Overview
Document Version 1
3.5 Invoice

An order can contain one or more invoices. Invoices have different types:
 Simulation: It is necessary to do offline billing/invoicing.
 Online: Result of the online billing/invoicing
 Delivery: Invoice was created on order creation, only printing and delivery necessary
 Information: Invoice stub, used to print an notification if the online billing failed

Each offline order needs exactly one simulation invoice and only offline orders should have a simulation
invoice. The simulation contains all reading independent information of the invoice (e.g. address) and
also the order specific data to process the offline billing/invoicing.

A delivery invoice can be part of an online or offline order. PrintOnly orders always have at least one
delivery invoice.

An information invoice can be part of an online order. It contains basic data to print a notification for the
customer if the online invoice creation failed/was not possible.

3.6 Document

BODocument and BODocumentLink allow to link files with business objects and send them to the SAP
system.
BODocument has a Type property which controls the processing of a document in SAP (see transaction
/WATP/MOB_CONFIG -> configuration master data -> DMS).
The document (file) content can be saved to the data store via the property Content or as a file system
link (via property ContentFileReference). The linked file will be deleted after sending the document to SAP
system. For larger documents it is recommended to use external files instead of including the content in
the data store.
BODocument publishes one event for notifications:

Event Description

OnSendDocumentFailed is raised when the document can't be send. e.g. when the file reference isn't
available.
Table 7: BODocument

A BODocument should have at least one connected BODocumentLink. You can create Link by using the
helper methods on BODocument (Add*Link).
The BODocumentLinks property ObjectType definies the type of business object this Link is connected to.
For standard OSB objects the correct ObjectType is “/WATP/OBJ”.

3.7 Inheritance

Of course it will be necessary to adjust the standard data model of OSBCore to the customers’
requirements. This can be easily done by deriving the standard business objects and the Gateway data
objects to add new properties to them.

To replace the original business object/data object, it is necessary to register the new types on the
BOFactory. The registration needs to be done before initializing the OSBCore. For more details refer to
How-to Use PROLOGA OSBCore SDK.docx.

© PROLOGA GmbH Page 10 of 15

Mobile On-Site Billing OSBCore SDK Overview
Document Version 1
4 Workflow

A typical OSBCore application has the following workflow:

 Create an instance of the OSBCore (OSBCoreAndroid or OSBCoreWindows) and initialize it

 Get login and password from user and do a login (offline or via SAP)
 Start a thread to maintain periodically communication
 Receive tours (including orders etc.) and master data
 Send reading results
 Request invoices for reading values
 After receiving a tour, process an order:
o Let the user read register values for this order
o If required process the invoicing
o If the order has the type offline the invoicing can be done on the device
o If the order has the type online the invoicing has to be done via SAP
o If an order is finished the results will automatically send back to SAP
 Process all orders of that tour
 After all orders are done the tour is closed and deleted from the data store

© PROLOGA GmbH Page 11 of 15

Mobile On-Site Billing OSBCore SDK Overview
Document Version 1
5 Communication

The communication is processed using two methods: RequestData and SendData. Both methods should
be called periodically after the login is done.

If any orders are currently queued to do online billing/invoicing,

the normal communication will be stopped and only calls
necessary to process the online billing will be executed. The
reason for this behavior is to get the online result as fast as
possible, because the user/meter reader will be waiting for it. The
cancellation of an online process for an order is possible using
method CancelBillOnline.

5.1 RequestData

This method is responsible for retrieving all data from SAP:

1. Check if any orders are currently in the online invoice process

a. If yes: The method returns without doing any communication
2. If the parameter aIncludeMasterData is set to true:
a. Meter Reader Notes are requested/downloaded
b. Tax and Proof master data are requested/downloaded
c. Tour headers for current meter reader are requested/downloaded
d. Acknowledges for those data are sent back to SAP
e. Data for changed/new tours are downloaded
f. Billing master data are requested if required versions are not already downloaded
g. Version of the meter reader is updated.

5.2 SendData

This method sends the result data to SAP and also retrieves the results of the online billing/invoicing
process:

1. Handle online data

2. Send online results
3. Send activation of online orders
4. Check/download online results (including invoice)
5. If there are no orders in online process, all other results are sent to SAP (e.g. offline readings)
6. If parameter aIncludeFileData is set to true, pictures are also sent to SAP

5.3 Gateway Data Classes

In order to transfer data from and to SAP simple data classes are used. The classes contain simple
properties only and are not persistent. Objects of those classes are serialized/deserialized to the JSON
format. There are two types of data classes
 For sending data
 For retrieving data

© PROLOGA GmbH Page 12 of 15

Mobile On-Site Billing OSBCore SDK Overview
Document Version 1
5.3.1 Receiving Classes
The results of the calls to the SAP are deserialized to objects of the data objects below:

Data Class Corresponding Business Class Description

GWBillingMasterData BOBinaryMasterData Data structure for billing master data

GWLogin - Represents the data class retrieved after
successful login
GWMeterReader BOMeterReader Represents the data class for meter reader
GWMeterReaderNote BOMeterReaderNote Represents the data class for meter reader
note
GWOrder BOOrder Represents the data class for an order
GWOrderAddress BOOrderAddress Represents the data class for an order address
GWOrderInvoice BOInvoice Represents the data class for an order invoice
GWOrderItem BOOrderItem Represents the data class for an order item
GWOrderNote BOOrderNote Represents the data class for an order note
GWTour BOTour Represents the data class for a tour
GWTourSequence (Stored in BOOrder) Represents the data class for a tour sequence
Table 8: Receiving Classes

All data objects with a direct corresponding business object apply their data to a BO by using its method
AssignFrom.

5.3.2 Result Classes

In order to send results back to SAP the result data of a business object is assigned to its data class. This
data class is serialized to JSON format and transferred to SAP. To get a result data object of a BO the
method AssignTo is called.

Data Class Corresponding business class Description

GWDocumentResult BODocument Document (file) result data

GWDocumentLinkResult BODocumentLink Links document and business objects
GWLoginResult - Represents the login result data class
GWMeterReaderResult BOMeterReader Represents the data class for meter reader
result
GWMeterReaderResultVersion - Represents the data class for meter reader
version result
GWOrderInvoiceResult BOInvoice Represents the data class for an order invoice
result
GWOrderItemResult BOOrderItem Represents the data class for an order item
result
GWOrderResult BOOrder Represents the data class for an order result
GWOrderResultVersion - Represents the data class for an order
version result
GWTourResult BOTour Represents the data class for a tour result
GWTourResultVersion - Represents the data class for a tour version
result
Table 9: Result Classes

The three data classes with the postfix version are used to confirm the version of meter reader, tours and
orders after receiving them.

5.3.3 Online Invoicing Process Data Classes

Class Description

GWOnlineInvoiceRequest Represents the data class for online invoice requests

GWOnlineInvoiceActivation Represents the data class for online invoice activations
GWOrderKey Represents the data class for an order key (used for online invoice activation)

© PROLOGA GmbH Page 13 of 15

Mobile On-Site Billing OSBCore SDK Overview
Document Version 1
GWOnlineInvoiceResult Represents the data class for online invoice result
Table 10: Online Invoicing Process Data Classes

© PROLOGA GmbH Page 14 of 15

Mobile On-Site Billing OSBCore SDK Overview
Document Version 1
6 Configuration

The OSBCore provides a configuration mechanism. This process is implemented in the OSBConfig. An
instance of that class is available at the Config property of the OSBCore. This property is filled during the
initialization of OSBCore.

This configuration is used by the OSBCore itself and can also be used to retrieve application settings.
OSBConfig does not support the writing of settings to the config-ini file, it is for reading only.

6.1 Configuration Process

The configuration is text file based. In the OSBCore a property ConfigFileLocation can be filled by the
application. In this location a config.ini file is expected. It allows changing the configuration of the
application without creating a new version (especially for Android apps). If ConfigFileLocation is filled and
a config.ini file is found at this location, the configuration will be read from this file. Otherwise the
config.ini from the application asset (Android app) or from the application folder (Windows) is used.

6.2 Configuration Setting Format

A setting is a triple of the following values:

Name Description

Section A section is started by a single line containing sections enclosed in square

brackets. A section is valid for all settings until the next section starts. A
section can be defined in multiple places, but that should be avoided keeping
the file easy readable.
Name Name is the identifier of the setting. The name is unique within a section.
Names and values are defined in one line and are separated by a ‘=’. If a
setting is defined several times in the file, the last occurrence is used.
Value The value can be one of the following types:
- String
- Integer
- Decimal
- Double
- Boolean
Table 11: Configuration Setting Format

In order to read a setting use the get*-methods of the OSBConfig class. Every method has three
parameters: the section, the name and a default value.

6.3 Configuration Settings for OSBCore

The following settings are read by the OSBCore by OSBConfig:

Section Setting Description

COMMUNICATION PPP Uri to SAP (reachable via PPP)

COMMUNICATION WLAN Uri to SAP (reachable via WLAN)
COMMUNICATION GPRS Uri to SAP (reachable via GPRS)
COMMUNICATION ORDERPAGINGSIZE Maximal count of orders read from SAP with one call, if not
defined all orders of a tour are read at once
Table 12: Configuration Setting for OSBCore

At least one of the Uri settings is necessary to use the OSBCore.

© PROLOGA GmbH Page 15 of 15

Mobile On-Site Billing OSBCore SDK Overview
Document Version 1