Gestión de Plantillas

Operaciones CRUD completas para gestionar plantillas de notebooks. Todos los endpoints requieren una Clave API Global.

---

Listar Plantillas Globales

GET /api/templates

Devuelve todas las plantillas globales disponibles para todos los tenants.

Respuesta (200 OK)

{
  "templates": [
    {
      "templateId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "name": "Process Discovery",
      "description": "Standard process discovery workflow",
      "category": "Templates",
      "processName": "Order to Cash",
      "tenantId": null,
      "isGlobal": true,
      "hasThumbnail": true,
      "autoAddedDefaultSortOrder": 100,
      "dateModified": "2024-01-15T10:30:00Z"
    }
  ],
  "totalCount": 1
}

---

Listar Plantillas para Tenant

GET /api/templates/tenant/{tenantId}

Devuelve todas las plantillas disponibles para un tenant específico, incluyendo tanto las globales como las específicas del tenant.

Parámetros de Ruta

Parámetro	Tipo	Obligatorio	Descripción
tenantId	GUID	Sí	Identificador del tenant

Respuesta (200 OK)

{
  "templates": [
    {
      "templateId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "name": "Process Discovery",
      "description": "Standard process discovery workflow",
      "category": "Templates",
      "processName": "Order to Cash",
      "tenantId": null,
      "isGlobal": true,
      "hasThumbnail": true,
      "autoAddedDefaultSortOrder": 100,
      "dateCreated": "2024-01-01T00:00:00Z",
      "dateModified": "2024-01-15T10:30:00Z",
      "createdByName": "System",
      "modifiedByName": "System"
    },
    {
      "templateId": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff",
      "name": "Custom Analysis",
      "description": "Tenant-specific custom analysis",
      "category": "Custom",
      "processName": null,
      "tenantId": "12345678-1234-1234-1234-123456789012",
      "isGlobal": false,
      "hasThumbnail": false,
      "autoAddedDefaultSortOrder": 0,
      "dateCreated": "2024-02-01T09:00:00Z",
      "dateModified": "2024-02-15T14:30:00Z",
      "createdByName": "API",
      "modifiedByName": "API"
    }
  ],
  "totalCount": 2
}

---

Listar Plantillas por Categoría

GET /api/templates/category/{category}

Devuelve plantillas filtradas por categoría.

Parámetros de Ruta

Parámetro	Tipo	Obligatorio	Descripción
category	string	Sí	Nombre de la categoría: Templates, Custom, o BaseKnowledge

Parámetros de Consulta

Parámetro	Tipo	Obligatorio	Descripción
tenantId	GUID	No	Filtrar plantillas de un tenant específico

Ejemplo

# Obtener todas las plantillas personalizadas
curl -X GET "https://your-mindzie-instance.com/api/templates/category/Custom" \
  -H "Authorization: Bearer YOUR_GLOBAL_API_KEY"

# Obtener plantillas personalizadas para un tenant específico
curl -X GET "https://your-mindzie-instance.com/api/templates/category/Custom?tenantId=12345678-1234-1234-1234-123456789012" \
  -H "Authorization: Bearer YOUR_GLOBAL_API_KEY"

---

Obtener Detalles de Plantilla

GET /api/templates/{templateId}

Devuelve detalles completos de la plantilla incluyendo el texto de configuración MCL.

Parámetros de Ruta

Parámetro	Tipo	Obligatorio	Descripción
templateId	GUID	Sí	Identificador de la plantilla

Respuesta (200 OK)

{
  "templateId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "name": "Process Discovery",
  "description": "Standard process discovery workflow with variant analysis",
  "category": "Templates",
  "processName": "Order to Cash",
  "mclText": "// MCL configuration defining notebook blocks and settings\n{\n  \"blocks\": [...],\n  \"settings\": {...}\n}",
  "tenantId": null,
  "isGlobal": true,
  "hasThumbnail": true,
  "autoAddedDefaultSortOrder": 100,
  "originatingNotebookId": null,
  "dateCreated": "2024-01-01T00:00:00Z",
  "dateModified": "2024-01-15T10:30:00Z",
  "createdBy": null,
  "createdByName": "System",
  "modifiedBy": null,
  "modifiedByName": "System"
}

Campos de Respuesta

Campo	Tipo	Descripción
templateId	GUID	Identificador único
name	string	Nombre de la plantilla
description	string	Descripción de la plantilla
category	string	Categoría (Templates, Custom, BaseKnowledge)
processName	string	Nombre del proceso asociado
mclText	string	Texto de configuración MCL
tenantId	GUID	ID del tenant (null para plantillas globales)
isGlobal	boolean	Verdadero si es una plantilla global
hasThumbnail	boolean	Verdadero si existe imagen miniatura
autoAddedDefaultSortOrder	integer	Orden de visualización
originatingNotebookId	GUID	Notebook de origen si fue creada desde otro notebook
dateCreated	datetime	Fecha de creación
dateModified	datetime	Fecha de última modificación
createdBy	GUID	ID del usuario creador
createdByName	string	Nombre del usuario creador
modifiedBy	GUID	ID del usuario que modificó por última vez
modifiedByName	string	Nombre del usuario que modificó por última vez

Respuestas de Error

No Encontrado (404)

{
  "error": "Template with ID 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee' not found"
}

---

Obtener Miniatura de Plantilla

GET /api/templates/{templateId}/thumbnail

Devuelve la imagen miniatura de una plantilla.

Parámetros de Ruta

Parámetro	Tipo	Obligatorio	Descripción
templateId	GUID	Sí	Identificador de la plantilla

Respuesta (200 OK)

Devuelve datos de imagen JPEG con Content-Type: image/jpeg.

Respuestas de Error

No Encontrado (404)

{
  "error": "Thumbnail not found for template 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee'"
}

---

Crear Plantilla

POST /api/templates/tenant/{tenantId}

Crea una nueva plantilla específica para un tenant. No se pueden crear plantillas globales vía API.

Parámetros de Ruta

Parámetro	Tipo	Obligatorio	Descripción
tenantId	GUID	Sí	Identificador del tenant

Cuerpo de la Solicitud

{
  "name": "Custom Analysis Template",
  "description": "Custom analysis workflow for monthly reporting",
  "mclText": "// MCL configuration text",
  "category": "Custom",
  "processName": "Monthly Report",
  "isGlobal": false,
  "autoAddedDefaultSortOrder": 0
}

Campos de Solicitud

Campo	Tipo	Obligatorio	Descripción
name	string	Sí	Nombre de la plantilla (debe ser único)
description	string	No	Descripción de la plantilla
mclText	string	Sí	Texto de configuración MCL
category	string	No	Categoría (por defecto: "Custom")
processName	string	No	Nombre del proceso asociado
isGlobal	boolean	No	Debe ser false para creación vía API
autoAddedDefaultSortOrder	integer	No	Orden de visualización

Respuesta (201 Created)

{
  "templateId": "cccccccc-dddd-eeee-ffff-000000000000",
  "name": "Custom Analysis Template",
  "description": "Custom analysis workflow for monthly reporting",
  "category": "Custom",
  "processName": "Monthly Report",
  "mclText": "// MCL configuration text",
  "tenantId": "12345678-1234-1234-1234-123456789012",
  "isGlobal": false,
  "hasThumbnail": false,
  "autoAddedDefaultSortOrder": 0,
  "dateCreated": "2024-03-01T10:00:00Z",
  "dateModified": "2024-03-01T10:00:00Z",
  "createdByName": "API"
}

Respuestas de Error

Solicitud Incorrecta (400) - Validación Fallida

{
  "error": "Validation failed",
  "validationErrors": ["Name is required", "MclText is required"]
}

Conflicto (409) - Nombre Duplicado

{
  "error": "A template with this name already exists"
}

---

Actualizar Plantilla

PUT /api/templates/{templateId}

Actualiza una plantilla existente específica para un tenant. No se pueden actualizar plantillas globales vía API.

Parámetros de Ruta

Parámetro	Tipo	Obligatorio	Descripción
templateId	GUID	Sí	Identificador de la plantilla

Cuerpo de la Solicitud

{
  "name": "Updated Template Name",
  "description": "Updated description",
  "mclText": "// Updated MCL configuration",
  "category": "Custom",
  "processName": "Updated Process",
  "autoAddedDefaultSortOrder": 10
}

Todos los campos son opcionales - solo se actualizarán los campos proporcionados.

Respuesta (200 OK)

Devuelve los detalles de la plantilla actualizada.

Respuestas de Error

Solicitud Incorrecta (400) - Plantilla Global

{
  "error": "Cannot update global templates through the API"
}

No Encontrado (404)

{
  "error": "Template not found"
}

Conflicto (409) - Nombre Duplicado

{
  "error": "A template with this name already exists"
}

---

Eliminar Plantilla

DELETE /api/templates/{templateId}

Elimina una plantilla específica para un tenant. No se pueden eliminar plantillas globales vía API.

Parámetros de Ruta

Parámetro	Tipo	Obligatorio	Descripción
templateId	GUID	Sí	Identificador de la plantilla

Respuesta (200 OK)

{
  "message": "Template deleted successfully"
}

Respuestas de Error

Solicitud Incorrecta (400) - Plantilla Global

{
  "error": "Cannot delete global templates"
}

No Encontrado (404)

{
  "error": "Template not found"
}

---

Ejemplos de Implementación

cURL

# Listar todas las plantillas para un tenant
curl -X GET "https://your-mindzie-instance.com/api/templates/tenant/12345678-1234-1234-1234-123456789012" \
  -H "Authorization: Bearer YOUR_GLOBAL_API_KEY"

# Obtener detalles de plantilla
curl -X GET "https://your-mindzie-instance.com/api/templates/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" \
  -H "Authorization: Bearer YOUR_GLOBAL_API_KEY"

# Crear una plantilla
curl -X POST "https://your-mindzie-instance.com/api/templates/tenant/12345678-1234-1234-1234-123456789012" \
  -H "Authorization: Bearer YOUR_GLOBAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Custom Template",
    "description": "Custom analysis workflow",
    "mclText": "// MCL configuration",
    "category": "Custom"
  }'

# Actualizar una plantilla
curl -X PUT "https://your-mindzie-instance.com/api/templates/cccccccc-dddd-eeee-ffff-000000000000" \
  -H "Authorization: Bearer YOUR_GLOBAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Name"}'

# Eliminar una plantilla
curl -X DELETE "https://your-mindzie-instance.com/api/templates/cccccccc-dddd-eeee-ffff-000000000000" \
  -H "Authorization: Bearer YOUR_GLOBAL_API_KEY"

Python

import requests

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

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

    def list_templates(self, tenant_id=None):
        """Listar plantillas, opcionalmente filtradas por tenant."""
        if tenant_id:
            url = f'{BASE_URL}/api/templates/tenant/{tenant_id}'
        else:
            url = f'{BASE_URL}/api/templates'
        response = requests.get(url, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def get_template(self, template_id):
        """Obtener detalles de plantilla incluyendo texto MCL."""
        url = f'{BASE_URL}/api/templates/{template_id}'
        response = requests.get(url, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def create_template(self, tenant_id, name, mcl_text, description=None, category='Custom'):
        """Crear una nueva plantilla específica para un tenant."""
        url = f'{BASE_URL}/api/templates/tenant/{tenant_id}'
        data = {
            'name': name,
            'mclText': mcl_text,
            'description': description,
            'category': category
        }
        response = requests.post(url, json=data, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def update_template(self, template_id, **kwargs):
        """Actualizar una plantilla. Pasar solo los campos a actualizar."""
        url = f'{BASE_URL}/api/templates/{template_id}'
        response = requests.put(url, json=kwargs, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def delete_template(self, template_id):
        """Eliminar una plantilla específica para un tenant."""
        url = f'{BASE_URL}/api/templates/{template_id}'
        response = requests.delete(url, headers=self.headers)
        response.raise_for_status()
        return response.json()

# Uso
manager = TemplateManager('your-global-api-key')

# Listar plantillas
templates = manager.list_templates(TENANT_ID)
print(f"Se encontraron {templates['totalCount']} plantillas")

for t in templates['templates']:
    print(f"  - {t['name']} ({'Global' if t['isGlobal'] else 'Tenant'})")

# Crear una plantilla
new_template = manager.create_template(
    tenant_id=TENANT_ID,
    name='My Analysis Template',
    mcl_text='// MCL configuration here',
    description='Custom workflow'
)
print(f"Plantilla creada: {new_template['templateId']}")

# Actualizar la plantilla
updated = manager.update_template(
    new_template['templateId'],
    name='Renamed Template'
)

# Eliminar la plantilla
manager.delete_template(new_template['templateId'])
print("Plantilla eliminada")

JavaScript/Node.js

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

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

  async listTemplates(tenantId = null) {
    const url = tenantId
      ? `${BASE_URL}/api/templates/tenant/${tenantId}`
      : `${BASE_URL}/api/templates`;
    const response = await fetch(url, { headers: this.headers });
    if (!response.ok) throw new Error(`Failed: ${response.status}`);
    return response.json();
  }

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

  async createTemplate(tenantId, name, mclText, description = null, category = 'Custom') {
    const url = `${BASE_URL}/api/templates/tenant/${tenantId}`;
    const response = await fetch(url, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify({ name, mclText, description, category })
    });
    if (!response.ok) throw new Error(`Failed: ${response.status}`);
    return response.json();
  }

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

  async deleteTemplate(templateId) {
    const url = `${BASE_URL}/api/templates/${templateId}`;
    const response = await fetch(url, {
      method: 'DELETE',
      headers: this.headers
    });
    if (!response.ok) throw new Error(`Failed: ${response.status}`);
    return response.json();
  }
}

// Uso
const manager = new TemplateManager('your-global-api-key');

// Listar plantillas
const templates = await manager.listTemplates(TENANT_ID);
console.log(`Se encontraron ${templates.totalCount} plantillas`);

// Crear una plantilla
const newTemplate = await manager.createTemplate(
  TENANT_ID,
  'My Analysis Template',
  '// MCL configuration',
  'Custom workflow'
);
console.log(`Creada: ${newTemplate.templateId}`);

// Eliminar la plantilla
await manager.deleteTemplate(newTemplate.templateId);

---

Buenas Prácticas

1. Usar Claves API Globales: Las operaciones de plantillas requieren claves API globales
2. Nombres Únicos: Los nombres de las plantillas deben ser únicos dentro de su ámbito
3. Texto MCL: Almacenar la configuración completa MCL para notebooks reproducibles
4. Categorías: Usar categorías estándar para organización
5. Miniaturas: Las plantillas creadas vía API no tendrán miniaturas automáticamente