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) 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: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: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:
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:
The “nameAttribute” Field
The fieldnameAttribute 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.
The “attributes” Field
The fieldattributes 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.
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 fielddatatype within an attribute definition is optional. Allowed data types are:
TextNumberBooleanDateTimeList<Text|Number|Boolean|DateTime>
Please note that the names of the data types are case sensitive.
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 fieldupdateStrategy 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.
Name property of “Server 1” to “Server 2”, just send the following JSON text to the upsert endpoint with the same taskId as before:
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:
If you are missing an update behavior for your use case, then don’t hesitate to reach out to us.
The “elements” Field
Theelements 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 intypes 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].
