API

Many ECMAScript 6 features are available in scripts, including but not limited to:

Globals

In each script has the following additional global variables available:

Sandbox/Context

An object passed as first parameters to all functions. It has the following properties

  • viewer
  • log
  • ScriptVault
  • IDVault
  • config
  • formatDN(dn: string | DN): string - normalizes the given DN and returns a string
  • parseDN(dn: string | DN): DN - parses the given parameter to DN
  • escapeLDAPFilter(value: any): string - escapes the given value to be used in an LDAP filter; the following chars are escaped: *, (, ), \\, \\0 
    escapeLDAPFilter('star*') // => 'star\2A'

Viewer

The viewer represent the currently logged in user. It has the following properties:

  • entryDN: string - the normalized DN

  • $id: string - as configured in the users.id (defaults to entryUUID)

  • $type: string - usually 'user'

  • $name: string - as configured in the users.name (defaults to cn)

  • $description: string - as configured in the users.description (defaults to displayName or fullName)

  • $role: string - the karma role; one of guest, user, admin

  • has(dn: string | DN): boolean - determines if the viewer has this principal (dn, parent container, role or group)

  • is(dnOrKarmaRole | DN): boolean - determines if the viewer has at least this karma role (admin, user or guest) or this principal (viewer dn, parent container, role or group)

    $roleis('admin')is('user')is('guest')
    admintruetruetrue
    userfalsetruetrue
    guestfalsefalsetrue

  • $principals: string[]

    Note: Use is(dn) instead of $principals as that method normalizes the passed DN before looking for it in this array.

    There are the following principals:

    • on any object type: all parent containers of the object
    • on a user: groupMembership nrfDynamicGroupMembership nrfMemberOf
    • on a role: nrfChildRoles nrfExternalChildRoles

  • $partition: string - the partition of the viewer (only if partitions are enabled)

  • $primaryPartition: string - the primary partition of the viewer (only if partitions are enabled)

ScriptVault

  • log
  • config
  • import(scriptLocation: string): any - load and parse/execute the given script; if scriptLocation starts with file: the script is located relative to config dir (it may be a javascript, json or json5 file) otherwise it is expected to be an DN of an object which has a DirXML-Dataattribute that is used as the script
  • runScript: (scriptLocation, context: any = Sandbox): any - executes the module.exports function with context (defaults to a fresh Sandbox passed as first parameter and returns its result; scriptLocation is same as in import() above
  • localizeAttributes: (entry: object, attrs: any): object - 
    const entry = {
  siteLocation: 'en~1st Floor|de~1.OG'
}

const result = ScriptVault.localizeAttributes(entry, { siteLocation: 'localizedSiteLocation' })
// -> result === entry
// -> entry.localizedSiteLocation === '1.OG'
// -> entry.siteLocation === undefined

ScriptVault.localizeAttributes(entry, { siteLocation: '=' })
ScriptVault.localizeAttributes(entry, ['siteLocation'])
// -> entry.siteLocation === '1.OG'

IDVault

  • get(dn [, ignored], attribute_key: string | string[]): Promise<any> - loads a LDAP entry by its DN
    • dn: string | DN - of entry to load
    • ignored - (optional)
    • attribute_key: string | string[] - either a list of attributes (an object with these attributes is returned) or single attribute as string (only that attribute is returned)
  • globalQuery(ignored, dalKey, dalOptions): Promise<any> - see dal(key, options)
  • dal(key, options): Promise<any> - executes the given (key) dal query
  • search(baseDN: string | DN [, options: Options]): Promise<any[]> - find several LDAP entries
    • baseDN: string | DN - the LDAP search base
    • options: Options - (optional) a config object with the following properties (all optional)
      • scope: 'base' | 'one' | 'sub' = 'sub'
      • filter: string = '(objectClass=*)'
      • attributes: string[] = ['1.1'] - unless attribute is defined
      • attribute: string - => attributes = [attribute] -> result is an array with only the attribute value for each entry
      • sort: string = undefined - like 'cn' (same as '+cn') or '-modifiedTimestamp'
      • skip: number = 0
      • take: number = undefined

Log

A Bunyan logger object.

Config

An object to access the application configuration. It has the following methods:

  • get(key: string): any - returns the given config value (like users.base)

    Note: This methods throws an error if the given key is not defined! Guard the access with config.exists(key).

    const value = (config.exists(key) && config.get(key)) || 'fallback value'
  • exists(key: string): boolean - determines if the given config key exists
← Queries