The Customer Meta Data (CMD) Group Relocation API is a RESTful web service that enables customers to integrate 3rd party back-office systems to change the group hierarchy within a REVEAL account.
Important concepts to understand prior to utilizing any of the available integration methods:
· The customer Meta Data (CMD) Group Relocation API is offered as a RESTful web service
· Standard REST verbs are applied: POST
· Throughout this document, we will reference the unique identifier to be invoked for each of the main objects available to be created or deleted. The unique identifiers used within this API method set include:
o Group ID
o Parent Group ID
The Customer Meta Data API is separated out into different services that have a variety of methods that can be accessed to create, update, and delete key objects within a REVEAL account.
Note: This document
specifically reviews the Customer Meta Data API’s method for enabling
integration users with the ability to move groups within an account and the
impact this will have.
The returned response
will be restricted to the Reveal account's data plan. If the information being
queried is outside of the data plan, a "400 Bad Request error
"response will be returned.
For more details on
your account's data plan please reach out to Verizon Connect Customer Support
|
API Name |
Customer
Meta Data API |
|
Endpoint |
https://fim.api.us.fleetmatics.com/cmd/v1/groups |
|
Operation |
POST |
The POST Group to a Group ID enables integration users with the ability to pick a designated group that already exists within a REVEAL account and move it under a new Parent Group ID. In order to successfully move groups within an account, all groups must have a Group ID as a unique identifier.
Before moving groups within a REVEAL account, it is important to understand the impact moving groups may have on the account. Verizon Connect will not be responsible for the reversal of groups that are moved within an account via the API.
The Parent Group
ID is the new Group ID where group(s) will be moved to within the REVEAL
tree. The moved group or groups will
then be considered child groups of the Parent Group ID.
When moving the
nominated Group ID within the REVEAL tree via the API, the Group’s identification
value must be provided within the API request.
The nominated group’s unique ID value can be provided by utilizing the
“Id” field within the POST Group to Group ID method’s request body. If the nominated Group ID has any child
groups, the child groups will also be moved under the Parent Group ID in the
same cascading order.
There are several business rules to be aware of when moving a group within REVEAL, regarding the impact on users within the REVEAL account:
1. Users that had inherited access to the group specified to be moved may lose access following the move. Users with access to the Group ID’s current Parent Group will lose access due to a new Parent Group ID being specified for that group.
2. Users that have direct access to the moved group, who did not have access to the group’s previous Parent Group, will maintain access to the group following the group move.
3. Users may inherit access to the moved group if they have access to the group’s new Parent Group ID.
The business rules that apply to users and their associations may impact various areas of REVEAL, i.e. Alert Policies and recipients, and Scheduled Reports and recipients.
The following request header along with the Group ID content body information demonstrates how the call should be invoked to a move a group. The URL should contain the new Parent Group ID where the group will be moved.
{
“Id”: “Group to be moved Group Id”,
}
|
Operation and Path |
POST https://fim.api.us.fleetmatics.com/cmd/v1/groups/<GroupID>
HTTP/1.1 |
|
HOST |
fim.api.us.fleetmatics.com |
|
Accept |
application/json |
|
Authorization |
Atmosphere
realm=http://atmosphere,atmosphere_app_id=<Fleetmatics Integration Manager
App ID>, Bearer <token> Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls. |
POST methods will not return an object review. The response will be limited to a set of standard HTTP codes:
· Successfully edited vehicles will return a 200 code
· Unfound Vehicle Numbers, or the unique identifier used for the call, will return a 404 error
· Bad requests, typically due to an error in the call’s content, will return a 400 error
· Invalid tokens or an Authorization problem will return a 401 error
· If the service is unavailable at the time the call was made a 500 error will return