Utiliser l’API Engage

Utilisez l’API Engage pour envoyer et extraire des données vers et depuis Engage.

Terminaison

L’API Engage prend actuellement en charge les points de terminaison suivants.
Fonctionnement Description
Read Dashboard Data Obtient les valeurs de données globales de tous les projets inclus dans les rapports de tableau de bord et toutes les idées de flux de travail.
Create File Crée une idée de projet ou un projet hors flux de travail.
Remarque

Recommandé plutôt que Create Idea.

Create Idea Crée une nouvelle idée de projet.
Remarque

Pour bénéficier de fonctionnalités étendues, utilisez Create File.

Get Job Status Obtient les informations d’état d’un travail d’arrière-plan spécifié.

Lire les données du tableau de bord

L’opération Read Dashboard Data récupère les données globales de tous les projets inclus dans les rapports de tableau de bord et toutes les idées de flux de travail. Ce point de terminaison utilise la OData norme pour l’interrogation des données.

Les fonctions suivantes OData ne sont pas prises en charge :
  • $filter
  • $apply
  • $orderby
  • $select
  • $expand
  • $count
  • $skip
  • $top

Demander

La Read Dashboard Data demande peut être formulée comme suit. Remplacez subscription-id par l’ID de votre abonnement.
Méthode URL de la demande
GET https://engage.minitab.com/api/v1/subscription-id/export/odata
En-têtes de requête
En-tête Description
Authorization Obligatoire. Fournissez un jeton API via le schéma d’autorisation Bearer.
Demande d’échantillon
Request: GET https://engage.minitab.com/api/v1/4906fcd496d94f738304dfcde754000a/export/odata HTTP/1.1 Headers: Authorization: Bearer token

Réponse

La réponse comprend un code d’état HTTP, un ensemble d’en-têtes de réponse et un corps.

Code d’état
Une demande réussie renvoie le code d’état 200 (OK).
En-têtes de réponse
La réponse de cette opération comprend les en-têtes suivants. La réponse peut également inclure des en-têtes standard HTTP supplémentaires. Tous les en-têtes standard sont conformes à la norme spécification du protocole HTTP/1.1.
En-tête Description
Content-Type Indique le type de support du corps de la réponse.
Corps de la réponse
Le corps de la réponse contient les données demandées dans JSON un format structuré conformément à la OData norme. Voici un exemple de réponse :
{ "value": [ { "ProjectId": "12345", "ProjectName": "Project A", "Status": "Active", "StartDate": "2025-01-01", "EndDate": "2025-12-31" }, { "ProjectId": "67890", "ProjectName": "Project B", "Status": "Completed", "StartDate": "2024-01-01", "EndDate": "2024-12-31" } ] }
Exemple de réponse
Response Status: HTTP/1.1 200 OK Response headers: Content-Type: application/json Response Body: { "value": [ { "ProjectId": "12345", "ProjectName": "Project A", "Status": "Active", "StartDate": "2025-01-01", "EndDate": "2025-12-31" }, { "ProjectId": "67890", "ProjectName": "Project B", "Status": "Completed", "StartDate": "2024-01-01", "EndDate": "2024-12-31" } ] }

Créer un fichier

L’opération Create File lance une tâche pour créer une idée de projet ou un projet hors flux de travail dans votre abonnement.

Demander

Vous pouvez créer la demande Create File comme indiqué ici. Remplacez subscription-id par l’ID de votre abonnement.
Méthode URL de la demande
POST https://engage.minitab.com/api/v2/subscription-id/Item
En-têtes de requête
En-tête Description
Authorization Obligatoire. Fournir un jeton API via le schéma d’autorisation Bearer. Le jeton doit disposer de l’autorisation Create Idea.
Content-Type Obligatoire. Doit être application/json.
Corps de la requête
Le corps de la demande se compose d’un objet JSON avec trois propriétés obligatoires : FileName, ProjectTemplateName et CreateFileType.
{ « FileName » : « nom de l’idée » « ProjectTemplateName » :"nom du modèle de projet à utiliser pour le projet », #Only requis pour les projets sans flux de travail. Le nom doit correspondre à un modèle de projet de votre abonnement. « CreateFileType » : 0, #(0 idée, 1 projet sans flux de travail) }
Vous pouvez inclure l’une des options suivantes.
  • OwnerE-mail: L’adresse e-mail de l’utilisateur propriétaire de ce nouveau fichier.
  • IncludeInDashboard: Valeur true ou false pour remplacer la valeur par défaut dans les paramètres d’abonnement.
  • Data: Objet permettant de définir les valeurs des champs de données dans le fichier. Data se composent de noms de code de catégorie à valeur unique associés à des objets de noms de code et de valeurs de champ.
  • TableData: Objet permettant de définir les valeurs de données de table dans le fichier. TableData se compose de noms de code de catégories de tables de données associés à des objets de noms de code de champs et d’ensembles de valeurs.
    • Pour les idées, les données de la table doivent se trouver sur le formulaire d’idée.
    • Dans les données de table, lorsque le nombre de valeurs d’un champ est inégal, les champs avec moins de valeurs sont définis sur leurs valeurs par défaut dans les lignes restantes.
    • Utilisez null pour obtenir une valeur vide.
    • Certaines tables de données ont des champs obligatoires, tels que [teammember / name]. Lorsque les champs obligatoires sont vides, aucun projet n’est créé.
  • NotificationRecipients: Adresses e-mail pour recevoir un message en cas de réussite ou d’échec de l’opération Create File.
{ « FileName » : « nom de l’idée », « ProjectTemplateName » :"Fais-le », « CreateFileType » :1, « OwnerEmail » :"user@company.com », « IncludeInDashboard » :false, « NotificationRecipients » : ["fmae@mortgage.gov », « user@domain.com"], « Données » : { « projectsummary » : { « belt_level » : « Ceinture verte », « critical_to » : « Texte long\r\navec\r\nnouvelles lignes » }, « annualized_financial » : { « annualized_actual_hard_savings » : 100 } } } « TableData » :{ « teammember » :{ « name » :["John Q. Public »,"Fannie Mae »,"Freddie Mac"], « role » :["Chef de projet »,null,"Courtier en hypothèques"], « email » :[null,"fmae@mortgage.gov"] }, « task » :{ « subject » :["refinance »,"origination"] « startdate » :["2025-04-24"] } } }
Remarque

Pour afficher la liste des champs de données valides et des noms de catégories disponibles pour le partage, les architectes de données peuvent télécharger un fichier CSV à partir de l’onglet Paramètres Engage web app.

Remarque

Pour définir le nom d’un membre de l’équipe sur un rôle d’équipe (Sponsor, Champion, Analyste financier, etc.), connectez le champ Membre de l’équipe / Rôle au champ Rôle. Dans l’exemple précédent, le rôle d’équipe / chef de projet sera défini sur « John Q. Public ».

Remarque

L’opération Create File ne prend pas en charge la définition de valeurs de données pour tous les champs. Toute tentative de fournir des données pour une formule, du texte enrichi ou des champs internes entraînera une erreur.

Demande d’échantillon
Request: POST https://engage.minitab.com/api/v2/4906fcd496d94f738304dfcde754000a/Item HTTP/1.1 Headers: Authorization: Bearer token Content-Type: application/json Content-Length: 785 Body: { "FileName": "file name", "ProjectTemplateName":"DMAIC Project", "CreateFileType": 1, "OwnerEmail":"user@yourcompany.com", "IncludeInDaashboard":true, "Data": { "_category1": { "_text_field": "text value", "_date_field": "2025-03-20", "_number_field": 3.1415 }, "_category2": { "_text_field": "text value", "_date_field": "2025-03-20", "_number_field": 3.1415 } }, "TableData": { "_tableCategory1": { "_text_field": ["text value","text_value2","text_value"], "_date_field": ["2025-03-20","2025-04-21","2024-03-20"], "_number_field": [3.1415,2.73,1.414] }, "_tableCategory2": { "_text_field": ["text value",null,"text_3"], "_date_field": ["2025-03-20","2025-08-23"], "_number_field": [3.1415,null] } } }

Réponse

La réponse comprend un code d’état HTTP, un ensemble d’en-têtes de réponse et un corps.

Code d’état
Une opération réussie renvoie le code d’état 202 (Accepté).
En-têtes de réponse
La réponse de cette opération comprend les en-têtes suivants. La réponse peut également inclure des en-têtes standard HTTP supplémentaires. Tous les en-têtes standard sont conformes à la spécification du protocole HTTP/1.1.
En-tête Description
Location URL qui peut être utilisée pour récupérer l’état de la tâche.
Corps de la réponse
La réponse de l’opération Create File contient l’identificateur de la tâche qui créera le projet ou l’idée. Le JSON format est illustré ci-dessous :
{ "JobId": "479f6bea-360f-40ba-be0a-bd06c032c4fb" }

Créer une idée

L’opération Create Idea lance un travail pour créer une idée de projet dans votre abonnement.
Remarque

Lors de la création d’une nouvelle idée de projet, vous pouvez utiliser Create Idea, mais il est recommandé Create File.

Demander

Vous pouvez créer la demande Create Idea comme indiqué ici. Remplacez subscription-id par l’ID de votre abonnement.
Méthode URL de la demande
POST https://engage.minitab.com/api/v1/subscription-id/Item
En-têtes de demande
En-tête Description
Authorization Obligatoire. Fournissez un jeton API via le schéma d’autorisation Bearer. Le jeton doit disposer de l’autorisation Create Idea.
Content-Type Obligatoire. Doit être application/json.
Corps de la requête
Le corps de la demande se compose d’un JSON objet avec une propriété FileName obligatoire.
{ "FileName": "name of idea" }
Vous pouvez éventuellement inclure un Data objet pour définir les valeurs des champs de données dans l’idée. Les données se composent de noms de code de catégorie à valeur unique associés à des objets de noms de code et de valeurs de champ.
{ "FileName": "name of idea", "Data": { "projectsummary": { "belt_level": "Green Belt", "critical_to": "Long text\r\nwith\r\nnewlines" }, "annualized_financial": { "annualized_actual_hard_savings": 100 } } }
Remarque

Pour afficher la liste des champs de données valides et des noms de catégories disponibles pour le partage, les architectes de données peuvent télécharger un fichier CSV à partir de l’onglet Paramètres Engage web app.

Remarque

Seuls les champs de données partagés avec les contrôles du formulaire d’idée peuvent être spécifiés dans la demande d’opération Create Idea. De plus, la spécification de champs de texte enrichi, de formule, en lecture seule ou de table de données n’est pas prise en charge. Toute tentative de fourniture de données pour des champs non partagés avec des contrôles sur le formulaire d’idée ou des champs de texte enrichi, de formule, en lecture seule ou de table de données entraînera une erreur.

Demande d’échantillon
Request: POST https://engage.minitab.com/api/v1/4906fcd496d94f738304dfcde754000a/Item HTTP/1.1 Headers: Authorization: Bearer token Content-Type: application/json Content-Length: 287 Body: { "FileName": "idea name", "Data": { "_category1": { "_text_field": "text value", "_date_field": "2025-03-20", "_number_field": 3.1415 }, "_category2": { "_text_field": "text value", "_date_field": "2025-03-20", "_number_field": 3.1415 } } }

Réponse

La réponse comprend un code d’état HTTP, un ensemble d’en-têtes de réponse et un corps.

Code d’état
Une opération réussie renvoie le code d’état 202 (Accepté).
En-têtes de réponse
La réponse de cette opération comprend les en-têtes suivants. La réponse peut également inclure des en-têtes standard HTTP supplémentaires. Tous les en-têtes standard sont conformes à la spécification du protocole HTTP/1.1.
En-tête Description
Location URL qui peut être utilisée pour récupérer l’état de la tâche.
Corps de la réponse
La réponse de l’opération Create Idea contient l’identificateur de la tâche qui créera l’idée de projet. Le JSON format est illustré ci-dessous :
{ "JobId": "479f6bea-360f-40ba-be0a-bd06c032c4fb" }
Exemple de réponse
Response Status: HTTP/1.1 202 ACCEPTED Response headers: Location: /api/v1/4906fcd496d94f738304dfcde754000a/job/479f6bea-360f-40ba-be0a-bd06c032c4fb Content-Type: application/json Response Body: { "JobId": "479f6bea-360f-40ba-be0a-bd06c032c4fb" }

Obtenir l’état de la tâche

L’opération Get Job Status récupère l’état du travail spécifié.

Demander

La demande Get Job Status peut être construite comme suit. Remplacez-le subscription-id par l’ID de votre abonnement et job-id par un identificateur de tâche valide.
Méthode URL de la demande
GET https://engage.minitab.com/api/v1/subscription-id/job/job-id
En-têtes de requête
En-tête Description
Authorization Obligatoire. Fournissez un jeton API via le schéma d’autorisation Bearer.
Demande d’échantillon
Request: GET https://engage.minitab.com/api/v1/4906fcd496d94f738304dfcde754000a/job/479f6bea-360f-40ba-be0a-bd06c032c4fb HTTP/1.1 Headers: Authorization: Bearer token

Réponse

La réponse comprend un code d’état HTTP et un corps.

Code d’état
Une demande réussie renvoie le code d’état 200 (OK).
Corps de la réponse
La réponse de l’opération Get Job Status contient une Status propriété integer représentant les différents états possibles d’un travail, comme illustré dans l’exemple suivant.
{ "Status": 1 }
Statut du travail Description
0 Poste pas encore commencé
1 Le travail a commencé ; en cours
2 Le travail est terminé
3 Échec de la tâche
4 Job n’a pas pu être trouvé
5 Le travail a été annulé
Exemple de réponse
Response Status: HTTP/1.1 200 OK Response headers: Content-Type: application/json Response Body: { "Status": 2 }