An IDM-as-code tree is the driver set as files. bin/idm import,
import-project, import-ldif, and import-live write it. Git is the
history. The vault is where you deploy it.
This page is the plain-language map. The file-format contract (canonical XML, package-stamp attributes, round-trip) is model.md.
Names below are fictional. A real driver is whatever driverset.xml lists.
These live in the client directory, next to tree/, not inside it.
| Path | Committed? | What it is |
|---|---|---|
environments.properties |
No | Vault URL, bind DN, tier, driver-set DN, where the password comes from. One prefix per environment (stg., prd.). |
secrets-<env>.properties |
No | Shim passwords, Remote Loader passwords, named passwords. The tool reads them at deploy and never prints them. |
cases/ |
Yes | Simulator cases. simulate --cases cases/ runs them. |
deploy-log/<env>.jsonl |
Yes | One JSON line per deploy or driver operation. The production gate reads it. |
deploy-snapshots/<env>/ |
No | LDIF (and cache XDS) taken before a write. vault.rollback --snapshot restores an LDIF. Keep it out of git and out of chat. |
catalog/ |
Yes | Package jars you fetched or built. Optional. |
A redacted environments file and secrets file are in examples/.
tree/
driverset.xml
config-values.xml
.gitattributes
.package-baseline/
library/
library.xml
<name>.policy.xml
<name>.js
<name>.mapping-table.xml
<name>.gcv.xml
drivers/
AD Driver/
driver.xml
driver-filter.xml
config-values.xml
shim-config-info.xml
engine-control-values.xml
icon.gif
<name>.policy.xml
subscriber/
publisher/
entitlements/
provisioning/
The driver-set manifest: the set's name and DN, and one <driver> per driver
pointing at drivers/<name>. This is the table of contents. Operations rewrite
it when you add or remove a driver. Do not edit it by hand.
Global configuration values for the whole driver set. A driver can override
the same name in its own config-values.xml. query tree/ gcvs "<driver>"
shows the value that wins and where it is defined.
Only on a driver set served by several servers: the never-sync settings
(config-values.xml, shim-config-info.xml, engine-control-values.xml)
that this server holds differently from the primary's, one directory per
server; driver.xml lists them under <server dn>, whose shim-auth-server
and shim-auth-id attributes carry those two settings when the server holds
them differently. driverset.xml records the set's server list. See vault-deploy.md, "Several
servers".
Values that differ per stage — one file per environment, key = value
lines for GCVs, shim parameters, engine control values and the driver's
connection settings (drivers/<driver>.gcv.<name>, .ecv.<name>,
.shim-auth-server, .shim-auth-id,
drivers/<driver>.shim.<name>, driverset.gcv.<name>). The tree's own
files keep the base value; a deploy to that environment applies its file. See
getting-started.md §3.1.
What else differs per environment goes in the same file (existing-environments.md):
drivers/<driver>.name = <name>: that environment's vault calls the driver something else; compare, plan and deploy use that name, an import maps it back.servers.<tree server's name> = <that environment's server's DN>: one line per server of the tree, several onto one where the environment has fewer;servers.<its server's name>.prefer = <tree server's name>picks whose per-server settings a shared server takes. Required for every environment but the base: no two environments share a server.drivers/<driver>.job.<job>.schedule(empty = none),.disabled,.trace-level,.trace-file,.trace-size-limit, anddriverset.job.<job>.…: a job's schedule, state and trace.
Differences between two environments accepted as they are: each entry names
the other environment, the object's path, a fingerprint of the change, the
decision (intended or later), a note, who and when. A comparison leaves an
entry's difference out while the fingerprint matches, and shows it again once
the object changes. Written by known.accept / known.forget.
Only in a project kept per environment, as the target of another project
(promotion.md): <source>.properties maps the source's driver
names and servers to this tree's, <source>.known.json holds differences
accepted as they are, and <source>.json is the promotion record, which says
which side changed each object since it was last promoted. Written by
promote.pair, promote.apply, promote.accept and promote.forget; the map
is yours.
Policies, ECMAScript, mapping tables, and GCV objects shared by more than one
driver. library.xml lists them. A driver uses a library object by linking
it (policy.link); the link is recorded in that driver's driver.xml, and
the file stays in library/.
That driver's manifest: shim class, authentication server and id (not the
password), which environments get it (environments="QA, PROD", absent = every
environment) and which it is planned for but not promoted to yet
(planned="PROD"), which config files exist, every policy and resource, the
entitlements, and the linkage — which object runs in which policy set, in
which order. The linkage is what Designer's policy flow shows.
query tree/ chain "<driver>" sub prints the subscriber order.
query tree/ fishbone "<driver>" prints the same flow as the VS Code viewer.
subscriber/ is Identity Vault → application. publisher/ is application →
Identity Vault. Policies that belong to the driver as a whole (schema map,
input and output transforms) sit next to driver.xml, not in those folders.
On disk the file is <name>.policy.xml, <name>.js, or
<name>.mapping-table.xml. Commands address the object by artifact path,
which is the name without the extension:
drivers/AD Driver/subscriber/ACME-sub-ctp-NormalizeTitle
library/lib-Shared
show, refs, package.diff, rule.add, and policy.link all use that
path. Quote it when the driver name contains spaces.
| File | What it is |
|---|---|
driver-filter.xml |
Which classes and attributes synchronize, per channel |
shim-config-info.xml |
Shim parameters (the driver's options page) |
engine-control-values.xml |
Engine control values for this driver |
config-values.xml |
This driver's GCVs |
icon.gif (or .png) |
The icon Designer and iManager show. Opaque bytes. A tree without one leaves the vault's icon alone |
Passwords are not in these files. They live in secrets-<env>.properties.
The <job>, <rbe-policy> and <template> entries of driverset.xml (and a
driver's <job> entries) carry the same two attributes as a driver:
environments (absent = every environment) and planned. Compare and deploy
to an environment leave out what it doesn't get. environments.set sets them,
several objects at once.
<name>.xml for each DirXML-Job on the driver: the job's configuration document
(<job-aggregation>). The servers it runs on, its scopes and its trace settings are
on the manifest's <job> entry. The driver set's own jobs (a statistics job) are
jobs/<name>.xml beside driverset.xml, listed in it the same way. Read from the
vault, an LDIF, a Designer project (Idm:Jobs) and an export (<jobs>); not deployed
yet (docs/console-gaps.md §1, phase J2).
Beside driverset.xml: <name>.xml for each role-based entitlement policy of the set's
Entitlements Service driver (DirXML-SharedProfile in the set's one DirXML-SharedProfileSet
container, cn=Entitlement Policies unless driverset.xml's meta rbe.container says
otherwise). One <rbe-policy name priority> document holds the description, the membership
query (<member-query>, an LDAP URL), the identity it runs as, static and excluded members,
the entitlement refs it grants (<entitlement-ref>, the vault's dn#0#<ref>…</ref> values),
the editor's criteria and Designer's display document. Priorities must run 0, 1, 2 … Read from
the vault, an LDIF, a Designer project and an export; deployed (docs/console-gaps.md §9).
Beside driverset.xml: <name>.xml for each e-mail notification template of the vault's
notification collection (notfMergeTemplate under cn=Default Notification Collection,cn=Security,
or the collection driverset.xml's meta templates.collection names): the body document; the
subject and the package stamps are on the manifest's <template> entry. They are the vault's,
not the driver set's, but they travel with the tree: read live and from an LDIF, diffed and
deployed (docs/console-gaps.md §12). Most come from packages and carry their stamps.
<name>.xml for each DirXML-Entitlement on the driver. Workflows grant
them; the Identity Applications read the definition from the vault. They
deploy with vault.deploy and do not restart the driver.
Present on a User Application driver that has an AppConfig container.
provisioning/
provisioning.xml
forms/request/<name>.form.json
forms/approval/<name>.form.json
forms/template/<name>.form.json
prds/<name>/definition.xml
prds/<name>/request.xml
objects/... roles, resources, entities, navigation, …
form.list and prd.list read this tree. prd.flow walks the workflow
inside a PRD. JSON forms are pretty-printed here so git diffs are readable;
the deployer writes the compact document the vault expects.
The content of a packaged policy, form, PRD, or other object before the
first customization. The object in drivers/ or library/ is your current
copy and is marked customized. package.diff tree/ <artifact-path> shows the
difference. Do not delete the baseline if you want a later package upgrade to
know what you overrode.
Import writes this once:
# IDM-as-code: content is byte-exact vault data; never normalize line endings
* -text
Keep it. Vault content is bytes. If git converts a CRLF inside an ECMAScript
resource, vault.diff will report a change you did not make.
| You want to | Do this |
|---|---|
| Change a rule's XML | Edit the .policy.xml file, or rule.add / artifact.set-content, then validate |
| Add, link, rename, or reorder a policy | policy.add, policy.link, policy.reorder, artifact.rename |
| Change a GCV, the filter, the schema map, a mapping-table row | gcv.set, filter.set-attr, schema-map.set, mapping-table.set-row |
| Add a driver | driver.add |
| Customize a packaged object | Edit it through an operation. The tool marks it customized |
| Change which drivers exist in the set | An operation. Not a hand-edit of driverset.xml |