Notizbuchverwaltung

Vollständige CRUD-Operationen zur Verwaltung von Notizbüchern innerhalb von Untersuchungen. Alle Änderungsoperationen laden das Projekt automatisch in den gemeinsamen Cache.

Notizbücher auflisten

GET /api/{tenantId}/{projectId}/notebook/investigation/{investigationId}

Gibt alle Notizbücher innerhalb einer Untersuchung zurück.

Pfadparameter

Parameter Typ Erforderlich Beschreibung
tenantId GUID Ja Die Mandanten-ID
projectId GUID Ja Die Projekt-ID
investigationId GUID Ja Die Untersuchungs-ID

Antwort (200 OK)

[
  {
    "notebookId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "investigationId": "11111111-2222-3333-4444-555555555555",
    "name": "Haupt",
    "description": "Primäres Analyse-Notizbuch",
    "dateCreated": "2024-01-15T10:30:00Z",
    "dateModified": "2024-01-20T14:45:00Z",
    "createdBy": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "modifiedBy": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "notebookType": 0,
    "notebookOrder": 1.0,
    "lastExecutionDuration": 2.5,
    "blockCount": 12
  },
  {
    "notebookId": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff",
    "investigationId": "11111111-2222-3333-4444-555555555555",
    "name": "Variantenanalyse",
    "description": "Prozess-Varianten-Erkundung",
    "dateCreated": "2024-01-16T09:00:00Z",
    "dateModified": "2024-01-18T11:30:00Z",
    "createdBy": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "modifiedBy": null,
    "notebookType": 0,
    "notebookOrder": 2.0,
    "lastExecutionDuration": 1.2,
    "blockCount": 8
  }
]

Fehlerantworten

Nicht gefunden (404)

{
  "Error": "Investigation not found",
  "InvestigationId": "11111111-2222-3333-4444-555555555555"
}

Notizbuch abrufen

GET /api/{tenantId}/{projectId}/notebook/{notebookId}

Gibt detaillierte Informationen zu einem bestimmten Notizbuch zurück.

Pfadparameter

Parameter Typ Erforderlich Beschreibung
tenantId GUID Ja Die Mandanten-ID
projectId GUID Ja Die Projekt-ID
notebookId GUID Ja Die Notizbuch-ID

Antwort (200 OK)

{
  "notebookId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "investigationId": "11111111-2222-3333-4444-555555555555",
  "name": "Haupt",
  "description": "Primäres Analyse-Notizbuch",
  "dateCreated": "2024-01-15T10:30:00Z",
  "dateModified": "2024-01-20T14:45:00Z",
  "createdBy": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "modifiedBy": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "notebookType": 0,
  "notebookOrder": 1.0,
  "lastExecutionDuration": 2.5,
  "blockCount": 12
}

Notizbuch erstellen

POST /api/{tenantId}/{projectId}/notebook/investigation/{investigationId}

Erstellt ein neues, leeres Notizbuch in der Untersuchung.

Pfadparameter

Parameter Typ Erforderlich Beschreibung
tenantId GUID Ja Die Mandanten-ID
projectId GUID Ja Die Projekt-ID
investigationId GUID Ja Die Untersuchungs-ID

Anforderungsinhalt

{
  "name": "Prozessanalyse",
  "description": "Detaillierter Prozessanalyse-Workflow",
  "notebookType": 0
}

Anfragefelder

Feld Typ Erforderlich Beschreibung
name string Ja Name des Notizbuchs (eindeutig innerhalb der Untersuchung)
description string Nein Beschreibung des Notizbuchs
notebookType integer Nein Typ (0=Standard, Standardwert)

Antwort (201 Created)

{
  "notebookId": "cccccccc-dddd-eeee-ffff-000000000000",
  "investigationId": "11111111-2222-3333-4444-555555555555",
  "name": "Prozessanalyse",
  "description": "Detaillierter Prozessanalyse-Workflow",
  "dateCreated": "2024-03-01T10:00:00Z",
  "dateModified": "2024-03-01T10:00:00Z",
  "createdBy": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "modifiedBy": null,
  "notebookType": 0,
  "notebookOrder": 3.0,
  "lastExecutionDuration": 0,
  "blockCount": 0
}

Fehlerantworten

Fehlerhafte Anfrage (400)

{
  "Error": "Failed to create notebook. The name may already exist in this investigation."
}

Aus Vorlage erstellen

POST /api/{tenantId}/{projectId}/notebook/investigation/{investigationId}/from-template

Erstellt ein Notizbuch aus einer vordefinierten Vorlage, inklusive aller Blöcke und Konfigurationen.

Pfadparameter

Parameter Typ Erforderlich Beschreibung
tenantId GUID Ja Die Mandanten-ID
projectId GUID Ja Die Projekt-ID
investigationId GUID Ja Die Untersuchungs-ID

Anforderungsinhalt

{
  "templateId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "name": "Prozess-Discovery-Analyse",
  "description": "Analyse mit Process Discovery Vorlage"
}

Anfragefelder

Feld Typ Erforderlich Beschreibung
templateId GUID Ja Vorlage, die verwendet werden soll
name string Nein Überschreibt den Namen der Vorlage
description string Nein Überschreibt die Beschreibung der Vorlage

Antwort (201 Created)

Gibt das erstellte Notizbuch mit Blöcken aus der Vorlage zurück.

Fehlerantworten

Nicht gefunden (404)

{
  "Error": "Template not found"
}

Notizbuch aktualisieren

PUT /api/{tenantId}/{projectId}/notebook/{notebookId}

Aktualisiert Metadaten des Notizbuchs. Unterstützt optimistisches Sperren via DateModified.

Pfadparameter

Parameter Typ Erforderlich Beschreibung
tenantId GUID Ja Die Mandanten-ID
projectId GUID Ja Die Projekt-ID
notebookId GUID Ja Die Notizbuch-ID

Anforderungsinhalt

{
  "name": "Aktualisierter Notizbuchname",
  "description": "Aktualisierte Beschreibung",
  "notebookOrder": 2.5,
  "dateModified": "2024-01-20T14:45:00Z"
}

Anfragefelder

Feld Typ Erforderlich Beschreibung
name string Ja Notizbuchname
description string Nein Notizbuchbeschreibung
notebookOrder decimal Nein Anzeige-Reihenfolge
dateModified datetime Nein Für optimistisches Sperren

Antwort (200 OK)

Gibt das aktualisierte Notizbuch zurück.

Optimistisches Sperren

Wenn dateModified angegeben ist und nicht mit dem aktuellen Wert auf dem Server übereinstimmt, wird 409 Conflict zurückgegeben:

{
  "Error": "CONFLICT",
  "Message": "Notebook wurde seit dem letzten Abruf von einem anderen Benutzer geändert",
  "YourDateModified": "2024-01-20T14:45:00Z",
  "CurrentDateModified": "2024-01-21T09:30:00Z",
  "ModifiedBy": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "Resolution": "GET /api/{tenantId}/{projectId}/notebook/{notebookId} um aktuellen Zustand abzurufen, dann erneut versuchen"
}

Notizbuch löschen

DELETE /api/{tenantId}/{projectId}/notebook/{notebookId}

Löscht ein Notizbuch und alle seine Blöcke dauerhaft.

Pfadparameter

Parameter Typ Erforderlich Beschreibung
tenantId GUID Ja Die Mandanten-ID
projectId GUID Ja Die Projekt-ID
notebookId GUID Ja Die Notizbuch-ID

Antwort (200 OK)

{
  "Message": "Notizbuch erfolgreich gelöscht",
  "NotebookId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
}

Notizbuch kopieren

POST /api/{tenantId}/{projectId}/notebook/{notebookId}/copy

Erstellt eine vollständige Kopie eines Notizbuchs inklusive aller Blöcke. Kann in dieselbe oder eine andere Untersuchung kopieren.

Pfadparameter

Parameter Typ Erforderlich Beschreibung
tenantId GUID Ja Die Mandanten-ID
projectId GUID Ja Die Projekt-ID
notebookId GUID Ja Quell-Notizbuch-ID

Anforderungsinhalt

{
  "name": "Kopie von Hauptanalyse",
  "destinationInvestigationId": "22222222-3333-4444-5555-666666666666"
}

Anfragefelder

Feld Typ Erforderlich Beschreibung
name string Nein Name für die Kopie (Standard: "Kopie von ")
destinationInvestigationId GUID Nein Zieluntersuchung (Standard: gleiche Untersuchung)

Antwort (201 Created)

Gibt das neu erstellte Notizbuch zurück.

Teilbaren URL abrufen

GET /api/{tenantId}/{projectId}/notebook/{notebookId}/url

Erzeugt eine teilbare URL für den direkten Zugriff auf das Notizbuch im UI.

Antwort (200 OK)

{
  "notebookId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "url": "https://your-mindzie-instance.com/investigation/12345678/87654321/11111111/notebook/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "relativePath": "/investigation/12345678/87654321/11111111/notebook/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "expiresAt": null
}

Implementierungsbeispiele

Python

import requests

BASE_URL = 'https://your-mindzie-instance.com'
TENANT_ID = '12345678-1234-1234-1234-123456789012'
PROJECT_ID = '87654321-4321-4321-4321-210987654321'

class NotebookManager:
    def __init__(self, api_key):
        self.headers = {
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        }

    def list_notebooks(self, investigation_id):
        """Listet alle Notizbücher in einer Untersuchung auf."""
        url = f'{BASE_URL}/api/{TENANT_ID}/{PROJECT_ID}/notebook/investigation/{investigation_id}'
        response = requests.get(url, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def get_notebook(self, notebook_id):
        """Ruft Notizbuchdetails ab."""
        url = f'{BASE_URL}/api/{TENANT_ID}/{PROJECT_ID}/notebook/{notebook_id}'
        response = requests.get(url, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def create_notebook(self, investigation_id, name, description=None):
        """Erstellt ein neues Notizbuch."""
        url = f'{BASE_URL}/api/{TENANT_ID}/{PROJECT_ID}/notebook/investigation/{investigation_id}'
        data = {'name': name, 'description': description}
        response = requests.post(url, json=data, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def create_from_template(self, investigation_id, template_id, name=None):
        """Erstellt ein Notizbuch aus einer Vorlage."""
        url = f'{BASE_URL}/api/{TENANT_ID}/{PROJECT_ID}/notebook/investigation/{investigation_id}/from-template'
        data = {'templateId': template_id, 'name': name}
        response = requests.post(url, json=data, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def update_notebook(self, notebook_id, name, description=None, date_modified=None):
        """Aktualisiert Notizbuch mit optimistischem Sperren."""
        url = f'{BASE_URL}/api/{TENANT_ID}/{PROJECT_ID}/notebook/{notebook_id}'
        data = {'name': name, 'description': description}
        if date_modified:
            data['dateModified'] = date_modified
        response = requests.put(url, json=data, headers=self.headers)
        if response.status_code == 409:
            conflict = response.json()
            raise Exception(f"Konflikt: {conflict['Message']}")
        response.raise_for_status()
        return response.json()

    def delete_notebook(self, notebook_id):
        """Löscht ein Notizbuch."""
        url = f'{BASE_URL}/api/{TENANT_ID}/{PROJECT_ID}/notebook/{notebook_id}'
        response = requests.delete(url, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def copy_notebook(self, notebook_id, name=None, destination_investigation=None):
        """Kopiert ein Notizbuch."""
        url = f'{BASE_URL}/api/{TENANT_ID}/{PROJECT_ID}/notebook/{notebook_id}/copy'
        data = {'name': name}
        if destination_investigation:
            data['destinationInvestigationId'] = destination_investigation
        response = requests.post(url, json=data, headers=self.headers)
        response.raise_for_status()
        return response.json()

# Nutzung
manager = NotebookManager('your-api-key')
investigation_id = '11111111-2222-3333-4444-555555555555'

# Notizbücher auflisten
notebooks = manager.list_notebooks(investigation_id)
print(f"{len(notebooks)} Notizbücher gefunden")

# Ein Notizbuch erstellen
notebook = manager.create_notebook(investigation_id, 'Neue Analyse', 'Mein Workflow')
print(f"Notizbuch erstellt: {notebook['notebookId']}")

# Notizbuch kopieren
copy = manager.copy_notebook(notebook['notebookId'], 'Kopie von Neue Analyse')
print(f"Kopie erstellt: {copy['notebookId']}")

# Aktualisieren mit optimistischem Sperren
try:
    updated = manager.update_notebook(
        notebook['notebookId'],
        'Umbenannte Analyse',
        date_modified=notebook['dateModified']
    )
except Exception as e:
    print(f"Aktualisierung fehlgeschlagen: {e}")

JavaScript/Node.js

const BASE_URL = 'https://your-mindzie-instance.com';
const TENANT_ID = '12345678-1234-1234-1234-123456789012';
const PROJECT_ID = '87654321-4321-4321-4321-210987654321';

class NotebookManager {
  constructor(apiKey) {
    this.headers = {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    };
  }

  async listNotebooks(investigationId) {
    const url = `${BASE_URL}/api/${TENANT_ID}/${PROJECT_ID}/notebook/investigation/${investigationId}`;
    const response = await fetch(url, { headers: this.headers });
    if (!response.ok) throw new Error(`Fehler: ${response.status}`);
    return response.json();
  }

  async createNotebook(investigationId, name, description = null) {
    const url = `${BASE_URL}/api/${TENANT_ID}/${PROJECT_ID}/notebook/investigation/${investigationId}`;
    const response = await fetch(url, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify({ name, description })
    });
    if (!response.ok) throw new Error(`Fehler: ${response.status}`);
    return response.json();
  }

  async updateNotebook(notebookId, name, description = null, dateModified = null) {
    const url = `${BASE_URL}/api/${TENANT_ID}/${PROJECT_ID}/notebook/${notebookId}`;
    const body = { name, description };
    if (dateModified) body.dateModified = dateModified;

    const response = await fetch(url, {
      method: 'PUT',
      headers: this.headers,
      body: JSON.stringify(body)
    });

    if (response.status === 409) {
      const conflict = await response.json();
      throw new Error(`Konflikt: ${conflict.Message}`);
    }
    if (!response.ok) throw new Error(`Fehler: ${response.status}`);
    return response.json();
  }

  async deleteNotebook(notebookId) {
    const url = `${BASE_URL}/api/${TENANT_ID}/${PROJECT_ID}/notebook/${notebookId}`;
    const response = await fetch(url, {
      method: 'DELETE',
      headers: this.headers
    });
    if (!response.ok) throw new Error(`Fehler: ${response.status}`);
    return response.json();
  }

  async copyNotebook(notebookId, name = null, destinationInvestigationId = null) {
    const url = `${BASE_URL}/api/${TENANT_ID}/${PROJECT_ID}/notebook/${notebookId}/copy`;
    const body = {};
    if (name) body.name = name;
    if (destinationInvestigationId) body.destinationInvestigationId = destinationInvestigationId;

    const response = await fetch(url, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify(body)
    });
    if (!response.ok) throw new Error(`Fehler: ${response.status}`);
    return response.json();
  }
}

// Nutzung
const manager = new NotebookManager('your-api-key');
const investigationId = '11111111-2222-3333-4444-555555555555';

// Notizbücher auflisten
const notebooks = await manager.listNotebooks(investigationId);
console.log(`${notebooks.length} Notizbücher gefunden`);

// Erstellen und Kopieren
const notebook = await manager.createNotebook(investigationId, 'Neue Analyse');
const copy = await manager.copyNotebook(notebook.notebookId, 'Kopie der Analyse');

Best Practices

  1. Automatisches Laden: Projekte für Notebook-CRUD nicht explizit laden – das erfolgt automatisch
  2. Optimistisches Sperren: dateModified bei Updates angeben, um Konflikte zu erkennen
  3. Vorlagen: Vorlagen für konsistente Analyse-Workflows verwenden
  4. Benennung: Beschreibende, eindeutige Namen innerhalb jeder Untersuchung verwenden
  5. Aufräumen: Nicht verwendete Notizbücher löschen, um Untersuchungen organisiert zu halten