Przegląd API

Jak wywoływać ProcessMind API

W tym przewodniku przedstawiono przykłady i dobre praktyki dotyczące wywoływania ProcessMind API w celu pobierania danych, przesyłania informacji i automatyzowania workflow.

Pełną dokumentację endpointów wraz z formatami żądań i odpowiedzi można znaleźć w dokumentacji API.

Dodatkowe przykłady i biblioteki klienckie są dostępne w dokumentacji API w serwisie GitHub.

Podstawowy adres URL API

Wszystkie żądania API należy kierować na adres:

https://api.processmind.com

Wszystkie trasy są wersjonowane pod /v1. Pełna, czytelna maszynowo specyfikacja API (OpenAPI 3.1) jest dostępna pod adresem:

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

Uwierzytelnianie

Wszystkie żądania API wymagają klucza API w nagłówku x-api-key, z wyjątkiem publicznego dokumentu OpenAPI (/v1/openapi.json) i endpointów MCP OAuth:

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

Klucz API można uzyskać w ustawieniach konta ProcessMind. Instrukcje znajdują się w sekcji Uzyskiwanie klucza API.

Kody statusu

ProcessMind API korzysta ze standardowych kodów statusu HTTP:

Najważniejsze pojęcia

• apiKey: token uwierzytelniający dla wszystkich żądań API.
• tenantId: identyfikuje obszar roboczy lub organizację. Można go znaleźć w ustawieniach konta.
• datatableId: identyfikuje konkretną tabelę danych używaną do operacji na danych. Można go uzyskać za pomocą opcji Pobierz identyfikator tabeli danych w menu ustawień zbioru danych w ProcessMind.

Dostępne działania

ProcessMind API umożliwia:

• Zarządzanie tenantami: pobieranie informacji o tenantach, aktualizowanie ustawień i wyświetlanie statystyk
• Zarządzanie użytkownikami: dodawanie, aktualizowanie i usuwanie użytkowników z tenantów i organizacji
• Zarządzanie procesami: tworzenie procesów, przesyłanie modeli BPMN i porządkowanie ich w folderach
• Łączenie danych: mapowanie tabel danych do procesów na potrzeby analizy
• Przesyłanie danych: bezpośrednie przesyłanie plików CSV/XLSX do tabel danych
• Zarządzanie zbiorami danych: wyświetlanie, sprawdzanie i usuwanie zbiorów danych oraz tabel danych

Typowe przykłady

Poniżej przedstawiono praktyczne przykłady typowych operacji wykonywanych za pomocą ProcessMind API.

Uzyskiwanie wstępnie podpisanego adresu URL do przesyłania

Aby przesłać plik do tabeli danych, najpierw uzyskaj wstępnie podpisany adres URL:

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

Wyświetlanie listy zbiorów danych

Pobierz wszystkie zbiory danych w swoim tenancie:

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

Pobieranie informacji o tenancie

Pobierz szczegóły swojego tenanta:

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

Tworzenie procesu

Utwórz nowy proces w swoim tenancie:

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

Przesyłanie modelu BPMN

Prześlij plik BPMN, aby zdefiniować model procesu:

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

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

Mapowanie danych do procesu

Połącz tabelę danych z procesem na potrzeby analizy:

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

Dodawanie użytkownika do tenanta

Dodaj użytkownika do swojego tenanta:

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

Uwaga: Pola ról w treści żądania (isAdminInTenant, access, isDashboardViewer) są uwzględniane dokładnie w podanej postaci. Endpointy zarządzania użytkownikami zapewniają pełny zakres uprawnień administratora tenanta. Dlatego klucze API z prawem zapisu należy udostępniać wyłącznie podmiotom, którym można powierzyć kontrolę administracyjną. System API nie wysyła zaproszenia e-mail. Za wdrożenie użytkownika odpowiadają Państwo.

Przesyłanie plików

Ogólny przebieg przesyłania pliku do ProcessMind:

1. Uzyskaj wstępnie podpisany adres URL za pomocą wywołania getPresignedUploadUrl.
2. Wyślij zawartość pliku na ten adres URL za pomocą żądania PUT.
3. Wstępnie podpisany adres URL umożliwia bezpośrednie przesłanie pliku do magazynu w chmurze. Nie są potrzebne dodatkowe dane uwierzytelniające.

Poniżej uproszczony przykład użycia 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
	});
}

Kompletne przykłady

Poniżej znajdują się kompletne przykłady w różnych językach, gotowe do skopiowania i użycia.

Przykład Bash: przesyłanie pliku

Minimalny skrypt Bash do przesłania pliku do ProcessMind za pomocą dwóch wywołań curl. Wszystkie wartości zastąpiono symbolami zastępczymi.

#!/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>" "{}"

Przykład Node.js: przesyłanie lokalnego pliku CSV

Przesyła lokalny plik CSV do ProcessMind za pomocą wstępnie podpisanego adresu URL.

Kroki:

1. Pobierz z API wstępnie podpisany adres URL do przesyłania pliku.
2. Odczytaj plik z dysku lokalnego.
3. Prześlij plik na wstępnie podpisany adres URL za pomocą żądania HTTP PUT.

Konfiguracja:

• Podczas wywoływania uploadFile() podaj klucz API, tenantId, datatableId i filePath.
• Podstawowy adres URL API ustawiono na https://api.processmind.com

/**
 * 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 
};

Przykład Python: przesyłanie lokalnego pliku CSV

Przesyła lokalny plik CSV do zdalnego API za pomocą wstępnie podpisanego adresu URL.

Kroki:

1. Pobierz z API wstępnie podpisany adres URL do przesyłania pliku.
2. Odczytaj plik z dysku lokalnego.
3. Prześlij plik na wstępnie podpisany adres URL za pomocą żądania HTTP PUT.

Konfiguracja:

• W razie potrzeby zaktualizuj wartości api_key, tenant_id, datatable_id i file_path.

"""
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.")

Stronicowanie

Endpointy list przyjmują parametry zapytania limit i offset oraz zwracają zwykłą tablicę JSON, bez dodatkowego obiektu i łącznej liczby wyników:

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

Aby pobrać wszystkie strony wyników, wysyłaj kolejne żądania z parametrem offset += limit, aż tablica odpowiedzi będzie krótsza niż żądana wartość limit lub pusta. Wartości przekraczające limit są odrzucane z błędem 400. Wersjonowane endpointy danych (zbiory danych, wersje, webhooki) działają tak samo. Maksymalna wartość parametru limit dla obu list tabel danych wynosi 250.

Wersjonowanie i wycofywanie

• Wszystkie ścieżki mają wersję w /v1. Zmiany niezgodne ze starszymi wersjami trafiają do nowej wersji, zamiast po cichu zmieniać /v1.
• Informacje o zmianach i usunięciu ścieżek publikujemy w informacjach o wydaniu.
• Zmiany widoczne dla klienta zawsze opisujemy w changelogu. Przed aktualizacją przypiętych klientów API warto zasubskrybować changelog lub sprawdzić go ponownie.

Następne kroki

• Dokumentacja API: pełna dokumentacja wszystkich endpointów, wraz z formatami żądań i odpowiedzi
• Przykłady w GitHub: przykłady do pobrania i biblioteki klienckie
• Jak uzyskać klucz API: uzyskiwanie klucza API i zarządzanie nim