Importing Controllable Devices

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

Controllable Device Import File Format

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


Field Name	Optional/Required	Notes
Legacy Device Id	Required	An id for the controllable device in the DRMS application.
Device Type	Required	The controllable device's type. This must be a valid controllable device type defined in Digital Asset Management / Digital Asset Cloud Service. See Understanding Controllable Asset Types for more information.
Serial Number	Optional	The controllable device's serial number.
Badge Number	Optional	The controllable device's badge number.
NIC ID	Required	The controllable device's Network Identification Card (NIC) ID.
Head End Registration	Optional	A flag that indicates if the controllable device is registered in the head end system. Valid values are values for the Head-End Registration Status (HEAD_END_REGISTR_STATUS_FLG) lookup, and include: D1RE - Registered D1NR - Not Registered D1DR - Deregistered
Legacy Device Date Time	Required	The controllable device's asset disposition date and time. This will be one of the following: In-Store Date Time: Date and time when the asset came into the storeroom/warehouse or when asset was removed from the location. Retire Date Time: Date and time when the asset was expired. Repair Date Time: Date and time when the asset came into the repair shop
Specification	Required	The specification associated with the controllable device. This must be a specification defined in Digital Asset Management / Digital Asset Cloud Service
Asset Ownership	Optional	A flag that indicates the controllable device's ownership. Valid values are values for the Asset Ownership (ASSET_OWNERSHIP_FLG) lookup, and include: W1CO - Customer Owned W1OW - Utility Owned
Asset Status	Required	A value that indicates the current status of the controllable device. Valid values include: INSTORE INREPAIR RETIRED

Sample Record

Below is a sample file:

EXTDVC3    ZZ-MUYU    SERIALNBR3    BADGENBR3    NICID3    D1NR    2023-04-23T12:22:00-05:00    ZZ-MUYU-CD-SPEC    W1CO    INSTORE

Upload Batch Process

Legacy controllable device import files are uploaded using the Legacy Controllable Device File Upload (X1-DVUPL) 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).

Inbound Sync Request Business Object

Controllable device inbound sync requests are based on the Controllable Device Initial Sync Request (X1-DASyncReqControllableDevice) 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 Controllable Device (X1-SILDV) 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 Controllable Asset from Controllable Device Batch Process

The Create Controllable Asset from Controllable Device (X1-CRAST) batch control is used to create controllable assets from newly uploaded controllable devices. This process should be run as needed for the initial import.

This process uses the following algorithms:

Select Records - Controllable Devices without an asset id (X1-SLNOASSET): This algorithm selects controllable devices where the legacy device ID is populated, but the Asset ID is empty.
Process Record - Create Controllable Asset - DACS (X1CREATASSET): This algorithm creates controllable assets from data in the Controllable Device Initial Sync Request (X1-DASyncReqControllableDevice) inbound sync requests created for each controllable device.

This process uses the following parameters:

Default Out of Service Location: The fallback out of service location used when creating controllable assets if other state-specific out of service locations are not defined. (Required) Note that controllable asset types must be configured with the appropriate device location types for each these states. See Understanding Controllable Asset Types for more information.
In Store Out of Service Location: The out of service location when creating controllable assets in the "In Store" state.
InRepair Out of Service Location: The out of service location when creating the controllable assets in the "In Repair" state.
Retired Out of Service Location: The out of service location when creating the controllable assets in the "In Store", "In Repair" or "Retired" state.

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

Note: Because a controllable asset's disposition includes a device location, and device locations are imported after importing controllable devices, controlled devices that currently "Installed" are imported in the "In Store" state. Their status will be corrected when the device locations are imported.