Delayed connections batch

The API Delayed connections batch facilitates processing delayed connection in bulk. A handled delayed connection means that for a specific building the data has been correctly updated in the Cocon Fiber database. This is also true for the corresponding AsBuilt file. For more details see Delayed connections. A use case for batch processing delayed connections is handling the apartments that are part of a high-rise. Using Cocon Fiber terminology an apartment would be a building and the high-rise would be a building of type complex.

In order to realize delayed connections in bulk, the Delayed connections batch endpoint can be used.

The signature of this API is as follows. POST /api/v1/delayed-connections/batch

The Delayed connections batch API can be called to perform delayed connections regarding a specific set of buildings. For this purpose, the API consumer provides the necessary data. The requested data consists of a list of delayed connection items. Upon receival items are translated into individual background jobs. These jobs are subsequently executed asynchronously and atomically in order to realize a single delayed connection per job. Each batch job contains the data with which the delayed connection logic can determine the actions that need to be performed. 

Validations

Before actual changes are made, checks and validations are performed to ensure that all necessary information is present and valid. The validations can roughly be divided into two categories:

1. Determining which delayed connection 'scenario' needs to be executed (see Delayed connections).
2. Validating if all of the requirements for that scenario are met.

If one of these two validations fail, the delayed connection as part of the batch request fails and no changes are applied in the Cocon Fiber database for that specific building. This is not true for the associated AsBuilt file. Since multiple buildings are represented in the AsBuillt drawing, an AsBuilt can be changed although one or more delayed connection operations did not succeed.

Characteristics

Actuality of data

The Delayed connections batch API manipulates assets in the Cocon Fiber database. Per succesfully executed background job changes are effective immediately. However, it may take some time before the Sync API and the Read-only API reflect the changes. After the last job of the batch was performed the API starts the process to update the AsBuilt drawing based on the provided batch data.

Quality of service

The availability of the Delayed connections batch API is similar to the other Cocon Fiber API's. Dependent on the type of subscription, specific rate limiting and/or quota measures may be in effect (see the general rate limiting information on the API's overview page).

Filtering and paging

Filtering and paging are not applicable to the Delayed connections batch API.

Security

The Delayed connections batch API uses system context authentication. See the general information about system context authentication on the APIs overview page.

Usage Guidelines

There are certain specifics with regard to the usage of the Delayed connections batch API, which are described below.

General usage

Delayed connections are realized by providing the necessary batch data when calling the Delayed connections batch endpoint.

note

You can find the Delayed Connection API Specifications here

Request

Request to perform three delayed connections. Note that for one delayed connection the geometry is provided (scenario 2) and that the installation company is stated per request.

Example

POST /api/v1/delayed-connections/batch

Request body:
{
  "installationCompanyName": "BAM Infra",
  "delayedConnections": [
    {
      "frameName": "MTK",
      "terminationUnitType": "DIVERS",
      "attenuation1": 1.4,
      "attenuation2": 1.6,
      "isWithoutGeometry": true,
      "buildingName": "3573BR-23"
    },
    {
      "frameName": "MTK",
      "terminationUnitType": "DIVERS",
      "attenuation1": 1.5,
      "attenuation2": 1.3,
      "isWithoutGeometry": false,
      "newRoute": {
        "type": "LineString",
        "coordinates": [
          [
            142590.34774,
            486687.2322
          ],
          [
            142606.46397,
            486686.9567
          ]
        ]
      },
      "buildingName": "3573BR-25"
    },
    {
      "frameName": "MTK",
      "terminationUnitType": "DIVERS",
      "attenuation1": 1.2,
      "attenuation2": 1.3,
      "isWithoutGeometry": true,
      "buildingName": "3573BR-27"
    }
  ]
}

Parameters

• installationCompanyName: The name of the company that realized the delayed connections (Type: string) e.g. "BAM infra".
• 'delayedConnections`: Collection of delayed connections elements

Per delayed connections element:

• frameName: The frame short name. (Type: string) e.g. "MTK"
• terminationUnitType: The name of the fiber termination unit type that is placed in the frame.(Type: string) e.g. "FTU_DK01"
• attenuation1: The attenuation of the first termination. (Type: number) e.g. 0.4
• attenuation2: The attenuation of the second termination. (Type: number) e.g. 0.4
• newRoute: The linestring that will be used to extend the geometry to the new endpoint. (Type: object)
• isWithoutGeometry: Specifies whether the NewRoute is intentionally empty. (Type: boolean)
• buildingName: The name of the building which is a combined string of zipcode with house number. (Type: string) e.g. "1234AB-12-A"

Response

On success (HTTP Status Code 200) the batch jobs have been created and scheduled. The batch id is returned as a result.

Example

{
    "batchId": "5e862306-673a-4744-9234-17f8063f52a0"
}

Errors 

See the generic  Transactional API page for information about Error Responses.