collection of use cases

Use Case 1: user and items thing

Use case 1.1: Which item is associated with which user?

• [x] PY see here
• [x] R see here

input:

• user email or
• user firstname and lastname

Per API: Search for all items of contact x, i) by (system) email address, ii) by contact names.

1. get /sensors/device/getItemsOfContact/{contactEmail} OR
2. get /sensors/contacts/getContactsByName/{firstName}/{lastName} --> email address will be output, then go on with step 1

Use case 1.2: Which items have the user x with a certain role?

• [x] PY see here
• [x] R see here

input:

• input from 1.1
• user role

1. von use case 1.1
   1. get /sensors/device/getItemsOfContact/{contactEmail} OR
   2. get /sensors/contacts/getContactsByName/{firstName}/{lastName} --> email address as output then go to step 1
2. get /sensors/contacts/getAllContactRoles --> pick out which ID is related to which role type (e.g. Data scientist="id": 29]
3. filter (role) ID-based
   • PI==True --> put to list
   • PI==False --> go on
   • ...

Use Case 2: write a certain event (e.g. info about calibration) to item xy

• [ ] PY
• [ ] R

input:

• item URN
• user credentials
• event infos

1. get /sensors/item/getItemByUrn/{urn} --> filter for "id"

2. create a usable token post [input] /sensors/contacts/login (input is a json holding username and password) --> response --> save token

3. get /sensors/events/getAllEventTypes --> filter for event type id for input in #5.5

4. create json for other input for #5

5. put /sensors/events/putEvent/{deviceID} + INPUT {

   1. "startDate": "2020-01-01T14:10:00",
   2. "endDate": "2020-01-01T14:10:00",
   3. "label": "Test",
   4. "description": "string",
   5. "eventType": 0,
   6. "longitude": 0,
   7. "latitude": 0,
   8. "elevationInMeter": 0,
   9. all children <- not part of the json body
   10. create version <- not part of the json body [TRUE/FALSE]

}

Use Case 3: create a list of all items of a platform that measure parameter xyz

• [x] PY see here
• [x] R see here

Precondition: only valid for current configuration. If the item was object to modifications (mounts) the results may differ.

input:

• top most item
• paramter type (e.g. salinity)

1. get https://sensor.awi.de/rest/sensors/item/getChildrenOfItem/{itemID}
2. get https://sensor.awi.de/rest/sensors/sensorOutputs/getAllSensorOutputTypes -> filter by i.e. regex "temp" (water temperature, technical temperature, etc. ...)
3. get https://sensor.awi.de/rest/sensors/sensorOutputs/getDeviceSensorOutputs/{itemID}

TODO: solve outputType is matching exactly but the response is not unique.... doh!

Use Case 4: adding/removing/modifying a parameter to item xyz

• [x] PY see here
• [ ] R

input:

• parental item ID
• some user added info, such as name and comment
• parameter id (derived from dict)
• unit id (derived from dict)
• (own) user credentials

1. token
2. get https://sandbox.sensor.awi.de/rest/sensors/sensorOutputs/getAllSensorOutputTypes -> filter
3. get https://sandbox.sensor.awi.de/rest/sensors/unitsOfMeasurement/getAllUnitsOfMeasurement -> filter
4. (if necessary) get https://sandbox.sensor.awi.de/rest/sensors/item/getItemByUrn/{URN} -> derive ID

add

1. put https://sandbox.sensor.awi.de/rest/sensors/sensorOutputs/putSensorOutput/{itemID} + INPUT {

   1. "name": "this is the long name, it can have blanks",
   2. "type_vocableID": 0,
   3. "itemID": 0,
   4. "unitOfMeasureID": 0,
   5. "shortName": "shortname_of_the_item",
   6. "comment": "optional comment"

}

modify

Possibly a look in the available output types/units is useful in advance, if these things shall be modified.

1. get sensorOutputs/getDeviceSensorOutputs/{itemID} -> use reply to fill new json

2. put sensorOutputs/modifySensorOutput/{outputID}/{itemID} + INPUT {

   1. "name": "this is the long name, it can have blanks",
   2. "type_vocableID": 0,
   3. "itemID": 0,
   4. "unitOfMeasureID": 0,
   5. "shortName": "shortname_of_the_item",
   6. "comment": "optional comment, but it is changed"

}

remove

1. delete sensorOutputs/deleteSensorOutputFromDevice/{outputID}/{itemID} -> done

Use Case 5: create a list for my item that holds necessary infos, such as 'parameter name', 'parameter type', 'unit' and comments', for a PANGAEA data publication.

• [x] PY see here
• [x] R see here

input:

• item id

1. getting all outputs from certain item: /sensors/sensorOutputs/getDeviceSensorOutputs/{deviceID} --> scrape all IDs to a list
2. iterate over list from 1. and obtain each parameter via /sensors/sensorOutputs/getSensorOutput/{parameterID} --> collect infos on
   • (short) name of parameter
   • parameter type
   • standardized/controlled vocabulary for parameter type (at best a NERC link)
   • unit
   • unit in ucum format
   • description of parameter
   • (user) comment on parameter
3. compile 2. to a dataframe
4. write to hd

Use Case 6: adding/removing a user with a certain role to an item

• [x] PY see here
• [x] R see here

input:

• (own) user credentials
• contact role of a user to be added/removed
• id of a user to be added/removed

1. post https://sensor.awi.de/rest/sensors/contacts/login
2. get https://sensor.awi.de/rest/sensors/contacts/getAllContactRoles
3. get https://sensor.awi.de/rest/sensors/item/getItemByUrn/
4. user id:
   1. direct input
   2. derived from mail
   3. from first and last name

add

1. put https://sensor.awi.de/rest/sensors/contacts/putExistingContactToDevice/{itemID}/{userID}/{contactRoleID}

remove

1. delete https://sensor.awi.de/rest/sensors/contacts/deleteContactFromDevice/{itemID}/{userID}/{contactRoleID}

Use Case 7: show all items (e.g. ctd) that measure a certain parameter type

• [ ] R
• [ ] PY

input:

Use Case 8: Which item types are available and how are they described

This procedures applies also to sensors/events/getAllEventTypes, sensors/sensorOutputs/getAllSensorOutputTypes, sensors/unitsOfMeasurement/getAllUnitsOfMeasurement, sensors/measurementProperties/getAllMeasurementPropertyTypes, and several more.

• [ ] R
• [x] PY see here

input:

• nothing required

1. get https://sensor.awi.de/rest/sensors/item/getAllItemCategories
2. combine all necessary information

Use Case 9: explore relevant, human-readable metadata fields of an item

• [ ] R
• [x] PY see here

input:

1. get https://sensor.awi.de/rest/sensors/item/getDetailedItem/{itemID}?includeChildren=true

compile parameter list

approach 1

1. map entries, such as output type, unit, etc. -> create lists
2. iterate and align information

approach 2

1. create id list of output items

2. get https://sensor.awi.de/rest/sensors/sensorOutputs/getSensorOutput/{sensorOutputID} -> create lists

3. export

make a list of all subitems

1. extract information of choice

For a complete list of all subitems (of all subitems of all subitems), make use of a while loop as in use case no. 3.

As altnerative approach the endpoint https://sensor.awi.de/rest/sensors/item/getChildrenOfItem/{itemID} could be facilitated as well.

Use Case 10: create a new item

• [ ] R
• [x] PY see here

input:

• (own) user credentials
• item type
• status type
• some infos about the item to be created

1. post https://sensor.awi.de/rest/sensors/contacts/login --> generate auth token
2. get https://sensor.awi.de/rest/sensors/item/getAllItemCategories --> item type ID
3. get https://sensor.awi.de/rest/sensors/item/getAllItemStatuses --> status code ID
4. put https://sandbox.sensor.awi.de/rest/sensors/item/createItem?parentItemID={parentItemID} --> create item

Use Case 11: reassign items

• [ ] R
• [x] PY see here

input:

• (own) user credentials
• unmount and mount dates
• target item ID
• source item ID

1. post https://sensor.awi.de/rest/sensors/contacts/login --> generate auth token
2. put https://sensor.awi.de/rest/sensors/itemReassignment/assignItemToItem/{itemID} + --> content json-body