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

## Begin of the deletion 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).

##End of the deletion File Begin of the insertionlinkEnd of the insertion Begin of the deletion (link)End of the deletion resources

Begin of the insertion`FileLink`End of the insertion Begin of the deletion `File`End of the deletion resources in OpenProject describe links between resources in OpenProject Begin of the insertion(first workEnd of the insertion Begin of the deletion (workEnd of the deletion packages, Begin of the insertionmaybe in the futureEnd of the insertion wiki pages, etc.) and their representation in a file store, i.e. a file in Nextcloud or in a Google Drive.

Begin of the insertion## GET all file links to work packages of project a project from a certain file storeEnd of the insertion Begin of the deletion ### Example:End of the deletion

Begin of the insertionExample:End of the insertion _"Get all Begin of the insertionfile links linkingEnd of the insertion Begin of the deletion files linkedEnd of the deletion 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`GET /api/v3/file_links?filters=[{"resource_type":{"operator":"=","values":["WorkPackage"]}},{"project_id":{"operator":"=","values":["5"]}},{"file_store":{"operator":"=","values":["1"]}}]`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":[""]}}]`End of the deletion

This will return a collection of file reference resources.

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

},
"_type" : Begin of the insertion"FileLink"End of the insertion Begin of the deletion "File"End of the deletion
},
{
...another file Begin of the insertionlinkEnd of the insertion
}
]
}

},
```

## Begin of the insertionGET workEnd of the insertion Begin of the deletion WorkEnd of the deletion packages that are related to Begin of the insertionfile linkEnd of the insertion Begin of the deletion a Nextcloud "fileid"End of the deletion

To query all work packages that are linked to a Begin of the deletion NextcloudEnd of the deletion file you need to apply the filter Begin of the insertion`originId`End of the insertion Begin of the deletion `nextcloudFileid`End of the deletion to the `work_packages` API endpoint. Begin of the insertion ThisEnd of the insertion Begin of the deletion TheEnd of the deletion filter allows only one operator `=` and multiple Begin of the insertionIDsEnd of the insertion Begin of the deletion `fileid`sEnd of the deletion as Begin of the insertionvalues, for example in case of a Nextcloud storage the IDs are Nextclouds `fileid`s.End of the insertion Begin of the deletion values.End of the deletion

Begin of the deletion ###End of the deletion Example: Begin of the deletion

End of the deletion _"Get all work packages that are Begin of the insertionlinkedEnd of the insertion Begin of the deletion relatedEnd of the deletion to Begin of the insertiontwo certain files with their original IDs being 1234 and 1235."_End of the insertion Begin of the deletion a Nextcoud_ `_fileid_`_"_End of the deletion

Begin of the insertionAttention:End of the insertion 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`GET /api/v3/work_packages?filters=[{"originId":{"operator":"=","values":["1234","1235"]}}]`End of the insertion Begin of the deletion `/api/v3/work_packages?filters=[{"nextcloudFileid":{"operator":"=","values":["00001234","00001235"]}}]`End of the deletion

This will return a collection of work package resources.

## Begin of the insertion**GET file linksEnd of the insertion Begin of the deletion **FilesEnd of the deletion that are related to a work package**

Begin of the insertionFor displayingEnd of the insertion Begin of the deletion To queryEnd of the deletion all Begin of the insertionlinks to allEnd of the insertion Begin of the deletion linkedEnd of the deletion files Begin of the insertionnext to a work package, for example in a "Nextcloud" tabEnd of the insertion of a work Begin of the insertionpackage, we need to be able to query all file links linking to a work package.

Example: _"Get me all files that are linked to workEnd of the insertion package Begin of the insertion1."_

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.

`GET /api/v3/file_links?filters=[{"container_type":{"operator":"=","values":["WorkPackage"]}},{"container_id":{"operator":"=","values":["1"]}}]`

## CREATE a file link

To create a link between a file and a work package we need make a POST request, containing the storage ID, the original file ID (i.e. Nextcloud's `fileid`) and the work package ID.

Example: "Create a link between work package 2 and file 1234 in storage 1."

`POST /api/v3/file_links`

with payload

```json
{
"storageId" : 1,
"originId" : 1234,
"workPackageId" : 2
}
```

The return value will be the created `FileLink` resource as described above.

## DELETE a file link

Example: _"Delete file link with ID 1."_

`DELETE /api/v3/file_links/1`

## Nice to have: UPDATE origin data of a file link

It might be necessary to offer a way to update the origin data of a file link as files attributes could change at its origin, such as its file name, mime type, last modified timestamp and the name of the person that last modified the file. However, I am not sure if we will really need it in the first version.End of the insertion