Présentation de l’API

Effectuer des appels à l’API ProcessMind

Ce guide présente des exemples et des bonnes pratiques pour appeler l’API ProcessMind afin de récupérer des données, d’envoyer des informations ou d’automatiser des flux de travail.

Pour consulter la documentation complète des points de terminaison et des formats de requête et de réponse, reportez-vous à la référence de l’API.

Pour d’autres exemples et des bibliothèques clientes, consultez la documentation de l’API sur GitHub.

URL de base de l’API

Toutes les requêtes API doivent être envoyées à l’adresse suivante :

https://api.processmind.com

Toutes les routes sont versionnées sous /v1. La spécification complète de l’API, lisible par machine (OpenAPI 3.1), est disponible à l’adresse suivante :

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

Authentification

Toutes les requêtes API doivent inclure votre clé API dans l’en-tête x-api-key, à l’exception du document OpenAPI public (/v1/openapi.json) et des points de terminaison OAuth MCP :

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

Vous trouverez votre clé API dans les paramètres de votre compte ProcessMind. Consultez la page Obtenir votre clé API pour savoir comment procéder.

Codes d’état

L’API ProcessMind utilise les codes d’état HTTP standard :

Concepts clés

• apiKey : votre jeton d’authentification pour toutes les requêtes API.
• tenantId : identifie le contexte de votre espace de travail ou de votre organisation. Vous le trouverez dans les paramètres de votre compte.
• datatableId : identifie une table de données précise pour les opérations sur les données. Vous pouvez l’obtenir à l’aide de l’option Obtenir l’identifiant de la table de données dans le menu des paramètres du jeu de données de ProcessMind.

Opérations disponibles

L’API ProcessMind vous permet de :

• Gérer les environnements : récupérer les informations sur les environnements, modifier les paramètres et consulter les statistiques
• Gérer les utilisateurs : ajouter, modifier ou supprimer des utilisateurs dans les environnements et les organisations
• Gérer les processus : créer des processus, importer des modèles BPMN et les organiser dans des dossiers
• Connecter des données : associer des tables de données à des processus pour les analyser
• Importer des données : importer directement des fichiers CSV/XLSX dans des tables de données
• Gérer les jeux de données : répertorier, examiner et supprimer des jeux de données et des tables de données

Exemples courants

Voici des exemples pratiques d’opérations courantes avec l’API ProcessMind.

Obtenir une URL d’importation pré-signée

Pour importer un fichier dans une table de données, commencez par obtenir une URL pré-signée :

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

Répertorier les jeux de données

Récupérez tous les jeux de données de votre environnement :

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

Obtenir les informations sur un environnement

Récupérez les détails de votre environnement :

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

Créer un processus

Créez un processus dans votre environnement :

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

Importer un modèle BPMN

Importez un fichier BPMN pour définir votre modèle de processus :

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

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

Associer des données à un processus

Connectez une table de données à un processus pour l’analyser :

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

Ajouter un utilisateur à un environnement

Ajoutez un utilisateur à votre environnement :

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

Remarque : les champs de rôle du corps de la requête (isAdminInTenant, access, isDashboardViewer) sont pris en compte tels quels. Les points de terminaison de gestion des utilisateurs donnent accès à l’ensemble des fonctions d’administration d’un environnement. Ne fournissez donc des clés API avec autorisation d’écriture qu’aux personnes auxquelles vous confiez le contrôle administratif. L’API système n’envoie aucun courriel d’invitation ; il vous revient d’assurer l’intégration de l’utilisateur.

Importer des fichiers

Pour importer un fichier dans ProcessMind, procédez comme suit :

1. Obtenez une URL pré-signée à l’aide de l’appel getPresignedUploadUrl.
2. Envoyez une requête PUT à cette URL avec le contenu du fichier.
3. L’URL pré-signée autorise l’importation directement dans le stockage cloud ; aucun autre identifiant n’est nécessaire.

Voici un exemple simplifié avec 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
	});
}

Exemples complets

Vous trouverez ci-dessous des exemples complets, prêts à copier-coller, dans différents langages.

Exemple Bash : importer un fichier

Script Bash minimal pour importer un fichier dans ProcessMind à l’aide de deux appels curl, avec des valeurs fictives à remplacer

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

Exemple Node.js : importer un fichier CSV local

Importe un fichier CSV local dans ProcessMind à l’aide d’une URL pré-signée.

Étapes :

1. Récupérez une URL d’importation pré-signée auprès de l’API.
2. Lisez le fichier local sur le disque.
3. Importez le fichier à l’aide d’une requête HTTP PUT vers l’URL pré-signée.

Configuration :

• Lors de l’appel à uploadFile(), renseignez votre clé API, tenantId, datatableId et filePath.
• L’URL de base de l’API est définie sur 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 
};

Exemple Python : importer un fichier CSV local

Importe un fichier CSV local vers une API distante à l’aide d’une URL pré-signée.

Étapes :

1. Récupérez une URL d’importation pré-signée auprès de l’API.
2. Lisez le fichier local sur le disque.
3. Importez le fichier à l’aide d’une requête HTTP PUT vers l’URL pré-signée.

Configuration :

• Modifiez api_key, tenant_id, datatable_id et file_path selon vos besoins.

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

Pagination

Les points de terminaison de liste acceptent les paramètres de requête limit et offset et renvoient un **tableau JSON seul **, sans enveloppe ni nombre total :

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

Pour parcourir tous les résultats, continuez à envoyer des requêtes avec offset += limit jusqu’à ce que le tableau de réponse contienne moins d’éléments que la valeur demandée pour limit (ou soit vide). Les valeurs supérieures au maximum sont rejetées avec 400. Les points de terminaison de données versionnés (jeux de données, versions, webhooks) suivent la même règle. Les deux listes de tables de données limitent limit à 250.

Versionnement et dépréciation

• Toutes les routes sont versionnées sous /v1 ; les changements incompatibles sont publiés dans une nouvelle version plutôt que d’altérer silencieusement /v1.
• Les modifications et suppressions de routes sont annoncées dans les notes de version.
• Les changements importants visibles par les clients figurent toujours dans le journal des modifications. Abonnez-vous ou consultez-le avant de mettre à niveau des clients API dont la version est verrouillée.

Étapes suivantes

• Référence de l’API : documentation complète de tous les points de terminaison et des formats de requête et de réponse
• Exemples GitHub : exemples téléchargeables et bibliothèques clientes
• Obtenir votre clé API : comment obtenir et gérer votre clé API