Child pages
  • openBIS iPad App
Skip to end of metadata
Go to start of metadata

Introduction

The openBIS iPad app is an native iOS application designed for displaying information from an openBIS instance.

The app uses a navigation and interaction model that is natural to the iPad to support browsing openBIS data on and offline.

User Interface (UI)

The UI of the iPad app is broken into two sections, the navigation section and the details section. (Will add screenshots from app to aid illustration). The navigation section is for browsing and navigating information in an openBIS instance. It shows summary information about entities to provide an overview. The details section is for looking at one single item and shows all information about that item.

Implementing an iPad UI for an Instance

The iPad app is generic -- it is designed to talk to any openBIS instance. The instance provides services that map from openBIS to the iPad to support the app. To provide an iPad UI for an openBIS instance, one needs to decide on a navigation model and an decide what information from openBIS should be shown where. This is the core design task. Once that has been done, implementation is the relatively straightforward task of providing the information necessary to support that model.

The sections on the the ipad-ui core plugin module and the ipad-read-service-v1 provide the detailed information necessary to customize the iPad UI to the data in an openBIS instance. The following sections discuss the decisions in the design process.

Mapping from openBIS to the iPad

The iPad data model is more generic than the openBIS data model. Whereas openBIS tracks domain-specific information such as experiments, samples, etc., the iPad app only stores information necessary to support navigation and display. It does not know about the meaning of information within a domain context -- it only knows about how to navigate from some information to another. Because of this, the iPad app supports flexibly mapping information from openBIS to the iPad to support just about any kind of navigation.

Both openBIS and the iPad app refer to groupings of information as entities. To disambiguate, we will refer to "openBIS entities" and "iPad entities" to make clear which we mean, because one openBIS entity may map to several iPad entities and vice-versa.

Structuring data in iPad entities comes down to determining how the user will navigate the information. In many cases, a one-to-one mapping from openBIS entities to iPad entities is an appropriate solution. There are, however some situations in which a more complex mapping is warranted. Sometimes it makes sense to show information from several openBIS entities in one place in the iPad. One example of this is a situation where the user wants to see the metadata for a sample in the context of the data set associated with the sample. This case can be easily implemented in the iPad app.

On the other hand, there are situations where one openBIS entity might best map to several iPad entities to support the desired navigation structure. For example, one openBIS data set may contain three images. By mapping the openBIS data set to three iPad entities, it is possible to show each image on its own page.

Once a navigational scheme has been decided up, the sections below explain the steps necessary to support it.

The ipad-ui core plugin module

The ipad-ui core plugin module defines the services used by the openBIS iPad app. The iPad app is currently read-only, so there is only one service used by the iPad app, the ipad-read-service-v1. In the future, the iPad app may gain the ability to modify entities, requiring the creation of an additional service.

The ipad-read-service-v1 Service

Summary

The purpose of the read service is to provide information about entities to the iPad. To do this, it receives requests for data, retrieves the information necessary to fulfill this request, and translates between the openBIS entities, such as experiment and sample, and iPad entities. iPad entities are not the same as openBIS entities. The iPad has a much more generic understanding of entities and ties entities very closely to information displayed in the UI. Since the correspondence between openBIS entities and iPad entities is not simply one-to-one, one openBIS entity may be spread over several iPad entities and one iPad entity can contain information from multiple openBIS entities, the communication model is designed to make it possible for the service to map back and forth between iPad entities and openBIS entities.

iPad Data Model

The iPad data model tracks information for displaying and navigating between entities on the iPad. Each element in the model is used for a specific purpose in the UI. This table summarizes the pieces of the iPad entity data model and describes what the information is used for.

 

ColumnDescriptionUseExamples
PERM_IDA stable identifier for the object.Used internally to map from server data to local data.openBIS permId
REFCONData that is passed unchanged back to the server when a row is modified. This can be used by the server to encode whatever it needs in order to modify the row. Transmitted as JSON.For server use only; transmitted to the server on every call that it is appropriate.E.g., {code : [code], entityKind : [entity kind], entityType : [entity type], permId : [permId]}
CATEGORYA category identifier for grouping entities.Used to group entities together.openBIS entity type
SUMMARY_HEADERA short summary of the entity.Shown in listings and as the header for detail views.openBIS code
SUMMARYA potentially longer summary of the entity.Shown in listings and in detail views.The content of a <code>description</code> property
CHILDRENThe permIds of the children of this entity. Transmitted as JSON.Used to navigate between entities. Entities with children allow drill down and the children are shown in the drill-down view.Sample / data set children. An experiments samples or data sets may also be shown this way.
IDENTIFIERAn identifier for the object.Shown in detail views.openBIS identifier
IMAGE_URL (deprecated: use IMAGES instead)A url for an image associated with this entity. If None or empty, no image is shown.Shown in detail views.An image from the DSS. An external image.
IMAGESA hash map containing image specifications (described below). Two keys are possible: MARQUEE, a single image specification shown in a prominant location; TILED, many image specification shown in a tiled display.Shown in detail views.An image from the DSS or an external image from the web.
PROPERTIESProperties (metadata) that should be displayed for this entity. Transmitted as JSON.Shown in detail views.openBIS properties
ROOT_LEVELTrue if the entity should be shown on the root level.Used to construct the initial navigation view.Empty means do not show. Non-empty means show.

There are two fields in the data model that have a purpose beyond the UI. These are the `PERM_ID` field and the `REFCON` field. The `PERM_ID` field is assumed to be a stable identifier for the iPad entity and, thus, cannot change. The `PERM_ID` field is used by the iPad app to associate information from the server to the correct entity on the app.

The `REFCON` field is a field that is not touched by the iPad app at all. The server is free to place whatever information it wishes in this field. The content of the `REFCON` is sent back to the server when the iPad makes requests for more data for an existing entity. The server can thus use the `REFCON` to keep track for itself how several openBIS entities are merged into one iPad entity, for example. The `REFCON` is updated on every request, so the service can modify this value if it is appropriate.

Image Specification

Image specifications describe images. They may contain either a URL for the image or the data for the image itself.

keyvalue
URLA url to the image. The url may refer to the DSS or somewhere in the Internet.
DATAA map containing the data for the image. The format has not yet been finalized, but we expect it to include the following keys: 'BASE64' (base-64 coded data for the image), 'FORMAT' (the image format, e.g., PNG, JPG, etc.)

Communication

The communication model between the iPad and the service has been designed to transmit only the necessary information on demand, when needed. The iPad specifies what kind of data it needs in the parameter key `request`. The response, as with all aggregation services, is in the form of a table model. The headers in the table model correspond to columns in the data model described above. The service then returns only the information requested back to the iPad. The `PERM_ID` and `REFCON` are always returned, as they are used by the communication model to match responses to iPad entities and iPad entities to openBIS entities.

Requests

requestKeyArgumentsDescriptionUseColumns
CLIENT_PREFSNoneReturn values for the client preferences.Used to initialize client behaviorKEY, VALUE
NAVIGATIONNoneReturn the top-level categories used for navigation.Used to initialize the top level of the navigation view.PERM_ID, REFCON, CATEGORY, SUMMARY_HEADER, SUMMARY, ROOT_LEVEL
ROOTentities : List of {"PERM_ID" : String, REFCON : String}Return root entities for the specified navigational entitiesUsed to track which entities should be constantly available on the iPad.PERM_ID, REFCON, CATEGORY, SUMMARY_HEADER, SUMMARY, CHILDREN, ROOT_LEVEL
DRILLentities : List of {"PERM_ID" : String, REFCON : String}Return navigational information for the specified entities.Used to navigate. The result should at least include data for children of children to permit efficient navigation on the iPad.PERM_ID, REFCON, CATEGORY, SUMMARY_HEADER, SUMMARY, CHILDREN
DETAILentities : List of {"PERM_ID" : String, REFCON : String}Return detail information for the specified entities.Used to display the entity in the detail view. This should return all information necessary to show the entity.PERM_ID, REFCON, SUMMARY_HEADER, SUMMARY, IDENTIFIER, IMAGES, PROPERTIES
SEARCH{searchtext : String, searchdomain : Map}Return a list of entities that match the specified search string. The search is restricted to the searchdomain, which is either null or one of the domains specified in the preferences.Used to search for matching entities on the server. This returns information necessary to navigate the results (same as DRILL).PERM_ID, REFCON, CATEGORY, SUMMARY_HEADER, SUMMARY, CHILDRE

Preferences

The CLIENT_PREFS request returns information used to configure the client. This information includes the following:

KeyValue TypeDescriptionUse
ROOT_SET_REFRESH_INTERVALNumberThe number of seconds the client should wait between calls for the root setUsed to throttle client/server request frequency
SEARCH_DOMAINSArray of DictionaryThe domains that can used in searches. The dictionary for a domain should include the keys "key" and "label". The label is displayed in the UI. The domains are displayed in the order sent by the server. The first value in the array is the default search domain on the client. If there is a global domain, that should be the first one.Used to support searching in specific domains. Example include "GLOBAL", that is search everywhere, "BARCODE", which searches just for values that can be barcodes, etc.

Communication Model

On startup, the iPad app requests the client preferences. These preferences configure how the client should behave. For example, the server can inform the client how often it should refresh its root set. This allows the server to control the load caused by ipad clients. Once the preferences have been retrieved, the client starts initializing its root data, if necessary. The root data contains all the entities that should be stored locally on the iPad. To initialize the root data, it first retrieves the categories from the server. The categories determine the groups shown at the very top level of navigation. These categories are typically not real openBIS entities; they are just there to aid navigation and group entities suitably. Once the categories have been retrieved, the client retrieves the root data for each category by specifying `{ requestKey : ROOT, category : [category ref con]}` as the request parameters.

Reference Implementation

Under the openbis-ipad project:

The main reference implementation for the ipad server service: The plugin ipad-ui-demo, this plugin uses the ipad-framework.jar.

A Debug UI that simulates the ipad calls, very useful to test connectivity to the server: The ipad-ui plugin .

The openbis_mobile project:

This project contains the classes found at the ipad-framework.jar, depending of the extensions required they will maybe need to be updated and exported again as a jar to be used by the Jython script.

  • No labels