Dealing With Hierarchical Data

Maximo Asset Management has many hierarchical objects, such as Locations, Workorders, Assets, Failure codes, etc and there are subtle differences between each of these hierarchies.

The location hierarchy is always scoped under the LOCSYSTEM object. Effectively, a given location can belong to multiple systems, and hence different hierarchies. The API is designed where the list of systems that is available for the user is first with the hierarchy under the scope of that system.

For example, you can get a list of systems for the MXAPILOCSYSTEMobject structure by using the following API:

With this API, you go to the top (root) location under that system and select the system that you want to drill down using the href of the system record. The following API call shows how to do that:

Here toplevelloc is the name of the relation from LOCSYSTEM to LOCATIONS table. The object structure name is added to the relation name to get the response as the MXAPIOPERLOC os. This helps to jump from one object structure to the other using the rest APIs.

To drill down under that top level location, you can use the href of the location object and append the relation name syschildren with the object structure mxapioperloc (to keep within the context of the mxapioperloc OS). The following API shows this format:

The a query parameter ctx is also used with the value of systemid=<systemid> for the system that is being drilled down into. This is needed because a location can belong to multiple systems and hence multiple hierarchies. So when drilling down into the hierarchy, the systemid context is required.

You can take any of the locations in the response and drill down by following the API described in the previous example. Always remember to set the ctx query parameter with the right systemid or the API defaults to the primary system for that location for the drill down.

These collection responses can be filtered, sorted, or paged just like any otheOSos query response. So if you are building a tree structure in the UI using these APIs, you can introduce a sorting or filtering function at each tree node (which is a location).

General Ledger (GL) component hierarchies provides another flavor of hierarchies in Maximo Asset Management. The general ledger account consists of segments (gl components), which follow a certain hierarchy as defined in the chartofaccounts and glcomponents table. The glcomponents table defines all the components and their gl order. To specify a general ledger account, you need an API to find the segments in a hierarchical way (following the gl order). The following APIs describes how to find segments:

The response for this API is a list of GL segments at the top level, that is GL order 0. For each of the records, you can look for the childcompref URI. If you do a GET on that URL, you get the child records for that segment. Note that the JSON also has a responseInfo that provides some metadata about the current segment (glsegmentcurrent) as well as the total number of segments (glsegmentcount). The glcompsofar describes the account that has been selected so far. At the start, the metacharacters ? (as configured) and the segment separators to represent the account are used. The GET on the childcompref would look like the following API call:

The collection of records you get would be the next set of segments that are valid for the segments selected so far as described in the glcomp query parameter value. Note the glcomp query parameter value is updated to point to the next set of segments. Internally, the | separator for the segments are used and hence the childcompref URL for the third set of segments look like

You can also specify the glcompsofar value to drill down too as shown in the following API call:

Note the use of glvalue query parameter to get the values. This will give the exact same results as the glcomp=comp0|comp1 api call.

As is the case with the other hierarchies, you can sort (oslc.orderBy) and filter (oslc.where) bu using these APIs.