Aufgaben

Auch Aufgaben können via REST API bedient werden. Die Erstellung einer Aufgabe erfolgt wie bei anderen Inhalten (siehe Kapitel Operationen) via POST request:

Beispiel-Request:

POST /(container) HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "@type": "opengever.task.task",
  "title": "Bitte Dokument reviewen",
  "responsible": "john.doe",
  "issuer": "john.doe",
  "responsible_client": "afi",
  "task_type": "direct-execution"
}

Beispiel-Response:

HTTP/1.1 201 Created
Accept: application/json

{
  "@id": "http://example.org/ordnungssystem/fuehrung/dossier-1/task-5",
  "@type": "opengever.task.task",
  "...": "..."
}

Bearbeitung bzw. Statusänderungen

Die Bearbeitung einer Aufgabe via Patch Request ist limitiert und nur möglich solange sich die Aufgabe im Status offen befindet. Im weiteren Verlauf einer Aufgabe werden diese auschliesslich via Statusänderungen bearbeitet. Dies geschieht über den @workflow Endpoint mit entsprechender Transition ID als zusätzlicher Parameter.

Ein GET Request auf den @workflow endpoint listet mögiche Transitions auf:

Beispiel-Request:

GET /(path)/@workflow HTTP/1.1
Accept: application/json

Beispiel-Response:

HTTP/1.1 200 OK
Accept: application/json

{
  "@id": "http://example.org/ordnungssystem/fuehrung/dossier-1/task-5/@workflow",
  "history": [],
  "transitions": [
    {
    "@id": "http://example.org/ordnungssystem/fuehrung/dossier-1/task-5/@workflow/task-transition-modify-deadline",
    "title": "Frist ändern"
    },
    {
    "@id": "http://example.org/ordnungssystem/fuehrung/dossier-1/task-5/@workflow/task-transition-open-in-progress",
    "title": "Akzeptieren"
    },
    {
    "@id": "http://example.org/ordnungssystem/fuehrung/dossier-1/task-5/@workflow/task-transition-reassign",
    "title": "Neu zuweisen"
    }
  ]
}

Eine Transition wird dann folgendermassen ausgeführt:

Beispiel-Request:

POST /(path)/@workflow/task-transition-open-in-progress HTTP/1.1
Accept: application/json

{
  "text": "Ok, wird gemacht!"
}

Beispiel-Response:

HTTP/1.1 200 OK
Accept: application/json

{
  "action": "task-transition-open-in-progress",
  "actor": "philippe.gross",
  "comments": "",
  "review_state": "task-state-in-progress",
  "time": "2019-01-24T16:12:12+00:00",
  "title": "In Arbeit"
}

Folgend sind die möglichen Statusänderungen kurz dokumentiert:

Akzeptieren

Transition IDs:
  • task-transition-open-in-progress

Zusätzliche Metadaten:

text
Datentyp:Text

Frist verlängern

Transition IDs:
  • task-transition-modify-deadline

Zusätzliche Metadaten:

new_deadline
Datentyp:Date
Pflichtfeld:Ja (*)
text
Datentyp:Text

Neu zuweisen

Transition IDs:
  • task-transition-reassign

Zusätzliche Metadaten:

text
Datentyp:Text
responsible
Datentyp:Choice
Pflichtfeld:Ja (*)
responsible_client
Datentyp:Choice
Pflichtfeld:Nur wenn responsible den Client nicht bereits enthält. (*)

Hinweis:

Das Attribut responsible kann einen kombinierten Wert im Format responsible_client:responsible enthalten. Z.b. fd:hans.muster oder team:musterteam. Wird das Feld responsible mit einem kombinierten Wert befüllt, muss das Feld responsible_client nicht mehr mitgeschickt werden.

Erledigen

Transition IDs:
  • task-transition-in-progress-resolved
  • task-transition-open-resolved

Zusätzliche Metadaten:

text
Datentyp:Text
approved_documents
Datentyp:Text

Der Parameter approved_documents (optional) wird nur unterstützt für Aufgaben des Typs “Zur Genehmigung” (task_type approval`). Mit diesem Parameter kann eine Liste von UIDs der genehmigten Dokumente mitgegeben werden, welche beim Abschluss der Aufgabe durch den authentisierten User genehmigt werden. Diese Dokumente müssen sich entweder in der Aufgabe befinden, oder mit einem Verweis von der Aufgabe referenziert sein.

Überarbeiten

Transition IDs:
  • task-transition-resolved-in-progress

Zusätzliche Metadaten:

text
Datentyp:Text

Abschliessen

Transition IDs:
  • task-transition-resolved-tested-and-closed
  • task-transition-in-progress-tested-and-closed
  • task-transition-open-tested-and-closed

Zusätzliche Metadaten:

text
Datentyp:Text

Abbrechen

Transition IDs:
  • task-transition-open-cancelled
  • task-transition-in-progress-cancelled

Zusätzliche Metadaten:

text
Datentyp:Text

Ablehnen

Transition IDs:
  • task-transition-open-rejected
  • task-transition-in-progress-cancelled

Zusätzliche Metadaten:

text
Datentyp:Text

Wieder eröffnen

Transition IDs:
  • task-transition-cancelled-open
  • task-transition-rejected-open

Zusätzliche Metadaten:

text
Datentyp:Text

Delegieren

Transition IDs:
  • task-transition-delegate

Zusätzliche Metadaten:

text
Datentyp:Text
responsibles
Datentyp:ChoiceList
Pflichtfeld:Ja (*)
documents
Datentyp:Choice

Des weiteren stehen auch die Statuswechsel für sequentielle Aufgaben zur Verfügung:

Überspringen

Transition IDs:
  • task-transition-planned-skipped
  • task-transition-rejected-skipped

Zusätzliche Metadaten:

text
Datentyp:Text

Öffnen

Transition IDs:
  • task-transition-planned-open

Zusätzliche Metadaten:

text
Datentyp:Text

Aufgabe übertragen

Sowohl Auftraggeber, als auch Auftragnehmer können mit dem @transfer-task Endpoint gewechselt werden. Dabei wird überprüft, ob old_userid der User-ID des Auftraggebers und/oder des Auftragnehmers entspricht. Ist dies der Fall, wird der Benutzer mit der User-ID new_userid als Auftraggeber und/oder Auftragnehmer gesetzt. Benachrichtigungen, die normalerweise bei einer Änderung ausgelöst werden, werden unterdrückt. Dieser Endpoint wird mit einer Berechtigung beschützt: opengever.api.TransferAssignment Die Berechtigung ist standardmässig den Rollen Administrator und Manager zugewiesen.

Beispiel-Request:

POST /task-1/@transfer-task HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "old_userid": "john.doe",
  "new_userid": "robert.ziegler"
}

Beispiel-Response:

HTTP/1.1 204 No content

Aufgabe kommentieren

Eine Aufgabe kann über den @responses Endpoint kommentiert werden:

Kommentar hinzufügen

Ein POST Request auf den @responses Endpoint erstellt einen Kommentar mit dem aktuellen Benutzer.

Beispiel-Request:

POST http://example.org/ordnungssystem/fuehrung/dossier-1/task-5/@responses HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "text": "Bitte rasch anschauen. Danke.",
}

Beispiel-Response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "@id": "http://example.org/ordnungssystem/fuehrung/dossier-1/task-5/@responses/1569875801956269",
  "added_objects": [],
  "changes": [],
  "created": "2019-05-21T13:57:42+00:00",
  "creator": {
    "title": "Meier Peter",
    "token": "peter.meier"
  },
  "mimetype": "",
  "modified": null,
  "modifier": null,
  "related_items": [],
  "rendered_text": "",
  "response_id": 1569875801956269,
  "response_type": "comment",
  "successor_oguid": "",
  "text": "Bitte rasch anschauen. Danke.",
  "transition": "task-commented"
}

Kommentar bearbeiten

Ein PATCH Request auf eine Antwort vom Typ Kommentar ändert den Kommentar.

Beispiel-Request:

PATCH http://example.org/ordnungssystem/fuehrung/dossier-1/task-5/@responses/1569875801956269 HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "text": "Hat sich erledigt.",
}

Beispiel-Response:

HTTP/1.1 204 Created
Content-Type: application/json

Kommentar löschen

Ein DELETE Request auf eine Antwort vom Typ Kommentar löscht den Kommentar.

Beispiel-Request:

DELETE http://example.org/ordnungssystem/fuehrung/dossier-1/task-5/@responses/1569875801956269 HTTP/1.1
Accept: application/json
Content-Type: application/json

Beispiel-Response:

HTTP/1.1 204 No Content

Aufgabenverlauf

Der Verlauf einer Aufgabe ist in der GET Repräsentation einer Aufgaben unter dem Attribut responses enthalten.

Beispiel-Response auf ein GET Request:

HTTP/1.1 200 OK
Accept: application/json

{
  "@id": "http://example.org/ordnungssystem/fuehrung/dossier-1/task-5",
  "@type": "opengever.task.task",
  "UID": "3a551f6e3b62421da029dfceb71656e6",
  "oguid": "fd:12345",
  "items": [],
  "responses": [
    {
      "response_id": 1
      "response_type": "default"
      "added_objects": [],
      "changes": [],
      "creator": "zopemaster",
      "created": "2019-05-21T13:57:42+00:00",
      "date_of_completion": null,
      "modified": null,
      "modifier": null,
      "related_items": [],
      "reminder_option": null,
      "text": "Lorem ipsum.",
      "transition": "task-commented"
    },
    {
      "response_id": 2
      "response_type": "default"
      "added_objects": [],
      "changes": [],
      "creator": "zopemaster",
      "created": "2019-05-21T14:02:01+00:00",
      "date_of_completion": null,
      "modified": null,
      "modifier": null,
      "related_items": [],
      "text": "Suspendisse faucibus, nunc et pellentesque egestas.",
      "transition": "task-transition-open-in-progress"
    },
  ]
  "responsible": "david.erni",
  "...": "...",
}

Übergeordnetes Dossier

Angaben zum übergeordneten Dossier einer Aufgabe ist in der GET Repräsentation der Aufgaben unter dem Attribut containing_dossier enthalten. Dies ist auch bei Unteraufgaben und Weiterleitungen im Eingangskorb der Fall.

Beispiel-Response auf ein GET Request:

HTTP/1.1 200 OK
Accept: application/json

{
  "@id": "http://example.org/ordnungssystem/fuehrung/dossier-1/task-5",
  "@type": "opengever.task.task",
  "UID": "3a551f6e3b62421da029dfceb71656e6",
  "oguid": "fd:12345",
  "...": "...",
  "containing_dossier": {
    "@id": "http://example.org/ordnungssystem/fuehrung/dossier-1",
    "title": "Ein Dossier mit Tasks",
  },
  "...": "...",
}

Aufgabenhierarchie

Zu einer Aufgabe kann die Aufgabenhierarchie bestehend aus Hauptaufgabe und allen Unteraufgaben abgefragt werden. Dazu steht ein spezifischer Endpoint @tasktree zur Verfügung. Die Aufgaben werden nach Erstelldatum sortiert zurückgeliefert. Bei sequenziellen Aufgabenabläufen werden die Aufgaben nach Aufgabenfolge sortiert.

Beispiel-Request:

GET http://example.org/ordnungssystem/fuehrung/dossier-1/task-1/@tasktree HTTP/1.1
Accept: application/json

Beispiel-Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://example.org/ordnungssystem/fuehrung/dossier-1/task-1/@tasktree",
  "children":             [
    {
      "@id": "http://example.org/ordnungssystem/fuehrung/dossier-1/task-1",
      "@type": "opengever.task.task",
      "children": [
        {
          "@id": "http://example.org/ordnungssystem/fuehrung/dossier-1/task-1/task-2",
          "@type": "opengever.task.task",
          "children": [],
          "review_state": "task-state-resolved",
          "is_task_addable": false
          "is_task_addable_before": false
          "title": "Eine Unteraufgabe"
        },
      ],
      "review_state": "task-state-in-progress",
      "is_task_addable": true
      "is_task_addable_before": false
      "title": "Eine Aufgabe"
    }
  ],
}

Die Aufgabenhierarchie kann auch direkt über den GET-Request eines Tasks mittels Expansion angefordert werden.

GET http://example.org/ordnungssystem/fuehrung/dossier-1/task-1?expand=tasktree HTTP/1.1
Accept: application/json

Für sequenzielle Aufgabenabläufe steht zusätzlich das Feld is_task_addable_before zur Verfügung.

Ursprüngliche Aufgabe

Bei mandantenübergreifenden Aufgaben kann bei einer Aufgabe die ursprüngliche Aufgabe (Vorgänger) abgefragt werden. Dazu steht ein spezifischer Endpoint @predecessor zur Verfügung.

Beispiel-Request:

GET http://example.org/ordnungssystem/fuehrung/dossier-1/task-2/@predecessor HTTP/1.1
Accept: application/json

Beispiel-Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://example.org/ordnungssystem/fuehrung/dossier-1/task-2/@predecessor",
  "item": {
    "@id": "http://example.org/ordnungssystem/fuehrung/dossier-1/task-1",
    "@type": "opengever.task.task",
    "oguid": "fd:1234",
    "review_state": "task-state-in-progress",
    "task_id": 1234,
    "task_type": "Zum Bericht / Antrag",
    "title": "Eine Aufgabe"
  }
}

Die ursprüngliche Aufgabe kann auch direkt über den GET-Request eines Tasks mittels Expansion angefordert werden.

GET http://example.org/ordnungssystem/fuehrung/dossier-1/task-2?expand=predecessor HTTP/1.1
Accept: application/json

Kopierte Aufgabe

Bei mandantenübergreifenden Aufgaben können bei einer Aufgabe die kopierten Aufgaben (Nachfolger) abgefragt werden. Dazu steht ein spezifischer Endpoint @successors zur Verfügung.

Beispiel-Request:

GET http://example.org/ordnungssystem/fuehrung/dossier-1/task-1/@successors HTTP/1.1
Accept: application/json

Beispiel-Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://example.org/ordnungssystem/fuehrung/dossier-1/task-1/@successors",
  "items": [{
    "@id": "http://example.org/ordnungssystem/fuehrung/dossier-1/task-2",
    "@type": "opengever.task.task",
    "oguid": "fd:2345",
    "review_state": "task-state-in-progress",
    "task_id": 2345,
    "task_type": "Zum Bericht / Antrag",
    "title": "Eine Aufgabe"
  }]
}

Die kopierten Aufgaben können auch direkt über den GET-Request eines Tasks mittels Expansion angefordert werden.

GET http://example.org/ordnungssystem/fuehrung/dossier-1/task-1?expand=successors HTTP/1.1
Accept: application/json

Aufgabenliste einer sequenziellen Aufgabe erweitern

Bei sequenziellen Aufgaben ist die Position von Aufgaben relevant. Wird die Aufgabenliste von einer sequenziellen Aufgabe erweitert, kann über den Parameter position die Position der neuen Aufgabe bestimmt werden.

Wird keine Position angegeben, wird die Aufgabe am Ende der Aufgabenliste hinzugefügt.

Beispiel-Request:

POST /(container) HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "@type": "opengever.task.task",
  "title": "Bitte Dokument reviewen",
  "position": 4,
  "...": "...",
}

Der Parameter steht nur für Aufgaben innerhalb einer sequenziellen Aufgabe zur Verfügung.

Dokumente automatisch als Verweis der nächsten Aufgabe hinzufügen

Bei Transitionen, welche automatisch das Öffnen der nächsten Aufgabe zur Folge haben (sequentiellen Aufgaben), kann über den Boolean-Parameter pass_documents_to_next_task gesteuert werden, ob alle Dokumente der aktuellen Aufgabe automatisch als Verweis in der nächsten Aufgabe hinzugefügt werden sollen:

Wird der Parameter nicht verwendet, werden keine Dokumente automatisch als Verweis eingetragen.

Beispiel-Request:

POST /(path)/@workflow/task-transition-open-resolved HTTP/1.1
Accept: application/json

{
  "text": "Ok, wird gemacht!",
  "pass_documents_to_next_task": "true"
}