Install-editable values

Building a connector, step 7 (LDAP track, 3 of 4). Previous: Attributes, membership and writes.

Two installs of the same LDAP connector rarely search the same OUs or read the same attributes. An install-editable value lets each install set its own: you give a starting value, called the seed, and each install gets its own copy to change. Make a value install-editable when sites legitimately differ on it and it does not identify anything.

What can be install-editable

Install-editable	Always fixed in the definition
pageSize	engine, description, icon
An entity's bases, objectClasses, filter and attributes	Entity keys and name
write.base and write.dn	The identifier attribute and its type, and rdnAttribute
membership.nested	scope and write.delete
A value lifecycle's attribute, enabledValue and disabledValue	The membership attribute, direction and writable
	The lifecycle's form, and every field of a flag lifecycle
	password, incremental, custom_ops and handlers

A fixed field given an expression is refused, usually with "this value is never install-editable, so it must be a literal".

Declare one

An install-editable value takes two changes to the definition.

1. Declare an install field under config.properties: a JSON Schema whose type matches the field it feeds, with a title, a description, and the seed as its default.
2. In the field itself, write { "$oxl": "config.<name>" } instead of a literal.

{
  "engine": 1,
  "config": {
    "properties": {
      "userBases": {
        "type": "array",
        "items": { "type": "string" },
        "title": "Account search bases",
        "description": "The OUs whose accounts this install syncs, as whole DNs, for example ou=people,dc=northwind,dc=example."
      },
      "userObjectClasses": {
        "type": "array",
        "items": { "type": "string" },
        "title": "Account object classes",
        "default": ["inetOrgPerson"]
      }
    }
  },
  "entities": {
    "user": {
      "bases": { "$oxl": "config.userBases" },
      "objectClasses": { "$oxl": "config.userObjectClasses" },
      "identifier": { "attribute": "entryUUID" },
      "rdnAttribute": "uid"
    }
  }
}

The expression must be exactly config.<name>, naming a declared field. Owlie refuses any other expression, an undeclared name, and a field whose type does not match:

Field	Declared type
bases, objectClasses	array of strings
attributes	object, keyed by attribute name as on the previous page
filter, write.base, write.dn, lifecycle values	string
pageSize	integer
membership.nested	boolean

The names url, baseDn and tls belong to every LDAP connector already and cannot be declared.

In the Connector Builder

On the Install values tab, What installs may edit has a switch for each value an install may edit, such as User search bases, User attributes or Nested groups. Turning one on moves the definition's current value into a new install field as its seed, named after the value (for example userBases), and points the definition at it. Turning it off makes the value a literal again. The Install values table below lists the install fields with their titles and descriptions. Set write.dn and a lookup entity's values in Raw JSON.

Seeds, and values with no seed

Seed each value with what a typical directory uses. Two cases are special:

• No seed. A search base list with no sensible default can have no default. The install form then requires it. Only bases may be declared without a seed; any other install-editable field without one fails with "has no value and no seed".
• An empty seed. A field seeded with "" is optional for installs. It is how an optional value says "none": an empty enabledValue makes enable remove the attribute, and an empty write.dn means no template.

What an install sees

When someone installs the connector, the install gets its own copy of every seeded value. The install form shows each field under your title and description, filled with its seed, and asks for each field that has none. From then on the copy belongs to the install. Each time an admin saves the install's configuration, Owlie derives the install's own entity schemas from its values, and refuses a save whose values do not derive.

An install's values pass the same checks as literals in the definition: DN and filter syntax, attribute and object class names, and the page size range. Some fields are also protected:

• The identifier attribute and the rdnAttribute are always read, even when an install's attribute list leaves them out.
• An account or group search base list left empty stops the connector: its configuration check reports that the search bases are not set. A lookup entity's empty list searches the whole base DN.

When you change a seed later

Because each install owns its copy, publishing a new seed never overwrites an install's value. When an install moves to a version whose seeds differ (Publish, install and upgrade):

• the install keeps its own value for every field it already had;
• each field whose seed changed appears on the integration in a notice, Owlie updated followed by the connector's name, showing the install's value beside the previous and new seed. An admin decides each field on its own: Use Owlie's value replaces the install's value, and Keep mine keeps it;
• a field new in that version starts at its seed, and a field the version no longer declares is dropped.

New installs start from the new seeds. Owlie does not treat a changed seed, or an attribute added to or dropped from a seeded attribute list, as a breaking change to the connector, because installs choose whether to take it.

Next: Overrides and PowerShell