Panoramica dell’API

Effettuare chiamate API a ProcessMind

Questa guida presenta esempi e buone pratiche per utilizzare l’API di ProcessMind e recuperare dati, inviare informazioni o automatizzare flussi di lavoro.

Per consultare la documentazione completa degli endpoint, con i formati delle richieste e delle risposte, veda la documentazione di riferimento dell’API.

Per altri esempi e librerie client, visiti la documentazione dell’API su GitHub.

URL di base dell’API

Tutte le richieste API devono essere inviate a:

https://api.processmind.com

Tutte le route sono versionate sotto /v1. La specifica completa dell’API in formato leggibile dalle macchine (OpenAPI 3.1) è disponibile all’indirizzo:

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

Autenticazione

Tutte le richieste API richiedono la chiave API nell’intestazione x-api-key, ad eccezione del documento OpenAPI pubblico (/v1/openapi.json) e degli endpoint OAuth MCP:

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

Può ottenere la chiave API dalle impostazioni del proprio account ProcessMind. Per le istruzioni, consulti Come ottenere la chiave API.

Codici di stato

L’API di ProcessMind utilizza i codici di stato HTTP standard:

Concetti chiave

• apiKey: token di autenticazione per tutte le richieste API.
• tenantId: identifica l’ambiente dell’area di lavoro o dell’organizzazione. È disponibile nelle impostazioni dell’account.
• datatableId: identifica una tabella dati specifica per le operazioni sui dati. È disponibile tramite l’opzione Ottieni l’ID della tabella dati nel menu delle impostazioni del dataset in ProcessMind.

Operazioni disponibili

L’API di ProcessMind consente di:

• Gestire i tenant: recuperare informazioni sui tenant, aggiornare le impostazioni e visualizzare statistiche
• Gestire gli utenti: aggiungere, aggiornare o rimuovere utenti da tenant e organizzazioni
• Gestire i processi: creare processi, caricare modelli BPMN e organizzarli in cartelle
• Collegare i dati: associare tabelle dati ai processi per l’analisi
• Caricare i dati: caricare file CSV/XLSX direttamente nelle tabelle dati
• Gestire i dataset: elencare, esaminare ed eliminare dataset e tabelle dati

Esempi comuni

Di seguito sono riportati esempi pratici delle operazioni più comuni con l’API di ProcessMind.

Ottenere un URL di caricamento prefirmato

Per caricare un file in una tabella dati, occorre prima ottenere un URL prefirmato:

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

Elencare i dataset

Recuperi tutti i dataset del tenant:

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

Ottenere informazioni sul tenant

Recuperi i dettagli del tenant:

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

Creare un processo

Crei un nuovo processo nel tenant:

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

Caricare un modello BPMN

Carichi un file BPMN per definire il modello del processo:

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

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

Associare i dati a un processo

Colleghi una tabella dati a un processo per l’analisi:

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

Aggiungere un utente a un tenant

Aggiunga un utente al tenant:

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

Nota: I campi del ruolo nel corpo della richiesta (isAdminInTenant, access, isDashboardViewer) vengono rispettati esattamente. Gli endpoint di gestione degli utenti consentono l’amministrazione completa del tenant; pertanto, assegni chiavi API con autorizzazioni di scrittura solo a chi ritiene affidabile per il controllo amministrativo. L’API di sistema non invia e-mail di invito: l’onboarding dell’utente è a Suo carico.

Caricare file

Per caricare un file in ProcessMind, la procedura generale è la seguente:

1. Ottenga un URL prefirmato tramite la chiamata getPresignedUploadUrl.
2. Invii una richiesta PUT a quell’URL con il contenuto del file.
3. L’URL prefirmato autorizza il caricamento direttamente nell’archiviazione cloud: non servono altre credenziali.

Ecco un esempio semplificato che utilizza 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
	});
}

Esempi completi

Di seguito sono riportati esempi completi, pronti da copiare e incollare, in diversi linguaggi.

Esempio Bash: caricare un file

Script Bash essenziale per caricare un file in ProcessMind con due chiamate curl e segnaposto per tutti i valori

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

Esempio Node.js: caricare un file CSV locale

Carica un file CSV locale in ProcessMind utilizzando un URL prefirmato.

Procedura:

1. Recuperare dall’API un URL di caricamento prefirmato.
2. Leggere il file locale dal disco.
3. Caricare il file all’URL prefirmato tramite HTTP PUT.

Configurazione:

• Quando chiama uploadFile(), specifichi la chiave API, tenantId, datatableId e filePath.
• L’URL di base dell’API è impostato su 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 
};

Esempio Python: caricare un file CSV locale

Carica un file CSV locale su un’API remota utilizzando un URL prefirmato.

Procedura:

1. Recuperare dall’API un URL di caricamento prefirmato.
2. Leggere il file locale dal disco.
3. Caricare il file all’URL prefirmato tramite HTTP PUT.

Configurazione:

• Aggiorni api_key, tenant_id, datatable_id e file_path secondo necessità.

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

Paginazione

Gli endpoint di elenco accettano i parametri di query limit e offset e restituiscono un array JSON semplice, senza involucro né conteggio totale:

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

Per scorrere tutti i risultati, continui a inviare richieste con offset += limit finché l’array della risposta non contiene meno elementi del valore limit richiesto (o è vuoto). I valori superiori al massimo vengono rifiutati con 400. Gli endpoint dati versionati (dataset, versioni, webhook) seguono la stessa convenzione; i due elenchi delle tabelle dati hanno un limite di limit pari a 250.

Versioni e deprecazioni

• Tutte le route sono versionate sotto /v1; le modifiche incompatibili vengono rilasciate in una nuova versione anziché modificare silenziosamente /v1.
• Le modifiche e le rimozioni delle route vengono annunciate nelle note di rilascio.
• Le modifiche principali visibili ai client sono sempre riportate nel registro delle modifiche; si iscriva agli aggiornamenti o consulti le note prima di aggiornare i client API bloccati su una versione specifica.

Prossimi passaggi

• Documentazione di riferimento dell’API: documentazione completa di tutti gli endpoint, con i formati delle richieste e delle risposte
• Esempi su GitHub: esempi scaricabili e librerie client
• Come ottenere la chiave API: istruzioni per ottenere e gestire la chiave API