API-Endpunkt: Task

Einleitung

Aufgaben sind vielseitige Objekte in smenso und können für verschiedene Zwecke verwendet werden. Sie sind ein zentrales Element im Rahmen von Projekten. 

Der task-Endpunkt ermöglicht das Abrufen (GET) und das Hinzufügen oder Aktualisieren (POST) von Aufgaben zu einem bestimmten Projekt. Aufgaben werden durch verschiedene Attribute definiert und müssen dem zugehörigen Projekt zugeordnet sein.

Jeder Endpunkt erfordert die Verwendung eines personalisierten Tokens, der aus dem Admin Center bezogen werden kann und im Header gesetzt werden muss. Mehr Informationen zum Header.

Diese Dokumentation bietet Informationen zum API-Endpunkt task. Entwickler:innen können diese Informationen nutzen, um Aufgaben abzurufen oder von anderen Quellen in das System zu integrieren und den Status der Verarbeitung abzurufen.

1. Export Endpunkt

**GET** `https://WORKSPACENAME.smenso.cloud/skyisland/api/Reports/tasks/projectID?view=viewID`

Vorbereitung einer Aufgabenliste

Um die Export-API zu nutzen, muss zunächst eine Listenansicht mit den gewünschten Feldern erstellt werden. Diese Ansicht bestimmt, welche Felder im GET-Service übergeben und somit über die API abgerufen werden können.

Beispiel

Im folgenden Beispiel wurde im Projekt "Beispielprojekt DEMO2" die Aufgabenansicht "06 📅 Termine / 💰 Kosten“ ausgewählt. Diese Ansicht enthält alle Felder, die über die API bereitgestellt werden sollen.

API-Link der Aufgabenlistenansicht abrufen

1. Öffne das Dropdown-Menü für die Verwaltung von Ansichten.
2. Klicke auf das Teilen-Symbol .
3. Im daraufhin angezeigten Dialog , gehe zum Bereich API-Link und klicke auf Kopieren.
   
   
   
   

&format=JSON

&lang=de

2. Import Endpunkt

**POST** `https://WORKSPACENAME.smenso.cloud/skyisland/api/Integration/task`

Felder

Anfragedaten (Beispiel)

Die Anfrage enthält eine Liste von Aufgaben im folgenden XML-Format:

<Tasks projectId="project-guid">
  <Task>
   <Id>task-guid</Id>
   <Title><![CDATA[Titel der Aufgabe]]></Title>
   <Timezone>
   <Description><![CDATA[Beschreibung der Aufgabe]]></Description>
   <Priority>1</Priority>
   <StartDate>04.05.2022 +02:00</StartDate>
   <DueDate>18.5.2022 +2:00</DueDate>
   <PlannedCost>200</PlannedCost>
   <Cost>100</Cost> 
   <StatusId>1</StatusId>
   <WorkflowId>workflow-guid</WorkflowId>
   <WorkflowStatusId>workflow-status-guid</WorkflowStatusId>
   <Duration>120</Duration>
   <PlannedDuration>180</PlannedDuration>
   <IsMilestone>True</IsMilestone>
   <Folder>Folder-name</Folder>
  </Task>
</Tasks>

Antwort

Nach erfolgreicher Ausführung erhältst du eine Ticket ID (z. B. `c3406426-6028-48da-ad4a-76865336ff0f`), die zur späteren Überprüfung des Status verwendet wird.

Unteraufgaben ansprechen

<Tasks projectId=...>
<Task>
...
<Subtasks>
<Task>
...
</Task>
<Task>
...
</Task>
</Subtasks>
</Task>
</Tasks>

Verwendung von Flavors in Anfragen

Flavors sind in jedem Workspace individuell. Um sie über die API anzusprechen, kann entweder die GUID (eine global eindeutige ID mit spezieller Formatierung) oder der Name des Flavors verwendet werden.

Mehr Informationen zur Flavor-GUID: Woher bekomme ich eine Flavor-GUID?

Die Syntax zur Verwendung der GUID oder des Flavornamens in einer Anfrage lautet wie folgt:

<Flavor target="GUID oder Name">Wert</Flavor>

Anfragedaten (Beispieldaten):

<Tasks projectId="e7737f60-d5a8-4b61-8cda-2ad51ccff4dd">
<Task>
<Id>567ed2e2-4eba-4c4d-aadd-97b8778ea98e</Id>
<Flavor target="f5a7dbd8-b3dc-4e51-99a6-385846823311">PHRI</Flavor>
<Flavor target="fa44bc82-30a9-4eb9-a343-f5b7f0a9c269">Objektplanung</Flavor>
</Task>
</Tasks>

Ticket-Status abrufen

Beschreibung

Um den Status der Anlage überprüfen zu können, kann man die Ticket ID in einem separaten Call überprüfen.

Anfragedaten

Du kannst den Status eines Tickets unter folgendem Endpoint abrufen:

**GET** `https://WORKSPACENAME.smenso.cloud/skyisland/api/Integration/status/{ticket-id}`

Antwort

Die Antwort enthält detaillierte Informationen über den Status des Tickets und die Anzahl der erstellten und modifizierten Projekte und Aufgaben.

<Ticket>
<Id>c3406426-6028-48da-ad4a-76865336ff0f</Id>
<Endpoint>Task</Endpoint>
<Success>1</Success>
<Status>Success</Status>
<StatusId>10</StatusId>
<Received>05/10/2022 09:53:49 +00:00</Received>
<Started>05/10/2022 09:53:52 +00:00</Started>
<Processed>05/10/2022 09:56:41 +00:00</Processed>
<Projects>
<Created>0</Created>
<Modified>0</Modified>
<AttributesModified>0</AttributesModified>
</Projects>
<Tasks>
<Created>100</Created>
<Modified>0</Modified>
<AttributesModified>0</AttributesModified>
</Tasks>
</Ticket>