Skip to main content

Data mapping

Mapping consists in transforming the received data (trigger, API response) into the format expected by the destination system (database, ERP, another API). Done well, it stays readable, maintainable and avoids copying whole blocks of data. The variable syntax (input data, context, dictionaries) is detailed in Variable management.

Surgical approach​

Only transform what is necessary: only store in the context the values useful to the following nodes, rather than copying the whole data.

Variable naming​

Name the context variables explicitly: context.customer_id rather than context.var1, context.mapped_users rather than context.data2. The error traces and team work are all the more readable.

Extractors vs Code node​

  • Extractors (JSONPath): for simple assignments from an HTTP response ($.data.id → context.orderId).
  • Code node: for complex transformations (concatenation, calculations, mapping to another format).

Extract a value: the JSONPath extractor​

On an HTTP(S) Request node, an extractor copies a value from the response to a context variable. If the value is missing (JSONPath not found), the node fails — this is the recommended behavior to avoid propagating incomplete data to the following nodes.

Extracteur (JSONPath)Context variableContent
$.data.idorderId"12345"
$.data.itemsorderItems[...]
$.headers['ratelimit-remaining']rateLimitRemaining"49"

Transform: the Code node​

Example of mapping an API response to a database format, in a Code node:

// Mapping of an API response to a database format
const apiItems = (context.lastResponse.data.items) || [];

context.mapped_users = apiItems.map(item => {
    return {
        external_id: item.id,
        full_name: `${item.firstName} ${item.lastName}`,
        synced_at: new Date().toISOString()
    };
});

The result is then usable by the following nodes via {{mapped_users}} — see Context variables.

Never hard-code a secret​

Never store an API key or a password in a Code or HTTP(S) Request node: use the dictionaries ({{dictionaries.nomDuDico.cleDuDico}}) or the authentication methods.

Next steps​