API-áttekintés

API-hívások indítása a ProcessMindhez

Ez az útmutató példákat és bevált módszereket mutat be a ProcessMind API használatához, adatok lekéréséhez, információk beküldéséhez és workflow-k automatizálásához.

A végpontok teljes dokumentációját, a kérés- és válaszformátumokkal együtt, az API-referenciában találja.

További példákért és klienskönyvtárakért látogasson el az API-dokumentáció GitHub-oldalára.

API-alap URL

Minden API-kérést a következő címre kell küldeni:

https://api.processmind.com

Minden útvonal verziószáma /v1. A teljes, géppel olvasható API-specifikáció (OpenAPI 3.1) itt érhető el:

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

Hitelesítés

Minden API-kéréshez szükség van az API-kulcsra a x-api-key fejlécben, a nyilvános OpenAPI-dokumentum (/v1/openapi.json) és az MCP OAuth-végpontok kivételével:

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

Az API-kulcsot a ProcessMind-fiók beállításainál találja. Az útmutatót az API-kulcs beszerzése oldalon olvashatja el.

Állapotkódok

A ProcessMind API a szabványos HTTP-állapotkódokat használja:

Alapfogalmak

• apiKey: Hitelesítési token minden API-kéréshez.
• tenantId: Azonosítja a munkaterületet vagy a szervezeti környezetet. A fiókbeállításoknál találja.
• datatableId: Azonosít egy adott adattáblát az adatműveletekhez. A ProcessMind adathalmaz-beállításainak menüjében, az Adattábla-azonosító lekérése lehetőségnél találja.

Mire használható?

A ProcessMind API-val a következőket végezheti el:

• Bérlők kezelése: bérlői adatok lekérése, beállítások módosítása, statisztikák megtekintése
• Felhasználók kezelése: felhasználók hozzáadása, módosítása vagy eltávolítása bérlőkből és szervezetekből
• Folyamatok kezelése: folyamatok létrehozása, BPMN-modellek feltöltése, mappákba rendezés
• Adatok összekapcsolása: adattáblák hozzárendelése folyamatokhoz elemzés céljából
• Adatok feltöltése: CSV- és XLSX-fájlok feltöltése közvetlenül az adattáblákba
• Adathalmazok kezelése: adathalmazok és adattáblák listázása, megtekintése és törlése

Gyakori példák

Az alábbi példák bemutatják, hogyan végezhet el gyakori műveleteket a ProcessMind API-val.

Előre aláírt feltöltési URL lekérése

Ha fájlt szeretne feltölteni egy adattáblába, először kérjen le egy előre aláírt URL-t:

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

Adathalmazok listázása

A bérlő összes adathalmazának lekérése:

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

Bérlői adatok lekérése

A bérlő adatainak lekérése:

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

Folyamat létrehozása

Új folyamat létrehozása a bérlőben:

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

BPMN-modell feltöltése

Töltsön fel egy BPMN-fájlt a folyamatmodell meghatározásához:

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

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

Adatok hozzárendelése egy folyamathoz

Adattábla csatlakoztatása egy folyamathoz elemzés céljából:

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

Felhasználó hozzáadása egy bérlőhöz

Felhasználó hozzáadása a bérlőhöz:

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

Megjegyzés: A törzsben megadott szerepkörmezők (isAdminInTenant, access, isDashboardViewer) változtatás nélkül érvényesülnek. A felhasználókezelési végpontok teljes körű bérlői adminisztrációt tesznek lehetővé, ezért írási jogosultságú API-kulcsot csak olyan hívóknak adjon, akikre rábízná az adminisztrációt. A System API nem küld meghívó e-mailt; a felhasználó bevezetéséről Önnek kell gondoskodnia.

Fájlok feltöltése

A fájlok ProcessMindbe történő feltöltése általában így zajlik:

1. Kérjen le egy előre aláírt URL-t a getPresignedUploadUrl hívással.
2. Küldjön PUT-kérést erre az URL-re a fájl tartalmával.
3. Az előre aláírt URL közvetlenül a felhőtárhelyre engedélyezi a feltöltést, további hitelesítő adatok nélkül.

Íme egy egyszerűsített példa a fetch használatával:

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
	});
}

Teljes példák

Az alábbiakban különböző programnyelveken írt, teljes, másolásra és futtatásra kész példákat talál.

Bash-példa: fájl feltöltése

Egyszerű Bash-szkript fájl ProcessMindbe való feltöltéséhez két curl-hívással, minden érték helyőrzőjével

#!/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-példa: helyi CSV-fájl feltöltése

Helyi CSV-fájl feltöltése a ProcessMindbe előre aláírt URL használatával.

Lépések:

1. Kérjen le egy előre aláírt feltöltési URL-t az API-tól.
2. Olvassa be a helyi fájlt a lemezről.
3. Töltse fel a fájlt az előre aláírt URL-re HTTP PUT-kéréssel.

Beállítás:

• Az uploadFile() hívásakor adja meg az API-kulcsot, a tenantId, a datatableId és a filePath értékét.
• Az API alap URL-je 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 
};

Python-példa: helyi CSV-fájl feltöltése

Helyi CSV-fájl feltöltése távoli API-ra előre aláírt URL használatával.

Lépések:

1. Kérjen le egy előre aláírt feltöltési URL-t az API-tól.
2. Olvassa be a helyi fájlt a lemezről.
3. Töltse fel a fájlt az előre aláírt URL-re HTTP PUT-kéréssel.

Beállítás:

• Szükség szerint módosítsa az api_key, tenant_id, datatable_id és file_path értékét.

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

Lapozás

A listázó végpontok elfogadják a limit és offset lekérdezési paramétereket, és egy burkolóelem nélküli JSON-tömböt adnak vissza (nincs körülötte objektum, és nincs összesített elemszám):

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

Az összes oldal lekéréséhez folytassa a kéréseket a offset += limit értékkel, amíg a válaszként kapott tömb rövidebb nem lesz a kért limit értéknél (vagy üressé nem válik). A maximumnál nagyobb értékekre a rendszer 400 hibát ad. A verziózott adatvégpontok (adathalmazok, verziók, webhookok) ugyanezt az elvet követik, a két adattáblalista pedig legfeljebb limit 250 elemet ad vissza.

Verziókezelés és kivezetés

• Minden útvonal verziózott, a /v1 alatt. A visszafelé nem kompatibilis módosítások új verzióban jelennek meg, nem változtatják meg észrevétlenül a /v1 működését.
• Az útvonalak módosításáról és megszüntetéséről a kiadási megjegyzésekben adunk hírt.
• A klienseket érintő jelentős változásokat mindig feltüntetjük a változásnaplóban. Iratkozzon fel az értesítésekre, vagy frissítés előtt ellenőrizze a naplót, ha rögzített API-verziót használ.

Következő lépések

• API-referencia: Az összes végpont részletes leírása a kérés- és válaszformátumokkal
• GitHub-példák: Letölthető példák és klienskönyvtárak
• API-kulcs beszerzése: Az API-kulcs beszerzése és kezelése