Configuration

This section describes how to configure the DirX Corporate Directory web application.The application’s configuration is stored in the file install_path/plugins/dirx-corporate-directory/assets/config/app-config.json.

For example, install_path looks like C:\Program Files\Apache Software Foundation\Tomcat 10.1\webapps\spa.

The configuration file is in human-readable form in JSON format and contains these parts:

REST API Configuration
Bind Operation
Search Request Parameters
Attributes
Quick search
Extended search
Expert search
Person details
Results table
Logger
Translations
Page Headers and Paragraphs

REST API Configuration

REST API configuration is stored in the root of the configuration object in the “rest” JSON attribute.This configuration object defines the DirX Directory server instance with which the application communicates.

This configuration object contains these configurable attributes:

path (string, required) - Defines a URL to the DirX Directory REST API.

"rest": {
    "path": "https://dxd-hostName:dxd-rest-server-port/dxd/ldap/v1"
}

We strictly recommend using the HTTPS protocol instead of HTTP for security reasons.If HTTPS is used, please ensure that the user’s browser trusts the certificate that is used by the DirX Directory REST API.

Default ports for the DirX Directory REST API are: HTTP: 8880, HTTPS: 8443

Bind Operation

Bind operation configuration is stored in the root of the configuration object in the “bind” JSON attribute.This attribute is optional.This configuration object defines bind operation-specific settings.If it is not defined, the application takes into account its default value with the “anonymous“ attribute set to false.

"bind": {
    "anonymous": false
}

The configuration object contains the following attributes:

anonymous (boolean, required) - Whether the application UI supports login as an anonymous user.Supported values are true and false.When true, ** the login page contains a button for login as an anonymous user (there is no need to provide a username and password).

Search Request Parameters

Search request parameters configuration is stored in the root of the configuration object in the “searchParameters” ** JSON attribute.This object defines the base parameter values used for LDAP searches in the application.

This configuration object contains the following attributes:

baseObject (string, required) - The name of the base object entry (or possibly the root) relative to where the search is to be performed.There is no default value and baseObject must be configured.See RFC 4511, section 4.5.1.1.
scope (string, required) - The scope of the search to be performed.Supported values are base (base object), one (single level) and sub (whole subtree).For details, see RFC 4511, section 4.5.1.2.
sizeLimit (string, optional) - The maximum number of entries to be returned as a result of the search.A value of zero in this field indicates that there are no client-requested size limit restrictions in effect for the search.The default value is 0. Servers may also enforce a maximum number of entries to return.See RFC 4511, section 4.5.1.4.
timeLimit (string, optional) - The maximum time (in seconds) allowed for a search.A value of zero in this field indicates that there are no client-requested time limit restrictions in effect for the search.Servers may also enforce a maximum time limit for the search.The default value is 60. See RFC 4511, section 4.5.1.5.
filter (string, required) - The conditions that must be satisfied for the search to match a given entry.This attribute usually corresponds to the “{{searchFilter}}” constructed in the application but can also extend it; for example, to restrict the search result only to entries of the given object class.The default value is “(&(objectClass=person){{searchFilter}})”.For details, see RFC 4511, section 4.5.1.7.

"searchParameters": {
    "baseObject": "o=My-Company",
    "scope": "sub",
    "sizeLimit": "0",
    "timeLimit": "60",
    "filter": "(&(objectClass=person){{searchFilter}})"
}

Attributes

Attributes configuration is stored in the root of the configuration object in the “attributes” JSON attribute.This object defines the set of all LDAP attributes that the application can use.Attributes are referenced by application components like quick search, expert search, extended search, and so on.

The value is an array of attribute configuration objects.

Quick search

The Quick search component’s configuration is stored in the root of the configuration object in the “quickSearch“ JSON attribute.The Quick search component’s functionality depends on this configuration.

This configuration object contains this attribute:

ldapName (string, required) - A reference to the attribute configuration object with the same ldapName.This attribute is used in the quick search.

Extended search

The Extended search view’s configuration is stored in the root of the configuration object in the “extendedSearch“ JSON attribute.The Extended search form component’s functionality and view depend on this configuration object.The view consists of groups that have defined attributes according to which user can perform the search.

This configuration object contains this attribute:

groups (array, required) - A list of group configuration objects.The search filter view is divided into these groups.

Expert search

The Expert search view’s configuration is stored in the root of the configuration object in the “expertSearch” JSON attribute.The Expert search form component’s functionality and view depend on this configuration object.The view consists of groups that have defined attributes according to which user can perform the search.

This configuration object contains this attribute:

groups (array, required) - A list of group configuration objects.The search filter view is divided into these groups.

Person details

The Person details view’s configuration is stored in the root of the configuration object in the “detail” JSON attribute.The Person details view’s functionality and view depend on this configuration object.The view consists of groups that have defined attributes which values are presented in the detail.

This configuration object contains this attribute:

groups (array, required) - A list of group configuration objects.The search view is divided into these groups.

Results table

The Results table view configuration is stored in the root of the configuration object in the “result” JSON attribute.The Results table component’s functionality and view depend on this configuration object.The configuration object contains attributes that define the columns in the result table.

This configuration object contains these configuration attributes:

tableParameters (TableParameters, required) - A result table parameters object.
attributes (array, required) - An array of Attribute link objects.

Table of Configuration Objects

Attribute Configuration Object

Each attribute configuration object contains these attributes:

displayName (string, required) - The attribute’s internationalization (i18n) translation key.
ldapName (string, required) - The attribute’s name in the LDAP directory.
type (string, required) - The attribute type.Supported types are: string, number, boolean, datetime.
defaultSearchOperator (string, required) - The default search operator pre-set in the user interface extended / expert search view.The supported value is one of: begins, ends, contains, equals.
searchOperators (array, required) - The set of supported search operations.Supported values are: begins, ends, contains, equals.Configured values are used in a selection list in an Expert search view.
sortable (boolean, required) - Whether results in the table are sortable according to this attribute.Supported values are true and false.
editable (boolean, required) - Whether this attribute is editable in the Person details view.Supported values are true and false.
multiValued (boolean, required) - Whether this attribute can be multi-valued. Supported values are true and false.
validationParameters (object, optional) - The validation parameters configuration object used in expert / extended search and in edit mode for input values validation.

Be careful when configuring the sortable attribute. * The sorting feature requires corresponding indexes to be created in the DirX Directory server. The attribute’s *INITIAL index is required. The PRESENT index is recommended for reverse sorting. Missing indexes may cause performance issues.

Be careful when configuring the defaultSearchOperator and searchOperators attributes. Missing corresponding indexes in a DirX Directory server instance can cause performance issues.

"attributes": [
    {
        "displayName": "SURNAME",
        "ldapName": "sn",
        "type": "string",
        "defaultSearchOperator": "begins",
        "searchOperators": [
            "begins"
            "ends",
            "contains",
            "equals"
        ],
        "sortable": true,
        "editable": false,
        "multiValued": true,
        "validationParameters": {
            "minLength": 1
        }
    },
    ...
]

Validation Parameters Configuration Object

The validation parameters configuration object contains these configurable attributes:

maxLength (number, optional) - The maximum length of the attribute value.
minLength (number, optional) - The minimum length of the attribute value.
pattern (string, optional) - A regular expression condition which must be met.

Group Configuration Object

The group configuration object contains these configurable attributes:

displayName (string, required) - The group’s i18n translation key.
attributes (array, required) - An array of attribute links.

{
    "displayName": "PERSONAL_INFO",
    "attributes": [
        {
            "ldapName": "sn"
        },
        {
            "ldapName": "givenName"
        }
    ]
}

Attribute Link Object

The attribute link configuration object consists of these attributes:

ldapName (string, required) - A reference to an attribute configuration with the same ldapName.This attribute is used in the quick search.
link (Link, optional) - A link configuration object.

{
    "ldapName": "sn",
    "link": {
        "actionType": "paramSearch"
    }
}

Link Configuration Object

The link configuration object consists of these attributes:

actionType (string, required) - The operation to be performed when a user clicks on the link.Supported values are: paramSearch (sets the attribute value in the search form and performs a search), dnSearch (searches for entry with this dn and shows it in the detail view).

{
    "actionType": "paramSearch"
}

To display a working link, the attribute must support the equals operator.
See the section on Attributes configuration.

Table Parameters Configuration Object

The table parameters configuration object consists of these attributes:

pageSize (string, required) - The count of entries shown in the results table on one page.
sort (Sort configuration object, required) - The sort properties of the result table.

"tableParameters": {
    "pageSize": "15",
    "sort": {
        "ldapName": "sn",
        "dir": "asc"
    }
}

Sort Configuration Object

The sort configuration object consists of these attributes:

ldapName (string, required) - The LDAP attribute by which the result table is sorted.
dir (enum, required) - The sort direction of the column that represents the attribute specified in ldapName.Supported values: asc, desc.

Logger

Each Logger configuration object contains these attributes:

level (enum, required) - The NGXLogger level.Valid values are 0 for TRACE, 1 for DEBUG, 2 for INFO, 3 for LOG, 4 for WARN, 5 for ERROR, 6 for FATAL and 7 for OFF.For details, see the NGXLogger documentation:
- https://github.com/dbfannin/ngx-logger/blob/ac55c7257dddcba376342c880141df4bae49e9a4/docs/config.md
- https://github.com/dbfannin/ngx-logger/blob/ac55c7257dddcba376342c880141df4bae49e9a4/src/lib/types/logger-level.enum.ts

"logger": {
    "level": 4
}

The default logger level in the application is set to level 4 (WARN).This setting can be overridden in the configuration by defining the desired value for the “level“ attribute.

Translations

The application supports two languages:

English
German

The client application contains translation files in JSON structure for both languages.These files are stored in the folder:

install_path/plugins/dirx-corporate-directory/assets/i18n/ :

en.json - English translation file.
de.json - German translations file.

If you are adding a new attribute into the configuration, the displayName value is taken as a translation key whose value is searched in the translation file.If this translation key is not found in the translation file, the value of the attribute is shown in the user interface.Translation keys for attributes are stored in the

DXD_CD.CONFIGURATION.ATTRIBUTES object in the corresponding translation file.

For example: for the surname attribute, the displayName attribute is set to “SURNAME”.This key is searched in the translation file.For the English language, the “Surname” value is returned and the “Nachname“ value is returned for the German language.

Page Headers and Paragraphs

Each view in the application contains its header text and paragraphs describing the basic functionality of the view.

It is possible to update the text of these headers and paragraphs directly in the translation files.

Translation keys for headers are stored in the DXD_CD.PAGE.HEADERS object in the corresponding translation file.

Possible keys are:

EXTENDED_SEARCH - The header for the Extended search view.
EXPERT_SEARCH - The header for the Expert search view.
RESULT_DETAIL - The header for the Person details view.
RESULT_TABLE - The header for the Results table view.

Translation keys for paragraphs are stored in the DXD_CD.PAGE.PARAGRAPHS object in the corresponding translation file.

Possible keys are:

EXTENDED_SEARCH - The header for the Extended search view.
EXPERT_SEARCH - The header for the Expert search view.
RESULT_DETAIL - The header for the Person details view.
RESULT_TABLE - The header for the Results table view.

It is possible to avoid showing view headers and paragraphs. In this case, please delete the DXD_CD.PAGE object in the corresponding translation file.