Buenas prácticas para el desarrollo de software personalizado en Athento – Athento

IMPORTANTE: La gran mayoría de buenas prácticas recomendadas para el desarrollo sobre Athento, son buenas prácticas conocidas en el ámbito de la ingeniería del software. Contar con personal formado en esta disciplina es un factor esencial en lo que se refiere al desarrollo de código personalizado.

IMPORTANTE: Athento se reserva el derecho de eliminar de la plataforma cualquier código personalizado que considere que no cumple los criterios mínimos de calidad, eficiencia y seguridad. En su caso, Athento le informará previamente de las mejoras o correcciones que deban realizarse dando un plazo de 60 días naturales para su realización antes de desactivar dicho código.

Buenas prácticas en general

Como en cualquier sistema de información, deben usarse los recursos de forma óptima. Por ejemplo:
- Se deben diseñar formularios con un número de campos razonable, más de 200 campos ya es una situación anormal en un formulario. Para mayor información consultar: ¿Cuál es el número máximo de campos permitido en un documento en Athento?
- Cuando se configura un campo de tipo choice, es recomendable que la lista de valores se configure como un Diccionario, en lugar de configurar las opciones directamente sobre el campo.
- Más de 1.000 elementos por bandeja no se considera un buen diseño de bandeja. Para mayor detalle consultar: Colas
- Se recomienda la estandarización en el nombre de los espacios, formularios, metadatos de manera que se puedan reutilizar sin generar impactos sobre configuraciones previas.
- Etc.
Athento recomienda el uso de nombres descriptivos para las operaciones, de manera que los usuarios puedan identificar fácilmente lo que hace la operación.
Las operaciones en general es recomendable que tarden menos de 3 segundos en ejecutarse.
Es necesario considerar que las operaciones de extracción tienen dependencia respecto del número de páginas que compongan el documento sobre el que se ejecutan, con lo cual los tiempos pueden variar.
Se debe desarrollar código óptimo desde el punto de vista de rendimiento, se deben considerar, por tanto:
- Que las consultas a base de datos realizadas por el código personalizado sean óptimas.
- Que el código tenga órdenes de complejidad cercanos a órden constante.
- Idem para consumo de memoria.
Desarrollar tests unitarios para las operaciones será de ayuda en el aseguramiento de la calidad.

Buenas prácticas sobre el ciclo de desarrollo

El ciclo de desarrollo de software personalizado para Athento incluye la utilización de repositorios GIT, desarrollos realizados desde local, o desde un servidor dedicado al desarrollo.

Como buenas prácticas, se recomienda:

No desarrollar directamente en entornos de producción.
No realizar cambios o modificaciones directamente en entornos de producción (salvo hotfixes).
Mantener el código en un sistema de control de versiones (GIT).
Para despliegue de código, limitar el acceso únicamente a personal cualificado.

Buenas prácticas sobre el código fuente

Aplicar PEP8
La ejecución de operaciones no debería tener una duración mayor a 5 segundos cada una. Estos 5 segundos son una referencia, debe tenerse en cuenta el contexto en el que se van a ejecutar. Por ejemplo, si la operación se va a ejecutar sobre miles de documentos a la hora, es recomendable que tenga una duración menor.
Las funciones/métodos no deben tener una longitud mayor a 30 líneas.
Controlar las excepciones en las operaciones.
Si se van a realizar actualizaciones masivas, usar la opción "bulk update" de Django. https://docs.djangoproject.com/en/4.1/ref/models/querysets/#bulk-update
No usar str sobre un objeto para luego comparar el resultado con un nombre de objeto o similar. La implementación de str podría cambiar en cualquier momento. En su lugar, comparar el valor del atributo que deseemos.

Buenas prácticas sobre creación de operaciones

Durante la fase de pruebas, usar logs para depurar con mayor facilidad.
Asegurar que su tiempo de ejecución sea inferior a 10 segundos, recomendable inferior a 5 segundos.

Buenas prácticas sobre creación de comandos

Si el comando recorre un listado de documentos, es recomendable hacerlo en un orden concreto. Por ejemplo, según "id".
Si vamos a tratar un volumen alto de elementos, paginar el resultado.
Disponer de parámetros que permitan indicar elementos de incio y fin. Esto permite poder ejecutar el comando en paralelo para un conjunto determinado de elementos.
Usar la entidad CronExecution para mantener traza de la ejecución del comando.
Disponer de un parámetro --test_uuid que permita ejecutar el comando sobre un documento en concreto.
Para realizar join de dos queryset con muchos resultados (miles), aplanar los resultados obteniendo los ids de los elementos, operar sobre dichos ids con entidades set y list, y obtener los resultados en base a los ids resultantes.
Evitar generar reportes con información que no haya cambiado, es recomendable hacer reportes sobre lo que se haya modificado en el día y trabajarlos en un sistema BI. Hay que evitar realizar comandos que exporten la información de "todo el año" o "todo el mes".
Se recomienda que para la generación de reportes se realice con la exportación de la información más reciente.
No se recomienda la exportación de reportes cada 30 minutos con volúmenes del orden de 50.000 registros y 180 días de antigüedad.
- Para frecuencias de exportación cada 30 minutos o 1 hora, el límite de antigüedad debe ser de 1 día y un máximo de 1.000 registros.
- Para exportar 50.000 registros con 180 días de antigüedad, la exportación debe configurarse para ser realizada durante una ventana que no afecte la operación, por ejemplo durante la madrugada y sólo 1 vez al día.
Para todos los efectos Athento recomienda explotar los datos en una herramienta dedicada de BI.
Dejar el código limpio, evitar dejar "print" no necesarios durante el uso en producción, no dejar "set_feature" que se hayan usado para depuración, etc.
Es importante tener en cuenta que cuando los comandos manejen un volumen alto de elementos, se sugiere sean ejecutados en horarios que no impacten la operación de los usuarios en la herramienta, por ejemplo, en horario no hábil o al finalizar la jornada laboral.
Si el comando debe actuar contra un volumen de miles de elementos, durante la fase de pruebas, es recomendable lanzarlo sobre un límite más pequeño, decenas de documentos, para así poder comprobar el resultado. Se puede limitar directamente el número de elementos haciendo slice o filtrando los elementos creados en las últimas horas.

Buenas prácticas sobre uso de parámetros

Athento tiene distintos niveles para la parametrización de la configuración:

Las operaciones permiten parámetros.
Los comandos, permiten parámetros, que puden incluirse directamente al configurar desde administración avanzada en "Crontab Config".
Desde administración avanzada, se pueden crear parámetros en las tablas "Config property", "Config secret property" y "Config file property"
Desde administración avanzada, se pueden cambiar algunos parametros en "Config settings".
A nivel de servidor, se puede usar el fichero local_settings.py

Buenas prácticas sobre ciclos de vida

Es normal que los procesos evolucionen y con ello que sea necesario ajustar o modificar por ejemplo los ciclos de vida, Athento recomienda:

Revisar que los estados o transiciones tengan únicamente caracteres alfanuméricos. + info
Se recomienda la estandarización en el nombre de los estados del ciclo de vida y transiciones de manera que se puedan reutilizar sin generar impactos sobre configuraciones previas.
Si en algún momento van a realizar migración del ciclo de vida, no deben borrar los estados originales hasta que la migración de los estados de los documentos se haya realizado.
Por integridad de los datos, en caso de que se "elimine" un estado del ciclo de vida, debe realizarse la homologación o migración para garantizar que los documentos anteriores al cambio tengan un estado del ciclo de vida asignado.

Buenas prácticas sobre el uso de entornos UAT

Los entornos UAT se utilizan para pruebas, por lo tanto, se recomiendan las siguientes indicaciones:

Estos entornos suelen tener una cantidad de recursos más limitada, por ese motivo, no es recomendable cargar los entornos de UAT con millones de documentos o configuraciones pesadas (miles de campos en formularios, miles de elementos en bandejas, cientos de automatismos, etc.).
Por razones de seguridad, no se deben usar datos reales en entornos de UAT.
En los entornos de UAT, los backups no suelen estar asegurados, es muy importante no guardar datos de los que se requiera un backup.

Abreviaturas para variables

En algunos casos, es útil tener abreviaturas para ciertas variables que son muy usadas, las abreviaturas recomendadas por Athento son:

fil o doc# Para una variable con instancia de File
mt o mtd # Para una variable con instancia de Metadata
mtt # Para una variable con instancia de MetadataType
dt # Para una variable con instancia de DocumentType
s # Para una variable con instancia de Serie

Ejemplos de optimización de código

TODO

Te puede interesar ¿Cómo desplegar código personalizado en una instancia dedicada?