BlackBerry UEM Integration SDKDevelopment Guide

12.12

2020-01-08Z

 |  | 2

Contents

What is the BlackBerry UEM Integration SDK?.................................................. 5Architecture: BlackBerry UEM plug-ins................................................................................................................. 5Benefits of the BlackBerry UEM Integration SDK................................................................................................ 7

What is a BlackBerry UEM plug-in?...................................................................9Creating and deploying a BlackBerry UEM plug-in.............................................................................................. 9How BlackBerry UEM plug-in components interact with the BlackBerry UEM platform................................. 10BlackBerry UEM plug-in project structure.......................................................................................................... 12Integrating UI elements for a plug-in..................................................................................................................13UEM plug-in compatibility and versioning..........................................................................................................14

Using the BlackBerry UEM Integration APIs.................................................... 15Prerequisites for BlackBerry UEM plug-in development................................................................................... 15Entity model and main service interfaces and packages................................................................................. 15

Setting up your BlackBerry UEM plug-in development environment.................20System requirements for BlackBerry UEM plug-in development......................................................................20Configuring your development environment......................................................................................................22

Install BlackBerry UEM in your development environment....................................................................22Change the UI configuration file for development.................................................................................23Install the BlackBerry UEM Integration SDK........................................................................................... 24Install the UEM Integration plug-in for Eclipse.......................................................................................24Create an Eclipse workspace and integrate it with BlackBerry UEM.................................................... 24Start the BlackBerry UEM Core and management console services from Eclipse.............................. 26Verify that you can compile a plug-in project........................................................................................ 27Converting CSS to GSS for GWT 2.8.0 and later....................................................................................27

Joining BlackBerry UEM plug-in development................................................................................................... 27UEM plug-in source control......................................................................................................................28

Configure automated builds for a BlackBerry UEM plug-in.............................................................................. 28

Upgrading your development environment...................................................... 30Updating the platform version dependency for your UEM plug-in................................................................... 30

Sample BlackBerry UEM plug-in......................................................................31

Using widgets to customize the UI elements of a plug-in................................ 33Common form widgets........................................................................................................................................33Factories................................................................................................................................................................36Table...................................................................................................................................................................... 37Progress indicator................................................................................................................................................ 37

 |  | iii

Button band.......................................................................................................................................................... 38Dialogs...................................................................................................................................................................39

Enabling a BlackBerry UEM plug-in to integrate with an external system......... 40Establish the URL pattern for the REST route................................................................................................... 40Access BlackBerry UEM logging.........................................................................................................................41Validate using a query string.............................................................................................................................. 41Validate using a URI value.................................................................................................................................. 42Retrieve information from the authorization header......................................................................................... 43

Best practices and troubleshooting.................................................................44

Deploy a plug-in to a production BlackBerry UEM domain............................... 46Creating an installer for a BlackBerry UEM plug-in........................................................................................... 46Removing a plug-in from a BlackBerry UEM instance...................................................................................... 49

Legal notice.................................................................................................... 50

 |  | iv

What is the BlackBerry UEM Integration SDK?The BlackBerry UEM Integration SDK allows developers to create plug-ins that extend the functionality ofBlackBerry UEM version 12.7 or later. Using the UEM Integration SDK (which includes the UEM Integration plug-infor Eclipse) and the UEM Integration APIs, you can create and deploy BlackBerry UEM plug-ins that allow for thetight integration of new features or services with an existing BlackBerry UEM installation.

The advantages offered by a BlackBerry UEM plug-in:

Feature Description

Integrate new services andfeatures

You can integrate custom services with BlackBerry UEM to extendservice-based functionality to device users. For example, the BlackBerryWorkspaces plug-in allows an administrator to integrate Workspacesfile-sharing services with an existing BlackBerry UEM domain.Administrators can use the management console to assign theWorkspaces service to users and groups and to configure and managevarious aspects of the service, including distribution lists, workspaces,and document settings.

Add UI components to themanagement console

You can expose UI for new features or services in the managementconsole, including configuration settings, enable and disable options,administrator permissions, and user assignment mechanisms. Featuresor services can also be implemented as "back-end" changes with no UIimpact.

Leverage existing UEM features The new features or services that you integrate with BlackBerry UEM canleverage the existing capabilities of the platform, including role-basedauthorization, high availability, group and user management, logging,monitoring, and licensing.

Leverage existing systems You can integrate BlackBerry UEM plug-ins with and use data fromexisting systems, including an organization's company directory and keycomponents of the BlackBerry Infrastructure (for example, the licensinginfrastructure and provisioning servers).

Add custom APIs You can add new APIs to BlackBerry UEM that can be exposed on anexisting BlackBerry UEM port. For example, you can implement APIsthat allow a third-party product to obtain information about the status ofactivated devices.

You can request the free UEM Integration SDK package from developers.blackberry.com. The SDK package givesyou everything you need to get started, including the UEM Integration plug-in for Eclipse, several code samples,and API references.

Architecture: BlackBerry UEM plug-ins 

 | What is the BlackBerry UEM Integration SDK? | 5

 

The diagram above includes only the BlackBerry UEM components that are directly related to the BlackBerryUEM Integration SDK. For complete architecture diagrams that illustrate all BlackBerry UEM components, seethe BlackBerry UEM Architecture content.

Component Description

Management console The management console is a web-based console that administrators use toconfigure an organization’s BlackBerry UEM domain and perform daily tasks,including managing users, devices, policies, profiles, and apps.

The management console consists of two parts:

• UI client: A client application that is based on the Google Web Toolkit. Codeis written in Java and translated to JavaScript by GWT. The UI client runsthe JavaScript code in the browser to create and manipulate the appearanceof the management console.

• UI server: A web server that hosts the necessary static resources and providesdata support. The UI server runs in a Java VM and is compatible with Java.

BlackBerry UEM Core The BlackBerry UEM Core is the central component of the BlackBerryUEM architecture. It consists of several subcomponents that are responsible for:

• Logging, monitoring, reporting, and management functions• Authentication and authorization services for the BlackBerry UEM Core local

directory and company directories• Scheduling and sending commands, IT policies, and profiles to devices

The BlackBerry UEM Core is written in Java and is installed with theprimary BlackBerry UEM components.

 | What is the BlackBerry UEM Integration SDK? | 6

Component Description

BlackBerry UEM plug-in A BlackBerry UEM plug-in is a code delivery mechanism that adds new servicesor functionality to BlackBerry UEM. Developers create BlackBerry UEM plug-insusing the BlackBerry UEM Integration SDK (which includes the UEM Integrationplug-in for Eclipse). The BlackBerry UEM Integration SDK provides a developmentenvironment and templates that can be used to integrate code with themanagement console and BlackBerry UEM Core.

Developers manage BlackBerry UEM plug-in code in its own repository and buildthe code using the UEM Integration APIs. When BlackBerry UEM plug-ins aredeployed to BlackBerry UEM, any new UI elements developed in the plug-in areadded to the management console, and supporting functionality required bythe BlackBerry UEM components is added to the BlackBerry UEM Core.

UEM Integration APIs The UEM Integration APIs are:

• The BlackBerry UEM UI APIs: provide the capability to add new screens, menuitems, configuration settings, status fields, and other UI elements to themanagement console to support plug-in features or services. There are APIsfor the UI client and the UI server, with many components shared by both.

• The BlackBerry UEM Core API: provides the capability to integrate plug-inlogic using various APIs for user management, group management, profilemanagement, and so on.

The relationship between the UI and the BlackBerry UEM Core can be thoughtof as a client-middleware-server relationship, where the UI client runs andpresents the management console in a browser, the UI server is the middlewarefor the management console, and the BlackBerry UEM Core is the main servercomponent that allows BlackBerry UEM to carry out management activities thatare initiated in the management console.

Spring Spring is a Java application framework that is used to integrate a BlackBerryUEM plug-in with the BlackBerry UEM Core. When a plug-in is ready to deploy,a developer generates a plug-in package and adds the files to the BlackBerryUEM file structure. The ApplicationContext interface is used to load and executethe plug-in code with the BlackBerry UEM Core.

For more information about Spring, visit the Spring website.

Benefits of the BlackBerry UEM Integration SDKAdd new features to BlackBerry UEM outside of regular software releases

The BlackBerry UEM Integration SDK allows you to add new services and management features to BlackBerryUEM at any time. BlackBerry offers several plug-in products, such as the BlackBerry Workspaces plug-in forBlackBerry UEM and the BlackBerry Enterprise Identity plug-in for BlackBerry UEM, or you can develop your ownplug-ins.

User-friendly, extensible APIs

The UEM Integration APIs are designed to be user-friendly and are based on consistent design principles. Anyplug-in that follows the rules and structure of the APIs can integrate with BlackBerry UEM to add features andservices. The APIs are designed to maintain compatibility with future versions of BlackBerry UEM.

 | What is the BlackBerry UEM Integration SDK? | 7

Seamless integration with the BlackBerry UEM management console

When you use the UEM Integration SDK to add new features and services to BlackBerry UEM, you are also giventhe tools to add new properties, configuration settings, user-assignment mechanisms, and other controls to themanagement console. The UI components that you add to the product are easy to access and use because theconsole has been designed to implement the UI features of any number of plug-ins.

Easy to implement

The UEM Integration SDK provides the development environment and templates that you need to create and test aplug-in for BlackBerry UEM. When your plug-in is ready to deploy to a production environment, you simply compileand generate a .zip file, deploy the contents to the BlackBerry UEM file structure, and run a validation process.When BlackBerry UEM starts, it runs the plug-in files and integrates the code with the BlackBerry UEM Core andmanagement console.

 | What is the BlackBerry UEM Integration SDK? | 8

What is a BlackBerry UEM plug-in?A BlackBerry UEM plug-in is a code delivery mechanism that adds new features or user-assignable servicesto BlackBerry UEM. Plug-in integration is made possible by the BlackBerry UEM platform, which handles coreoperations such as user management, authentication, mapping services to users and devices, and providing theunderlying logic for the management console and BlackBerry UEM Self-Service.

A BlackBerry UEM plug-in integrates with the core code base of BlackBerry UEM. As a result, a plug-in can interactwith the system, listen for and react to events, add configuration and management options to the managementconsole, and add custom APIs to support new services or features. The extensible design of the BlackBerry UEMplatform supports any number of plug-ins.

Plug-in design is flexible. You can create a plug-in that exposes UI options for configuration, permission andprofile management, and user assignment, or you can implement “back-end” functionality with no UI impact atall. A plug-in can exist independent of other BlackBerry UEM features (for example, a service that is extendedto devices and managed from a dedicated screen in the management console). A plug-in can also introducenew functionality that is reflected throughout the user experience (for example, a new profile type that can beassigned, removed, or edited just like any other BlackBerry UEM profile).

Creating and deploying a BlackBerry UEM plug-inYou will use the following process to create a BlackBerry UEM plug-in and deploy it to a production domain. Thisguide provides you with the instructions you need for each step of the process.

1. Request the free BlackBerry UEM Integration SDK package from developers.blackberry.com.2. On a dedicated development computer, install a BlackBerry UEM instance for testing, the Eclipse IDE with

required plug-ins, and the UEM Integration plug-in for Eclipse.

• Run the integration process to connect the development environment to the local BlackBerry UEMinstallation. This gives your Eclipse environment access to the necessary development resources anddependencies for the BlackBerry UEM components, and provides resources that can be used to build theBlackBerry UEM plug-in code using the UEM Integration APIs.

• The integration process creates a folder for the plug-in in the BlackBerry UEM file structure. The UEMIntegration plug-in for Eclipse packages and deploys code to this file path, and BlackBerry UEM executes it.

• The UEM Integration plug-in for Eclipse creates projects with sample build.gradle files that are used to buildand package the plug-in. You can modify build.gradle files to fit your development processes, for example,to publish build products to an artifact repository.

• For complete instructions, see Setting up your BlackBerry UEM plug-in development environment.3. Develop a BlackBerry UEM plug-in and test it with a local BlackBerry UEM installation. The following sections

provide useful references, guidance, examples, and best practices:

• Using the BlackBerry UEM Integration APIs• Sample BlackBerry UEM plug-in• Using widgets to customize the UI elements of a plug-in• Enabling a BlackBerry UEM plug-in to integrate with an external system• Best practices and troubleshooting

4. When the plug-in is ready to deploy to your production environment, you compile and generate a plug-inpackage (.zip file) from the command line. The package contains the component-specific extension parts (.jarand other files) with the code to run in the UI and BlackBerry UEM Core components. A plug-in can integratewith either or both components, depending on the plug-in design.

• For complete instructions, see Deploy a plug-in to a production BlackBerry UEM domain.

 | What is a BlackBerry UEM plug-in? | 9

5. Transfer the plug-in package to each computer that hosts a production BlackBerry UEM instance. From thecommand line, you run a deployment tool that validates the plug-in, integrates it with the BlackBerry UEMcomponents, and restarts the components.

• The plug-in deployment tool also gives you the ability to create a simple executable installer for the plug-inwith an optional UI. You may want to create an executable installer if you want others to deploy the plug-inon one or more BlackBerry UEM instances.

• For complete instructions, see Deploy a plug-in to a production BlackBerry UEM domain.

How BlackBerry UEM plug-in components interact with the BlackBerryUEM platformThe following diagram shows a basic set of BlackBerry UEM plug-in components and how they interact withthe BlackBerry UEM platform:

 

 | What is a BlackBerry UEM plug-in? | 10

BlackBerry UEM platform components

• BlackBerry UEM UI client: Runs and presents the management console in a browser• BlackBerry UEM UI server: Server component that hosts the necessary static resources and provides data

support for the management console• BlackBerry UEM Core: Central component of the BlackBerry UEM architecture

Plug-in components

• ui.client: Code that is executed in the browser that is used to access the BlackBerry UEM management console• ui.server: Code that is executed on the server component of the management console• core.server: Code that is executed in the BlackBerry UEM Core• common.common, ui.common, common.server: Enable code sharing between the plug-in components

 | What is a BlackBerry UEM plug-in? | 11

BlackBerry UEM plug-in project structureYou develop a BlackBerry UEM plug-in using multiple projects that are organized into a hierarchy:

 

Projects Description

• core.server• ui.server• ui.client

These are the main projects that represent the three environments thatthe BlackBerry UEM plug-in projects will run in: the BlackBerry UEM Core,the UI server, and the UI client (the code running in the browser thatdisplays the management console).

 | What is a BlackBerry UEM plug-in? | 12

Projects Description

• common.common• common.server• ui.common

These projects are intended for code that is shared by the three mainprojects (core.server, ui.server, and ui.client).

• ui.client-generated• ui.server-generated

When the ui.server project is compiled, helper code is automaticallygenerated in the ui.client-generated and ui.server-generated projects.These projects allow the UI client code to make calls to methods in theUI server based on remote execution (RX) annotations.

Note: If you remove an RX method annotation, code that was generatedpreviously for that annotation will remain in the ui.server project. Youmust manually remove all generated code from the ui.server project,then regenerate the code by clean-building the ui.server project. Whenthis is complete, refresh all projects in Eclipse.

• ui.translations The ui.translations project contains a directory tree with *.propertiesfiles. These files contain runtime translation resources that followstandard Java practices. The translation resources are available for useby the UI code.

The first level of directories in ui.translations defines separatetranslation bundles. At least one must exist, and each can haveany regular directory name. This directory structure containsthe Java package directory structure. A default properties file for thecom.sample.Code should be placed in ui.translations/<bundleName>/com/sample/Code.properties. Every language has a correspondingversion, for example, ui.translations/<bundleName>/com/sample/Code_es.properties for Spanish, ui.translations/<bundleName>/com/sample/Code_de.properties for German, and so on for each languagethat BlackBerry UEM supports.

• ui.web The ui.web project contains the directory src/war/ext/snapin-id/. Thisdirectory can be used for static web resources that are not included inthe standard GWT code packaging. The files in this directory can beaccessed from the following URL: http(s)://host:port/product-mode/ext/snapin-id/....

• ui.ide-dev The ui.ide-dev project is an Eclipse helper project that is used bythe SDK Eclipse tooling to configure certain classpaths and launchconfigurations. Do not change this project during plug-in development.

Integrating UI elements for a plug-inThe BlackBerry UEM UI APIs give you the ability to add UI for a plug-in to the management console. Thiscan include options to enable or disable a feature or service, configuration settings, user assignment andmanagement mechanisms, and status information.

When BlackBerry UEM executes plug-in code, it integrates the plug-in UI elements in the overall process ofdisplaying the console in a browser. The management console service consists of a UI server (web server) anda UI client. Java source code is transpiled to JavaScript by the Google Web Tookit, and the UI server provides

 | What is a BlackBerry UEM plug-in? | 13

the JavaScript code and static resources to the UI client code running inside the browser. The UI client runs theJavaScript code in the browser to create and manipulate the appearance of the console.

This process allows for code sharing and object communication between the UI server and the UI client, resultingin optimized versions of JavaScript for each browser platform. The UI client can link event listeners to react todifferent types of events, including user activity, time, system events, and messages pushed from the UI server.

For more information about the widgets that are available to add and customize UI components for a UEM plug-in,see Using widgets to customize the UI elements of a plug-in.

UEM plug-in compatibility and versioningPlug-in development is supported for BlackBerry UEM version 12.7 or later. Each release of BlackBerry UEM usesa specific version of the underlying UEM Integration platform, so you must use the version of the BlackBerry UEMIntegration SDK that matches your organization's version of BlackBerry UEM. The APIs are designed to maintaincompatibility with later versions of the platform.

You can use the following files, both found at the project root file path (for example, C:\example_plugin), to definethe name and version information for your UEM plug-in:

• snapin-manifest.properties: Generates version and name information for Eclipse builds. For more informationabout updating this file after upgrading, see Updating the platform version dependency for your UEM plug-in.

• version.properties: Generates the version and name information for command line builds.

In both files, the MARKET_NAME property is used to specify the plug-name, and the DEV_VERSION property (in theformat <major_version>.<minor_verison>.<patch_version>) is used to specify the version number.

 | What is a BlackBerry UEM plug-in? | 14

Using the BlackBerry UEM Integration APIsThe resources that you need to develop a BlackBerry UEM plug-in are contained in the UEM Integration APIreferences:

• The BlackBerry UEM Core API reference describes how to use the packages, interfaces, and classes requiredto add plug-in functionality to the BlackBerry UEM Core.

• The BlackBerry UEM UI API references (UI client and UI server) describe how to use the packages, interfaces,and classes required to add plug-in functionality to the UI client and the UI server.

These API references are included in the BlackBerry UEM Integration SDK. Visit developers.blackberry.com torequest the free SDK package.

Prerequisites for BlackBerry UEM plug-in developmentTo develop a BlackBerry UEM plug-in, you must be familiar with the following:

• The Java programming language• Eclipse IDE• The Google Web Toolkit, including the following resources:

• Getting Started• Developer's Guide• Server Communication (especially Serializable Types)• Reference Guide (especially JRE Emulation and Widget Gallery)

Entity model and main service interfaces and packagesEntity model of the UEM Integration APIs

 

 | Using the BlackBerry UEM Integration APIs | 15

 

BlackBerry UEM Core API

The main service interfaces of the BlackBerry UEM Core API:

Interface Description

Configuration service(IConfigurationService)

The configuration service allows a plug-in to add custom configurationdefinitions that can be used by plug-in features and services.

Device service (IDeviceService) The device service allows a plug-in to retrieve device informationfrom BlackBerry UEM.

Event service (IEventService) The event service allows a plug-in to register, listen for, and processevents, as well as create new events.

Execution service(IExecutionService)

The execution service allows a plug-in to execute services and retrytasks.

 | Using the BlackBerry UEM Integration APIs | 16

Interface Description

Feature service (IFeatureService) The feature service manages reading platform-defined features andfeature definitions specific to a plug-in.

Group service (IGroupService) The group service allows a plug-in to interact with the user groupsavailable in BlackBerry UEM.

HTTP client service(IHttpClientUtil)

The HTTP client service allows a plug-in to make HTTP requests toexternal resources through the BlackBerry Infrastructure.

Key store service(IKeyStoreService)

The key store service gives a plug-in access to the certificates andprivate keys stored in the BlackBerry UEM Core key store, and supportsthe creation and storage of certificates and key pairs for the plug-in.

Licensing service(ILicensingService)

The licensing service allows a plug-in to retrieve licensing informationand modify licensing entitlements.

Permission service(IPermissionService)

The permission service manages reading platform-defined permissionsand permission definitions that are specific to a plug-in.

Profile service (IProfileService) The profile service allows a plug-in to add new profiles and profilesettings to BlackBerry UEM.

User device service(IUserDeviceService)

The user device service allows a plug-in to retrieve device data for aspecific user.

User service (IUserService) The user service allows a plug-in to interact with existing BlackBerryUEM users, for example, to associate a service with a user or to removea service from a user.

User setting service(IUserSettingService)

The user setting service allows a plug-in to retrieve and configure usersettings.

BlackBerry UEM UI APIs (UI server and UI client)

The main packages of the BlackBerry UEM UI APIs:

Package Description

com.blackberry.platform.common.api.entity The entities that are common in all components ofthe BlackBerry UEM Integration platform.

Note: The implementation of this package forthe BlackBerry UEM Core is not available in thisrelease, but is targeted for an upcoming release.

 | Using the BlackBerry UEM Integration APIs | 17

Package Description

com.blackberry.platform.common.api.log The logging capabilities that are common in allcomponents of the BlackBerry UEM Integrationplatform.

Note: The implementation of this package forthe BlackBerry UEM Core is not available in thisrelease, but is targeted for an upcoming release.

com.blackberry.platform.ui.common.api.auth The classes that are related to user authentication forthe BlackBerry UEM UI APIs (UI client and UI server).

com.blackberry.platform.ui.common.api.provider The provider framework and related classes forthe BlackBerry UEM UI APIs (UI client and UI server).

com.blackberry.platform.ui.client.api.nav The navigation API for the UI client.

com.blackberry.platform.ui.client.api.widgets The UI widgets for the UI client.

com.blackberry.platform.ui.rx.client.api The Remote Execution (RX) classes for the UI client.

com.blackberry.platform.ui.rx.common.api The RX classes common to the UI client and the UIserver.

The main entry points for the BlackBerry UEM UI APIs:

Entry point Description

com.blackberry.platform.ui.server.api.UIServerModule This is an abstract base class that a plug-in mustsubclass in the UI server code to add elements tothe UI. The name of the subclass must follow thisconvention: <plug-in-id>.ui.server.ServerEntryPoint.

com.blackberry.platform.ui.server.api.

UIServerSessionAPI

This is the interface that defines the API providedby the platform to the plug-in code in the UIserver. Implement the connect() method of theUIServerModule class to provide the instance of theinterface to a plug-in. Each plug-in receives a separateinstance of this object that cannot be shared withother plug-ins.

com.blackberry.platform.ui.client.api.

 AbstractClientSnapin

This is the equivalent of UIServerModule for the UIclient; an abstract base class that a plug-in mustsubclass in the UI client code to add elements to theUI.

 | Using the BlackBerry UEM Integration APIs | 18

Entry point Description

com.blackberry.platform.ui.client.api.UIClientAPI This is the interface that defines the API providedby the platform to the plug-in code in the UIclient. Implement the api() method of theAbstractClientSnapin class to provide the instanceof the interface to a plug-in. Each plug-in receives aseparate instance of this object that cannot be sharedwith other plug-ins.

The following diagram demonstrates the relationship between key objects in the UEM Integration Framework (thewhite boxes are platform classes; the blue boxes are plug-in classes):

 

 

To complete a successful login, the platform makes a call to the connect() method of the ServerEntryPoint. Theplug-in exposes its functionality to the authenticated user by returning an instance of the class that extendsModuleSessionExtensionConnection. This object will be stored along with other such objects in the internal usersession object, and can be treated as a plug-in specific session object; it is a user session's connection to theplug-in. All subsequent functionality that is related to the user session is routed to this object.

The first such call obtains an initialization package for the plug-in's client code. This is accomplished by overridingthe getClientModulePostLoginInitPack(...) method in the connection object. It should return an implementationthat creates an instance of a subclass of ClientModulePostLoginInitPack. This class must be serializable to theclient, so it must be in the ui.common project, and it must meet all criteria for RX/GWT serialization. Otherwise,the class may contain whatever data and logic the plug-in requires.

 | Using the BlackBerry UEM Integration APIs | 19

Setting up your BlackBerry UEM plug-in developmentenvironmentFollow the instructions in this section to set up your development environment to create a BlackBerry UEM plug-in.

System requirements for BlackBerry UEM plug-in developmentVerify that your development computer meets the following software requirements:

Item Requirement

Java Development Kit (JDK) A 64-bit Java SE Development Kit that matches the version of the JRE thatwill be installed by BlackBerry UEM, or a later version. To verify the versionthat will be installed by BlackBerry UEM, see the BlackBerry UEM Compatibilitymatrix.

Note: It is recommended to install the JDK on your development machinebefore you install BlackBerry UEM. If you want install the JDK after youinstall BlackBerry UEM, install it after you log in to the management consolefor the first time and provide your SRP ID and authentication key. The JDKinstaller will prompt you for a different install location for the JRE folderbecause BlackBerry UEM will have already installed a JRE folder.

After you install the JDK, add the following to Enviroment Variables > Systemvariables:

• JAVA_HOME: <file path to the jdk_version folder> (for example, C:\ProgramFiles\Java\jdk1.8.0_112)

• JDK_HOME: %JAVA_HOME%• JRE_HOME: %JAVA_HOME%\jre• CLASSPATH: .;%JAVA_HOME%\lib;%JAVA_HOME%\jre\lib• PATH: <your_unique_entries>;%JAVA_HOME%\bin

For PATH, verify that your unique entries do not have any references to adifferent Java installation folder.

BlackBerry UEM Plug-in development is supported for BlackBerry UEM version 12.7 or later.Plug-in development is not supported for BlackBerry UEM Cloud.

Each release of BlackBerry UEM includes a specific version ofthe UEM Integration platform. You must use the version of the BlackBerryUEM Integration SDK that matches your organization's version of BlackBerryUEM. Request the required version of the BlackBerry UEM IntegrationSDK from developers.blackberry.com.

The UEM Integration APIs are designed to maintain compatibility with laterversions of the platform.

You must install BlackBerry UEM on your development computer.This UEM instance should be reserved for testing your plug-in integration.See Install BlackBerry UEM in your development environment.

 | Setting up your BlackBerry UEM plug-in development environment | 20

Item Requirement

Uprading UEM and the SDKto a new version

If you are upgrading UEM and the BlackBerry UEM Integration SDK to a newversion, follow the instructions in Upgrading your development environment.

Operating system The OS of your development computer must meet the OS requirementsof the BlackBerry UEM version that you want to develop a plug-in for. Toreview the OS requirements for BlackBerry UEM, see the BlackBerry UEMCompatibility matrix.

The UEM software must be installed on a computer with Windows Server. Seethe compatibility matrix for supported versions.

RAM 16 GB minimum

Solid-state drive (SSD) An SSD for Eclipse development (recommended)

Java Cryptography Extension(JCE) Unlimited StrengthJurisdiction Policy Files

Install the Java Cryptography Extension (JCE) Unlimited Strength JurisdictionPolicy Files. The version of the files must match the JDK.

Extract the contents of the .zip file (two .jar files) and replace the existingversions of those files in <drive>:\Program Files\Java\jdk<version>\jre\lib\security.

Note: You must re-apply the JCE files each time you upgrade the JRE andJDK.

Eclipse IDE • 64-bit Eclipse IDE for Java Developers with a minimum of 5 GB of memory.• The supported versions of Eclipse IDE depend on the Eclipse IDE plug-ins

that you are using (see Eclipse IDE plug-ins row below):

• Google Web Toolkit (GWT) Eclipse Plugin 3.0.0 or later(recommended): Eclipse Luna SR2, Eclipse Oxygen 4.7, Eclipse Photon4.8, or Eclipse 4.9, 4.10, 4.11

• Google Plugin for Eclipse 4.4/4.5/4.6: Eclipse Luna SR2.• Configure Eclipse to start with the JVM of the JDK, instead of the JRE. For

instructions, see Overview: eclipse.ini. After you make this change, you canverify it in Eclipse under Window > Preferences > Java > Installed JREs.

• In a text editor, make the following changes to the eclipse.ini file:

• Verify that -Dosgi.requiredJavaVersion=<version> matches the versionof the JRE used by BlackBerry UEM.

• Change -Xms<value>m to at least -Xms2048m• Change -Xmx<value>m to at least -Xmx5120m• Change -Xss<value>M to -Xss4M

 | Setting up your BlackBerry UEM plug-in development environment | 21

Item Requirement

Eclipse IDE plug-ins Eclipse IDE (run as an administrator) with the following plug-ins:

• GWT Eclipse Plugin 3.0.0 or later is recommended for the latestversion of the SDK. Use the new version of the UEM Integrationplug-in for Eclipse that is available in the SDK package(uem.eclipse.plugin.gwt-<version>-external.zip). To download and installthe GWT Eclipse Plugin, visit http://gwt-plugins.github.io/documentation/gwt-eclipse-plugin/Download.html.

• If you are upgrading your development environment from a previousversion of the SDK that used the Google Plugin for Eclipse and you wantto start using the GWT Eclipse Plugin (recommended), see Upgradingyour development environment.

• For backwards compatibility, the deprecated Google Pluginfor Eclipse 4.4/4.5/4.6 and GWT 2.7.0 and later are supported if you usethe older version of the UEM Integration plug-in for Eclipse that is includedin the SDK package (uem.eclipse.plugin-<version>-external.zip). Note thatthis legacy version of the plug-in will not include new features or fixes. Ifyou are using GWT 2.8.0 or later, see Converting CSS to GSS for GWT 2.8.0and later.

• FindBugs Eclipse plug-in 3.0.1; installation instructions are availablefrom http://findbugs.cs.umd.edu/eclipse

UEM Integration plug-infor Eclipse

See Install the UEM Integration plug-in for Eclipse.

Two versions of the UEM Integration plug-in for Eclipse are includedin the SDK package. One version supports the GWT Eclipse Plugin(uem.eclipse.plugin.gwt-<version>-external.zip), and is recommended goingforward to benefit from the new features and fixes in each release of the SDK.

The legacy version of the plug-in (uem.eclipse.plugin-<version>-external.zip) is included for backwards compatibility with the Google Pluginfor Eclipse 4.4/4.5/4.6, but will not include new features or fixes.

Configuring your development environment

Install BlackBerry UEM in your development environmentYou must install BlackBerry UEM version 12.7 or later on your development computer to ensure that the systemis properly configured, to allow the BlackBerry UEM plug-in to access the UEM services and database, and toallow you to test the plug-in integration. It is a best practice to install BlackBerry UEM before you set up yourdevelopment environment in Eclipse, to ensure that your development computer has the right version of the JREand other requirements.

This BlackBerry UEM instance should be reserved for development testing only, with its own SRP ID andauthentication key. After you complete and test your plug-in in the development environment, you can packageand deploy it to a production BlackBerry UEM domain.

1. Visit developers.blackberry.com and do one of the following:

 | Setting up your BlackBerry UEM plug-in development environment | 22

• Register a new BlackBerry Online Account with new organization information that you will use specificallyfor development purposes. You get an option for 25 trial licenses that are valid for 180 days (after 180 daysyou can extend the trial period or request new licenses).

• Log in with an existing BlackBerry Online Account that is used to manage your organization’sproduction UEM licenses. Note: If you choose this option, the licenses you use for your developmentinstance are shared from the same pool of licenses for your production instances.

2. In the top-right menu, select My Organization.3. Navigate to the menu listing your server instances and select the option to add a server.4. Choose Unified Endpoint Manager (UEM) and the on-premises deployment option. If you created a new

account with a new organization, in the Licenses section, choose Developers.5. Specify any other required information and add the server.

You receive an SRP ID and authentication key that you will use to install BlackBerry UEM on your developmentcomputer.

• If you created a new account, you receive 25 trial user licenses that are valid for 180 days. If you installmore than one UEM instance for development, the trial licenses are shared across all instances.

• If you are using an account that is also used to manage licenses for production UEM instances, whenyou install BlackBerry UEM, choose to install a new BlackBerry UEM database and use the provided SRPID and authentication key; this creates a new UEM domain for development that is separate from theproduction UEM domain.

6. Visit BlackBerry UEM and BES Downloads to download BlackBerry UEM.7. Install and configure BlackBerry UEM on your development computer. See the BlackBerry UEM

documentation and follow the instructions in the Installation and Upgrade Guide and Configuration Guide.Complete the post-installation configuration process before you make any other configuration changes.

After you finish:

• By default, the logging settings for BlackBerry UEM are automatically configured by database settings. Fordevelopment purposes, it is recommended to control the logging locally. In <drive>:\Program Files\BlackBerry\UEM\ui, open the UI-config XML file in a text editor. In the <fusion-config> section, add the following: <loglocal=”yes”/>

• You can access your account from developers.blackberry.com to manage your licenses (for example, toextend the trial period or to request new licenses).

• Change the UI configuration file for development.

Change the UI configuration file for developmentMake the following changes to the UI configuration file to avoid UI authentication issues during the developmentand testing process.

1. Run a text editor as an administrator and open the UI-config XML file found in <drive>:\Program Files\BlackBerry\UEM\ui.

2. Locate the following lines:

bind protocol="${gcs:ui.protocol.ssp}" port="${gcs:ui.port.ssp}" bind protocol="${gcs:ui.protocol.admin}" port="${gcs.ui.port.admin}"

3. Replace "${gcs:ui.protocol.ssp}" with "http", and "${gcs:ui.protocol.admin}" with "http". After the changes,these lines should be:

bind protocol="http" port="${gcs:ui.port.ssp}"

 | Setting up your BlackBerry UEM plug-in development environment | 23

bind protocol="http" port="${gcs:ui.port.admin}"

4. Save and close the file.

After you make these changes, when you open the management console in a browser you mustadd :<console_port> after the host value in the URL (for example, http://example.domain:443/admin/). Thedefault management console port is 443. If 443 is not available, the setup application tries to use 8008. Formore information about default BlackBerry UEM listening ports, see "BlackBerry UEM listening ports" in the UEMInstallation and Upgrade Guide.

After you finish: Install the BlackBerry UEM Integration SDK.

Install the BlackBerry UEM Integration SDKBefore you begin: Change the UI configuration file for development.

 Extract the contents of the BlackBerry UEM Integration SDK .zip file to <drive>:\Program Files\BlackBerry\UEM.

After you finish: Install the UEM Integration plug-in for Eclipse.

Install the UEM Integration plug-in for EclipseFollow these steps to install the UEM Integration plug-in for Eclipse or to upgrade to the latest available version.

Before you begin: Install the BlackBerry UEM Integration SDK.

1. Run Eclipse IDE as an administrator.2. Click Help > Install New Software.3. Click Add.4. In the Name field, type UEM Plug-in Tools.5. Click Archive. Navigate to <drive>\Program Files\BlackBerry\UEM\sdk and select one of the following:

• To use the SDK with the GWT Eclipse Plugin 3.0.0 or later (recommended),select uem.eclipse.plugin.gwt-<version>-external.zip.

• To use the SDK with Google Plugin for Eclipse 4.4/4.5/4.6 and GWT 2.7.0 or later,select uem.eclipse.plugin-<version>-external.zip.

6. Click OK.7. Select the BlackBerry UEM Tools check box. Click Next.

After the installation completes, you will see a new menu for UEM Integration plug-in tools.

After you finish: Create an Eclipse workspace and integrate it with BlackBerry UEM.

Create an Eclipse workspace and integrate it with BlackBerry UEMYou must integrate your development environment with a local BlackBerry UEM installation that is reserved fortesting your BlackBerry UEM plug-in. This gives your Eclipse environment access to the necessary developmentresources and dependencies for the BlackBerry UEM components, including the BlackBerry UEM Core and themanagement console, and provides the necessary mechanisms to integrate a BlackBerry UEM plug-in.

The integration process creates a folder for the plug-in in the BlackBerry UEM installation files, in <drive>:\Program Files\BlackBerry\UEM\ext. The UEM Integration plug-in for Eclipse packages and deploys code to thisfile path so that you can test the plug-in with your local BlackBerry UEM installation.

Before you begin: In the Windows Services, set the start-up type for the BlackBerry UEM Core and managementconsole services to Manual. Disable automatic restart for both services. Stop the BlackBerry UEM Core andmanagement console services. After you complete the integration task below, you will configure yourdevelopment environment to start and run the BlackBerry UEM Core and management console.

 | Setting up your BlackBerry UEM plug-in development environment | 24

1. Run Eclipse as an administrator and open a workspace.2. On the menu, click UEM Plug-in Tools > UEM Integration Setup.3. For the UEM Root Directory field, click Browse and navigate to the root folder for the BlackBerry

UEM installation (for example, C:\Program Files\BlackBerry\UEM).4. For the Plug-in Project Root field, specify a root folder (for example, C:\example_plugin).5. Select the Create Basic Plug-in Projects check box.6. If you want to enable a background process to scan for discouraged uses of the UEM Integration APIs, verify

that the Enable Private API validator check box is selected.7. If you upgraded UEM to a new version and you are running the integration process for the first time after the

upgrade, select the Regenerate launchers check box. This will regenerate the utilities that are used to launchthe BlackBerry UEM Core and management console from Eclipse.

8. Click OK.9. The BlackBerry UEM Plug-in window lists any BlackBerry UEM services that are running that may interfere with

the integration process. Select all of the services and click OK.10.In the BlackBerry UEM Integration SDK Development Environment window, specify the ID, name, and version

for the BlackBerry UEM plug-in that you plan to develop.The plug-in ID must:

• Use the format <company>.<product>.<plug-in>, where <company> is the fully qualifiedinternet address of the company in reverse order (for example, com.company), <product> is thename of the product that the plug-in is built for (only required if there is more code to the productthan just the BlackBerry UEM plug-in), and <plug-in> uniquely identifies the plug-in code. Forexample: com.blackberry.sampleproduct.monitoringplugin

• Be globally unique and human-readable• Meet all criteria when treated as case-sensitive or case-insensitive, must be consistent wherever used (it is

recommended to use only lower-case characters)• Use ASCII characters with the following conventions:

• each segment must begin with a letter (a-z) and the remaining characters in a segment must be a letter(a-z) or a number (0-9)

• segments must be separated by a single period (.)11.Click OK.

When the process completes, the workspace restarts to apply the configuration changes. You will see the newproject structure in the Package Explorer tab.

 | Setting up your BlackBerry UEM plug-in development environment | 25

Project structure following integration with BlackBerry UEM

After you finish:

• If you run into issues setting up the workspace, review the setup logs under Console > BlackBerry UEMIntegration SDK Plug-in Console and see Best practices and troubleshooting. After you resolve errors, repeatthis task. Clear the Create Basic Plug-in Projects check box before you run the integration process again.

• In the Windows Services, restart the BlackBerry UEM services, except for the BlackBerry UEM Core and themanagement console services. In the following tasks you will start these services from Eclipse.

• Start the BlackBerry UEM Core and management console services from Eclipse.

Start the BlackBerry UEM Core and management console services from EclipseFrom now on you will be starting and running the BlackBerry UEM Core and management console services fromyour development environment, instead of the default automatic startup or starting them from the WindowsServices.

Before you begin: Run Eclipse as an administrator. This is required for Eclipse to access BlackBerry UEM files inyour development environment.

1. On the menu bar, click Run > Run Configurations.2. Click Java Application > Core Server.

On the Environment tab, confirm that the JAVA_HOME variable is set to the appropriate JDK folder.3. Click Run.4. Verify that the BlackBerry UEM Core service starts. This process may take a few minutes.5. On the menu bar, click Run > Run Configurations.6. Click Java Application > GWT Super Dev Mode Code Server.

 | Setting up your BlackBerry UEM plug-in development environment | 26

7. Click Run.This option runs a Google Web Toolkit code server daemon that monitors changes to source code affectingthe UI client and incrementally transpiles the code to JavaScript. You can leave this process running.

8. On the menu bar, click Run > Run Configurations.9. Click Java Application > UI Server.10.Click Run.

This option runs the UI server component. This process may take a few minutes. During this time, if youtry to open the management console, your browser displays "Compiling client". The browser displays themanagement console after the compilation is complete.

After you finish: Verify that you can compile a plug-in project.

Verify that you can compile a plug-in projectAfter you set up your development environment and integrate it with a local BlackBerry UEM installation, verifythat you can compile the default projects and build a plug-in package (.zip file). When you complete yourBlackBerry UEM plug-in, this is the process you will use to create a package that you can deploy to a productionBlackBerry UEM installation. You build a plug-in package by invoking the g.bat batch file.

1. Run the command prompt as an administrator and change the directory to the plug-in root folder, for example,C:\example_plugin.

2. Type g zip.3. Press ENTER.

The resulting plug-in package is located in the root folder that you specified, in a “dist” folder. The package isnamed after the plug-in ID.

Converting CSS to GSS for GWT 2.8.0 and laterIn GWT 2.8.0, CSS (Cascading Style Sheets) are deprecated and replaced with GSS (Grid Style Sheets). If you wantto use GWT 2.8.0 or later, you must:

• Change the resource file extension from .css to .gss• Use GSS syntax instead of CSS syntax• Update the java class to reference .gss instead of .css resources

For more information and migration instructions, see the GWT Project - GSS Migration Guide.

Joining BlackBerry UEM plug-in developmentIf development will be a joint effort with other developers, the initial developer must make the plug-in projectsavailable in a code repository such as Git or Perforce. Developers that want to join plug-in development mustobtain the file structure from the repository, verify that they meet the system requirements, and follow theinstructions to configure a development environment.

When completing Create an Eclipse workspace and integrate it with BlackBerry UEM, each developer that isjoining development must do the following:

• For the Plug-in Project Root, specify the root of the plug-in file structure obtained from the code repository.• Do not select Create Basic Plug-in Projects.• Accept the prompt to auto-import the existing projects from the plug-in file structure that you obtained from

the code repository.

 | Setting up your BlackBerry UEM plug-in development environment | 27

Note: As a best practice, do not check-in the UEM Core launcher (<workspace>\core.server\launchers\CoreServer.launch) when you make the plug-in projects available in a code repository. When other developers run theintegration process, the process generates a UEM Core launcher specific to their development environment.

UEM plug-in source controlThe sample plug-in that is included in the UEM Integration SDK package includes the following .gitignore files thatspecify the files and folders that should not be checked in to a code repository:

• .gitignore• common.common\.gitignore• common.server\.gitignore• core.server\.gitignore• ui.client\.settings\.gitignore• ui.client\.gitignore• ui.client-generated\.gitignore• ui.common\.gitignore• ui.ide-dev\.gitignore• ui.server\.settings\.gitignore• ui.server\.gitignore• ui.server-generated\.gitignore

It is a best practice to keep the Eclipse workspace in a separate folder from the plug-in project. The workspaceshould not be checked in to the code repository.

Configure automated builds for a BlackBerry UEM plug-inAfter you set up a development environment for a BlackBerry UEM plug-in and make the projects available in acode respository, you can configure an automated build process.

Before you begin:

• Obtain the latest project code and file structure from the code repository. This should place the files in aproject root folder, for example, C:\example_plugin.

• In the project root file path (for example, C:\example_plugin), open the version.properties file and specify theDEV_VERSION major, minor, and patch version numbers (integer values) that you want to use for the buildprocess. To specify a fourth version number within the plug-in version string, set the BUILD_VERSION variablein your build system or command line environment for a command line plug-in build. To set the value for anEclipse build, set a Windows environment variable. The build script combines these values with a generatedbuild number and passes it as build.version on the command line.

• To publish build products to an artifact repository, in the project root file path, open the build.gradle file andmodify it to specify the credentials, publication, and repository values required to publish to your artifactrepository. The following example uses the Nexus repository manager:

//-----------------------------------------------------------------------// Main distribution//-----------------------------------------------------------------------publishing { // Define repositories to publish to repositories { maven { credentials { username System.getProperty('NEXUS_USER') password System.getProperty('NEXUS_PASSWORD')

 | Setting up your BlackBerry UEM plug-in development environment | 28

} // The following URL is a sample of what can be dynamically constructed. // Java or Groovy expression, can change as needed: url 'http://' + System.getProperty('NEXUS_REPO') + '/nexus/content/repositories/releases/' } }

// Define publications to publish publications { zip(org.gradle.api.publish.maven.MavenPublication) { groupId snapinId // like "com/company/platform/mdm/mycomponent" +$build.branch artifactId artifactId // component name version componentDevelopmentVersion // version string, from $build.version artifact zip { classifier "snapin" // Sample only, hard-coded constant can be used } } }}

After this information is added, a new set of build tasks is available with names generated based onthis template: publish<PublicationName>PublicationTo<RepositoryName>Repository. For example,publishZipPublicationToMavenRepository can be invoked during a build to upload the publication to Nexus.Note: In the BlackBerry UEM Integration SDK version 12.8, some plug-in build instructions have been removedfrom the plug-in build.gradle file and are now handled by the SDK build tooling. If you are upgrading from theSDK for UEM 12.7 to the SDK for UEM 12.8 or later, this change has two implications:• Importing a plug-in into your Eclipse environment with the 12.8 SDK will fail• The plug-in standalone build process will failTo correct this issue, remove the following build instructions from the plug-in build.gradle file: snapinManifest,translations, zip. If you import an existing plug-in with UI and Core launchers and integrate it with a new UEMinstance, you may need to regenerate the UI and Core server launchers.

• Open the command prompt as an administrator, change the directory to the project root folder, and run thefollowing command: g buildPrerequisitesWithSdkThis command creates a build-prerequisites-with-sdk.zip file in a "dist" folder at the project root. The .zip filecontains the prerequisites that are required to build a UEM plug-in. Publish build-prerequisites-with-sdk.zipto a location where the automated build system can retrieve it. Note that whenever you upgrade UEM or geta new version of the UEM Integration SDK, you must recreate build-prerequisites-with-sdk.zip and publish itagain.

Configure your automated build system to do the following:

1. Create a "build" folder in <project_root>\buildsys\. Unpack build-prerequisites-with-sdk.zip into<project_root>\buildsys\build\.

2. Change the directory to <project_root>\buildsys\build\sdk\tools and invoke g initLocal.3. Change the directory to the project root and invoke g zip to build the plug-in.

 | Setting up your BlackBerry UEM plug-in development environment | 29

Upgrading your development environmentWhen a new version of BlackBerry UEM becomes available, you must do the following to upgrade yourdevelopment environment:

• Upgrade your dedicated development instance of UEM to the new version. For instructions, see the UEMInstallation Guide.

• Download the new version of the SDK that is designed for use with the new version of UEM. • If you are upgrading your development environment from a previous version of the SDK that used

the Google Plugin for Eclipse and GWT 2.7.0 or later, and you want to use the GWT Eclipse Plugin 3.0.0 or later(recommended), do the following:

• Uninstall the previous version of the UEM Integration plug-in for Eclipse (uem.eclipse.plugin-<version>-external.zip).

• Uninstall the Google Plugin for Eclipse and GWT 2.7.0 or later.• Install the GWT Eclipse Plugin 3.0.0 or later (visit http://gwt-plugins.github.io/documentation/gwt-eclipse-

plugin/Download.html).• Complete all of the instructions in the Setting up your BlackBerry UEM plug-in development

environment section of this guide with the new version of UEM and the new SDK package.To use the GWT Eclipse plugin, install the new version of the UEM Integration plug-infor Eclipse (uem.eclipse.plugin.gwt-<version>-external.zip). When you re-import your plug-in and run theintegration process again (UEM Plug-in Tools > UEM Integration Setup), clear the Create Basic Plug-inProjects check box and select the Regenerate launchers check box. The Regenerate launchers option isrequired to ensure that your plug-in uses the new Eclipse launcher utilities for the BlackBerry UEM Core andmanagement console that are compatible with the upgraded UEM environment.

Updating the platform version dependency for your UEM plug-inWhen you create a new UEM plug-in, a snapin-manifest.properties file is generated in the root folder of your plug-in code. This file includes the following line: API_VERSION=<version number>

This API version is referenced in the META-INF/snapin-manifest.xml file in the .zip build artifact. This isthe UEM platform API version that your plug-in requires. It is important to keep this version up to date.

For example, if you developed the first version of your plug-in for UEM version 12.9, the API version willreflect the API dependency version. If you want to update your plug-in to incorporate new platform featuresfrom UEM version 12.10, you must update the API_VERSION in the snapin-manifest.properties file.

To verify the platform API version, navigate to <drive:>\Program Files\BlackBerry\UEM\common-settingsand open the uos-manifest.xml file. Find the “service” element with id “BEP” and name “API”. The value of the“version” element is the API_VERSION that your plug-in requires.

 | Upgrading your development environment | 30

Sample BlackBerry UEM plug-inThe BlackBerry UEM Integration SDK package includes a functional UEM plug-in sample that demonstratesseveral key use cases. The sample is found in the Samples folder in the SDK package.

To import the sample projects into Eclipse, extract the Samples folder to a directory on your developmentcomputer, then follow the instructions in Create an Eclipse workspace and integrate it with BlackBerry UEM, withthe following changes:

• For the Plug-in Project Root, specify the root of the sample plug-in files.• Do not select Create Basic Plug-in Projects.• Accept the prompt to auto-import the existing projects from the plug-in file structure that you specified.

For an explanation of the different projects and how they relate to each other, review BlackBerry UEM plug-inproject structure.

Explore the sample plug-in to gain a better understanding of how to build your code and how a plug-in interactswith the UEM platform to add new functionality to the code base and to display new UI elements in themanagement console.

A brief introduction to some of the key packages:

Package Description

Project: core.server

com.blackberry.snapin.sample.core.server.configuration> ConfigurationController.java

Demonstrates how to get configuration data fora plug-in from the UEM database and how to setconfiguration data in the database.

com.blackberry.snapin.sample.core.server.eventing >SampleEventListener.java

Demonstrates how a plug-in can subscribe to andhandle synchronous or asynchronous events from theUEM platform.

com.blackberry.snapin.sample.core.server.execution> SampleExecutionCallback.java

Demonstrates how a plug-in can call out to a RESTendpoint and return a success or retry on failure.

com.blackberry.snapin.sample.core.server.rest.controller> SampleProfileController.java

Demonstrates how a plug-in can create and add anew profile definition.

com.blackberry.snapin.sample.core.server.rest.controller> SampleUserController.java

Demonstrates how a plug-in can perform differentactions for user accounts (for example, retrieve,create, delete, and so on).

com.blackberry.snapin.sample.core.server.util >SampleRestEndpointController.java

Demonstrates how a plug-in can expose a RESTendpoint for external systems and software tocontact to exchange data with the plug-in.

Project: ui.client

 | Sample BlackBerry UEM plug-in | 31

Package Description

com.blackberry.snapin.sample.ui.client >ClientSnapin.java

The main entry point that is invoked when the UIclient initializes a plug-in. The UEM platform registersproviders for the plug-in’s UI elements and displaysthe UI elements that have been defined (for example,a new icon for the plug-in on the user details screen, anew menu item on the policies and profiles screen, anew settings screen, and so on).

com.blackberry.snapin.sample.ui.client.features Demonstrates how to use the features API.

com.blackberry.snapin.sample.ui.client.menu.dynamic Demonstrates how to add a dynamic menu.

com.blackberry.snapin.sample.ui.client.navigation Demonstrates how to navigate to another screen inthe management console.

com.blackberry.snapin.sample.ui.client.sampleIFrame Demonstrates how to add external content into theUEM management console using a frame model.

com.blackberry.snapin.sample.ui.client.settings Demonstrates how to add plug-in UI elements to thesettings screens.

com.blackberry.snapin.sample.ui.client.userdetails Demonstrates how to add plug-in UI elements to theuser details screens.

com.blackberry.snapin.sample.ui.client.usergroupdetails Demonstrates how to add a tab to the group detailsscreen that is specific to your plug-in.

com.blackberry.snapin.sample.ui.client.users Demonstrates how to add plug-in UI elements to theusers screens.

com.blackberry.snapin.sample.ui.client.usersandservicesDemonstrates how to add plug-in UI elements to theusers and services screens.

Project: ui.server

com.blackberry.snapin.sample.ui.server >SnapinConnection.java

Demonstrates how the UI server handles calls fromthe UI client to retrieve data from the UEM Core andprovides the data to the UI client.

 | Sample BlackBerry UEM plug-in | 32

Using widgets to customize the UI elements of a plug-inThe UI client API includes widgets that can be used to add and customize UI components for a UEM plug-in. Formore information about how the UI server and UI client components interact to create the management console ina browser, see Integrating UI elements for a plug-in.

The UI client constructs the UEM management console using a variety of widgets. This section lists the commonwidgets that are available for use, and indicates whether each requires GWT as the base class.

The details for how to use each widget are found in the UI client API reference in the Documentation folder ofthe UEM Integration SDK package.

Note: The UI client API includes more widgets than the ones listed in this section. Widgets not listed here maystill be in development and not yet ready for public use. Review the widget packages in the UI client API referencefor more information about the status of each package.

The available UI client widgets are organized into the following categories:

• Common form widgets• Factories• Table• Progress indicator• Button band• Dialogs

Common form widgetsCheck box with a label

Class: com.blackberry.platform.ui.client.api.widgets.custom.LabeledCheckBox

Base class: GXT

Example:

Combo box with a label

Class: com.blackberry.platform.ui.client.api.widgets.custom.LabeledComboBox

Base class: GXT

Example:

 | Using widgets to customize the UI elements of a plug-in | 33

Text field with a label

Class: com.blackberry.platform.ui.client.api.widgets.text.LabeledTextField

Base class: GXT

Example:

Anchor (link)

Class: com.blackberry.platform.ui.client.api.widgets.factory.anchor.BBAnchor

Base class: GWT

Example:

Label

Class: com.blackberry.platform.ui.client.api.widgets.factory.label.BBLabel

Base class: GWT

Example:

 | Using widgets to customize the UI elements of a plug-in | 34

Inline label

Class: com.blackberry.platform.ui.client.api.widgets.factory.label.BBInlineLabel

Base class: GWT

Example:

Button

Class: com.blackberry.platform.ui.client.api.widgets.custom.Button

Base class: GWT

Example:

 | Using widgets to customize the UI elements of a plug-in | 35

FactoriesCreate and return a label

Class: com.blackberry.platform.ui.client.api.widgets.factory.label.LabelFactory

Base class: GWT

Example:

Create and return an anchor (link)

Class: com.blackberry.platform.ui.client.api.widgets.factory.anchor.AnchorFactory

Base class: GWT

Example:

Create and return an icon

Class: com.blackberry.platform.ui.client.api.widgets.factory.icon.IconFactory

Base class: GWT

Example:

 | Using widgets to customize the UI elements of a plug-in | 36

TableDisplay contents in a simple table

Class: com.blackberry.platform.ui.client.api.widgets.container.Table

Base class: GWT

Example:

Progress indicatorSpinning progress image

Class: com.blackberry.platform.ui.client.api.widgets.image.ProgressIndicatorImage

Base class: GWT

Example:

Full screen spinning progress image (prevents user interaction while displayed)

Class: com.blackberry.platform.ui.client.api.util.BusyIndicator

Base class: GWT

Example:

 | Using widgets to customize the UI elements of a plug-in | 37

Button bandMultiple buttons (aligned horizontally)

Class: com.blackberry.platform.ui.client.api.widgets.custom.Button.ButtonBand

Base class: GWT 

Example: 

 | Using widgets to customize the UI elements of a plug-in | 38

DialogsPop-up dialog: Success

Class: com.blackberry.platform.ui.client.api.widgets.windows.SuccessToast

Base class: GWT

Example:

 | Using widgets to customize the UI elements of a plug-in | 39

Enabling a BlackBerry UEM plug-in to integrate with anexternal systemYou can develop a BlackBerry UEM plug-in that is designed to communicate and exchange data with softwareand systems that are outside of the BlackBerry UEM solution. For example, an external inventory system cancommunicate with a UEM plug-in to obtain users’ device information.

To allow for this interaction with an external system, you must create a public REST route for the UEM plug-in that sets a URL pattern and port for REST communication. External software can establish authenticated orunauthenticated connections with the plug-in over this REST route.

The BlackBerry UEM Integration SDK package includes two basic code samples to demonstrate howto create an authenticated REST route (SampleController.java) and an unauthenticated REST route(SampleOpenController.java). The samples are located in the Samples folder of the SDK package.

This section provides a walkthrough of the samples and provides guidance and best practices.

Establish the URL pattern for the REST routeThe REST route is exposed under the following URL and default port value:

• Authenticated: https://localhost:8095/{tenantGuid}/ext/sample/...• Unauthenticated: https://localhost:8095/{tenantGuid}/ext/open/sample/...

The tenantGuid is the SRP ID that is associated with the BlackBerry UEM domain and was entered by theadministrator when they installed the BlackBerry UEM software. It is a unique identifier for the BlackBerryUEM domain.

Note: When the administrator installs the first instance of BlackBerry UEM, by default, the installer triesto reserve port 8095 for REST communication for BlackBerry UEM plug-ins. The database name of thisport is tomcat.public.https.port. If the default port value is not available, the installer assigns an availableport value from the range of 12000 to 12999. For more information about BlackBerry UEM listening ports,see “How BlackBerry UEM selects listening ports during installation” in the BlackBerry UEM Installation content.The topic "Check the ports assigned by the BlackBerry UEM setup application" provides a script you can use toretrieve assigned port values from the UEM database. You will need to add tomcat.public.https.port to the scriptbefore you run it.

Note: The REST communication port uses a BlackBerry self-signed certificate. Any external system that wants tocommunicate over the REST route must trust this certificate to successfully make requests.

An external system must provide an authentication header to invoke a plug-in’s authenticated REST route. Thefollowing BlackBerry UEM REST API utility method can be used to generate an authentication header: https://localhost:18084/{tenantGuid}/api/v1/util/authorization. For more information about using this method toauthenticate API calls, see the BlackBerry Web Services REST API Reference – Utilities, and Example: RequestAuthorization Header.

All controllers must:

• Be annotated with @Controller• Extend AbstractController• Be annotated with @Path and use AbstractController.PATH_PREFIX (authenticated)

or AbstractController.OPEN_PATH_PREFIX (unauthenticated).

 | Enabling a BlackBerry UEM plug-in to integrate with an external system | 40

SampleController.java

@Controller@Path(AbstractController.PATH_PREFIX + "/sample")public class SampleController extends AbstractController{ /** * Provides access to authentication utilities. * Any UEM services can be @Autowired into controllers */ @Autowired private AuthenticationUtil authenticationUtil;

SampleOpenController.java

@Controller@Path(AbstractController.OPEN_PATH_PREFIX + "/sample")public class SampleOpenController extends AbstractController{

Access BlackBerry UEM loggingThe following statement provides access to the standard logging capability of BlackBerry UEM.

private static final MDMLogger LOGGER = MDMLoggerFactory.getLogger(SampleController.class);

Validate using a query stringTo validate the REST path, create a ping route that returns a passed string value. The sample establishes thefollowing URL path for the query:

• Authenticated: http://localhost:8095/{tenantGuid}/ext/sample/ping?pingValue=Hello• Unauthenticated: http://localhost:8095/{tenantGuid}/ext/open/sample/ping?pingValue=Hello

@GET and @Path are required to establish the REST route. For more information, see "Using @Path and @GET,@POST, etc" in the jboss.org Community Documentation.

The sample code returns an error if the passed value is null, or a response if the passed value is a valid string.@QueryParam pingValue is the value to return, @Suspended asyncResponse is the object that returns a responseto the client.

The following code is the same in both samples, but SampleOpenController.java usesAbstractController.OPEN_PATH_PREFIX instead.

SampleController.java

@GET @Path("/ping") public void pingQueryRoute(@QueryParam("pingValue") String pingValue, @Suspended final AsyncResponse asyncResponse)

 | Enabling a BlackBerry UEM plug-in to integrate with an external system | 41

{ // Log the request LOGGER.debug("{}/sample/ping?pingValue={}", AbstractController.PATH_PREFIX, pingValue); // The response to send back Response response = null; // No guarantee a query parameter is sent. Must check for null. if (pingValue != null) { // Create an OK response with the pingValue response = Response.ok(pingValue).build(); } else { // Create an error response response = Response.status(Status.BAD_REQUEST).entity("Must provide 'pingValue' on the query string").build();

// Log the error LOGGER.error("Must provide 'pingValue' on the query string"); } // Send back the response asyncResponse.resume(response); }

Validate using a URI valueTo vaildate the REST path, create a ping route that returns a passed URI value. The sample establishes thefollowing URL path for the query:

• Authenticated: http://localhost:8095/{tenantGuid}/ext/sample/ping/Hello• Unauthenticated: http://localhost:8095/{tenantGuid}/ext/open/sample/ping/Hello

The following code is the same in both samples, but SampleOpenController.java usesAbstractController.OPEN_PATH_PREFIX instead.

SampleController.java

@GET @Path("/ping/{pingValue}") public void pingUriRoute(@PathParam("pingValue") String pingValue, @Suspended final AsyncResponse asyncResponse) { // Log the request LOGGER.debug("{}/sample/ping/{}", AbstractController.PATH_PREFIX, pingValue);

// Send back the response. The pingValue is always set because this is a path parameter asyncResponse.resume(Response.ok(pingValue).build()); }

 | Enabling a BlackBerry UEM plug-in to integrate with an external system | 42

Retrieve information from the authorization headerThe final portion of the SampleController.java sample is used to retrieve information about the authenticated user(username and first name) and tenant (SRP ID) from the authorization header and return it as a JSON payload.The following URL path is used for this purpose: https://localhost:8095/{tenantGuid}/ext/sample/authInfo

The sample comments also explain another way to retrieve this information using methods of theAuthenticationUtil class.

As in the previous sections, @Suspended asyncResponse is the object that returns a response to the client.

SampleController.java

@GET @Path("/authInfo") public void authInfo(@Suspended final AsyncResponse asyncResponse) { // Log the request LOGGER.debug("{}/sample/authInfo", AbstractController.PATH_PREFIX);

// Retrieve the authenticated user and tenant from the base class IUser authenticatedUser = getUser(); ITenant authenticatedTenant = getTenant();

// This can also be done elsewhere using the AuthenticationUtil // IUser authenticatedUser = authenticationUtil.getUser(); // ITenant authenticatedTenant = authenticationUtil.getTenant();

// Create a simple return payload. This will get converted to JSON. HashMap<String, String> info = new HashMap<String, String>(); info.put("username", authenticatedUser.getUsername()); info.put("firstName", authenticatedUser.getFirstName()); info.put("externalTenantId", authenticatedTenant.getExternalTenantId());

// Return the response asyncResponse.resume(Response.ok(info).build()); }

 | Enabling a BlackBerry UEM plug-in to integrate with an external system | 43

Best practices and troubleshootingBest practices

How to... Steps

Avoid issues if you remove an RXmethod annotation

If you remove an RX method annotation, code that was generatedpreviously for that annotation will remain in the ui.server project. Youmust manually remove all generated code from the ui.server project,then regenerate the code by clean-building the ui.server project (Project >Clean). When this is complete, refresh all projects in Eclipse.

Remove a plug-in froma BlackBerry UEM installation (testor production)

1. In the Windows Services, stop the BlackBerry UEM Core andmanagement console services.

2. Shut down Eclipse.3. Delete the plug-in folder from <drive>:\Program Files\BlackBerry

\UEM\ext\.4. Navigate to <drive>:\Program Files\BlackBerry\UEM\ui\ and

run deploy.bat as an administrator. This process may take up to 10minutes.

5. When deploy.bat completes, restart the BlackBerry UEM Core andmanagement console services.

Troubleshooting

Issue Possible solution

In Eclipse, I can't view log data forthe UI server

In Run > Run Configurations > Java Application > UI Server, add thefollowing VM argument: -"Dlog4j.configuration=file:///${bep.ui}/log4j.xml"

Eclipse crashes Add -XX:-UseLoopPredicate to the eclipse.ini file. For moreinformation, see Stack Overflow: Eclipse crashing frequently.

The Core or UI launchers do notstart

Complete the integration process again and select the Regeneratelaunchers check box.

 | Best practices and troubleshooting | 44

Issue Possible solution

The ui.client project does notcompile due to missing classes inthe <plug-in_id>.ui.server package

There are errors in *-generatedprojects (but none in serverprojects)

Possible solution 1:

1. Verify that there are no errors in *.common and *.server projects.2. In Eclipse, verify that auto-building is enabled.3. Delete all generated source code (src/generated) in *-generated

projects. Ignore additional errors that are caused by this step.4. Clean the ui.server project (Project > Clean > Clean projects selected

below).5. Refresh all projects:

a. In the Project Explorer, collapse all projects. For each project, onlythe project name should be visible, not the contents.

b. Click a project that is not currently selected.c. Click a different project.d. Press Ctrl + A.e. Press F5.

6. Wait for the build to complete.

If this does not correct the issue, clean all projects (Project > Clean >Clean all projects) then repeat steps 5 and 6.

Possible solution 2: In the project ui.server-generated, create a foldernamed src/generated. Put a dummy file in this folder and rebuild theproject.

Possible solution 3: Run the integration process again (see Createan Eclipse workspace and integrate it with BlackBerry UEM) and do notselect Create Basic Plug-in Projects.

 | Best practices and troubleshooting | 45

Deploy a plug-in to a production BlackBerry UEM domainFollow these instructions when your plug-in is complete and ready to deploy to a production BlackBerryUEM domain. The deployment process will stop the BlackBerry UEM services for a short time, so you shouldperform this task when there will be minimal impact to users.

If you want to create a simple executable installer that automates this process, see Creating an installer fora BlackBerry UEM plug-in instead.

Whenever you update or create a new version of a plug-in, follow this process again to re-deploy the snap-in.

1. On your development computer, run the command prompt as an administrator and change the directory to theplug-in root folder (for example, C:\example_plugin).

2. Type g zip.3. Press ENTER.

After g.bat builds the plug-in package, you can find it in a “dist” folder in the root folder that you specified (forexample, C:\example_plugin). The .zip file is named after the plug-in ID.

4. Copy the .zip file to each computer that hosts a production BlackBerry UEM instance.5. On each computer that hosts a production BlackBerry UEM instance, open the command line as an

administrator and change the directory to <drive>:\Program Files\BlackBerry\UEM\tools\plugins\onprem.Execute one of the following commands:

• To install a plug-in, execute: plugin-deploy.bat --plugins "<file_path>"• To upgrade an existing plug-in to a new version, execute: plugin-deploy.bat --plugins

"<file_path>" --update 

"<file_path>" is the location of the plug-in package (.zip). The file path must be enclosed in double quotationmarks. If you want to integrate more than one plug-in, you can type a comma-separated list of file paths in oneset of double quotation marks (for example, "<file_path>,<file_path>,<file_path>").The command validates the plug-in, integrates it with the BlackBerry UEM components, and restartsthe BlackBerry UEM services. This process may take some time (approximately 10 minutes). After the plug-inis integrated, the plug-in files are located at <drive>:\Program Files\BlackBerry\UEM\ext\.

Creating an installer for a BlackBerry UEM plug-inYou have the option to create a simple executable installer for a BlackBerry UEM plug-in. This is an alternative tothe basic deployment steps described in Deploy a plug-in to a production BlackBerry UEM domain. You may wantto create an executable installer if you want others to install the plug-in on one or more BlackBerry UEM instances.

What you will need to create an executable installer:

• The BlackBerry UEM plug-in package generated from Eclipse. See Verify that you can compile a plug-in project,or steps 1 to 3 in Deploy a plug-in to a production BlackBerry UEM domain.

• The commands for the plugin-deploy.bat batch file, provided below. You can find plugin-deploy.bat inthe BlackBerry UEM installation files. See "plugin-deploy.bat commands" below.

• If you want the installer to display a simple UI, a plug-in installer configuration file. See the "Installer UIconfiguration file" section below.

Note: If you choose to deploy a BlackBerry UEM plug-in using an executable installer, the installer must be run oneach computer that hosts a BlackBerry UEM instance in the organization’s domain.

 | Deploy a plug-in to a production BlackBerry UEM domain | 46

plugin-deploy.bat commands

Each instance of BlackBerry UEM 12.7 or later includes a plugin-deploy.bat batch file in <drive>:\Program Files\BlackBerry\UEM\tools\plugins\onprem. When an administrator installs a UEM instance, plugin-deploy.bat ispopulated with values such as the install location and the log file path. You will use this batch file to validatea BlackBerry UEM plug-in and integrate it with a UEM installation. For your UEM plug-in installer, specify thefollowing commands for plugin-deploy.bat:

Command Description

--plugins "<file_path>" The absolute or relative file path of the UEM plug-in package that wasgenerated from Eclipse

--GUI "<file_path>" Optional, use only if you want to display a simple installer UI; theabsolute or relative file path of the plug-in installer UI configuration file

--iAcceptEULA Optional, use only if you want to display a simple installer UI and youwant to display an end-user license agreement (EULA) that the user mustaccept before starting the installation

--update You must use this parameter if you are upgrading an existing UEM plug-in to a new version. 

Example command

plugin-deploy.bat --plugins “C:\pluginDirectory\example_plugin.zip” --GUI "C:\pluginDirectory\ConfigFile.txt" --iAcceptEULA

Installer UI configuration file

You can display a simple UI for the UEM plug-in installer. The UI consists of the following screens:

• Language selection (optional): The user selects the language of the text used in the installer (statusmessages, text on buttons, and so on). You provide the translated text of the product name (full name andshort name) in the configuration file.

• Splash screen: Displays the full product name and market version, and provides the initialization status.Provides error messages for common initialization issues (for example, UEM does not support this version, alater version was found, this product is already installed, and so on). The user clicks Next or Cancel.

• License screen (optional): The user selects and views a EULA for the product. The user accepts the license,then clicks Install to start the installation. For more information, see the "Adding a license screen" sectionbelow.

• Installation: Displays the overall progress of the installation and the progress of the current installation step. Ifissues occur, this screen displays a corresponding error message.

If you want the plug-in installer to use a simple UI, specify the following properties as key-value pairs in aconfiguration text file (for example, ConfigFile.txt):

 | Deploy a plug-in to a production BlackBerry UEM domain | 47

Property Description

deployer.product.full.name The full product name that is displayed on the splash screen and on theinstallation status screens.

The specified product name is used for a product folder and log folder inthe BlackBerry UEM installation files:

• <drive>:\Program Files\BlackBerry\<product_name>• <drive>:\Program Files\BlackBerry\<product_name>\Logs

deployer.product.short.name A short product name that is displayed in the top panel of each installerscreen.

deployer.product.version The product version number that is displayed in the log files. You canspecify a version number with up to four version sections in the followingformat: x.x.x.x

deployer.market.version The product version number that is displayed on the splash screenand in the top panel of each installer screen. You can specify a versionnumber with up to four version sections in the following format: x.x.x.x

deployer.supported.languages.list A comma-separated list of the languages supported by the installer,represented by language codes. Only the following language codes canbe specified:

• en - English (included by default)• fr - French• es - Spanish• ja - Japanese• de - German

When a user opens the installer, a language selection window displaysthe language options that correspond to the codes specified. If nolanguage codes are specified (or only en is specified), the languageselection window does not display.

If you specify a language code, add the translated textfor the necessary installer properties using the followingformat: <property>.<language_code>, for example,deployer.product.short.name.es=Inventario

Example configuration file

deployer.product.full.name=Inventory Plug-in for BlackBerry UEMdeployer.product.full.name.es=Plug-in de inventario para BlackBerry UEMdeployer.product.short.name=Inventorydeployer.product.short.name.es=Inventariodeployer.product.version=1.1.1.1deployer.market.version=1.1deployer.supported.languages.list=en,es

 | Deploy a plug-in to a production BlackBerry UEM domain | 48

Adding a license screen

If you want the installer UI to display a license screen, in the folder that contains plugin-deploy.bat (<drive>:\Program Files\BlackBerry\UEM\tools\plugins\onprem), you must create a Licenses folder that containsa TXT folder.

The TXT folder must contain:

• Text (.txt) files that contain the UTF-8 license text that you want to display. Use a separate text file foreach language. For examples, see the BlackBerry UEM licenses in <drive>:\BlackBerry\UEM\BlackBerryUEM <version>\Licenses\TXT.

• An sla.ini file with sections for each license with a unique ID header in square brackets, the translated stringsfor each language (an english line is required as the default), and the relative path to the license text file. Forexample:

[DZ_English]DisplayName_en=Algeria (English)DisplayName_es=Argelia (inglés)InstallSLA=BBSLA_Algeria_English.txt

Removing a plug-in from a BlackBerry UEM instanceAfter you deploy a UEM plug-in, it displays in the standard list of programs installed on your computer(Windows Control Panel > Uninstall or change a program). To uninstall a UEM plug-in, you can select the plug-infrom the list of installed programs and use the standard OS option to uninstall it. This removes the plug-in fromthe UEM instance.

 | Deploy a plug-in to a production BlackBerry UEM domain | 49

Legal notice ©2020 BlackBerry Limited. Trademarks, including but not limited to BLACKBERRY, BBM, BES, EMBLEM Design,ATHOC, CYLANCE and SECUSMART are the trademarks or registered trademarks of BlackBerry Limited, itssubsidiaries and/or affiliates, used under license, and the exclusive rights to such trademarks are expresslyreserved. All other trademarks are the property of their respective owners. 

 This documentation including all documentation incorporated by reference herein such as documentationprovided or made available on the BlackBerry website provided or made accessible "AS IS" and "AS AVAILABLE"and without condition, endorsement, guarantee, representation, or warranty of any kind by BlackBerry Limited andits affiliated companies ("BlackBerry") and BlackBerry assumes no responsibility for any typographical, technical,or other inaccuracies, errors, or omissions in this documentation. In order to protect BlackBerry proprietary andconfidential information and/or trade secrets, this documentation may describe some aspects of BlackBerrytechnology in generalized terms. BlackBerry reserves the right to periodically change information that is containedin this documentation; however, BlackBerry makes no commitment to provide any such changes, updates,enhancements, or other additions to this documentation to you in a timely manner or at all. 

This documentation might contain references to third-party sources of information, hardware or software,products or services including components and content such as content protected by copyright and/or third-party websites (collectively the "Third Party Products and Services"). BlackBerry does not control, and is notresponsible for, any Third Party Products and Services including, without limitation the content, accuracy,copyright compliance, compatibility, performance, trustworthiness, legality, decency, links, or any other aspectof Third Party Products and Services. The inclusion of a reference to Third Party Products and Services in thisdocumentation does not imply endorsement by BlackBerry of the Third Party Products and Services or the thirdparty in any way.

EXCEPT TO THE EXTENT SPECIFICALLY PROHIBITED BY APPLICABLE LAW IN YOUR JURISDICTION, ALLCONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS, OR WARRANTIES OF ANY KIND, EXPRESSOR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY CONDITIONS, ENDORSEMENTS, GUARANTEES,REPRESENTATIONS OR WARRANTIES OF DURABILITY, FITNESS FOR A PARTICULAR PURPOSE OR USE,MERCHANTABILITY, MERCHANTABLE QUALITY, NON-INFRINGEMENT, SATISFACTORY QUALITY, OR TITLE, ORARISING FROM A STATUTE OR CUSTOM OR A COURSE OF DEALING OR USAGE OF TRADE, OR RELATED TO THEDOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE,SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN, ARE HEREBY EXCLUDED.YOU MAY ALSO HAVE OTHER RIGHTS THAT VARY BY STATE OR PROVINCE. SOME JURISDICTIONS MAYNOT ALLOW THE EXCLUSION OR LIMITATION OF IMPLIED WARRANTIES AND CONDITIONS. TO THE EXTENTPERMITTED BY LAW, ANY IMPLIED WARRANTIES OR CONDITIONS RELATING TO THE DOCUMENTATION TOTHE EXTENT THEY CANNOT BE EXCLUDED AS SET OUT ABOVE, BUT CAN BE LIMITED, ARE HEREBY LIMITED TONINETY (90) DAYS FROM THE DATE YOU FIRST ACQUIRED THE DOCUMENTATION OR THE ITEM THAT IS THESUBJECT OF THE CLAIM.

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, IN NO EVENT SHALLBLACKBERRY BE LIABLE FOR ANY TYPE OF DAMAGES RELATED TO THIS DOCUMENTATION OR ITS USE,OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRDPARTY PRODUCTS AND SERVICES REFERENCED HEREIN INCLUDING WITHOUT LIMITATION ANY OF THEFOLLOWING DAMAGES: DIRECT, CONSEQUENTIAL, EXEMPLARY, INCIDENTAL, INDIRECT, SPECIAL, PUNITIVE,OR AGGRAVATED DAMAGES, DAMAGES FOR LOSS OF PROFITS OR REVENUES, FAILURE TO REALIZE ANYEXPECTED SAVINGS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, LOSS OF BUSINESSOPPORTUNITY, OR CORRUPTION OR LOSS OF DATA, FAILURES TO TRANSMIT OR RECEIVE ANY DATA,PROBLEMS ASSOCIATED WITH ANY APPLICATIONS USED IN CONJUNCTION WITH BLACKBERRY PRODUCTS ORSERVICES, DOWNTIME COSTS, LOSS OF THE USE OF BLACKBERRY PRODUCTS OR SERVICES OR ANY PORTIONTHEREOF OR OF ANY AIRTIME SERVICES, COST OF SUBSTITUTE GOODS, COSTS OF COVER, FACILITIES ORSERVICES, COST OF CAPITAL, OR OTHER SIMILAR PECUNIARY LOSSES, WHETHER OR NOT SUCH DAMAGES

 | Legal notice | 50

WERE FORESEEN OR UNFORESEEN, AND EVEN IF BLACKBERRY HAS BEEN ADVISED OF THE POSSIBILITY OFSUCH DAMAGES.

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, BLACKBERRY SHALLHAVE NO OTHER OBLIGATION, DUTY, OR LIABILITY WHATSOEVER IN CONTRACT, TORT, OR OTHERWISE TOYOU INCLUDING ANY LIABILITY FOR NEGLIGENCE OR STRICT LIABILITY.

THE LIMITATIONS, EXCLUSIONS, AND DISCLAIMERS HEREIN SHALL APPLY: (A) IRRESPECTIVE OF THE NATUREOF THE CAUSE OF ACTION, DEMAND, OR ACTION BY YOU INCLUDING BUT NOT LIMITED TO BREACH OFCONTRACT, NEGLIGENCE, TORT, STRICT LIABILITY OR ANY OTHER LEGAL THEORY AND SHALL SURVIVE AFUNDAMENTAL BREACH OR BREACHES OR THE FAILURE OF THE ESSENTIAL PURPOSE OF THIS AGREEMENTOR OF ANY REMEDY CONTAINED HEREIN; AND (B) TO BLACKBERRY AND ITS AFFILIATED COMPANIES, THEIRSUCCESSORS, ASSIGNS, AGENTS, SUPPLIERS (INCLUDING AIRTIME SERVICE PROVIDERS), AUTHORIZEDBLACKBERRY DISTRIBUTORS (ALSO INCLUDING AIRTIME SERVICE PROVIDERS) AND THEIR RESPECTIVEDIRECTORS, EMPLOYEES, AND INDEPENDENT CONTRACTORS.

IN ADDITION TO THE LIMITATIONS AND EXCLUSIONS SET OUT ABOVE, IN NO EVENT SHALL ANY DIRECTOR,EMPLOYEE, AGENT, DISTRIBUTOR, SUPPLIER, INDEPENDENT CONTRACTOR OF BLACKBERRY OR ANYAFFILIATES OF BLACKBERRY HAVE ANY LIABILITY ARISING FROM OR RELATED TO THE DOCUMENTATION.

Prior to subscribing for, installing, or using any Third Party Products and Services, it is your responsibility toensure that your airtime service provider has agreed to support all of their features. Some airtime serviceproviders might not offer Internet browsing functionality with a subscription to the BlackBerry® Internet Service.Check with your service provider for availability, roaming arrangements, service plans and features. Installationor use of Third Party Products and Services with BlackBerry's products and services may require one or morepatent, trademark, copyright, or other licenses in order to avoid infringement or violation of third party rights. Youare solely responsible for determining whether to use Third Party Products and Services and if any third partylicenses are required to do so. If required you are responsible for acquiring them. You should not install or useThird Party Products and Services until all necessary licenses have been acquired. Any Third Party Products andServices that are provided with BlackBerry's products and services are provided as a convenience to you and areprovided "AS IS" with no express or implied conditions, endorsements, guarantees, representations, or warrantiesof any kind by BlackBerry and BlackBerry assumes no liability whatsoever, in relation thereto. Your use of ThirdParty Products and Services shall be governed by and subject to you agreeing to the terms of separate licensesand other agreements applicable thereto with third parties, except to the extent expressly covered by a license orother agreement with BlackBerry.

The terms of use of any BlackBerry product or service are set out in a separate license or other agreement withBlackBerry applicable thereto. NOTHING IN THIS DOCUMENTATION IS INTENDED TO SUPERSEDE ANY EXPRESSWRITTEN AGREEMENTS OR WARRANTIES PROVIDED BY BLACKBERRY FOR PORTIONS OF ANY BLACKBERRYPRODUCT OR SERVICE OTHER THAN THIS DOCUMENTATION.

BlackBerry Enterprise Software incorporates certain third-party software. The license and copyright informationassociated with this software is available at http://worldwide.blackberry.com/legal/thirdpartysoftware.jsp.

BlackBerry Limited2200 University Avenue EastWaterloo, OntarioCanada N2K 0A7

BlackBerry UK LimitedGround Floor, The Pearce Building, West Street,Maidenhead, Berkshire SL6 1RLUnited Kingdom

Published in Canada

 | Legal notice | 51