Packages
Package	Description
com.rim.platform.mdm.core.plugin.bws.dto
com.rim.platform.mdm.core.plugin.bws.service

Overview

The BlackBerry Web Services for BlackBerry Enterprise Service 12 are a collection of document-style web services that you can use to create applications to manage your organization's BES12 domain. You can use the BlackBerry Web Services to automate many of the tasks that administrators typically perform using the management console. For example, you can create an application that automates the process of adding user accounts to the domain, or you can create a self-service portal that allows device users to perform basic management tasks.

The BlackBerry Web Services are installed automatically when you install the management console for the BES12. To use the BlackBerry Web Services, you should be proficient in one of the supported programming languages and in the use of common web services concepts such as XML, SOAP, and WSDL. You should be familiar with the configuration and administration of the domain, including the management of user accounts, groups, IT policies, software configurations, and security settings.

For more information about the BlackBerry Web Services, visit docs.blackberry.com/bwsbes12 to read the Feature and Technical Overview, Getting Started Guide, and Release Notes.

For a complete list of the management tasks that you can perform and code samples demonstrating their usage, see the following services pages:

BWS
BWSUtil

Sample applications demonstrating how to use BlackBerry Web Services are available in Java, C#, and PowerShell. You can find them on GitHub at github.com/blackberry/BWS-Samples.

Key concepts

The following concepts are referenced throughout the API documentation. Please review these concepts before you integrate your custom applications with the BlackBerry Web Services.

BWS date format

A date and time in the format of MM/dd/yyyy HH:mm:ss (eg. 02/29/2012 08:10:24). This value will also be in UTC and no timezone information will be returned.

Enumeration implementation classes

To help preserve backwards compatibility, BlackBerry Web Services contains many classes implemented as enumerators. These classes contain a set of boolean fields where exactly one boolean must be true. Each class also has a value field that contains a string representing the field that's set to true.

To ensure that your application is compatible with later versions, your code should not logically depend on the value field. The string values can change, so they should only be used for logging purposes. Instead, you should always check the individual boolean values to find out the current state of the object.

It is good practice to set the value field to the name of the boolean field that is set to true, so that if the server doesn't support the field that is set to true, it can log the value and return it in the error message. This could potentially happen when a new client attempts to pass a boolean to an old server. When the server encounters an enum value which it doesn't support an enumeration implementation object with its UNSUPPORTED_VALUE boolean field set will occur in a response. In this case, the name of the unsupported value will be stored in the value field of the enumeration implementation.

Policy

Administrators create and use policies to configure user permissions and security settings on devices. Policies consist of policy rules that administrators can configure to change device functionality. IT policies, Wi-Fi profiles, and VPN profiles are all classified as policies.

RequestMetadata creation

private final static String CLIENT_VERSION = "12.0.0";
private final static String LOCALE = "en_US";
private final static String ORG_UID = "0";

private final static RequestMetadata REQUEST_METADATA = new RequestMetadata();

private static void initializeRequestMetadata()
{
        REQUEST_METADATA.setClientVersion(CLIENT_VERSION);
        REQUEST_METADATA.setLocale(LOCALE);
        REQUEST_METADATA.setOrganizationUid(ORG_UID);
}

Error codes common to all APIs:

SUCCESS - The operation completed successfully.
ONE_OR_MORE_FAILURES - The operation failed for at least one of the entities in the request object, see the individual responses for more information.
INVALID_PARAMETER - One or more of the parameters are invalid, see the return message for more information.
NOT_AUTHORIZED - The user is not authorized to perform this operation.
NOT_SUPPORTED - This operation is not supported, see error message for more details.
METADATA_REQUIRED - The required RequestMetadata parameter was not given.
NULL_REQUEST - Request object cannot be null.
UNKNOWN - Unknown internal error.

Framework

This API documentation is generated for use with the Apache CXF Web Service framework. Actual syntax may differ on other web service frameworks. The BlackBerry Web Services proxy classes can be successfully generated on the following frameworks:

Language	Web Service Framework
Java SE Development Kit 5-7	Apache CXF 2.7.3 (binary distribution)
	Apache Axis2 1.5.1
Microsoft Visual Studio C# (2005, 2008, or 2010)	Microsoft .NET Framework v2.0 or later

API Reference BlackBerry Enterprise Service 12.0.0 BlackBerry Web Services for Enterprise Administration