Appearance
Upgrading Datafor
About 2367 wordsAbout 8 min
2026-10-10
An existing installation is upgraded in place with an update package, a .jar file such as datafor-updater.jar. The package replaces program files and some configuration files, so plan the upgrade as a short maintenance window: back up, apply the package, put your own settings back, then check.
1. Before you upgrade
- Read the upgrade notes of the release, for example 10.02 Upgrade notes. They list behavior changes and steps that apply only to that release.
- Create a backup with Content and settings selected and download it to another computer (see Backup and Restore). If the repository runs on your own PostgreSQL server (Repository Separation), back up those databases with your own tools as well.
- Copy two AI Agent files to a safe place:
bi-server/ai-agent/instance-secrets.envandbi-server/ai-agent/.env. No Datafor backup contains them.instance-secrets.envholds the key that encrypts the LLM API keys stored in the database; without it a restored system cannot read them..envholds your AI Agent settings, such asDATABASE_URL, theMCP_*keys andAI_AGENT_DISPATCH_WORKERS. - Write down what you changed in the files the package replaces (section 3): the Java heap in the start script, database connections, passwords and ports in
server.xml, and any other file underpentaho-solutions/systemyou edited by hand. - Have all components of the update package. Install them together: several features need matching browser and server parts, and an older engine does not work with a newer plugin.
2. Apply the update package
Datafor applies update packages when it starts: start-server runs every .jar file in bi-server/update before it starts the server, then renames the file with a time stamp (for example datafor-updater_20260918171548) so that it is not applied again.
Linux (installation in /opt/bi-server):
Copy the package into
/opt/bi-server/updateand give it tobiadmin:chown biadmin:biadmin /opt/bi-server/update/datafor-updater.jar.Switch to
biadminwithsu - biadmin. Stop Datafor, which also stops the AI Agent:cd /opt/bi-server && ./stop-server.shStart Datafor with
./start-server.shin/opt/bi-server. It applies the package, then starts the database, the AI Agent and the web server.
Windows:
- Copy the package into
bi-server\update. - Run
stop-server.bat. - Run
start-server.bat. It applies the package, then starts the database, the AI Agent and the web server.
To apply the package without starting the server, run update.bat in bi-server. It stops at the first package that fails and prints Update failed, keeping "…\update" for inspection.
Docker: pulling a newer image does not update an existing installation, because the installation lives in the volume. Copy the package into the container and restart it:
docker cp datafor-updater.jar datafor-ee:/opt/bi-server/update/
docker exec -u root datafor-ee chown biadmin:biadmin /opt/bi-server/update/datafor-updater.jar
docker exec datafor-ee /opt/bi-server/stop-server.sh
docker restart datafor-eeSee Deploying Datafor Using Docker for the container itself.
3. Reapply your own settings
The package replaces start-server.*, set-env.* and tomcat/conf/server.xml in full, and it can replace configuration files under pentaho-solutions/system as well, such as pentaho.xml, applicationContext-spring-security*.xml, the plugins' settings.xml files and datafor/mondrian.properties. Check every file you changed by hand.
The replaced files are kept in bi-server/update/backup<time stamp>/, in the same folder structure as in bi-server. change-list.md in that folder lists the configuration files whose content changed.
| What you may have changed | File | After the upgrade |
|---|---|---|
Java heap (-Xms/-Xmx in CATALINA_OPTS) | start-server.sh or start-server.bat | Set the values again. |
Repository connections, passwords, ports, RemoteIpValve | tomcat/conf/server.xml | Copy your <Resource>, <Connector> and <Valve> settings into the new file. Without this, a separated repository is replaced by the built-in database again, and a proxy setup loses its forwarded-header handling. |
| Connection pool defaults, engine properties | pentaho-solutions/system/pentaho.xml, pentaho-solutions/system/datafor/mondrian.properties | Set your values again. |
| AI Agent shared secret, AI Agent on another server | -Ddatafor.agent.secret in CATALINA_OPTS in start-server.sh or start-server.bat | Add the option again, or move the value to the DATAFOR_AGENT_SECRET environment variable, which updates do not touch. A co-located AI Agent needs nothing: Datafor reads the value from ai-agent/instance-secrets.env. Since 10.01 <agent-secret> in the modeler's settings.xml is ignored (AI Agent Shared Secret). |
| AI Agent settings | ai-agent/.env | The package can change this file (it then appears in change-list.md). Compare it with your copy and restore your settings. |
Stop Datafor, copy your values into the new files rather than copying the old files back (a new file can contain new entries), and start Datafor again.
4. Steps for 10.02
When you upgrade to 10.02, also do the following. If you come from an earlier version, do the steps for 10.01 (section 5) and 10.00 (section 6) as well. The full list of changes is in the 10.02 Upgrade notes.
- Install the new plugins with the others. Subscriptions and alerts (
datafor-notify) and IM platforms (datafor-im) are new; the audit log (datafor-audit) is rebuilt. Paginated report subscriptions send nothing withoutdatafor-notify. - Render service. If the AI Agent you upgrade has no render service yet, copy the
ai-agent-renderprogram, its start scripts,render-runtime-*.propertiesand the wholebrowsersfolder from the new package. Without them, subscriptions go out without screenshots and PDF. On Linux, install the libraries and fonts listed in Render service. - Your own
applicationContext-spring-security.xml. If you maintain it yourself, replacewecomFilterwithimFilterand add the three anonymous rules listed in the upgrade notes; otherwise Datafor does not start. - WeCom. The old WeCom integration is removed and its settings are not carried over. Register the WeCom app again under Settings › Notifications › IM platforms and set its home page to the address shown there. See IM Platforms.
- Audit log. Where audit settings were never saved, auditing is on after the upgrade, with 180 days of retention. Check Settings › Operations › Audit log. See Audit Log.
- Time zone. Set Platform time zone in Settings › General › System configuration of the default tenant if the server's zone is not your business zone. Subscription and alert schedules, including those of existing paginated report subscriptions, use it. Tenants in other zones can set their own System time zone on the same page.
- Tenants. On Settings › Operations › Multi-tenancy, run Repair permissions on every existing tenant and on template0, and set each tenant's AI User Limit with Change Quotas (it starts at 0, so nobody new can get the AI Agent). Embedding into a tenant needs an embed token configuration in that tenant; a default-tenant configuration with
?tenantId=no longer signs in there. See Upgrading tenants to 10.02. - Personal tokens stop working after 90 days without use, counted from the last use already recorded. Users whose AI clients stop connecting create a new token or click Allow again. See Connect AI Clients.
- File datasets. Seeing the uploads, original files and table previews of a file dataset now needs Edit on it. Give Edit to the people who maintain a dataset's files; Read still lets people build models and reports on it.
- Mapbox maps. Click Clear geocoding cache on the Mapbox card under Settings › Data › Maps. See GIS Map Settings.
- Cookies. Set
session-expired-dialogtofalseinpentaho-solutions/system/pentaho.xmlso that thesession-expiryandserver-timecookies are no longer sent.
5. Steps for 10.01
When you upgrade to 10.01, also do the following. If you come from a version before 10.00, do the steps for 10.00 (section 6) as well. The full list of changes is in the 10.01 Upgrade notes.
- Install the modeler plugin and the AI Agent together. 10.01 moves the AI Agent shared secret out of the modeler's
settings.xml, and a 10.00 modeler with a 10.01 AI Agent (or the other way round) loses it. - AI Agent on another server. If you set
<agent-secret>insettings.xmlby hand, 10.01 ignores it: set the same value as theDATAFOR_AGENT_SECRETenvironment variable of the Datafor server and restart Datafor. A co-located AI Agent needs nothing. See Upgrading from 10.00. - Rebuild lineage data. Sign in as an administrator, open Data › Lineage and run Rebuild lineage data once, so that reports saved before the upgrade appear in usage lists and in the impact lists of delete and change confirmations. See The Lineage Page.
- Paginated reports are a separate plugin (
datafor-pagereport). Install it with the other components if you want New › Paginated report. - Reports with relative component filters. A filter with Include reference time now covers exactly N units, one day less than before. Open the reports whose numbers are checked against other systems and compare. See Relative component filters.
- Date components with fixed default dates that were saved in another time zone open on the author's dates now. Save such a report once to store the dates in the new format.
- List filters on a time field that defaulted to Last now default to Latest period: the most recent period that has data, no longer the last member of the date table. Check reports that relied on the old behavior to show a future month.
- Action buttons bound to a model field keep working as Data button (legacy). Nothing to do; see Action button if you want to convert them.
6. Steps for 10.00
When you upgrade to 10.00, also do the following. The full list of changes is in the 10.00 Upgrade notes.
- AI Agent shared secret. Datafor gives LLM API keys to the AI Agent only when both use the same secret. With the packaged layout the AI Agent's launcher creates it and Datafor reads it from
ai-agent/instance-secrets.env. If the AI Agent runs on another server, give Datafor the same value. See AI Agent Shared Secret. - Model Resolution stage. Open AI Agent › LLM › Assignments. The new stage runs on the Workflow Routing profile until it has its own assignment; click Save to record it, or choose another profile first. If Workflow Routing is unassigned too, assign both. See LLM Configuration.
- Knowledge indexes. Indexes are now built in the background when a model is saved, copied or imported. If you schedule index builds yourself, turn off Auto-build knowledge index at the top of Settings › AI Agent › Knowledge indexes. Let each model's index build or sync once (save the model, run Prep data for AI, or wait for its schedule) so that members of numeric-keyed fields are recognized. See Preparing Data for AI.
- Metric bindings. Run Compare all again on the Metric bindings tab of each model that has bindings. Verdicts stored under the old rules stay until then, and users see them as notes in answers. See Model Diagnostics.
- AI clients. Users of Claude Desktop uninstall the old extension and install the new datafor.mcpb (also in
bi-server/ai-agent/claude-extension/), which takes only a personal token. Clients that were set up with user name and password headers stop working unlessMCP_PASSWORD_SESSION_AUTH_ENABLED=trueis set; enable personal tokens and let users create one under My account › Personal tokens. See Connect AI Clients. - Aggregation tables are off by default. If your models use them, turn on UseAggregates and ReadAggregates in Settings › Data › Query engine (see Use Aggregation Tables).
- Permissions. Deleting content needs Delete or Full control, and publishing a model or changing its data source needs Read on the data source. Check that users you disabled are still disabled. See Managing Analysis Models.
- Conversations. A follow-up in a conversation started before the upgrade may not continue a hierarchy from the earlier turn; start New Chat.
7. Check the upgrade
- Check the server log (
tomcat/logs/catalina.outon Linux, the server console on Windows) for errors during the update and start. - Sign in as an administrator. Open a few reports and models and check that they show data. If your content is missing and only the sample content appears, Datafor is connected to the built-in database: reapply
server.xml(section 3). - Run
curl -i http://127.0.0.1:28081/ai/healthon the server.HTTP/1.1 200means the AI Agent is ready; a503body names the cause. Runcurl http://127.0.0.1:38082/healthfor the render service; it answers"ok":true. Then send yourself a test of a dashboard subscription (Subscribe › Send me a test) and check that it has a screenshot. - Open AI Agent › LLM and check that Assignments shows 16/16 assigned.
- If Dashboard Review, Model Brief or Question Suggestions has no assignment of its own, try that feature as a user who is not an administrator. A model error there points to the shared secret.
- Behind Nginx, ask a question in the AI Assistant and check that the progress title moves through several stages (Deploying Datafor Behind Nginx).
- Open Settings › AI Agent › Knowledge indexes and check that the builds succeed.
- Create a new backup.