HCMS schemas
[]
Introduction
Schemas play a crucial role in the HCMS Client architecture. They help to map data structures intended for the Client with the existing data structures in the censhare system the Client is using. Here you can read more about HCMS schemas.
All critical schemas are already provided with the source code. They are automatically deployed to HCMS on runtime.
Schema handling
During build
During build, schemas are copied from their source directories to a single output directory, also created during build.
On runtime (deployment)
During deployment, the location of the unified schema directory is read from the configuration file (config.json), property "schemas": {"dir": }.
Please be aware that, on this step, schemas are slightly modified according to the provided HCMS Client configuration.
Schema modifications on runtime
Validation hooks
Some schemas have validation hooks. In that case, the URLs in those hooks are automatically patched to use the Node.js backend - the middleware - on the configured domain. Examples are image or person.
Setting initial values
Some schemas allow initial values (e.g., cs:internal). In that case, those values are automatically set to the configured security domain and initial workflow, if there is any.
Replacing placeholders
In complex permission rules (cs:permissions), the query property typically contains a special syntax expression to allow replacing it with hardcoded values from the portal definition. I.e., the <portal.id> is replaced by the portal id. An example can be found in the user_stats_dail schema: the (!portal)|(portal="<portal.id>") is actually deployed with the real portal id.
Automatic deployment of schema changes
From time to time, all schemas undergo the validation and get re-deployed if any changes have been detected.
Running application outside of the Docker image
If you want to run the application without building a Docker image, schemas won't be put into a single output directory, but will remain spread across all sources. However, in this case, you can specify the output directory manually, for debugging purposes.
You will need to create the config.json manually and not from the config.standalone.json file, but from the /backend/config.local.json instead, and specify the correct path in the property "schemas": {"dir": }.
Source directories
Where default schemas live
Backend modules directories
The core module directory contains schemas that store portal configuration, but not the ones actually available to the frontend, for security reasons.
The user management module directory contains such schemas as account (user accounts with authentication data), terms (license terms) and permission_group (user groups). None of those is actually ever accessible to the frontend as well. To represent user data, the frontend uses the person schema which is similar to account, but does not contain any authorization data.
The frontend core module directory contains most of the other out-of-the-box schemas.
Where to place new schemas
All schemas for the module should be placed in the schemas directory of that module.
Schema naming
Please pay attention to the following rules if you want to customize existing or create your own schemas.
-schema.json
Files that don't end with -schema.json are silently ignored, i.e., no warning will be shown that the schema could not be deployed.
Numbering
The schemas are always deployed separately, in the alphabetical order of the filenames. For this reason, it is important that the first component of the name is a number that correctly places the schema after all its dependencies.
Troubleshooting
Name conflict during build
If schema files located in different source repositories have the same name, there is no rule which file is actually used and which is discarded. Therefore make sure that there are no duplicate filenames.
Schemas directory missing in the config
If the "schemas": {"dir": } property is missing in the configuration, no schemas will be deployed; this might be useful when doing local debugging.
Changes done to schemas
Schemas are re-deployed from time to time. Hence, when you test your schema changes by deploying them manually through the HCMS REST API, these changes will be eventually rolled back by the next automated deployment.