Integrating 
BlackBerry Enterprise Mobility Server
 services

This section covers the general approach for programming with the 
BlackBerry Dynamics SDK
 and the BlackBerry Enterprise Mobility Server services. The approach consists of two parts:
  • Programming an app to interact with the desired 
    BEMS
     services
  • Entitling users to the necessary applications
BEMS
 services conform to the Shared Services Framework. A service consists of two applications: A program that provides the service, and an app that consumes the service. 
BEMS
 is the service provider that must be configured for use in 
BlackBerry UEM
 or in standalone 
Good Control
. You create the app that consumes this service.

BEMS
 services APIs

The 
BEMS
 services are described in the 
BEMS
 API Reference Guides
.

Programming your service consumer app

You must define a unique 
BlackBerry Dynamics
 app ID for your application (for complete details, see Using an entitlement ID and version to uniquely identify a BlackBerry Dynamics app). The 
BlackBerry Dynamics SDK
 has functions to discover services, and each 
BEMS
 service has specific programming interfaces.
To discover the 
BEMS
 services, use 
GDServiceType
. This API and other APIs for shared services are described in other sections of this guide and in the BlackBerry Dynamics API reference.
After your consumer app discovers the service, the way the app communicates with the service depends on the service definition.
Most 
BEMS
 services run over SSL (HTTPS) on port 8443. Be sure your consumer application connects to the correct server and port.

Discovering the BlackBerry Enterprise Mobility Server services

Described here is a general approach to using the 
BlackBerry Dynamics SDK
 and Server-based Services Framework to programmatically discover the 
Docs
 services offered by your 
BEMS
 installation.
Item
Description
Service identifier
First you need to know the service identifier and version. For more information about the available services, see Mobile Services.
Service discovery
Next, code a service discovery query in your application program. See the 
getServiceProvidersFor
 API in the 
GDAndroid
GDiOS
, and 
GDMac
 classes.
Server cluster
The result of the service discovery query is an array of GDServiceProvider objects. Each object corresponds to a 
BlackBerry Dynamics
 entitlement ID that is registered as a provider of the service. Your best result is that the array has one element.
If the array is empty, it means that the current end user isn't entitled to any App ID that provides the service. In that case, your app shouldn’t use the service. 
If the array has more than one element, it means that the end user is entitled to more than one GD App ID that provides the service (likely a configuration error by the enterprise). Your app would have to pick one of the GD App IDs, or try all of them, or prompt the user to select.
In the 
GDServiceProvider
 object, there is a 
serverCluster
 attribute. It contains an array of 
GDAppServer
 objects, each of which tells you the address and port number of a server, and the priority of that instance within the cluster.
Server selection
If the 
serverCluster
 array has only one element, then server selection is trivial. Use the server address and port number of the first element.
If the 
serverCluster
 array is empty, that indicates an enterprise configuration error.
If the 
serverCluster
 array has more than one element, then you must implement a server selection algorithm. A sample algorithm is given on the 
GDAndroid
GDiOS
, and 
GDMac
 pages in the BlackBerry Dynamics API reference, in the 
getApplicationConfig
 section. The algorithm is the same for the 
BlackBerry Dynamics SDK for Android
 and for the 
BlackBerry Dynamics SDK for iOS
. The recommended selection algorithm is as follows.
For each priority value in the list, starting with the highest:
  • Select a server that has that priority, at random.
  • Attempt to connect to the server.
  • If the connection succeeds, use that server.
  • If the connection fails, try another server at the same priority, at random.
  • If there are no more untried servers at that priority, try the servers at the next lower priority.