JSON API

Synchronising a JSON API

  1. Select the JSON API menu

  2. Edit the settings for a connection

  3. Delete a connection

  4. Activate a connection
    In addition to usual contact and image information, it is also possible to take registration data into account (BLF, Presence). Corresponding server attributes must be created for this.

  5. Add a new connection

Enabled

Enables the request to any JSON source

Disable automatic import on software startup

By default, the import is run on startup. Disable this feature if you prefer to initiate the import manually.
Add records without a unique contact ID as a new contact (OFF=skip the record)Can be activated to import from a source without unique contact ID once. Be aware that importing multiple times from a source without unique contact ID will result in the same contacts being created multiple times.

Import once from the source URL

Click to import contacts right now.

Directory nameFree name of the JSON source to be accessed
API InterfaceSelection of an available API interface
Authentication typeThis parameter defines how and where authentication takes place
User nameUser name for negotiation procedures such as Negotiate
PasswordUser password
URLURL of JSON data source
  1. Attributes of local data

  2. Attributes
    Select a value in the list box (if offered) or enter an individual attribute in the editable list box.

JSON import

Contacts can be imported from JSON data sources with a URL link or file link. URL data sources are URLs that can be accessed without authentication, with HTTP-AUTH or oAUTH. Static files that are created once for the import or updated cyclically can also be used.

Regardless of the data source, contact data can be imported/synchronized "once" or cyclically. For synchronization purposes, a unique contact ID assignment is preferable in order to avoid duplicates during cyclical import processes.

To import from local data sources, please use a special form of path specification and add "file:///" before the drive specification, e.g. "file:///d:/json-csv/data.json".

The JSON structure is not subject to any special specifications. JSON objects can be addressed directly and customized for import. This applies to simple objects and also to JSON arrays.

The data to be imported is assigned using the simple principle of value assignment by object path: [Value to be imported] -> [Local value]

Example of a simple JSON structure for a single "contact object":

[
   {
  "id": "10201",
  "cn": "Tim1-WEB",
  "sn": "Harper1",
  "mail": "tim1@testmail.com",
  "title": "Product Manager1",
  "o": "Test Company Inc.1",
  "postalCode": "11111",
  "street": "street1",
  "jpegPhoto": "",
  "extension": "300",
  "data":
           {
          "postOfficeBox": "PO127653-T3",
          "st": "NY"
           },
  "phoneUseBLF":"1",
  "phoneUsePresence":"0",
  "AssignedSIPAccountID":"placetel"
   }
]

Import example "First name"

Import example "post office box"

When importing from an array, every array index is checked and imported, provided that usable data is available.

"numbers": {
  "PRIVATE": [
       {
          "id": "",
          "number_e164": "4964454930560000",
          "number_disp": "4930567890"
       },
       {
          "id": "",
          "number_e164": "4964454930671111",
          "number_disp": "4930678900"
       }
   ]

In some cases, the data to be imported must be modified. Two functions can be used for this purpose, which influence a value during the data import. These functions can be combined several times in the object path specification. Functions and object specifications are logically linked with "|" (pipe).

  • writeIfNotEmpty("<Value>")        -> only writes the value if the result is > NULL

  • write("<Value>")          -> always writes the value, regardless of the result

Example:

writeIfNotEmpty("+")|numbers/PRIVATE/number_e164

Result:

+4964454930560000

+4964454930671111

Example:

writeIfNotEmpty("+")|numbers/PRIVATE/number_e164|write("123")

Result:

+4964454930560000123

+4964454930671111123

Special handling when importing group assignments:

A group assignment of a contact can be made by importing data into the "Assignment to contact group" field.

The following applies:

  • External group designations always take precedence over the program groups.

    • The internal program group "Favorite" is the only group that can be used and assigned haptically alongside the externally supplied groups.

    • Group names are NOT treated as "case sensitive" during the import. This avoids multiple groups with different spellings of a group type (Friends, friends, FrienDs).

    • Imported groups are permanently stored in the application. Groups that are no longer required must be deleted in the application's group management. Deletion via JSON is currently not provided.

Import example "Groups" from an array:

"groups": [
   {
      "id": "14741",
      "name": "Friends",
      "desc": "Friends"
   },
   {
      "id": "14744",
      "name": "Partner",
      "desc": ""
   }
]

If no contact groups with the names "Friends" and "Partner" exist, these are created. The contact currently being imported is also assigned to the "Friends" and "Partners" groups.

Import of image files:

Image data is always expected in JPEG image format. JPEG files must be converted to BASE64 format for any import.