Concept for filtering Shells based on timestamp

[tunacicek]

As a dataconsumer,
i want to retrieve only the shells that have been created since my last request
so that i dont have to fetch and process all the shells every time, enabling more efficient and resource-saving operations.

Notes

• clarify how the data can be included in the shell response (check if IDTA is applicable).
• Do we need to adjust the lookup API to make it searchable by timestamp?

Useful links
admin-shell-io/aas-specs-api#176

Outcome
concept-shell-timestamp-filter_0.0.1.md

Related issues
admin-shell-io/aas-specs-api#346
admin-shell-io/aas-specs#484

[tunacicek]

Filter Shell based on timestamp

Overview

Include createdAfter as query parameter allows consumers to filter results based on the timestamp of a shell's creation.

Database tables

1. Shell table

 TABLE shell (
    ...,
    created_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

API Design

Search by created after

A new query parameter createdAfter will be introduced to the shell API to allow for filtering by after 'created_date'.
The parameter will be optional and the format of the timestamp is 'RFC3339' and looks like YYYY-MM-DDTHH:MM:SSZ.

• GET /shell-descriptors?createdAfter=2021-01-01T00:00:00Z
• GET /lookup/shells?createdAfter=2021-01-01T00:00:00Z
• GET /shell-descriptors/{aasIdentifier}/submodel-descriptors?createdAfter=2021-01-01T00:00:00Z (Needs to be clarified)
• POST /lookup/shellsByAssetLink?createdAfter=2021-01-01T00:00:00Z (Needs to be clarified)

Extend Shell

A new parameter createdAt will be added to the shell object and will be returned.

{
  ...
  "id": "123",  
  "idShort": "model-b1",
  "specificAssetIds" : [],
  "createdAt": "2021-01-01T00:00:00Z",
  ...
}

Business logic

General workflow

When consumer sends a request with the createdAfter query parameter, the DTR handles the request by:

• Parsing the timestamp.
• Filtering the dataset to return only shells created after the specified timestamp.
• Returning the filtered shells/shell_ids.

When the createdAfter query parameter is not provided, the DTR returns all shells without filtering them by creation date.

Backward compatible (How to handle existing where created_date = NULL )

1. Solution: Migrate existing data

The created_date field in the shell table will be populated with the current timestamp for all existing shells that do not have a created_date value.

Impact on business logic:
The business logic remains as described above.

2. Solution: Handle created_date = NULL

When querying entries with the createdAfter parameter, entries with NULL in the creationDate field are ignored.

Example entries in Database:

Id	idShort	creationDate
1	Shell 1	NULL
2	Shell 2	2024-11-20
3	Shell 3	2010-05-10

1. Initial call (without parameters): Fetches all data, including entries with created_date = NULL.

[
  ...
  {

    "idShort": "shell 1",
    "creationDate": null
  },
  {
    "idShort": "shell 2",
    "creationDate": "2024-11-20"
  },
  {
    "idShort": "shell 3",
    "creationDate": "2010-05-10"
  }
  ...
]

2. Call with the createdAfter =2024-11-19 parameter: Fetches all entries after the createdAfter date. Entries with `reated_date = NULL are excluded

[
  ...
  {
    "idShort": "shell 2",
    "creationDate": "2024-11-20"
  }
  ...
]

[BirgitBoss]

For metadata like creationDate, updateDate etc. please request new attributes for AssetAdministrationShellDescriptor/administration of type AdministrativeData, this will be more future proof

However: creationDate of AssetAdministrationShellDescriptor needs not to be identicial with creationDate of the AssetAdministrationShell itself. Same for Submodel and SubmodelDescriptor.
Although AssetAdministrationShellDescriptor/administration is suggesting that it is the administration information for the descriptor: it is not (it is "copy/paste" from AAS attributes).

Besides this I would always use Extensions in case metamodel extensions are required but not yet in place -this is what extensions are introduced for. With this we stay 100% compatible to AAS Specifications.