--- title: "Cron Job" slug: "nodejs-cron-job" description: "Send the FILE consumer log files of the Node.js Library to Mapp Intelligence with a custom or the predefined cron job: options, exit codes, file handling." status: "update" updated: 2026-11-02T16:53:36Z published: 2026-11-02T16:53:36Z canonical: "docs.mapp.com/nodejs-cron-job" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.mapp.com/llms.txt > Use this file to discover all available pages before exploring further. # Cron Job We recommend using a cron job which will send logfile requests to the Mapp tracking server every few minutes, and empty your file to keep it at a manageable size. There are two options: Custom and Predefined. ## Custom Cron Job File This option requires you to write your own cron job file and use our *MappIntelligenceCronjob* class. ### Methods #### constructor For a complete configuration of the Mapp Intelligence Cronjob please check [Configuration](/v1/docs/nodejs-integration-and-configuration). The constructor accepts a `MappIntelligenceConfig` or the command line arguments as an array (`process.argv`, see Predefined Cron Job Script below). Anything else throws an error (`Unsupported config option`). Without a track ID or track domain the constructor throws an error as well (`Argument '-i' or alternative '--trackId' are required`, `Argument '-d' or alternative '--trackDomain' are required`); catch it, `run()` is not reached then. Without `filePath` and `filePrefix`, `os.tmpdir()` and `MappIntelligenceRequests` are used. The cron job always sends with the HTTP_CLIENT consumer and a batch size of 1000, whatever `consumerType`, `setConsumer()` and `maxBatchSize` of the configuration say, and with an unlimited queue and no `requestInterval`. `maxAttempt`, `attemptTimeout`, `connectionTimeout`, `readTimeout`, `maxFileDuration` and the log level are taken from the configuration. ```javascript /** * @param config Mapp Intelligence config or command line arguments * @throws Error Mapp Intelligence configuration exception */ const cronjob = new MappIntelligenceCronjob(config: MappIntelligenceConfig | Array); ``` #### run Send the logfile requests to the Mapp tracking server and delete your logfiles to keep it at a manageable size. Returns the following results: - **0**: All data was sent successfully, there were no log files to send, another run is still sending the files of the same file path and prefix (INFO), tracking is deactivated (`setDeactivate(true)` or `--deactivate`, logged at level INFO, nothing is sent), or `--help` / `--version` was printed. - **1**: An error has occurred: - a log file could not be sent completely or could not be read and is kept for the next run, - a log file contained requests that can never be sent, - a sent log file can neither be deleted nor renamed (see the table below), - the file path does not exist or is not writable, so the run lock cannot be created (`Request log files "<filePath>" not found`, level ERROR), or the log files cannot be listed, - the command line is invalid (an unsupported option prints the help on stderr). A missing track ID or track domain throws in the constructor (see above); the predefined script `mapp-intelligence-node` prints the message on stderr and ends with exit status 1. `run()` never ends the process itself. Errors are written to stderr, also without `--debug` (at the configured log level, default `ERROR`); `--debug` writes all messages of the log level to stdout. How a run works: 1. Temporary files (`<prefix>-*.tmp`) that are older than the configured `maxFileDuration` (default 30 minutes) are renamed into log files (`.log`), logged at level INFO. This happens under the same lock (`<prefix>.lock`) the file consumers use while they write, so no request is written into a file at the moment it is renamed; a writer detects the rename and continues with a new file. A rename never replaces an existing file. 2. The log files (`<prefix>-*.log`, oldest first) are sent one after another. Only files named `<prefix>-<timestamp>…` are picked up, so the prefix `Shop` does not send the files of the prefixes `ShopDE` and `Shop-DE`. The result decides what happens with each file: | Result | File | | --- | --- | | Every request was delivered | Deleted. If it cannot be deleted, it is renamed to `*.log.sent` (logged at level WARN) so it is not sent again. | | A batch could not be delivered right now (e.g. server error, no connection) | Kept. The run stops with exit status 1, this file and all files after it are sent with the next run. | | A batch can never be sent (permanent client error such as a wrong track ID, or a batch above the hard limits) | Its requests (only these, not the delivered ones) are appended to `*.log.discarded` (logged at level ERROR) and not picked up again; the data stays on disk. If no other batch of the file has to be retried, the log file is deleted (or renamed to `*.log.sent`), the run continues with the next file and ends with exit status 1. If other requests have to be retried, the file keeps only them (see below). If the discarded requests cannot be written, the file is kept unchanged (logged at level ERROR) and the run stops with exit status 1. | | The file cannot be read | Kept, logged at level ERROR, the run stops with exit status 1. | | Every request was delivered, but the file can neither be deleted nor renamed to `*.log.sent` | Kept, logged at level ERROR (`Log file <file> was sent but could neither be deleted nor renamed, ...`). The run stops with exit status 1. Every following run sends the file again (the requests arrive twice) and stops there, until the file can be deleted. Fix the permissions of the file path. | A file that could only be sent partially keeps only the requests that were not delivered (logged at level INFO), so the next run does not send the delivered ones again. The file is replaced atomically: the remaining requests are written into `<file>.<random>.part` first, which then replaces the log file. If the replacement fails, the whole file is sent again with the next run. If the cron job is killed in the middle of a file, the whole file is sent again with the next run; a `.part` file left behind by a run that was killed during the replacement is not picked up and not removed by the cron job, delete it manually. Only one run at a time sends the files of a file path and prefix: a run holds the lock `<filePath>/<filePrefix>.cronjob.lock` and refreshes it every 10 seconds. A run that starts while another one is still sending (e.g. with a slow track server) ends right away with exit status 0 and an INFO message. The lock of a run that was killed is taken over after 60 seconds. ```javascript /** * @return Promise */ cronjob.run(); ``` #### Example ```javascript import {MappIntelligenceConfig, MappIntelligenceCronjob} from '@mapp-intelligence/node'; (async function() { let status = 1;    try { const mappIntelligenceConfig = new MappIntelligenceConfig(); mappIntelligenceConfig.setTrackId("111111111111111"); mappIntelligenceConfig.setTrackDomain("analytics01.wt-eu02.net"); mappIntelligenceConfig.setFilePath("/path/to/your/log/file/"); mappIntelligenceConfig.setFilePrefix("MappIntelligenceData");        const cronjob = new MappIntelligenceCronjob(mappIntelligenceConfig);        status = await cronjob.run();    } catch (e) {        // e.g. a missing track ID        console.error(e.message);    }    process.exit(status); })(); ``` ## Predefined Cron Job Script This option allows you to use our predefined `mapp-intelligence-node` script, which is included in the package. | Short notation | Long notation | Description | | --- | --- | --- | | -i | --trackId | Enter your Mapp Intelligence track ID provided by Mapp. | | -d | --trackDomain | Enter your Mapp Intelligence tracking URL. | | -f | --filePath | Enter the path to your request logging file. | | -p | --filePrefix | Enter the prefix for your request logging files. | | | | -c | --config | Enter the path to your configuration file (*.json or *.js). The options `-i`, `-d`, `-f`, `-p`, `-l`, `--debug` and `--deactivate` override the values of this file. | | | | | --debug | Activates the debug mode. The debug mode sends messages to the command line. | | -l | --logLevel | Shows all messages at this level and at higher levels of importance: `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL` and `NONE`. | | | --deactivate | Deactivate the tracking functionality (`--deactivate false` does not deactivate). | | | --help | Display the help (this text) and exit. | | | --version | Display version and exit. | #### Example ```bash $ mapp-intelligence-node -i 111111111111111 -d analytics01.wt-eu02.net -f /tmp/ -p MappIntelligenceData $ mapp-intelligence-node -i 111111111111111 -d analytics01.wt-eu02.net -f /tmp/ -p MappIntelligenceData --debug $ mapp-intelligence-node -c /path/to/your/configuration/file/config.json $ mapp-intelligence-node -c /path/to/your/configuration/file/config.json --debug ``` ## Define a Cron Job To create your crontab file, type the following command at the shell prompt `crontab -e` and add the following lines. cron starts the job in the home directory of the user: use absolute paths for the configuration file and the `filePath`, a relative path is resolved against the current working directory. ```bash # sends every five minutes the tracking data to the Mapp tracking serve */5 * * * * mapp-intelligence-node -c /path/to/your/configuration/file/config.json ```