Gestión de Investigaciones

Administre investigaciones dentro de proyectos mindzieStudio. Cree, recupere, actualice y elimine investigaciones que contienen cuadernos y definen flujos de trabajo de análisis de minería de procesos.

Pruebas de Conectividad

Ping No Autenticado

GET /api/{tenantId}/{projectId}/investigation/unauthorized-ping

Punto final de prueba que no requiere autenticación. Úselo para verificar la conectividad de red.

Respuesta

Ping Successful

Ping Autenticado

GET /api/{tenantId}/{projectId}/investigation/ping

Punto final de ping autenticado para verificar el acceso a la API para un inquilino y proyecto específicos.

Respuesta (200 OK)

Ping Successful (tenant id: {tenantId})

---

Listar Todas las Investigaciones

GET /api/{tenantId}/{projectId}/investigation

Recupera una lista paginada de todas las investigaciones dentro del proyecto especificado.

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
tenantId	GUID	Sí	Identificador del inquilino
projectId	GUID	Sí	Identificador del proyecto

Parámetros de Consulta

Parámetro	Tipo	Por defecto	Descripción
page	entero	1	Número de página para paginación
pageSize	entero	50	Número de elementos por página (máximo recomendado: 100)

Respuesta (200 OK)

{
  "investigations": [
    {
      "investigationId": "11111111-2222-3333-4444-555555555555",
      "projectId": "87654321-4321-4321-4321-210987654321",
      "investigationName": "Order Analysis",
      "investigationDescription": "Process mining analysis of order workflow",
      "datasetId": "12345678-1234-1234-1234-123456789012",
      "dateCreated": "2024-01-15T10:30:00Z",
      "dateModified": "2024-01-20T14:45:00Z",
      "createdBy": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "modifiedBy": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "investigationOrder": 1.0,
      "isUsedForOperationCenter": false,
      "investigationFolderId": null,
      "notebookCount": 3
    }
  ],
  "totalCount": 5,
  "page": 1,
  "pageSize": 50
}

Campos del Objeto Investigación

Campo	Tipo	Descripción
investigationId	GUID	Identificador único para la investigación
projectId	GUID	Proyecto al que pertenece esta investigación
investigationName	string	Nombre para mostrar de la investigación
investigationDescription	string	Descripción de la investigación
datasetId	GUID	Conjunto de datos que esta investigación analiza
dateCreated	datetime	Fecha de creación de la investigación
dateModified	datetime	Fecha de última modificación de la investigación
createdBy	GUID	Usuario que creó la investigación
modifiedBy	GUID	Usuario que modificó por última vez la investigación
investigationOrder	decimal	Orden de visualización dentro del proyecto
isUsedForOperationCenter	boolean	Indica si se usa para monitoreo en tiempo real
investigationFolderId	GUID	Carpeta opcional para organización
notebookCount	entero	Número de cuadernos en la investigación

---

Obtener Detalles de la Investigación

GET /api/{tenantId}/{projectId}/investigation/{investigationId}

Recupera información detallada para una investigación específica.

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
tenantId	GUID	Sí	Identificador del inquilino
projectId	GUID	Sí	Identificador del proyecto
investigationId	GUID	Sí	Identificador de la investigación

Respuesta (200 OK)

Misma estructura que el objeto de investigación en la respuesta de lista.

Respuestas de Error

No Encontrado (404):

{
  "error": "Investigation not found",
  "investigationId": "11111111-2222-3333-4444-555555555555"
}

---

Crear Investigación

POST /api/{tenantId}/{projectId}/investigation

Crea una nueva investigación vinculada a un conjunto de datos existente. Se crea automáticamente un cuaderno principal.

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
tenantId	GUID	Sí	Identificador del inquilino
projectId	GUID	Sí	Identificador del proyecto

Cuerpo de la Solicitud

{
  "investigationName": "Order Analysis",
  "investigationDescription": "Process mining analysis of order workflow",
  "datasetId": "12345678-1234-1234-1234-123456789012",
  "isUsedForOperationCenter": false
}

Campos de la Solicitud

Campo	Tipo	Requerido	Descripción
investigationName	string	Sí	Nombre de la investigación
investigationDescription	string	No	Descripción de la investigación
datasetId	GUID	Sí	Conjunto de datos a analizar
isUsedForOperationCenter	boolean	No	Habilitar para monitoreo en tiempo real (por defecto: false)

Respuesta (201 Created)

Devuelve el objeto de la investigación creada (misma estructura que Obtener Investigación).

Respuestas de Error

Solicitud Incorrecta (400):

{
  "error": "Dataset not found with ID '12345678-1234-1234-1234-123456789012'"
}

---

Actualizar Investigación

PUT /api/{tenantId}/{projectId}/investigation/{investigationId}

Actualiza las propiedades de una investigación existente. Todos los campos son opcionales.

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
tenantId	GUID	Sí	Identificador del inquilino
projectId	GUID	Sí	Identificador del proyecto
investigationId	GUID	Sí	Identificador de la investigación

Cuerpo de la Solicitud

{
  "investigationName": "Updated Analysis Name",
  "investigationDescription": "Updated description",
  "isUsedForOperationCenter": true
}

Campos de la Solicitud

Campo	Tipo	Requerido	Descripción
investigationName	string	No	Nuevo nombre de la investigación
investigationDescription	string	No	Nueva descripción
isUsedForOperationCenter	boolean	No	Activar/desactivar centro de operaciones

Respuesta (200 OK)

Devuelve el objeto de la investigación actualizada.

Respuestas de Error

No Encontrado (404):

{
  "error": "Investigation not found",
  "investigationId": "11111111-2222-3333-4444-555555555555"
}

---

Eliminar Investigación

DELETE /api/{tenantId}/{projectId}/investigation/{investigationId}

Elimina permanentemente una investigación y TODOS los cuadernos asociados.

ADVERTENCIA: Esta es una operación DESTRUCTIVA que NO puede deshacerse.

La Eliminación en Cascada Incluye

• Todos los cuadernos en la investigación
• Todas las configuraciones de bloques
• Todo el historial de ejecuciones
• Todos los resultados de análisis

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
tenantId	GUID	Sí	Identificador del inquilino
projectId	GUID	Sí	Identificador del proyecto
investigationId	GUID	Sí	Identificador de la investigación

Respuesta (204 No Content)

Sin cuerpo de respuesta en caso de eliminación exitosa.

Respuestas de Error

No Encontrado (404):

{
  "error": "Investigation not found",
  "investigationId": "11111111-2222-3333-4444-555555555555"
}

---

Ejemplos de Implementación

cURL

# Listar todas las investigaciones
curl -X GET "https://your-mindzie-instance.com/api/12345678-1234-1234-1234-123456789012/87654321-4321-4321-4321-210987654321/investigation" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Obtener detalles de una investigación
curl -X GET "https://your-mindzie-instance.com/api/12345678-1234-1234-1234-123456789012/87654321-4321-4321-4321-210987654321/investigation/11111111-2222-3333-4444-555555555555" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Crear una nueva investigación
curl -X POST "https://your-mindzie-instance.com/api/12345678-1234-1234-1234-123456789012/87654321-4321-4321-4321-210987654321/investigation" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "investigationName": "Q4 Analysis",
    "investigationDescription": "Quarterly order analysis",
    "datasetId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }'

# Actualizar una investigación
curl -X PUT "https://your-mindzie-instance.com/api/12345678-1234-1234-1234-123456789012/87654321-4321-4321-4321-210987654321/investigation/11111111-2222-3333-4444-555555555555" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "investigationName": "Q4 Analysis - Final",
    "investigationDescription": "Updated description"
  }'

# Eliminar una investigación (¡PRECAUCIÓN: Irreversible!)
curl -X DELETE "https://your-mindzie-instance.com/api/12345678-1234-1234-1234-123456789012/87654321-4321-4321-4321-210987654321/investigation/11111111-2222-3333-4444-555555555555" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Python

import requests

TENANT_ID = '12345678-1234-1234-1234-123456789012'
PROJECT_ID = '87654321-4321-4321-4321-210987654321'
BASE_URL = 'https://your-mindzie-instance.com'

class InvestigationManager:
    def __init__(self, token):
        self.headers = {
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }

    def list_investigations(self, page=1, page_size=50):
        """Listar todas las investigaciones en el proyecto."""
        url = f'{BASE_URL}/api/{TENANT_ID}/{PROJECT_ID}/investigation'
        params = {'page': page, 'pageSize': page_size}
        response = requests.get(url, headers=self.headers, params=params)
        response.raise_for_status()
        return response.json()

    def get_investigation(self, investigation_id):
        """Obtener detalles de una investigación."""
        url = f'{BASE_URL}/api/{TENANT_ID}/{PROJECT_ID}/investigation/{investigation_id}'
        response = requests.get(url, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def create_investigation(self, name, dataset_id, description='', is_operation_center=False):
        """Crear una nueva investigación."""
        url = f'{BASE_URL}/api/{TENANT_ID}/{PROJECT_ID}/investigation'
        payload = {
            'investigationName': name,
            'investigationDescription': description,
            'datasetId': dataset_id,
            'isUsedForOperationCenter': is_operation_center
        }
        response = requests.post(url, json=payload, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def update_investigation(self, investigation_id, name=None, description=None, is_operation_center=None):
        """Actualizar una investigación existente."""
        url = f'{BASE_URL}/api/{TENANT_ID}/{PROJECT_ID}/investigation/{investigation_id}'
        payload = {}
        if name:
            payload['investigationName'] = name
        if description is not None:
            payload['investigationDescription'] = description
        if is_operation_center is not None:
            payload['isUsedForOperationCenter'] = is_operation_center
        response = requests.put(url, json=payload, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def delete_investigation(self, investigation_id):
        """Eliminar una investigación (¡PRECAUCIÓN: Irreversible!)."""
        url = f'{BASE_URL}/api/{TENANT_ID}/{PROJECT_ID}/investigation/{investigation_id}'
        response = requests.delete(url, headers=self.headers)
        response.raise_for_status()
        return None  # 204 No Content

# Uso
manager = InvestigationManager('your-auth-token')

# Listar todas las investigaciones
result = manager.list_investigations()
print(f"Total de investigaciones: {result['totalCount']}")

for inv in result['investigations']:
    print(f"- {inv['investigationName']}: {inv['notebookCount']} cuadernos")

# Crear una nueva investigación
new_inv = manager.create_investigation(
    name='API Test Investigation',
    dataset_id='aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
    description='Created via API'
)
print(f"Creada: {new_inv['investigationId']}")

JavaScript/Node.js

const TENANT_ID = '12345678-1234-1234-1234-123456789012';
const PROJECT_ID = '87654321-4321-4321-4321-210987654321';
const BASE_URL = 'https://your-mindzie-instance.com';

class InvestigationManager {
  constructor(token) {
    this.headers = {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    };
  }

  async listInvestigations(page = 1, pageSize = 50) {
    const url = `${BASE_URL}/api/${TENANT_ID}/${PROJECT_ID}/investigation?page=${page}&pageSize=${pageSize}`;
    const response = await fetch(url, { headers: this.headers });
    if (!response.ok) throw new Error(`Failed: ${response.status}`);
    return await response.json();
  }

  async getInvestigation(investigationId) {
    const url = `${BASE_URL}/api/${TENANT_ID}/${PROJECT_ID}/investigation/${investigationId}`;
    const response = await fetch(url, { headers: this.headers });
    if (!response.ok) throw new Error(`Failed: ${response.status}`);
    return await response.json();
  }

  async createInvestigation(name, datasetId, description = '', isOperationCenter = false) {
    const url = `${BASE_URL}/api/${TENANT_ID}/${PROJECT_ID}/investigation`;
    const response = await fetch(url, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify({
        investigationName: name,
        investigationDescription: description,
        datasetId: datasetId,
        isUsedForOperationCenter: isOperationCenter
      })
    });
    if (!response.ok) throw new Error(`Failed: ${response.status}`);
    return await response.json();
  }

  async updateInvestigation(investigationId, updates) {
    const url = `${BASE_URL}/api/${TENANT_ID}/${PROJECT_ID}/investigation/${investigationId}`;
    const response = await fetch(url, {
      method: 'PUT',
      headers: this.headers,
      body: JSON.stringify(updates)
    });
    if (!response.ok) throw new Error(`Failed: ${response.status}`);
    return await response.json();
  }

  async deleteInvestigation(investigationId) {
    const url = `${BASE_URL}/api/${TENANT_ID}/${PROJECT_ID}/investigation/${investigationId}`;
    const response = await fetch(url, {
      method: 'DELETE',
      headers: this.headers
    });
    if (!response.ok) throw new Error(`Failed: ${response.status}`);
    return null; // 204 No Content
  }
}

// Uso
const manager = new InvestigationManager('your-auth-token');

const investigations = await manager.listInvestigations();
console.log(`Se encontraron ${investigations.totalCount} investigaciones`);

investigations.investigations.forEach(inv => {
  console.log(`- ${inv.investigationName}: ${inv.notebookCount} cuadernos`);
});

// Crear una nueva investigación
const newInv = await manager.createInvestigation(
  'API Test Investigation',
  'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
  'Created via API'
);
console.log(`Creada: ${newInv.investigationId}`);