Definition

The definition API is used by vehicles to query the system for release metadata and instructions on how to obtain and apply the software.

Definition request

The definition request structure and an example are given below.

Definition request header

The table below provides the fields required in the header of a definition request.

Field Required Type Description Example Value(s)
protocol yes Object Metadata about the protocol that is being used. N/A
protocol.name yes String A name key that identifies the protocol. Definition
protocol.version yes String The version of the protocol that is being used. 4.0.0
protocol.type yes String The type of the protocol. Possible values are:
  • REQUEST - Indicates this is a request to the server.
  • RESPONSE - Indicates this is a response from the server to the client.
 REQUEST
tenantId yes String The identifier of the tenant that this endpoint belongs to. example_tenant
deviceId yes String The unique identifier for the device on the given tenant. 1XKADP9X7CJ328889
sourceId yes String The originating source of the request. ENDPOINT
sessionId yes String A client-generated value that should uniquely identify a series of transactions that are related to each other. 1220320-231ffw

Definition request body

The table below provides the fields required in the body of a definition request.

Field Required Type Description Example Value(s)
endpointProfileChecksum yes String This checksum is the same as provided in the registration. This value indicates the profile of the device. asdlfujh982fuaoij3rjfadhgfoia
directives yes Object This structure contains information and directives that will guide the infrastructure in how to process the transaction. N/A
directives.packagePatching no Object The structure allows the client to specify if it wants delta patches or now. N/A
directives.packagePatching.type no String The type of patching to use. The default value is BLACKBERRY. BLACKBERRY
directives.packagePatching.allow yes Boolean Tells the infrastructure whether patching is allowed. TRUE
directives.currentBearer no Object Information about the current bearer that the endpoint is on. This is used for network restriction features. N/A
directives.currentBearer.type yes String The type of data connection used by the client for requests. The value must be one of the following:
  • WIRED - Indicates that the endoint is tethered.
  • WIFI - Indicates that the endpointis connected via a WIFI access point.
  • BLUETOOTH - Indicates that the endpoint is tethered via Bluetooth.
  • 2G - Indicates that the device is communicating over a 2G cellular connection.
  • 3G - Indicates that the device is communicating over a 3G cellular connection.
  • 4G - Indicates that the device is communicating over a 4G cellular connection.
 4G
directives.currentBearer.cellTowerId no String An identifier for the currently used cell tower (only applicable when using cellular transport). ATT-Cell-192
directives.releaseResolution no String How the system should process multiple available releases. The value must be one of the following:
  • LATEST_PACKAGES - All applicable releases are merged into a single release with the latest and greatest packages available.
  • LATEST_RELEASE - The latest and greatest release will be made available.
  • AVAILABLE_RELEASES - All the available releases will be presented in the response.
 LATEST_PACKAGES
directives.pollInitiationType yes String The reason the Definiton protocol was initiated. The value must be one of the following:
  • AUTO - Endpoint automatically querying in on a timed interval.
  • TRIGGER - A condition or state change on the device triggered the event.
  • MANUAL - The user initiated the update check manually.
  • PUSH - Definition initiated due to notification from the server.
 AUTO
directives.includeKeepOperations no Boolean It can be helpful to include keep operation in the response from the server but it can also add a lot of overhead. This option will allow clients to specify how verbose the response should be. TRUE
queryCriteria no Array A listing of the constraints the endpoint wants to impose on the resulting packages and releases that are returned. N/A
queryCriteria.scope no String The scope of the results. The value must be one of the following:
  • RELEASE - Checks release scope attributes.
  • PACKAGE - Checks package scope attributes.
 RELEASE
queryCriteria.queryString yes String A string conforming to the Query Grammar that specifies criteria on which packages or releases to return. """version > \""4.0.0.0\"""""

Definition request URL

POST https://ps.dcms.blackberry.com/dmps/definition/4.1.0

Definition request example

Definition_Request

Definition response

The following depicts the definition response structure.

Definition response header

The table below provides the fields required in the header of a definition response.

Field Required Type Description Example Value(s)
protocol yes Object Metadata about the protocol that is being used. N/A
protocol.name yes String A name key that identifies the protocol. Definition
protocol.version yes String The version of the protocol that is being used. 4.0.0
protocol.type yes String The type of the protocol. Possible values are:
  • REQUEST - Indicates this is a request to the server.
  • RESPONSE - Indicates this is a response from the server to the client.
 RESPONSE
tenantId yes String The identifier of the tenant that this endpoint belongs to. example_tenant
deviceId yes String The unique identifier for the device on the given tenant. 1XKADP9X7CJ328889
sessionId yes String A client-generated value that should uniquely identify a series of transactions that are related to each other. 1220320-231ffw
status.code yes String A server-generated code that indicates the result of sending the request to the server. 0
status.message yes String A message that correlates to the status code and provides additional information about the code. Success

Definition response body

The table below provides the fields required in the body of a definition response.

Field Required Type Description Example Value(s)
releases no Array A block that contains the information for all of the requested releases. N/A
releases.category yes String The category of the release. FULL
releases.version yes String The version number of the release within the given category. 10.0.0.123
releases.revision yes Integer The revision of the release version within the given category. 1
releases.releaseProperties no Array A block that contains all of the properties defined for the software release in the backend system. N/A
releases.releaseProperties.key yes String The key of the property. model_year
releases.releaseProperties.value yes String The value of the property. 2016
releases.allowedBearers no Array The allowed bearers specify on a per carrier basis which kinds of connections are allowed for the download.  Since payload may be returned in the definition response, it is important for the bearers to be specified ahead of the definition transaction. WIFI
releases.transports no Array A listing of the possible transports used to download content and the priority of each transport. The endpoint should attempt to retrieve the content in the order specified by the server. N/A
releases.transports.ordinal yes Integer The priority order of the transport. 1 is the highest priority. Priority decreases in ascending order of the ordinals. 1
releases.transports.value yes String The type of transport. The value must be one of the following:
  • LOCAL STORAGE: The content resides on the endpoint itself. This could happen when content is preseeded in the factory.
  • ETHERNET: A standard hardwired Ethernet connection.
  • WIFI: A WI-FI access point.
  • CELLULAR: Any kind of cellular connection.
  • BLUETOOTH: The device is tethered via Bluetooth.
 WIFI
releases.url no String The base URL of the package set. http://www.blackberry.com
releases.packages yes Array A listing of the packages which contain all information pertaining to a package. N/A
releases.packages.path no String The path from which to download. /example_tenant/ADAS_ ECU_2015.bar
releases.packages.downloadSize no Integer The size in bytes of the package to be downloaded. Not applicable if the package is provided in line. 23563
releases.packages.nodes no Array A listing of the target nodes that need to receive the package content. This listing will correspond to the nodes that were provided in the registration. N/A
releases.packages.nodes.id yes String The unique node identifier. ECUID200912345
releases.packages.nodes.operation yes String The action to perform on the package. The value must be one of the following:
  • ADD: Indicates that a package is to be added to the device that was not there before.
  • REPLACE: Indicates that there is a new version of a package available.
  • PATCH: Indicates that a patch is available for the source version of the package.
  • DELETE: Indicates that a package should be removed from the system.
  • KEEP: Indicates that package already exists and nothing needs to be done.
 ADD
releases.packages.manifest no String This is the manifest that the server recieves from the backoffice system for the packages when they are first uploaded to the system. It is a PACK Specification 1.7 JSON that has been encoded as a base64 string. bWFuaWZlc3Q=
releases.packages.inline no Object An object that contains inline package data. Inline package data are packages that are delivered directly, in response to a check for update; no download from a separate URL is required. N/A
releases.packages.inline.encoding yes String The encoding type of the inline content. base64
releases.packages.inline.content yes String The inline package content string. dGVzdA==
actions no Object A listing of the actions that the device is required to take. N/A
actions.repollInterval no Number The endpoint must perform another discovery request within the specified amount of time in seconds. 86400
actions.registrationRequired no Boolean The endpoint needs to register it's current state with the server because it's state has changed. FALSE
actions.bootstrapRequired no Boolean The endpoint needs to perform bootstrap again. FALSE

Definition Response Example

Definition_Response