# This specification is "Work in progress" and is not yet finished.

## Nextcloud file identifiers in OpenProject

In Nextcloud every file has an `id` and a `fileid`. The `id` differentiates a file from another within the same Nextcloud instance. The `fileid` in contrast is globally unique as it is a composition of the unique Nextcloud instance ID and the file's `id`. More information on this [here.](https://help.nextcloud.com/t/difference-between-id-and-fileid-in-webdav/91414) In OpenProject we use the `fileid` as we might want to support multiple Nextcloud instances in the future and still want to have a simple way to query on them. By using the `fileid` we only need one value to identify a file and not two (file id and instance id).

## File (link) resources

`File` resources in OpenProject describe links between resources in OpenProject (work packages, wiki pages, etc.) and their representation in a file store, i.e. a file in Nextcloud or in a Google Drive.

### Example:

_"Get all files linked to work packages in project 5 that are stored in file store 1"_

For readability reasons we chose to show the URL params not URL encoded in this example. The params must be URL encoded first if you want to use them in a real example.

Begin of the insertion`/api/v3/files?filters=[{"resource_type":{"operator":"=","values":["WorkPackage"]}},{"project_id":{"operator":"=","values":["5"]}},{"file_store":{"operator":"=","values":[""]}}]`End of the insertion Begin of the deletion `/api/v3/files?filters=[{"resource_type":{"operator":"=","values":["WorkPackage"]}},{"project_id":{"operator":"=","values":["5"]}},{"file_store":{"operator":"=","values":["1"]}}]`End of the deletion

This will return a collection of Begin of the insertionfile reference resources.

```json
{
"_type" : "collection",
"count" : 2,
"total" : 2,
"_embedded" : {
"elements" : [
{
"id" : 1,
"storageType" : "nextcloud",
"storageId" : "5502",
"originData" : {
"createdAt" : "2021-12-20T13:37:45Z",
"lastModifiedAt" : "2021-12-20T14:27:01Z",
"authorName" : "Manuel Müller",
"lastModifiedByName" : "Christina Bolz",
"path" : "/documents/images",
"fileName" : "picture_1.png",
"mimeType" : "image/png",
},
"_links" : {
"self" : {
"href" : "/api/v3/files/1",
"title" : "picture_1.png"
},
"downloadLocation" : "https://mynextcloud.com/..."
"staticDownloadLocation" : "/api/v3/files/1/download",
"preview/thumbnail/..." : "/api/v3/files/1/preview",
"origin" : "https://mynextcloud.com/index.php/apps/files/?fileid=5502",
"author" : {
"href" : "/api/v3/users/3145",
"title" : "Richard Wolf",
},
"delete" : {
"href" : "/api/v3/files/1",
"method" : "delete"
},
"container" : {
"href" : "/api/v3/work_packages/22",
"title" : "AwesomeEnd of the insertion work package Begin of the insertionwith file references"
}

},
"_type" : "File"
},
{
...another file
}
]
}

},
```End of the insertion Begin of the deletion resources.End of the deletion

## Work packages that are related to a Nextcloud "fileid"

To query all work packages that are linked to a Nextcloud file you need to apply the filter `nextcloudFileid` to the `work_packages` API endpoint. The filter allows only one operator `=` and multiple `fileid`s as values.

### Example:

_"Get all work packages that are related to a Nextcoud_ `_fileid_`_"_

For readability reasons we chose to show the URL params not URL encoded in this example. The params must be URL encoded first if you want to use them in a real example.

`/api/v3/work_packages?filters=[{"nextcloudFileid":{"operator":"=","values":["00001234","00001235"]}}]`

This will return a collection of work package resources.

## **Files that are related to a work package**

To query all linked files of a work package