Upgrade and dev → prod¶
Upgrading Artekis. Read the release notes first: every release opens with three yes/no lines: whether there is
a schema step (with its script), whether a playbook template's major version changed, and whether the configuration
format changed (Appendix B). When there is a schema step, your DBA applies the upgrade script first, then you
install the new .modl, minutes apart; the module requires an exact schema version match, so the old module idles in
between with the reason on Status. Then re-run the views-pack installer from the Status page: it replaces only its
own files and leaves yours alone. A module keeps the previous major version of each playbook template for one release;
a playbook pinned to a major the module no longer ships is refused with the needed version named on Status.
Upgrading from an older build. A gateway running an Artekis build from before the current 1.5.26 installs it as an
upgrade: the module id (com.artek.artekis) is unchanged, so the configuration is kept. 1.5.26 is numbered above every
earlier build, the retired 1.1.x included, so Config → Modules shows it as an upgrade. The module is signed with the Artek, LLC certificate (SHA-1
99e472815b3417abab93e1c744c76699c73375d2): the gateway asks to accept it once on install, and where the module is
registered in data/modules.json (a scripted install, section 3 step 1), re-derive its certFingerprint from the new
.modl, or the module quarantines on restart instead of loading. The license agreement names Artek, LLC as licensor
from 1.0.1, so its hash changed: licenseAgreementHash is 4274987724, unchanged in 1.2.0, 1.2.1, 1.2.2, 1.2.3, 1.2.4, 1.2.5, 1.3.0, 1.4.0, 1.5.0, 1.5.1, 1.5.2, 1.5.3, 1.5.4, 1.5.5, 1.5.6, 1.5.7, 1.5.8, 1.5.9, 1.5.10, 1.5.11, 1.5.12, 1.5.13, 1.5.14, 1.5.15, 1.5.16, 1.5.17, 1.5.18, 1.5.19, 1.5.20, 1.5.21, 1.5.22, 1.5.23, 1.5.24 and 1.5.25, 1.5.26 (1.0.0: 52611452). The schema is still v1, so a database on the frozen v1 DDL has no DDL step.
A database created by a build from before the v1 DDL was frozen may lack what the frozen file has:
artekis_run.kpis_json, artekis_run.answer_json, artekis_run.actor with its (actor, started_at) index,
artekis_feedback.run_id with finding_id nullable and a check that exactly one of the two is set, and on SQL Server
the five finding text columns (title, raise_confidence, cause_class, subject_path, candidate_id) as
NVARCHAR. The Status page's storage check reads the tables and the schema version, not the columns: compare against
GET /data/artekis/ddl and have the DBA add what is missing before installing. Then re-run the views-pack installer
from the Status page to get the views an older pack lacked.
What travels in a project export, and what does not. A Perspective project export carries your playbooks, the views pack and your Event Streams. Everything else moves by its own path, and must be in place on the target gateway before the project is imported:
| Resource | In a project export | Moves by |
|---|---|---|
| Playbook instances | yes | the export |
Views pack (Artekis/* views, its style classes, the artekisFinding session handler, the page routes, the Ask dock) |
yes | the export, or re-run the installer on the target |
| Event Streams (yours) | yes | the export |
settings, provider, policy and each context-model |
no: gateway configuration | copy config/resources/core/com.artek.artekis/ from the source gateway's data directory and trigger a config scan (POST /data/api/v1/scan/config), or re-enter them on the Artekis pages; before the project import |
| The model API key | no | never moves: entered in the target gateway's own Secret Provider; only the secret's name travels inside provider |
| The license key | no | activated per gateway |
| DDL and upgrade scripts | no | applied by the DBA, before the module or project that needs them |
The [Artekis] tag provider and its tags |
no | rebuilt by the module at runtime from the database |
| Image assets, gateway themes | : | the views use neither |
Customer dev → prod, in order: (1) the DBA applies the same-version DDL or upgrade script on prod's database; (2) move the Artekis gateway configuration and enter prod's own model key in prod's Secret Provider; (3) import the project. Collections are matched by collection id, which must be the same on both gateways.
Dangling references. An enabled playbook that reaches a gateway lacking a provider, its collections or the schema is inert and says so on Status; nothing fails to load:
| Reference | Missing on this gateway | Shows on |
|---|---|---|
| playbook → collection | that collection is skipped and the rest run; none left → the run is SKIPPED(no-collection) |
Status and the Playbooks view (warning) |
| context model → project | warning only | Status |
| settings → database connection | the module idles, as for missing tables | Status |
| provider → secret | FAILED(credential) per run |
Status and the Playbooks view |
Where a provider, the collections and the schema all exist on a gateway, Artekis was set up there on purpose: there is no further gate, so keep an unfinished playbook disabled on a project that is exported to production.