The CSV Source Connector allows you to take exports from your building systems and import them into your Mapped graph via CSV file. The Connector's configuration wizard will guide you step by step, from selecting and uploading your file, to mapping the data to the correct Site, to aligning the rows in the CSV with the fields in the Mapped graph.

Schema

The schema for the CSV Connector is as follows:

Building

• buildingAddress
• buildingRefId (optional)
• buildingName (optional)
• latitude/longitude (optional, but required if address validation is disabled)
• Address must be validated

Floor (optional)

• floorRefId (optional)
• floorLevel (required if Floor is included)
• floorName (required if Floor is included)

Space (optional)

• spaceRefId (optional)
• spaceName (required if Space is included)
• spaceCode (required if Space is included, must be unique per spaceRefId)
• Must relate to a Floor

Zone (optional)

• zoneRefId (required if Zone is included)
• zoneName (optional)
• zoneExactType (optional, defaults to ZONE)
• Must be associated with a Building, Floor or Space

Thing (optional)

• thingRefId (required if Thing is included)
• thingName (required if Thing is included)
• Must be located based on Building, Floor or Space
• If a Zone is present, the Thing serves that Zone

Point (optional)

• pointRefId (required if Point is included)
• pointName (strongly recommended)
• pointUnit (optional)
• pointExactType (optional, defaults to POINT)
• pointValue (required if pointTimeStamp is included, must be numeric int or float)
• pointTimeStamp (required if pointValue is included)
• Must be associated with a Thing, Zone, Space, Floor, or Building

Business Rules

There are a number of rules that control the process of importing data via a CSV file:

Address Validation

Building address is always required, so the connector can either map to an existing building or create a new one. The building address is validated by an address validation service that automatically finds the latitude and longitude based on the address. If the address validation cannot find a longitude and latitude with the provided address, the import may fail at this step or automatically change the address to a valid one.

⚠️ If a connector contributes a new address for an existing Building, this will create a duplicate. ⚠️

Address validation may be disabled under the Advanced Config tab, but in that case latitude and longitude values must be provided.

RefIds

• Each entity includes requires a RefId. The RefId should be unique within the scope of the imported sheet. If you select to add an org-scoped identities to a Building, Floor, Space, Zone, Thing or Point, keep in mind that these entities will merge with any other entity that shares that same identity scoped to the org-level. Read more on Identities at Mapped.

Hierarchy

The data follows a hierarchy of requirements: Point requires a Thing, Thing requires a Space or a Floor, Space requires a Floor.

Relationships

• A Thing can only have one location, so it can only be mapped to one Space or one Floor.
• A Space can only be mapped to one Floor.
• A Floor cannot be mapped to more than one Building.

Values

• A Point requires both a Point Value and a Point Timestamp, if it has either.
• Floor Level and Point Value must be a valid number; we do not currently support other types for Point Values.

Other Considerations

• Larger datasets may be cumbersome for the connector - if your CSV contains over 500 unique devices, consider breaking it up into multiple import files.
• After you submit your CSV, our system will import the data in the background. You are free to return to the Mapped Console after submission, and can see the data populate via the Explorer Grid View.
• When importing Floors, be consistent in the floor-level indexing to ensure Floors merge correctly without duplicates. A Floor named "Level 01" can have floor.Level 1 or floor.Level 0, but if it has both this will result in duplicate Floors of the same name.
• ⚠️ Automatic address validation may edit the building address from what you have entered it in the CSV. In order to avoid changing the building's address from what is entered in your file, disable address validation in the Advanced Config tab by setting Disable Address Validation to true and saving. ⚠️

Config

Site Options

On the Site Options tab, select the Site to which you wish to add this data and Save.

Advanced Config

The Advanced Config tab lets you enable or disable several default options on the CSV connector.

• Add Org Scoped Identities - Building: If set to true, this uses the building.RefId value to add an identity to the building scoped to the entire organization. If true, the Building will merge with any other Building that shares the same org-scoped identity. If false or not selected, this identity remains scoped to the connector only.
• Add Org Scoped Identities - Floor: If set to true, this uses the floor.RefId value to add an identity to the Floor scoped to the entire organization. If true, the Floor will merge with any other Floor that shares the same org-scoped identity. If false or not selected, this identity remains scoped to the connector only. Additional Note: Floors merge on the floorLevel value when scoped to the same Building.
• Add Org Scoped Identities - Space: If set to true, this uses the space.RefId value to add an identity to the Space scoped to the entire organization. If true, the Space will merge with any other Space that shares the same org-scoped identity. If false or not selected, this identity remains scoped to the connector only. Additional Note: Spaces merge on the spaceCode value when scoped to the same Floor.
• Add Org Scoped Identities - Zone: If set to true, this uses the zone.RefId value to add an identity to the Zone scoped to the entire organization. If true, the Zone will merge with any other Zone that shares the same org-scoped identity. If false or not selected, this identity remains scoped to the connector only.
• Add Org Scoped Identities - Thing: If set to true, this uses the thing.RefId value to add an identity to the Thing scoped to the entire organization. If true, the Thing will merge with any other Thing that shares the same org-scoped identity. If false or not selected, this identity remains scoped to the connector only.
• Add Org Scoped Identities - Point: If set to true, this uses the point.RefId value to add an identity to the Point scoped to the entire organization. If true, the Point will merge with any other Point that shares the same org-scoped identity. If false or not selected, this identity remains scoped to the connector only.
• Disable Address Validation: If set to true, the automatic address validation is disabled, and latitude and longitude will be required. Setting this option to true will prevent automatic address validation from making any changes to the address value.
• Invert Space Zone Relationship

Select Save after you have made any changes.

Mapping

In the Mapping tab, upload your CSV or XLSX file to the CSV importer wizard. If there are multiple sheets in your XLSX file, you will be prompted to select the name of the sheet you wish you upload and Continue. Next, the wizard will allow you to change or confirm the headers of your file then Continue.

Then, the next step will let you change or confirm how the columns in your file fit the wizard template. Hover over each line to preview your data and select Continue. Next, you can review and finalize the data before selecting to Import. At this point, automatic address validation occurs if not disabled.

Finally, you can review the record(s) imported and select Submit to save. At any point before selecting Submit, you may navigate away and then select Start Over when you return in order to cancel the import and submission.