Importing Device Locations

This topic provides additional details related to importing legacy device locations from a demand response management system (DRMS) into Digital Asset Management / Digital Asset Cloud Service.

Device Location Import File Format

Legacy device location import files use the following tab-separated values format:

Field Name

Optional/Required

Notes

Legacy Device Location Id

Required

The id for the device location in the DRMS application.

Device Location Type

Required

The device location's type. This must be a valid device location type defined in Digital Asset Management / Digital Asset Cloud Service. See Understanding Device Location Types for more information.

CIS Metered Service Point

Required

The id for the metered service point associated with the device location in the CIS application.

Ok To Enter

Optional

A value that indicates if it is okay for field service crews to enter the device location. Valid values are values defined for the Ok to Enter (D1-OkToEnterLookup) extendable lookup.

SP Warning

Optional

A value that indicates any warnings for field service crews when at the device location (such as a dog). Valid values are values defined for the SP Warning (D1-SPWarningLookup) extendable lookup.

SP Instruction

Optional

A value that provides any special instructions for field service crews when at the device location. Valid values are values defined for the SP Instruction (D1-SPInstructionLookup) extendable lookup.

SP Instruction Details

Optional

A text string containing any additional details related to the SP Instruction value.

Key

Optional

A value that indicates if a key is available for field service crews when at the device location. Valid values are values defined for the Key (D1-KeyLookup) extendable lookup.

Key Id

Optional

A text string containing any additional details related to a key.

Device Location

Optional

A value that indicates the location of the controllable device at the device location. Valid values are values defined for the Device Location (D1-DeviceLocationLookup) extendable lookup.

Device Location Details

Optional

A text string containing any additional details related to the device location.

Device List

Optional

A concatenated list of controllable devices current installed at the device location.

Each row in this list is composed of the following:

  • Legacy Device Id (Required)

  • Attach Date Time (Required)

  • Remove Date Time (Optional)

  • Active/Inactive Indicator (D1YS/D1NO)  (Required)

Each element in the row will be delimited by comma ( , ).

Each row in the list will be delimited by semi-colon ( ; ).

Example:

DVC1,2022-12-13T14:30:00-05:00,,D1YSDVC2,,2022-12-13T14:30:00-05:00,D1YS;

Sample Record

Below is a sample file:

EXTDVCLOC1    ZZ-MUYU    EXTMSP1    ZZNO    DOG    C    service point instruction details    ZZ1    key1    LEFT    DeviceLoc1 details    ACTIVE    EXTDVC1,2022-11-09T09:23:00-05:00,2023-04-15T14:04:00-05:00,D1YS;

Upload Batch Process

Legacy device location import files are uploaded using the Legacy Device Location File Upload (X1-DLUPL) batch process. Use the Batch Control portal to view the parameters used by this batch process. This process should be run as needed for the initial import. 

This process creates inbound sync requests in the "Pending" state (see below).

The Legacy Device Location File Upload - DACS (X1LGDVLOCUPL) algorithm used by this batch process uses the following extendable lookups to map data in the import file to values defined in Digital Asset Management / Digital Asset Cloud Service:

  • Ok to Enter (D1-OkToEnterLookup)

  • SP Warning (D1-SPWarningLookup)

  • SP Instruction (D1-SPInstructionLookup)

  • Key (D1-KeyLookup)

  • Device Location (D1-DeviceLocationLookup)

Values must be defined for these extendable lookups before device location import files can be uploaded into Digital Asset Management / Digital Asset Cloud Service.

Inbound Sync Request Business Object

Controllable device inbound sync requests are based on the Device Location Initial Sync Request (X1-DASyncReqDeviceLocation) business object.

Inbound sync requests are created in the "Pending" state. The Sync Request Monitor (F1-SYNRQ) batch process is used to transition these to the "Transform/Validate" state where the data is validated and transformed as needed for import and moved into the "Validated" state (or "Validation Error" if an error is encountered). These are processed by an "Initial Sync Request Load" batch process (see below).

Initial Sync Request Load Batch Process

Legacy controllable devices are created from inbound sync requests using the Initial Sync Request - Load Device Location (X1-SILDL) batch process. Use the Batch Control portal to view the parameters used by this batch process. This process should be run as needed for the initial import.

This process transitions the inbound sync requests to the "Loaded" state.

Create Asset Locations from Device Location Batch Process

The Create Asset Location from Device Location (X1-CRASL) batch control is used to create asset locations from newly uploaded device locations. 

This process uses the following algorithms:

  • Select Records - Device locations without an asset location (node) (X1SLNOASTLOC): This algorithm selects device locations where the legacy device location ID is populated, but the Asset service point ID is empty. 

  • Process Record - Create Asset Location (Node) - DACS (X1CRASSETLOC): This algorithm creates asset locations from data in the Device Location Initial Sync Request (X1-DASyncReqDeviceLocation) inbound sync requests created for each device location.

This process uses the following parameters:

  • Default Out of Service Location: The out of service location used when creating controllable assets if state-specific out of service locations are not defined. (Required)

Use the Batch Control portal to learn more about these and other parameters used by these batch process.