A guide to the API endpoints for accessing assets like machines and factories.
Please ensure you have completed the first guide to gain an API key and access the interactive API docs before beginning this guide.
Introduction
The FourJaw data is always filtered by asset - you might be looking at the utilisation of a single machine or the downtime within an entire factory.
Either way, when making a request to the API, we must include in the request which asset we want the data for. This is always done by passing an asset ID to the API.
Fortunately, every asset in FourJaw has an ID and we can use the Asset Endpoints to retrieve those IDs.
Revisiting the hierarchy
The assets in FourJaw are structured as a hierarchy. For example in the structure below, there are 5 levels: Organisation, Factory, Area, Cell and Machine. In your business these levels might be called different things, for example production "Lines" commonly replace "Cells in some businesses.
This structure is already defined in your existing FourJaw dashboard under Settings > Assets. The API won't change this structure, but you will be able to query it and get an ID for any asset in the hierarchy.
Getting all assets
To retrieve the full asset hierarchy from the API, first navigate to the interactive API docs, as discussed in this guide.
When the docs have loaded, use the lefthand menu to navigate to Assets > Get assets
Enter your API Key in the top right and press "Send API Request".
The response you get back will show each asset with the following data:
id: The unique identifier for this asset - this will be used in other queries (e.g. utilisation)
display_name: The name for this asset, e.g. "Packaging Line 1" or "Unit 2".
level_name: The level of this asset in your hierarchy e.g. "Factory" or "Machine. See the section above "Revisiting the hierarchy" to understand how the levels work.
children: A list of direct descendants in the asset hierarchy. For example, in the diagram found above within "Revisiting the hierarchy", the "Machining" Area would have two entries in the list of children, the "Milling" Cell and the "Turning" Cell.
Using asset ids
Most of the time, you will simply use the asset hierarchy to find the asset ids. These are essential as all other API calls require an asset id to be specified as a parameter.
You can use the interactive API docs to find the id of any asset you are interested in. For example, in the screenshot below I have a factory called "Unit 1" with the following id: "6572f4b000ca569294368285".
Important: when using the asset id in API requests, never include the quotation marks.
Copy and paste the id of an asset in preparation for the next section.
Using an asset id as an API request parameter
Using the lefthand menu, navigate to "Get an asset by ID".
In the box on the right you'll need to enter your API key, and there is another input for the asset id. Paste in your chosen id from the previous section and press "Send API Request".
In the response you will see the details of the asset you chose. Please note there will also be all the children of your chosen asset returned as well. You are effectively getting the hole branch of the asset hierarchy below your chosen asset.
If you chose the id of a machine, you'll only get a single entry as machines have no child assets.
Getting all assets at a particular level
The final asset endpoint allows you to get all assets at a particular level, for example, everything at the "Factory" level. To try this functionality, use the lefthand menu to navigate to "Get an asset by level name".
On the resulting page, you'll use the input box in the top right to enter the level name you are interested in. The level names will be those seen throughout this guide, and match exactly to the level names in your FourJaw dashboard under Settings > Assets.
In this case, the levels are configured as "Organisation", "Factory", "Area", "Cell", "Machine".
That's it! you're all done for this tutorial and now have everything you need to work with the asset hierarchy and get asset ids.