Hooks

Hooks types

Common: reusable logic Import: Allows to import excel files Send Notification (web) Scheduled Jobs Generate QR Code

Referencing a hook

Anywhere the platform asks for a hook identifier (for example customHookId in a custom query endpoint, or the before/after transaction hooks of a data source) you can use either:

the hook name, which is the readable identifier you gave it, or
the hook _id (the 24-character Mongo id shown in the hook detail).

queryOptions: { customHookId: "getPersonasExternas" }       # by name (recommended)
queryOptions: { customHookId: "67981f0014d7df001d4aef1b" }  # by _id

Prefer the name: cloning an application or creating an environment copies the hooks with new _ids, so a reference by _id has to be remapped, while a reference by name keeps pointing at the local copy of the hook. A hook referenced this way only runs from its own table: customLead with customHookId can run the custom endpoint hooks of the Lead table, and the same applies to customEntityQuery and to the before/after transaction hooks of a mutation. Referencing a hook of another table returns Hook not found; call the operation of the hook’s table instead (for example customUsuario for a hook of Usuario). Hooks without a table still run from any table.

Anyone with the custom permission on a table can call its custom endpoint hooks, including anonymous users when the table grants anonymous access. A custom endpoint that is not meant to be public must check options.session and reject calls without a logged-in user.

The hook pickers in the designer (for example the import/export buttons) save the name. Configurations created before this change still hold the _id: they keep working as they are, and the picker shows the hook they point to. Selecting a hook again replaces the stored _id with the name. Configurations that still hold an _id can also be migrated in bulk: the platform can run a one-off migration for your application that rewrites the stored _ids (in features, feature versions and hook code) to the corresponding hook name. It is opt-in — ask the Codenull team to run it — and until it runs the existing references keep working exactly as they are.

Hook names are not enforced to be unique. If two hooks in the same application share a name, the reference resolves to the oldest one. The platform renames the duplicates automatically on startup (to <name>_2, <name>_3, …) so every hook stays reachable by a unique name.

Roles

Avoid hardcoding a role’s Id inside a hook. Roles live in the SQL Server Rol table — the Id itself is stable across clones and environments of the same application, but it isn’t readable or auditable in a hook’s code, and it’s specific to this app’s role catalog. Every role also has a Codigo, generated automatically from its name when the role is created and never changed afterwards — not even if the role is later renamed (see Authorization: Role Codigo). Prefer resolving roles by Codigo with getRoleByCodeAsync/getRolesByCodesAsync from ./utils/roleResolver: both are cached for 5 minutes, so calling them on every hook execution is safe. Both resolve the full row (Id, Nombre, Codigo) instead of just the Id, so you can read any other column of the role you just looked up — its current Nombre for a message, for example — without a second query.

const { getRoleByCodeAsync } = require("./utils/roleResolver");

const beforeUpdateCostoProduccion = async (instance, options) => {
  const isClosingReopen = instance.previous("Estado") === "Cerrado";
  if (!isClosingReopen) return;

  const supervisorRole = await getRoleByCodeAsync("SUPERVISOR");
  const userRoleIds = (options?.session?.userInfo?.RolesxUsuarios || []).map((r) => r.RoleId);
  if (!userRoleIds.includes(supervisorRole?.Id)) {
    throw new Error(`Only the ${supervisorRole?.Nombre ?? "Supervisor"} role can reopen a closed cost record.`);
  }
};
beforeUpdateCostoProduccion(instance, options);

getRolesByCodesAsync resolves several role codes in one call — useful to build a list of target role ids, for example when calling sendNotification with rolesTo:

const { getRolesByCodesAsync } = require("./utils/roleResolver");

const roles = await getRolesByCodesAsync(["DIRECTOR_TECNICO", "ADMIN"]);
const roleIds = roles.map((role) => role.Id);

Both functions return null (or omit that entry from the result) when there is no matching role — always treat that as deny, never as “no restriction configured”.

Hook context (`instance` and `options`)

Table hooks run as a callback with the signature async (instance, options) => { ... }:

instance: the record that triggered the hook. Access its fields with instance.dataValues.<Field>.
options.transaction: the active database transaction. Pass it to any additional query you run inside the hook (see Troubleshooting).
options.session?.userInfo: the authenticated user that triggered the event.
options.clientIp: IP address the request was made from, resolved from the reverse proxy headers. It can be null when there is no originating request (for example, scheduled jobs).

const auditChange = async (instance, options) => {
  await modelsapp.Auditoria.create(
    {
      Registro: instance.dataValues.Id,
      Usuario: options.session?.userInfo?.Id,
      Ip: options.clientIp,
    },
    { transaction: options.transaction }
  );
};
auditChange(instance, options);

options.clientIp is informational (audit trails, logging). Do not use it as your only security control: IP addresses can be shared (NAT, corporate proxies) and change between requests.

The same options object (session, clientIp) is also available in before/after transaction hooks and in custom endpoint hooks.

Send Emails

From: Email address from where you want to send the email, It is not required if was configured in the application designer
To: Email address of the destination person
Subject: Subject of the email (text plain)
Message: The body of the email can be in HTML format or Text Plain.

To know more about the allowed email options please read nodemailer docs

const sendEmail = require("./utils/mailSender").default;

//...
   const options ={
     from: 'correo@gmail.com',
     to: 'correo@gmail.com',
     subject: 'subject of the email',
     message: '<a>message of the email in HTML format or TEXT plain<a>'
   }
   await sendEmail(options);

Documentation for Sending Emails with Base64 Attachments (backend, hooks)

Override email provider settings

If you want to use a different mail provider you can pass that configuration as a second parameter of the sendEmail function

const sendEmail = require("./utils/mailSender").default;

//...
   const options ={
     from: 'correo@gmail.com',
     to: 'correo@gmail.com',
     subject: 'subject of the email',
     message: '<a>message of the email in HTML format or TEXT plain<a>'
   }
   
   const mailSenderOptions = {
      host: '',
      port: '',
      secure: true, //true or false
      user: '',
      pass: '',
      emailFrom: '' //optional if you are already using options.from
   }
   await sendEmail(options, mailSenderOptions);

Async Logic

const asyncFunctionExample = async (instance) => {
   // implement code here for async functions
}
asyncFunctionExample(instance);

Querying and importing database model

//import the model
const modelsapp = require("../modelsapp").default;

const asyncFunctionExample = async (instance) => {
    const personas = await modelsapp.Persona.findAll({
        where: { IglesiaId: '123' },
        limit: 100,
    });
   // implement code here for async functions
}

asyncFunctionExample(instance);

To see more querying examples you can use any sequelize method: https://sequelize.org/v4/manual/tutorial/querying.html

Hooks Errors

This section will show you how to throw hook errors. The simplest way to throw an error looks like this

throw new Error("My error message");

🔁Redirecting to a different Feature

If you want to allow the user to see a modal with a button that redirects to a new Feature, you should throw an exception using the CodenullError class with the following parameters: ✅ Example:

const CodenullError = require("./utils/CodenullError").default;

throw new CodenullError(
  {
    featureId: "6122b2944ee09f001813a6fe", // ID of the Feature to redirect to
    params: [
      {
        type: "hardcoded",   // Type of value (e.g., "hardcoded")
        value: instance.Id,  // Relevant value to pass
        name: "Id"           // Descriptive name of the parameter
      }
    ],
    target: "_blank", //open in a new tab
    okLabel: "Aceptar", //label for ok button
    cancelLabel: "Cancelar", //lable for cancel button
    message: error,          // Error message or object
    type: "navigation"       // Type must be "navigation" to trigger redirection
  },
  "my message"               // Optional message for logs or modal display
);

💡 type: "navigation" is mandatory to trigger the redirect behavior. The params array allows dynamic values to be passed to the destination feature

This is how the error message will look, once the user hit the “Aceptar/Ok” button will be redirected to the new feature

This requires the 1.1.9 version or greater

Executing Store Procedure from Hooks

//import a database connection
const dbApp = require("../modelsapp/db").default

const ReplicarDatos = async (instance) => {
    //pass a transaction configuration in case you need it
    await dbApp.query(`exec ReplicarDatos '${instance.Id}'`, { transaction: options.transaction })
}
ReplicarDatos(instance);

You can know more about queries here https://sequelize.org/master/manual/raw-queries.html

Other Import examples

const axios = require("axios").default;
const sortBy = require("lodash/sortBy");

Troubleshooting

Timeout doing database operations on the afterSave or any other after hook

Solution: Add the transaction to the operation as the second parameter

await modelsapp.Usuario.create(data, { transaction: options.transaction });

Get Started

Configurations

Agents

Environments

Reference

Hooks types

Referencing a hook

Roles

Hook context (`instance` and `options`)

Send Emails

Documentation for Sending Emails with Base64 Attachments (backend, hooks)

Override email provider settings

Async Logic

Querying and importing database model

Hooks Errors

🔁Redirecting to a different Feature

Executing Store Procedure from Hooks

Other Import examples

Troubleshooting

​Hooks types

​Referencing a hook

​Roles

​Hook context (instance and options)

​Send Emails

​Documentation for Sending Emails with Base64 Attachments (backend, hooks)

​Override email provider settings

​Async Logic

​Querying and importing database model

​Hooks Errors

​🔁Redirecting to a different Feature

​Executing Store Procedure from Hooks

​Other Import examples

​Troubleshooting

Hooks types

Referencing a hook

Roles

Hook context (`instance` and `options`)

Send Emails

Documentation for Sending Emails with Base64 Attachments (backend, hooks)

Override email provider settings

Async Logic

Querying and importing database model

Hooks Errors

🔁Redirecting to a different Feature

Executing Store Procedure from Hooks

Other Import examples

Troubleshooting