Présentation de l’API

Comment effectuer des appels d’API vers 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, avec les formats des requêtes et des réponses, reportez-vous à la référence de l’API.

Pour obtenir 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 d’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, est disponible au format OpenAPI 3.1 à l’adresse suivante :

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

Authentification

Toutes les requêtes d’API doivent inclure votre clé d’API dans l’en-tête x-api-key :

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

Vous pouvez obtenir la clé d’API dans les paramètres de votre compte ProcessMind. Consultez Obtenir votre clé d’API pour connaître la procédure.

Codes d’état

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

Concepts clés

• apiKey : votre jeton d’authentification pour toutes les requêtes d’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 datatable précise pour les opérations sur les données. Cette valeur est disponible via l’option Obtenir l’identifiant de la datatable dans le menu des paramètres du jeu de données, au sein de ProcessMind.

Ce que vous pouvez faire

L’API ProcessMind vous permet de :

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

Exemples courants

Voici des exemples pratiques montrant comment effectuer des opérations courantes avec l’API ProcessMind.

Obtenir une URL d’importation présignée

Pour importer un fichier dans une datatable, obtenez d’abord 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 tenant :

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

Obtenir les informations d’un tenant

Récupérez les informations de votre tenant :

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

Créer un processus

Créez un processus dans votre tenant :

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 datatable à 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 tenant

Ajoutez un utilisateur à votre tenant :

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 dans le corps de la requête (isAdminInTenant, access, isDashboardViewer) sont pris en compte tels quels. Les points de terminaison de gestion des utilisateurs offrent une interface complète d’administration du tenant. Vous devez donc fournir uniquement des clés API avec un périmètre d’écriture aux appelants auxquels vous accordez des droits d’administration. L’API système n’envoie aucun e-mail d’invitation ; vous êtes responsable de l’intégration de l’utilisateur.

Importer des fichiers

La procédure générale pour importer un fichier dans ProcessMind est la suivante :

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

Voici un exemple simplifié utilisant 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 à être copiés-collés, dans différents langages.

Exemple Bash : importer un fichier

Script Bash minimal permettant d’importer un fichier dans ProcessMind à l’aide de deux appels curl, avec des espaces réservés pour toutes les valeurs

#!/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 depuis le disque.
3. Importez le fichier vers l’URL présignée à l’aide de HTTP PUT.

Configuration :

• Indiquez votre clé d’API, tenantId, datatableId et filePath lors de l’appel à uploadFile().
• 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 depuis le disque.
3. Importez le fichier vers l’URL présignée à l’aide de HTTP PUT.

Configuration :

• Mettez à jour 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 brut, 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 limit demandée, ou qu’il 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, datatables, versions et webhooks, suivent la même convention.

Versionnement et obsolescence

• Toutes les routes sont versionnées sous /v1 ; les changements incompatibles sont publiés dans une nouvelle version au lieu de modifier silencieusement /v1.
• Les obsolescences sont annoncées dans le journal des modifications et sur cette page au moins 6 mois avant la suppression d’une route, et les routes obsolètes continuent de fonctionner pendant cette période.
• Les réponses des routes obsolètes contiennent un en-tête Sunset indiquant la date de suppression, ainsi que Deprecation: true.
• Les changements importants visibles par les clients sont toujours répertoriés dans le journal des modifications ; abonnez-vous ou consultez cette page avant de mettre à niveau des clients d’API dont la version est figée.

Étapes suivantes

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