Data Loader

About the Geographic Information System (GIS) Data Loader

The GIS Data Loader allows geospatial data associated with existing APM entities to be imported into the GIS data model, so that information about the entities can be displayed in the Maps module in APM. You can load geospatial data using the provided Excel workbook.

About the GIS Data Loader Requirements

To use the GIS Data Loader, you must have existing entity records, for example, the Functional Locations or Equipment, that you want to associate with the geospatial data. To use the geospatial data in the Maps module, your organization must have completed the GIS Configuration steps.

Mapping

The GIS Data Loader inserts geospatial data in the MI_ENTY_GEO_DATA table and associates it with existing entities in APM. Entities are identified by mapping from specified cells in the Excel workbook to the ENTITY_KEY field. The data loader evaluates the data provided in the Excel workbook in the following order:

ENTITY_KEY + FAMILY_ID
ENTY_ID + FAMILY_ID
FAMILY_ID + ID_FIELD + ID

Note: The column positions in the spreadsheet should not be moved and the captions should not be changed.

Note: If data is not provided, the cell should be left empty.

About the GIS Data Loader Data Model

The following data model illustrates the records that the Data Loader supports.

GIS Data Loader Data Model

Note: In the diagram, GIS Location refers to the name of a database table. You can relate each GIS Location to an Entity of any family in APM. Geometry represents the actual data for GIS Location. The Has Entity and Has Geometry are not relationship families defined in APM. They are the relationships in an internal database and the purpose is same as the relationships between entity families.

About the GIS Data Loader General Loading Strategy

The imported data must load in a specific sequence to successfully populate fields, create records, and link data to the predecessor and successor records.

Best Practices

When importing data using the GIS Data Loader, you must use the following Best Practices:

To identify an existing record to associate with the geospatial information, use one of the following options:
- Specify the ENTITY_KEY and FAMILY_ID values.
- Specify the ENTITY_ID and FAMILY_ID values. If ENTITY_KEY is not provided, the data loader will search for the ENTITY_KEY matching the ENTITY_ID.
- Specify the FAMILY_ID, ID_FIELD, and ID values. If ENTITY_KEY and ENTITY_ID are not provided, the data loader will search for an ENTITY_KEY matching the specified values.
If there is no existing record for the referenced Entity Key in the MI_ENTY_GEO_DATA table, and you provide valid geospatial data, a new record will be created in the MI_ENTY_GEO_DATA table.
If there is an existing record for the referenced Entity Key in the MI_ENTY_GEO_DATA table, and you provide new valid geospatial data, the existing record in the MI_ENTY_GEO_DATA table will be updated.
If there is an existing record for the referenced Entity Key in the MI_ENTY_GEO_DATA table, and you provide no geospatial data (i.e. the cell is empty), the record will be deleted from the MI_ENTY_GEO_DATA table.
If the identifying values (i.e. either ENTY_ID + FAMILY_ID or FAMILY_ID + ID_FIELD + ID) provided in the worksheet match more than one entity record, the record in the MI_ENTY_GEO_DATA table will be associated with the first matching entity record that is found. If this occurs, a warning will be added to the import log.
Geospatial data in the GEOD_DATA column should conform to the geometry spatial data type.
Note: Valid geospatial data format is dependent on your APM database type. Points must specify Longitude first, then Latitude, in degrees. For example, the geospatial data for a point in Roanoke, Virginia, USA is defined as. POINT (-79.9372289704512 37.2698054035023) in SQL Server 2016.

Load Sequence

When importing data using the data loader workbook, you must use the following workflow:

Download the data loader workbook provided by GE Vernova.
Identify the data requirements for exporting the data into the data loader workbook.
Extract data from APM and your GIS applications to populate the data loader workbook.
Provide batch numbers in the first column of the worksheet in the data loader workbook.
Import data into APM.
Monitor the status of the data load, and verify the results in the log.
Conduct tests in APM to ensure that the imported data loaded accurately.

For each row in the data loader workbook, the GIS Data Loader will insert, update. or delete a row in the geospatial data table in the APM system.

About the GIS Data Loader Workbook Layout and Use

In order to import data using the GIS Data Loader, APM provides an Excel workbook, Geographic Information System (GIS).xlsx, which supports the Maps tool in APM. This workbook must be used to perform the data load.

The following table lists the worksheets that are included in the GIS Data Loader workbook.


Worksheet	Description
GIS	The only worksheet used by the GIS Data Loader. It is used to load geospatial data for existing entities.

The following table lists the fields in the workbook:

GIS Worksheet


Field Caption	Field ID	Data Type (Length)	Comments
Batch ID	BATCH_ID	Character (50)	You must specify a Batch ID for each row in the worksheet.
Entity Key	ENTITY_KEY	Numeric	You can use this column to specify the Entity Key field of the APM entity that you want to associate with the GIS data.
Entity ID	ENTITY_ID	Character (255)	You can use this column to specify the Entity ID of the APM entity that you want to associate with the GIS data.
Family ID	FAMILY_ID	Character (50)	You must specify the Family ID of the APM entity that you want to associate with the GIS data.
Family ID Field	ID_FIELD	Character (50)	You can use this column to specify the Field ID of the field which will be used to identify the APM entity record that you want to associate with the GIS data.
ID	ID	Character (255)	You can use this column to specify the identifying value in the Family ID Field of APM entity record that you want to associate with the GIS data.
Geometry	GEOD_DATA	Character (4000)	You can use this column to specify the GIS data to be associated with the APM entity. If this column contains a null value, any existing GIS data associated with the APM entity will be deleted.

About the GIS Data Loader Load Verification

About This Task

After loading data, you must perform the following steps in APM to ensure the integrity and accuracy of the data imported from the data loader workbook:

Review the details of the import job. These details will indicate if any errors or warnings occurred during the data load. The log helps you identify any records that are not loaded.
Run a query to view the geospatial data that was uploaded. You can use the baseline Map Query that is stored in the \\Public\Meridium\Modules\Core\Queries\Map Queries\ folder, as a reference.