Aidbox configuration project

Aidbox configuration project refers to a set of configuration files used to set up an Aidbox instance

Aidbox is transitioning to the FHIR Schema engine. Existing zen and Entity/Attribute (EA) engines are deprecated and will be obsolete starting August 2025. July 2025 version will become LTS supporting zen and Entity/Attributes for 2 years.

Read full announcement Since the 2405 release, using Aidbox in FHIR schema validation engine is recommended, which is incompatible with zen or Entity/Attribute options.

Setup Aidbox with FHIR Schema validation engine

Aidbox configuration project is a directory containing configuration files written in Zen language. Don’t worry if you are not familiar with Zen yet — we’ll explain all the necessary details along the way. For now you can think of it as a simple syntax well-suited for specifying all sorts of configs.

With Aidbox configuration project, you can configure all the things you need for a functioning Aidbox instance, including API endpoints, authorization flows, FHIR IGs and more.

Once you set up your project for one Aidbox instance you can reuse it across multiple instances — they all will be configured in the exact same way. This feature is especially useful for testing purposes. Using a single configuration project, you can be sure that your CI pipeline has the same setup as your deployed instance.

Aidbox configuration project is sometimes referred to as Aidbox Project or just project. It should not be confused with Aidbox User Portal projects containing licenses.

Aidbox configuration project structure

Features supported by configuration projects

Enable IGsSeed v2https://github.com/HealthSamurai/documentation/blob/master/docs/deprecated/deprecated/zen-related/aidbox-zen-lang-project/broken-reference/README.md

Use Aidbox configuration project

Aidbox configuration project is simply a directory of config files. In order to use it with Aidbox you just need to tell the latter where it is located and how it can be accessed.

Currently Aidbox configuration projects are supported by self-hosted instances and Aidbox User Portal Sandbox instances. Support for AWS Marketplace installations is coming soon.

Configuration projects can be provided either as a git repository URL or as a local path. We recommend keeping your project in git as source control allows you to easily track changes, revert them or switch between branches.

Set up a configuration project

Setting up a self-hosted project is done by providing access to project files.

https://github.com/HealthSamurai/documentation/blob/master/docs/deprecated/deprecated/zen-related/aidbox-zen-lang-project/broken-reference/README.md

Production installation

A production installation is the same as a regular installation, except when your production environment has no access to the git repo containing your configuration project. For these cases Aidbox supports other methods of providing configuration projects.

Configuration projects for Sandbox instances on Aidbox user portal

1. Proceed to creating a new license

2. Select either a Standard or Development license type and Sandbox hosting

3. Choose which projects to enable in FHIR Server Configuration section.

Currently available projects include various FHIR IG zen packages and Aidbox SDC forms.

FHIR terminologies from IG packages are not loaded into the Sandbox database. This means they won’t be available for introspection. You can still use them for validation.

If you want to have them in the database, you need to configure projects for a local instance.

Configuration projects in AWS Marketplace Aidbox SaaS

Aidbox configuration projects will be supported on AWS Marketplace in upcoming releases.

Configuration projects in self-hosted instances

https://github.com/HealthSamurai/documentation/blob/master/docs/deprecated/deprecated/zen-related/aidbox-zen-lang-project/broken-reference/README.md

Examples

See examples of Aidbox configuration projects in our GitHub repository.

Common errors

Entrypoint 'smartbox.portal' not loaded.

{:message "No file for ns 'smartbox.portal", :missing-ns smartbox.portal, :ns smartbox.portal}

Meaning: Wrong zen source files path

Cloning into '/tmp/aidbox-project-git'...

remote: Repository not found.

fatal: repository 'https://github.com/Aidfdfdfbox/aidbox-project-samples.git/' not found

Meaning: Incorrect git repo url

error: pathspec 'git-project-unexist' did not match any file(s) known to git

Meaning: Incorrect checkout branch/commit