5.14.1 api dir template

The /api/dir/template function retrieves the template of an entry in the directory.


Methods

  • GET

  • POST


Request


Table 1. Request Parameters
Key NameMandatoryExpected ValuesDefault ValueDescription

N/A

-

-

-

-


Example of a Request

https://192.168.1.1/api/dir/template


 

Response

The response is in the application/json format. The result object contains the keys series and users.


Go to the topic api/dir/query to get more information on the use of the key series.


The key users contains an array with one object (entry template) that contains all available keys of an entry in the directory with their default values for a particular device.

Tip

  •  You can get better acquainted with the structure of the JSON response in the example at the end of this topic.

Note

  •  Available keys depend on the model, type and hardware configuration of a device (e.g. key photo is only applicable for devices that have a display and store images in their directories).

Table 2. Response JSON Keys in the users Array
KeyTypical Returned ValuesDescription

uuid

Empty

Unique User Identifier. When a new entry in the directory is created by api/dir/create, uuid can be either provided as a parameter of the request or automatically generated by the device.

The format of uuid is "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", where X can be any hexadecimal digit. All zeroes are reserved for an empty uuid.

deleted

false

Indication of whether an entry in the directory has been deleted or not. Deleted entries remain in the directory until the maximum number of entries is reached. Stored deleted entries preserve uuid only for logging reasons. Two valid values: false, true.

owner

Empty

Indication of whether an entry in the directory is remotely managed by 2N® My2N, 2N® Access Commander or another remote management system. This value is intended for internal 2N® TELEKOMUNIKACE a.s. usage, alternatively it can be used for deleting a group of users (see api/dir/delete).

name

Empty

Name of an entry in the directory (a user or device name). A string of up to 63 characters is expected. The name can be left empty (the entry is in such a case identified by its uuid in logs, emails, etc.).

photo

Empty

Image of an entry in the directory (e.g. user’s photo, company logo). Saved as base64 encoded jpeg with the following syntax:
EXAMPLE: data:image/jpeg;base64,IMAGE_DATA_IN_BASE64

email

Empty

Email address of an entry in the directory. The expected format is namestructure@domainhierarchy.top. It is possible to enter multiple addresses separated with commas (saved as one string).

treepath

/

Definition of positions of an entry in the directory on the display.

  • The default position is in the root folder. This position is achieved by simply entering only one slash.
    EXAMPLE: / shows the entry in a root folder

  • An entry may be positioned on a display several times - the positions are separated with a semi-colon (;).
    EXAMPLE: /Folder1/;/Folder2/ shows the entry both in Folder1 and Folder2

  • An entry may be assigned a calling group that also serves as an alternative name in an individual position on the display by omitting the slash at the end of the position definition.
    EXAMPLE: /Folder1/Calling Group shows the entry in Folder1 under the name "Calling Group"

  • An entry may be prioritized (i.e. a prioritized entry is shown above unprioritized entries) individually in each position by adding :1 at the end of the position definition.
    EXAMPLE: /Folder1/:1;Folder2/Calling Group:1 shows the entry prioritized in Folder1 under its name and the entry prioritized in Folder2 as "Calling Group".

  • Multiple entries may be assigned to one calling group (selecting this calling group on a display results in a group call to all the entries under the calling group).
    EXAMPLE:
    Entry1: /Calling Group
    Entry2: /Calling Group
    shows both entries in the root folder as one row named "Calling Group" (both entries are called when this row is selected)

virtNumber

Empty

Virtual number of an entry in the directory. Virtual numbers may be dialed using a dialpad (if configured). The maximum length is 7 characters. The first and the last character may be chosen from the range of A to Z or 0 to 9. The rest of the characters may be between 0 to 9.

deputy

Empty

Uuid of a deputy entry that is called when the original callee is unavailable or not answering. When the deputy is not set the deputy uuid, it remains empty.

buttons

Empty

Buttons assigned to this entry in the directory. An array of integers (assigned according to the button position starting from 1) separated by a comma.

callPos

Array

Calling information of an entry. Entered as an array of up to three objects, i.e. up to three sets of calling information can be entered. Each of these three objects can contain the following keys:

  • peer - a phone number of an entry in the directory

  • profiles - time profiles if this phone number is valid (a number is not dialed when invalid)

    • P=X,..,Y
      where X,..,Y stands for a comma-separated array of predefined time profiles from 0 (time profile 1) to 19 (time profile 20)
      EXAMPLE: P=1,3,5 means that the predefined profiles 2, 4 and 6 define the validity period of the phone number

    • D=A,..,B@H:MM-H:MM
      where A,..,B stands for a comma-separated array of days of week (0 to 6 from Sunday to Saturday, 7 is Holiday), H stands for hour of the day (from 0 to 23), MM stands for minutes (from 00 to 59) - two values defining an interval. Several definitions may be combined separated with a semi-colon.
      EXAMPLE: D=7@0:15-13:15;D=5,7@13:15-15:15;D=7@15:15-23:30 means that the phone number is valid on Holiday from 0:15 to 13:15, on Friday and Holiday from 13:15 to 15:15 and on Holiday from 15:15 to 23:30.
      EXAMPLE: D=5,7 means that the phone number is valid on Friday and Holiday for the whole day.

  • grouped - defines whether the number is dialed in a group call together with the previous number (the third number is dialed with a deputy). Can be true or false.

  • ipEye - defines the IP address of the PC on which the 2N® IP Eye application is running (used for receiving video if the telephone does not have a display).

access

JSON Object

Access Control information of an entry in the directory. Contains the following keys:

  • validFrom - definition of the start of the validity term for the credentials of an entry in the directory. Entered in the Unix Time format. If left empty, the validity period starts at the beginning of the time (i.e. 00:00:00 UTC Jan 1st 1970).

  • validTo - definition of the end of the validity term for the credentials of an entry in the directory. Entered in the Unix Time format. If left empty, the validity period ends at the end of the time (i.e. 03:14:07 UTC Jan 19th 2038).

  • accessPoints - contains an array of access points (two access points, entry and exit). Each array item is represented as a JSON object with the following keys:

    • enabled - defines whether it is generally possible to use this access point (i.e. if it is possible to authenticate at that particular access point). Two valid values: true, false.

    • profiles - defines whether it is currently possible to use this access point (i.e. if it is possible at the moment to authenticate at that particular access point). The syntax of the profile definition is the same as in callPos.

  • pairingExpired - defines whether the Bluetooth pairing of an entry in the directory has expired or not. Two valid values: true, false.

  • virtCard - defines the virtual card of an entry in the directory that is relayed to Wiegand and other 3rd party systems if there is a successful authentication of the entry in the directory. 6 to 32 hexadecimal characters are expected.

  • card - defines up to two cards of an entry in the directory that are used for authentication. The card numbers are written as an array of strings. 6 to 32 hexadecimal characters are expected.

  • mobkey - defines the Bluetooth authentication ID of an entry in the directory. 32 hexadecimal characters are expected.

  • fpt - fingerprint templates of an entry in the directory. An encoded fingerprint is expected (for the details contact the Technical Support staff).

  • pin - defines the pin of an entry in the directory. 2 to 15 digits are expected.

  • apbException - defines whether an entry in the directory has an exception from the anti-passback policy (e.g. if so, its credentials can be used multiple times for entry without any exit). Two valid values: true, false.

  • code - defines up to three individual codes for switches. The individual switch codes are written in an array of strings (2 to 15 digits). The first position in the array defines an individual code for the first switch. Input an empty string to skip a code for the particular switch.

  • liftFloors - defines the configuration of accessible lift floors upon authentication. The following formatting is expected:
    F=P,..,R@PROFILE1_DEFINITION|F=X,..,Z@PROFILE2_DEFINITION
    where P,..,R and X,..,Z are arrays of comma-separated floors (0 to 63). io_1_1 is entered as 0, io_1_5 is entered as 4, io_2_2 is entered as 9 and so on. The arrays of floors active in certain profiles are separated by |. Predefined profiles or ad hoc definition of a new profile can be used (see the syntax definition in callPos/profiles). The profile definition part can be omitted if no profile is applied.
    EXAMPLE: F=2,4 defines floors without any time profile (user can access them any time).
    EXAMPLE: F=5@P=0,7 defines that the sixth floor (F=5) is accessible the whole day on Mondays and Holidays.
    EXAMPLE: F=0@P=7,13|F=0@D=5@9:15-11:45;D=4@11:45-13:30 defines that the first floor (F=0) is accessible in predefined profiles 8 and 14 (P=7,13) and in the time profile defined by the definition string.

  • licensePlates - defines a set of license plates configured to the user (used for opening upon license plate recognition). Individual licensePlates are separated by a comma. Whitespaces are ignored. A maximum of 255 characters is allowed (including whitespaces). The array is limited to 20 license plates and each license plate may have a maximum of 10 non-whitespace characters.

timestamp

0

A timestamp of performed changes in the directory. Timestamps are automatically generated by the directory in an ascending order. Go to the topic api/dir/query to get more information on the use of the timestamp.

Example of a Response

{
    "success": true,
    "result": {
        "series": "5247939846841727056",
        "users": [
            {
                "uuid": "",
                "deleted": false,
                "owner": "",
                "name": "",
                "photo": "",
                "email": "",
                "treepath": "\/",
                "virtNumber": "",
                "deputy": "",
                "buttons": "",
                "callPos": [
                    {
                        "peer": "",
                        "profiles": "",
                        "grouped": false,
                        "ipEye": ""
                    },
                    {
                        "peer": "",
                        "profiles": "",
                        "grouped": false,
                        "ipEye": ""
                    },
                    {
                        "peer": "",
                        "profiles": "",
                        "grouped": false,
                        "ipEye": ""
                    }
                ],
                "access": {
                    "validFrom": "0",
                    "validTo": "0",
                    "accessPoints": [
                        {
                            "enabled": true,
                            "profiles": ""
                        },
                        {
                            "enabled": true,
                            "profiles": ""
                        }
                    ],
                    "pairingExpired": false,
                    "virtCard": "",
                    "card": [
                        "",
                        ""
                    ],
                    "mobkey": "",
                    "fpt": "",
                    "pin": "",
                    "apbException": false,
                    "code": [
                        "",
                        "",
                        "",
                        ""
                    ],
                    "licensePlates": "",
                    "liftFloors": ""
                },
                "timestamp": 0
            }
        ]
    }
}