Broadworks External Synchronization

This set of API’s allow to read/search, create, modify or delete records that keep track of synchronization between Broadworks Tenants, Groups and Users and an external directory system (typically an enterprise LDAP directory). The synchronization direction is intended to be from an external directory system (source) to Broadworks (target). The way records are accessed and modified is designed with this consideration in mind.

Search for a list of synchronization objects

GET /api/v1/broadworks/external_sync/

Gets a list of synchronization objects that matches the passed searching criteria.

Example request:

GET /api/v1/broadworks/external_sync/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "objectTypeEquals": "GROUP",
   "externalSystemEquals": "External_Directory_System",
   "externalIdEquals": "ou=Group1,ou=tenant1,ou=Instance1,dc=vendor,dc=intra",
   "broadworksIdEquals": "test_group",
   "syncStatusEquals": "PENDING_SYNC",
   "syncTimeStart": "2020-11-03T00:00:00",
   "syncTimeEnd": "2020-12-03T23:59:59"
}
Request JSON Object:

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
   "syncObjectList": [
      {
         "objectType": "GROUP",
         "broadworksId": "test_group",
         "externalSystem": "External_Directory_System",
         "externalId": "ou=Group1,ou=tenant1,ou=Instance1,dc=vendor,dc=intra",
         "objectData": {
            "bool_value": true,
            "null_value": null,
            "string_value": "This is a String",
            "another_object": {
               "syncro_ref": 1234
            }
         },
         "syncStatus": "PENDING_SYNC",
         "syncExtraInfo": {
            "thisIsTheEnd": true
         },
         "syncTime": "2020-11-05T09:37:21"
      }
   ]
}
Response JSON Object:
Status Codes:

Create a new synchronization object

POST /api/v1/broadworks/external_sync/

Creates a new synchronization object.

Authorization Right: System Admin.

Example request:

POST /api/v1/broadworks/external_sync/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "objectType": "GROUP",
   "externalSystem": "External_Directory_System",
   "externalId": "ou=Group1,ou=tenant1,ou=Instance1,dc=vendor,dc=intra",
   "syncStatus": "MUST_BE_SYNCED",
   "objectData": {
      "bool_value": true,
      "null_value": null,
      "string_value": "This is a String",
      "another_object": {
         "syncro_ref": 1234
      }
   },
  "syncExtraInfo": {
     "thisIsTheEnd": true
  }
}
Request JSON Object:

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
   "objectType": "GROUP",
   "broadworksId": null,
   "externalSystem": "External_Directory_System",
   "externalId": "ou=Group1,ou=tenant1,ou=Instance1,dc=vendor,dc=intra",
   "objectData": {
      "bool_value": true,
      "null_value": null,
      "string_value": "This is a String",
      "another_object": {
         "syncro_ref": 1234
      }
   },
   "syncStatus": "MUST_BE_SYNCED",
   "syncExtraInfo": {
      "thisIsTheEnd": true
   },
   "syncTime": "2020-11-05T17:37:52",
}
Response JSON Object:
Status Codes:

  • 200 OK – no error.

  • 400 Bad Request – format of the JSON input data not valid or tenant already exists.

Modify an existing synchronization object

PUT /api/v1/broadworks/external_sync/(string: external_system)/(string: external_id)/

Modifies an existing synchronization object.

Authorization Right: System Admin.

Example request:

PUT /api/v1/broadworks/external_sync/External_Directory_System/ou=Group1,ou=tenant1,ou=Instance1,dc=vendor,dc=intra/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "broadworksId": "test_group",
   "syncStatus": "PENDING_SYNC"
}
Request JSON Object:

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
   "objectType": "GROUP",
   "broadworksId": "test_group",
   "externalSystem": "External_Directory_System",
   "externalId": "ou=Group1,ou=tenant1,ou=Instance1,dc=vendor,dc=intra",
   "objectData": {
      "bool_value": true,
      "null_value": null,
      "string_value": "This is a String",
      "another_object": {
         "syncro_ref": 1234
      }
   },
   "syncStatus": "PENDING_SYNC",
   "syncExtraInfo": {
      "thisIsTheEnd": true
   },
   "syncTime": "2020-11-05T17:37:52",
}
Response JSON Object:
Status Codes:

Delete a synchronization record

DELETE /api/v1/broadworks/external_sync/(string: external_system)/(string: external_id)/

Deletes an existing synchronization object. This is always done by external ID reference.

Authorization Right: System Admin.

Example request:

DELETE /api/v1/broadworks/external_sync/External_Directory_System/ou=Group1,ou=tenant1,ou=Instance1,dc=vendor,dc=intra/ HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{}
Status Codes:

Read / Search External Synchronization Object

Name

Type

Methods

Description

GET

objectTypeEquals

String

O

The object type. Allowed values are TENANT, GROUP or USER

externalSystemEquals

String

O

The external Directory Server name.

externalIdEquals

String

O

The exact external ID reference.

externalIdStartsWith

String

O

External ID reference starts with passed string.

externalIdEndsWith

String

O

External ID reference ends with passed string.

externalIdContains

String

O

External ID reference contains passed string.

broadworksIdEquals

String

O

The Broadworks ID reference, can be null if no ID exists.

syncStatusEquals

String

O

The actual synchronization status of object. Allowed values are MUST_BE_SYNCED, MUST_BE_SKIPPED, MUST_BE_PROVISIONED, MUST_BE_DELETED, PENDING_SYNC, SYNCED, DELETED

syncTimeStart

String

O

The lower limit of date and time to search for. Must be specified together with syncTimeEnd. Allowed format is YYYY-MM-DDThh:mm:ss

syncTimeEnd

String

O

The lower limit of date and time to search for. Must be specified together with syncTimeStart. Allowed format is YYYY-MM-DDThh:mm:ss

Create / Modify / Delete External Synchronization Object

Name

Type

Methods

Description

POST

PUT

DELETE

objectType

String

R

F

F

The object type. Allowed values are TENANT, GROUP or USER

externalSystem

String

R

F

F

The external Directory Server name.

externalId

String

R

F

F

The external ID reference.

broadworksId

String

O

O

F

The Broadworks ID reference, can be null if no ID exists.

syncStatus

String

R

R

F

The actual synchronization status of object. Allowed values are MUST_BE_SYNCED, MUST_BE_SKIPPED, MUST_BE_PROVISIONED, MUST_BE_DELETED, PENDING_SYNC, SYNCED, DELETED

objectData

Object

O

O

F

Additional object synchronization data. This is a valid JSON object that may store any specific use data structure.

syncExtraInfo

Object

O

O

F

Additional object synchronization status. This is a valid JSON object that may store any specific additional information on canonical synchronization status.

syncTime

String

F

F

F

The creation or modfication timestamp. This is automatically set when using a POST or PUT method. Format is YYYY-MM-DDThh:mm:ss