Dokumente

Für die Bearbeitung einer Dokumentdatei muss auch via REST API der Checkin/Checkout workflow beachtet und eingehaltet werden.

Folgende Abfolge ist dabei vorgesehen:

  1. Checkout
  2. Lock
  3. Download
  4. Upload
  5. Unlock
  6. Checkin

Checkout - Dokument auschecken

Ein Dokument wird via @checkout Endpoint ausgecheckt.

POST /ordnungssystem/dossier-23/document-123@checkout HTTP/1.1
Accept: application/json
HTTP/1.1 204 No Content

Darf ein Dokument vom aktuellen Benutzer nicht ausgecheckt werden, so wird mit dem Status 403 Forbidden geantwortet.

POST /ordnungssystem/fuehrung/dossier-23/document-123@checkout HTTP/1.1
Accept: application/json
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "error": {
        "message": "Checkout is not allowed.",
        "type": "Forbidden"
    }
}

Lock

Um das Dokument von Schreibzugriffen von anderen Benutzern zu schützen muss es mittels Lock gesperrt werden.

Lock erstellen

POST /ordnungssystem/dossier-23/document-123/@lock HTTP/1.1
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json

{
  "creator": "peter.meier",
  "locked": true,
  "name": "plone.locking.stealable",
  "stealable": true,
  "time": 1477076400.0,
  "timeout": 600,
  "token": "0.684672730996-0.25195226375-00105A989226:1477076400.000"
}

Standardmässig haben Locks ein Timeout von 600s Sekunden und müssen anschliessend erneuert werden. Entweder sollten daher Locks periodisch erneuert werden oder man verwendet ein höheres Timeout:

Lock erneuern

POST /ordnungssystem/dossier-23/document-123/@refresh-lock HTTP/1.1
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json

{
  "creator": "peter.meier",
  "locked": true,
  "name": "plone.locking.stealable",
  "stealable": true,
  "time": 1477076400.0,
  "timeout": 600,
  "token": "0.684672730996-0.25195226375-00105A989226:1477076400.000"
}

Lock erstellen mit eigenem Timeout

POST /ordnungssystem/dossier-23/document-123/@lock HTTP/1.1
Accept: application/json

{
    "timeout": 86400
}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "creator": "peter.meier",
  "locked": true,
  "name": "plone.locking.stealable",
  "stealable": true,
  "time": 1477076400.0,
  "timeout": 86400,
  "token": "0.684672730996-0.25195226375-00105A989226:1477076400.000"
}

Datei aktualisieren

Für den Upload einer Datei unterstützt die REST API das sogenannte TUS Protocol. Eine detaillierte Dokumentation über die verschieden Möglichkeiten und Endpoints finden Sie in der plone.restapi Dokumentation.

Folgend ein kurzes Beispiel wie eine Datei eines bestehenden Dokumentes aktualisiert werden kann.

Upload URL erstellen:

POST /ordnungssystem/dossier-23/document-123/@tus-replace HTTP/1.1
Accept: application/json
Tus-Resumable: 1.0.0
Upload-Length: 8
Upload-Metadata: filename dGVzdC50eHQ=,content-type dGV4dC9wbGFpbg==
HTTP/1.1 201 created
Content-Type: application/json
location: ordnungssystem/ressourcen-und-support/personal/personalrekrutierung/dossier-4/document-2/@tus-upload/6cdfc5ddd1844e8cbca32721c4b17b84

Datei uploaden:

PATCH /ordnungssystem/dossier-23/document-123/@tus-upload/6cdfc5ddd1844e8cbca32721c4b17b84 HTTP/1.1
Accept: application/json
Tus-Resumable: 1.0.0
Upload-Offset: 0
Content-Type: application/offset+octet-stream

test data
HTTP/1.1 204 No content
Content-Type: application/json

Lock entfernen

Ein bestehendes Lock kann mittels @unlock Endpoint entfernt werden.

POST /ordnungssystem/dossier-23/document-123/@unlock HTTP/1.1
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json

{
    "locked": false,
    "stealable": true
}

Checkin - Dokument einchecken

Ein Dokument wird via @checkin Endpoint eingecheckt, dabei wird automatisch eine neue Version erstellt.

POST /ordnungssystem/dossier-23/document-123/@checkin HTTP/1.1
Accept: application/json

{
    "comment": "Kapitel 3 - 6 korrigiert."
}
HTTP/1.1 204 No content
Content-Type: application/json

Versionen auflisten:

GET /ordnungssystem/dossier-23/document-123/@history HTTP/1.1
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "@id": "/ordnungssystem/dossier-23/document-123/@history/1",
        "action": "Bearbeitet",
        "actor": {
            "@id": "http://localhost:8080/fd/@users/peter.meier ",
            "fullname": "Peter Meier",
            "id": "peter.meier",
            "username": "peter.meier"
        },
        "comments": null,
        "may_revert": true,
        "time": "2019-03-27T10:50:59.196843",
        "transition_title": "Bearbeitet",
        "type": "versioning",
        "version": 1
    },
    {
        "@id": "/ordnungssystem/dossier-23/document-123/@history/0",
        "action": "Bearbeitet",
        "actor": {
            "@id": "http://localhost:8080/fd/@users/hugo.boss",
            "fullname": "Hugo Boss",
            "id": "hugo.boss",
            "username": "hugo.boss"
        },
        "comments": "Dokument erstellt (Initialversion)",
        "may_revert": true,
        "time": "2019-03-27T09:19:25",
        "transition_title": "Bearbeitet",
        "type": "versioning",
        "version": 0
    }
]