Introduccion a {M}aker
{M}aker es un sistema de gobernanza de codigo M (Power Query) donde las consultas de Power BI no viven dentro del fichero .pbix, sino en una base de datos centralizada. Power BI ejecuta una query "lanzadora" que descarga el codigo desde el servidor y lo ejecuta con Expression.Evaluate en cada refresco de datos.
mmaker()) que descarga y ejecuta el codigo en tiempo real.
Por que {M}aker
En entornos con multiples informes Power BI, mantener el codigo M directamente en los ficheros .pbix presenta varios problemas:
- Duplicacion: la misma consulta se copia en varios informes y diverge con el tiempo.
- Sin versionado: no hay forma nativa de ver versiones anteriores del codigo M ni hacer rollback.
- Sin parametrizacion centralizada: cada informe tiene sus propios valores hardcodeados.
- Sin reutilizacion: compartir un conjunto de queries entre informes requiere copiar y pegar manualmente.
{M}aker resuelve todo esto con un repositorio central de queries versionadas, parametrizables y reutilizables.
Conceptos principales
Queries
Una query es una consulta Power Query M dividida en pasos con nombre. Cada query tiene un sistema de versionado con borradores: los cambios se acumulan en un borrador que se activa explicitamente como nueva version. Las versiones anteriores son inmutables y se puede hacer rollback a cualquiera de ellas.
Reports
Un report agrupa queries y les asigna un token de acceso unico. Desde Power BI, la funcion lanzadora usa ese token para descargar el codigo de cada query. Los reports permiten configurar valores de parametros ({{PARAM}}) diferentes para cada query, y soportan multiples tokens (multi-token) para escenarios de RLS de parametros.
Packs
Un pack es un grupo reutilizable de queries que se puede asignar a multiples reports. Caso tipico: un pack de "dimensiones" (tablas de fechas, productos, clientes) compartido entre todos los informes de una organizacion.
DW (Data Warehouse)
El modulo DW permite cargar datos desde ficheros Excel/CSV a tablas dinamicas en MySQL. Se organiza en tres niveles:
- Pipeline
- Configuracion reutilizable de proceso: define como parsear un tipo de fichero (columnas, globals, fijas, keys, validaciones, pasos post-carga). Un pipeline puede compartirse entre multiples bloques.
- Bloque
- Instancia con identidad propia: tiene un nombre de tabla unico y referencia a un pipeline. Cada bloque genera su propia tabla dinamica en la base de datos DW.
- App
- Agrupacion de bloques con un pipeline de fallback. Organiza bloques relacionados bajo un mismo paraguas (por ejemplo, "Ventas" con bloques "Ventas Nacional", "Ventas Export").
BPM / Kanban
Sistema de gestion de procesos sobre cargas de datos. Cada bloque puede tener un tablero Kanban con estados configurables, transiciones entre estados (con pipelines opcionales que se ejecutan al transicionar), y acciones invocables sobre cargas existentes.
Portal de usuario
Interfaz simplificada para usuarios finales (rol usuario). Permite subir ficheros, ver estado de cargas e historial sin acceso a la configuracion tecnica.
Como funciona el sistema
El flujo basico de {M}aker es:
- El configurador crea queries con codigo M en {M}aker, organizadas en pasos con nombre.
- Las queries se agrupan en reports, donde se configuran los valores de parametros.
- Cada report tiene un token de acceso unico.
- En Power BI, se crea una funcion lanzadora
mmaker()con el token del report. - Cada query del informe se invoca con
mmaker("nombre_query", true, true). - En cada refresco, Power BI llama al servidor, descarga el codigo M actualizado y lo ejecuta.
Navegacion de la interfaz
Topbar
La barra superior contiene el logo de {M}aker y, si tienes acceso a multiples proyectos, un selector de proyecto que filtra toda la interfaz por proyecto. Cada proyecto tiene un color asignado para identificacion visual rapida.
Sidebar (barra lateral)
La barra lateral izquierda tiene 5 secciones, cada una colapsable:
| Seccion | Contenido |
|---|---|
| DW | Arbol de Apps con sus Bloques anidados. Boton "+ Bloque" para crear nuevos bloques. |
| Pipelines | Lista de pipelines independientes. Boton "+ Pipeline" para crear nuevos. |
| Queries | Lista plana de todas las queries. Al hacer click se muestra el codigo M sin parametros aplicados. |
| Reports | Lista de reports con sus queries asignadas como nodos hijo expandibles. Boton "+ Report". |
| Packs | Lista de packs con sus queries como nodos hijo expandibles. Boton "+ Pack". |
El buscador en la parte superior del sidebar filtra por nombre en todas las secciones simultaneamente. Las secciones colapsadas se expanden automaticamente si contienen resultados, y se restauran al limpiar la busqueda.
Panel principal
El area central muestra el detalle del elemento seleccionado en el sidebar, con diferentes pestanas segun el tipo de recurso (estructura, cargas, datos, versiones, codigo M, etc.).
Roles de usuario
{M}aker implementa una jerarquia de 4 roles con permisos incrementales:
| Rol | Acceso | Uso tipico |
|---|---|---|
| superadmin | Todo el sistema: todas las empresas, todos los usuarios, toda la configuracion. | Administrador global de la plataforma. |
| admin | Su empresa y proyectos hijos. Puede crear proyectos (sub-empresas) y gestionar usuarios. | Responsable de una consultora o empresa cliente. |
| desarrollador | Interfaz completa de {M}aker: queries, reports, packs, DW, pipelines. Sin acceso a admin. | Configurador tecnico que trabaja con el sistema dia a dia. |
| usuario | Solo portal: subir ficheros, ver estado, consultar historial. | Usuario final que sube datos pero no configura nada. |
usuario son redirigidos automaticamente al portal al iniciar sesion. No tienen acceso a la interfaz de configuracion de {M}aker.
Modelo consultora
Las empresas pueden tener una relacion padre-hijo (consultora-proyecto). Una empresa con parent_id es un proyecto bajo una empresa madre. Los administradores ven su empresa y todos sus proyectos; los superadmins ven todo.
Empresa "Consultora" (padre)
+-- Admin: ana@consultora.com
+-- Proyecto "Cliente Acme" (hijo)
| +-- Desarrollador: dev@consultora.com
| +-- Usuario: contacto@acme.com (solo portal)
+-- Proyecto "Cliente Beta" (hijo)
Proximos pasos
Consulta las siguientes secciones de esta wiki para profundizar en cada area:
- Queries: creacion, versionado, placeholders y referencias entre queries.
- Reports: agrupacion de queries, tokens de acceso, lanzaderas y multi-token.
- Packs: grupos reutilizables de queries compartidos entre reports.
- DW - Pipelines: configuracion de procesos de carga de datos.
- DW - Bloques: instancias de datos con tabla propia.
- DW - Apps: agrupacion de bloques.
- BPM / Kanban: gestion de procesos y estados sobre cargas.
Queries
Una query en {M}aker es una consulta Power Query M con nombre unico, dividida en pasos ordenados. Las queries son el recurso fundamental del sistema: todo lo demas (reports, packs, lanzaderas) se construye sobre ellas.
Tipos de query
Cada query tiene un tipo que determina como se usa desde Power BI. El tipo se ve en el sidebar como una letra (T/S/C) junto al nombre:
- T (transform): query pura, solo transformaciones M (
Table.*,List.*,Text.*,Date.*...). Se invoca viammaker()y refresca en PBI Service. Es el tipo por defecto. - S (staging): query con connectors (
Excel.Workbook,SharePoint.Files,Sql.Database,Web.Contents...). Se pega literal en el .pbix como consulta separada y su resultado alimenta una transform. Detalles en la guia de integracion con Power BI. - C (completa): query entera con connectors en modo "quick & dirty". Requiere que en el
.pbixse haya pegado la variante Desktop demmaker(mismo nombre, cuerpo con#shared). NO refresca en PBI Service.
Crear una query
Para crear una query, haz click en "+ Query" en la seccion Queries del sidebar, o usa el boton de creacion dentro de un report.
- Nombre
- Identificador unico de la query. No puede repetirse en la misma empresa. Se recomienda usar nombres descriptivos sin espacios (ej:
Ventas_Mensual,Dim_Producto). - Descripcion
- Texto opcional que describe el proposito de la query. Visible en el panel de detalle.
- Pasos
- Opcionalmente, puedes crear la query con pasos iniciales. Si no, se crea vacia y se anaden pasos despues.
Pasos (Steps)
Cada query se compone de uno o mas pasos ordenados. Cada paso es una expresion M independiente que puede referenciar pasos anteriores.
Campos de un paso
- nombre_paso
-
Nombre del paso. Si contiene espacios, guiones, acentos o empieza por numero, Power Query requiere quoting con
#"Nombre del Paso".Ejemplos validos:
Origen,FiltrarFilas,#"Filtrar Filas",#"Paso-2" - codigo_paso
-
Expresion M del paso. Nunca empieza con
NombrePaso =— el sistema lo anade automaticamente al generar el bloque let/in.Ejemplo correcto:
Table.SelectRows(Origen, each [Ventas] > 0)Ejemplo incorrecto:
FiltrarFilas = Table.SelectRows(Origen, each [Ventas] > 0) - es_output
- Marca el paso como salida final de la query. Exactamente un paso debe tener
es_output = 1por version. Este paso se usa en la clausulaindel bloque let/in generado. - notas
- Texto libre para documentar el proposito del paso. No afecta al codigo generado.
Anadir, modificar y eliminar pasos
Los pasos se gestionan desde el tab "Pasos" del panel de detalle de la query. El boton "+ Anadir paso" ofrece cuatro opciones:
- Paso manual: especifica nombre, codigo M, posicion (orden) y si es output.
- Paso DW: crea una consulta SQL sobre las tablas DW y genera los pasos M de conexion automaticamente.
- Pegar codigo M: pega un bloque
let ... incompleto y reemplaza todos los pasos de la query. - Crear con asistente IA: abre el chat IA para generar pasos con lenguaje natural.
- Modificar paso: al editar un paso, los cambios van al borrador (se crea automaticamente si no existe).
- Eliminar paso: elimina el paso del borrador actual.
#"NombreViejo" en los demas pasos del mismo borrador.
Pegar codigo M completo
Esta opcion es util cuando has trabajado el codigo M directamente en Power Query (donde puedes ver resultados en vivo) y quieres sincronizarlo de vuelta a {M}aker.
- Copia el bloque
let ... incompleto desde el Editor Avanzado de Power Query. - En {M}aker, selecciona la query destino y haz click en "+ Anadir paso" → "Pegar codigo M".
- Pega el codigo en el textarea y haz click en "Parsear".
- El sistema muestra un preview con los pasos detectados, cual es el output, y avisos si hay referencias externas.
- Haz click en "Reemplazar pasos" para confirmar.
#"Nombre" que no son pasos dentro de la propia query, el sistema las detecta y muestra un aviso. Estas referencias pueden ser a otras queries del mismo report (que funcionan dentro de Expression.Evaluate) o a queries que deberian reescribirse como mmaker("nombre", true, true).
Sistema de versionado
{M}aker implementa un sistema de versionado inmutable con borradores:
- version_activa
- La version oficial en uso. Es la que Power BI descarga al hacer refresco de datos. Las versiones anteriores son inmutables: una vez activada, no se pueden modificar sus pasos.
- version_borrador
- Version de trabajo donde se acumulan los cambios. Puede ser
NULLsi no hay borrador activo. Al modificar cualquier paso, se crea automaticamente un borrador si no existe.
Flujo de trabajo tipico
- Se parte de la version activa (ej: version 3).
- Al editar un paso, se crea automaticamente un borrador (version 4).
- Se hacen mas cambios: todos van al borrador (version 4).
- Cuando todo esta listo, se activa el borrador → version 4 pasa a ser la version activa.
- Power BI descargara la version 4 en el siguiente refresco.
Activar borrador
Convierte el borrador en la nueva version activa. Opcionalmente se puede anadir una descripcion del cambio. Una vez activado, los pasos de esa version quedan inmutables.
Descartar borrador
Elimina el borrador y todos sus cambios. La version activa no se modifica.
Rollback
Cambia version_activa a cualquier version anterior. No elimina versiones — simplemente apunta a una version distinta. Util para revertir cambios problematicos rapidamente.
mmaker("nombre_query", false, true) (segundo parametro false) para cargar el borrador en lugar de la version activa. Esto permite probar cambios antes de activarlos.
Placeholders (parametros)
Los pasos pueden usar placeholders con la sintaxis {{NOMBRE_PARAM}} en el codigo M. Estos placeholders se sustituyen por valores concretos cuando la query se sirve en el contexto de un report.
Reglas de formato
- Doble llave:
{{y}} - Solo mayusculas, numeros y guiones bajos
- Ejemplos validos:
{{EMPRESA_ID}},{{ANIO_FISCAL}},{{SERVIDOR_2}} - Ejemplos invalidos:
{{empresa_id}},{{año}},{{mi param}}
Como se resuelven
Cada query asignada a un report puede tener valores configurados para sus placeholders. Al servir el codigo M via el endpoint codigo_m_report, el sistema sustituye cada {{PARAM}} por el valor configurado en ese report (o token).
Deteccion de cambios de placeholders
Al activar una nueva version, si los placeholders han cambiado respecto a la version anterior (se han anadido o eliminado), el sistema notifica y permite resolver los cambios para cada report afectado.
Referencias entre queries
Dentro de Expression.Evaluate, las referencias normales de Power Query (#"Otra Query") se resuelven como null. Para que una query pueda referenciar a otra query de {M}aker, se usa la funcion lanzadora:
mmaker("nombre_otra_query", true, true)
Esto descarga y ejecuta la otra query en el mismo refresco. El resultado se puede usar como cualquier tabla o valor M.
Ejemplo de uso
// Paso "Origen" de la query "Ventas_Con_Productos"
let
Ventas = mmaker("Ventas_Raw", true, true),
Productos = mmaker("Dim_Producto", true, true),
Resultado = Table.NestedJoin(Ventas, "ProductoID", Productos, "ID", "Producto", JoinKind.LeftOuter)
in
Resultado
let/in propio, debe ir entre parentesis: (let ... in resultado). Esto es una regla de sintaxis M cuando el let/in esta dentro de otro bloque.
Invocacion rapida
En el panel de detalle de cada query, junto al titulo, hay un boton para copiar la invocacion al portapapeles:
let Origen = mmaker("nombre_query", true, true) in Origen
Reglas criticas de codigo M
Al escribir pasos en {M}aker, ten en cuenta estas reglas obligatorias:
| Regla | Correcto | Incorrecto |
|---|---|---|
El codigo nunca empieza con NombrePaso = |
Table.FromRows(...) |
Origen = Table.FromRows(...) |
| Let/in anidados entre parentesis | (let x = 1 in x) |
let x = 1 in x (dentro de otro paso) |
Quoting con #"Nombre" si tiene caracteres especiales |
#"Filtrar Filas" |
Filtrar Filas (sin quoting) |
| Exactamente 1 paso output por version | Un paso con es_output = 1 |
Cero o multiples outputs |
| Sin comillas simples envolventes | Table.FromRows(...) |
'Table.FromRows(...)' |
| Rutas Windows con doble barra | "C:\\Datos\\fichero.xlsx" |
"C:\Datos\fichero.xlsx" |
| Caracteres reales, no escapes Unicode | "Informacion" |
"Informaci\u00f3n" |
Referencias rotas
Cuando una query referencia a otra mediante mmaker("nombre_query") y esa query no existe, se considera una referencia rota.
- En el sidebar, las queries con referencias rotas muestran un badge de advertencia ⚠.
- En el panel de detalle, aparece un banner con la lista de referencias rotas.
- Las referencias rotas no impiden el funcionamiento, pero causaran errores en Power BI al intentar resolver la query referenciada.
Renombrar queries
Al renombrar una query, el sistema detecta automaticamente si otras queries la referencian con mmaker("nombre_antiguo"). Si hay dependencias, ofrece dos opciones:
- Actualizar referencias automaticamente: el sistema corrige
mmaker("nombre_antiguo")pormmaker("nombre_nuevo")en todas las queries que la referencian. - Corregir manualmente: se renombra la query y se muestra la lista de queries afectadas para corregirlas a mano.
Tab Codigo M
El tab "Codigo M" en el panel de detalle muestra el bloque let/in generado a partir de los pasos de la version activa. Este es el codigo exacto que Power BI descargara al invocar la query.
Si la query se visualiza desde el contexto de un report (haciendo click en ella desde el nodo hijo de un report), el codigo muestra los placeholders sustituidos por los valores configurados en ese report. Si se visualiza directamente desde la seccion Queries del sidebar, los placeholders aparecen sin sustituir.
Tab Reports
El tab "Reports" muestra la lista de reports que contienen esta query, ya sea asignada directamente o a traves de un pack. Permite ver rapidamente donde se usa cada query.
Emulador de pasos
El emulador permite ver como cada paso transforma los datos, sin necesidad de Power BI abierto. Aparece integrado en la vista de Pasos:
- En la barra superior de la vista Pasos, sube un fichero Excel/CSV con "Subir Excel/CSV" o pega JSON con "Pegar JSON".
- Selecciona el paso de inicio (el paso cuya salida representan los datos subidos).
- Cada paso que el emulador puede procesar muestra un badge con el numero de filas resultantes.
- Haz click en un paso para ver la tabla resultante de ese paso debajo de la lista.
mmaker("nombre_query", true, true, "NombrePaso") en Power BI para obtener una tabla con las primeras 50 filas de un paso intermedio. Copia el JSON resultante y pegalo con "Pegar JSON". Esto es util para queries conectadas a bases de datos, APIs o SharePoint que el emulador no puede simular directamente.
Reports
Un report en {M}aker es una agrupacion de queries con un token de acceso que permite a Power BI descargar y ejecutar el codigo M. Cada report representa un informe de Power BI (o un grupo de informes) que comparten el mismo conjunto de queries y parametros.
Crear un report
Haz click en "+ Report" en la seccion Reports del sidebar.
- Nombre
- Identificador unico del report. Sirve como referencia visual — no se usa en el codigo M.
- Descripcion
- Texto opcional que describe el proposito del report o el informe Power BI al que esta asociado.
- Token
- Se genera automaticamente al crear el report (formato
mk_xxx...). Este token se usa en la funcion lanzadora de Power BI para autenticar las peticiones. Se puede regenerar en cualquier momento desde la interfaz.
Importar queries al crear el report (opcional)
El modal "Nuevo report" incluye un selector en la seccion de importacion con dos vias para poblar el report con queries existentes:
- Pegar codigo M
- Pega un bloque
let ... in(o varios, prefijados con// NombreQuery). El sistema detecta los pasos, asigna los nombres y reescribe las referencias cruzadas#"Otra Query"ammaker("otra_query", true, true). - Cargar dataflow JSON
- Carga el fichero exportado desde Power BI Service (Dataflow → Export) o pega su contenido. Ver la seccion Importar dataflow de Power BI mas abajo.
Si la importacion falla tras crear el report, el sistema elimina automaticamente el report creado (rollback) para no dejar estado inconsistente.
Importar dataflow de Power BI
Permite traspasar de forma masiva el trabajo de un dataflow de Power BI Service a queries de {M}aker en una sola operacion. Esta disponible en dos lugares:
- Al crear un report, eligiendo "Cargar dataflow JSON" en el modal nuevo report (crea el report y asigna las queries en un solo paso).
- En un report existente, desde el dropdown "+ Anadir query" → "Importar dataflow (JSON)".
Tambien existe una tercera via standalone (sin report) accesible si tienes acceso directo a la opcion de importacion, pero la conversion de parametros a {{placeholders}} requiere tener un report destino.
Que hace el importador
- Lee el JSON del dataflow y extrae todas las queries (
section Section1; shared X = let ... in X;), los grupos (carpetas) y los metadatos. - Clasifica cada query como tabla, parametro (tiene
meta [IsParameterQuery = true]) o funcion ((args) as tipo => ...). - Reescribe las referencias cruzadas (
#"Otra Query"o nombres desnudos comoFechaInicio) ammaker("otra_query", true, true)para que funcionen dentro deExpression.Evaluatede la lanzadera. - Detecta conflictos con queries existentes en la empresa y duplicados dentro del propio lote (por ejemplo cuando dos nombres distintos como
aux FestivosMadridyaux_FestivosMadridcolisionan tras sanitizar). - Muestra un preview editable con checkbox por fila, nombre final renombrable y avisos.
Preview y opciones
- Politica de conflicto
-
Renombrar (por defecto): aplica sufijo automatico
_2,_3... a las queries que colisionan, manteniendo las refs consistentes.
Saltar: no importa las queries que ya existen en BD.
Sobrescribir: crea una nueva version activa para las queries que ya existen. - Nombre final (editable por fila)
- Puedes cambiar manualmente el nombre propuesto antes de importar. Las referencias
mmaker("nombre_original", ...)en otras queries del lote se reescriben automaticamente al nombre que dejes. - Crear pack por cada grupo
- Si el dataflow tiene grupos (carpetas tipo PARAMETROS, FUNCIONES, DIMENSIONES), crea un pack por grupo con las queries correspondientes y lo asigna al report.
- Asignar al report activo
- Solo visible en el flujo del dropdown (en el modal nuevo report se asigna implicitamente al nuevo report).
- Convertir parametros PQ a
{{placeholders}} - Activo por defecto cuando hay report destino. Ver la siguiente seccion.
Conversion de parametros a placeholders de mmaker
Los parametros de Power Query (queries con meta [IsParameterQuery = true] como SV = "52.236.82.20" o FechaInicio = #date(2000, 1, 1)) son valores constantes, no procesos. Crearlos como queries de {M}aker anadiria un viaje HTTP innecesario y romperia el modelo multi-token/RLS donde cada token puede tener su propio valor.
Cuando la opcion esta activa, el importador:
- No crea query para los parametros seleccionados.
- Reescribe las refs en los otros pasos del lote:
mmaker("SV", true, true)→{{SV}}. - Anade entradas en
report_paramsconnombre_placeholder=SVyvalor="52.236.82.20"(el valor literal con comillas / funciones M intactas, para sustitucion textual directa en el codigo M generado).
El indicador visual en las filas de tipo parametro muestra → {{NOMBRE}} para que veas antes de confirmar que pasara con cada uno.
mmaker("SV", true, true), el importador no la modifica. Se respeta la decision previa del usuario.
Asignar queries
Un report puede contener queries de dos formas:
Asignacion directa
Desde el tab "Estructura" del report, usa el boton "Anadir query" para seleccionar queries existentes. Cada query directa puede tener un alias opcional — un nombre alternativo que se muestra en la interfaz sin afectar al codigo.
Via packs
Desde el mismo tab, puedes asignar packs al report. El report hereda automaticamente todas las queries del pack. Ver la seccion Packs para mas detalles.
Parametros (placeholders)
Si las queries asignadas al report contienen placeholders ({{PARAM}}), estos deben configurarse con valores concretos.
Configuracion de parametros
Desde el tab "Estructura", cada query muestra sus placeholders pendientes de configurar. Al hacer click en una query, se abre el editor de parametros donde se introducen los valores.
| Concepto | Descripcion |
|---|---|
| Placeholder | Variable en el codigo M con formato {{NOMBRE}}. Detectada automaticamente. |
| Valor | Texto que sustituye al placeholder al servir el codigo. Puede ser un numero, texto, ruta, etc. |
| Estado | Se indica visualmente si un placeholder tiene valor configurado o esta pendiente. |
codigo_m_report devuelve HTTP 422 y Power BI mostrara un error al refrescar. Asegurate de configurar todos los parametros antes de usar el report en produccion.
Sistema multi-token (RLS de parametros)
Ademas del token principal del report (token legacy), {M}aker soporta la creacion de multiples tokens de acceso por report, cada uno con sus propios valores de parametros.
Caso de uso
Imagina un report con una query que filtra datos por empresa usando {{EMPRESA_ID}}. Con multi-token puedes:
- Crear un token "Empresa A" con
EMPRESA_ID = 1 - Crear un token "Empresa B" con
EMPRESA_ID = 2 - Crear un token "Todas" con
EMPRESA_ID = 0
Cada usuario de Power BI usa un token diferente y obtiene datos diferentes, todo con las mismas queries.
Gestion de tokens
Los tokens se gestionan desde el tab "Accesos" del report:
- Crear token
- Especifica un nombre descriptivo y opcionalmente una descripcion. El token se genera automaticamente.
- Configurar parametros
- Cada token tiene su propio conjunto de valores para los placeholders de las queries del report. Los valores se configuran independientemente para cada token.
- Duplicar token
- Crea una copia de un token existente con todos sus parametros. Util para crear variantes con pequenas diferencias.
- Regenerar token
- Genera un nuevo string de token (invalida el anterior). Util si un token se ha comprometido.
- Toggle activo/inactivo
- Desactiva un token temporalmente sin eliminarlo. Un token inactivo no sirve codigo M — Power BI recibira un error.
- Eliminar token
- Elimina permanentemente el token y todos sus parametros configurados.
report_params): un valor por placeholder, compartido por todas las queries del report. Los tokens de acceso pueden tener sus propios overrides en report_token_params. Si dos conceptos necesitan valores distintos, usa nombres distintos (ej: ANIO_ACTUAL vs ANIO_ANTERIOR), no el mismo nombre con dos valores.
Sustitucion en Power Query M vs en DW SQL
Los mismos {{PARAM}} sustituyen en dos contextos distintos con reglas diferentes:
| Power Query M | DW SQL (dw_consultas) | |
|---|---|---|
| Tipo de sustitucion | Textual (sin comillas) | Con auto-quote (PDO::quote) |
| String | "{{REGION}}" — comillas manuales | {{REGION}} — sin comillas |
| Numero | {{N}} | {{N}} — MySQL coerce |
| LIMIT / OFFSET | — | No soportado (requiere int literal, no aceptado por PDO::quote) |
| Seguridad | Responsabilidad del disenador | SQL injection prevenido via quote |
- M (.pbix): tu controlas las comillas segun el tipo
- SQL (dw_consultas): nunca pongas comillas alrededor de
{{PARAM}}
Ejemplo: mismo parametro REGION en ambos contextos
// Power Query M (paso de filtro)
= Table.SelectRows(Datos, each [region] = "{{REGION}}")
-- DW SQL (consulta nombrada)
SELECT * FROM dw_1_ventas WHERE region = {{REGION}}
Caso especial: LIMIT dinamico
El auto-quote impide usar LIMIT {{N}} porque MySQL requiere un literal entero. Alternativa: forzar el valor en la propia consulta (LIMIT 1000) o usar per_page en la llamada HTTP.
Deteccion de placeholders en el panel del report
El panel de parametros del tab Lanzadora detecta automaticamente todos los placeholders usados por las queries del report. Dos comportamientos clave:
- Placeholders en consultas DW: si un paso Power Query invoca una consulta DW (
dw_sql), el sistema escanea tambien el SQL de esa consulta y anade sus{{PARAM}}al panel. Configuras el valor una sola vez y aplica en ambos sitios (M + SQL). - Borrador vs activa: si una query tiene borrador, se usan los placeholders del borrador. Asi puedes configurar y probar parametros nuevos mientras desarrollas, sin esperar a activar la version.
{{PARAM}} por un valor dummy antes del LIMIT 0. Puedes guardar consultas con parametros sin necesidad de tener valores configurados.
Tab Lanzadora
El tab "PQ Queries" (o "Lanzadora") muestra el codigo M de la funcion lanzadora que debe crearse en Power BI para conectar con este report.
La funcion mmaker()
La lanzadora es una funcion Power Query con tres parametros:
- NombreQuery (text)
- Nombre de la query a descargar desde {M}aker. Debe coincidir exactamente con el nombre registrado.
- Version (logical)
true= version activa (publicada),false= borrador (en desarrollo). En Power BI aparece como un dropdown con dos opciones gracias aDocumentation.AllowedValues.- Evaluar (logical)
true= ejecuta el codigo M descargado,false= muestra el codigo como texto sin ejecutar (modo debug). Tambien aparece como dropdown en Power BI.
Estructura de la lanzadora
let
FnType = type function (
NombreQuery as (type text meta [
Documentation.Description = "Nombre de la query en {M}aker"
]),
Version as (type logical meta [
Documentation.Description = "true = activa; false = borrador",
Documentation.AllowedValues = {true, false},
Documentation.DefaultValue = true
]),
Evaluar as (type logical meta [
Documentation.Description = "true = ejecuta; false = muestra codigo",
Documentation.AllowedValues = {true, false},
Documentation.DefaultValue = true
])
) as any meta [
Documentation.Name = "mmaker"
],
Fn = (NombreQuery as text, Version as logical, Evaluar as logical) =>
let
Token = "mk_tu_token_aqui",
BaseUrl = "https://tu-servidor/mmaker/api.php",
Respuesta = Text.FromBinary(
Web.Contents(BaseUrl, [
Query = [
action = "codigo_m_report",
token = Token,
query = NombreQuery,
v = if Version then "activa" else "borrador"
]
])
),
Resultado = if Evaluar then
Expression.Evaluate(Respuesta, #shared)
else
Respuesta
in
Resultado
in
Value.ReplaceType(Fn, FnType)
Uso desde Power BI
Una vez creada la funcion mmaker, cada query del informe se invoca asi:
// En una nueva consulta en blanco:
mmaker("Ventas_Mensual", true, true)
O en formato paso completo:
let
Origen = mmaker("Ventas_Mensual", true, true)
in
Origen
Parametros como dropdowns en Power BI
Gracias a Documentation.AllowedValues = {true, false}, Power BI muestra los parametros Version y Evaluar como dropdowns en la interfaz de invocacion. Documentation.DefaultValue pre-rellena los valores por defecto.
Tablas DW en la lanzadora
Si la empresa tiene tablas en el modulo DW (Data Warehouse), el tab de lanzadora tambien muestra una seccion "Tablas DW (API)" con codigo M copiable para cada tabla.
Estas tablas se acceden via Web.Contents al endpoint dw_data, usando el mismo token del report. El codigo M generado incluye:
- Paginacion automatica con
List.Generatepara tablas grandes. - Conversion de tipos automatica (
Table.TransformColumnTypes) basada en los tipos de las columnas. - Exclusion de columnas internas (
_dw_*) por defecto.
Para cada tabla, hay un boton "Copiar M" que copia el codigo listo para pegar en Power BI como consulta en blanco.
Tab Estado
El tab "Estado" muestra un resumen del estado del report:
- Numero de queries asignadas (directas y via packs).
- Parametros pendientes de configurar.
- Tokens activos e inactivos.
Eliminar y renombrar reports
Eliminar: Elimina el report, todos sus tokens y las configuraciones de parametros. Las queries no se eliminan — siguen existiendo como recursos independientes.
Renombrar: Cambia el nombre del report. No afecta a los tokens ni al funcionamiento en Power BI (el token es el identificador real, no el nombre).
Packs
Un pack en {M}aker es un grupo reutilizable de queries que se puede asignar a multiples reports. Los packs permiten compartir un conjunto comun de queries entre varios informes Power BI sin tener que asignarlas una a una.
Caso de uso tipico
En la mayoria de proyectos de Power BI existen queries que se repiten en muchos informes:
- Tablas de dimensiones: fechas, productos, clientes, regiones.
- Funciones auxiliares: transformaciones comunes, limpieza de datos.
- Conexiones base: queries que establecen la conexion a una fuente de datos compartida.
En lugar de asignar estas queries individualmente a cada report, se agrupan en un pack (ej: "Dimensiones Comunes") y se asigna el pack a cada report que lo necesite.
Crear un pack
Haz click en "+ Pack" en la seccion Packs del sidebar.
- Nombre
- Identificador unico del pack. Se recomienda un nombre descriptivo del grupo de queries que contiene (ej: "Dimensiones Comunes", "Conexiones SAP", "Utilidades ETL").
- Descripcion
- Texto opcional que explica el proposito del pack y que tipo de queries agrupa.
Gestionar queries del pack
Anadir queries
Desde el tab "Queries" del panel de detalle del pack, usa el boton "Anadir query" para seleccionar queries existentes. Se muestra una lista con las queries disponibles (las que aun no estan en el pack).
Orden de las queries
Las queries dentro de un pack tienen un orden definido. El orden determina la posicion en la que aparecen en la interfaz. Puedes reorganizar las queries arrastrando o cambiando su posicion.
mmaker("nombre", true, true). El orden es puramente organizativo dentro de la interfaz de {M}aker.
Eliminar queries del pack
Para quitar una query de un pack, usa el boton de desasignar junto a cada query en la lista. Esto no elimina la query — solo la desvincula del pack. La query sigue existiendo como recurso independiente.
mmaker("nombre"), recibira un error 403 en el siguiente refresco (salvo que la query este asignada directamente al report).
Asignar packs a reports
Los packs se asignan a reports desde el tab "Estructura" del report (ver seccion Reports). Al asignar un pack, el report hereda todas las queries del pack.
Herencia dinamica
La relacion es dinamica: si despues de asignar un pack se anaden o eliminan queries del pack, el report refleja los cambios automaticamente. No hay que reasignar el pack.
Queries duplicadas
Si una query esta asignada tanto directamente al report como a traves de un pack, no hay conflicto. El servidor la sirve igualmente. Los parametros se resuelven de la misma forma.
Parametros en queries de packs
Los valores de parametros ({{PARAM}}) de las queries de un pack se configuran a nivel del report, no del pack.
Ejemplo
Supongamos un pack "Dimensiones" con la query "Dim_Empresa" que usa {{SERVIDOR_BD}}:
| Report | Pack asignado | Valor de {{SERVIDOR_BD}} |
|---|---|---|
| Report Produccion | Dimensiones | srv-prod.empresa.com |
| Report Desarrollo | Dimensiones | srv-dev.empresa.com |
| Report UAT | Dimensiones | srv-uat.empresa.com |
Los tres reports comparten la misma query del pack, pero cada uno sustituye el placeholder con su propio servidor.
Tab Uso
El tab "Uso" del panel de detalle del pack muestra la lista de reports que tienen este pack asignado. Permite ver de un vistazo donde se usa el pack y evaluar el impacto de cualquier cambio.
Eliminar un pack
Al eliminar un pack:
- Se desvincula de todos los reports que lo usaban.
- Las queries del pack no se eliminan — siguen existiendo como recursos independientes.
- Los reports que usaban el pack pierden acceso a esas queries (a traves del pack). Si las necesitan, deben asignarse directamente.
Renombrar un pack
Puedes renombrar un pack desde el boton de edicion junto al titulo. El renombrado no afecta a las asignaciones ni al funcionamiento — es puramente un cambio de nombre visual.
Buenas practicas
- Agrupar por dominio funcional
- Crea packs que representen un dominio logico: "Dimensiones", "Conexiones ERP", "Utilidades". Evita packs genericos como "Queries comunes" que crecen sin control.
- Un pack, un proposito
- Es mejor tener varios packs pequenos y especificos que uno grande con todo. Facilita la asignacion selectiva a reports.
- Documentar con la descripcion
- Usa la descripcion del pack para explicar que contiene y cuando debe usarse. Esto ayuda a otros configuradores a decidir si asignar el pack a sus reports.
- Revisar el impacto
- Antes de modificar las queries de un pack, revisa el tab "Uso" para saber cuantos reports se veran afectados.
Pipelines
Un pipeline en {M}aker es una configuracion reutilizable de proceso que define como parsear un tipo de fichero, que columnas extraer, que validaciones aplicar y que acciones ejecutar tras la carga. Es el "plano" del proceso: define el como, pero no el donde.
dw_{empresa_id}_{nombre_tabla}) y ejecuta el pipeline asignado. Varios bloques pueden compartir el mismo pipeline.
Crear un pipeline
Haz click en "+ Pipeline" en la seccion Pipelines del sidebar. Se abre un wizard de 3 pasos.
Paso 1 — Datos basicos y fichero muestra
- Nombre
- Identificador unico del pipeline dentro de la empresa. Debe ser descriptivo del tipo de fichero o proceso que gestiona (ej: "Ventas Mensuales", "Carga Stock CSV").
- Descripcion
- Texto libre opcional que documenta el proposito del pipeline.
- Fichero muestra
- Fichero Excel (.xlsx, .xls) o CSV que sirve como plantilla para detectar columnas y estructura. El sistema lee las cabeceras y ofrece autodeteccion de tipos.
- Toggle "Sin fichero"
- Activa este toggle para crear un pipeline que no procesa ficheros. Se usa para pipelines de accion (BPM): solo ejecutan pasos del pipeline sin insertar datos en una tabla. Al activarlo, el selector de fichero desaparece y el paso 3 genera fijas automaticamente desde los campos de carga.
file) genera automaticamente una columna fija con campo_carga_ref vinculado. La tabla se construye enteramente desde fijas. El proceso de carga equivale a "anadir una linea" rellenando los campos de carga, sin subir ningun fichero.
Paso 2 — Campos de carga
Los campos de carga son formularios que el usuario rellena al momento de subir un fichero (o al ejecutar un pipeline sin fichero). Consulta la seccion Campos de carga para detalles completos sobre tipos, opciones SQL, grupos y condiciones.
Paso 3 — Estructura
Define la estructura de la tabla destino y como mapear los datos del fichero a columnas de la base de datos.
Tabla destino
- Nombre de tabla
- Nombre interno de la tabla dinamica que se creara en
mmaker_dw. El nombre final seradw_{empresa_id}_{nombre_tabla}. Solo letras, numeros y guiones bajos. No se puede cambiar despues de la creacion. - Fila de cabecera
- Numero de fila del fichero Excel que contiene los nombres de columna. Por defecto
1. - Fila de datos
- Numero de fila donde empiezan los datos. Por defecto
2. Si el fichero tiene filas de metadatos entre la cabecera y los datos, ajusta este valor.
nombre_tabla puede dejarse vacio. En ese caso no se crea tabla dinamica y el pipeline solo ejecuta sus pasos post-carga.
Columnas de datos
Cada columna define un mapeo entre una columna del fichero fuente y un campo de la tabla destino.
| Campo | Descripcion |
|---|---|
nombre_origen |
Nombre de la columna tal como aparece en la cabecera del fichero fuente. Debe coincidir exactamente (sensible a mayusculas/minusculas). |
nombre_campo |
Nombre de la columna en la tabla destino MySQL. Solo letras, numeros y guiones bajos. |
tipo_dato |
Tipo de dato MySQL: varchar, int, decimal, date, datetime, text. |
longitud |
Longitud maxima del campo. Por defecto 255 para varchar. Para decimal, es la precision total (ej: 10 en DECIMAL(10,2)). |
decimales |
Solo para tipo decimal. Numero de decimales (ej: 2 en DECIMAL(10,2)). |
formato_fecha |
Uso dual segun el tipo de dato:
|
orden |
Posicion relativa de la columna en la tabla. Determina el orden de las columnas en la UI y en la creacion de la tabla. |
1.234,56 (punto para miles, coma para decimales), pon eu en el campo formato_fecha de las columnas int o decimal. El parser convertira automaticamente al formato MySQL estandar.
Globals (celdas fijas del fichero)
Los globals extraen valores de celdas fijas del fichero Excel (no de la zona de datos tabulares). Son utiles para metadatos que aparecen en una posicion fija del fichero (ej: mes de reporte en celda B1, ano en celda C1).
| Campo | Descripcion |
|---|---|
nombre_campo |
Nombre de la columna en la tabla destino donde se guardara el valor. |
fila |
Numero de fila de la celda (1-based). |
columna |
Numero de columna de la celda (1-based, donde A=1, B=2, etc.). |
tipo_dato |
varchar, int, decimal o date. |
El valor extraido de la celda global se repite en todas las filas insertadas de esa carga. Es como una constante que viene del propio fichero.
Fijas (valores constantes)
Las fijas asignan un valor fijo a una columna para todas las filas de cada carga. A diferencia de los globals, el valor no viene del fichero sino de la configuracion.
| Campo | Descripcion |
|---|---|
nombre_campo |
Nombre de la columna en la tabla destino. |
valor |
Valor literal, expresion SQL (ej: NOW(), CURDATE()) o variable del pipeline (ej: {{_DW_CARGA_ID}}). Se evalua en el momento de la insercion. |
campo_carga_ref |
Si se activa, el valor de la fija se toma del campo de carga indicado en lugar del valor literal. En la UI hay un toggle para alternar entre valor literal y referencia a campo de carga. |
tipo_dato |
varchar, int, decimal o date. |
campo_carga_ref apuntando al nombre del campo de carga.
Singularidad (Keys)
El sistema de singularidad (keys) controla la deduplicacion de datos. Antes de insertar nuevas filas, el sistema borra las filas existentes que coincidan en todos los campos clave configurados. Si no hay keys configuradas, los datos simplemente se acumulan (append only).
| Tipo de key | Fuente del valor | Ejemplos |
|---|---|---|
columna |
Dato del fichero (columna mapeada) | producto, fecha, codigo |
global |
Celda fija del fichero (globals) | ANIO, MES |
interno |
Campo interno de la tabla DW | _dw_bloque_id, _dw_fichero, _dw_hoja_idx, _dw_hoja_nombre |
campo_carga |
Campo rellenado por el usuario al subir | Se resuelve via la fija que tiene campo_carga_ref apuntando al campo |
_dw_bloque_id como key interna. Cuando esta activado, las cargas de un bloque solo afectan (borran/reemplazan) datos de ese mismo bloque, nunca de otros bloques que compartan la misma tabla.
Required (campos obligatorios)
Marca columnas que deben tener valor en cada fila. Las filas donde un campo required este vacio se rechazan como error y se registran en dw_carga_errores. Las filas validas se insertan normalmente.
Pipeline sin tabla
Desde la migracion 037, el campo nombre_tabla en dw_pipelines es nullable. Un pipeline sin tabla:
- No crea tabla dinamica en
mmaker_dw. - No ejecuta INSERT de datos.
- Solo ejecuta los pasos post-carga (validaciones, SQL, variables, mailing, triggers, estados BPM).
Casos de uso tipicos:
- Acciones BPM: Cambiar el estado de una carga en el Kanban.
- Mailing automatico: Enviar emails como accion sobre una carga existente.
- Triggers en cadena: Ejecutar otros pipelines como respuesta a una accion.
- Validaciones independientes: Comprobar datos sin modificar la tabla.
dw_guardar_pipeline_config omite las operaciones CREATE/ALTER sobre la tabla dinamica.
Multi-hoja (config_hojas)
Para ficheros Excel con multiples hojas, el pipeline puede configurar que hojas procesar y si comparten la misma estructura.
- Modo "nombres"
- Identifica hojas por su nombre exacto. Util cuando el fichero siempre tiene una hoja llamada "Datos" entre otras hojas variables.
- Modo "indices"
- Identifica hojas por su posicion (0-based). Util cuando el nombre de la hoja cambia (ej: el nombre del mes) pero siempre es la misma posicion.
misma_estructura- Si es
true, todas las hojas seleccionadas comparten la misma configuracion de columnas. Si esfalse, cada hoja puede tener su propio mapeo de columnas independiente.
Las columnas internas _dw_hoja_idx y _dw_hoja_nombre se rellenan automaticamente con el indice y nombre de la hoja de cada fila. Pueden usarse como keys de singularidad (tipo interno).
Editar un pipeline existente
Desde el panel de detalle del pipeline (tab Estructura), haz click en "Editar configuracion". Esto abre el wizard DW en modo edicion:
- El wizard salta directamente al paso 2 (campos de carga), pre-populado con la configuracion actual.
- El campo "Tabla destino" es de solo lectura — no se puede renombrar la tabla dinamica una vez creada.
- Al guardar, se ejecuta
dw_actualizar_pipeline+dw_guardar_pipeline_config, que aplica los cambios y ejecuta ALTER TABLE si es necesario (anadir columnas nuevas, modificar tipos).
int).
Compartir pipeline entre bloques
Un pipeline puede ser asignado a multiples bloques. Cada bloque que usa el mismo pipeline:
- Comparte la misma configuracion de columnas, globals, fijas, keys y campos de carga.
- Tiene su propia tabla destino (nombre unico por bloque).
- Ejecuta los mismos pasos post-carga.
Para asignar un pipeline a un bloque, usa el boton "Cambiar" en el header del panel de bloque, o el endpoint dw_asignar_pipeline_bloque.
bloque.pipeline_id ?? app.pipeline_id ?? null. Si el bloque tiene pipeline propio, se usa ese. Si no, se hereda el pipeline de la app contenedora. Si ninguno esta definido, el bloque usa su configuracion legacy (tablas dw_bloque_*).
Eliminar un pipeline
Un pipeline solo puede eliminarse si no tiene bloques asignados. Si hay bloques que referencian el pipeline, el sistema lo impide y muestra un error. Debes reasignar o eliminar los bloques vinculados antes de poder borrar el pipeline.
Pasos post-carga
Los pipelines pueden incluir pasos que se ejecutan automaticamente tras la insercion de datos. Los tipos de paso disponibles se documentan en detalle en la seccion Pasos de pipeline. Los tipos incluyen: validaciones (stop/alarma), SQL, variables, mailing, triggers, bucles, tablas de resultado, flyouts y estados BPM.
Resumen de estructura del pipeline
| Componente | Tabla | Funcion |
|---|---|---|
| Columnas | dw_pipeline_columnas |
Mapeo fichero → tabla (nombre_origen → nombre_campo + tipo) |
| Globals | dw_pipeline_globals |
Celdas fijas del fichero (fila + columna → campo) |
| Fijas | dw_pipeline_fijas |
Valores constantes o referencias a campos de carga |
| Keys | dw_pipeline_keys |
Campos de singularidad (deduplicacion) |
| Required | dw_pipeline_required |
Campos obligatorios por fila |
| Campos de carga | dw_pipeline_campos_carga |
Formulario que rellena el usuario al subir |
| Pasos | dw_pipeline_pasos |
Acciones post-carga (validacion, SQL, mailing, etc.) |
Bloques
Un bloque es una instancia con identidad propia dentro del modulo DW. Cada bloque representa un destino de datos concreto: tiene una empresa, un nombre y una tabla dinamica unica en la base de datos mmaker_dw. La combinacion empresa_id + nombre_tabla genera la tabla dw_{empresa_id}_{nombre_tabla}.
Mientras que un pipeline define como se procesa un fichero (columnas, validaciones, pasos), el bloque define donde aterrizan los datos. Multiples bloques pueden compartir el mismo pipeline, pero cada bloque tiene su propia tabla y su propio historial de cargas.
Crear un bloque
Para crear un bloque, haz click en "+ Bloque" en la seccion DW del sidebar. Se abre el wizard DW en modo bloque con 3 pasos:
- Paso 1 — Datos basicos
-
Nombre del bloque (unico por empresa), descripcion opcional y fichero muestra para detectar estructura. Opcionalmente se puede marcar "Sin fichero" si el bloque solo recibira datos via campos de carga.
- Paso 2 — Campos de carga
-
Formulario que el usuario rellenara al subir datos. Se definen campos de tipo
input,number,select,dateofile. Ver seccion Campos de carga para mas detalle. - Paso 3 — Estructura
-
Tabla destino (
nombre_tabla), fila de cabecera, fila de datos, globals, fijas y columnas de datos. Esta configuracion define la estructura de la tabla dinamica que se creara enmmaker_dw.
nombre_tabla se define durante la creacion y no se puede cambiar despues. Elige un nombre descriptivo en minusculas sin espacios (ej: ventas, stock_mensual).
Campos del bloque
| Campo | Tipo | Descripcion |
|---|---|---|
nombre |
VARCHAR(100) | Nombre visible del bloque (unico por empresa) |
nombre_tabla |
VARCHAR(100) | Nombre de la tabla dinamica (inmutable tras creacion) |
descripcion |
TEXT | Descripcion opcional |
pipeline_id |
INT FK | Pipeline asignado que define la configuracion de proceso |
app_id |
INT FK | App contenedora (Fase 2). Puede ser NULL para bloques standalone |
fila_cabecera |
INT | Fila del fichero que contiene las cabeceras (default: 1) |
fila_datos |
INT | Primera fila de datos (default: 2) |
config_hojas |
JSON | Configuracion multi-hoja (modo nombres/indices, hojas seleccionadas) |
fichero_master |
VARCHAR(255) | Nombre interno del fichero master de referencia |
expectativa_carga |
JSON | Frecuencia/calendario de carga esperada |
Asignacion de pipeline
Un bloque obtiene su configuracion de proceso (columnas, globals, fijas, keys, required, campos de carga, pasos) de un pipeline. La resolucion sigue esta jerarquia:
pipeline efectivo = bloque.pipeline_id ?? app.pipeline_id ?? null
- bloque.pipeline_id
- Si el bloque tiene un pipeline asignado directamente, se usa ese (override).
- app.pipeline_id
- Si el bloque no tiene pipeline propio pero pertenece a una app con pipeline, hereda el de la app (fallback).
- null (sin pipeline)
- Si no hay pipeline en ninguno de los dos niveles, el bloque usa su configuracion propia (modo legacy). Ver seccion siguiente.
En el panel de detalle del bloque, el header muestra el pipeline asignado con un link al pipeline y un boton "Cambiar" que abre un modal con un selector de pipelines disponibles.
Modo legacy (sin pipeline)
Si un bloque no tiene pipeline asignado (ni directo ni via app), utiliza su propia configuracion almacenada en las tablas dw_bloque_*:
dw_bloque_columnas— columnas de datosdw_bloque_globals— celdas fijas del ficherodw_bloque_fijas— valores constantesdw_bloque_keys— claves de singularidaddw_bloque_required— campos obligatoriosdw_bloque_campos_carga— campos del formulario de subida
En este modo, el tab Estructura muestra la configuracion completa y permite editarla via el boton "Editar configuracion".
Tabla dinamica
Al crear o guardar la configuracion de un bloque, el sistema genera (o altera) una tabla en la base de datos mmaker_dw con el nombre dw_{empresa_id}_{nombre_tabla}.
Columnas internas automaticas
Toda tabla dinamica incluye estas columnas internas, gestionadas automaticamente por el sistema:
| Columna | Tipo | Descripcion |
|---|---|---|
_dw_id |
INT AUTO_INCREMENT PK | Identificador unico de fila |
_dw_carga_id |
INT | ID de la carga que inserto esta fila |
_dw_bloque_id |
INT | ID del bloque origen |
_dw_linea |
INT | Numero de linea en el fichero original |
_dw_fichero |
VARCHAR(255) | Nombre del fichero subido |
_dw_hoja_idx |
INT | Indice de la hoja (NULL para CSV) |
_dw_hoja_nombre |
VARCHAR(255) | Nombre de la hoja de Excel |
_dw_timestamp |
DATETIME | Momento de la insercion |
Tras las columnas internas, se anaden las columnas definidas por el usuario: primero las de globals, luego las fijas y finalmente las columnas de datos del fichero.
_dw_bloque_id, _dw_fichero, _dw_hoja_idx y _dw_hoja_nombre pueden usarse como claves de singularidad de tipo interno. Esto es util para controlar la granularidad de la deduplicacion.
Tabs del panel de bloque
El panel de detalle de un bloque tiene 5 tabs principales:
Tab Estructura
Muestra la configuracion completa del bloque: tabla destino, globals, fijas, columnas, keys y required. Permite editar la configuracion via el wizard.
Tab Cargas
Historial de subidas (ultimas 100 cargas) con la siguiente informacion por carga:
| Dato | Descripcion |
|---|---|
| Nombre fichero | Nombre original del fichero subido |
| Estado | ok, error, procesando o cancelado |
| Estado BPM | Estado actual en el Kanban (si aplica) |
| Filas OK / Error | Conteo de filas insertadas vs rechazadas |
| Fecha | Inicio y fin de la carga |
| Usuario | Quien realizo la carga |
Al expandir el detalle de una carga se muestra:
- Acciones disponibles: botones de acciones BPM filtrados por el
estado_bpmactual de la carga. - Valores de campos de carga: los valores que el usuario relleno al subir.
- Tablas de resultado: tablas generadas por pasos tipo
tabladel pipeline. - Flyouts: ficheros generados por pasos tipo
flyout, con boton de descarga. - Errores: filas rechazadas con linea, motivo y datos JSON.
- Log de ejecucion: registro detallado paso a paso del pipeline.
- Cargas hijas: cargas generadas por acciones BPM sobre esta carga.
Tab Datos
Tabla paginada con el contenido de la tabla dinamica dw_{empresa_id}_{nombre_tabla}. Muestra todas las columnas (internas y de usuario) con paginacion server-side.
Tab Vista
Contiene dos subtabs:
- Kanban
- Tablero drag & drop donde las columnas son los estados configurados y las cards son las cargas con
estado_bpm. Requiere que el bloque tenga estados Kanban configurados. Ver seccion Kanban / BPM. - Formulario publico
- Configuracion del formulario publico de carga para usuarios externos. Ver seccion Formularios publicos.
Tab Acciones
CRUD de acciones BPM disponibles sobre las cargas del bloque. Cada accion vincula un pipeline que se ejecuta sobre una carga existente. Ver seccion Kanban / BPM para el detalle completo.
| Campo | Descripcion |
|---|---|
nombre | Nombre visible de la accion (ej: "Aprobar", "Rechazar") |
pipeline_id | Pipeline a ejecutar sobre la carga |
icono | Icono opcional (emoji) |
estado_origen | Solo visible cuando la carga esta en este estado (NULL = siempre visible) |
Flujo de carga (upload)
El proceso de subida de datos a un bloque sigue 4 pasos:
Paso 1 — Campos de carga
Se abre un modal con los campos de carga definidos en el pipeline/bloque. Si hay grupos de campos configurados, el modal funciona como un wizard multi-paso:
- Se muestra el primer grupo visible (segun condiciones).
- El usuario rellena los campos y pulsa Continuar.
- Se evalua la condicion del siguiente grupo (
siempre,valor_igual,valor_diferente,sql). - Si el grupo es visible, se muestra; si no, se salta al siguiente.
- Al terminar los grupos, se muestra un resumen de valores rellenados.
Si no hay grupos configurados (modo legacy), todos los campos se muestran juntos en un solo paso.
Paso 2 — Selector de fichero
El usuario selecciona el fichero Excel (.xlsx, .xls) o CSV a subir. El fichero se sube al servidor y se guarda en uploads/tmp/.
Paso 3 — Preview
El sistema parsea el fichero segun la configuracion (fila cabecera, fila datos, hojas) y muestra las primeras 20 filas en una tabla preview. El usuario puede verificar que el mapeo de columnas es correcto antes de confirmar.
Paso 4 — Confirmacion
Al confirmar, el sistema ejecuta la siguiente secuencia:
- Singularity delete: si hay claves de singularidad (keys) configuradas, se eliminan las filas existentes que coincidan en los campos clave.
- Insert: se insertan las filas validas en la tabla dinamica, aplicando conversiones de tipo y verificando campos required.
- Pipeline: se ejecuta el pipeline post-carga (validaciones, SQL, variables, mailing, etc.).
- Log: se registran errores (filas rechazadas) y el resultado del pipeline.
- Estado BPM inicial: si el bloque tiene Kanban con estado
es_inicial=1, se asigna automaticamente.
El fichero se mueve de uploads/tmp/ a uploads/procesados/.
validacion_stop encuentra filas que violan la condicion, se hace rollback completo: se eliminan los datos insertados y se deshacen las operaciones SQL del pipeline. La carga queda con estado error.
Ejecucion sin fichero
Un bloque puede ejecutar su pipeline sin subir un fichero, mediante el boton "Ejecutar pipeline" en el tab Cargas. Esto es util para pipelines que solo necesitan campos de carga (sin datos de fichero).
El flujo:
- Se muestra un modal con los campos de carga (si los hay).
- Al confirmar, se crea una carga con
nombre_fichero = '[sin fichero]'. - Se inserta una unica fila en la tabla dinamica con los valores de las fijas (incluyendo fijas con
campo_carga_ref). - Se ejecuta el pipeline normalmente.
nombre_tabla (pipeline sin tabla), no se inserta ninguna fila — solo se ejecutan los pasos del pipeline. Esto es tipico de pipelines de accion BPM.
Fichero master
Cada bloque puede tener un fichero master de referencia. Este fichero se almacena en uploads/masters/ y sirve como plantilla o referencia para las subidas.
- Subir master
- Accion
save_masterendw_upload.php. Se sube via FormData y se guarda asociado al bloque. - Descargar master
- Accion
get_masterendw_upload.php. Sirve el fichero como descarga binaria con verificacion de ownership. - Uso en wizard
- Cuando se edita la configuracion del bloque/pipeline, el fichero master puede re-parsearse para actualizar la deteccion de columnas.
Singularidad (keys)
Las claves de singularidad controlan la deduplicacion de datos. Antes de insertar nuevas filas, se borran las filas existentes que coincidan en todos los campos clave definidos.
| Tipo de key | Fuente del valor | Ejemplo |
|---|---|---|
columna |
Dato del fichero (columna mapeada) | producto, fecha |
global |
Celda fija del fichero (globals) | ANIO, MES |
interno |
Campo interno de la tabla DW | _dw_bloque_id, _dw_fichero |
campo_carga |
Campo rellenado por el usuario al subir | Se resuelve via campo_carga_ref en la fija |
_dw_bloque_id. Al activarla, cada carga reemplaza todos los datos previos de ese bloque (comportamiento de reemplazo total).
Eliminar un bloque
Al eliminar un bloque:
- Se elimina el registro del bloque en
dw_bloques. - Se ejecuta
DROP TABLEsobre la tabla dinamicadw_{empresa_id}_{nombre_tabla}enmmaker_dw. - Se eliminan en cascada: cargas, errores, logs, campos de carga, acciones, estados Kanban, transiciones y bricks.
Endpoints relacionados
GET
| Endpoint | Params | Descripcion |
|---|---|---|
dw_bloques | — | Lista bloques con num_columnas, num_cargas |
dw_bloque_detalle | bloque_id | Config completa: columnas, globals, fijas, keys, required |
dw_cargas | bloque_id | Historial de cargas (ultimas 100) |
dw_carga_log | carga_id | Log de ejecucion del pipeline |
dw_carga_errores | carga_id | Filas rechazadas con motivo |
dw_datos | bloque_id, page?, per_page? | Datos paginados de la tabla dinamica |
POST
| Action | Campos clave | Descripcion |
|---|---|---|
dw_crear_bloque | nombre, nombre_tabla?, descripcion? | Crea bloque DW |
dw_actualizar_bloque | bloque_id, nombre?, descripcion? | Actualiza nombre/descripcion |
dw_eliminar_bloque | bloque_id | Elimina bloque + DROP tabla |
dw_guardar_config | bloque_id, columnas[], etc. | Guarda config completa + CREATE/ALTER tabla |
dw_asignar_pipeline_bloque | bloque_id, pipeline_id | Asigna pipeline al bloque |
dw_mover_bloque_app | bloque_id, app_id | Mueve bloque a otra app |
dw_upload.php
| Action | Tipo | Descripcion |
|---|---|---|
preview | FormData | Sube fichero a tmp, parsea y devuelve preview (20 filas) |
confirm | JSON | Singularity delete + insert + pipeline + log |
delete_carga | JSON | Elimina carga y sus datos de la tabla |
execute_pipeline | JSON | Ejecuta pipeline sin fichero |
save_master | FormData | Guarda fichero master de referencia |
get_master | GET | Descarga fichero master |
get_flyout | GET | Descarga fichero flyout generado |
Apps
Una App es una agrupacion logica de bloques dentro del modulo DW. Su funcion principal es organizar bloques relacionados bajo un mismo paraguas y, opcionalmente, proporcionar un pipeline de fallback que heredan todos sus bloques que no tengan pipeline propio asignado.
Pipeline efectivo (fallback)
El sistema resuelve el pipeline que aplica a cada bloque con la siguiente logica de cascada:
pipeline efectivo = bloque.pipeline_id ?? app.pipeline_id ?? null
- bloque.pipeline_id
- Si el bloque tiene un pipeline asignado directamente, se usa ese. Tiene prioridad maxima.
- app.pipeline_id
- Si el bloque NO tiene pipeline propio, hereda el pipeline configurado en su app contenedora. Este es el pipeline de fallback.
- null
- Si ni el bloque ni la app tienen pipeline, el bloque no tiene configuracion de proceso y no podra procesar cargas de fichero automaticamente.
Crear una app
Para crear una app nueva:
- En la seccion DW del sidebar, haz click en el boton "+ App" (o usa el menu contextual).
- Se abre un modal con los siguientes campos:
| Campo | Obligatorio | Descripcion |
|---|---|---|
| Nombre | Si | Nombre unico de la app dentro de la empresa. Identifica la app en el sidebar y en los paneles. |
| Descripcion | No | Texto descriptivo opcional sobre el proposito de la app. |
| Pipeline | No | Pipeline de fallback. Se selecciona de la lista de pipelines disponibles en la empresa. Puede dejarse vacio y asignarse posteriormente. |
- Haz click en Crear. La app aparecera en el sidebar bajo la seccion DW y se abrira su panel de detalle.
Panel de la app
Al seleccionar una app en el sidebar se muestra su panel de detalle con dos zonas principales:
Header
El header muestra:
- Nombre de la app (con boton de renombrar al hacer hover).
- Descripcion (si existe).
- Badge de pipeline: si la app tiene un pipeline de fallback asignado, aparece un badge con el nombre del pipeline. Si no, se indica que no hay pipeline configurado.
- Botones de Editar (nombre, descripcion, pipeline) y Eliminar.
Lista de bloques
Debajo del header se muestra la lista de todos los bloques que pertenecen a la app. Cada bloque aparece como una card con:
- Nombre del bloque.
- Nombre de la tabla dinamica asociada.
- Indicador del pipeline efectivo (propio o heredado de la app).
- Boton "Subir" que abre directamente el modal de subida de fichero para ese bloque (
selectBloqueDWAndUpload(id)).
Sidebar: arbol Apps → Bloques
La seccion DW del sidebar muestra un arbol jerarquico:
DW
+-- App "Ventas" [click para ver panel app]
| +-- Facturas [click para ver panel bloque]
| +-- Devoluciones [click para ver panel bloque]
| +-- Abonos [click para ver panel bloque]
+-- App "RRHH"
+-- Nominas
+-- Asistencia
- Hacer click en el nombre de la app abre su panel de detalle.
- Hacer click en el triangulo/flecha expande o colapsa los bloques hijos sin cambiar la seleccion activa.
- Hacer click en un bloque abre el panel de detalle del bloque (con sus tabs: Estructura, Cargas, Datos, Kanban, etc.).
- El buscador del sidebar filtra tanto apps como bloques por nombre. Si un bloque coincide con la busqueda, su app padre se expande automaticamente.
Mover bloques entre apps
Un bloque puede moverse de una app a otra mediante el endpoint dw_mover_bloque_app:
| Parametro | Descripcion |
|---|---|
bloque_id |
ID del bloque a mover. |
app_id |
ID de la app destino. |
pipeline_id = NULL), su pipeline efectivo cambiara al fallback de la nueva app. Esto puede alterar como se procesan las cargas en ese bloque. Verifica que la nueva app tiene un pipeline compatible o asigna un pipeline directo al bloque antes de moverlo.
Eliminar una app
Para eliminar una app, usa el boton Eliminar en el panel de la app.
Pasos para eliminar una app con bloques:
- Mover cada bloque a otra app con
dw_mover_bloque_app. - Alternativamente, eliminar los bloques (esto tambien elimina sus tablas dinamicas y todo su historial de cargas).
- Una vez la app esta vacia, usar
dw_eliminar_app.
Permisos de acceso
El sistema de permisos permite controlar el acceso a apps y bloques de forma granular con dos ejes:
- Eje app (acceso a nivel de app)
- Al asignar permiso
dw_appa un usuario, este hereda acceso a todos los bloques de esa app. Es la forma mas sencilla de dar acceso cuando el usuario necesita ver/usar toda la app. - Eje bloque (acceso a nivel de bloque)
- Al asignar permiso
dw_bloquea un usuario, este accede solo a ese bloque concreto, independientemente de la app. Util cuando un usuario solo necesita acceso a un subconjunto de bloques.
| Tipo de permiso | Alcance | Caso de uso |
|---|---|---|
dw_app |
Todos los bloques de la app | Usuario que gestiona toda el area (ej: todo "Ventas") |
dw_bloque |
Solo el bloque especifico | Usuario que solo sube facturas pero no devoluciones |
La gestion de permisos se realiza desde el panel de Administracion (seccion Usuarios), donde se pueden asignar y revocar permisos por usuario. Tambien se puede ver que usuarios tienen acceso a un recurso concreto desde la tab Permisos del gestor de tablas DW.
Casos de uso
Ejemplo 1: App "Ventas" con pipeline compartido
Una empresa recibe tres tipos de ficheros comerciales con la misma estructura (columnas producto, fecha, importe, cliente):
App "Ventas"
pipeline_id = 5 (Pipeline "Ventas Estandar")
+-- Bloque "Facturas" (pipeline_id = NULL -> hereda Pipeline 5)
+-- Bloque "Devoluciones" (pipeline_id = NULL -> hereda Pipeline 5)
+-- Bloque "Abonos" (pipeline_id = NULL -> hereda Pipeline 5)
Los tres bloques comparten el mismo pipeline de proceso. Cada uno tiene su propia tabla dinamica (dw_1_facturas, dw_1_devoluciones, dw_1_abonos), pero las columnas, validaciones y pasos post-carga son identicos. Si necesitas cambiar una validacion, la cambias una sola vez en el Pipeline 5 y aplica a los tres bloques.
Ejemplo 2: App con pipeline fallback y override
Una app donde la mayoria de bloques usan el mismo proceso, pero uno necesita un proceso diferente:
App "Informes RRHH"
pipeline_id = 8 (Pipeline "RRHH Estandar")
+-- Bloque "Nominas" (pipeline_id = NULL -> hereda Pipeline 8)
+-- Bloque "Asistencia" (pipeline_id = NULL -> hereda Pipeline 8)
+-- Bloque "Evaluaciones" (pipeline_id = 12 -> usa Pipeline 12, ignora fallback)
Nominas y Asistencia heredan el pipeline estandar de la app. Evaluaciones tiene su propio pipeline porque la estructura del fichero es diferente (diferentes columnas, diferentes validaciones). No es necesario sacar Evaluaciones a otra app: basta con asignarle su pipeline propio.
Ejemplo 3: App como agrupacion organizativa
Si no necesitas pipeline de fallback, la app funciona simplemente como agrupacion visual/organizativa:
App "Datos Maestros"
pipeline_id = NULL (sin fallback)
+-- Bloque "Productos" (pipeline_id = 3)
+-- Bloque "Clientes" (pipeline_id = 4)
+-- Bloque "Proveedores" (pipeline_id = 5)
Cada bloque tiene su propio pipeline porque cada maestro tiene una estructura diferente. La app solo sirve para agruparlos logicamente en el sidebar y facilitar la gestion de permisos (un solo permiso dw_app da acceso a los tres bloques).
Endpoints de la API
GET
| Endpoint | Parametros | Descripcion |
|---|---|---|
dw_apps |
— | Lista todas las apps accesibles con num_bloques y pipeline_nombre. |
dw_app_detalle |
app_id |
Detalle de la app con su lista de bloques. |
POST
| Action | Campos | Descripcion |
|---|---|---|
dw_crear_app |
nombre, descripcion?, pipeline_id? |
Crea una nueva app. |
dw_actualizar_app |
app_id, nombre?, descripcion?, pipeline_id? |
Actualiza nombre, descripcion o pipeline de la app. |
dw_eliminar_app |
app_id |
Elimina la app (solo si no tiene bloques). |
dw_mover_bloque_app |
bloque_id, app_id |
Mueve un bloque a otra app. |
Resumen
| Aspecto | Detalle |
|---|---|
| Funcion principal | Agrupar bloques relacionados y compartir pipeline |
| Pipeline fallback | bloque.pipeline_id ?? app.pipeline_id |
| Eliminacion | Solo si la app no tiene bloques |
| Permisos | Eje app (todos los bloques) o eje bloque (individual) |
| Sidebar | Arbol DW con nodos expandibles/colapsables |
| Nombre unico | Por empresa (UNIQUE KEY (empresa_id, nombre)) |
Campos de Carga
Los campos de carga son formularios que el usuario debe rellenar antes o durante la subida de un fichero a un bloque. Permiten capturar informacion contextual que no viene en el propio fichero: periodo, cliente, responsable, fecha de corte, adjuntos, etc.
Se configuran en el pipeline asignado al bloque (o directamente en el bloque en modo legacy). Cuando el usuario inicia una carga, el sistema presenta estos campos antes de mostrar la preview del fichero.
campo_carga_ref apuntando al campo. Esto se explica en detalle mas abajo.
Propiedades de un campo
Cada campo de carga tiene las siguientes propiedades:
- nombre_campo
- Nombre interno del campo. Se usa como identificador en el sistema: en las referencias
{{nombre_campo}}dentro de SQLs del pipeline, en las columnas fijas concampo_carga_ref, y en las condiciones de grupos. Debe ser unico dentro del pipeline. Se recomienda usar nombres cortos, sin espacios ni caracteres especiales (ej:periodo,cliente_id,fecha_corte). - etiqueta
- Texto visible para el usuario en el formulario de carga. Puede ser largo y descriptivo (ej: "Seleccione el periodo de reporte", "Fecha de corte del informe").
- tipo
- Determina el tipo de control que se presenta al usuario. Los tipos disponibles son:
input,number,select,date,file. Cada uno se describe en detalle a continuacion. - opciones
- Solo aplica al tipo
select. Define las opciones del desplegable, ya sea como lista CSV o como consulta SQL. Se detalla en la seccion de tipo select. - obligatorio
- Si esta activado, el usuario no puede continuar con la carga sin rellenar este campo. Los campos obligatorios se muestran con un indicador visual (asterisco) en el formulario.
- orden
- Posicion del campo dentro de su grupo (o dentro de la lista general si no hay grupos). Los campos se presentan al usuario en orden ascendente.
Tipos de campo
input — Texto libre
Campo de texto de una sola linea. El usuario puede escribir cualquier valor. Util para nombres, codigos, referencias, comentarios cortos.
| Propiedad | Valor |
|---|---|
| Control HTML | <input type="text"> |
| Validacion | Solo obligatoriedad (si esta marcado) |
| Opciones | No aplica (se ignora) |
| Valor almacenado | Texto exacto introducido por el usuario |
number — Numerico
Campo numerico. Acepta enteros y decimales. El navegador muestra controles de incremento/decremento y valida que el contenido sea un numero.
| Propiedad | Valor |
|---|---|
| Control HTML | <input type="number" step="any"> |
| Validacion | Obligatoriedad + formato numerico |
| Opciones | No aplica |
| Valor almacenado | Numero como texto (ej: 1234.56) |
step="any" permite decimales con cualquier precision. Si el usuario escribe "3.14159", ese valor exacto se almacena.
select — Desplegable
Campo de seleccion con opciones predefinidas. Las opciones se definen en el campo opciones de dos maneras:
Opciones estaticas (lista CSV)
Una lista de valores separados por comas. Cada valor se usa tanto como etiqueta visible como valor almacenado.
Ene,Feb,Mar,Abr,May,Jun,Jul,Ago,Sep,Oct,Nov,Dic
Esto genera un desplegable con 12 opciones. Si el usuario selecciona "Mar", el valor almacenado sera Mar.
Ventas,Compras,RRHH,Finanzas
Opciones dinamicas (consulta SQL)
Si el contenido del campo opciones empieza por SQL:, el sistema ejecuta la consulta contra la base de datos mmaker_dw para obtener las opciones en tiempo real.
SQL:SELECT elemento, valor, seleccionado FROM mi_tabla_opciones WHERE activo = 1 ORDER BY elemento
La consulta debe devolver columnas con estos nombres exactos:
| Columna | Obligatoria | Descripcion |
|---|---|---|
elemento | Si | Texto visible en el desplegable (lo que ve el usuario) |
valor | Si | Valor interno que se almacena cuando el usuario selecciona esta opcion |
seleccionado | No | Si es 1, esta opcion aparece pre-seleccionada al abrir el formulario. Solo una opcion deberia tener este valor. |
SQL:SELECT nombre AS elemento, id AS valor, 0 AS seleccionado FROM `mmaker_dw`.`dw_1_clientes` WHERE activo = 1 ORDER BY nombre
Esto genera un desplegable con los nombres de clientes, pero almacena el ID numerico.
Selects dependientes (variables {{campo}})
Las consultas SQL de un select pueden referenciar el valor de otros campos de carga usando la sintaxis {{nombre_campo}}. Esto permite crear selects en cascada donde las opciones de un campo dependen de lo que el usuario haya seleccionado en otro campo anterior.
SQL:SELECT nombre AS elemento, id AS valor, 0 AS seleccionado FROM `mmaker_dw`.`dw_1_ciudades` WHERE pais_id = '{{pais}}' ORDER BY nombre
En este ejemplo, {{pais}} se sustituye por el valor que el usuario haya seleccionado en el campo pais. Las opciones del select se recargan cada vez que se navega entre grupos del wizard.
{{campo}} se re-evaluan cada vez que el usuario navega entre grupos del wizard. Si el usuario cambia el valor de "pais" y vuelve al grupo que contiene "ciudad", las opciones de ciudad se recargan con el nuevo valor de pais.
date — Selector de fecha
Campo de fecha. El navegador muestra un calendario nativo para seleccionar la fecha.
| Propiedad | Valor |
|---|---|
| Control HTML | <input type="date"> |
| Validacion | Obligatoriedad + formato fecha valido |
| Opciones | No aplica |
| Valor almacenado | Fecha en formato ISO: YYYY-MM-DD (ej: 2026-04-07) |
file — Adjunto
Campo para subir un fichero adjunto. A diferencia del fichero principal de la carga (el que se parsea y carga en la tabla), los adjuntos de tipo file son ficheros complementarios que se guardan tal cual, sin parsear.
| Propiedad | Valor |
|---|---|
| Control HTML | <input type="file"> |
| Almacenamiento | uploads/adjuntos/ con nombre interno unico |
| Registro | Tabla dw_carga_adjuntos (nombre original, nombre interno, tamano) |
| Opciones | No aplica |
uniqid()), no con el nombre original del usuario. El directorio uploads/adjuntos/ tiene un .htaccess que deniega el acceso directo. Solo se pueden descargar a traves de endpoints PHP con verificacion de permisos.
file no se pueden usar como valor de una columna fija (campo_carga_ref). Tampoco se incluyen en los valores por defecto de schedules (ejecuciones programadas) ni de radares, ya que estos procesos se ejecutan sin intervencion del usuario.
Almacenamiento de valores
Los valores que el usuario introduce en los campos de carga se guardan en la tabla dw_carga_campos_valores, vinculados a la carga (carga_id). Cada fila tiene:
| Columna | Descripcion |
|---|---|
carga_id | ID de la carga a la que pertenecen los valores |
nombre_campo | Nombre interno del campo (coincide con la configuracion) |
valor | Valor introducido por el usuario (siempre como texto) |
Esto significa que para cada carga se guarda un registro de que valores uso el usuario. Se puede consultar despues en el historial de cargas.
Vincular campos a columnas de la tabla (campo_carga_ref)
Por defecto, los campos de carga solo se guardan como metadatos de la carga (en dw_carga_campos_valores). No aparecen como columnas en la tabla dinamica del bloque.
Para que el valor de un campo aparezca en cada fila de la tabla dinamica, hay que crear una columna fija con la propiedad campo_carga_ref apuntando al campo.
Como hacerlo
- Ve a la configuracion de estructura del pipeline (o bloque legacy).
- En la seccion Columnas fijas, anade una nueva fija.
- Dale un
nombre_campo(que sera el nombre de la columna en la tabla). - En lugar de escribir un valor literal, activa el toggle para cambiar a modo referencia a campo de carga.
- Selecciona el campo de carga del desplegable.
Ahora, cada vez que se haga una carga, el valor que el usuario introduzca en ese campo se insertara en cada fila de la tabla como valor de esa columna fija.
periodo (tipo select con opciones Ene, Feb, Mar...) y creas una fija periodo con campo_carga_ref = periodo, cada fila del fichero subido tendra una columna periodo con el valor seleccionado por el usuario (ej: "Mar").
Singularidad por campo de carga
Las columnas fijas vinculadas a campos de carga tambien pueden participar en la singularidad (keys). Si necesitas que la combinacion de claves incluya el campo de carga, anade una key de tipo campo_carga con el nombre del campo. El sistema resolvera el valor buscando la fija que tiene campo_carga_ref apuntando a ese campo.
Uso en el pipeline (variables)
Los valores de los campos de carga estan disponibles como variables en todos los pasos del pipeline. Se referencian con la sintaxis {{nombre_campo}} dentro de cualquier SQL del pipeline.
SELECT * FROM {{_DW_TABLA}}
WHERE _dw_carga_id = {{_DW_CARGA_ID}}
AND periodo = '{{periodo}}'
En este ejemplo, {{periodo}} se sustituye por el valor que el usuario selecciono en el campo periodo.
Grupos de campos (wizard multi-paso)
Cuando un pipeline tiene muchos campos de carga, o cuando algunos campos solo aplican en ciertos casos, se pueden organizar en grupos. Los grupos convierten el formulario de carga en un wizard de multiples pasos.
Sin grupos (modo legacy)
Si no se definen grupos, todos los campos se muestran a la vez en un unico paso del formulario, seguidos del selector de fichero. Este es el comportamiento clasico.
Con grupos
Si se definen uno o mas grupos, el formulario de carga se convierte en un wizard:
- Se muestra el primer grupo visible con sus campos.
- El usuario rellena los campos y pulsa Continuar.
- Se evalua la condicion del siguiente grupo. Si es visible, se muestran sus campos.
- Si no es visible, se salta al siguiente grupo cuya condicion se cumpla.
- Al llegar al final de los grupos, se muestra un resumen de todos los valores introducidos mas el selector de fichero.
- El usuario confirma y se procede a la preview.
Los botones Continuar y Atras permiten navegar entre grupos.
Propiedades de un grupo
- nombre
- Titulo visible del grupo en el wizard. Se muestra como encabezado del paso actual.
- orden
- Posicion del grupo en la secuencia del wizard. Los grupos se presentan en orden ascendente.
- condicion_tipo
- Determina cuando se muestra el grupo. Las opciones son:
siempre— El grupo se muestra siempre, sin condicion.valor_igual— El grupo solo se muestra si el valor de otro campo es igual a un valor especifico.valor_diferente— El grupo solo se muestra si el valor de otro campo es diferente de un valor especifico.sql— El grupo se muestra si una consulta SQL devuelve al menos una fila (evaluacion server-side).
- condicion_campo
- Solo aplica a
valor_igualyvalor_diferente. Nombre del campo de carga cuyo valor se evalua. Debe ser un campo de un grupo anterior (ya rellenado por el usuario). - condicion_valor
- Solo aplica a
valor_igualyvalor_diferente. Valor contra el que se compara. Parasql, contiene la consulta SQL a ejecutar.
Ejemplo de grupos condicionales
Supongamos un proceso donde el usuario primero selecciona el tipo de operacion, y luego se muestran campos diferentes segun la seleccion:
| Grupo | Orden | Condicion | Campos |
|---|---|---|---|
| Datos generales | 1 | siempre |
tipo_operacion (select: Venta, Compra, Devolucion), fecha |
| Datos de venta | 2 | valor_igual, campo: tipo_operacion, valor: Venta |
cliente, vendedor, descuento |
| Datos de compra | 3 | valor_igual, campo: tipo_operacion, valor: Compra |
proveedor, orden_compra |
| Datos de devolucion | 4 | valor_igual, campo: tipo_operacion, valor: Devolucion |
motivo, referencia_original |
Si el usuario selecciona "Venta", vera: Datos generales → Datos de venta → Resumen. Los grupos de compra y devolucion se saltan automaticamente.
Campos sin grupo
Los campos que no pertenecen a ningun grupo se muestran en un paso implicito inicial, antes de los grupos definidos. Si todos los campos tienen grupo asignado, no existe paso implicito.
Condicion SQL en grupos
La condicion sql permite logica mas compleja. La consulta se ejecuta en el servidor (mmaker_dw) y puede referenciar campos ya rellenados con {{nombre_campo}}:
SELECT 1 FROM `mmaker_dw`.`dw_1_configuracion` WHERE tipo = '{{tipo_operacion}}' AND requiere_aprobacion = 1
Si la consulta devuelve al menos una fila, el grupo se muestra. Si no devuelve filas, se salta.
Pipeline sin fichero
Cuando un pipeline se configura sin fichero (toggle "Sin fichero" en el wizard), los campos de carga se convierten en la unica fuente de datos. En este modo:
- No se sube ningun fichero Excel/CSV.
- Cada carga inserta una sola fila en la tabla dinamica.
- Los valores de esa fila provienen de las columnas fijas vinculadas a campos de carga (
campo_carga_ref). - El wizard auto-genera una fija por cada campo de carga (excepto tipo
file).
Este modo es util para procesos de alta manual: dar de alta un registro, registrar una incidencia, capturar un evento, etc.
Configuracion en la UI
Donde se configuran
Los campos de carga se configuran en el paso 2 del wizard de creacion/edicion de pipeline (o bloque legacy). El paso 2 esta dedicado exclusivamente a los campos de carga.
Acciones disponibles
- Anadir campo: Boton para crear un nuevo campo con las propiedades descritas arriba.
- Reordenar: Arrastrar campos para cambiar su orden de presentacion.
- Editar: Modificar cualquier propiedad de un campo existente.
- Eliminar: Quitar un campo del pipeline. Los valores ya guardados en cargas anteriores se conservan en
dw_carga_campos_valores. - Crear grupo: Organizar campos en grupos para el wizard multi-paso.
Campos en ejecuciones programadas (schedules) y radares
Los schedules y radares pueden preconfigurar valores por defecto para los campos de carga. Estos valores se usan automaticamente cuando la ejecucion se dispara sin intervencion del usuario. Los campos de tipo file se excluyen de los valores por defecto, ya que no se pueden preconfigurar ficheros adjuntos.
Pasos del Pipeline (Post-carga)
Los pasos del pipeline son acciones que se ejecutan automaticamente despues de que los datos se insertan en la tabla dinamica de un bloque. Forman un arbol de decision que puede validar datos, ejecutar SQL, capturar variables, enviar emails, generar ficheros, cambiar estados y mas.
Los pasos se configuran en el pipeline asignado al bloque. Se ejecutan en orden (campo orden), salvo que las transiciones redirijan el flujo a un paso diferente.
validacion_stop detecta un problema, se hace rollback de todo: los datos insertados y cualquier cambio SQL del pipeline se deshacen.
Conceptos generales
Orden de ejecucion
Por defecto, los pasos se ejecutan secuencialmente segun su campo orden. Sin embargo, si un paso tiene transiciones definidas, el flujo salta al paso indicado por la transicion que se cumpla. Si no se cumple ninguna transicion y existe una de tipo resto, se usa esa como fallback.
Si no hay transiciones definidas para un paso, simplemente se continua con el siguiente paso por orden.
Proteccion anti-bucle
Un mismo paso nunca se ejecuta dos veces en la misma ejecucion del pipeline. Si una transicion apunta a un paso ya ejecutado, se salta y se continua con el siguiente.
Condicion de ejecucion (sql_condicion)
Cualquier paso puede tener un campo sql_condicion. Si esta definido, el sistema ejecuta esa consulta SQL antes del paso:
- Si la consulta devuelve al menos una fila → el paso se ejecuta.
- Si la consulta no devuelve filas → el paso se salta (se pasa al siguiente).
Esto permite ejecutar pasos condicionalmente sin necesidad de usar transiciones. La sql_condicion puede usar las mismas variables ({{...}}) que el resto del paso.
SELECT 1 FROM {{_DW_TABLA}} WHERE _dw_carga_id = {{_DW_CARGA_ID}} AND importe > 10000
En este ejemplo, el paso solo se ejecuta si hay alguna fila con importe mayor a 10.000.
Variables disponibles
Todos los pasos del pipeline pueden usar variables dentro de sus campos SQL. Se referencian con la sintaxis {{NOMBRE}} y se sustituyen antes de ejecutar la SQL.
| Variable | Descripcion |
|---|---|
{{_DW_CARGA_ID}} | ID de la carga actual |
{{_DW_TABLA}} | Nombre completo de la tabla dinamica (ej: `mmaker_dw`.`dw_1_ventas`) |
{{_DW_BLOQUE_ID}} | ID del bloque |
{{_DW_FICHERO}} | Nombre del fichero subido |
{{_DW_PARENT_CARGA_ID}} | ID de la carga padre (solo en acciones BPM vinculadas a otra carga) |
{{_DW_ESTADO_BPM}} | Estado BPM actual de la carga (se actualiza tras pasos de tipo estado) |
{{ESTADO}} | Estado interno del pipeline: empieza como ok, pasa a error si falla algo |
{{nombre_campo}} | Valor del campo de carga con ese nombre (rellenado por el usuario) |
{{variable_paso}} | Variable capturada por un paso anterior de tipo variable |
variable en modo fijo puede tener variable_valor = "Reporte de {{periodo}} - {{cliente}}", combinando valores de campos de carga.
Variable {{ESTADO}}
La variable {{ESTADO}} es un indicador interno que refleja si el pipeline ha tenido problemas:
- Empieza con valor
ok. - Pasa a
errorsi un pasovalidacion_stopdispara (encuentra filas problematicas). - Pasa a
errorsi una SQL falla en su ejecucion. - Se comparte entre el pipeline padre y los triggers anidados.
Puedes usar {{ESTADO}} en transiciones para bifurcar el flujo segun si hubo errores o no.
Mensaje de usuario (mensaje_usuario)
Los pasos de validacion (validacion_stop y validacion_alarma) pueden tener una plantilla mensaje_usuario. Esta plantilla genera mensajes legibles para el usuario a partir de las filas del resultado SQL.
La plantilla usa {{columna}} para sustituir valores de cada fila del resultado SQL:
La fila {{linea}} tiene el producto "{{producto}}" con importe negativo ({{importe}})
Si no se define mensaje_usuario, el sistema busca una columna MSG en el resultado SQL. Si tampoco existe, se muestra un volcado JSON de la fila.
Tipos de paso
validacion_stop — Validacion con rollback
El paso mas critico del pipeline. Ejecuta una consulta SQL y, si devuelve filas, se considera que la validacion ha fallado. Todos los datos de la carga se eliminan (rollback completo: DELETE de las filas insertadas + reversion de cualquier SQL ejecutada previamente en el pipeline).
- sql_code
- Consulta SQL que busca filas problematicas. Si devuelve al menos una fila, la validacion falla. Si no devuelve ninguna fila, la validacion pasa y el pipeline continua.
SELECT _dw_linea AS linea, producto, importe FROM {{_DW_TABLA}} WHERE _dw_carga_id = {{_DW_CARGA_ID}} AND importe < 0 - mensaje_usuario
- Plantilla para generar mensajes legibles por cada fila problematica. Usa
{{columna}}para insertar valores del resultado SQL.Linea {{linea}}: el producto "{{producto}}" tiene importe negativo ({{importe}})
Jerarquia de mensajes de error:
- Si
mensaje_usuarioesta definido → se aplica la plantilla a cada fila. - Si no, y la SQL tiene una columna
MSG→ se usa el valor de esa columna. - Si ninguno → se muestra un volcado JSON de cada fila.
INSERT, UPDATE o DELETE ejecutado por pasos anteriores del mismo pipeline tambien se deshace. Esto es posible porque todo el pipeline se ejecuta dentro de una transaccion.
Efecto en {{ESTADO}}: Si la validacion falla, {{ESTADO}} pasa a error.
validacion_alarma — Validacion sin rollback
Funciona igual que validacion_stop en cuanto a la SQL y los mensajes, pero con una diferencia fundamental: NO hace rollback. Los datos se mantienen y la carga se completa. Las filas problematicas se muestran como advertencias (warnings) al usuario.
- sql_code
- Misma logica que
validacion_stop. Consulta que busca filas sospechosas. - mensaje_usuario
- Misma plantilla que
validacion_stoppara mensajes legibles.
Las advertencias se muestran en el modal de preview despues de confirmar la carga, junto a la tabla de resultados (si la hay). El usuario ve los datos pero es informado de los problemas.
sql — Ejecucion SQL
Ejecuta una consulta SQL directamente contra la base de datos mmaker_dw. Puede ser cualquier operacion DML: INSERT, UPDATE, DELETE, o incluso CREATE INDEX.
- sql_code
- Consulta SQL a ejecutar. El numero de filas afectadas se registra en el log de la carga.
UPDATE {{_DW_TABLA}} SET importe_eur = importe * tipo_cambio WHERE _dw_carga_id = {{_DW_CARGA_ID}}
El resultado del paso (filas afectadas) se registra en el log. Si la SQL falla, {{ESTADO}} pasa a error y el error se registra en el log, pero el pipeline continua con los pasos siguientes (no hace rollback automatico — para eso existe validacion_stop).
- Calcular columnas derivadas (conversiones, porcentajes, clasificaciones).
- Actualizar tablas de resumen o agregados.
- Insertar registros en otras tablas (logs, auditorias, notificaciones).
- Borrar datos antiguos o temporales.
variable — Captura de variable
Captura un valor y lo convierte en una variable disponible para los pasos siguientes del pipeline. Tiene dos modos de funcionamiento:
Modo SQL
Ejecuta una consulta SQL y convierte las columnas de la primera fila del resultado en variables. Cada columna se convierte en una variable con el nombre de la columna.
- sql_code
- Consulta que devuelve los valores a capturar.
SELECT COUNT(*) AS total_filas, SUM(importe) AS importe_total, MAX(fecha) AS fecha_mas_reciente FROM {{_DW_TABLA}} WHERE _dw_carga_id = {{_DW_CARGA_ID}}
Despues de este paso, las variables {{total_filas}}, {{importe_total}} y {{fecha_mas_reciente}} estan disponibles en todos los pasos siguientes.
Modo fijo
Asigna un valor literal directamente, sin ejecutar SQL.
- variable_nombre
- Nombre de la variable a crear (ej:
titulo_reporte). - variable_valor
- Valor literal a asignar. Puede referenciar otras variables con
{{...}}.Reporte de {{periodo}} - {{cliente}} ({{total_filas}} filas)
Despues de este paso, {{titulo_reporte}} contiene el texto con las variables sustituidas.
Persistencia de variables
Todas las variables capturadas (tanto por SQL como por modo fijo) se guardan en la tabla dw_pipeline_variables vinculadas a la carga. Esto permite:
- Consultar los valores capturados en el historial de cargas.
- Mostrar informacion en las tarjetas del Kanban (via bricks).
- Auditar que valores se usaron en cada ejecucion del pipeline.
mailing — Envio de emails
Envia emails con adjuntos generados dinamicamente a partir de una consulta SQL. Requiere que la empresa tenga configurado el SMTP en dw_mail_config.
- sql_contenido
- Importante: El mailing usa el campo
sql_contenido, nosql_code. Esta consulta genera los datos que se usaran tanto para el cuerpo del email como para los ficheros adjuntos.SELECT c.email AS DESTINO, c.nombre AS cliente_nombre, v.fecha, v.producto, v.importe, CONCAT(c.nombre, '_', DATE_FORMAT(v.fecha, '%Y%m')) AS ADJUNTO FROM {{_DW_TABLA}} v JOIN `mmaker_dw`.`dw_1_clientes` c ON c.id = v.cliente_id WHERE v._dw_carga_id = {{_DW_CARGA_ID}}
Columnas especiales en la SQL
| Columna | Obligatoria | Descripcion |
|---|---|---|
DESTINO | Si | Direccion(es) de email del destinatario. Puede ser un solo email o multiples separados por coma (ana@empresa.com,pedro@empresa.com). |
ADJUNTO | No | Clave de agrupacion. Todas las filas con el mismo valor de ADJUNTO se agrupan en un unico fichero adjunto. Cada valor distinto genera un fichero separado. Si no existe esta columna, todas las filas van en un solo adjunto. |
FORMATO | No | csv o excel. Determina el formato del fichero adjunto. Si no existe, se usa excel por defecto. |
ELEMENT | No | Variable adicional disponible para sustitucion en el asunto y cuerpo del email. Util para personalizar el mensaje con datos de la fila. |
- mail_titulo
- Asunto del email. Soporta variables:
{{ADJUNTO}},{{ELEMENT}}, y cualquier variable del pipeline.Informe de ventas - {{ADJUNTO}} - {{periodo}} - mail_cuerpo
- Cuerpo HTML del email. Mismas sustituciones que el titulo.
<h2>Informe de ventas</h2> <p>Adjunto el informe de ventas para {{ADJUNTO}}.</p> <p>Periodo: {{periodo}}</p> <p>Total filas procesadas: {{total_filas}}</p>
Como funciona el proceso de envio
- Se ejecuta
sql_contenidopara obtener los datos. - Las filas se agrupan por el valor de
ADJUNTO(si existe la columna). - Por cada grupo, se genera un fichero adjunto (Excel XML 2003 o CSV segun
FORMATO) con las columnas de datos (excluyendo las columnas especiales DESTINO, ADJUNTO, FORMATO, ELEMENT). - Se recopilan las direcciones de email unicas de la columna
DESTINOde ese grupo. - Se envia el email con el adjunto a todos los destinatarios del grupo.
- El envio se registra en
dw_mail_log.
ADJUNTO (ej: "Ana_202604", "Pedro_202604", "Luis_202604"), se enviaran 3 emails: cada uno con un fichero Excel que solo contiene las filas de ventas de ese cliente.
trigger — Llamada a otro pipeline
Ejecuta otro pipeline completo dentro del pipeline actual. Es como una "llamada a funcion": el pipeline referenciado se ejecuta inline, compartiendo el contexto (variables, carga, transaccion).
- trigger_pipeline_id
- ID del pipeline a ejecutar. Se selecciona de una lista de pipelines disponibles en la empresa.
Comportamiento detallado
| Aspecto | Comportamiento |
|---|---|
| Variables | Se comparten bidireccionalmente. Variables del padre estan disponibles en el trigger, y variables creadas en el trigger estan disponibles en el padre tras volver. |
| validacion_stop | Si un validacion_stop dispara dentro del trigger, aborta todo: el trigger y el pipeline padre. Rollback completo. |
| Transicion FIN | Una transicion que apunta a NULL (fin del pipeline) dentro del trigger solo termina el trigger. El pipeline padre continua con su siguiente paso. |
| {{ESTADO}} | Se comparte. Si el trigger falla, el padre ve {{ESTADO}} = 'error'. |
| Profundidad | Maximo 5 niveles de anidamiento (trigger dentro de trigger dentro de trigger...). Si se supera, el paso falla con error. |
| Log | Los mensajes de log del trigger se prefijan con el nombre del pipeline trigger para distinguirlos del padre. |
bucle — Iteracion (loop)
Ejecuta un conjunto de SQLs embebidas para cada fila del resultado de una consulta principal. Util para operaciones que requieren procesar registros uno a uno.
- sql_code
- Consulta principal del bucle. Cada fila del resultado es una iteracion.
SELECT DISTINCT cliente_id, cliente_nombre FROM {{_DW_TABLA}} WHERE _dw_carga_id = {{_DW_CARGA_ID}} - bucle_pasos
- Array JSON de SQLs embebidas que se ejecutan por cada fila. Cada elemento tiene
nombre(descriptivo) ysql(la consulta a ejecutar).[ { "nombre": "Actualizar totales", "sql": "UPDATE `mmaker_dw`.`dw_1_resumen_clientes` SET total = (SELECT SUM(importe) FROM {{_DW_TABLA}} WHERE cliente_id = '{{cliente_id}}') WHERE id = '{{cliente_id}}'" }, { "nombre": "Registrar actividad", "sql": "INSERT INTO `mmaker_dw`.`dw_1_log_actividad` (cliente_id, accion, fecha) VALUES ('{{cliente_id}}', 'carga_actualizada', NOW())" } ]
Comportamiento detallado
- Las columnas de cada fila del resultado de
sql_codese convierten en variables temporales (ej:{{cliente_id}},{{cliente_nombre}}). - Las variables generales del pipeline siguen disponibles dentro del bucle.
- Al terminar cada iteracion, las variables temporales se restauran a sus valores originales (no contaminan la siguiente iteracion ni el pipeline padre).
- Si una SQL embebida falla,
{{ESTADO}}pasa aerrory se registra en el log, pero el bucle continua con las siguientes iteraciones. - El log muestra:
Bucle[0].Actualizar totales: 1 fila(s) afectada(s).
UPDATE ... JOIN o INSERT ... SELECT en lugar de un bucle. Reserva los bucles para operaciones que realmente requieren procesamiento fila a fila.
tabla — Tabla de resultados
Genera una tabla de datos que se muestra al usuario en la interfaz. No modifica datos — solo sirve para mostrar informacion.
- sql_code
- Consulta que genera los datos a mostrar.
SELECT producto, SUM(importe) AS total_importe, COUNT(*) AS num_filas FROM {{_DW_TABLA}} WHERE _dw_carga_id = {{_DW_CARGA_ID}} GROUP BY producto ORDER BY total_importe DESC
El resultado se guarda en el log de la carga (dw_carga_log) con tipo = 'tabla' y se muestra en dos lugares:
- Post-carga: En el modal de preview despues de confirmar, junto a los warnings de alarma (si los hay).
- Detalle de carga: En la vista de historial, seccion "Tablas de resultado" arriba del log de ejecucion.
Si hay varios pasos de tipo tabla en el pipeline, las tablas se muestran apiladas (una debajo de otra), cada una con su titulo (el nombre del paso).
flyout — Generacion de fichero
Genera un fichero Excel o CSV a partir de una consulta SQL. El fichero puede descargarse desde la interfaz o enviarse directamente a un servidor FTP/SFTP.
- sql_code
- Consulta que genera los datos del fichero.
SELECT producto, fecha, importe, cliente_nombre FROM {{_DW_TABLA}} t JOIN `mmaker_dw`.`dw_1_clientes` c ON c.id = t.cliente_id WHERE t._dw_carga_id = {{_DW_CARGA_ID}} ORDER BY fecha, producto - flyout_formato
excel(formato Excel XML 2003, extension .xls) ocsv(texto plano separado por punto y coma).- flyout_nombre
- Nombre del fichero generado. Soporta variables
{{...}}para nombres dinamicos.Ventas_{{periodo}}_{{cliente}}.xls - flyout_destino
-
descarga— El fichero se guarda enuploads/flyouts/y esta disponible para descarga desde el detalle de la carga en la UI.ftp— El fichero se envia automaticamente a un servidor FTP/SFTP configurado.
- flyout_ftp_id
- Solo si
flyout_destino = ftp. Referencia a la configuracion FTP/SFTP endw_ftp_config(se selecciona del desplegable en la UI).
El registro del fichero generado se guarda en dw_flyout_log con informacion de nombre, formato, destino, estado y numero de filas.
uploads/flyouts/ no son accesibles directamente via URL. Solo se pueden descargar a traves del endpoint get_flyout, que verifica la propiedad del recurso (ownership) antes de servir el fichero.
estado — Cambio de estado BPM
Cambia el estado BPM (estado_bpm) de una carga. Se usa en pipelines vinculados a acciones Kanban y transiciones de estado.
- estado_valor
- Valor del estado a asignar. Puede ser un texto literal o usar variables
{{...}}para valor dinamico.AprobadoO con variable:
{{nuevo_estado}}
Comportamiento segun contexto
| Situacion | Comportamiento |
|---|---|
La carga tiene parent_carga_id | Asigna estado_bpm en la carga padre, no en la carga actual. |
La carga NO tiene parent_carga_id | Asigna estado_bpm en la propia carga. |
Tras la asignacion, la variable {{_DW_ESTADO_BPM}} se actualiza inmediatamente, por lo que los pasos siguientes del pipeline ya ven el nuevo estado.
estado con estado_valor = Aprobado. Esto actualiza la carga y mueve la tarjeta en el tablero.
Transiciones entre pasos
Las transiciones permiten controlar el flujo de ejecucion del pipeline, creando un arbol de decision en lugar de una secuencia lineal. Cada paso puede tener multiples transiciones con condiciones diferentes.
Tipos de transicion
| Tipo | Condicion | Descripcion |
|---|---|---|
siempre | Ninguna | Se ejecuta siempre, sin condicion. Equivale a un salto incondicional. |
hay_filas | Resultado SQL | Se activa si el paso actual devolvio filas en su resultado (aplica a validaciones, variables SQL, etc.). |
sin_filas | Resultado SQL | Se activa si el paso actual NO devolvio filas. |
valor_igual | Variable | Se activa si la variable especificada (variable_name) tiene un valor igual a valor_esperado. |
valor_diferente | Variable | Se activa si la variable tiene un valor distinto de valor_esperado. |
valor_mayor | Variable | Se activa si la variable es numericamente mayor que valor_esperado. |
valor_menor | Variable | Se activa si la variable es numericamente menor que valor_esperado. |
valor_mayor_igual | Variable | Se activa si la variable es mayor o igual que valor_esperado. |
valor_menor_igual | Variable | Se activa si la variable es menor o igual que valor_esperado. |
resto | Fallback | Se activa solo si ninguna otra transicion del mismo paso se ha cumplido. Actua como un "else" o "default". |
Propiedades de una transicion
- paso_origen_id
- El paso desde el que parte la transicion (se establece automaticamente al crear la transicion desde un paso).
- paso_destino_id
- El paso al que salta si la condicion se cumple. Si es
NULL, indica fin del pipeline — la ejecucion termina aqui. - tipo
- Tipo de condicion (ver tabla arriba).
- variable_name
- Solo para tipos
valor_*. Nombre de la variable cuyo valor se evalua (ej:total_filas,ESTADO). - valor_esperado
- Solo para tipos
valor_*. Valor contra el que se compara la variable. - orden
- Orden de evaluacion. Las transiciones se evaluan en orden ascendente y se usa la primera que se cumple.
Reglas de evaluacion
- Tras ejecutar un paso, se buscan sus transiciones ordenadas por
orden. - Se evalua cada condicion en secuencia.
- La primera transicion cuya condicion se cumpla determina el siguiente paso.
- Si ninguna condicion se cumple y existe una transicion de tipo
resto, se usa esa. - Si no hay transiciones definidas (o ninguna se cumple y no hay
resto), se continua con el siguiente paso pororden.
Ejemplo de arbol de decision
Paso 1: variable (SQL) → captura {{total_filas}}
├── valor_mayor total_filas > 1000 → Paso 4 (alerta volumen alto)
├── valor_igual total_filas = 0 → NULL (fin: sin datos)
└── resto → Paso 2 (flujo normal)
Paso 2: validacion_stop → verifica duplicados
├── hay_filas → NULL (fin: rollback automatico)
└── sin_filas → Paso 3
Paso 3: sql → calcula totales
└── siempre → Paso 5
Paso 4: validacion_alarma → avisa volumen alto
└── siempre → Paso 2
Paso 5: mailing → envia resumen
(sin transiciones → fin del pipeline)
Configuracion en la UI
Editor de pasos
Los pasos se gestionan desde el tab Estructura del pipeline (o bloque legacy). Cada paso se muestra como una card con su tipo, nombre, y un indicador de estado (activo/inactivo).
Crear un paso
Usa el boton "Anadir paso" debajo de la lista de pasos. Se abre un formulario con los campos que corresponden al tipo de paso seleccionado. Los campos visibles cambian segun el tipo elegido.
Desactivar un paso
Un paso se puede desactivar sin eliminarlo (campo activo). Un paso inactivo se salta durante la ejecucion pero se conserva en la configuracion para poder reactivarlo despues.
Editor de transiciones
Cada paso tiene un boton para gestionar sus transiciones. Al hacer click, se muestra el editor de transiciones donde se pueden anadir, modificar y eliminar transiciones. Se indica el paso destino (o "FIN" para terminar el pipeline), el tipo de condicion y los valores de comparacion.
Reordenar pasos
El campo orden determina la secuencia base. Los pasos se pueden reordenar arrastrando. El orden es importante cuando no hay transiciones: el sistema sigue al siguiente paso por orden numerico.
BPM / Kanban
El sistema BPM (Business Process Management) de {M}aker permite gestionar flujos de trabajo sobre cargas de datos mediante un tablero Kanban visual. Cada bloque DW puede tener su propio tablero con estados configurables, transiciones controladas y acciones invocables sobre cargas existentes.
Vision general
El sistema BPM se compone de cuatro elementos principales:
- Estados
- Etapas por las que pasa una carga (ej: "Pendiente", "En revision", "Aprobado", "Rechazado"). Se configuran por bloque.
- Tablero Kanban
- Vista visual con columnas = estados y tarjetas (cards) = cargas. Las tarjetas se arrastran entre columnas.
- Transiciones
- Reglas que definen que movimientos estan permitidos entre estados, y que pipeline (si alguno) se ejecuta al mover.
- Acciones
- Pipelines invocables manualmente sobre cargas existentes. Permiten ejecutar logica (mailing, triggers, cambios de estado) sin crear nuevos datos.
Estados Kanban
Los estados definen las etapas del proceso. Se configuran en la pestana Kanban del bloque, boton "Configurar".
Propiedades de un estado
| Propiedad | Descripcion |
|---|---|
| Nombre | Texto libre que identifica el estado. Aparece como titulo de la columna en el tablero. Ejemplo: "Pendiente", "En curso", "Finalizado". |
| Color | Color hexadecimal para la columna del tablero (ej: #3b82f6 para azul). Cada estado tiene su propio color para diferenciacion visual rapida. |
| Es inicial | Si esta marcado, las nuevas cargas confirmadas en este bloque reciben automaticamente este estado. Solo un estado debe ser inicial. Si no hay estado inicial, las nuevas cargas no entran al Kanban. |
| Es final | Marca el estado como estado terminal del proceso. Informativo: no bloquea movimientos pero indica visualmente que la carga ha completado su ciclo. |
| Orden | Posicion de la columna en el tablero, de izquierda a derecha. Los estados se ordenan de menor a mayor. |
es_inicial = 1, el sistema asigna automaticamente ese estado a la nueva carga (funcion setInitialEstadoBpm). Esto garantiza que cada nueva carga entra al tablero en la columna correcta sin intervencion manual.
Renombrar estados
Al renombrar un estado existente, el sistema reasigna automaticamente todas las cargas que tenian el nombre antiguo al nuevo nombre. Esto se gestiona mediante el array renombramientos que se envia al guardar: cada entrada indica {de: "nombre_viejo", a: "nombre_nuevo"}.
estado_bpm que no corresponde a ningun estado configurado. No apareceran en el tablero Kanban. Usa las reasignaciones para mover cargas a otro estado antes de eliminar.
Reasignaciones
Al guardar la configuracion de estados, puedes incluir reasignaciones para mover cargas de un estado a otro. Cada reasignacion indica {de: "estado_origen", a: "estado_destino"}. Esto es util cuando eliminas un estado y quieres redistribuir sus cargas.
Tablero Kanban
El tablero se muestra en la pestana Kanban del bloque. Presenta una vista de columnas donde:
- Cada columna representa un estado configurado, con su color y nombre como encabezado.
- Cada tarjeta (card) representa una carga con ese
estado_bpm. - Las tarjetas son arrastrables (drag & drop) entre columnas.
- El encabezado de cada columna muestra el numero de tarjetas que contiene.
Configuracion de tarjetas (Bricks)
Las tarjetas del Kanban muestran informacion configurable mediante bricks. Los bricks se configuran en el boton "Configurar" del Kanban, pestana "Tarjetas".
Cada brick referencia una variable capturada durante la ejecucion del pipeline (almacenada en dw_pipeline_variables) o un valor de campo de carga. Los bricks tienen tres roles posibles:
| Rol | Descripcion | Cantidad |
|---|---|---|
| Cabecera | Titulo principal de la tarjeta. Se muestra en negrita en la parte superior. Tipicamente el nombre del fichero, un identificador o un campo significativo. | Una variable |
| Detalle | Subtitulo de la tarjeta. Se muestra debajo de la cabecera en texto mas pequeno. Puede ser una fecha, un usuario responsable, etc. | Una o mas variables |
| Brick | Chips informativos en el cuerpo de la tarjeta. Cada uno muestra una etiqueta y el valor de la variable, con color configurable. Ideal para mostrar metricas, importes, categorias. | Multiples |
total_filas, importe_total o cliente, estas aparecen disponibles para configurar bricks. Los valores de campos de carga tambien estan disponibles.
Ejemplo de configuracion de tarjeta
Cabecera: cliente --> "Acme Corp"
Detalle: fecha_pedido --> "2026-03-15"
Brick: importe_total --> [Importe: 12.500,00]
Brick: num_lineas --> [Lineas: 48]
Brick: prioridad --> [Prioridad: Alta]
Transiciones
Las transiciones definen que movimientos estan permitidos entre estados en el tablero Kanban. Se configuran en el boton "Configurar" del Kanban, pestana "Transiciones".
Propiedades de una transicion
| Propiedad | Descripcion |
|---|---|
| Estado origen | Estado desde el cual se permite mover la tarjeta. |
| Estado destino | Estado al cual se permite mover la tarjeta. |
| Pipeline (opcional) | Pipeline que se ejecuta automaticamente al realizar la transicion. Si no se configura pipeline, el cambio de estado es directo. |
Transiciones con pipeline
Cuando una transicion tiene un pipeline asociado:
- El usuario arrastra la tarjeta a la columna destino.
- El sistema verifica que la transicion existe.
- Se ejecuta el pipeline asociado (que tipicamente incluye un paso tipo
estadopara cambiar elestado_bpm). - Si el pipeline falla o un
validacion_stopdispara, la tarjeta no se mueve y permanece en su columna original. - Si el pipeline se completa correctamente, la tarjeta refleja el nuevo estado.
estado que asigne el estado destino. Tambien puede incluir validaciones (verificar condiciones antes de permitir el cambio), mailings (notificar al responsable), triggers (ejecutar logica adicional) o cualquier combinacion de pasos.
Acciones sobre cargas
Las acciones permiten ejecutar pipelines sobre cargas existentes sin necesidad de subir un nuevo fichero. Se configuran en la pestana Acciones del bloque.
Propiedades de una accion
| Propiedad | Descripcion |
|---|---|
| Nombre | Texto descriptivo de la accion (ej: "Aprobar pedido", "Enviar notificacion", "Rechazar con motivo"). |
| Icono | Emoji o caracter que identifica visualmente la accion en los botones (ej: ▶). |
| Pipeline | Pipeline que se ejecuta al invocar la accion. Tipicamente un pipeline sin tabla (solo ejecuta pasos). |
| Estado origen | Si se configura, la accion solo es visible cuando la carga esta en este estado. Si es NULL, la accion esta disponible en cualquier estado. |
Ejecucion de acciones
Las acciones aparecen como botones en el detalle de la carga (en la pestana Cargas del bloque) y en el historial del portal. Al hacer click:
- Se abre un modal con los campos de carga del pipeline de la accion (si los tiene). Esto permite al usuario introducir datos adicionales (ej: motivo de rechazo, comentario, fecha).
- Al confirmar, se ejecuta el pipeline sobre la carga existente (
executePipelineAction). - El pipeline tiene acceso a las variables de la carga original:
{{_DW_CARGA_ID}},{{_DW_TABLA}},{{_DW_BLOQUE_ID}}. - La variable
{{_DW_PARENT_CARGA_ID}}esta disponible para referenciar la carga padre. - Los resultados (logs, tablas, errores) se muestran tras la ejecucion.
estado_origen = "Pendiente", solo aparecera en cargas cuyo estado_bpm sea "Pendiente". Cuando la carga pase a otro estado, el boton desaparece. Usa estado_origen = NULL para acciones que deben estar siempre disponibles.
Pipelines sin tabla
Los pipelines con nombre_tabla vacio (nullable) son pipelines que solo ejecutan pasos sin insertar datos en una tabla dinamica. Son ideales para acciones BPM:
- Cambio de estado: un paso tipo
estadoque actualiza elestado_bpm. - Notificaciones: un paso tipo
mailingque envia un email. - Logica encadenada: un paso tipo
triggerque invoca otro pipeline. - Validaciones: un paso tipo
validacion_stopque verifica condiciones antes de permitir una transicion.
Para crear un pipeline sin tabla, activa el toggle "Sin fichero" en el paso 1 del wizard de pipeline. El pipeline no creara tabla destino en la base de datos DW.
Paso tipo "estado"
El paso tipo estado es un tipo de paso del pipeline disenado especificamente para el BPM. Permite cambiar el estado_bpm de una carga.
Propiedades
- estado_valor
- Valor del estado a asignar. Puede ser un texto fijo (ej:
Aprobado) o una expresion con variables (ej:{{nuevo_estado}}) para valor dinamico basado en logica previa del pipeline.
Comportamiento
- Si la carga tiene
parent_carga_id(es resultado de una accion), el estado se asigna en la carga padre. - Si la carga no tiene padre, el estado se asigna en la propia carga.
- Tras la asignacion, la variable
{{_DW_ESTADO_BPM}}se actualiza inmediatamente y esta disponible para pasos siguientes del pipeline.
validacion_stop que verifica que el importe no exceda un limite, 2) paso estado con estado_valor = "Aprobado", 3) paso mailing que notifica al solicitante. Si la validacion falla, el estado no cambia y no se envia el mail.
Relacion padre-hijo entre cargas
Cuando una accion se ejecuta sobre una carga, se crea una carga hija vinculada via parent_carga_id. Esto permite:
- Rastrear que acciones se han ejecutado sobre una carga original.
- Que el paso tipo
estadoescriba el nuevo estado en la carga padre (la original), no en la carga hija (la accion). - Ver el historial completo de acciones ejecutadas sobre una carga desde el endpoint
carga_hijas.
Configuracion paso a paso
1. Crear estados
- Selecciona el bloque en el sidebar.
- Ve a la pestana Kanban.
- Haz click en "Configurar".
- En la pestana "Estados", anade los estados con nombre, color y orden.
- Marca uno como inicial para que las nuevas cargas entren automaticamente al Kanban.
- Guarda la configuracion.
2. Configurar tarjetas
- En la misma ventana de configuracion, ve a la pestana "Tarjetas".
- Selecciona una variable como cabecera (titulo de la tarjeta).
- Opcionalmente, selecciona variables como detalle (subtitulo).
- Anade bricks con las variables que quieras mostrar como chips, con etiqueta y color.
- Guarda la configuracion.
3. Definir transiciones
- En la pestana "Transiciones", define cada movimiento permitido.
- Para cada transicion, indica estado origen, estado destino y (opcionalmente) pipeline a ejecutar.
- Guarda la configuracion.
4. Crear acciones (opcional)
- Ve a la pestana Acciones del bloque.
- Haz click en "Nueva accion".
- Configura nombre, icono, pipeline (tipicamente sin tabla) y estado origen (si quieres filtrar por estado).
- Guarda la accion.
estado si quieres que cambien el estado_bpm automaticamente.
Ejecucion programada
{M}aker permite automatizar la ejecucion de pipelines mediante dos mecanismos: schedules (ejecuciones programadas con cron) y radares (vigilancia de carpetas FTP/SFTP). Ambos se configuran por bloque y se ejecutan automaticamente a traves del script scheduler.php.
scheduler.php debe estar configurado como cron del sistema operativo ejecutandose cada minuto: * * * * * php /ruta/a/mmaker/scheduler.php
Schedules (ejecucion programada)
Un schedule ejecuta un pipeline automaticamente con una frecuencia definida por una expresion cron, sin necesidad de subir un fichero. Es ideal para procesos recurrentes que no dependen de datos nuevos de un fichero (consolidaciones, calculos periodicos, envio de informes).
Configuracion
Los schedules se gestionan en la pestana "Programados" del bloque. Cada schedule tiene las siguientes propiedades:
| Propiedad | Descripcion |
|---|---|
| Nombre | Identificador unico del schedule dentro de la empresa. Aparece en el log y en las cards de la UI. |
| Descripcion | Texto libre opcional para documentar el proposito del schedule. |
| Expresion cron | Expresion cron estandar de 5 campos: minuto hora dia_mes mes dia_semana. Define la frecuencia de ejecucion. Consulta la seccion "Expresiones cron" mas abajo. |
| Campos valores | Valores por defecto para los campos de carga del pipeline (excluye tipo file). Estos valores se usan automaticamente en cada ejecucion sin intervencion del usuario. |
| Activo | Toggle on/off. Si esta desactivado, el schedule no se ejecuta aunque su hora llegue. |
Expresiones cron
La expresion cron usa el formato estandar de 5 campos:
* * * * *
| | | | |
| | | | +-- dia de la semana (0-7, 0 y 7 = domingo)
| | | +------- mes (1-12)
| | +------------ dia del mes (1-31)
| +----------------- hora (0-23)
+---------------------- minuto (0-59)
La interfaz ofrece presets para las expresiones mas comunes:
| Preset | Expresion | Significado |
|---|---|---|
| Cada hora | 0 * * * * | Al minuto 0 de cada hora |
| Diario 8h | 0 8 * * * | Cada dia a las 8:00 |
| Lunes 8h | 0 8 * * 1 | Cada lunes a las 8:00 |
| L-V 8h | 0 8 * * 1-5 | Lunes a viernes a las 8:00 |
| Dia 1 mes | 0 8 1 * * | El primer dia de cada mes a las 8:00 |
| Cada 5 min | */5 * * * * | Cada 5 minutos |
Funcionamiento interno
- El script
scheduler.phpse ejecuta cada minuto. - Selecciona todos los schedules activos cuya
proxima_ejecuciones menor o igual a la hora actual. - Para cada schedule, ejecuta
executeNoFilePipeline(), que crea una carga connombre_fichero = '[programado] nombre_schedule'y ejecuta el pipeline asociado al bloque. - Tras la ejecucion, recalcula
proxima_ejecucionautomaticamente usando el parser cron. - Registra el resultado en
dw_scheduler_logcon estado, duracion y carga generada.
Cards de la UI
Cada schedule se muestra como una card con:
- Nombre del schedule.
- Cron legible: la expresion cron traducida a texto (ej: "Lunes a viernes a las 8:00").
- Badge de estado:
ok(verde),error(rojo) oprocesando(amarillo) de la ultima ejecucion. - Proxima ejecucion: fecha y hora calculada de la proxima ejecucion.
- Botones: Ejecutar (ejecucion manual), Editar, Activar/Desactivar, Eliminar.
Radares (vigilancia de carpetas)
Un radar vigila una carpeta FTP o SFTP para detectar ficheros nuevos y procesarlos automaticamente. Es ideal para integraciones con sistemas que depositan ficheros en un servidor (ERP, bancos, proveedores).
Configuracion
Los radares se gestionan en la pestana "Radares" del bloque. Cada radar tiene las siguientes propiedades:
| Propiedad | Descripcion |
|---|---|
| Nombre | Identificador unico del radar dentro de la empresa. |
| Descripcion | Texto libre opcional. |
| Tipo de origen | ftp — referencia a una configuracion FTP/SFTP existente (ver seccion "Configuracion FTP/SFTP"). |
| Configuracion FTP | Selector del destino FTP/SFTP previamente configurado (solo visible cuando tipo = ftp). |
| Ruta remota | Directorio dentro del servidor FTP/SFTP donde buscar ficheros. Por defecto /. |
| Patron de fichero | Patron glob para filtrar ficheros. Ejemplos: *.xlsx (todos los Excel), ventas_*.csv (CSVs que empiezan por "ventas_"), * (todos). Por defecto *. |
| Intervalo (min) | Frecuencia de revision en minutos. Minimo 1 minuto. El radar solo escanea si han pasado al menos estos minutos desde la ultima revision. |
| Campos valores | Valores por defecto para campos de carga, igual que en schedules. |
| Mover procesados | Si esta activado, tras procesar un fichero exitosamente se mueve a una subcarpeta procesados/ (o la ruta indicada en ruta_procesados) dentro del servidor FTP/SFTP. Si no, el fichero permanece en su ubicacion (y podria reprocesarse en el siguiente ciclo). |
| Ruta procesados | Ruta personalizada donde mover ficheros procesados. Si no se indica, se usa procesados/ relativa a la ruta del radar. |
| Activo | Toggle on/off. |
Funcionamiento interno
- El script
scheduler.phprevisa los radares activos cuyaultima_revision+intervalo_minha expirado. - Escanea la carpeta remota con
scanFtpFiles(), filtrando porpatron_fichero. - Para cada fichero encontrado:
- Descarga el fichero temporalmente (
downloadFtpFile()). - Ejecuta el flujo completo de carga: parseo, singularity delete, insert, pipeline.
- Si
mover_procesadosesta activo y la carga fue exitosa, mueve el fichero a la subcarpeta.
- Descarga el fichero temporalmente (
- Registra cada fichero procesado en
dw_scheduler_log.
Cards de la UI
Cada radar se muestra como una card con:
- Badge FTP indicando el tipo de conexion.
- Patron: patron de fichero configurado.
- Intervalo: frecuencia de revision.
- Badge de estado:
ok,errorosin_ficherosde la ultima revision. - Botones: Probar (escanear sin procesar), Editar, Activar/Desactivar, Eliminar.
Configuracion FTP/SFTP
Los destinos FTP/SFTP se configuran a nivel de empresa y pueden usarse tanto por radares como por pasos flyout de pipelines. Se gestionan desde el panel de pipeline, seccion FTP/SFTP.
Propiedades de una configuracion FTP
| Propiedad | Descripcion |
|---|---|
| Nombre | Identificador unico dentro de la empresa. Aparece en los selectores de radar y flyout. |
| Protocolo | ftp (FTP estandar) o sftp (SSH File Transfer Protocol, mas seguro). |
| Host | Direccion del servidor (IP o dominio). Ejemplo: ftp.empresa.com. |
| Puerto | Puerto de conexion. Por defecto: 21 para FTP, 22 para SFTP. |
| Usuario | Nombre de usuario para autenticacion. |
| Password | Contrasena. Solo se actualiza si se envia un valor nuevo (no se muestra la actual por seguridad). |
| Ruta destino | Directorio base en el servidor. Por defecto /. |
| Modo pasivo | Solo para FTP: activa el modo pasivo (PASV). Recomendado cuando hay firewalls de por medio. Activado por defecto. |
ssh2 este habilitada en PHP. Si no esta disponible, el sistema mostrara un error claro indicando que la extension es necesaria. FTP estandar no requiere extensiones adicionales.
Configuracion SMTP (mailing)
Para que los pasos tipo mailing del pipeline puedan enviar emails, es necesario configurar el servidor SMTP de la empresa. Se configura en el panel de administracion, seccion "Mail".
Propiedades de la configuracion SMTP
| Propiedad | Descripcion |
|---|---|
| SMTP Host | Servidor SMTP. Ejemplo: smtp.gmail.com, smtp.office365.com. |
| SMTP Puerto | Puerto del servidor. Valores tipicos: 587 (TLS), 465 (SSL), 25 (sin cifrado). |
| Usuario SMTP | Email o usuario para autenticacion SMTP. |
| Password SMTP | Contrasena de la cuenta SMTP. Solo se actualiza si se envia valor nuevo. |
| Email remitente | Direccion "From" en los emails enviados. |
| Nombre remitente | Nombre que aparece junto al email del remitente (opcional). |
| Cifrado | tls (recomendado), ssl o none (sin cifrado, no recomendado). |
Log del scheduler
Todas las ejecuciones (schedules y radares) se registran en dw_scheduler_log con:
- Tipo:
scheduleoradar. - Fichero: nombre del fichero procesado (solo radares).
- Estado:
ok,errorosin_ficheros. - Mensaje: detalle del resultado o del error.
- Duracion: tiempo de ejecucion en segundos.
- Carga: referencia a la carga generada (si la hubo).
El log es consultable desde la UI en el detalle de cada schedule o radar, mostrando las ultimas 20 ejecuciones.
Portal de usuario
El portal es una interfaz simplificada disenada para usuarios finales (rol usuario). Permite subir ficheros, consultar el estado de cargas y revisar el historial, sin acceso a la configuracion tecnica de {M}aker.
usuario son redirigidos automaticamente al portal cuando acceden a la URL principal de {M}aker (index.php). No tienen acceso a la interfaz de configuracion (queries, reports, packs, pipelines).
Acceso y permisos
Los usuarios del portal solo ven los recursos (apps y bloques) para los que tienen permiso explicito. El administrador configura estos permisos desde la interfaz principal de {M}aker.
Ejes de acceso
Existen dos formas de otorgar acceso a un usuario:
- Permiso por App
- El usuario recibe acceso a una app completa (
tipo_recurso = dw_app). Esto le da acceso a todos los bloques dentro de esa app. Si se anaden nuevos bloques a la app, el usuario los ve automaticamente. Ideal para usuarios que necesitan acceso amplio a un area funcional. - Permiso por Bloque
- El usuario recibe acceso a un bloque especifico (
tipo_recurso = dw_bloque). Solo puede ver y subir datos a ese bloque concreto. Ideal para usuarios con responsabilidad sobre un tipo de dato especifico.
Configurar permisos (desde la interfaz principal)
Los permisos se gestionan desde la seccion de Administracion de {M}aker (accesible solo para roles admin y superadmin):
- Ve a la seccion de administracion de usuarios.
- Selecciona el usuario al que quieres dar acceso.
- En la seccion de permisos, anade los recursos:
- dw_app: acceso a una app y todos sus bloques.
- dw_bloque: acceso a un bloque especifico.
- report: acceso a un report (para otros contextos fuera del portal).
- pack: acceso a un pack (para otros contextos fuera del portal).
- Guarda los permisos.
El endpoint admin_guardar_permisos reemplaza todos los permisos del usuario de una vez (no es acumulativo: envia la lista completa deseada).
Interfaz del portal
El portal tiene una interfaz limpia y moderna con las siguientes secciones:
Barra de busqueda
En la parte superior, un buscador permite filtrar las apps y bloques visibles por nombre. Filtra en tiempo real mientras el usuario escribe.
Vista de apps y bloques
La pantalla principal muestra las apps accesibles, cada una como una tarjeta expandible que contiene sus bloques. Cada bloque tiene un boton "Subir" que inicia el flujo de carga.
Si el usuario tiene acceso directo a bloques que no pertenecen a ninguna app (o cuya app no esta en sus permisos), estos se muestran en una seccion aparte.
Actividad reciente
Feed de las cargas mas recientes del usuario en todos los bloques accesibles. Muestra:
- Nombre del fichero subido.
- Bloque destino.
- Estado de la carga (
ok,error,procesando). - Fecha y hora.
- Numero de filas procesadas.
Historial por bloque
Vista detallada de todas las cargas de un bloque, accesible desde el boton de historial de cada bloque. Muestra:
- Lista de cargas con estado, fichero, fecha, filas ok/error.
- Detalle de cada carga: log de ejecucion, errores por fila, tablas de resultado.
- Boton "Acciones" (si el bloque tiene acciones BPM configuradas) — ver seccion siguiente.
Flujo de subida
El flujo de subida en el portal es identico al de la interfaz principal de {M}aker, incluyendo el sistema de grupos de campos.
Flujo con grupos de campos
Si el pipeline del bloque tiene grupos de campos de carga configurados, el modal de subida se presenta como un wizard multi-paso:
- Grupo 1: Se muestran los campos del primer grupo visible. El usuario rellena los valores y hace click en "Continuar".
- Evaluacion de condicion: Al avanzar, el sistema evalua la condicion del siguiente grupo:
siempre: el grupo se muestra siempre.valor_igual/valor_diferente: el grupo se muestra solo si un campo previo tiene (o no tiene) un valor especifico.sql: el servidor evalua una consulta SQL para decidir si mostrar el grupo.
- Grupo N: Se repite el proceso para cada grupo visible.
- Resumen: Antes de seleccionar el fichero, se muestra un resumen de todos los valores rellenados. El usuario puede volver atras para corregir.
- Fichero: El usuario selecciona el fichero y hace click en "Continuar" para ver el preview.
- Preview: Se muestran las primeras filas parseadas segun la configuracion del pipeline.
- Confirmar: El usuario confirma la carga. Se ejecuta singularity delete, insert y pipeline.
Flujo sin grupos (legacy)
Si no hay grupos configurados, todos los campos de carga y el selector de fichero se muestran en un solo paso, seguido del preview y la confirmacion.
select cuyas opciones se definen con una consulta SQL (SQL:SELECT...) se recargan dinamicamente al navegar entre grupos. Si la consulta SQL contiene {{campo}}, el valor del campo referenciado se sustituye automaticamente, permitiendo selects dependientes (ej: un campo "Categoria" que filtra las opciones de un campo "Subcategoria").
Subida sin fichero
Si el pipeline esta configurado como "Sin fichero" (pipeline sin tabla), el flujo omite la seleccion de fichero y el preview. El usuario solo rellena los campos de carga y confirma. Esto es util para acciones como registrar datos manuales o ejecutar procesos que no requieren fichero de entrada.
Acciones BPM en el portal
Si un bloque tiene acciones configuradas (pestana Acciones en la interfaz principal), los usuarios del portal pueden ejecutarlas desde la vista de historial.
Como funcionan
- En el historial de cargas de un bloque, cada entrada con acciones disponibles muestra un boton "Acciones" en la esquina superior derecha.
- Al hacer click, se despliega la lista de acciones disponibles, filtradas por el
estado_bpmactual de la carga. - El usuario selecciona una accion.
- Si el pipeline de la accion tiene campos de carga, se abre un modal para rellenarlos.
- Al confirmar, se ejecuta el pipeline sobre la carga existente.
- El resultado (exito, error, tablas de resultado) se muestra al usuario.
estado_origen configurado solo aparecen cuando la carga esta en ese estado. Si la carga no tiene estado_bpm (no hay Kanban configurado), solo se muestran las acciones sin estado_origen (las que tienen NULL). Si el bloque no tiene ninguna accion configurada, el boton "Acciones" no aparece.
Diferencias entre portal e interfaz principal
| Caracteristica | Interfaz principal ({M}aker) | Portal |
|---|---|---|
| Acceso | Roles superadmin, admin, desarrollador |
Rol usuario |
| Configuracion | Completa: queries, reports, packs, pipelines, bloques, apps, Kanban, acciones | Ninguna: solo operacion (subir, ver estado) |
| Subida de datos | Mismo flujo con wizard completo | Mismo flujo con wizard completo |
| Kanban | Tablero completo con drag & drop, configuracion de estados y transiciones | No disponible (solo acciones desde historial) |
| Acciones BPM | Desde detalle de carga y tablero Kanban | Desde historial de cargas |
| Datos de tabla | Tab "Datos" con tabla paginada y consola SQL | No disponible |
| Administracion | Gestion de usuarios, empresas, permisos | No disponible |
Sesion independiente
El portal tiene su propio sistema de autenticacion (portal/auth.php), independiente de la sesion principal de {M}aker. Esto significa:
- El login del portal es una pantalla separada con su propio formulario.
- Las sesiones del portal y de la interfaz principal son independientes.
- El rate limiting (5 intentos por IP en 15 minutos) se aplica igualmente en el portal.
- Las cookies de sesion son
HttpOnlyySameSite=Strictpara seguridad.
Guia rapida para administradores
Para habilitar el portal para un usuario final:
- Crear el usuario con rol
usuarioen la seccion de Administracion. - Asignar permisos al usuario:
- Permiso
dw_apppara acceso a una app completa, o - Permiso
dw_bloquepara acceso a bloques individuales.
- Permiso
- Comunicar la URL del portal al usuario (
/mmaker/portal/). - El usuario inicia sesion con sus credenciales y ve solo los recursos asignados.
usuario para el cliente. El cliente accede al portal, sube sus datos y puede ejecutar acciones (como "Aprobar" o "Rechazar") desde el historial. El equipo tecnico de la consultora monitoriza el proceso desde la interfaz principal con el tablero Kanban.
Formularios publicos
Los formularios publicos permiten exponer los campos de carga de un bloque como un formulario web accesible sin login, similar a Google Forms o Typeform. Cualquier persona con el enlace puede rellenar el formulario y enviar datos que se procesan a traves del pipeline del bloque.
Activar un formulario publico
- Navega al bloque en la seccion DW del sidebar.
- Abre la pestana Vista del panel del bloque.
- Activa el toggle "Formulario publico".
- El sistema genera automaticamente una URL unica con un token del tipo
frm_xxxxxxxxxxxxxxxx. - Copia la URL con el boton de copiar o usa "Abrir" para previsualizar el formulario.
Opciones de configuracion
Al activar el formulario publico, aparecen dos opciones configurables:
- Max envios/hora por usuario
- Limita el numero de envios por hora desde un mismo navegador. La identificacion se basa en un fingerprint anonimo (hash de IP + User-Agent). Valor por defecto: 10 envios/hora. Util para prevenir abuso o envios accidentales duplicados.
- Limite fichero (MB)
- Tamano maximo permitido para ficheros adjuntos subidos desde el formulario. Valor por defecto: 5 MB. Se aplica por fichero individual, no al total del envio. Los ficheros que superen este limite se rechazan con un mensaje de error claro.
Experiencia del usuario externo
Cuando un usuario accede a la URL del formulario publico, ve una interfaz limpia y responsive con tema claro, disenada para ser intuitiva:
Formulario sin grupos (clasico)
Si el pipeline no tiene grupos de campos configurados, todos los campos se muestran en una sola pantalla. El usuario rellena los campos, adjunta ficheros si los hay, y pulsa Enviar.
Formulario con grupos (wizard multi-paso)
Si el pipeline tiene grupos de campos, el formulario se presenta como un wizard paso a paso:
- Paso 1: Se muestran los campos del primer grupo visible (segun condiciones).
- El usuario rellena y pulsa Continuar.
- Pasos intermedios: Se evalua la condicion del siguiente grupo. Si es visible, se muestra; si no, se salta al siguiente.
- Resumen: Pantalla final con todos los valores introducidos. El usuario revisa y confirma.
- Envio: Se ejecuta el pipeline (mismo flujo que
executeNoFilePipeline).
Elementos visuales del wizard:
- Dots de progreso: indicadores visuales del paso actual sobre el total.
- Barra de progreso: barra horizontal que avanza con cada paso.
- Botones Atras/Continuar: navegacion fluida entre pasos.
Resultado tras el envio
Tras enviar el formulario, el usuario ve:
- Tablas de resultado si el pipeline genera pasos de tipo
tabla. - Warnings si el pipeline tiene validaciones de tipo
validacion_alarma. - Mensaje de exito generico si el pipeline no genera tablas ni warnings.
- Un boton "Enviar otro" para volver al formulario limpio y hacer otro envio.
validacion_stop que se dispara, se hace rollback completo y el usuario ve un mensaje de error explicativo. Asegurate de que los mensajes de validacion (mensaje_usuario) estan bien redactados para un publico externo.
Tipos de campo soportados
| Tipo | Renderizado | Notas |
|---|---|---|
input |
Campo de texto libre | Texto simple, una linea |
number |
Campo numerico | Validacion de formato numerico en cliente |
select |
Desplegable | Opciones CSV (Ene,Feb,Mar) o consulta SQL (SQL:SELECT...) |
date |
Selector de fecha | Formato nativo del navegador |
file |
Selector de fichero | Validacion de tamano y extension |
Selects con opciones SQL
Los campos de tipo select con opciones SQL (SQL:SELECT...) se resuelven de dos formas:
- Sin variables
{{campo}} - Las opciones se pre-resuelven en servidor al cargar el formulario. El desplegable se renderiza directamente con todas las opciones.
- Con variables
{{campo}}(dependientes) - Las opciones se cargan dinamicamente via AJAX cuando el usuario cambia el valor del campo del que dependen. El desplegable se actualiza en tiempo real. Esto permite cascadas de selects (ej: seleccionar pais → se cargan las ciudades de ese pais).
Usuario anonimo
Las cargas generadas por formularios publicos se atribuyen a un usuario de sistema anonimo@sistema creado automaticamente por empresa. Este usuario:
- No puede iniciar sesion en {M}aker ni en el portal.
- Existe unicamente como referencia para las cargas anonimas.
- Se crea una vez por empresa la primera vez que se recibe un envio.
- Las cargas de este usuario aparecen en el historial del bloque como cualquier otra carga, identificadas por el nombre
anonimo@sistema.
Seguridad
Los formularios publicos implementan varias capas de proteccion:
| Medida | Detalle |
|---|---|
| Rate limiting | Limite configurable de envios/hora por fingerprint (IP + User-Agent). Superar el limite devuelve un error claro. |
| Limite de fichero | Tamano maximo configurable por fichero adjunto. Se valida tanto en cliente como en servidor. |
| Whitelist de extensiones | Solo se aceptan extensiones de fichero seguras. Extensiones ejecutables (.exe, .bat, .php, etc.) se rechazan. |
| Sin sesion / sin CSRF | El formulario publico no requiere sesion de usuario ni token CSRF. La autenticacion se basa unicamente en el token frm_xxx de la URL. |
| Token unico | Cada formulario tiene un token aleatorio unico. Desactivar el toggle invalida el token. |
Flujo tecnico completo
- El usuario accede a la URL con token
frm_xxx. - El servidor valida el token y carga la configuracion del bloque y su pipeline efectivo.
- Se renderizan los campos de carga (con grupos si estan configurados).
- El usuario rellena campos y adjunta ficheros.
- Se valida rate limiting (fingerprint vs limite configurado).
- Se validan ficheros (tamano, extension).
- Se ejecuta
executeNoFilePipelinecon los valores del formulario, atribuido aanonimo@sistema. - El pipeline procesa los datos: fijas con
campo_carga_refse rellenan, se insertan filas, se ejecutan pasos. - Se devuelve el resultado (tablas, warnings o mensaje de exito).
Administracion
El panel de administracion permite gestionar empresas, proyectos y usuarios del sistema. Requiere rol admin o superadmin para acceder.
admin o superadmin.
Jerarquia de empresas (modelo consultora)
{M}aker organiza las empresas en una jerarquia de dos niveles que refleja el modelo tipico de una consultora con proyectos:
- Empresa madre (top-level)
- La entidad principal con
parent_id = NULL. Representa la consultora u organizacion principal. Los recursos creados aqui se consideran recursos generales y son accesibles desde todos los proyectos hijos. - Proyecto (empresa hija)
- Una empresa con
parent_idapuntando a la empresa madre. Representa un cliente o proyecto especifico. Los recursos creados aqui estan aislados: solo son visibles desde ese proyecto.
Ejemplo de estructura:
Empresa "Consultora ABC" (parent_id=NULL)
|-- Admin: ana@consultora.com
|-- Proyecto "Cliente Acme" (parent_id=1)
| |-- Desarrollador: dev@consultora.com
| +-- Usuario: contacto@acme.com (solo portal)
+-- Proyecto "Cliente Beta" (parent_id=1)
+-- Desarrollador: otro-dev@consultora.com
Color de proyecto
Cada proyecto tiene un color asignado automaticamente de una paleta de 10 colores. Este color se usa en toda la interfaz para identificar visualmente a que proyecto pertenece cada recurso:
- Dots de color en el sidebar junto a recursos de un proyecto especifico.
- Badge "G" gris para recursos generales (de la empresa madre) cuando se esta viendo un proyecto concreto.
Selector de proyecto
El dropdown en el topbar permite filtrar toda la interfaz por proyecto. Es el mecanismo principal de scoping transversal:
| Seleccion | Que se ve | Donde se crean recursos nuevos |
|---|---|---|
| "Todos" | Recursos de todas las empresas accesibles | En la empresa madre (generales) |
| Proyecto concreto | Recursos del proyecto + recursos generales de la madre | En ese proyecto |
Badges visuales en el sidebar
- Vista "Todos"
- Los recursos generales (empresa madre) no llevan badge. Los recursos de proyectos llevan un dot coloreado con el color del proyecto y un tooltip con su nombre.
- Vista de proyecto concreto
- Los recursos del proyecto seleccionado no llevan badge. Los recursos generales llevan un badge gris "G" para distinguirlos.
Gestion de usuarios
Roles del sistema
| Rol | Acceso principal | Acceso admin | Alcance |
|---|---|---|---|
superadmin |
Todo el sistema | Empresas, todos los usuarios, todo | Global |
admin |
Su empresa + proyectos hijos | Crear proyectos, gestionar usuarios en su ambito | Empresa + hijos |
desarrollador |
UI completa ({M}aker) | Ninguno | Empresa asignada |
usuario |
Solo portal | Ninguno | Recursos con permiso |
usuario son redirigidos automaticamente al portal al iniciar sesion en index.php. No pueden acceder a la UI de configuracion de {M}aker.
Crear un usuario
- Accede a la seccion Admin desde el topbar.
- En la pestana Usuarios, pulsa "Nuevo usuario".
- Rellena los campos:
- Email: debe ser unico en todo el sistema.
- Nombre: nombre visible en la interfaz.
- Password: contrasena inicial.
- Rol: selecciona el rol apropiado.
- Empresa: empresa/proyecto al que pertenece el usuario.
- Pulsa Crear.
Gestionar usuarios existentes
- Editar
- Modifica nombre, email o rol del usuario. El cambio de rol es inmediato.
- Toggle activo/inactivo
- Desactivar un usuario mata todas sus sesiones activas inmediatamente. El usuario no podra iniciar sesion hasta que se reactive.
- Reset password
- Establece una nueva contrasena e invalida todas las sesiones activas. El usuario debera iniciar sesion de nuevo con la nueva contrasena.
Gestion de permisos
Los permisos controlan que recursos puede ver un usuario con rol usuario en el portal. Los roles desarrollador, admin y superadmin tienen acceso completo a los recursos de su ambito sin necesidad de permisos explícitos.
Tipos de recurso con permisos
| Tipo | Efecto del permiso |
|---|---|
report |
El usuario puede ver el report en el portal |
pack |
El usuario puede ver el pack en el portal |
dw_bloque |
El usuario puede subir ficheros y ver historial del bloque en el portal |
dw_app |
El usuario puede acceder a la app y todos sus bloques en el portal (herencia) |
Doble eje de acceso (apps/bloques)
El acceso a bloques desde el portal funciona con un doble eje:
- Eje app: Si se da permiso a una app, el usuario hereda acceso a todos los bloques de esa app.
- Eje bloque: Se puede dar permiso a un bloque individual sin dar acceso a toda la app.
Asignar permisos
- En la seccion Admin, selecciona un usuario.
- En su detalle, ve a Permisos.
- Selecciona los recursos (apps, bloques, reports, packs) que quieres asignar.
- Guarda. Los cambios son inmediatos.
API keys
Cada usuario puede tener una API key unica para autenticacion desde integraciones externas:
- Formato
sk-mmaker-xxxxxxxxxxxxxxxx- Uso
- Se envia como header
Authorization: Bearer sk-mmaker-xxxen las peticiones HTTP. - Integraciones compatibles
-
- MCP Server: el servidor MCP de {M}aker usa la API key para autenticarse contra
api.php. - Excel Add-in: el complemento de Excel usa la API key para subir datos y consultar tablas.
- MCP Server: el servidor MCP de {M}aker usa la API key para autenticarse contra
- Seguridad
- Las peticiones con Bearer auth saltan la validacion CSRF (no hay sesion ni cookies). La API key identifica al usuario y su empresa, aplicando las mismas reglas de acceso que una sesion normal.
Gestion de empresas
Crear una empresa/proyecto
- En la seccion Admin, pestana Empresas.
- Pulsa "Nueva empresa".
- Introduce el nombre. El slug se genera automaticamente si se deja vacio (formato URL-safe: minusculas, sin espacios ni acentos).
- Si se crea desde un admin (no superadmin), la empresa se crea como proyecto hijo bajo la empresa del admin.
Desactivar una empresa
El toggle activo/inactivo desactiva la empresa. Los usuarios de esa empresa no podran iniciar sesion. Los recursos de la empresa siguen existiendo pero no son accesibles.
Rate limiting (login)
El sistema protege contra ataques de fuerza bruta en el login:
- 5 intentos fallidos por IP en 15 minutos = bloqueo temporal.
- Mensaje generico: "Demasiados intentos. Espera unos minutos."
- Tras un login exitoso, se limpian los intentos de esa IP.
- Los registros antiguos (>1 hora) se limpian probabilisticamente (1% de las peticiones).
- Aplica tanto al login principal como al login del portal.
Integracion con Power BI
{M}aker se conecta con Power BI de dos formas: mediante una lanzadera HTTP (recomendado) que no requiere driver MySQL, o mediante una conexion MySQL directa (legacy). Ademas, el sistema DW ofrece una API de datos para acceder a tablas dinamicas y consultas nombradas directamente desde Power Query.
Metodo 1: Lanzadera HTTP (recomendado)
La lanzadera HTTP es una funcion Power Query M llamada mmaker() que descarga el codigo de cada query desde el servidor via Web.Contents y lo ejecuta con Expression.Evaluate.
Como funciona
- Power BI invoca
mmaker("nombre_query", true, true). - La funcion lanzadora hace una llamada HTTP al endpoint
codigo_m_reportcon el token del report y el nombre de la query. - El servidor resuelve la version, sustituye los
{{PARAM}}con los valores configurados y devuelve el codigo M como texto plano. - Power BI ejecuta el codigo con
Expression.Evaluate(Respuesta, #shared).
Configuracion paso a paso
- En {M}aker, selecciona el report en el sidebar.
- Abre la pestana "Lanzadora".
- Copia el bloque de codigo M que aparece (la funcion
mmakercompleta). - En Power BI Desktop, crea una consulta en blanco (Inicio > Obtener datos > Consulta en blanco).
- Abre el Editor avanzado y pega el codigo de la lanzadera.
- Nombra esta consulta como
mmaker. - Para consumir una query, crea otra consulta en blanco con:
mmaker("nombre_query", true, true).
mmaker aparece en Power BI como una funcion invocable con dropdowns para los parametros Version y Evaluar, gracias a los metadatos Documentation.AllowedValues.
Parametros de la lanzadera
| Parametro | Tipo | Valores | Descripcion |
|---|---|---|---|
NombreQuery |
text | Nombre de la query | Nombre exacto de la query en {M}aker |
Version |
logical | true / false |
true = version activa (publicada); false = borrador (desarrollo) |
Evaluar |
logical | true / false |
true = ejecuta el codigo M; false = muestra el codigo como texto (debug) |
Config |
nullable record | Record opcional (ver abajo) | Opcional. Record que agrupa inyeccion de stagings (fields Source, SourceA, SourceB...) y sampling de paso (field Paso). |
mmaker("query", true, false) devuelve el codigo M como texto sin ejecutarlo. Util para diagnosticar errores: puedes ver exactamente que codigo se esta generando, con los parametros ya sustituidos.
El record Config
El cuarto parametro acepta un record que combina dos cosas: las stagings que se inyectan al entorno de evaluacion y el Paso para sampling. Todos los fields son opcionales.
// Ejemplos validos:
mmaker("calendario", true, true) // sin config
mmaker("ventas", true, true, [Source = VentasRaw]) // con staging
mmaker("reporte", true, true, [SourceA = Ventas, SourceB = Clientes]) // multi-staging
mmaker("ventas", true, true, [Paso = "Tipo cambiado"]) // sampling
mmaker("ventas", true, true, [Source = VentasRaw, Paso = "Types"]) // combinado
Cualquier field que empiece por Source se inyecta al entorno de Expression.Evaluate con ese nombre (el codigo M de la transform lo referencia como si fuera variable local). El field Paso activa el modo sampling.
Exportar sample de un paso (Emulador)
Pasando el field Paso en el Config se extraen datos de un paso intermedio de la query para alimentar el emulador de {M}aker:
mmaker("Ventas_Raw", true, true, [Paso = "Cabeceras"])
Esto devuelve una tabla con las primeras 50 filas del paso "Cabeceras". Internamente, el servidor genera codigo M que ejecuta la query hasta ese paso y serializa el resultado como JSON, que la lanzadera parsea de vuelta a tabla.
Para usar el resultado en el emulador:
- En Power BI, invoca la funcion con el cuarto parametro.
- Copia el JSON resultante (o exporta la tabla).
- En {M}aker, en la vista de Pasos de la query, haz click en "Pegar JSON".
- Pega el JSON y selecciona el paso de inicio del emulador.
Multi-token (RLS de parametros)
Un report puede tener multiples tokens, cada uno con sus propios valores de parametros. Esto permite escenarios de Row-Level Security por parametros:
- Cada token accede a las mismas queries pero con valores de
{{PARAM}}diferentes. - Ejemplo: Token "Espana" con
{{PAIS}}= "ES", Token "Francia" con{{PAIS}}= "FR". - Cada usuario de Power BI recibe una lanzadera con su token especifico.
- Los tokens se gestionan desde la pestana "Accesos" del report.
Tipos de query y refresh en PBI Service
{M}aker clasifica las queries en tres tipos segun su contenido, y eso determina como se consumen desde Power BI:
| Tipo | Badge | Contenido | Como se usa | Refresh Service |
|---|---|---|---|---|
transform |
T | Solo transformaciones M puras (Table.*, List.*, Text.*, etc.) sin connectors |
Se invoca via mmaker("nombre", true, true) |
Si |
staging |
S | Contiene connectors (Excel.Workbook, SharePoint.Files, Sql.Database, Web.Contents...) |
Se pega LITERAL como consulta separada en el .pbix. Su output se inyecta al Config del mmaker de una transform | Si (la staging es codigo M nativo en el .pbix) |
completa |
C | Query entera con connectors, quick & dirty | Se invoca via mmaker("nombre", true, true) pero el .pbix debe tener pegada la variante Desktop de mmaker (mismo nombre, cuerpo con #shared) |
No (PBI Service marca "dynamic data source") |
Por que los connectors no pueden ir dentro de mmaker
La lanzadera mmaker pasa un record curado _env (con ~430 funciones puras de transformacion) al Expression.Evaluate, en lugar de #shared. Esto es lo que permite el refresh en PBI Service: sin connectors en el entorno, el analyzer del servicio lo trata como origen estatico.
Si metieras Excel.Workbook(...) dentro de una query transform, al refrescar daria el error "the name 'Excel.Workbook' cannot be found", porque no esta en el _env. Por eso las queries con connectors viven en tipo=staging y el connector se ejecuta fuera del Expression.Evaluate (nativamente en el .pbix).
Division automatica: de query original a staging + transform
Cuando pegas una query con connectors en {M}aker (via "Pegar codigo M" o via el asistente IA), el sistema detecta los connectors y propone dividirla automaticamente:
- Pegas codigo completo, incluyendo SharePoint.Files + Excel.Workbook + transformaciones posteriores.
- {M}aker detecta connectors y muestra un dialogo de preview: "Se crearia staging X con N pasos + transform con M pasos".
- Confirmas: {M}aker extrae los pasos con connectors (y su navegacion pura como
Libro{[Item="Hoja",Kind="Sheet"]}[Data]) a una nueva querytipo=stagingllamada por defecto{nombreQuery}Conn. La query original se queda con los pasos puros post-frontera y sus referencias se reescriben al aliasSource. - En la tab Accesos del report ves ahora dos bloques: el codigo M del staging (para pegar en el .pbix) y la invocacion
mmaker("nombre", true, true, [Source = nombreConn]).
ventas_por_mes y ventas_top10 ambos consumen ventasConn). En la tab Accesos aparece cada staging una sola vez aunque lo usen N transforms — pegas el codigo del staging en el .pbix y ya.
Flujo en Power BI paso a paso
Supongamos una query ventas_2026 que originalmente tenia SharePoint + Excel + transformaciones, dividida automaticamente por {M}aker en:
ventas_2026Conn(tipo staging, con SharePoint.Files + Excel.Workbook)ventas_2026(tipo transform, con Table.PromoteHeaders + Table.TransformColumnTypes, empieza conSource)
En Power BI Desktop pegas tres consultas:
// 1. La lanzadera (copiar desde tab "Accesos" del report, variante SERVICE)
mmaker = let Token = "mk_...", RootUrl = "...", ApiPath = "..." in ...
// 2. El staging (copiar desde tab "Accesos" > "Stagings requeridas")
ventas_2026Conn = let
Fuente = SharePoint.Files("https://tenant.sharepoint.com/sites/X", [ApiVersion = 15]),
Fichero = Fuente{[Name="ventas.xlsx"]}[Content],
Libro = Excel.Workbook(Fichero, null, true),
Hoja = Libro{[Item="Ventas",Kind="Sheet"]}[Data]
in Hoja
// 3. La consulta final (la que usaras en el modelo)
ventas_2026 = mmaker("ventas_2026", true, true, [Source = ventas_2026Conn])
Cambios server-side en ventas_2026 (anadir columnas calculadas, nuevos types, filtros) se recogen en el siguiente refresh sin tocar el .pbix. Solo necesitas regenerar el staging si cambia la URL del SharePoint o el nombre del fichero.
Variante Desktop de mmaker (cuerpo con #shared)
La tab Accesos ofrece tambien una variante Desktop de la lanzadera: mismo nombre de funcion (mmaker), solo cambia el cuerpo — usa #shared como environment en vez del _env curado. Soporta cualquier query con connectors directamente, pero el dataset bloquea scheduled refresh en Service. Util para:
- Desarrollo rapido (no dividir queries cada vez)
- Reports que solo se usan en Desktop
- Queries marcadas como
tipo=completa(quick & dirty)
Al tener ambas variantes el mismo nombre, las invocaciones mmaker("X", true, true) funcionan con cualquier variante pegada — el .pbix elige cual sirve. Cambiar de Desktop a Service es tan sencillo como re-pegar el cuerpo en la misma consulta mmaker.
// La invocacion es la misma, independientemente de la variante pegada:
mmaker("mi_query_con_excel", true, true)
Patron alternativo: Desktop + OneDrive (no oficial)
Cuando un cliente tiene un unico entorno con varios .pbix vinculados a {M}aker y no quiere pelearse con la disciplina staging/transform ni pagar Power BI Premium, existe una alternativa conocida que apalanca el auto-refresh de OneDrive del Service:
- Una maquina always-on (mini-PC, VM, o equipo de oficina) con Power BI Desktop instalado y credenciales a los origenes configuradas.
- Task Scheduler + PowerShell abre el
.pbix, fuerza refresh, guarda y cierra — con la frecuencia que necesites. - El
.pbixvive en una carpeta sincronizada con OneDrive / SharePoint. - Power BI Service detecta el cambio (polling ~1 h) e importa el snapshot: modelo, queries Y datos ya refrescados.
En este escenario puedes usar la variante Desktop de mmaker (con #shared) para todas tus queries, sin necesidad de dividir en staging/transform. Los connectors (Excel, SharePoint, SQL, Web.Contents...) funcionan directamente porque el refresh lo hace Desktop en local, no Service.
.pbix ni redistribuir nada. Versionado, borrador/activa, params por token y emulador siguen funcionando como siempre.
Script PowerShell de refresh
Power BI Desktop no expone una CLI oficial para refresh, pero se puede automatizar via SendKeys desde PowerShell:
param(
[Parameter(Mandatory=$true)][string]$PbixPath,
[int]$WaitLoadSec = 60, # tiempo para que abra el .pbix
[int]$WaitRefreshSec = 600 # timeout del refresh (ajustar al tamano)
)
Add-Type -AssemblyName System.Windows.Forms
$pbi = "C:\Program Files\Microsoft Power BI Desktop\bin\PBIDesktop.exe"
# 1. Abrir el .pbix
$proc = Start-Process -FilePath $pbi -ArgumentList "`"$PbixPath`"" -PassThru
Start-Sleep -Seconds $WaitLoadSec
# 2. Enfocar la ventana
$title = [IO.Path]::GetFileNameWithoutExtension($PbixPath)
$shell = New-Object -ComObject WScript.Shell
$shell.AppActivate("$title - Power BI Desktop") | Out-Null
Start-Sleep -Seconds 2
# 3. Refresh (Ctrl+Shift+F5 = Refresh All)
[System.Windows.Forms.SendKeys]::SendWait("^+{F5}")
Start-Sleep -Seconds $WaitRefreshSec
# 4. Guardar
$shell.AppActivate("$title - Power BI Desktop") | Out-Null
[System.Windows.Forms.SendKeys]::SendWait("^s")
Start-Sleep -Seconds 15
# 5. Cerrar
[System.Windows.Forms.SendKeys]::SendWait("%{F4}")
Start-Sleep -Seconds 5
if (!$proc.HasExited) { $proc | Stop-Process -Force }
Guardar como refresh-pbix.ps1 y programar en Task Scheduler con:
powershell.exe -File "C:\scripts\refresh-pbix.ps1" -PbixPath "C:\OneDrive\reports\ventas.pbix"
Cuando encaja este patron
- Un solo cliente / tenant con hasta ~20 reports.
- Ya tiene OneDrive / SharePoint como repositorio de ficheros.
- Tolera latencia acumulada (cadencia Desktop + sync OneDrive + caching Service).
- No necesita DirectQuery ni near-real-time.
- Quiere la maxima comodidad de desarrollo: connectors donde sea, sin staging.
Limitaciones y avisos
- Fragilidad:
SendKeysdepende de la ventana activa y de tiempos heuristicos. Si el refresh tarda mas del timeout, guardas a medias. Para produccion seria, considerar Power Automate Desktop (reconoce iconos/ventanas de forma mas robusta y detecta mejor el fin del refresh). - Escala: todo pasa por una maquina. Docenas de reports grandes saturan el scheduler — se serializa todo.
- Maquina always-on: equivalente operacional a un gateway on-prem (Windows, credenciales locales, mantenimiento), aunque arquitectonicamente son cosas distintas.
- Service no orquesta: no hay logs centralizados de refresh, ni alertas nativas si uno falla — hay que montarlas fuera.
- No multi-tenant: cada tenant necesita su propia maquina con su propio Desktop y sus propias credenciales.
Metodo 2: MySQL directo (legacy)
Este metodo conecta Power BI directamente a la base de datos MySQL para leer las queries y pasos.
Configuracion:
- Instala el MySQL ODBC Connector (version 8.x o superior).
- En {M}aker, accede al panel "Integrar en Power BI".
- Copia el bloque de codigo M de la lanzadera MySQL.
- En Power BI, pega como consulta en blanco.
- La lanzadera lee directamente de las tablas
queriesyquery_pasosvia ODBC.
DW Data API
La API de datos DW permite acceder a las tablas dinamicas del Data Warehouse desde Power BI sin necesidad de driver ODBC ni exponer MySQL.
Autenticacion
Todos los endpoints de la DW Data API usan el token del report para autenticacion (el mismo token de la lanzadera). El token resuelve la empresa del usuario y da acceso a todas las tablas DW de esa empresa.
Endpoints disponibles
| Endpoint | Descripcion | Uso |
|---|---|---|
dw_tables |
Lista tablas DW de la empresa | Metadata: nombre, numero de filas, columnas con tipos |
dw_data |
Datos paginados de una tabla | Rows como arrays, column metadata, flag has_more para paginacion |
dw_code |
Codigo M auto-generado | Codigo M con List.Generate para paginacion transparente |
Usar tablas DW desde Power BI
- En {M}aker, abre la pestana "Lanzadora" del report (o del token si usas multi-token).
- En la seccion "Tablas DW (API)", veras la lista de tablas disponibles.
- Haz click en "Copiar M" junto a la tabla que quieras.
- En Power BI, pega como consulta en blanco. El codigo ya incluye:
- Paginacion transparente via
List.Generate(maneja automaticamente tablas grandes). Table.TransformColumnTypescon los tipos correctos de cada columna.- Autenticacion con el token del report.
- Paginacion transparente via
List.Generate en el codigo M maneja esto transparentemente: sigue pidiendo paginas hasta que has_more = false.
Consultas DW nombradas
Las consultas DW nombradas son queries SQL guardadas en el servidor, ejecutables via API con token. Permiten crear consultas SQL complejas que se ejecutan en el servidor y se consumen desde Power BI como una tabla mas.
Caracteristicas
- La SQL se ejecuta en el servidor y no es visible en Power BI. El usuario de PBI solo ve codigo M limpio con
Web.Contents. - Solo se permiten consultas
SELECT(validacion server-side). - Soportan paginacion transparente igual que las tablas DW.
- Se pueden crear desde el asistente de chat o desde el editor de queries en la UI.
Endpoints
| Endpoint | Descripcion |
|---|---|
dw_sql |
Ejecuta la consulta nombrada y devuelve datos paginados |
dw_consulta_code |
Codigo M auto-generado para la consulta (con paginacion) |
Crear una consulta DW
Hay tres formas de crear consultas DW:
- Desde el asistente de chat
- Pide al asistente que cree una consulta. El usa el tool
crear_consulta_dwautomaticamente y genera la query M correspondiente. - Desde el editor de queries
- En el dropdown "Anadir paso" de una query, selecciona "DW (conexion datos)". Rellena el nombre de la consulta y la SQL. El sistema crea la consulta DW y los pasos M necesarios.
- Desde la seccion DW Consultas
- Gestion directa: crear, editar, eliminar consultas SQL nombradas.
Consulta DW vinculada en el editor de pasos
Cuando editas un paso de query que referencia una consulta DW (el codigo M contiene action="dw_sql"...consulta="nombre"), el modal de edicion muestra automaticamente:
- El nombre de la consulta detectada.
- Un textarea con la SQL editable (con intellisense).
- Al guardar el paso, la SQL de la consulta DW se guarda simultaneamente.
Web.Contents a la API.
BI Credentials (credenciales ODBC)
Para conexiones ODBC directas a la base de datos DW (escenarios legacy o avanzados), {M}aker crea usuarios MySQL de solo lectura por empresa.
- Formato del usuario
mmaker_bi_{empresa_id}(ej:mmaker_bi_1)- Permisos
- Solo
SELECTsobre la base de datosmmaker_dw. Se otorga automaticamente unGRANT SELECTcada vez que se crea o modifica una tabla DW. - Gestion
-
- Crear: Endpoint
crear_bi_credentials. Genera usuario + password aleatorio. - Regenerar: Endpoint
regenerar_bi_credentials. Cambia la password del usuario existente. - Consultar: Endpoint
bi_credentials. Devuelve usuario y host (password solo al crear/regenerar).
- Crear: Endpoint
dw_{empresa_id}_* de su empresa en la base de datos mmaker_dw. No tiene acceso a la base de datos del sistema (mmaker).
Referencia rapida: que metodo elegir
| Escenario | Metodo recomendado |
|---|---|
| Queries M centralizadas sin driver | Lanzadera HTTP |
| Datos DW sin exponer MySQL | DW Data API (dw_data / dw_sql) |
| SQL compleja oculta al usuario PBI | Consultas DW nombradas (dw_sql) |
| Conexion directa MySQL (legacy) | BI Credentials + ODBC |
| Cliente unico, pocos reports, sin gateway (no oficial) | Variante Desktop + refresh programado local + OneDrive |
| Power BI Service (cloud) | Lanzadera HTTP + DW Data API (unicos metodos sin gateway) |
Asistente de chat
El asistente de chat es un panel lateral con inteligencia artificial integrada en {M}aker. Esta conectado a la API de Claude (Anthropic) con capacidad de tool_use, lo que le permite ejecutar acciones directamente sobre el sistema: crear queries, modificar pasos, configurar Kanban, ejecutar acciones BPM y mas.
Contexto automatico
El asistente recibe automaticamente el contexto de tu sesion actual:
- Query seleccionada
- Si tienes una query activa en el panel, el asistente conoce su nombre, pasos y codigo. Puede modificarla directamente.
- Report activo
- Si tienes un report seleccionado, el asistente conoce su ID, token y URL de la API. Usa esta informacion para generar codigo M con los tokens correctos.
- Bloque/Pipeline activo
- Si estas en un bloque DW, el asistente conoce su configuracion, tablas y pipeline asociado.
Capacidades del asistente
Gestion de queries
El asistente puede realizar todas estas operaciones directamente:
- Crear queries: Genera queries completas con multiples pasos. Si el nombre ya existe, actualiza los pasos como nueva version (upsert).
- Modificar pasos: Edita el codigo M de pasos individuales.
- Anadir pasos: Agrega nuevos pasos a una query existente (via borrador).
- Eliminar pasos: Elimina pasos de la query activa.
- Asignar a report: Asigna una query a un report. La asignacion es idempotente (si ya esta asignada, no falla).
query_id=0 en asignar_query_report. El sistema sustituye automaticamente el ID de la query recien creada.
Consultas DW nombradas
El asistente sigue un flujo especifico para crear conexiones de datos DW:
- Crear consulta SQL: Usa el tool
crear_consulta_dwpara guardar la SQL en el servidor. La consulta usa upsert: si el nombre existe, actualiza la SQL. - Crear query M: Genera los pasos Power Query M que llaman a
dw_sqlviaWeb.Contentscon paginacion transparente. - Asignar al report: Vincula la query al report activo.
Web.Contents + API dw_sql para datos DW. Nunca genera codigo con Odbc.Query ni MySQL.Database(). La SQL queda oculta en el servidor y el usuario de Power BI solo ve codigo M limpio.
BPM / Kanban
El asistente puede configurar y operar el sistema BPM completo:
| Capacidad | Tool | Descripcion |
|---|---|---|
| Configurar estados Kanban | configurar_kanban |
Define estados del tablero: nombre, color, inicial, final, orden |
| Configurar transiciones | configurar_kanban_transiciones |
Define movimientos permitidos entre estados con pipeline opcional |
| Crear acciones | crear_accion_carga |
Define pipelines invocables sobre cargas de un bloque |
| Ejecutar acciones | ejecutar_accion |
Ejecuta un pipeline sobre una carga existente |
| Mover cargas | mover_carga_kanban |
Mueve una carga entre estados del Kanban |
| Configurar tarjetas | configurar_kanban_tarjeta |
Define que variables mostrar en las cards del Kanban |
Buenas practicas
Contexto optimo
Para obtener los mejores resultados del asistente:
- Selecciona el report antes de pedir que cree una query DW. El asistente usara el token del report para generar el codigo M.
- Se especifico con los nombres de tablas y columnas. El asistente conoce las tablas DW disponibles pero agradece nombres exactos.
- Pide operaciones completas: en lugar de "crea una consulta SQL", di "crea una query Power Query que muestre las ventas por mes del ultimo ano, usando la tabla dw_ventas". El asistente creara la consulta SQL, la query M y la asignara al report en una sola interaccion.
Operaciones encadenadas
El asistente puede ejecutar multiples tools en una sola respuesta. Ejemplo tipico:
- Crea una consulta DW con la SQL.
- Crea una query M con 3 pasos (Datos, Tabla, Resultado).
- Asigna la query al report activo.
Todo esto ocurre en una sola interaccion del chat. Si un paso falla, el asistente informa del error y sugiere correcciones.
Modificaciones en cadena
Cuando el asistente cambia un paso de origen o conexion de una query, revisa automaticamente todos los pasos siguientes que puedan verse afectados y emite todas las modificaciones necesarias en una sola respuesta.
Estructura de la conversacion
- La conversacion persiste durante toda la sesion del navegador.
- El asistente recuerda el contexto de mensajes anteriores.
- Al cambiar de query o report, el contexto se actualiza automaticamente.
- Cada tool call se muestra en el chat como una accion ejecutada, con su resultado.
Limitaciones
- El asistente no puede subir ficheros ni ejecutar cargas DW directamente.
- No tiene acceso a los datos de las tablas DW (solo a la estructura/metadata).
- Las operaciones de eliminacion piden confirmacion antes de ejecutarse.
- El historial de chat no persiste entre sesiones del navegador.
chat.php como proxy, que anade el contexto del sistema y las definiciones de tools antes de enviar a la API.
Distribución RLS — Power BI filtrado por usuario sin publicar
El modo RLS (Row-Level Security) de {M}aker permite distribuir un mismo informe Power BI a varios usuarios y que cada uno vea datos filtrados segun su rol, sin necesidad de publicar en Power BI Service ni configurar gateway, RLS dinamico o licencias Pro/Premium.
mk_u_...) que resuelve en el servidor a un conjunto de parametros. La lanzadera M usa ese token y recibe datos ya filtrados. Todo ocurre en Power BI Desktop via Web.Contents.
Como funciona
- El admin crea tokens-rol en el report (ej: "Norte", "Sur") con valores distintos de
{{REGION}}. - Activa el toggle RLS en el tab Accesos → se auto-genera la App "Mis Reports", el Pipeline "Report PBI" y un bloque vinculado al report.
- Asigna cada usuario a un token-rol → se genera un
user_tokenpersonal (mk_u_...). - El admin sube un
.pbital bloque (via portal) con la lanzadera M preparada y un parametroMakerToken. - Cada usuario entra al portal, copia su token personal, descarga el
.pbity lo abre en Power BI Desktop. - Power BI pide el valor del parametro
MakerTokenal abrir — el usuario pega su token. - Guarda como
.pbix. En cada refresh, el servidor devuelve datos filtrados por el token.
Configuracion paso a paso (admin)
1. Crear tokens-rol
En el tab Accesos del report, crea un token por cada combinacion de parametros. Ejemplo para un report con {{REGION}}:
- Token "Equipo Norte" →
REGION = "Norte" - Token "Equipo Sur" →
REGION = "Sur" - Token "Direccion" →
REGION = "%"(ve todo)
2. Activar RLS
En el tab Accesos, activa el toggle "Distribucion RLS". El sistema:
- Crea la App "Mis Reports" (1 por empresa) si no existe
- Crea el Pipeline "Report PBI" compartido (sin tabla, con campos: comentario + fichero .pbit/.pbix)
- Crea un bloque vinculado al report con
report_idapuntando al informe
3. Asignar usuarios
En la seccion de cada token-rol, pulsa "+ Asignar" y selecciona el usuario. Se genera su user_token personal automaticamente.
4. Preparar la lanzadera con parametro
Con RLS activo, el tab Lanzadora muestra instrucciones sobre el parametro MakerToken y genera el codigo M usando Token = MakerToken en vez de un token hardcoded:
let
Token = MakerToken, // Parametro de Power BI
BaseUrl = "https://tu-servidor/mmaker/api.php",
...
5. Crear el parametro MakerToken en Power BI Desktop (solo el admin, una vez)
Esta configuracion la hace el admin una sola vez al preparar el fichero. Los usuarios finales NO necesitan crear el parametro — lo reciben ya definido dentro del .pbit.
- Abre Power BI Desktop con el informe en blanco o existente
- Inicio → Administrar parametros → Nuevo
- Nombre:
MakerToken - Tipo: Texto
- Valor actual: cualquier token valido (ej: el tuyo propio como admin) — solo se usa para que PBI pueda ejecutar el informe durante el diseno
- En el Editor Avanzado de la consulta
mmaker, pega la lanzadera M (que referenciaToken = MakerToken) - Disena el informe con tus visuales
- Archivo → Guardar como → tipo Power BI Template (.pbit)
.pbit, Power BI guarda la definicion del parametro pero no su valor. Cuando un usuario abre el .pbit, PBI Desktop le pide automaticamente el valor del parametro en un dialogo modal. El usuario solo tiene que pegar su token personal ahi — no configura nada mas.
6. Subir el .pbit al bloque
En el portal, abre el bloque del report (en la App "Mis Reports"), pulsa Subir version y adjunta el .pbit. Opcionalmente anade un comentario de version.
Para el usuario final
El usuario entra al portal y ve el bloque con badge "Report". Al abrirlo:
- Version actual: card destacada con el ultimo .pbit y boton de descarga
- Tu acceso: su token personal con boton Copiar
- Conectar Power BI: instrucciones numeradas del flujo
- Historial de versiones: versiones anteriores descargables
Flujo del usuario (4 pasos)
- Copia tu token personal del portal (boton Copiar)
- Descarga el
.pbitde la version actual - Abre el fichero — Power BI Desktop lanza un dialogo pidiendo el valor del parametro
MakerToken. Pega tu token y pulsa Cargar. - Guarda como .pbix con Archivo → Guardar como. Tu token queda almacenado en el fichero. En los siguientes refreshes no te lo vuelve a pedir.
.pbit, pega el token en el prompt automatico y guarda. El parametro ya esta definido dentro del template gracias al trabajo del admin en el paso 5.
Seguridad y validacion
- El
user_tokenes opaco (mk_u_<40 hex>) — no expone la estructura interna - Cada peticion a
codigo_m_reportcon user_token valida en tiempo real: usuario activo, token-rol activo, report activo - Revocar un usuario (boton x en la tabla) tiene efecto inmediato en el siguiente refresh
- Cada llamada se registra en
report_usage_logcon usuario, query, IP y timestamp
Estadisticas de uso
En el tab Accesos, la tabla de usuarios asignados muestra:
- Ultimo uso: fecha de la ultima peticion del usuario
- 30d: numero de refreshes en los ultimos 30 dias
Ventajas frente a RLS de Power BI Service
| Aspecto | RLS tradicional (PBI Service) | RLS {M}aker |
|---|---|---|
| Licencia | Pro o Premium | Solo Power BI Desktop gratis |
| Gateway | Requerido para BD on-premise | No requerido (HTTP) |
| Cambios de logica | Republicar .pbix | Cambio en {M}aker → siguiente refresh |
| Parametros por usuario | Roles DAX + asignaciones | Tokens-rol en {M}aker |
| Revocacion | Quitar acceso al workspace | Revocar token-usuario (inmediato) |
| Auditoria de uso | Activity log PBI | report_usage_log en {M}aker |
RLS en Excel (informes Power Query en libros Excel)
Si en vez de Power BI distribuyes informes como .xlsx/.xltx con consultas Power Query, tambien puedes usar RLS. Excel no tiene el prompt automatico que tiene .pbit, pero existe una convencion simple: una celda con nombre definido MakerToken.
Preparacion del libro (admin / disenador)
- En una hoja visible del libro, selecciona una celda (ej:
Config!B2) - En el cuadro de nombres (arriba izquierda) escribe
MakerTokeny pulsa Enter - En el editor de Power Query, define el
Tokenleyendo de esa celda:Token = Excel.CurrentWorkbook(){[Name="MakerToken"]}[Content]{0}[Column1] - Junto a la celda, pon un texto tipo "Pega aqui tu token personal de {M}aker" para guiar al usuario
- Guarda como
.xltx(Plantilla Excel) con la celda vacia — al abrir la plantilla, Excel crea un.xlsxnuevo para cada usuario
Uso para el usuario
Hay dos formas de rellenar la celda:
Opcion A — Manual
- El usuario copia su token del portal
- Abre la plantilla, pega el token en la celda
MakerToken - Refresca los datos (Datos → Actualizar todo)
- Guarda como
.xlsx
Opcion B — Con el Excel Add-in de {M}aker
El add-in de {M}aker para Excel incluye un tab "RLS" que muestra todos los tokens personales del usuario:
- Abre el add-in desde Excel (barra superior → complemento {M}aker)
- Ve a la pestana RLS
- Pulsa "Pegar en MakerToken" en el token del report que vas a usar
- El add-in escribe el token directamente en la celda — un click
MakerToken.
Diferencias vs Power BI
| Power BI (.pbit) | Excel | |
|---|---|---|
| Prompt al abrir | Si, automatico | No — celda manual |
| Token guardado al cerrar | Dentro del .pbix | Dentro del .xlsx (hoja) |
| Visibilidad | Oculto en parametros | Visible en la celda (se puede ocultar la hoja) |
| Setup cliente | Pegar en dialogo | Pegar en celda (o add-in) |
Licencias y Límites
Todos los límites de tu cuenta (cuántos reports, queries, cargas/mes, tokens de IA, GB de storage, etc.) se resuelven en tiempo real desde una capa central configurable. Esta sección explica el modelo, cómo ver tu uso y qué ocurre cuando llegas a un límite.
Conceptos
Productos y tiers
{M}aker se compone de tres productos que se combinan:
- CODE (siempre base): Solo · Studio · Agency. Gobierna queries M, reports, packs, tokens RLS.
- DATA (add-on): Light · Pro · Scale. Añade tablas DW, pipelines, cargas, mailings, BPM.
- FORMS (add-on de DATA): Forms Plus · Forms Pro. Formularios públicos de alto volumen.
Límites (tier_limits)
Cada tier define un conjunto de límites por métrica (ej. reports: 25, storage_gb: 25). El valor -1 significa ilimitado.
Precios (tier_prices)
Cada tier tiene precios mensual y anual, en modalidad public o early_access. El anual equivale a pagar 10 meses (≈17% descuento).
Overrides por suscripción
Una suscripción puede tener excepciones individuales: límites o precios distintos del tier base, con motivo y vigencia opcional. Se usan para acuerdos custom, pruebas con clientes específicos o reducción de caps para early testers.
Cascada de resolución
Al preguntar "¿cuál es el límite de queries para esta empresa?":
- Busca override activo en
subscription_overrides→ gana si existe. - Si no hay override → usa el valor de
tier_limitspara el tier actual. - Si la empresa no tiene suscripción de ese producto → límite = 0 (bloqueo).
Panel de Billing (tab Admin)
Admin → Billing muestra:
- Canjear código: caja para pegar un bono de acceso anticipado.
- Mis suscripciones: productos, tier, ciclo, estado y vencimiento.
- Chat IA: cuota mensual de tokens, barra de progreso, configuración BYOK.
- Excepciones activas: overrides aplicados a tu cuenta (solo aparece si existen).
- Uso actual: tabla con cada métrica (uso / límite / barra).
Avisos 80% y 95%
Cuando una métrica llega al 80% o 95% de su límite, aparece un banner fijo bajo el topbar con:
- Icono de aviso (⚠ para 80%, ⛔ para 95%).
- Nombre de la métrica + uso actual / límite + porcentaje.
- Botón Ver billing que lleva directo al tab.
- Botón de cerrar (la alerta no reaparece en la sesión hasta subir a danger).
El banner se refresca automáticamente cada 5 minutos.
Comportamiento al llegar al 100%
| Métrica | Comportamiento |
|---|---|
reports, queries, packs, apps, blocks, pipelines, named_queries, projects, devs, portal_users, schedules, ftp_destinations, rls_tokens | Bloqueo de creación. HTTP 402 con mensaje "Límite del plan superado". |
monthly_loads | Bloqueo de nuevas cargas (fichero, schedule, radar, action). Se pueden consultar datos existentes. |
mailings_month | El paso mailing del pipeline salta con warning pero el pipeline continúa. |
ai_tokens_month | Chat deshabilitado hasta el 1 del mes siguiente o hasta configurar BYOK. |
storage_gb (Light/Pro) | Bloqueo de escritura en mmaker_dw. Lectura sigue funcionando. |
storage_gb (Scale) | Overage automático (0,50 €/GB/mes), cap hard en +50% del tier. |
Chat IA: cortesía vs BYOK
Cuota de cortesía
Cada tier CODE incluye tokens/mes de cortesía:
- Solo: 200 000 tokens
- Studio: 500 000 tokens
- Agency: 1 000 000 tokens
El contador se resetea el 1 de cada mes natural. No se acumula entre meses.
BYOK (Bring Your Own Key)
En lugar de cortesía, puedes configurar tu propia API key de Anthropic. Ventajas:
- Sin tope mensual — pagas directo al proveedor.
- Ideal para uso intensivo.
- Configuración en Admin → Billing → Chat IA → "Configurar BYOK".
- La key se almacena cifrada (AES-256) en tu cuenta.
Códigos de acceso (bonos)
Los superadmins pueden generar códigos nominativos desde Admin → Licensing → Códigos. Tipos:
- Free indefinido: suscripción activa hasta anular (ideal para early testers, MVPs).
- Free con duración: activa durante N meses.
- Con overrides personalizados: permite subir/bajar límites concretos (ej.
{"ai_tokens_month": 2000000}).
Un código puede ser:
- Por email: sólo canjeable por el usuario con ese email (flexible — la empresa se crea al canjear).
- Por empresa: canjeable solo por una empresa específica (rígido).
- Abierto: cualquier usuario con el código puede canjear (limita con
usos_max).
Canje
Dos vías:
- Durante registro: en register.php, el código es obligatorio (no hay trial libre en early access).
- Desde una cuenta existente: Admin → Billing → "Canjear código".
Anulación
El superadmin puede anular un código desde Admin → Licensing → Códigos. Efecto inmediato: la suscripción derivada pasa a cancelled y la cuenta pierde acceso a límites del tier (vuelve a modo legacy si no tiene otras suscripciones).
Gestión (superadmin)
Admin → Licensing tiene 5 tabs:
- Códigos: generar, anular, ver canjes.
- Suscripciones: ver todas las suscripciones del sistema, gestionar overrides.
- Partners: CRUD de partners Certified/Strategic con tracking de comisiones.
- Límites: editar
tier_limits(cambios inmediatos globales). - Precios: editar
tier_prices. El cambio se refleja en/pricingal recargar.
Página pública de precios
Disponible en /mmaker/pricing.php. Lee en vivo de tier_prices y tier_limits. Bilingüe ES/EN. CTA lleva a register.php.
Base de datos (referencia)
subscriptions: suscripciones activas por empresa y producto.tier_limits,tier_prices: catálogos editables.subscription_overrides: excepciones individuales.access_codes,access_code_redemptions: bonos y canjes.usage_metrics: contadores mensuales (cargas, mails, tokens IA).ai_usage_log: log detallado de llamadas al chat.byok_config: configuración BYOK cifrada.lifecycle_events: auditoría de cambios de suscripción, canjes, avisos.partners,partner_attributions,partner_commissions: programa de partners.