Summary

This document provides some advanced context on the configuration of a Points of Interest (POIs) in MazeMap.

Advanced settings can be achieved in editing the JSON configuration on the poi import.

Prerequisites

Before modifying a POI import via the JSON configuration, ensure you have:

• Access to the MazeMap Admin Tool.

• Created a POI Import.

• A data source containing POI details that is structured correctly and accessible.

• An understanding of JSON structure.

MazeMap Import Configurations

MazeMap supports three primary types of POI imports:

Floorplan Label Configuration

• POIs in the import are matched against floor plan labels in the drawings and maps.

• Data is matched using the floor_plan_prefix and POI ID.

External ID Configuration

• POIs are matched with the external IDs provided in the import.

• Non-existing POIs will be created automatically if the latitude (lat), longitude (lng), and floor name are included.

Manual POI ID Configuration

• POIs in the import are matched against POI IDs manually created in the MazeMap Admin Tool.

• This configuration is only for manually created POIs and does not support automatic creation.

Recommendation: Use the External ID Configuration for programmatic updates to POI locations and information.

Explanation of JSON Configuration

MazeMap allows the importing of data through a structured configuration.

• Configuration is managed in a JSON configuration file located in the Admin Tool.

• To access the configuration:

  • From the POI menu, navigate to Import → Select the import

• For External JSON Imports, the JSON configuration can be edited directly.

• For Excel Imports, follow these steps:

  1. Click anywhere on the import.

  2. Press Escape.

  3. Type json, and the editor will load.

Important: After making changes, click the "Save Configuration" button in the bottom right-hand corner to apply updates.

Structure of the JSON Configuration

JSON Configuration Settings Explained

All column numbers referenced in the configuration are zero-based indexes (i.e., the first column is 0, the second is 1, and so on).

• Excel Imports: Columns are matched based on their position in the Excel file.

• JSON API Imports: Columns are extracted from the API response using columnJPaths, which must align with the JSON structure.

• Field Mapping: Ensure that the column numbers provided match the expected structure in the source data.

1. Import Type (type)

Defines whether the import is JSON (json_row) or Excel (row).

Example:

"type": "json_row"

• type: Type of Import

  • json_row for JSON API,

  • row for uploaded excel file.

2. Import Source (source)

This specifies the data source for the importt.

Example:

"source": 50

• source: Source of the import.

  • 50 for External JSON

  • 133 for Excel data

3. External JSON Import - Specific Configurations

3.1. Client Configuration (clientConfig)

Defines API request parameters.

Example:

"clientConfig": {
    "method": "GET",
    "headers": {
        "Content-Type": "application/json"
    },
    "params": {},
    "debug": "true"
}

Field Descriptions:

• method: GET or POST

• headers: API request headers.

• params: Additional API parameters.

• debug: Should remain "true".

3.2 URL (uris)

Defines the API endpoint for data import.

Example:

"uris": ["https://api.example.com/pois"]

3.3 Data Structure (rowConfig)

Defines how data is extracted from the API response.

Example:

"rowConfig": {
    "rowJPath": "$.imported_pois[*]",
    "columnJPaths": [
        "external_id",
        "floor_name",
        "lat",
        "lng",
        "text_on_map",
        "title",
        "description",
        "type",
        "searchable",
        "url",
        "url_text",
        "comment"
    ]
}

Field Descriptions:

• rowJPath: The JSON path to the POI data in the response.

• columnJPaths: The list of fields extracted from the API response.

Note: The fields must appear in the same order as they are in the API response.

4. Excel Data Import Specific Configurations

4.1. Data sheet (sheet)

Specifies which sheet to read in an Excel file (0-based index).

Example:

"sheet": 0,

4.2. Import Source (headerLines)

Specifies the row containing column headers, with 1 being the first row.

Example:

"headerLines": 1,

5. Identifier Sources (identifierSources)

This defines how POIs are matched or created based on the POI Import Configurations.

Floor Plan Label Example Configuration:

"identifierSources": [
    {
        "importSourceId": 126,
        "itemCol": 1,
        "floorCol": 0,
        "externalIdCol": null,
        "poiIdCol": null
    }
]

External ID Example Configuration :

Note: When using the External ID Configuration and there are POIs located inside, the additional floorNameColumn needs have the column number added.

"identifierSources": [
    {
        "importSourceId": 126,
        "itemCol": null,
        "floorCol": null,
        "externalIdCol": 1,
        "poiIdCol": null
    }
], 
"floorNameColumn": 1,

Manual POI ID Example Configuration:

"identifierSources": [
    {
        "importSourceId": 126,
        "itemCol": 1,
        "floorCol": 0,
        "externalIdCol": null,
        "poiIdCol": null
    }
]

Field Descriptions:

• importSourceId: Data source ID

  • 50 for External JSON,

  • 126 for Floor Plan Parsing / Manually Created.

• itemCol: Needed for Floorplan Label Configuration or null

• floorCol: For External ID Configuration containing the floor prefix or null.

• externalIdCol: For Manual POI ID Configuration - Column containing an external ID or null.

• poiIdCol: For Manual POI ID Configuration - the column with the corresponding PO ID or null.

6. POI Naming & Categorisation (poiInfo)

Determines how POI names and types are assigned.

6.1 Setting POI Names

• Use nameCol and assign a column number.

• Set priority at 20.

6.2 Setting POI Title

• Assign nameCol and a column number.

• The lowest priority value determines the title.

6.3 Setting POI Types

• Use typeCol to define POI types.

• Set priority at 20.

Example:

"poiInfo": [
    { 
      "nameCol": 1, 
      "priority": 5 
    },
    { 
      "nameCol": 2, 
      "priority": 20 
    },
    { 
      "nameCol": 3, "priority": 20 
    },
    { 
      "typeCol": 4, "priority": 20 
    }
]

Field Descriptions:

• nameCol: Column containing a name.

• priority: Lower values take precedence for setting the POI title.

• typeCol: Column defining the POI type.

7. POI Data (poiData)

This section is reserved for future use and should be left blank.

Example:

"poiData": []

8. Map Display Text (markers)

Defines what text appears on the map.

Example:

"markers": [
    { 
      "textCol": 2, 
      "priority": 15
      "joinPriority": 20,
      "comment": null 
    }
]

Field Descriptions:

• textCol: Column containing the text for the map.

• priority: set at 15

• joinPriority: set at 20

• comment: leave as null

9. Customer POI Identifiers (identifierNames)

Allows setting custom POI identifiers for integration with external systems.

Note: This field does not make this information searchable. If searching by identifierNames is needed, also add the identifier as a nameCol under poiInfo to make it searchable.

Example - Set:

"identifierNames": [
    {
        "itemCol": 0,
        "comment": null
    }
],

Example - Not Set:

"identifierNames": []

Field Descriptions:

• itemCol: Column containing the customer’s unique identifier.

• comment: set as null.

10. Created Point POI locations (geoCoordinates)

When using the External ID Configuration the location of the POI is derived from geoCoordinates.

Note: If some of the POIs are located indoors, floorNameColumn must be set to the column that contains the floor name.

Example:

"geoCoordinates": [
  {
    "latCol": 1,
    "lngCol": 2
  }
],

Field Descriptions:

• latCol: Column containing the latitude.

• lngCol: Column containing the longitude.

11. POI Information - URL (richPoiUrlColumn)

Defines the column in which the URL for POI details is located.

Example:

"richPoiUrlColumn": 5

12. POI Information - URL Text (richPoiUrlTextColumn)

Defines the column containing the text for a POI URL.

Example:

"richPoiUrlTextColumn": 6

13. POI Information - Description (richPoiDescriptionColumn)

Defines the column containing the text for the description for a POI.

Example:

"richPoiDescriptionColumn": 4

14. POI Information - PeopleCapacity(peopleCapacityColumn)

Defines the column for the occupancy for a POI.

Example:

"peopleCapacityColumn": 6

15. Floor Name Column (floorNameColumn)

When using the External ID Configuration import, this must be set to the appropriate column ID or null.

Example:

"floorNameColumn": 7

16. External References (externalReferencesColumn)

References for external system integration.

A single external reference has the format ‘type;vendor;value’. It is possible to have multiple external references per room. Multiple external references should be separated by the forward-slash character ( / ). Some external references may contain the forward-slash character so as a rule of thumb, each external reference should be url-encoded. 

E.g.   Given the following external references,

• room_booking;google;

• room_booking;outlook;

• room_booking;time_edit;

• room_booking;office_app;

• room_booking;planon;

• occupancy_senso;iaconnects;

• occupancy_sensor;johnsoncontrols;

• occupancy_sensor;iotspot;

• occupancy_sensor;sensorapi;

• occupancy_sensor;dnaspaces;

• occupancy_sensor;planon;

• library_shel;alma;

• webex;webex;

• link_insertion;outlook;

• ellucian;ellucian;

Each of them should be url-encoded like so...then separated by forward slashes ( / )

• occupancy_sensor%3Biaconnects%3BA%2FB%2FC%2FD

Example:

"externalReferencesColumn": 10

Encoded Example:

occupancy_sensor%3Biaconnects%3BA%2FB%2FC%2FD

This prevents issues with forward slashes / in values.

Conclusion

Configuring POI imports using advanced JSON settings in MazeMap allows for greater flexibility and automation. To ensure a successful setup, follow these key principles:

• Understand Data Matching: Column references use zero-based indexing, and values must align with the correct data structure from the API response or Excel sheet.

• Choose the Right Import Type: Use External JSON for API-based imports or Excel for file-based imports. Ensure source is correctly set (50 for JSON, 133 for Excel).

• Customize Data Extraction: Configure rowConfig for JSON imports to correctly map fields, or set headerLines and sheet for Excel imports.

• Define POI Matching Rules: Use identifierSources to determine how POIs are created or updated, whether by external ID, floor labels, or manually assigned POI IDs.

• Optimize POI Information: Configure poiInfo to set searchable names, titles, and types, ensuring correct categorization and display.

• Handle External System Integration: Use externalReferencesColumn to link POIs with external booking systems, occupancy sensors, or asset tracking solutions.

• Test & Validate Imports: Run sample imports in staging environments to verify correct mapping before applying changes to production.

By leveraging these advanced settings, you can create a scalable and automated POI import process that integrates seamlessly with external data sources. If you encounter any issues, refer to MazeMap’s support documentation or contact technical support.

Example JSON Configurations

Example - External JSON - Floorplan Label

{
    "type": "json_row",
    "source": 50,
    "clientConfig": {
        "method": "POST",
        "headers": {
            "Content-Type": "application/json"
        },
        "params": {},
        "debug": "true"
    },
    "uris": [
        "uris": ["https://api.example.com/pois"]
    ],
    "rowConfig": {
        "rowJPath": "pois",
        "columnJPaths": [
            "floor_prefix",
            "room_id",
            "text_on_map",
            "title",
            "description",
            "type",
            "searchable",
            "url",
            "url_text",
            "comment"
        ]
    },
    "identifierSources": [
        {
            "importSourceId": 50,
            "itemCol": 1,
            "floorCol": 0,
            "externalIdCol": null,
            "poiIdCol": null,
            "comment": 9
        }
    ],
    "poiInfo": [
        {
            "nameCol": 1,
            "priority": 20,
            "comment": null
        },
        {
            "nameCol": 2,
            "priority": 20,
            "comment": null
        },
        {
            "nameCol": 3,
            "priority": 15,
            "comment": null
        },
        {
            "nameCol": null,
            "typeCol": 6,
            "priority": 20,
            "comment": null
        }
    ],
    "poiData": [],
    "markers": [
        {
            "textCol": 2,
            "priority": 20,
            "joinPriority": 20,
            "comment": null
        }
    ],
    "identifierNames": [],
    "richPoiUrlColumn": 7,
    "richPoiUrlTextColumn": 8,
    "richPoiDescriptionColumn": 4,
    "peopleCapacityColumn": null,
    "externalReferencesColumn": null
}

Example - External JSON - External ID Configuration - Internal POI and External POIs

{
    "type": "json_row",
    "source": 50,
    "clientConfig": {
        "method": "POST",
        "headers": {
            "Content-Type": "application/json"
        },
        "params": {},
        "debug": "true"
    },
    "uris": [
        "uris": ["https://api.example.com/pois"]
    ],
    "rowConfig": {
        "rowJPath": "pois",
        "columnJPaths": [
            "external_id",
            "floor_name",
            "lat",
            "lng",
            "text_on_map",
            "title",
            "description",
            "type",
            "searchable",
            "url",
            "url_text",
            "comment"
        ]
    },
    "identifierSources": [
        {
            "importSourceId": 50,
            "itemCol": null,
            "floorCol": null,
            "externalIdCol": 0,
            "poiIdCol": null,
            "comment": 11
        }
    ],
    "poiInfo": [
        {
            "nameCol": 4,
            "typeCol": null,
            "priority": 20,
            "comment": null
        },
        {
            "nameCol": 5,
            "typeCol": null,
            "priority": 15,
            "comment": null
        },
        {
            "nameCol": null,
            "typeCol": 7,
            "priority": 20,
            "comment": null
        },
        {
            "nameCol": 8,
            "typeCol": null,
            "priority": 20,
            "comment": null
        }
    ],
    "poiData": [],
    "markers": [
        {
            "textCol": 4,
            "priority": 20,
            "joinPriority": 20,
            "comment": null
        }
    ],
    "identifierNames": [],
    "geoCoordinates": [
        {
            "latCol": 2,
            "lngCol": 3
        }
    ],
    "richPoiUrlColumn": 9,
    "richPoiUrlTextColumn": 10,
    "richPoiDescriptionColumn": 6,
    "peopleCapacityColumn": null,
    "floorNameColumn": 1,
    "externalReferencesColumn": null
}

Example - External JSON - External ID Configuration - External POIs only.

{
    "type": "json_row",
    "source": 50,
    "clientConfig": {
        "method": "POST",
        "headers": {
            "Content-Type": "application/json"
        },
        "params": {},
        "debug": "true"
    },
    "uris": [
        "%link_to_api_call%"
    ],
    "rowConfig": {
        "rowJPath": "%i%ocation_of_POI_data_in_response%",
        "columnJPaths": [
            "external_id",
            "lat",
            "lng",
            "text_on_map",
            "title",
            "description",
            "type",
            "searchable",
            "url",
            "url_text",
            "comment"
        ]
    },
    "identifierSources": [
        {
            "importSourceId": 50,
            "itemCol": null,
            "floorCol": null,
            "externalIdCol": 0,
            "comment": 10
        }
    ],
    "poiInfo": [
        {
            "nameCol": 3,
            "typeCol": null,
            "priority": 20,
            "comment": null
        },
        {
            "nameCol": 4,
            "typeCol": null,
            "priority": 15,
            "comment": null
        },
        {
            "nameCol": null,
            "typeCol": 7,
            "priority": 20,
            "comment": null
        }
    ],
    "poiData": [],
    "markers": [
        {
            "textCol": 3,
            "priority": 20,
            "joinPriority": 20,
            "comment": null
        }
    ],
    "identifierNames": [],
    "geoCoordinates": [
        {
            "latCol": 1,
            "lngCol": 2
        }
    ],
    "richPoiUrlColumn": 8,
    "richPoiUrlTextColumn": 9,
    "richPoiDescriptionColumn": 5,
    "peopleCapacityColumn": null,
    "floorNameColumn": null,
    "externalReferencesColumn": null
}

Example - External JSON - Manual POI ID

{
    "type": "json_row",
    "source": 50,
    "clientConfig": {
        "method": "POST",
        "headers": {
            "Content-Type": "application/json"
        },
        "params": {},
        "debug": "true"
    },
    "uris": [
        "%link_to_api_call%"
    ],
    "rowConfig": {
        "rowJPath": "pois,
        "columnJPaths": [
            "poi_id",
            "text_on_map",
            "title",
            "description",
            "type",
            "searchable",
            "url",
            "url_text",
            "comment"
        ]
    },
    "identifierSources": [
        {
            "importSourceId": 50,
            "itemCol": null,
            "floorCol": null,
            "externalIdCol": null,
            "poiIdCol": 0,
            "comment": 8
        }
    ],
    "poiInfo": [
        {
            "nameCol": 2,
            "typeCol": null,
            "priority": 15,
            "comment": null
        },
        {
            "nameCol": null,
            "typeCol": 4,
            "priority": 20,
            "comment": null
        },
        {
            "nameCol": 5,
            "typeCol": null,
            "priority": 20,
            "comment": null
        },
        {
            "nameCol": 1,
            "typeCol": null,
            "priority": 20,
            "comment": null
        }
    ],
    "poiData": [],
    "markers": [
        {
            "textCol": 1,
            "priority": 20,
            "joinPriority": 20,
            "comment": null
        }
    ],
    "identifierNames": [],
    "geoCoordinates": [],
    "richPoiUrlColumn": 7,
    "richPoiUrlTextColumn": 8,
    "richPoiDescriptionColumn": 3,
    "peopleCapacityColumn": null,
    "floorNameColumn": null,
    "externalReferencesColumn": null
}

These examples can be modified based on the POI data you are importing.