Benjamin Marchand EI

Products › DoliAI Assistant › Documentation

DoliAI Assistant documentation

Install, configure and use DoliAI Assistant 1.0.0 in Dolibarr.

DoliAI Assistant adds a read-only AI assistant to Dolibarr. It shows as “DoliAI Assistant” and in the “DoliAI” menu. Its technical name is dolibarrai: module folder, package module_dolibarrai-1.0.0.zip and DOLIBARRAI_* constants. The module does not change the Dolibarr core.

Installation

Requirements

  • Dolibarr 20.0 or later, with the native external module mechanism. Tested versions: 20.0.4, 21.0.4, 22.0.5, 23.0.4 and 24.0.1.
  • Main entity only: only data of entity 1 is read, linked and stored. The Multicompany module is not supported; activation from another entity is refused with a message.
  • PHP 7.4 or later, 64-bit, with sessions and the json, curl, mbstring, iconv and zlib extensions.
  • A private documents directory, writable by PHP, strictly outside the web root. A folder under the web root that is only protected by .htaccess is not enough.
  • An account with an AI provider that offers an OpenAI-compatible Chat Completions API. See Configure the AI provider.

No cron, permanent worker, Redis, Composer or SSH access is needed. The PDF parser ships with the module. Your host must still allow the needed run time, memory and concurrent requests.

Deploy the module

  1. In Home → Setup → Modules/Applications, open the Deploy/install external app/module tab and upload module_dolibarrai-1.0.0.zip.
  2. Enable DoliAI Assistant in Setup → Modules/Applications.
  3. Open the module setup, set the monthly budget, then the AI provider (see below).
  4. Set the retention period in the Privacy and retention card, and check the effective private directory and its free space.
  5. Grant the Access the AI assistant chat permission to the internal users or groups who need it.
  6. Run the connection test, then ask a first question.

Manual installation: unzip the dolibarrai folder into the custom directory configured in Dolibarr, then follow steps 2 to 6. Back up the current module files before replacing them.

Configure the AI provider

The module does not contain an AI model. It connects to the provider that the global administrator chooses. This provider must offer an OpenAI-compatible Chat Completions API with:

  • streaming responses;
  • tool calls for the chat;
  • token usage in the response.

DeepSeek and OpenAI are examples. Your provider bills its usage; it is not included with the module.

In the module setup, enter the chat URL, API key, model, limits and prices. Prices must be set in the budget currency. Saved keys are encrypted with Dolibarr’s native encryption and stay masked; if that encryption is unavailable, the key is not saved.

The judge, which evaluates answers when the administrator asks for it, is set up the same way. The shared settings option lets it follow the chat settings.

The connection test of each role is a manual action. Like real answers, your provider may bill it.

HTTPS connections

The Chat and judge HTTPS connections section applies to the chat, the judge and connection tests:

  • Verify the HTTPS certificate is on by default.
  • Certificate authority (PEM file, optional): for a provider signed by an internal authority.
  • Pinned public keys (optional): 1 to 5 sha256//… fingerprints separated by “;”.
  • Allow a provider on a private network: tick it only for a self-hosted model (Ollama, vLLM). Otherwise, the call is refused before anything is sent.
  • Outbound proxy (http(s)://host:port): the provider must then use HTTPS.
  • Links to other sites in answers: ask for confirmation, or show as text only.

Redirects are not followed.

User permissions

  • The Access the AI assistant chat permission gives access to the assistant. Grant it only to the internal users who need it.
  • External users (linked to a third party) have no access to the assistant.
  • The setup, the administrator view of conversations, the judge and deletion are reserved to the global administrator.
  • The assistant reads only what the user is allowed to see in Dolibarr. Each new lookup uses the user’s current permissions.

Monthly budget

A shared monthly budget covers the chat, the judge and connection tests. The module reserves the maximum cost before each call, then tracks usage. A budget of zero blocks new billable calls.

When a budget limit is reached, the assistant must report it clearly. Reservations without reliable usage data stay conservative; reconcile them only after checking with the provider.

Using the assistant

Open the assistant

The DoliAI menu opens a help page with a button that opens the assistant in full screen. The DoliAI Assistant button, at the bottom right of each page, opens the compact chat. Minimizing the chat keeps its widget; closing it brings back the help page. The conversation and the draft are kept in both cases.

Ask a question

Ask a business question and give the period, customers or suppliers involved. Examples:

  • “Which September customer invoices are still unpaid? Show the amounts and the links so I can check them.”
  • “Compare invoiced sales in August and September, with currencies kept apart.”
  • “Summarize the supplier order I am viewing.”
  • “Which payment terms appear in the PDF of this invoice?”

Ctrl+Enter or Cmd+Enter sends the message; Enter alone adds a new line. While an answer is written, you can follow its progress or stop it.

Talk about the record on screen

On a supported record, choose Use this record, check its label, then ask your question. The choice applies to that question only.

Help using Dolibarr

Ask for example “How do I create a quote?” or “Where can I find my customer invoices?”. The guided paths cover third parties, customer invoices, quotes, customer orders, supplier orders and invoices, products and services. The assistant gives the steps and the links; you fill in and submit the form yourself. A creation form is offered only if you have the required permissions. Validation, sending, payments and deletion are not part of these paths.

Read and check answers

  • Answers link to the source documents. Read the sources and the stated scope before reusing figures.
  • A paginated list or a pivot table covers the data actually read, not necessarily every document.
  • Currencies are kept apart; there is no implicit conversion.
  • Fields you are not allowed to see, or whose rule is not supported, stay unavailable.
  • The text of a PDF attached to a document you can access may add information. The assistant may read it on its own when the question needs it.

AI answers must be checked. They do not replace the source documents or an accounting review. A scanned PDF without text is not read, because no OCR is performed. The assistant advises and calculates; it does not create or change business documents.

Conversation history

The history lets you find and continue your conversations. The + button starts a new conversation, without the previous one. Archiving a conversation removes it for good from your personal access; the global administrator keeps it in the administrator view until it is deleted.

The administrator sets how long conversations are kept; the period is shown at the start of each new conversation. Without a set period, conversations are kept until an administrator deletes them. Older conversations keep the information received at the time, even after permissions are removed.

Evaluation by the judge

The global administrator can have a conversation evaluated by the judge, by hand. The judge scores information, sources and calculations from 0 to 5, and writes a dated report. It points out errors and possible improvements without changing the conversations or the data. A score does not replace an accounting check of the source documents.

Data, privacy and security

This section summarizes how the module works in your installation. It does not cover this website, whose data handling is described on the Privacy page.

You stay the data controller. DoliAI Assistant runs inside your Dolibarr installation; the publisher receives no data from it. The module contains no telemetry and does not contact any server of the publisher. It sends requests only to the AI providers configured for the chat and the judge.

What is sent to the provider

  • the question and the earlier messages of the same conversation;
  • the Dolibarr data read to answer, within the user’s permissions at the time of the question;
  • the user’s first name and last name, as set in their Dolibarr profile;
  • the user’s gender, unless the administrator unticks Send the user’s gender to the provider;
  • the base address of your installation, to build links, and the current date.

The user’s login, email address and internal user ID are not sent. During an evaluation, the judge provider receives the conversation and the data read for it.

Attached PDF files

The assistant can read the PDF files attached to quotes, orders, customer invoices, supplier orders and supplier invoices. Only the extracted text is sent, never the file. Scans, images, handwriting and password-protected PDF files are not read. Default limits: 2 MiB per file, 200 pages and 120,000 bytes of extracted text; beyond that, none of the PDF’s text is sent.

What is never done

  • The assistant does not create, change or delete any Dolibarr record. Its reads run in a read-only transaction, and it never runs SQL written by the model.
  • Extra fields of type password are never read, nor those whose name or label looks like a password, secret, API key, token, IBAN, BIC, RIB or bank account.

Storage and retention

The module creates no business tables; its settings are Dolibarr constants. Conversations, evidence (data read to answer), judge reports and the budget ledger are private files in the Dolibarr documents directory, with permissions 0700 on folders and 0600 on files.

By default, data is kept without a time limit and the setup page shows a warning. The Privacy and retention card sets two periods in days (0 = unlimited): one for inactive conversations, one for tool results and judge reports. The check runs at most once a day during normal use. For a site with little use, enable the scheduled job DoliAI Assistant: apply the retention period, which is disabled by default. The global administrator can also delete old conversations by hand, after a preview.

Each new conversation shows an information notice: the provider host (and the judge host if separate) and the retention period. The module does not record that it was read; if your policy requires recorded consent, collect it outside the module. Deletion does not reach your external backups.

Checklist

  1. Choose a provider whose terms match your confidentiality needs, and sign a data processing agreement with it if needed.
  2. Add DoliAI Assistant to your record of processing activities: purpose, data sent, provider, retention period.
  3. Set the two retention periods.
  4. Decide whether the user’s gender is sent.
  5. Grant chat access only to the users who need it.
  6. Align your backups with your retention period.

Upgrade

Back up the module, its configuration and its private storage, then replace the files with the new package. If the hook declaration has changed, disable then enable the module again.

From a pre-release version (before 1.0.0), disable then enable the module once after the upgrade. The module then takes its official ID; the chat access permission already granted to users and groups is carried over automatically.

FAQ and troubleshooting

Does the module work with Multicompany?

No. Only the main entity is served. From another entity, activation is refused with a message, and the module pages answer “access forbidden”.

The answer appears in one block instead of progressively

An intermediary (CDN, web application firewall, HAProxy, Apache mod_proxy with mod_deflate) probably holds the stream until the end. The answer stays correct and saved. Turn off buffering and compression for /custom/dolibarrai/ajax/chat.php, and keep a proxy read timeout of at least 30 seconds. Apache with mod_php, nginx with PHP-FPM, and Apache behind an nginx reverse proxy were tested.

My question stays waiting

Each answer uses one PHP process. By default, one user runs at most 2 generations at a time and the site at most 5. Beyond that, the browser retries on its own for at most 5 minutes, then you can try again. The administrator can adjust the DOLIBARRAI_MAX_USER_GENERATIONS and DOLIBARRAI_MAX_GENERATIONS constants (Setup → Other Setup, from 1 to 64), keeping the site limit well below the number of available PHP processes.

Does closing the tab stop the answer?

No. Closing the tab or cutting the stream does not stop the generation: it ends on the server. To stop it, use the stop action while the answer is written.

An unclear error occurred

Check the status of the conversation before trying again. There is no automatic new call to the provider: a retry is always an explicit action and may use budget.

HTTPS certificate error

Fix the certificate chain with your host, or set an internal certificate authority in the setup. Verification cannot be turned off from the interface alone: for a short diagnosis, the server administrator must first add define('DOLIBARRAI_ALLOW_INSECURE_TLS', true); to conf/conf.php. A red banner then shows this mode, which exposes the API key and the exchanges to interception. Turn verification back on afterwards and remove the constant.

The assistant does not read a PDF

Scans without text, images, handwriting and password-protected PDF files are not read. A PDF over the limits (2 MiB, 200 pages, 120,000 bytes of text) is not sent.

The retention scheduled job does not exist

On an existing installation, disable then enable the module to create it in the Scheduled jobs module.

Support

To report a problem, use the contact form. Give your Dolibarr, PHP and module versions, the steps you followed and the error message. Never send an API key or confidential data.

See also the DoliAI Assistant overview and the changelog.