Delayed connections

In order to realise delayed connections to a specific building, the DelayedConnections endpoint can be used.

The signature of this API is as follows.

POST /api/v1/delayed-connections

or

POST /api/v1/buildings/{buildingId}/delayed-connections

The delayed connection API can be used to preform a delayed connection on a specific building (by name or by id). For this purpose, the API consumer provides the necessary data with which the delayed connection logic can determine the actions that need to be performed. Before actual changes are made, checks and validations are done to ensure 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.
2. Validating if all of the requirements for that scenario are met.

If one of these two validations fail, the entire operation fails and no changes are applied.

The delayed connection API supports the following scenarios:

#	Scenario	Notes
1	Performing a delayed connection using existing network components. The to-be-connected building, frame and termination unit already exist. The cable is present in slack, close to the building The geometry for the connection is not provided as part of the call. Existing geometry is used. This is used to process delayed connections which are prepared and only needs need to be connected to the fusebox. No new route is needed, which means the whole object can be null in the request body.	The newRoute attribute is prohibited. The isWithoutGeometry is true.
2	Performing a delayed connection using existing network components. The to-be-connected building, frame and termination unit already exist. The cable is present in slack, close to the building. The geometry for the connection is provided as part of the call. This function may be used in a situation where all the network components are available but a new route should be provided to draw the cable to the fusebox.	The newRoute attribute is mandatory. The isWithoutGeometry is false.

Bulk operations

The Delayed connections API facilitates realizing a single delayed connection per request. To be able to process delayed connections in bulk and monitor its progress next API’s are available:

1. Delayed connections batch
2. Delayed connections batch status

Typical usage scenario of the bulk operations APIs

1. Use the client connections API in order to determine the slack locations of the to-be-connected buildings. Use that information to define the geometries required for the next step.
2. Use the delayed connections batch API to schedule and execute the delayed connection operations in bulk.
3. Use the delayed connections batch status API in order to track the progress of the bulk operation based on the batch id returned by the call in step 2.

Characteristics

Actuality of data

The DelayedConnection API manipulates assets in the Cocon Fiber database. Changes are effective immediately. However, it may take some time before the Sync API and the Read-only API reflect the changes.

Quality of service

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

Filtering and paging

Filtering and paging are not applicable to the DelayedConnection API.

Security

The DelayedConnection API uses system context authentication. See the general information about system context authentication on the API's overview page.

Usage Guidelines

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

General usage

Delayed connections are performed by providing the necessary data for a specific scenario (see above).

Example request for a delayed connection (scenario 1, no geometry changes)

/api/v1/delayed-connections

Request body (for scenario 1):
{
	"frameName": "MTK",
	"terminationUnitType": "FTU_DK01",
	"attenuation1": 0.4321,
	"attenuation2": 0.1234,
	"installationCompanyName": "BAM infra",
	"newRoute": null,
	"isWithoutGeometry": true,
	"buildingName": "1234AB-12-A"
}

note

You can find the Delayed Connection API Specifications here

Request

Request Body:

• 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.
• installationCompanyName: The name of the installation company. (Type: string) e.g. "BAM infra".
• 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) true in this case.
• buildingName: The name of the building which is a combined string of zipcode with house number. (Type: string) e.g. "1234AB-12-A"

Errors

The following table provides a list of error codes and their corresponding descriptions for the Cocon Fiber Delayed Connection API.

note

Not all errors are relevant in the context of every scenario.

Error Code	Scope	Error message	Scenario relevance	Notes
DC-0001	Building	Missing value BuildingId.	1, 2	The BuildingId must not be null or empty.
DC-0002	Building	Building not found.	1, 2	The BuildingId must refer to an existing building.
DC-0003	Building	The building does not reference one existing frame.	1, 2	The building must have exactly one existing frame.
DC-0004	Frame	Missing value frame type.	1, 2	The FrameName must not be null or empty.
DC-0005	Frame	Invalid Frame name for a delayed connection.	1, 2	The FrameName must be a valid frame type.
DC-0006	Termination Unit	Missing value TerminationUnitType.	1, 2	The TerminationUnitType must not be null or empty.
DC-0007	Termination Unit	Termination unit type not found.	1, 2	The TerminationUnitType must refer to an existing termination unit type.
DC-0008	Termination Unit	Termination unit type cannot be of type Combination Unit.	1, 2	The TerminationUnitType must not be of type "Combination Unit."
DC-0009	Installation Company	Missing value InstallationCompany.	1, 2	The InstallationCompanyName must not be null or empty.
DC-0010	Installation Company	Installation company not found.	1, 2	The InstallationCompanyName must refer to an existing installation company.
DC-0011	Attenuation	Attenuation for fiber 1 or 2 exceeds maximum value of maximumAttenuation.	1, 2	The Attenuation1 and Attenuation2 values must be less than or equal to a specified maximum value.
DC-0012	Route	New route is missing.	2	-
DC-0013	Route	New route outside the bounds of the coordinate system.	2	-
DC-0014	Route	Slack is not near the start of the new route.	2	-
DC-0015	Building	Project progress status not allowed.	1, 2	The project status must be allowed. At the moment the only allowed project status is "-" (= maintenance).
DC-0016	Route	New route data provided although network is not moved.	1	-
DC-0017	Termination Unit	Termination unit has no default connector.	1, 2	The TerminationUnitType must have a default connector.
DC-0018	Slack	No slack connected to building.	1, 2	A Slack needs to be connected to the specified building.
DC-0019	AsBuilt	Project files are already in use by another request.	1, 2	Try again at a later moment in time.

note

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