Panoramica dell’API

Come effettuare chiamate API a ProcessMind

Questa guida fornisce esempi e best practice per chiamare l’API di ProcessMind, recuperare dati, inviare informazioni o automatizzare flussi di lavoro.

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

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

URL di base dell’API

Tutte le richieste API devono essere effettuate a:

https://api.processmind.com

Tutti i percorsi sono sottoposti a versionamento in /v1. La specifica API completa e leggibile dalle macchine, OpenAPI 3.1, è disponibile all’indirizzo:

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

Autenticazione

Tutte le richieste API richiedono la Sua chiave API nell’header x-api-key:

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

La chiave API può essere ottenuta nelle impostazioni del Suo account ProcessMind. Consulti Ottenere la chiave API per le istruzioni.

Codici di stato

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

Concetti chiave

• apiKey: il token di autenticazione per tutte le richieste API.
• tenantId: identifica il contesto dell’area di lavoro o dell’organizzazione. È disponibile nelle impostazioni del Suo account.
• datatableId: identifica una datatable specifica per le operazioni sui dati. È disponibile nell’opzione Ottieni ID datatable del menu delle impostazioni del dataset in ProcessMind.

Operazioni disponibili

L’API di ProcessMind Le consente di:

• Gestire i tenant: recuperare informazioni sul tenant, aggiornare le impostazioni e visualizzare le 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 datatable ai processi per l’analisi
• Caricare dati: caricare direttamente file CSV/XLSX nelle datatable
• Gestire i dataset: elencare, esaminare ed eliminare dataset e datatable

Esempi comuni

Di seguito sono riportati esempi pratici che mostrano come eseguire operazioni comuni con l’API di ProcessMind.

Ottenere un URL di caricamento presigned

Per caricare un file in una datatable, ottenga innanzitutto un URL presigned:

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 nel Suo tenant:

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

Ottenere informazioni sul tenant

Recuperi i dettagli del Suo tenant:

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

Creare un processo

Crei un nuovo processo nel Suo 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 datatable 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 Suo 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 dei ruoli nel corpo della richiesta (isAdminInTenant, access, isDashboardViewer) vengono rispettati alla lettera. Gli endpoint per la gestione degli utenti offrono tutte le funzionalità di amministrazione del tenant; pertanto, assegni chiavi API con ambito di scrittura esclusivamente a chiamanti di cui si fida e ai quali intende affidare il controllo amministrativo. La System API non invia alcuna e-mail di invito; l’onboarding dell’utente è di Sua responsabilità.

Caricare file

Il flusso generale per caricare un file in ProcessMind è il seguente:

1. Ottenga un URL presigned utilizzando la chiamata getPresignedUploadUrl.
2. Esegua una richiesta PUT a quell’URL con il contenuto del file.
3. L’URL presigned autorizza direttamente il caricamento nell’archiviazione cloud; non sono necessarie credenziali aggiuntive.

Di seguito è riportato 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 per essere copiati e incollati, in linguaggi diversi.

Esempio Bash: caricamento di un file

Script Bash minimo per caricare un file in ProcessMind utilizzando due chiamate curl, con 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: caricamento di un file CSV locale

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

Passaggi:

1. Recuperi dall’API un URL di caricamento presigned.
2. Legga il file locale dal disco.
3. Carichi il file nell’URL presigned utilizzando HTTP PUT.

Configurazione:

• Fornisca la chiave API, tenantId, datatableId e filePath quando chiama uploadFile().
• 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: caricamento di un file CSV locale

Carica un file CSV locale in un’API remota utilizzando un URL presigned.

Passaggi:

1. Recuperi dall’API un URL di caricamento presigned.
2. Legga il file locale dal disco.
3. Carichi il file nell’URL presigned utilizzando 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 tutte le pagine, continui a effettuare richieste con offset += limit finché l’array della risposta non è più corto del valore limit richiesto, oppure finché non è vuoto. I valori superiori al massimo vengono rifiutati con 400. Gli endpoint dati sottoposti a versionamento, ovvero dataset, datatable, versioni e webhook, seguono la stessa convenzione.

Versionamento e deprecazione

• Tutti i percorsi sono sottoposti a versionamento in /v1; le modifiche incompatibili vengono introdotte in una nuova versione invece di modificare silenziosamente /v1.
• Le deprecazioni vengono annunciate nel changelog e in questa pagina almeno 6 mesi prima della rimozione di un percorso; durante tale periodo i percorsi deprecati continuano a funzionare.
• Le risposte dei percorsi deprecati includono un header Sunset con la data di rimozione, e Deprecation: true.
• Le modifiche principali visibili al client sono sempre elencate nel changelog; si iscriva o torni a consultarlo prima di aggiornare i client API bloccati.

Passaggi successivi

• 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
• Ottenere la chiave API: come ottenere e gestire la chiave API