Results with Structure

Sometimes, you'd like to know the structure of the assets in the selector, not just their identity.

The map endpoint works just like the normal selector endpoint, but includes quite a bit of additional detail on how the assets in your selector are related.

 http://<myardiserver+site>/selector/api/map?query=Water System}:@Pump

Along with the normal information, you may get one or more maps, which are arrays of asset details that describe how your results are connected.

Let's look at an example from our Paint Line example, when asking for everything inside our Finish Oven (Finish Oven}:)

 {
  "matches": [
      {
          "id": 100,
          "name": "Finish Oven Zone 1"
      },
      {
          "id": 101,
          "name": "Finish Oven Zone 2"
      },
      {
          "id": 102,
          "name": "Finish Oven Zone 3"
      }
  ],
  "maps": {
      "Location": [
          {
              "id": 99,
              "name": "Finish Oven",
              "parents": [],
              "base": true
          },
          {
              "id": 100,
              "name": "Finish Oven Zone 1",
              "parents": [
                  99
              ]
          },
          {
              "id": 101,
              "name": "Finish Oven Zone 2",
              "parents": [
                  99
              ]
          },
          {
              "id": 102,
              "name": "Finish Oven Zone 3",
              "parents": [
                  99
              ]
          }
      ],
      "Coil": [
          {
              "id": 100,
              "name": "Finish Oven Zone 1",
              "parents": [],
              "base": true,
              "sortorder": true
          },
          {
              "id": 101,
              "name": "Finish Oven Zone 2",
              "parents": [
                  100
              ]
          },
          {
              "id": 102,
              "name": "Finish Oven Zone 3",
              "parents": [
                  101
              ]
          }
      ],
      "Visualisation": [
          {
              "id": 210,
              "name": "Basic Control Infographic",
              "parents": [],
              "base": true
          },
          {
              "id": 100,
              "name": "Finish Oven Zone 1",
              "parents": [
                  210
              ]
          },
          {
              "id": 101,
              "name": "Finish Oven Zone 2",
              "parents": [
                  210
              ]
          },
          {
              "id": 102,
              "name": "Finish Oven Zone 3",
              "parents": [
                  210
              ]
          }
      ]
  },
  "orders": {
      "Coil": [
          100,
          101,
          102
      ]
  }
 }

The matches property contains the normal array returned from the selector.

The maps property has several items inside, each of which represents one of the relationships that all of the selected assets have in common. In this case, the items are all included in several different relationships.

Location tells us that all assets are inside the Finish Oven. Visualisation tells us that each of those oven zones can be seen in a dashboard display called the Basic Control Infographic. Coil tells us that the assets are in a sequence from Zone 1 to Zone 3.

Finally, the orders property suggests a suitable display order for the selected assets. In this example, it's suggested that we display them in coil order - Finish Oven Zone 1, Zone 2 and then Zone 3.

While this might be a little obvious in this case, there are many times when the ideal order isn't so obvious. The orders section can help make any reporting or visualisations you create much more readable to your users by displaying data in an more 'organic' way.

There are two options for the map URL.

Turning off the others option allows you to remove any assets that aren't in the selection from the map, with the exception of the 'root' asset (the asset that is common to the relationship). This allows you to 'filter out' all unnecessary assets when performing analytics that don't require them. 'Others' defaults to true, use others=false in your URL to hide the unselected assets.

singlepar tells the endpoint to only provide a single parent for each relationship. This is provided for compatibility with systems that demand 1:1 relationships, but please note that using the option is not advised unless you're confident that you don't - and will not - have any relationships where two upstream assets feed a single down-stream one. Use singlepar=true in your URL to use single-parent mode.