Scripts de Servidor

¿Qué es y para qué sirve?

Un Script de Servidor es un fragmento de código en C# que asocias a un Objeto del sistema (por ejemplo, Solicitudes de Servicio o Viajes) y a un Evento concreto de su ciclo de vida (Antes de Grabar, Después de Grabar, y para algunos objetos también antes/después de un cambio de estado o de una asignación de empleado). Cuando un usuario graba una transacción de ese tipo, AdmCloud ejecuta tu script automáticamente en el servidor, con acceso al registro que se está guardando.

Esto te permite implementar reglas de negocio muy específicas de tu empresa —que AdmCloud no ofrece de forma nativa— sin depender de un desarrollo a la medida del producto: validar el formato de un campo, exigir una combinación de datos particular, o rechazar la transacción con un mensaje de error propio si no se cumple una condición.

Cómo se usa

1. Crea un nuevo script (botón Crear) e indícale un Nombre único que te ayude a identificarlo.
2. Selecciona el Objeto del sistema donde se ejecutará (por ejemplo, Solicitudes de Servicio o Viajes) y el Evento que lo dispara (Antes de Grabar, Después de Grabar, o alguno de los eventos adicionales disponibles para ese objeto).
3. Escribe el código en C# en el editor con resaltado de sintaxis. Dentro del script tienes disponible la variable record, que representa el registro que se está guardando, para leer o exigir condiciones sobre sus campos. Por ejemplo:
   if (record.SKU.Length != 3) throw new ApplicationException("La longitud del código debe ser de 3 caracteres");
4. Marca "Protegido" si quieres que solo tú (el Propietario) puedas editarlo más adelante; de lo contrario, cualquier otro usuario con permiso de edición podrá modificarlo.
5. Guarda el script y pruébalo grabando una transacción del Objeto y Evento configurados, para confirmar que se comporta como esperas antes de dejarlo en uso por otros usuarios.
6. Consulta, edita o elimina el script desde el listado o su pantalla de Detalles, que además muestra el log de auditoría de quién lo creó, editó o eliminó.

Capacidades principales

• Se ejecuta automáticamente en el servidor, dentro de la misma transacción que graba el registro: si el script lanza un error, la operación se revierte por completo.
• Para la mayoría de los objetos del sistema puedes engancharte a los eventos Antes de Grabar y Después de Grabar.
• Para Solicitudes de Servicio y Viajes también puedes engancharte a Antes/Después de un cambio de estado y Antes/Después de una asignación de empleado.
• El script puede lanzar un mensaje de error propio (con throw new ApplicationException("...")) que el usuario ve directamente en pantalla al intentar grabar.
• Puedes marcar un script como Protegido para que solo su Propietario pueda modificarlo, evitando cambios accidentales de otros usuarios.
• Log de auditoría en la pantalla de Detalles con quién creó, editó o eliminó el script.

Campos clave

Validaciones al guardar

• El Nombre es obligatorio y debe ser único: no puede existir ya en otro script.
• El Objeto y el Evento son obligatorios, y su combinación debe estar soportada: para la mayoría de los objetos solo se permiten los eventos Antes de Grabar y Después de Grabar; los eventos de cambio de estado y de asignación de empleado solo están disponibles para Solicitudes de Servicio y Viajes. Si eliges una combinación no soportada, el sistema rechaza el guardado.
• El Propietario es obligatorio y debe corresponder a un usuario activo.
• Solo el Propietario puede editar un script marcado como Protegido; si otro usuario lo intenta, el sistema rechaza el cambio.
• No se puede eliminar un script del que dependan Plugins existentes; el sistema te muestra cuáles.
• El código solo puede usar lo permitido en los scripts (ver "Límites de ejecución y seguridad"); si usa algo no permitido, el sistema rechaza el guardado indicando qué elemento y en qué línea.
• Si tu código C# lanza una excepción de tipo ApplicationException al ejecutarse sobre una transacción real, el usuario que grababa ve ese mensaje y la operación no se completa; cualquier otro tipo de error también detiene la operación, mostrando un mensaje genérico.

Disponibilidad

• Consultar y ver el detalle de los Scripts de Servidor requiere el permiso "Personalización" de tu grupo de usuarios, además de tener la función habilitada en tu empresa.
• La función completa requiere el plan Enterprise.
• Crear, editar o transferir un script a otra empresa está restringido a usuarios marcados como "Para Soporte Técnico", porque un script mal escrito afecta todas las transacciones del objeto donde se ejecuta.
• Eliminar un script requiere el nivel de permiso correspondiente, y no se permite si el script está en uso por un Plugin.

Límites de ejecución y seguridad

Los scripts se ejecutan en los mismos servidores que usan todas las empresas, por lo que AdmCloud les aplica estos controles. Valen también para las fórmulas de numeración y para las fórmulas de los conceptos de nómina.

• Tiempo máximo de 5 segundos por ejecución. Si el script lo supera (por ejemplo, por un ciclo que nunca termina), AdmCloud lo detiene y la transacción no se graba.
• Profundidad máxima de llamadas. Si una función se llama a sí misma sin fin, AdmCloud la detiene antes de afectar el servidor.
• Expresiones regulares con tiempo límite. Puedes usar Regex para validar formatos (RNC, NCF, correos...); cada búsqueda se detiene si tarda más de 1 segundo (RegexMatchTimeoutException).
• Puedes usar los datos de record, los tipos básicos de C# (números, textos, fechas, Math, Convert, Guid), System.Text y System.Globalization, las listas y diccionarios, LINQ (con métodos o con from ... select), funciones locales, lambdas, goto, y declarar tus propias clases, structs, interfaces y enums. También Environment.NewLine, Console.WriteLine y Debug.WriteLine.
• No se permite acceder a archivos, red, procesos, hilos ni a la configuración del servidor (System.IO, System.Net, System.Diagnostics, System.Threading, el resto de Environment, GC), usar reflection (typeof, GetType(), Type), lock, async / await, ni las directivas #r / #load. En tus clases no se permiten campos, propiedades automáticas ni eventos static (usa const), constructores static, finalizadores (~Clase()) ni record.
• Los scripts que ya existían también se revisan antes de cada ejecución: si usan algo no permitido, la transacción no se graba y se muestra el elemento y la línea a corregir.
• Si una línea empieza con record. (por ejemplo record.Notes = "...";), escríbela como @record.Notes = "...";: en las versiones nuevas de C# record es una palabra reservada al inicio de una instrucción. Dentro de una condición (if (record.Total > 0)) no hace falta.

Consejos y errores comunes