Utilice la Engage API para enviar y extraer datos hacia y desde Engage.

Extremos

Actualmente, la Engage API admite los siguientes puntos de conexión.
Operación Descripción
Read Dashboard Data Obtiene valores de datos globales de todos los proyectos incluidos en los informes del panel y todas las ideas de flujo de trabajo.
Create File Crea una nueva idea de proyecto o un proyecto que no es de flujo de trabajo.
Nota

Recomendado sobre Create Idea.

Create Idea Crea una nueva idea de proyecto.
Nota

Para ampliar la funcionalidad, utilice Create File.

Get Job Status Obtiene la información de estado de un trabajo en segundo plano especificado.

Leer los datos del panel

La Read Dashboard Data operación recupera los datos globales del proyecto para todos los proyectos incluidos en los informes del panel y todas las ideas de flujo de trabajo. Este punto de conexión usa el OData estándar para consultar datos.

No se admiten las siguientes OData funciones:
  • $filter
  • $apply
  • $orderby
  • $select
  • $expand
  • $count
  • $skip
  • $top

Pedir

La Read Dashboard Data solicitud puede interpretarse de la siguiente manera. Reemplácelo subscription-id con el ID de su suscripción.
Método URL de solicitud
GET https://engage.minitab.com/api/v1/subscription-id/export/odata
Encabezados de solicitud
Header Descripción
Authorization Obligatorio. Proporcione un token de API a través del Bearer esquema de autorización.
Solicitud de muestra
Request: GET https://engage.minitab.com/api/v1/4906fcd496d94f738304dfcde754000a/export/odata HTTP/1.1 Headers: Authorization: Bearer token

Respuesta

La respuesta incluye un HTTP código de estado, un conjunto de encabezados de respuesta y un cuerpo.

Código de estado
Una solicitud correcta devuelve el código de estado 200 (OK).
Encabezados de respuesta
La respuesta para esta operación incluye los siguientes encabezados. La respuesta también puede incluir encabezados estándar HTTP adicionales. Todos los encabezados estándar se ajustan a la extensión especificación del protocolo HTTP/1.1.
Header Descripción
Content-Type Indica el tipo de medio del cuerpo de la respuesta.
Cuerpo de respuesta
El cuerpo de la respuesta contiene los datos solicitados en JSON formato, estructurados según la OData norma. A continuación se muestra un ejemplo de la respuesta:
{ "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" } ] }
Ejemplo de respuesta
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" } ] }

Crear archivo

La operación Create File inicia un trabajo para crear una nueva idea de proyecto o un proyecto que no sea de flujo de trabajo en la suscripción.

Pedir

Puede construir la solicitud Create File como se muestra aquí. Reemplace subscription-id por el identificador de su suscripción.
Método URL de solicitud
POST https://engage.minitab.com/api/v2/subscription-id/Item
Encabezados de solicitud
Header Descripción
Authorization Obligatorio. Proporcione un token de API a través del esquema de autorización del Bearer. Se requiere que el token tenga el Create Idea permiso.
Content-Type Obligatorio. Debe ser application/json.
Cuerpo de la solicitud
El cuerpo de la solicitud consta de un objeto JSON con tres propiedades obligatorias: FileName, ProjectTemplateName y CreateFileType.
{ "NombreDeArchivo": "nombre de la idea" "ProjectTemplateName":"nombre de la plantilla de proyecto que se utilizará para el proyecto", #Only necesario para proyectos que no son de flujo de trabajo. El nombre debe coincidir con una plantilla de proyecto de la suscripción. "CreateFileType": 0, #(0 idea, 1 proyecto sin flujo de trabajo) }
Puede incluir cualquiera de las siguientes opciones.
  • OwnerEmail: La dirección de correo electrónico del usuario que será el propietario de este nuevo archivo.
  • IncludeInDashboard: Un valor verdadero o falso para invalidar el valor predeterminado en la configuración de la suscripción.
  • Data: Objeto para establecer los valores de los campos de datos en el archivo. Data constan de nombres de código de categoría de un solo valor asignados a objetos de nombres de código y valores de campo.
  • TableData: Objeto para establecer los valores de los datos de la tabla en el archivo. TableData consta de nombres de código de categoría de tabla de datos asignados a objetos de nombres de código de campo y conjuntos de valores.
    • Para las ideas, los datos de la tabla deben estar en el formulario de la idea.
    • En los datos de tabla, cuando el número de valores de un campo es desigual, los campos con menos valores se establecen en sus valores predeterminados en las filas restantes.
    • Utilice null para obtener un valor en blanco.
    • Algunas tablas de datos tienen campos obligatorios, como [teammember / name]. Cuando los campos obligatorios están vacíos, no se crea un proyecto.
  • NotificationRecipients: Direcciones de correo electrónico para recibir un mensaje cuando la operación Create File se realiza correctamente o se produce un error.
{ "NombreDeArchivo": "nombre de la idea", "ProjectTemplateName":"Simplemente hazlo", "CreateFileType":1, "OwnerEmail":"user@company.com", "IncludeInDashboard":false, "NotificationRecipients": ["fmae@mortgage.gov", "user@domain.com"], "Datos": { "Resumen del proyecto": { "belt_level": "Cinturón Verde", "critical_to": "Texto largo\r\ncon\r\nnewlines" }, "annualized_financial": { "annualized_actual_hard_savings": 100 } } "TableData":{ "miembro del equipo":{ "nombre":["John Q. Public","Fannie Mae","Freddie Mac"], "role":["Líder del proyecto",null,"Agente hipotecario"], "email":[null,"fmae@mortgage.gov"] }, "tarea":{ "asunto":["refinanciamiento","originación"] "fecha de inicio":["2025-04-24"] } } } }
Nota

Para ver la lista de campos de datos válidos y nombres de categorías disponibles para compartir, los arquitectos de datos pueden descargar un archivo CSV desde la Configuración pestaña del archivo Engage web app.

Nota

Para establecer el nombre de un miembro del equipo en un rol de equipo (Patrocinador, Campeón, Analista financiero, etc.), conecte el campo Miembro del equipo/Rol con el campo Rol . En el ejemplo anterior, el Team Role / Project Leader se establecerá en "John Q. Public".

Nota

La operación Create File no admite la configuración de valores de datos para todos los campos. Si se intenta proporcionar datos para fórmulas, texto enriquecido o campos internos, se producirá un error.

Solicitud de muestra
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] } } }

Respuesta

La respuesta incluye un HTTP código de estado, un conjunto de encabezados de respuesta y un cuerpo.

Código de estado
Una operación correcta devuelve el código de estado 202 (Aceptado).
Encabezados de respuesta
La respuesta para esta operación incluye los siguientes encabezados. La respuesta también puede incluir encabezados estándar HTTP adicionales. Todos los encabezados estándar cumplen con la especificación del protocolo HTTP/1.1.
Header Descripción
Location Una dirección URL que se puede utilizar para recuperar el estado del trabajo.
Cuerpo de respuesta
La respuesta de la Create File operación contiene el identificador del trabajo que creará el proyecto o la idea. El JSON formato se muestra a continuación:
{ "JobId": "479f6bea-360f-40ba-be0a-bd06c032c4fb" }

Crear idea

La Create Idea operación inicia un trabajo para crear una idea de proyecto en la suscripción.
Nota

Al crear una nueva idea de proyecto, puede usar Create Idea, pero se recomienda Create File .

Pedir

Puede crear la solicitud Create Idea como se muestra aquí. Reemplácelo subscription-id con el ID de su suscripción.
Método URL de solicitud
POST https://engage.minitab.com/api/v1/subscription-id/Item
Encabezados de solicitud
Header Descripción
Authorization Obligatorio. Proporcione un token de API a través del Bearer esquema de autorización. Se requiere que el token tenga el Create Idea permiso.
Content-Type Obligatorio. Debe ser application/json.
Cuerpo de la solicitud
El cuerpo de la solicitud consta de un JSON objeto con una propiedad requerida FileName.
{ "FileName": "name of idea" }
Opcionalmente, puede incluir un Data objeto para establecer los valores de los campos de datos en la idea. Los datos constan de nombres de código de categoría de un solo valor asignados a objetos de nombres de código y valores de campo.
{ "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 } } }
Nota

Para ver la lista de campos de datos válidos y nombres de categorías disponibles para compartir, los arquitectos de datos pueden descargar un archivo CSV desde la Configuración pestaña del archivo Engage web app.

Nota

Solo se pueden especificar en la solicitud de Create Idea operación los campos de datos que se comparten con los controles del formulario de idea. Además, no se admite la especificación de campos de texto enriquecido, fórmula, solo lectura o tabla de datos. Si se intenta proporcionar datos para los campos no compartidos con los controles de los campos de formulario de idea o texto enriquecido, fórmula, solo lectura o tabla de datos, se producirá un error.

Solicitud de muestra
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 } } }

Respuesta

La respuesta incluye un HTTP código de estado, un conjunto de encabezados de respuesta y un cuerpo.

Código de estado
Una operación correcta devuelve el código de estado 202 (Aceptado).
Encabezados de respuesta
La respuesta para esta operación incluye los siguientes encabezados. La respuesta también puede incluir encabezados estándar HTTP adicionales. Todos los encabezados estándar cumplen con la especificación del protocolo HTTP/1.1.
Header Descripción
Location Una dirección URL que se puede utilizar para recuperar el estado del trabajo.
Cuerpo de respuesta
La respuesta de la Create Idea operación contiene el identificador del trabajo que creará la idea de proyecto. El JSON formato se muestra a continuación:
{ "JobId": "479f6bea-360f-40ba-be0a-bd06c032c4fb" }
Ejemplo de respuesta
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" }

Obtener el estado del trabajo

La Get Job Status operación recupera el estado del trabajo especificado.

Pedir

La solicitud Obtener estado del trabajo se puede construir de la siguiente manera. Reemplácelo subscription-id por el identificador de su suscripción y job-id por un identificador de trabajo válido.
Método URL de solicitud
GET https://engage.minitab.com/api/v1/subscription-id/job/job-id
Encabezados de solicitud
Header Descripción
Authorization Obligatorio. Proporcione un token de API a través del Bearer esquema de autorización.
Solicitud de muestra
Request: GET https://engage.minitab.com/api/v1/4906fcd496d94f738304dfcde754000a/job/479f6bea-360f-40ba-be0a-bd06c032c4fb HTTP/1.1 Headers: Authorization: Bearer token

Respuesta

La respuesta incluye un código de HTTP estado y un cuerpo.

Código de estado
Una solicitud correcta devuelve el código de estado 200 (OK).
Cuerpo de respuesta
La respuesta de la Get Job Status operación contiene una Status propiedad entera que representa los distintos estados posibles de un trabajo, como se muestra en el ejemplo siguiente.
{ "Status": 1 }
Estado del trabajo Descripción
0 El trabajo aún no ha comenzado
1 El trabajo ha comenzado; en curso
2 El trabajo se ha completado
3 El trabajo ha fallado
4 No se pudo encontrar el trabajo
5 El trabajo se ha cancelado
Ejemplo de respuesta
Response Status: HTTP/1.1 200 OK Response headers: Content-Type: application/json Response Body: { "Status": 2 }