-
Notifications
You must be signed in to change notification settings - Fork 6
Location
- CREATE and UPDATE operations are supported.
- DELETE operations are not supported for locations. But you can use the LocationDeleter.exe tool for that.
Column Header | Example value | Description |
---|---|---|
LocationIdentifier | 05JJ009 |
The text identifier for the location. |
LocationPath | WSC.SASKATCHEWAN.REGINA |
The folder path of the location |
LocationName | SALINE CREEK NEAR NOKOMIS |
A longer name of the location. |
LocationType | Hydrology Station |
The type of location |
UtcOffset | -06:00 |
The offset from UTC, in +HH:MM or -HH:MM format. |
Description | The underpass near Hatfield Road. |
A long description of the location |
Latitude | 51.41611 |
WGS84 latitude. |
Longitude | -105.10306 |
WGS84 longitude. |
Elevation | 504.5 |
Elevation of the location. |
ElevationUnits | m |
Units for elevation. |
Publish | false |
A true or false flag controlling the publish status of the location. |
UniqueId | b2c1b04f9e0547e7a23f9709137ddc7d |
This column is ignored in CREATE tasks, but can be used in UPDATE tasks. You can use either the UniqueId or LocationIdentifier column to specify the location whose other properties will be updated. If both columns are used, UniqueId takes precedence. |
UpdatedIdentifier | 05JJ009_OLD |
This column is ignored in CREATE tasks, but can be used in UPDATE tasks to change the identifier text of a location when the column value is not an empty string. |
Tag:{key} | Column headers beginning with "Tag:" followed by the key of the tag can be used to assign a tag value to a location. The tag must be configured with AppliesToLocations = true in order to set a value for the location. | |
Ext:{key} |
REGINA for Ext:Office
|
Column headers beginning with "Ext:" followed by the key of the extended attribute can be used to assign an extended attribute value to a location. The extended attribute must be configured with AppliesToLocations = true or AppliesToLocationTypes = true in order to set a value for the location. |
The same CSV file format for the -Task="CREATE Location CreateLocations.csv"
task can also be used for the -Task="UPDATE Location UpdateLocations.csv"
task. But the CSV shape of an UPDATE task can be much thinner, only needing to supply one column to select a location, plus one column for each property to update.
The UPDATE LOCATION task needs a CSV with at least a LocationIdentifier or UniqueId column, plus any other columns of the location to be updated. Any columns not included in the CSV will not be modified.
Notes:
- You cannot update the
UtcOffset
column of an existing location. When the-Task='UPDATE Location pathToCsv'
task is used, theUtcOffset
column will be ignored if it exists in the CSV file. - When all the column values match the current location's property values, no change will be made to the location. A location will only be modified when at least one property value is changed.
The ProvisioningTool supports the setting of any configured tag or extended attribute values. These values are identified by column names beginning with the Tag:
or Ext:
prefix. The appropriate tag or extended attribute key name follows the colon.
Assume there are four extended attributes which can be set on a location:
CSV column header | Extended attribute display name | Example value |
---|---|---|
Ext:Province |
Province |
SASKATCHEWAN |
Ext:Office |
Office |
REGINA |
Ext:User |
User |
SUSAN.SMITH |
Ext:Status |
Status |
ACTIVE |
Also assume these two Location tags have been configured (with AppliesToLocations
applicability):
CSV column header | Tag Key | Tag Type | Example value |
---|---|---|---|
Tag:Watershed |
Watershed |
PickList |
Fraser basin |
Tag:Has Telemetry |
Has Telemetry |
None |
any value - The tag will be set. empty - The tag will be removed. |
The None
tag type is slightly special. These tags don't have any value. They are simply applied to an item or they are absent from an item.
If the CSV cell is not empty, then the tag will be set, otherwise it will be removed from the item.
Here is an example CSV, with a header row and two location rows:
LocationIdentifier, LocationPath, LocationName, LocationType, UtcOffset, Description, Latitude, Longitude, Elevation, ElevationUnits, Publish, Ext:Province, Ext:Office, Ext:User, Ext:Status, Tag:Watershed, Tag:Has Telemetry
05JJ009, WSC.SASKATCHEWAN.REGINA, SALINE CREEK NEAR NOKOMIS, Hydrology Station, -06:00, The underpass near Hatfield Road., 51.41611, -105.10306, -105.10306, m, false, SASKATCHEWAN, REGINA, SUSAN.SMITH, ACTIVE, , YUP
08GA047, WSC.BRITISH COLUMBIA.NANAIMO, ROBERTS CREEK AT ROBERTS CREEK, Hydrology Station, -08:00, Where the bridge crosses the road, 49.42083, -123.64022, 15.3, m, false, BRITISH COLUMBIA, NANAIMO, FRANK.FROLLIC, ACTIVE, Fraser basin
Note that the Yup
value for the Tag:Has Telemetry
column could have been any non-blank value. Values of Yes
, 1
, OK
, or I am a teapot
all have the same effect.
An existing location can have its identifier changed using the -Task="UPDATE Location pathToCsv"
task.
This section describes a few different ways a location can be renamed. The example CSVs have been trimmed down to the fewest required columns for clarity, but keep in mind that you can update all the attributes of a location with one CSV if you need to.
Three different columns supported by the UPDATE task will determine if a location's identifier will be updated:
-
LocationIdentifier
,UniqueId
, andUpdatedIdentifier
. - When the
UniqueId
column exists and has a non-empty value, its value will be used to select the existing location to update. - When the
UniqueId
column value is empty, or if the column doesn't exist in the CSV, then theLocationIdentifier
column value will be used to select the existing location to update.
The above rules yield two different CSV shapes which can be used to rename a location:
This CSV shape is often the simplest for renaming, Just specify the old identifer and the new identifier.
LocationIdentifier, UpdatedIdentifier
05JJ009, 05JJ009_OLD
1100031, RenamedLoc
This CSV shape requires using the AQTS REST API to pull the list of locations and their uniqueID values. The GET /AQUARIUS/Publish/v2/GetLocationDescriptionList
response has all the required pieces.
This shape is useful when you have already extracted the AQTS unique IDs and you know the new identifier values.
UniqueId, LocationIdentifier
b2c1b04f9e0547e7a23f9709137ddc7d, 05JJ009_OLD
729254bc35c84762a4fa829fa0f2f3ec, RenamedLoc
In this scenario, the rule of "UpdatedIdentifier
trumps LocationIdentifier
" kicks in. CSVs with this shape will be essentially ignoring the LocationIdentifier
values completely, using the UniqueId
to find the existing location, and then using the UpdatedIdentifier
value as the location's new identifier.
UniqueId, LocationIdentifier, UpdatedIdentifier
b2c1b04f9e0547e7a23f9709137ddc7d, Can be anything, 05JJ009_OLD
729254bc35c84762a4fa829fa0f2f3ec, Does not matter, RenamedLoc