> ## Documentation Index
> Fetch the complete documentation index at: https://doc.qbilon.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Linking in Qbilon

> Use the linking API to connect assets with matching conditions.

## Preface

Linking in Qbilon is one of the possibilities to consolidate data by automatically creating relations between assets from two or more distinct data sources based on the properties that each asset has. This can be useful, for example, to link physical or virtual hardware devices to their respective monitoring counterparts whenever new devices are discovered.

The `/apiv1/data/link/{taskId}` endpoint allows you to programmatically link such data in Qbilon. Currently, this endpoint is considered to be in "beta stage", which means you can use it, but the data format still might change in the future.

## Linking Concept

To better understand this endpoint, we will first explain how linking works from the user's perspective, and then explain the data format that can be used in this endpoint to control how Qbilon links the data.

**So how does Linking work in Qbilon?**
Consider the following case shown in the first figure below, where you have loaded `Application` and `Server` assets from one data source and the `Monitoring Devices` that monitor those assets from another data source. As you can see in the second figure below, the `Monitoring Devices` are currently not connected to their respective monitored `Application` or `Server`.

![Linking in Qbilon: Linking Concept](https://mintcdn.com/qbilon-docs/Jmla3tEw4FRYjkNT/.gitbook/assets/58588698-a736-44e0-87bc-bce56aeea8b1-screenshot-2026-09-01-151428.png?fit=max\&auto=format\&n=Jmla3tEw4FRYjkNT\&q=85\&s=17d0b49db6b0a20dd764b0434d0a7e22)

Your intention now is to create a relation between each `Monitoring Device` instance and the specific asset it is monitoring. In order to automatically create those relations between these different types, you would now create a [Custom Linker](https://doc.qbilon.io/07-data-consolidation-writer/custom-linker.md) task in Qbilon like this:

![Linking in Qbilon: Linking Concept](https://mintcdn.com/qbilon-docs/Jmla3tEw4FRYjkNT/.gitbook/assets/89716a40-6a45-4273-b2f0-b0846439daab-screenshot-2026-09-01-152755.png?fit=max\&auto=format\&n=Jmla3tEw4FRYjkNT\&q=85\&s=08af21b09e9142a2f22de254935f0dd9)

In this linker task you defined that Qbilon shall create a relation of type `monitors` between all `Monitoring Devices` and `Application` or `Server` when the value of the `Asset` property of a `Monitoring Device` is the same as the value of the `Name` property of an `Application` or `Server`. Luckily, the existing data contained perfectly matching values for both, and after running the linker task for the first time, your "Monitoring View" and data schema will have changed to the following:

![Linking in Qbilon: Linking Concept](https://mintcdn.com/qbilon-docs/lr-P4KF_9wn8x9Vs/.gitbook/assets/d1d4094d-321c-4a90-8a3e-0cad87845c20-screenshot-2026-09-01-152941.png?fit=max\&auto=format\&n=lr-P4KF_9wn8x9Vs\&q=85\&s=c4ec3ab35515ce499b7f7020485119b0)

![Linking in Qbilon: Linking Concept](https://mintcdn.com/qbilon-docs/lr-P4KF_9wn8x9Vs/.gitbook/assets/f6d37b05-5836-492a-bab4-becf3b7afc6b-screenshot-2026-09-01-153345.png?fit=max\&auto=format\&n=lr-P4KF_9wn8x9Vs\&q=85\&s=21990654300c3ffe925637683ea126df)

This is how linking works from the user's perspective. With the Linking API, you can now programmatically trigger the same behavior by sending the necessary linking information as JSON instead of manually creating it in the UI.

To use the link endpoint, two conditions must be met:

* a prepared data source (see the respective section in [Rest API](https://doc.qbilon.io/12-customizing-qbilon/rest-api/index)) in whose name link requests are sent to Qbilon (this is the `taskId` part in the URL), and
* compliance with the data format as defined in Qbilon's OpenAPI specification (see `<your qbilon host>/openapi/index.html`).

## Data Format

The full version of the JSON format for a linking action as described above would look like this:

```json theme={null}
{
  "typesA": ["Monitoring Device"],
  "typesB": ["Application", "Server"],
  "linkConditions": {
    "booleanOperator": "or",
    "conditions": [
      {
        "attributeNameA": "Asset",
        "attributeDatatypeA": "Text",
        "attributeNameB": "Name",
        "attributeDatatypeB": "Text",
        "operator": "equal_to",
        "_conditionDiscriminator_": "simpledoubleattributenamecondition"
      }
    ]
  },
  "linkConnection": {
    "relationName": "monitors"
  },
  "nameAttribute": "Name"
}
```

If this is sent within the body to the endpoint `POST apiv1/data/link/-2` with valid credentials, then all instances of `Monitoring Devices` will be linked to any instance of `Application` or `Server` if the value of the respective `Monitoring Device's` `Asset` property is equal to the value of the `Application`/`Server`'s `Name` property.

The following is a step-by-step walk-through of the linking configuration to help you better understand what each part does and what the expected linking result will be.

### Fields "typesA" and "typesB"

These two fields are arrays of types within Qbilon that shall be linked with each other. In order to not have to create "Custom Linkers" between each combination of types, you can provide more than one type in each of those fields. Qbilon will automatically go through all combinations and try to find suitable linking candidates depending on the `linkConditions` provided.

### Field "linkConditions"

The `linkConditions` field contains a list of comparing `conditions` and a `booleanOperator` that tells how the comparing conditions should be evaluated.

All comparing conditions in the `conditions` array have to be in the form:

```json theme={null}
{
    "attributeNameA": "Asset",
    "attributeDatatypeA": "Text",
    "attributeNameB": "Name",
    "attributeDatatypeB": "Text",
    "operator": "equal_to",
    "_conditionDiscriminator_": "simpledoubleattributenamecondition"
}
```

The `attributeNameA`/`attributeNameB` fields should refer to an existing attribute of the types being compared. If the attribute does not exist, the condition is evaluated as `false`. The datatype of each attribute must be one of those allowed in Qbilon, i.e., `Boolean`, `Text`, `Number` , `DateTime` or `List<Boolean|Text|Number|DateTime>`.

The allowed operators depend on the combination of datatypes of the attributes used for the comparison:

| | **Boolean** | **Number** | **Text** | **DateTime** | **List\<Boolean>** | **List\<Number>** | **List\<Text>** | **List\<DateTime>** |
| - | - | - | - | - | - | - | - | - |
| **Boolean** | • is equal to | – | – | – | • contained in | – | – | – |
| **Number** | – | • is equal to • is \< than • is \<= than • is > than • is >= than | – | – | – | • contained in | – | – |
| **Text** | – | – | • is equal to • contained in • contains | – | – | – | • contained in | – |
| **DateTime** | – | – | – | • is equal to • is \< than • is \<= than • is > than • is >= than | – | – | – | • contained in |
| **List\<Boolean>** | • contains | – | – | – | • is equal to • contains • contained in • intersects with | – | – | – |
| **List\<Number>** | – | • contains | – | – | – | • is equal to • contains • contained in • intersects with | – | – |
| **List\<Text>** | – | – | • contains | – | – | – | • is equal to • contains • contained in • intersects with | – |
| **List\<DateTime>** | – | – | – | • contains | – | – | – | • is equal to • contains • contained in • intersects with |

The last field `conditionDiscriminator` is mandatory and must be `simpledoubleattributenamecondition`. This may change in a later version of the data format.

### Field "linkConnection"

The `linkConnection` field defines the type of the newly created relations, i.e., if the linker detects two assets for which it should create a new relation, the `relationName` is the type of the relation to be created. If a relation with the given name already exists in Qbilon, no new relation type is created and only the relation instance is created. If no such relation exists, the linker creates the relation type first and then the relation itself.

### Field "nameAttribute"

The `nameAttribute` field defines which attribute of the newly created relation should be used as display name for this relation, i.e., which property should be used for the name in a diagram or table view.

## Linking Behavior in Practice

In the following, we will go through several real-life cases that a linker might encounter and examine how the linker behaves during these cases to help you better understand the expected results of a custom linker.

### Repeated Run Without New Data

In the above case, where we have created 4 assets, i.e., 2x `Monitoring Device`, 1x `Application` and 1x `Server`, and have successfully linked them, you would now have exactly 3 relations. 2 of them were created by the call to the Linker API, i.e., the relations between the `Monitoring Device` and their respectively monitored `Application` or `Server`.
If you were to run the same linker again, it would internally find the same linking pairs, but it would not create any additional relations, because there is already a relation of type `monitors` existing between the respective assets. A linker will always only create exactly one relation of the given type between two assets that it has detected as viable linking candidates.

### Repeated Run With New Data

In contrast to the above case, where no new data was added to the scenario, consider a case where you have added an additional `Server` (asset type) which is also named `Server` (instance name), and as such would be a viable link candidate for the `Server Monitor` from the above example.

When the linker is run again, it detects the new data and creates an additional link between `Server Monitor` and the additional `Server 1`, as shown in the figure below:

![Linking in Qbilon: Repeated Run With New Data](https://mintcdn.com/qbilon-docs/Jmla3tEw4FRYjkNT/.gitbook/assets/8e297aed-c015-4483-bba0-2938394b9c97-screenshot-2026-09-01-153744.png?fit=max\&auto=format\&n=Jmla3tEw4FRYjkNT\&q=85\&s=94ecbcc5360bb101a6d5c28924912b39)

### Self-Reflective Relations

When a linker is run, it basically creates all possible combinations of assets of `typesA` and `typesB`, and then evaluates the `linkConditions` on all these combinations. If the combinations match, then it will create a relation between the two assets if there is not already one of the same relation.

However, there is the case where you could configure a linker that has the potential to create a lot of self-reflective relations, i.e., relations that are not between two different assets, but start and end at the same asset. For example, you could create a linker configuration like this:

```json theme={null}
{
  "typesA": ["Monitoring Device"],
  "typesB": ["Monitoring Device"],
  "linkConditions": {
    "booleanOperator": "or",
    "conditions": [
      {
        "attributeNameA": "Name",
        "attributeDatatypeA": "Text",
        "attributeNameB": "Name",
        "attributeDatatypeB": "Text",
        "operator": "equal_to",
        "_conditionDiscriminator_": "simpledoubleattributenamecondition"
      }
    ]
  },
  "linkConnection": {
    "relationName": "selfreflective"
  },
  "nameAttribute": "Name"
}
```

Theoretically, this would create two relations, one from and to `Server Monitor` and one from and to `Application Monitor`. However, in reality, Qbilon will not create a relation when you run this linking configuration. Qbilon currently doesn't allow to create self-reflective relations from a linking configuration. This may change with a future version of the link data format.

## Error Handling

Since the Linking API is currently in beta mode, most errors are not handled by Qbilon in an elaborate manner, but are discarded directly as format violations. This behavior will evolve over time and error handling will become more granular.

### Format Violations

| **Title** | **Description** | **Expected Behavior** |
| - | - | - |
| Non-existent operator | Providing an `operator` value that is not part of the predefined list above. | Returns a `422 - Unprocessable Entity` error. |
| Empty attribute in condition | Sending a blank value for `attributeNameA` or `attributeNameB` in the `linkConditions` field. | Returns a `422 - Unprocessable Entity` error. |

### Inconsistent Input

| **Title** | **Description** | **Expected Behavior** |
| - | - | - |
| Mismatching operator | If the `operator` value doesn't match the datatypes of the two attributes in a condition (e.g., using `is < than` for two text attributes), Qbilon ignores the condition. | Condition is ignored; returns `204 - No Content`. |
| Non-existent attribute | If an attribute in a condition does not exist, Qbilon logs a warning internally but still returns 204. This can happen when querying multiple types, where some may not contain the given attribute. | Logs warning internally; returns `204 - No Content`. |
| Mismatching datatype | If the datatype of a provided attribute in `linkConditions` does not match the actual attribute's datatype (e.g., expected Text, provided Number), Qbilon discards the condition. | Discards condition; returns `204 - No Content`. |
| Non-existent type | If a type in `typesA` or `typesB` does not exist in Qbilon, it is discarded. | Type is discarded; returns `204 - No Content`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.