Customer Meta Data Ė Group Relocation API

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.

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.

 

API Summary Details

API Name

Customer Meta Data API

Endpoint

https://fim.api.us.fleetmatics.com/cmd/v1/groups

Operation

POST

 

POST Group to Group ID

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Ē,
}

 

POST Group to Group ID Request Header

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 Group to Group ID Sample Response

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