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

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: 9080, HTTPS: 9443

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 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.

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:

Entry details

The Entry details view’s configuration is stored in the root of the configuration object in the detail JSON attribute. The detail attribute is an array containing a list of detail configuration objects, each defining the detail view for entries matching specific set of object classes (for example person, device, or organizationalRole). The application selects the appropriate detail configuration based on the object classes of the displayed entry.
The default configuration contains only one detail configuration for the Person entry type.

This attribute contains:

{
    "detail": [
        {
            "objectClasses": ["top"],
            "objectTypeName": "PERSON",
            "groups": [
                {
                    "displayName": "PERSONAL_INFO",
                    "attributes": [
                        { "ldapName": "sn" },
                        { "ldapName": "givenName" }
                    ]
                }
            ]
        },
        {
            "objectClasses": [
                "top",
                "device"
            ],
            "objectTypeName": "DEVICE",
            "groups": [
                {
                    "displayName": "DEVICE_INFO",
                    "attributes": [
                        { "ldapName": "l" },
                        { "ldapName": "description" }
                    ]
                }
            ]
        }
    ]
}

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:

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, certificate. (An attribute of certificate type can be used only in the detail view configuration object.)

  • 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 Entry 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 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 and ANY indexes are required.
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.

Detail Configuration Object

The detail configuration object defines the Entry details view for entries that match the specified object classes. The application matches the entry’s object classes against the configured objectClasses arrays and uses the first matching detail configuration to render the detail view. If no matching detail configuration is found, the application uses the first detail configuration in the array.

This configuration object contains these attributes:

  • objectClasses (array of string, required) - A list of LDAP object class names. This detail configuration is applied when an entry’s object classes matches exactly values in this list (The number of elements must be the same in both lists. Ordering does not matter).

  • objectTypeName (string, required) - The entry’s type name i18n translation key.

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

{
    "objectClasses": ["inetOrgPerson", "organizationalPerson"],
    "objectTypeName": "PERSON",
    "groups": [
        {
            "displayName": "PERSONAL_INFO",
            "attributes": [
                { "ldapName": "sn" },
                { "ldapName": "givenName" }
            ]
        }
    ]
}

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": "10",
    "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.

"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:

  • SEARCH - The header for the Expert search 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:

  • 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 entry detailed paragraph title are stored in the DXD_CD.CONFIGURATION.ENTRY_TYPES object in the corresponding translation file. Default configuration contains the following entry types:

  • PERSON - The title for the Person details paragraph.

  • DEVICE - The title for the Device details paragraph.

The text of paragraphs can be hidden for a cleaner view.
The configuration attribute representing this option is stored in the Appearance configuration object as the displayParagraphs JSON attribute. The default value of this attribute is true which means that the paragraphs are displayed in the application views. If you want to hide the paragraphs from the application views, set this attribute to false.

"appearance": {
    "displayParagraphs": true
}