Best practices for custom software development in Athento – Athento

IMPORTANT: The vast majority of best practices recommended for development on Athento are best practices known in the field of software engineering. Having personnel trained in this discipline is an essential factor when it comes to custom code development.

IMPORTANT: Athento reserves the right to remove from the platform any custom code that it considers does not meet the minimum criteria of quality, efficiency and security. In your case, Athento will previously inform you of the upgrades or corrections to be made giving a period of 60 calendar days for their realization before deactivating such code.

Buenas prácticas en general

1. As in any information system, resources must be used optimally. For example:

Forms should be designed with a reasonable number of fields, more than 200 fields is already an abnormal situation in a form. For more information see: What is the maximum number of fields allowed in a document in Athento?
When configuring a choice type field, it is recommended that the list of values be configured as a Dictionary, instead of configuring the options directly on the field.
More than 1,000 items per tray is not considered a good tray design. For more details see: Queues
It is recommended to standardize the names of spaces, forms, metadata so that they can be reused without impacting previous configurations.
Etc.

2. Athento recommends the use of descriptive names for operations, so that users can easily identify what the operation does.

3. In general, it is recommended that operations take less than 3 seconds to execute.

It is necessary to consider that the extraction operations depend on the number of pages that compose the document on which they are executed, so the times may vary.

4. Optimal code must be developed from the performance point of view, therefore, the following must be considered:

That the database queries performed by the customized code are optimal.
That the code has complexity orders close to constant order.
Idem for memory consumption.

5. Developing unit tests for operations will help in quality assurance.

Best practices on the development cycle

The development cycle of custom software development for Athento includes the use of GIT repositories, developments made from local, or from a server dedicated to development.

As best practices, it is recommended:

Do not develop directly in production environments.
Do not make changes or modifications directly in production environments (except hotfixes).
Keep the code in a version control system (GIT).
For code deployment, limit access to qualified personnel only.

Best practices on source code

Apply PEP8
The execution of operations should not have a duration longer than 5 seconds each. These 5 seconds are a reference, the context in which they are going to be executed must be taken into account. For example, if the operation is going to be executed on thousands of documents per hour, it is recommended to have a shorter duration.
Functions/methods should not be longer than 30 lines.
Control exceptions in the operations.
If you are going to perform massive updates, use Django's "bulk update" option. https://docs.djangoproject.com/en/4.1/ref/models/querysets/#bulk-update

Best practices on creating operations

During the testing phase, use logs for easier debugging.
Make sure your execution time is less than 10 seconds, recommended less than 5 seconds.

Good practices on command creation

If the command goes through a list of documents, it is recommended to do it in a specific order. For example, according to "id".
If we are going to process a high volume of elements, paginate the result.
Have parameters that allow to indicate start and end elements. This allows the command to be executed in parallel for a given set of elements.
Use the CronExecution entity to keep trace of the command execution.
To have a --test_uuid parameter that allows to execute the command on a specific document.
To join two querysets with many results (thousands), flatten the results by obtaining the ids of the elements, operate on these ids with set and list entities, and obtain the results based on the resulting ids.
Avoid generating reports with information that has not changed, it is advisable to make reports on what has been modified during the day and work them in a BI system. Avoid making commands that export the information of "the whole year" or "the whole month".
It is recommended that reports be generated by exporting the most recent information.
It is not recommended to export reports every 30 minutes with volumes in the order of 50,000 records and 180 days old.
1. To export frequencies every 30 minutes or 1 hour, the age limit should be 1 day and a maximum of 1,000 records.
2. To export 50,000 records with 180 days of age, the export should be configured to be performed during a window that does not affect the operation, for example during the early morning and only once a day.
For all purposes Athento recommends to exploit the data in a dedicated BI tool.
Leave the code clean, avoid leaving "print" not needed during production use, do not leave "set_feature" that have been used for debugging, etc.
It is important to keep in mind that when the commands handle a high volume of elements, it is suggested that they be executed at times that do not impact the operation of the users in the tool, for example, during non-business hours or at the end of the working day.
If the command must act against a volume of thousands of elements, during the testing phase, it is advisable to launch it on a smaller limit, tens of documents, in order to be able to check the result. The number of items can be limited directly by slice or filtering the items created in the last few hours.

Best practices on parameter usage

Athento has different levels for configuration parameterization:

Operations allow parameters.
Commands allow parameters, which can be included directly when configuring from advanced administration in "Crontab Config".
From advanced administration, parameters can be created in the tables "Config property", "Config secret property" and "Config file property".
From advanced administration, some parameters can be changed in "Config settings".
At server level, the file local_settings.py can be used.

Best practices on the use of UAT environments

UAT environments are used for testing purposes, therefore the following guidelines are recommended:

These environments usually have a more limited amount of resources, for that reason, it is not recommended to load UAT environments with millions of documents or heavy configurations (thousands of fields in forms, thousands of elements in trays, hundreds of automations, etc.).
For security reasons, real data should not be used in UAT environments.
In UAT environments, backups are usually not secured, it is very important not to save data that needs to be backed up.

Abbreviations for variables

In some cases, it is useful to have abbreviations for certain variables that are widely used, the abbreviations recommended by Athento are:

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