1. Rules Packages

A rules package is a ZIP archive that defines what can be described in ELZA and how: item types and their specifications, rule sets with their Drools rules, structured types, output types and templates, bulk actions and entity types. ELZA ships two packages:

CZ_BASE - entity types, entity parts and their item types (the CAM rule set for archival entities), shared code lists such as languages;
ZP2015 - the Czech archival description rules (Základní pravidla pro zpracování archiválií), rule set ZP2015.

Packages are imported in Administration > Package management, or automatically at startup from the dpkg/ subdirectory of the working directory: the imported packages, and those the configuration key elza.packages.enabled lists, with their dependencies (see the administration guide).

1.1. Structure of a package

The archive contains the package directory itself, without a parent directory. Files at the root describe the package and its global definitions; each rule set has a directory under rul_rule_set/.

package.xml                     code, name, version, dependencies
rul_item_type.xml               item types
rul_item_spec.xml               specifications and their item types
rul_rule_set.xml                rule sets owned by the package
ap_type.xml                     entity classes
rul_part_type.xml               part types of entities
rul_structure_type.xml          structured types (and their definitions,
rul_structure_definition.xml    extensions and scripts)
ui_setting.xml                  package-level UI settings
rul_rule_set/<RULE_SET>/
    rul_arrangement_rule.xml    rules of the rule set
    rul_arrangement_extension.xml   optional extensions of the rule set
    rul_extension_rule.xml      rules of those extensions
    rul_entity_rule.xml         rules and scripts of an entity rule set
    rul_ap_type.xml             entity classes of an entity rule set
    rul_part_type.xml           part types of an entity rule set, in order
    rul_output_type.xml, rul_template.xml, rul_policy_type.xml,
    rul_package_actions.xml, ui_setting.xml, ...
    rules/                      Drools (.drl) and Groovy rule files
    bulk_actions/               bulk action definitions (.yaml)
    templates/                  output templates

Files that a package does not need may be left out. The elements of each file are described in Package Files.

1.2. package.xml

<package>
  <code>ZP2015</code>
  <name>Základní pravidla pro zpracování archiválií</name>
  <version>344</version>
  <description>...</description>
  <dependencies>
    <dependency code="CZ_BASE" min-version="88"/>
  </dependencies>
</package>

code: Unique code of the package. It is also used as the prefix of the codes the package defines (see Codes).
version: Integer. Importing a package whose version is already installed is refused, so every change of the package content needs a higher version, otherwise it never reaches an installation that already has the package.
dependencies: Packages this package builds on, with the minimal installed version. The import is refused when a dependency is missing or older. Packages are imported in dependency order at startup, and a package cannot be deleted while another installed package depends on it.

1.3. Codes

The codes of item types and specifications are unique across all installed packages, and a package cannot redefine an item type of another package. Codes are referenced by rule files, templates, bulk actions and exported data, so they are permanent: once data exist, a code cannot be renamed by a new package version.

Every package therefore uses its own code prefix (ZP2015_, SRD_, ADT_), including packages that customize another package (see Customizing a Rule Set).

1.4. Base parts and items

A few part types and item types of archival entities are a shared base: the application has logic of its own for them, so every entity description framework uses them under these codes. They are declared by CZ_BASE; a framework either depends on CZ_BASE or declares the same codes itself, as ISAAR_CPF does (see Part types shared by packages and Item types shared by packages in Package Files). A framework adds its own part and item types next to them freely; only these codes carry built-in logic.

Code	What the application does with it
`PT_NAME`	Name. A new entity is created with a part of this type, and the preferred name of an entity has to be a part of this type (an entity whose preferred part is of another type is rejected). The search area names searches the names of these parts.
`PT_BODY`	Description. The display name of this part (`DISPLAY_NAME` from the `INDEX` rule) is the description of the entity in lists and in the export of entities.
`PT_CRE`, `PT_EXT`	Creation and extinction; sections of the export of entities.
`NM_MAIN`	Main part of a name: the search option only the main part of the name searches it; the name of a user created from an OAuth2 token is stored in it.
`NM_MINOR`	Minor part of a name; a column of the export of entities.
`CRE_DATE`, `EXT_DATE`	Dates of creation and extinction; the search filters by these dates read them.

Everything else the application shows or searches comes from the rules of the framework: the names of parts from its INDEX rules, the searched item fields and the indexes matched as a whole from its index-search setting (ui_setting.xml: index-search). The exchange with the CAM system and the import of the former party format work with the CAM codes only.

1.5. Rule sets and rules

A fund is described under exactly one rule set. The rule set decides which item types and specifications are offered on each unit of description, which of them are required, how new units of description are created and how the description is validated. These decisions are Drools rules, registered in rul_arrangement_rule.xml of the rule set directory:

<arrangement-rules>
    <arrangement-rule filename="AvailableItems.drl">
        <rule-type>ATTRIBUTE_TYPES</rule-type>
        <priority>100</priority>
    </arrangement-rule>
</arrangement-rules>

The rule types used for archival description:

ATTRIBUTE_TYPES: Which item types and specifications are possible, recommended, required or impossible on a unit of description, and whether they are repeatable.
CONFORMITY_INFO: Validation of a unit of description; reports missing items and errors.
CONFORMITY_IMPACT: Which other units of description must be validated again after a change.
NEW_LEVEL: The scenarios offered when a new unit of description is added.
ITEM_TYPE_FILTER: Additional item types belonging to the rule set (see Own item types).

The rule set’s own item type filter is named in rul_rule_set.xml (<rule-item-type-filter>). It decides which item types the rule set uses at all: the grid columns, the search filters, the add-item dialog and the dictionary offered to the AI assistant are built from it.

Rules of one type run in the order of their priority, each file in a session of its own, so a later file sees and may change the decisions of the earlier ones. The ZP2015 and CZ_BASE rules use priority 100.

At the start of the ATTRIBUTE_TYPES evaluation every item type and every specification is impossible; a rule has to allow it.

The specifications a rule can allow are those the rule set sees: the specifications assigned to the item type by packages related to the package of the rule set - the package itself, the packages it depends on and the packages depending on it (addons), both transitively. A specification that only an unrelated package assigns to a shared item type is not offered under the rule set, even by a rule allowing every specification of the item type (ItemSpec() from $it.specs). The same holds for the entity rules of an entity rule set. See “Specifications shared by packages” in the chapter on package files.

1.6. Order of specifications

The specifications of an item type are offered in this order:

by package, in dependency order: the specifications of a package come after those of the packages it depends on;
within a package, in the order of the <item-spec> elements in rul_item_spec.xml;
a specification with view-after on its <item-type-assign> is placed directly after the named specification of the same item type (see Position of the specification).

The order is recomputed for all item types whenever any package is imported.