Permisos Arcanos: el tomo secreto sobre roles y permisos para tus flujos en Cotalker (parte 1)

Trabajar con los permisos de Cotalker puede ser uno de los temas más enredados. A medida que los proyectos crecen, se transforman en un auténtico caldero de espaguetis mágicos, imposible de desenredar. Basta con asignar un rol equivocado a un permiso para que, minutos después, llegue un correo a las Artes Oscuras ([email protected]) alertando de una grieta en el hechizo del flujo.

Sin ir más lejos, cuando apenas era un muggle y llevaba unas semanas en Cotalker, me tocó editar y migrar un flujo con sus respectivos permisos. No me di cuenta y terminé sobreescribiendo los permisos de varios roles. ¿El resultado? El cliente no podía acceder a sus flujos e invocó directamente a la congregación de Archimagos de Consulting, saltándose todo protocolo de las Artes Oscuras.

Pero ya no más. Tras años de práctica creando flujos bajo la tutela del gran Brujo Calvo, he llegado a una fórmula probada: una estandarización que te permitirá gestionar roles y permisos sin miedo a invocar errores. En esta guía abriremos el códice RBAC de Cotalker para conjurar orden en tus flujos y evitar maldiciones en producción.

Capítulo 1: Las bases del hechizo. ¿Cómo funciona RBAC en Cotalker?

El sistema de permisos de Cotalker está altamente inspirado en RBAC: defines permisos atómicos, los agrupas en roles, y esos roles viajan dentro de cargos que finalmente se asignan a usuarios.

El resultado es una cadena clara (Usuarios → Cargo → Roles → Permisos), donde cada eslabón funciona como una runa mágica que debe encajar con la siguiente, de lo contrario, el conjuro no se completa.

Quedado de esta forma:

• Cargos: Combinaciones de roles asignables a usuarios. Un usuario puede tener asignado solo un cargo y un cargo puede contener varios roles.
• Roles: Es un conjunto de permisos. Puedes reutilizar permisos existentes o crear nuevos. Un rol puede agrupar múltiples permisos.
• Permisos: Llaves finas que Cotalker consulta en cada flujo.

Capítulo 2: Mapa del reino. ¿Dónde se ubican en Cotalker?

En Cotalker encontrarás permisos en muchos rincones: colecciones, bases de datos, formularios, usuarios y más. Sin embargo, el más importante, y donde todo realmente cobra sentido, son los permisos en los flujos de trabajo. Si dominas esa sección, el resto será un simple trámite.

Para configurar los permisos de un flujo, basta con crear un nuevo flujo o presionar el botón Editar en el panel de administrador (Administrador → Flujos de trabajo).

En esta sección, encontrarás dos agrupaciones de permiso:

2.1 Información General

Esta sección es bastante sencilla: si tu flujo tiene un formulario de inicio (startform), aquí defines qué permiso será necesario para poder responderlo (Permisos formulario de inicio).

Si no asignas ningún permiso, entonces cualquier usuario podrá responderlo sin importar su rol.

2.2 Ajustes Avanzados

A primera vista, esta sección puede intimidar por la cantidad de opciones, pero en realidad es más fácil de lo que parece. Veamos las más importantes:

• Permiso de visualización del flujo de trabajo: Es simplemente un eufemismo para decir: "¿Quién puede ver el flujo?"
• Permiso de importación de tareas: En Cotalker existe una opción algo "avanzada" que permite crear tareas de forma masiva por medio de un excel. También en conocido como "Importador Masivo", "Cargador Masivo" o "Importador de Tareas". Si este campo está vacío, entonces permanecerá desactivado, pero si añades un permiso, entonces se activará. Así que úsalo solo si sabes bien lo que estás haciendo.
• Permisos de edición: Yo lo llamaría como "¿Quiénes pueden editar el asset de una tarea?"
• Permisos de seguidor: O más conocido como "el permiso de los sapos", ya que permite a un usuario ver todas las tareas del flujo sin necesidad de estar invitado. Es, literalmente, una visión absoluta sobre el flujo, como si el usuario llevara un orbe de adivinación.

Capítulo 3: La convención mágica. Estandarización de nombres

Cotalker te da completa libertad para nombrar permisos, roles y cargos. El problema es que cada implementador lo hace a su manera y, cuando los proyectos crecen, mantener el orden se vuelve un dolor de cabeza.

Con el tiempo he pulido una convención que hasta ahora no me ha fallado. Aún no tiene nombre oficial, así que siéntanse libres de proponer uno.

3.1 Permisos

Como vimos en el capítulo anterior, hay múltiples permisos que se pueden añadir a un flujo, es por esto que cada acción debe tener un nombre de permiso bien marcado según la acción que quiere mostrar.

• Permisos formulario de inicio: Este permiso es prácticamente el permiso para responder el startform. ¿No quedaría bien llamarlo start-form entonces?
• Permiso de visualización del flujo de trabajo: Si es de visualización, lo mejor será que tenga view ¿no?
• Permiso de importación de tareas: Este es el conocido "Importador Masivo", ¿por qué no llamarlo de esa forma con un task-importsi permite importar tareas?
• Permisos de edición: La edición es prácticamente permisos de escritura, ¿qué tal un write?
• Permisos de seguidor: Este permiso puede ver todo, es como un view pero vitaminado. ¿Qué tal algo bien textual como: view-all?.

En resumen, los permisos base son: view, view-all, write, task-import y start-form.

Cada flujo debe tener sus propios permisos únicos y para diferenciarlos entre flujos, usaremos el nombre del flujo como prefijo en kebab-case. Dando como resultado <nombre-flujo>:<permiso>.

Ejemplo: un flujo llamado Órdenes de Compra tendría el prefijo de ordenes-de-compra , pero a mi me parece muy largo, así que lo dejaré como ordenes-compra. Por lo tanto, sus permisos quedarían así:

• Permisos formulario de inicio: ordenes-compra:start-form
• Permiso de visualización del flujo de trabajo: ordenes-compra:view
• Permiso de importación de tareas: ordenes-compra:task-import
• Permisos de edición: ordenes-compra:write
• Permisos de seguidor: ordenes-compra:view-all

Si quisiéramos verlo directamente en un flujo, tendríamos algo así:

Ahora se entiende mejor lo que hace cada apartado, ¿no?

3.2 Roles

Como comentamos antes, los roles no son más que un conjunto de permisos agrupados bajo un mismo nombre, lo que hace que su creación sea más sencilla y estructurada.

Antes de definirlos, conviene analizar qué facultades tendrá cada tipo de usuario dentro del flujo. En la práctica, los roles casi siempre los descubrimos conversando con el cliente, porque es él quien mejor sabe qué hará cada tipo de usuario y cuál es su cargo en la empresa. Retomemos el ejemplo del flujo Órdenes de Compra e imaginemos el siguiente caso:

“Mira, en este flujo de Órdenes de Compra tenemos tres tipos de usuarios.
Primero, un visualizador, que en realidad es un Supervisor. Él no crea ni aprueba nada, solo necesita ver que todas las tareas se estén ejecutando bien.
Luego está el aprobador, que es el Jefe de Área. Su trabajo es revisar las órdenes que le llegan y según eso decidir si las aprueba o las rechaza.
Y por último, tenemos al solicitante, que es la persona encargada de crear la orden de compra directamente a través del formulario inicial del flujo.”

De esta forma podemos desglosar los permisos que tendrá cada usuario:

• Solicitante: Debe visualizar el flujo (view) y responder el startform (start-form)
  • Permisos: ordenes-compra:view + ordenes-compra:start-form.
• Jefe de área (Aprobador): Debe visualizar el flujo (view) y responder ciertos formularios
  • Permisos: ordenes-compra:view.
• Supervisor (Visualizador): Debe visualizar el flujo (view) y además debe poder ver todas las tareas existentes en el flujo (view-all)
  • Permisos: ordenes-compra:view + ordenes-compra:view-all.

Ahora que sabemos bien lo qué hará cada usuario, viene la hora de crear los roles.

Para seguir un estándar en cuánto al nombrado, lo que haremos será seguir el siguiente patrón: <Nombre del Flujo>: <Nombre del Cargo o Rol>, donde

• Nombre del Flujo: debe identificar con claridad a qué flujo pertenece el rol. En este caso podría ser: "Órdenes de Compra" u "Orden de Compra"
• Nombre del Cargo o Rol: puede estar basado en el cargo (ej. Jefe de Área) o en la facultad del usuario (ej. Visualizador). Lo importante es mantener consistencia dentro de todo el proyecto.

Para este caso, me gusta más "Órdenes de Compra" como nombre del flujo junto con el rol que hará cada usuario.

• Órdenes de Compra: Solicitante → ordenes-compra:view + ordenes-compra:start-form
• Órdenes de Compra: Aprobador → ordenes-compra:view
• Órdenes de Compra: Visualizador → ordenes-compra:view + ordenes-compra:view-all

Habrás notado que aún no usamos permisos como ordenes-compra:task-import o ordenes-compra:write. Eso no fue un descuido, sino que forman parte de un rol especial que siempre recomiendo crear: Manager.

El Manager es un rol reservado exclusivamente para administradores del sistema o implementadores. Su propósito es unificar todos los permisos del flujo en un único rol, un verdadero grimorio maestro que concentra todas las llaves para administrar y mantener sin restricciones.

Como curiosidad, la idea de este rol maestro llamado "Manager" fue sacada de una librería para Node llama CASL. Si quieres más detalles para usarlo en tus códigos, te dejo la documentación:

CASL. Isomorphic Authorization JavaScript library

CASL (pronounced /ˈkæsəl/, like castle) is an isomorphic authorization JavaScript library which restricts what resources a given user is allowed to access. It’s designed to be incrementally adoptable and can easily scale between a simple claim based and fully featured subject and attribute based authorization. It makes it easy to manage and share permissions across UI components, API services, and database queries.

Siguiendo la convención, sería de esta forma:

• Órdenes de Compra: Manager → ordenes-compra:view, ordenes-compra:view-all, ordenes-compra:write, ordenes-compra:task-import, ordenes-compra:start-form.

Es importante aclarar que este rol no debe asignarse nunca a usuarios finales. A lo largo de mi experiencia, las peores “desgracias” ocurren cuando un usuario sin conocimientos técnicos recibe permisos absolutos. Por eso, este rol existe solo para quienes implementan y administran la plataforma.

Para crear roles basta con ir a su sección (Administrador → Roles de Acceso) e ingresar uno por uno los que hemos escrito aquí.

Como nota, una vez creado el rol Manager, es recomendable que lo asignes inmediatamente al usuario Administrador (o implementador, según corresponda).

3.3 Cargo

Por último, llegamos al cargo. Aquí ya no hay tanta ciencia ni convenciones estrictas: simplemente se designa el nombre del cargo real que tendrá el usuario dentro de la empresa, y se le asigna el rol correspondiente al flujo.

A diferencia de permisos y roles, donde necesitamos estandarización para mantener el orden, los cargos suelen llamarse tal cual el cargo real del usuario (ej. Solicitante, Jefe de Área, Supervisor).

Siguiendo el ejemplo del flujo Órdenes de Compra, los cargos quedarían así:

• Solicitante: Órdenes de Compra: Solicitante.
• Jefe de Área: Órdenes de Compra: Aprobador.
• Supervisor: Órdenes de Compra: Visualizador.
• Administrador: Órdenes de Compra: Manager.

De esta forma, cada cargo refleja directamente lo que el usuario hace en la organización, pero sin perder la estandarización que nos da tranquilidad al momento de escalar, mantener o auditar los permisos dentro de Cotalker.

Capítulo 4: Receta paso a paso

Esta es una pequeña guia que te servirá en caso de que debas crear los cargos, roles y permisos de un flujo:

4.1 Checklist

⃞ Definir un nombre para el flujo en kebab-case.
⃞ Crear los 4 permisos principales usando la convención de nombres.
⃞ Crear los roles junto al rol Manager.
⃞ Asignar los permisos en el flujo correspondiente.
⃞ Crear los cargos y asignarle los roles ya creados.

4.2 Ayudamemoria

Plantilla de permisos por flujo (recuerda que task-import es opcional):

<kebab-flujo>:start-form
<kebab-flujo>:view
<kebab-flujo>:view-all
<kebab-flujo>:write

Plantilla de roles por flujo

<Nombre de Flujo>: <Cargo/Rol>
<Nombre de Flujo>: Manager   # Obligatorio

Capítulo 5: Preguntas que suelen conjurarse

• ¿Puedo agregar más tipos de permiso?
  R: Sí, pero mantén siempre la convención flujo:acción en kebab-case.
• ¿Un cargo puede mezclar roles de varios flujos?
  R: Puede, pero evita los cargos “universales”. Prefiere cargos que reflejen funciones reales y áreas específicas. El único rol que puede considerarse “universal” es el Manager.
• ¿Puede un rol tener permisos de varios flujos?
  R: Idealmente no. Define un rol por flujo o propósito, y luego asígnalo a un cargo. De esa forma mantienes la trazabilidad y el orden.
• Por temas de tiempo no alcanzo a crear todos los roles/cargos. ¿Qué hago?
  R: Crea solo el rol Manager y utilízalo de forma temporal. Así podrás avanzar sin bloquearte. Eso sí, recuerda volver y dividir roles/cargos más adelante: abusar del Manager es como darle a todos la llave maestra del castillo.

Capítulo 6: Epílogo

Un RBAC claro es el mejor escudo contra el caos. Con una convención simple (flujo:permiso en kebab-case), roles bien definidos y un Manager custodiado como artefacto sagrado, tus flujos en Cotalker serán predecibles, auditables y fáciles de mantener.

La verdadera magia no está en los hechizos complejos, sino en la disciplina de nombrar, documentar y revisar. El resto… es pura repetición mágica.

¿Alguna vez un error de permisos te generó un dolor de cabeza en producción? Me encantaría leer tu experiencia en los comentarios.