API-Übersicht

API-Aufrufe an ProcessMind ausführen

Dieser Leitfaden enthält Beispiele und bewährte Vorgehensweisen für Aufrufe der ProcessMind API, um Daten abzurufen, Informationen zu übermitteln oder Workflows zu automatisieren.

Eine vollständige Dokumentation der Endpunkte mit Anfrage- und Antwortformaten finden Sie in der API-Referenz.

Weitere Beispiele und Client-Bibliotheken finden Sie in der API-Dokumentation auf GitHub.

API-Basis-URL

Alle API-Anfragen müssen an folgende Adresse gesendet werden:

https://api.processmind.com

Alle Routen sind unter /v1 versioniert. Die vollständige maschinenlesbare API-Spezifikation (OpenAPI 3.1) ist verfügbar unter:

GET https://api.processmind.com/v1/openapi.json

Authentifizierung

Für alle API-Anfragen ist Ihr API-Schlüssel im Header x-api-key erforderlich:

x-api-key: your-api-key-here

Den API-Schlüssel erhalten Sie in den Einstellungen Ihres ProcessMind-Kontos. Eine Anleitung finden Sie unter API-Schlüssel abrufen.

Statuscodes

Die API von ProcessMind verwendet standardisierte HTTP-Statuscodes:

Zentrale Konzepte

• apiKey: Ihr Authentifizierungstoken für alle API-Anfragen.
• tenantId: Identifiziert den Kontext Ihres Arbeitsbereichs beziehungsweise Ihrer Organisation. Sie finden die ID in Ihren Kontoeinstellungen.
• datatableId: Identifiziert eine bestimmte Datentabelle für Datenoperationen. Sie ist über die Option ID der Datentabelle abrufen im Dataset-Einstellungsmenü in ProcessMind verfügbar.

Mögliche Aktionen

Die ProcessMind API ermöglicht Ihnen:

• Mandanten verwalten: Mandanteninformationen abrufen, Einstellungen aktualisieren und Statistiken anzeigen
• Benutzer verwalten: Benutzer zu Mandanten und Organisationen hinzufügen, aktualisieren oder daraus entfernen
• Prozesse verwalten: Prozesse erstellen, BPMN-Modelle hochladen und in Ordnern organisieren
• Daten verbinden: Datentabellen für die Analyse Prozessen zuordnen
• Daten hochladen: CSV-/XLSX-Dateien direkt in Datentabellen hochladen
• Datensätze verwalten: Datensätze und Datentabellen auflisten, prüfen und löschen

Häufige Beispiele

Im Folgenden finden Sie praxisnahe Beispiele für häufige Vorgänge mit der ProcessMind API.

Presigned-Upload-URL abrufen

Um eine Datei in eine Datentabelle hochzuladen, rufen Sie zunächst eine Presigned-URL ab:

const presignedUrl = await getPresignedUploadUrl({
	apiKey,
	tenantId: "tenant-123",
	datatableId: "table-456"
});
console.log(presignedUrl); // https://s3.amazonaws.com/…?X-Amz-Signature=…

Datensätze auflisten

Rufen Sie alle Datensätze in Ihrem Mandanten ab:

const datasets = await getDatasets({
	apiKey,
	tenantId: "tenant-123"
});
console.log(datasets);

Mandanteninformationen abrufen

Rufen Sie Details zu Ihrem Mandanten ab:

const tenantInfo = await getTenant({
	apiKey,
	tenantId: "tenant-123"
});
console.log(tenantInfo);

Prozess erstellen

Erstellen Sie einen neuen Prozess in Ihrem Mandanten:

const process = await createProcess({
	apiKey,
	tenantId: "tenant-123",
	displayName: "Order to Cash"
});
console.log(process.id); // Use this ID for subsequent operations

BPMN-Modell hochladen

Laden Sie eine BPMN-Datei hoch, um Ihr Prozessmodell zu definieren:

const fs = require("fs");
const bpmnXml = fs.readFileSync("./my-process.bpmn", "utf8");

await uploadBpmn({
	apiKey,
	tenantId: "tenant-123",
	processId: "process-456",
	bpmnXml
});

Daten einem Prozess zuordnen

Verbinden Sie eine Datentabelle zur Analyse mit einem Prozess:

const mapping = await createProcessMapping({
	apiKey,
	tenantId: "tenant-123",
	processId: "process-456",
	dataTableId: "datatable-789",
	displayName: "Sales Data 2024",
	showByDefault: true
});

Benutzer zu einem Mandanten hinzufügen

Fügen Sie Ihrem Mandanten einen Benutzer hinzu:

const result = await addTenantUser({
	apiKey,
	tenantId: "tenant-123",
	id: "user-456",
	email: "colleague@example.com",
	isAdminInTenant: false,
	isActiveInTenant: true,
	sendInvitationEmail: true
});

Hinweis: Rollenfelder im Body (isAdminInTenant, access, isDashboardViewer) werden unverändert übernommen. Die Endpunkte für die Benutzerverwaltung bieten vollständige Administratorrechte für den Mandanten. Vergeben Sie daher nur API-Schlüssel mit Schreibberechtigung an Personen, denen Sie die administrative Kontrolle anvertrauen. Die System API versendet keine Einladungs-E-Mail. Sie sind für die Aufnahme des Benutzers verantwortlich.

Dateien hochladen

Der allgemeine Ablauf zum Hochladen einer Datei in ProcessMind ist:

1. Rufen Sie mit dem Aufruf getPresignedUploadUrl eine Presigned-URL ab.
2. Führen Sie eine PUT-Anfrage an diese URL mit dem Dateiinhalt aus.
3. Die Presigned-URL autorisiert den Upload direkt in den Cloud-Speicher. Zusätzliche Anmeldedaten sind nicht erforderlich.

Hier ist ein vereinfachtes Beispiel mit fetch:

async function uploadFile({ apiKey, tenantId, datatableId, file }) {
	// Step 1: Obtain a presigned URL
	const uploadUrl = await getPresignedUploadUrl({ apiKey, tenantId, datatableId });
	
	// Step 2: Upload the file via PUT
	await fetch(uploadUrl, {
		method: "PUT",
		headers: {
			"Content-Type": file.type
		},
		body: file
	});
}

Vollständige Beispiele

Im Folgenden finden Sie vollständige, direkt kopierbare Beispiele in verschiedenen Programmiersprachen.

Bash-Beispiel: Datei hochladen

Minimales Bash-Skript zum Hochladen einer Datei in ProcessMind mit zwei curl-Aufrufen und Platzhaltern für alle Werte

#!/bin/bash
# Minimal Bash script to upload a file to ProcessMind using two curl calls, with placeholders for all values

# Replace the following placeholders with your actual values:
# <API_KEY>, <TENANT_ID>, <DATATABLE_ID>, <FILE_PATH>

curl -s -H "x-api-key: <API_KEY>" \
	"https://api.processmind.com/v1/tenant/<TENANT_ID>/datatables/<DATATABLE_ID>/uploads/presigned-url" \
	| grep -oP '"PreSignedUploadUrl"\s*:\s*"\K[^"]+' \
	| xargs -I {} curl -s -X PUT --upload-file "<FILE_PATH>" "{}"

Node.js-Beispiel: Lokale CSV-Datei hochladen

Lädt eine lokale CSV-Datei mit einer Presigned-URL in ProcessMind hoch.

Schritte:

1. Rufen Sie eine Presigned-Upload-URL über die API ab.
2. Lesen Sie die lokale Datei vom Datenträger ein.
3. Laden Sie die Datei per HTTP PUT auf die Presigned-URL hoch.

Konfiguration:

• Geben Sie beim Aufruf von uploadFile() Ihren API-Schlüssel, tenantId, datatableId und filePath an.
• Die API-Basis-URL ist auf https://api.processmind.com festgelegt.

/**
 * Uploads a local CSV file to ProcessMind using a presigned URL.
 *
 * Steps:
 * 1. Fetch a presigned upload URL from the API.
 * 2. Read the local file from disk.
 * 3. Upload the file to the presigned URL using HTTP PUT.
 *
 * Configuration:
 * - Provide your API key, tenantId, datatableId, and filePath when calling uploadFile().
 * - The API base URL is set to https://api.processmind.com
 */

const fs = require("node:fs");

/**
 * Uploads a file to ProcessMind datatable using a presigned URL.
 * @param {string} apiKey - Your API key for authentication.
 * @param {string} tenantId - Your tenant identifier.
 * @param {string} datatableId - Your datatable identifier.
 * @param {string} filePath - Path to the file to upload.
 */

async function getApi({path, apiKey, apiUrl = "https://api.processmind.com"}) {
	try {
        const response = await fetch(`${apiUrl}${path}`, {
            method: "GET",
            headers: {
                "x-api-key": apiKey
            }
        });
        const body = await response.json();
        if (!response.ok) {
            console.error(`Error loading from API: ${response.status}, ${response.statusText}: ${body.message}`);
            return;
        }
        return body;
    } catch (err) {
        console.error("Unexpected error:", err);
    }
}

async function getPresignedUploadUrl({apiKey, tenantId, datatableId, apiUrl = "https://api.processmind.com"}) {
	return (await getApi({apiKey, path: `/v1/tenant/${tenantId}/datatables/${datatableId}/uploads/presigned-url`, apiUrl})).PreSignedUploadUrl;
}

async function getDatasets({apiKey, tenantId, apiUrl = "https://api.processmind.com"}) {
	return await getApi({apiKey, path: `/v1/tenant/${tenantId}/datasets`, apiUrl});
}

async function getTenant({apiKey, tenantId, apiUrl = "https://api.processmind.com"}) {
	return await getApi({apiKey, path: `/v1/tenant/${tenantId}`, apiUrl});
}

async function getOrganization({apiKey, tenantId, apiUrl = "https://api.processmind.com"}) {
	return await getApi({apiKey, path: `/v1/tenant/${tenantId}/organization`, apiUrl});
}

async function uploadFile({apiKey, tenantId, datatableId, filePath, apiUrl = "https://api.processmind.com"}) {
    try {
        const uploadUrl = await getPresignedUploadUrl({apiKey, tenantId, datatableId, apiUrl});

		console.log("Uploading file...");
        fs.readFile(filePath, async (err, data) => {
            if (err) {
                console.error("Error reading file:", err);
                return;
            }
            try {
                const uploadRes = await fetch(uploadUrl, {
                    method: "PUT",
                    body: data
                });
                if (!uploadRes.ok) {
                    console.error("Upload failed:", uploadRes.status, uploadRes.statusText);
                } else {
                    console.log("File uploaded successfully.");
                }
            } catch (uploadErr) {
                console.error("Error uploading file:", uploadErr);
            }
        });
    } catch (err) {
        console.error("Unexpected error:", err);
    }
}

// Export the function for use in other modules
module.exports = { 
	getPresignedUploadUrl,
	getDatasets,
	getTenant,
	getOrganization,
	uploadFile 
};

Python-Beispiel: Lokale CSV-Datei hochladen

Lädt eine lokale CSV-Datei mit einer Presigned-URL in eine entfernte API hoch.

Schritte:

1. Rufen Sie eine Presigned-Upload-URL über die API ab.
2. Lesen Sie die lokale Datei vom Datenträger ein.
3. Laden Sie die Datei per HTTP PUT auf die Presigned-URL hoch.

Konfiguration:

• Aktualisieren Sie api_key, tenant_id, datatable_id und file_path nach Bedarf.

"""
Uploads a local CSV file to a remote API using a presigned URL.

Steps:
1. Fetch a presigned upload URL from the API.
2. Read the local file from disk.
3. Upload the file to the presigned URL using HTTP PUT.

Configuration:
- Update api_key, tenant_id, datatable_id, file_path as needed.
"""

import requests

# === Configuration ===
api_key = ""  # API key for authentication
tenant_id = ""  # Tenant identifier
datatable_id = ""  # Datatable identifier
file_path = ""  # Path to the file to upload


print("Fetching upload URL...")
api_url = "https://api.processmind.com"  # Base API URL
presign_url = f"{api_url}/v1/tenant/{tenant_id}/datatables/{datatable_id}/uploads/presigned-url"
presign_res = requests.get(presign_url, headers={"x-api-key": api_key})
if not presign_res.ok:
	print(f"Error fetching upload URL: {presign_res.status_code}, {presign_res.reason}: {presign_res.text}")
	exit(1)

presign_body = presign_res.json()
upload_url = presign_body.get("PreSignedUploadUrl")
if not upload_url:
	print("No presigned upload URL returned.")
	exit(1)

print("Uploading file...")
with open(file_path, "rb") as f:
	upload_res = requests.put(upload_url, data=f)
if not upload_res.ok:
	print(f"Upload failed: {upload_res.status_code}, {upload_res.reason}")
else:
	print("File uploaded successfully.")

Seitennummerierung

Listenendpunkte akzeptieren die Abfrageparameter limit und offset und geben ein reines JSON-Array zurück, ohne Umschlag und ohne Gesamtanzahl:

GET /v1/tenant/{tenantId}/processes?limit=50&offset=100

Um alle Ergebnisse seitenweise abzurufen, fordern Sie wiederholt mit offset += limit Daten an, bis das Antwort-Array kürzer als der angeforderte Wert limit oder leer ist. Werte über dem Maximum werden mit 400 abgelehnt. Die versionierten Datenendpunkte, darunter Datensätze, Datentabellen, Versionen und Webhooks, folgen derselben Konvention.

Versionierung und Einstellung

• Alle Routen sind unter /v1 versioniert. Änderungen mit Auswirkungen auf die Kompatibilität werden in einer neuen Version veröffentlicht, statt /v1 stillschweigend zu ändern.
• Einstellungen werden im Changelog und auf dieser Seite mindestens 6 Monate vor der Entfernung einer Route angekündigt. Während dieses Zeitraums funktionieren eingestellte Routen weiterhin.
• Antworten eingestellter Routen enthalten einen Sunset-Header mit dem Entfernungsdatum sowie Deprecation: true.
• Wichtige, für Clients sichtbare Änderungen werden immer im Changelog aufgeführt. Abonnieren Sie den Changelog oder prüfen Sie ihn vor dem Aktualisieren festgelegter API-Clients.

Nächste Schritte

• API-Referenz: Vollständige Dokumentation aller Endpunkte mit Anfrage- und Antwortformaten
• GitHub-Beispiele: Herunterladbare Beispiele und Client-Bibliotheken
• API-Schlüssel abrufen: API-Schlüssel abrufen und verwalten