blackberry.com
BlackBerry Dynamics
Runtime library for iOS applications
from the application developer portal

BlackBerry Dynamics Service Definition

Defining BlackBerry Dynamics services enables rich and secure collaboration between applications.

BlackBerry Dynamics Application-Based Services utilize AppKinetics, which is a means of exchanging data and commands securely between two applications running on the same mobile device. Communication in the AppKinetics system follows a consumer-provider type of interaction. The service consumer application initiates data sharing by calling a method in the service provider application.

A BlackBerry Dynamics service definition is a declaration of the methods that comprise a service. For each method, the service definition includes:

  • Input and output parameters.
  • Input and output file attachments.
  • Errors returned.

AppKinetics can be used without service definitions having been declared. In that case, the interface of the service provider must be provided to the developer of the consumer by some other means.

To see the current public services and their definitions:

  1. Open the BlackBerry Dynamics application developer portal.
  2. Select a platform, if prompted to do so.
  3. In the Support Materials, open the Shared Services link.
  4. This opens the market place Mobile Services page, which shows all BlackBerry Dynamics shared services that have been published as public.
See also:
The GDService class reference, for a description of AppKinetics and its programming inteface.

Implementation

To declare a BlackBerry Dynamics service, create a schema definition file in the format described below.

The schema definition can be uploaded directly in the service management screens in the enterprise BlackBerry Dynamics management console. Alternatively, the file can be uploaded via the application developer portal website, and then designated either public or private.

BlackBerry Dynamics applications can be registered as providers of a service, once the service definition has been uploaded. Do this in the same user interface in which the service definition was uploaded, either the management console or the application developer portal.

The AppKinetics system does not enforce the service definition. The service definition can be considered to be a set of hints to service consumers, or a statement of expectation and intent by service providers.

Service Definition File Format

BlackBerry Dynamics service definition files are JavaScript Object Notation (JSON) files. The format is defined in terms of JSON objects and attributes.

The top level of a service definition is a single JSON object. The object must conform to the Service schema, meaning that it must include a number of required attributes, and may include a number of non-required attributes. Attributes can be of a simple type, such as number or string. Attributes can also themselves be objects. Attributes that are objects must themselves conform to a schema, defined in similar terms to the top-level schema, i.e. with required and non-required attributes of simple type or of object type, conforming to a schema.

Schema: Service

Create an object that conforms to this schema to define the whole service. The definition consists of a number of identification and description attributes, and a list of one or more methods. The methods are the substance of the service.

Attribute: service-id Required:Y Type:string

Unique identifier of the service, the service identifier. The value of this attribute will be the value used when registering or discovering the service.

The same syntactic rules apply to the service identifier as apply to the BlackBerry Dynamics entitlement identifier, see under Identification in the GDiOS class reference.

Attribute: version Required:Y Type:string

Version number of the service.

Attribute: creator_information Required:N Type:object

Information about the creator of the service definition, for display purposes. Set this attribute to an object that conforms to the Creator Information schema, see below.

Attribute: title Required:N Type:string

Title of the service, for display purposes.

Attribute: description Required:N Type:string

Description of the service, for display purposes.

Attribute: methods Required:Y Type:object

Defintion of the methods that comprise the service. Create a single object with an attribute for each method in the service. Set the name of the attribute to the name of the method. Set each attribute's value to an object that defines the method according to the Method schema, see below.

Schema: Method

Create an object that conforms to this schema to define a method within a service. The definition includes declarations of the inputs and outputs of the method.

The input declarations specify the expected characteristics of service requests sent to the method. The input declaration has two parts: parameter specification and file attachments specification.

The output declarations specify the characteristics of service replies returned by the method. The output declaration has three parts: parameter specification, file attachments specification, and error specification. Note that a method need not return any service replies.

Attribute: params Required:N Type:object

Declares the expected parameters of a service request sent to the method. Set this attribute to an object that conforms to the Parameter schema, see below. Omit this attribute if the method expects no parameters in its service requests.

Attribute: attachments Required:N Type:object

Declares the expected file attachments of a service request sent to the method. Set this attribute to an object that conforms to the Attachments schema, see below. Omit this attribute if the method expects no file attachments in its service requests.

Attribute: result-value Required:N Type:object

Specifies the parameters of non-error service response returned by the method. Set this attribute to an object that conforms to the Parameter schema, see below. Omit this attribute if the method does not return service replies. Note that this attribute must be present if the result-attachments attribute, below, is present.

Attribute: result-attachments Required:N Type:object

Specifies the file attachments of non-error service responses returned by the method. Set this attribute to an object that conforms to the Attachments schema, see below. Omit this attribute if the method does not return service replies, or if the method does not attach files to its service replies.

Attribute: errors Required:N Type:array

Specifies the custom errors that may be returned by the method. Set this attribute to an array of elements that conform to the Error schema, see below. Omit this attribute if the method does not define any custom errors.

Do not include AppKinetics common errors that could be returned by the method in this attribute. See AppKinetics Errors for details of common errors.

Attribute: description Required:N Type:string

Description of the method, for display purposes.

Schema: Parameter

Create an object that conforms to this schema to define the parameters of a service request or service response, either collectively or individually. A service request may take a single parameter, or may take a number of parameters. The same is true of service responses. This schema is used to define the parameters in all cases.

This schema can be recursive. The definition of a collection of parameters will conform to this schema itself, and will contain objects that also conform to this schema.

Parameters can be declared as optional or mandatory. Optional parameters can be omitted from service requests, and may not be present in service responses.

Attribute: type Required:N Type:string

The type of the parameter. The following values have particular meanings:

string
number
integer
boolean
null
Set this attribute to one of these values to define a single parameter of the specified simple type.
UInt8Array
Set this attribute to this value to define a single byte array parameter.
array
Set this attribute to this value to define a parameter that is a list of values of the same type. Set the items attribute, below, to define the type of the elements in the array.
object
Set this attribute to this value to define a parameter that is a collection of named sub-parameters. Use this value in the top-level definition of a request or response that takes multiple parameters. Set the properties attribute, below, to define the sub-parameters.

Other values are allowed but have no particular meaning.

Attribute: items Required:N Type:object

For an array type parameter, this attribute defines the type of every element in the array. Set the attribute to an object that conforms to the Parameter schema.

For a parameter of any other type, omit this attribute.

Attribute: properties Required:N Type:object

For an object type parameter, this attribute defines the types of the sub-parameters. Set the attribute to an object that has an attribute for each sub-parameter. Set the name of each attribute to the name of the sub-parameter. Set the value of each attribute to an object that conforms to the Parameter schema.

For a parameter of any other type, omit this attribute.

Attribute: description Required:N Type:string

Description of the parameter, for display purposes.

Attribute: required Required:N Type:Boolean

Specifies whether this parameter is mandatory. If this attribute is omitted, the parameter is optional by default.

Attribute: enum Required:N Type:array

Specifies the valid values of this parameter. Set the attribute to an array of values, each of which conforms to the definition specified in the type and other attributes. For example, if the object has "type": "string", set this attribute to an array of string values.

If this attribute is omitted, then any value that conforms to the type definition is valid for the parameter.

Schema: Attachments

Create an object that conforms to this schema to declare the file attachments for a service request or service response. File attachments can be mandatory or optional.

For service requests, the object declares the file attachments that the service consumer should include for the request to be valid. For service responses, the object declares the file attachments that will be supplied by the service provider in a non-error response.

Attribute: items Required:N Type:array

Information about mandatory file attachments. The information includes, for example, the display title and description of the file attachment. Set this attribute to either of the following.

  • A single object that conforms to the Individual Attachment schema, see below.
  • An array of objects, one per mandatory file attachment, each of which conforms to the Individual Attachment schema.

Set a single object if the same information applies to all mandatory files.

Attribute: additionalItems Required:N Type:array

Information about optional file attachments. Set this attribute to an object that conforms to the Individual Attachment schema, see below. The information in this object applies to all optional file attachments.

Attribute: minItems Required:N Type:number

Minimum number of file attachments.

Attribute: maxItems Required:N Type:number

Maximum number of file attachments.

Schema: Individual Attachment

Create an object that conforms to this schema to declare information about file attachments. See the Attachments schema, above, for details of when to use this schema.

Note that the attribute values are for display documentation only and are not available in the application. For example, the application cannot refer to an attachment by its title. In the application, attachments can only be accessed by their ordinal number in the attachments array.

Attribute: title Required:N Type:string

Title of the attachment, for display purposes.

Attribute: description Required:N Type:string

Description of the attachment, for display purposes.

Attribute: format Required:N Type:string

MIME type of the attachment. MIME is an abbreviation for Multipurpose Internet Mail Extensions.

Schema: Error

Create an object that conforms to this schema to declare an error condition that is specific to a service or method. Error conditions may be returned instead of service responses.

Attribute: title Required:N Type:string

Title of the error, for display purposes. This attribute's value should be short enough to appear as a heading in a document. Note that the value of this attribute is not available to the application.

Attribute: description Required:N Type:string

Description of the error condition, for display purposes. This attribute can take a longer value than the title attribute, above. Note that the value of this attribute is not available to the application.

Attribute: code Required:N Type:number

Error code returned to indicate the condition.

Attribute: data Required:N Type:object

Additional details that will be returned when the error condition occurs, if any. Set this attribute to an object that conforms to the Parameter schema, above, and has type "object".

Attribute: attachments Required:N Type:object

File attachments that will be returned when the error condition occurs. Set this attribute to an object that conforms to the Attachments schema, above.

Schema: Creator Information

Create an object that conforms to this schema to include details of the service creator in the definition in a structured way.

Attribute: name Required:N Type:string

Name of the organisation that created the service definition.

Attribute: api_url Required:N Type:string

URL at which the service description document is published. The service description should be different to the service definition. The service definition is the formal JSON file, the service description should be a document that is easy to read. Set this attribute to a value that could be used as the target of a link in an HTML page. Omit this attribute if there is no published service description document.

Attribute: copyright Required:N Type:string

Copyright notice for the service definition. Set this attribute to a short form of copyright notice, for example "(c) 2017 BlackBerry Limited. All rights reserved."

Attribute: contact_details Required:N Type:string

Personal contact details for the individual that wrote the service definition, and to whom questions should be addressed. This could include a home page, email address, phone number or any other details that the individual is comfortable to share.