blackberry developer summit rapid development ......page 4 of 15 1. workbook scope this workbook...

BlackBerry Developer Summit

Rapid Development Leveraging BEMS Services and the AppKinetics

Framework - iOS

of 15

Table of Contents 1. Workbook Scope ................................................................................................................. 4

2. Compatibility ....................................................................................................................... 4

3. Source code download & setup ........................................................................................... 4

4. App Kinetics Exercises ........................................................................................................ 4

Exercise One: Service Provider Discovery ............................................................................. 5

Exercise Two (a): Consume a service – Transfer File Service ................................................ 6

Exercise Two (b): Consume a service – Send Email Service ................................................. 7

Exercise Three: Provide a custom service .............................................................................. 8

5.BEMS Services Exercises ....................................................................................................... 8

Exercise One – Prepare BEMS Service usage ....................................................................... 9

Exercise Two – Consume Directory Service ........................................................................... 9

Exercise Three – Consume Docs Service .............................................................................11

Exercise Four – Auto Discover Service ..................................................................................11

Appendix A – Activate an Application in the BlackBerry Developer Summit Lab ....................................12

Appendix B – MyExpenses Service Definition ...................................................................................14

of 15

© 2018 BlackBerry. All rights reserved. BlackBerry® and related trademarks, names and logos are the property of BlackBerry Limited and

are registered and/or used in the U.S. and countries around the world. Xcode and iOS are trademarks of Apple Inc. All other trademarks

are the property of their respective owners. This documentation is provided "as is" and without condition, endorsement, guarantee,

representation or warranty, or liability of any kind by BlackBerry Limited and its affiliated companies, all of which are expressly disclaimed

to the maximum extent permitted by applicable law in your jurisdiction.

of 15

1. Workbook Scope

This workbook corresponds to the session –

• Rapid Development Leveraging BEMS Services and the AppKinetics Framework

2. Compatibility

These exercises can’t be done with an application running in Enterprise Simulation mode.

3. Source code download & setup

Application sample code can be downloaded from - http://www.blackberrydevsummit.com

The sample application depends on the BlackBerry Dynamics SDK. Ensure BlackBerry

Dynamics SDK is installed. SDK version 3.3.0.5929 has been tested with this sample

4. App Kinetics Exercises

These exercises can’t be done with an application running in Enterprise Simulation mode. If necessary, see the Application developer basics manuals for instructions on running applications in normal enterprise mode.

The Application-Based Services feature is for communication between two BlackBerry Dynamics applications, referred to as the service consumer and the service provider. You will therefore need two applications in order to complete these exercises.

One way to do these exercises is to use BlackBerry Work as one of the applications. BlackBerry Work is a provider of services, including Send Email and Transfer File, and also a consumer of services, including Transfer File.

Note that BlackBerry Work will not operate in Simulator. If you don’t have a device available to install BlackBerry Work use the AppKinetics sample app as part of the GD SDK sample apps.

of 15

Note: If you are using Simulator for these exercises, add additional URL scheme to the BBD_Services_Exercise app as follow. These steps are only if you are working on Simulator. You do not need do these steps if you are using a device with BlackBerry Work installed.

1. Open BBD_Services_Exercise in Xcode.

2. Open info.plist file

3. Add new URL scheme “com.good.gd.discovery.enterprise”

You need do these steps just for BBD_Services_Exercise application.

Exercise One: Service Provider Discovery

Select a service to consume.

For example, you could select the Transfer File service.

A complete list of services can be found on the application developer portal. Log in and then navigate to: Resources > BlackBerry Dynamics > Shared Services. This exercise doesn’t cover server-based services.

1. Get the service identifier and version.

The service listing that is mentioned in the previous step shows all the identifiers. Pages linked from the listing show the service versions, and the details of the service. Most services have only a single version.

For the Transfer File service:

– The service identifier is: com.good.gdservice.transfer-file

– There is only one service version: 1.0.0.0

2. Install and activate a service provider application.

For example, install and activate BlackBerry Work, which provides the service Transfer File. On Simulator, you can build AppKinetics sample app and run on the Simulator. AppKinetics also provides Transfer File service.

The application must be activated for the same end user in the same deployment as the application in which you code the following steps.

3. Code a service discovery query.

3.1 Open BBD_Services_Exercise project in Xcode.

3.2 In the ServiceConsumer+ServiceDiscovery.h or ServiceConsumer+ServiceDiscovery.swift file, define constants for the identifier, version and method of a shared service that you’ve installed on your device in the previous steps.

3.3 In the ServiceConsumer+ServiceDiscovery.m or ServiceConsumer+ServiceDiscovery.swift file, use the getServiceProvidersFor

of 15

method in the GDiOS class, to retrieve an array of service providers. Pass the service

identifier and version from the previous steps as parameters, and specify application-based as the service type.

3.4 Add code to log the relevant attributes (name, address, identifier etc.) of the GDServiceProvider objects that are returned.

3.5 Build the project and run the application. Press the button in the “Discover Providers” Tab to retrieve service providers. Check the logs you inserted and also the providers’ information for the service is displayed in the UI.

Exercise Two (a): Consume a service – Transfer File Service

Code the following.

1. Send a service request

Use the sendTo method in the GDServiceClient class. In the transferFile method in the ServiceConsumer+TransferFile.m or ServiceConsumer+TransferFile.swift file, call GDServiceClient sendTo method. Pass the necessary parameters:

a) application This is the service provider’s address. Use the GDServiceProvider object that is passed to transferFile method to obtain address.

b) service TransferFile service’s identifier.

c) version TransferFile service’s version

d) method TransferFile service’s method. Pass “transferFile” for this exercise.

e) params Pass nil.

d) attachments Pass the array of the file paths. This array object is already provided in the transferFile method.

e) option Specifies the foreground execution preference. In this exercise, Pass GDEPreferPeerInForeground value.

f) requestId ID that can be used to identify the service request on the response callback.

g) error NSError object

In the case where there are multiple providers for the service on the device, the application may present the list of service providers to the user and let them select one for the operation. In this exercise, this example app selects the first provider in the list that is returned from the service discovery API in the Exercise One: Service Provider Discovery.

2. Receive a service response.

of 15

A service response can be sent back to the sender of a service request by the provider that received it, as a form of reply. The details of service responses, if any, are part of the service definition. The Transfer File service definition specifies that an empty service response must be sent in reply to every successful service request. If the request fails, the response contains NSError object as params.

In the ServiceConsumer.m or ServiceConsumer.swift file, there are delegate methods implemented for GDServiceClientDelegate protocol. Add log to output the response from the service provider in GDServiceClientDidReceiveFrom method.

3. Build and Run Select “Transfer File” Tab, and then enter a file name and some text as the content of the file and tap the “Transfer File” button.

Exercise Two (b): Consume a service – Send Email Service

Code the following.

1. Use the sendTo method in the GDServiceClient class. In the sendEmailTo method in the ServiceConsumer+SendEmail.m file, call GDServiceClient sendTo method. Pass the necessary parameters:

a) application This is the service provider’s address. Use the GDServiceProvider object that is passed to sendEmailTo method to obtain address.

b) service sendEmail service’s identifier.

c) version sendEmail service’s version

d) method sendEmail service’s method. Pass “sendEmail” for this exercise.

e) params For this service, the parameters are passed with a dictionary object. In the exercise this is already created for you. The types of these parameters are defined in the service definition. For example, an array of strings is set for “to” key.

d) attachments Pass nil.

e) option Specifies the foreground execution preference. In this exercise, Pass GDEPreferPeerInForeground value.

f) requestId ID that can be used to identify the service request on the response callback.

g) error NSError object

2. Receive a service response.

A service response can be sent back to the sender of a service request by the provider that received it, as a form of reply. The details of service responses, if any, are part of the service definition.

of 15

In the ServiceConsumer.m file, there are delegate methods implemented for GDServiceClientDelegate protocol. Add log to output the response from the service provider in GDServiceClientDidReceiveFrom method.

3. Build and Run Select “Send Email” Tab, and then enter one email address – the example code assumes there is only one mail address here. Enter subject and mail body text and tap the “Send” button.

Exercise Three: Provide a custom service

In this exercise, we will implement a service provider for an application-based service “My

Expense”.

The implementation for this service provider is in MyExpenseServiceProvider.m or

MyExpenseServiceProvider.swift.

The delegate method for receiving a service request is implemented partially in

processRequestFrom method. It checks whether or not the request is valid – i.e. whether the

request is something that the provider supports such as service identifier, version and methods.

Code the following.

1. Add code to send the reply to the service consumer with the expense limit in

processGetLimitRequestFor method. Use replyTo method in GDService class. The params

should be integer as defined in the service definition. It has to be Object so the type is

NSNumber (Object-C) or Int (Swift).

2. Add code to log out the expense item and amount that the MyExpense service consumer

sent in processSetExpenseItemRequestFrom method. As defined in the service definition,

the prams of processGetLimitRequestFor is the properties (key/value) for “item” and

“amount”.

Sample code is not provided for a consumer of MyExpenses Service. The Service Definition for

the Service can be found in Appendix B. Creation of a Service Consumer for this Service can be

thought of as an ‘extra credit’ exercise and can be added to a new or existing BlackBerry

Dynamics application.

5.BEMS Services Exercises

These exercises correspond to the: Consume a BEMS Service session.

of 15

These exercises are based on the same sample code, the Services sample application

Exercise One – Prepare BEMS Service usage If the initial AppKinetics exercises were completed then the Services application will already be

build / installed / activated on device or simulator. If not do that first.

Server Based Services are ones which are provided by a Server and not an application.

However these Services are discovered in the same way as application services are

discovered.

GDiOS.getServiceProvidersFor( ) is the key method to use, and the Server Services definitions

can be found in list of public services - https://apps.good.com/#/services

In the Services application navigate to Service Discovery tab. Modify the code to discover the

Docs and Directory Server Services (instead of the Transfer File and Send Email application

application services which are used). Start by looking at ServiceDiscoveryViewController

TIP – In addition to the Service ID and version remember to change the Service Provider type.

The UI shows the result of Service Discovery for selected Server Service.

The important points from Server Service perspective are; Server Host, Server Port, Server

Priority. This information is then used as basis to consume Server Based Services.

Make sure you understand the returned items from Service Discovery query by browsing code,

setting breakpoints and asking questions.

Exercise Two – Consume Directory Service

https://apps.good.com/#/services

of 15

The Directory Service provides a REST API to query & retrieve information from Active

Directory. The specifics of the API can be found by reading API documentation which can be

found via Service Definition -https://apps.good.com/#/services

Navigate to the Directory Listing tab of the Services application. Enter a search query and select

SEARCH. For example you could search for ‘DevUser’. Below screenshot shows example

output (A production environment AD would likely have more fields) –

The code which handles actual Service use is – DirectoryServiceConsumer, UI code is –

DirectoryViewController

This code works as follows –

- On pressing SEARCH Service Discovery is used to find the BEMS Server host and port.

These are then used together with the lookup API endpoint address to create a full query URL

- GDAuthToken is used to authenticate the User to BEMS, as such app code checks if it has a

currently valid Auth Token for this URL. If it does not it requests one –

GDUtility.getGDAuthToken()

- When GDAuthToken is successfully returned an AsyncTask is created and executed which

makes the actual networking request.

- GD HTTP API is used as BEMS Service is an Enterprise Service and as such secure behind

enterprise firewall.

- Query is formed into post body which is sent. Response is parsed into a String and updated

into the UI

The core flow here is important, and the same for other Server Based Services –

1. Discover Server/Port for requested Server Service

2. Form URL based on this and desired API endpoint (from Service definition)

3. Request GDAuthToken for URL (if don’t already have one)

4. Make HTTP Request providing query

5. Receive response which is processed

https://apps.good.com/#/services

of 15

Make sure you understand this flow and code involved in DirectoryServiceConsumer by adding

breakpoints, changing query, asking questions

Exercise Three – Consume Docs Service

Consume Docs Service is another provided example of consuming Server Based Service. In the

Services Example application navigate to the Docs Listing Tab and hit “SEND LIST DOCS

REQUEST”. This will make a HTTP request to return contents of root of the Developer Summit

docs site.

This code can be found in DocsServiceConsumer. It follows the same flow as previous example

however shows use of different Service.

Make sure you understand the code involved by adding breakpoints, changing the query and

asking questions.

Exercise Four – Auto Discover Service

This exercise is ‘extra credit’ no sample code is provided.

However existing code could be repurposed to make use of this Service. This is an example of

making use of BEMS for auto discovery

REQUEST –

POST /api/autodiscover

{

"Settings": [

"EwsUrl",

"EasUrl"

]

}

of 15

RESPONSE

{

"EasUrl":{

"Status": "ok",

"Url": "https://XXXX/Microsoft-Server-ActiveSync"

},

"EwsUrl":{

"Status": "ok",

"InternalUrl": "https://XXXX/EWS/Exchange.asmx",

"ExternalUrl": "https://XXXX/EWS/Exchange.asmx"

}

}

Appendix A – Activate an Application in the BlackBerry Developer Summit

Lab

1. In activation screen of your sample application enter an email address of

DevUser###@BlackBerryDevSummit.com, replacing ### with the number assigned to

you when you arrived at the summit. The activation screen will appear as shown in the

screenshot below.

mailto:DevUser

of 15

2. Navigate to the BlackBerry UEM Self Service Portal to generate an access key:

https://uem.blackberrydevsummit.com:10443/index.jsp

3. Log in using the following credentials:

• Username: DevUser###

o Replace ### with the number assigned to you when you arrived at the

summit.

• Password: DevUser!2018

• Domain: BlackBerryDevSummit.com

4. Once logged in, click on the + button and choose “Generate a BlackBerry Dynamics

access key”.

5. Return to your sample application and enter the access key you just generated.

6. Press the OK button.

https://uem.blackberrydevsummit.com:10443/index.jsp

of 15

7. The activation processing carousel will scroll through its stages.

8. Create a password that will be required to start the application.

The application user interface will then be displayed. Note that activation isn't necessary when

you reinstall the application as an upgrade, without uninstalling.

Appendix B – MyExpenses Service Definition

MyExpenses is a private Service which the Services sample code is configured to implement

Service Provider. Below is the Service Definition for this Service.

{

"title": "My Expense",

"service-id": "com.blackberrydevsummit.2017.services.my-expense",

"version": "1.0.0.0",

"description": "This services offers services of providing the expense limit to a requesting

application and allow an application to set a expense item",

"methods": {

"getExpenseLimit": {

"description": "The consumer should specify itself to be brought to the foreground when sending

a request with this method. The service provider should respond returning the expense limit

(Integer) as parameter",

"params": {

"type": "null"

},

"result-value": {

"type": "integer",

"description": "Integer value of expense limit"

}

of 15

},

"setExpenseItem": {

"description": "",

"params": {

"type": "object",

"properties": {

"item": {

"description": "Name of expense item",

"type": "string"

},

"amount": {

"description": "Amount of the expense item",

"type": "integer

}

}

}

}

}

}

blackberry developer summit rapid development ......page 4 of 15 1. workbook scope this workbook...

Documents