> ## 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.

# Writing to Qbilon

> Write assets, relations, and properties through the Qbilon API.

## Preface

The `/apiv1/data/upsert/{taskId}` endpoint allows writing to Qbilon. Two conditions must be met before it can be used:

* A prepared data source (see the respective section in [REST API](https://doc.qbilon.io/12-customizing-qbilon/rest-api/index)) in whose name to send write requests to Qbilon (that's the `{taskId}` part in the URL) and
* adherence to the data format as defined in the OpenAPI specification of Qbilon (see `<your qbilon host>/openapi/index.html`).

## Data Format

Qbilon uses a versatile graph-like format in JSON that can be put in the body of a POST request to write data to Qbilon. The graph format consists of several optional parts and some mandatory basic parts. This allows a user to pass exactly as much information as needed. Most of the other information can be inferred by Qbilon but also be explicitly provided by the user if required.

### Full-Fledged Data Format

A full-fledged version of the format for a simple diagram with two assets and one relation/edge would look like this:

```json theme={null}
{
    "types": {
        "Server": {
            "nameAttribute": "Name",
            "attributes": {
                "Name": {
                    "dataType": "Text",
                    "updateStrategy": "UPDATE_ALWAYS"
                }
            },
            "elements": [
                {
                    "externalId": "uniqueid-1",
                    "properties": {
                        "Name": "Server 1"
                    }
                }
            ]
        },
        "Application": {
            "nameAttribute": "Name",
            "attributes": {
                "Name": {
                    "dataType": "Text",
                    "updateStrategy": "UPDATE_ALWAYS"
                }
            },
            "elements": [
                {
                    "externalId": "uniqueid-2",
                    "properties": {
                        "Name": "Application 1"
                    }
                }
            ]
        }
    },
    "relations": {
        "runs on [Application -> Server]": {
            "nameAttribute": "Name",
            "attributes":{
                "Name": {
                    "dataType": "Text",
                    "updateStrategy": "UPDATE_ALWAYS"
                }
            },
            "elements": [
                {
                    "externalId": "uniqueid-12",
                    "properties": {
                        "Name": "runs on"
                    },
                    "sourceExternalId": "uniqueid-2",
                    "targetExternalId": "uniqueid-1"
                }
            ]
        }
    }
}
```

 If this is sent within the body to the endpoint `POST apiv1/data/upsert/-2` with valid credentials, then two assets and one relation are created together with their corresponding type/relation in the data schema.

### Shorthand Data Format

The above example contains a lot of optional information that Qbilon can actually infer on its own. To simplify this, it can be reduced as shown below, while achieving exactly the same result:

```json theme={null}
{
    "types": {
        "Server": {
            "nameAttribute": "Name",
            "elements": [
                {
                    "externalId": "uniqueid-1",
                    "properties": {
                        "Name": "Server 1"
                    }
                }
            ]
        },
        "Application": {
            "nameAttribute": "Name",
            "elements": [
                {
                    "externalId": "uniqueid-2",
                    "properties": {
                        "Name": "Application 1"
                    }
                }
            ]
        }
    },
    "relations": {
        "runs on [Application -> Server]": {
            "nameAttribute": "Name",
            "elements": [
                {
                    "externalId": "uniqueid-12",
                    "properties": {
                        "Name": "runs on"
                    },
                    "sourceExternalId": "uniqueid-2",
                    "targetExternalId": "uniqueid-1"
                }
            ]
        }
    }
}
```

### Correlation of Data Format and Result

With the information provided by the above JSON files, Qbilon is not only able to create the two assets and the relation between them in the model, but also to infer the corresponding data schema of types and relations in the data schema.

The actual data types of the properties, e.g., "Name" being a text, are determined as far as possible by Qbilon on its own.
However, if data types are inferred incorrectly, just clear and reload the data, and then send the explicit data type as shown in the full-fledged data format.

In the following we will go through all parts of the above request and there are also additional examples at the end of this page that shall give you a guideline on what you can do with this API.

### Types and Relations

The body of the request is divided into two parts, i.e., `types` and `relations`. This allows you to send them separately or in combination, e.g., if you only provide the `types` part and leave the `relations` part empty, then qbilon will only insert the assets provided in that part, but no relations. Vice versa, if you leave the `types` part empty and only put the `relations` part into the request body, the API will create only the provided relations, but no assets or types.

**Examples**
For example in order to send only assets but no relations you could write the request body like this:

```json theme={null}
{
    "types": {
        "Server": {
            "nameAttribute": "Name",
            "elements": [
                {
                    "externalId": "server-1",
                    "properties": {
                        "Name": "Server 1"
                    }
                },
                {
                    "externalId": "server-2",
                    "properties": {
                        "Name": "Server 2"
                    }
                }
            ]
        }
    },
    "relations": {}
}
```

This request will write all `Server` assets that are provided into Qbilon with all their properties and create the according `Server` type in the data schema if necessary, but will not write any relations or create any relations.
The same is valid vice-versa for relations, i.e., you can leave the `types` part empty and only send relations in the `relations` part of the body. Please note that if the given source or target asset of a relation provided in that section is not available in Qbilon, then this relation will be skipped.

The names of the types (in the above example `Server` and `Application` ) can be freely chosen. Even special characters and emojis are allowed, although probably not sensible in most cases, e.g., the following request would work:

```json theme={null}
{
    "types": {
        "Something with special Characters ßüöé 🤒": {
            "nameAttribute": "Name",
            "elements": [
                {
                    "externalId": "somethingspecial-1",
                    "properties": {
                        "Name": "Something Special 1"
                    }
                }
            ]
        }
    },
    "relations": {}
}
```

### The "nameAttribute" Field

The field `nameAttribute` is mandatory and provides Qbilon with a human readable name, by pointing to a property of the type or relation, that shall be used as display name. In the following example, the type's display name is set to the value of the property `Name`, which would be `Server 1` for the provided asset.

```json theme={null}
{
    "types": {
        "Server": {
            "nameAttribute":"Name",
            "elements": [
                {
                    "externalId": "uniqueid-1",
                    "properties": {
                        "Name": "Server 1",
                        "Test": 123,
                        "Another Property": "Test"
                    }
                }
            ]
        }
    },
    "relations": {}
}
```

### The "attributes" Field

The field `attributes` is optional and can be used to explicitly provide attribute information for any type or relation, i.e., providing an explicit data type or update strategy for that attribute. Within the `attributes` object, each key name corresponds to an attribute, e.g., If the key `Name` is used, it corresponds to the attribute `Name` of the respective type. See the following example for further clarification, where datatype and update strategy are given for the two attributes `Name` and `Test`.

```json theme={null}
{
    "types": {
        "Server": {
            "nameAttribute":"Name",
            "attributes": {
                "Name": {
                    "dataType": "Text",
                    "updateStrategy": "UPDATE_ALWAYS"
                },
                "Test": {
                    "dataType": "Number",
                    "updateStrategy": "UPDATE_ALWAYS"
                }
            },
            "elements": [
                {
                    "externalId": "uniqueid-1",
                    "properties": {
                        "Name": "Server 1",
                        "Test": 123
                    }
                }
            ]
        }
    },
    "relations": {}
}
```

> [!NOTE]
>
> If you provide a data type and/or update strategy for an attribute that does not exist, then this will be ignored by Qbilon. For example: e.g., an additionally provided attribute called `Test2` in the `attributes` section of the above example.

#### Datatypes

The field `datatype` within an attribute definition is optional. Allowed data types are:

* `Text`
* `Number`
* `Boolean`
* `DateTime`
* `List<Text|Number|Boolean|DateTime>`

> [!NOTE]
>
> Please note that the names of the data types are case sensitive.

You can use this to explicitly provide the datatype of an attribute. This can be useful if you have somewhat ambiguous data, e.g., a version number which is most of the time in the form `x.y` but can also hold values like `x.y.z` If the majority of values were in the first format, Qbilon would infer the datatype `Number` and discard all values that could not be parsed as a number. In such cases, you could explicitly state that the datatype should instead be `Text`.

#### Update Strategies

The field `updateStrategy` within an attribute definition is optional.

The `POST apiv1/data/upsert` endpoint is not only for creating assets and relations, but also for updating them. Just send the data you want to update and an update strategy that tells Qbilon how to handle incoming data for an existing asset or relation.

The default update strategy in Qbilon is `UPDATE_ALWAYS`, which means that when new data is sent for an existing asset, then this asset will be overwritten with the incoming data. Please note that ...

* an already persisted data type cannot be changed afterwards, even if an appropriate update strategy is explicitly defined and
* trying to update a list property with a primitive data type will return an exception.

Example: To update the `Name` property of "Server 1" to "Server 2", just send the following JSON text to the upsert endpoint with the same `taskId` as before:

```json theme={null}
{
    "types": {
        "Server": {
            "nameAttribute": "Name",
            "elements": [
                {
                    "externalId": "uniqueid-1",
                    "properties": {
                        "Name": "Server 2"
                    }
                }
            ]
        }
    },
    "relations": {}
}
```

Qbilon first checks if the provided `taskId` /`externalId` combination already exists for an asset within Qbilon. As this "Server" asset was written before, it will be found and its `Name` property will be overwritten with the new value "Server 2". If the asset has additional properties, then these are not altered as only the `Name` property is being updated.

Additional update strategies are available to accommodate different update behaviors:

| `UPDATE_IF_NO_VALUE_PRESENT` | Updates the given properties only if there was no value for them before. If there was already a value, nothing will happen. |
| - | - |
| `LIST_MERGE_UNIQUE_VALUES` | Only for list properties: merges the existing list with an incoming list, keeping only unique values. |
| `LIST_KEEP_NEWEST_10` | Only for list properties: will always keep the 10 most recent values, e.g. if the incoming list has only 3 values, it will keep 7 from the existing list and add the 3 new ones. This is usually used for lists that would otherwise tend to grow indefinitely. |
| `LIST_KEEP_NEWEST_30` | Only for list properties: same behavior as before, but for 30 values. |

If you are missing an update behavior for your use case, then don't hesitate to [reach out to us](https://www.qbilon.io/de/support/).

### The "elements" Field

The `elements` field contains an array of the actual assets of the given type or relation. The most important part of this object is the unique id that is given to each asset, i.e., either the `externalId` or if it is an update of an already known asset, the `qbilonId`. Usually the `externalId` is provided.

This ID is then combined with the `taskId` that must be provided for each writing operation and will result in a `qbilonId` that can later be used to directly address also assets from other data sources. The `externalId` must be unique within the scope of the data source (but not globally unique). It also has to be deterministic, i.e., if there are two runs of the same data source, then in both runs the `externalId` should reference the same asset.

If you accidentally provide both `externalId` and `qbilonId`, the `qbilonId` takes precedence without any fallback to the `externalId` in case there is no asset found for the given `qbilonId`.

In addition to the ID, the properties of the asset are also provided in the `properties` field, which is again an object where the field names are the names of a property and the value is its value. The `properties` field is mandatory but can be an empty object to indicate an asset or relation with no further properties.

### Relation Names

While field names in `types` do not require a specific format and can be virtually any string, relations have a predefined format that has to be used for qbilon in order to work properly. All relations have to be provided in the form `<relation name> [<type name> → <type name>]`, e.g., a relation that is of type `runs on` and goes from an `Application` to a `Server` would be written like this: `runs on [Application → Server]`.

## Error Handling

### Format Violations

The API will throw an exception if the incoming payload (that constitutes the data being sent) is invalid or unexpected in any way.

| **Title** | **Description** | **Expected Behavior** |
| - | - | - |
| Missing `types` or `relations` field | If either the `types` or `relations` field is missing from the request. | Returns a `422 - Unprocessable Entity` error. |
| Missing `nameAttribute` field | If the `nameAttribute` field for types or relations is not provided. | Returns a `422 - Unprocessable Entity` error. |
| Unknown datatype | If the `datatype` in an attribute definition is not valid or is misspelled (e.g., using lowercase instead of uppercase). | Returns a `422 - Unprocessable Entity` error. |
| Missing `externalId` or `qbilonId` field | If neither `externalId` nor `qbilonId` is provided for an asset or relation in the `elements` field. | Returns a `422 - Unprocessable Entity` error. |
| Incorrectly encoded `qbilonId` | If the provided `qbilonId` for an asset or relation is malformed (e.g., "test123" or an empty string). | Returns a `422 - Unprocessable Entity` error. |
| Malformed relation format | If the relation does not follow the expected format `<relation name> [<type name> → <type name>]`. | Returns a `422 - Unprocessable Entity` error. |

### Inconsistent Input

| **Title** | **Description** | **Expected Behavior** |
| - | - | - |
| Source and/or Target ID of a relation not found | If either the source ID or the target ID of a relation cannot be found within Qbilon, the relation is dismissed and a warning with additional information is included in the response. | Relation is dismissed and warning is included in the response. |
| `nameAttribute` does not exist for an asset or relation | If the `nameAttribute` you provided is not available for an asset or relation, Qbilon falls back to using the `Qbilon ID`, which is always available. | Falls back to `Qbilon ID`. |
| Mismatch between incoming datatype and persisted datatype | If the datatype for an incoming attribute doesn't match the persisted datatype, Qbilon tries to cast the value. If that fails, the property is skipped. | Warning is issued, property is skipped if automatic cast fails. |
| Mismatching update strategy | If the update strategy does not match the datatype for an attribute (e.g., `LIST_KEEP_NEWEST_30` for a Text attribute), Qbilon sets the update strategy to `UPDATE_IF_NO_VALUE_PRESENT`. | Warning is issued, update strategy is corrected to `UPDATE_IF_NO_VALUE_PRESENT`. |
| Writing with System's `taskId` | If you try to write data with the reserved `taskId` value `-1`, you will receive a 403 - Forbidden error. | Returns a `403 - Forbidden` error. |
| Writing with a non-existent `taskId` | If you try to write data with a validly encoded but non-existent `taskId` , you will receive a 404 - Not Found error. | Returns a `404 - Not Found` error. |
| Two incoming assets with the same ID | If you provide two assets with the same ID in one write operation, Qbilon will skip both assets and issue a warning. | Warning is issued, both assets are skipped. |
| Valid but non-existent `qbilonId` | If you provide a validly encoded `qbilonId` but no asset exists for that ID, Qbilon will skip the asset and issue a warning. | Warning is issued, asset is skipped. |
| Writing system properties | If you try to write system properties such as `Data Sources`, `Qbilon ID`, `First Seen`, or `Last Seen`, Qbilon will skip these properties and issue a warning. | Warning is issued, properties are skipped. |
| Relation source or target type does not match relation's type | If you provide a relation that mismatches the source or target type of the relation, Qbilon will correct the relation accordingly. | Relation is corrected accordingly. |


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