API Reference
/businessnxtapi/apireference
section
Reference documentation for the Business NXT GraphQL schema, features, and extensions for working with DMEs.
2026-07-10T12:31:03+03:00
# API Reference
Reference documentation for the Business NXT GraphQL schema, features, and extensions for working with DMEs.
This section provides a comprehensive documentation of the Business NXT GraphQL API. In this section you will find:
- [Schema](./schema) documentation that details how to perform queries and mutations, how to execute asynchronous requests, how to fetch model information, and many others.
- [Features](./features) such as filtering, pagination, sorting, aliases, directives, fragments, and more
- [Extensions](./extensions) that enable you to work with data model extensions (DMEs)
- [Error handling](errors.md) information for understanding and managing errors that may occur
- [Rate limiting](ratelimits.md) information for understanding the rate limits that apply to your API usage
Schema
/businessnxtapi/apireference/schema
section
Details the Business NXT GraphQL schema, Relay-like, exposing system and company databases with types named after tables, supporting queries and mutations.
2026-07-10T12:31:03+03:00
# Schema
Details the Business NXT GraphQL schema, Relay-like, exposing system and company databases with types named after tables, supporting queries and mutations.
The Business NXT data model is exposed through a GraphQL schema. The schema defines the set of types that describe the set of possible data you can query from the service. Schemas are built with types (scalar, enumerations, union, input), objects, lists, arguments, intefaces, and other concepts. You can learn more about schemas and types in the [GraphQL schemas and types documentation](https://graphql.org/learn/schema/).
Business NXT GraphQL uses a [Relay](https://relay.dev/)-like schema, although not fully compliant. Relay is a specification for defining the GraphQL schema used at Facebook (where GraphQL was created) and open sourced. You can read more about improving your GraphQL schema with the Relay specification [in this article](
https://itnext.io/improve-your-graphql-schema-with-the-relay-specification-8952d06998eb). The Business NXT GraphQL API implementation differs from the Relay specification by not providing the `Node` base type and the `edges` field for a type.
The Business NXT data model is formed of two database types:
- a system database, containing information such as companies and company groups, users and user groups, folders, windows, active session, and various other data that applies to the whole application
- a company database, containing company specific information (such as associates, general ledger accounts, orders, vouchers, and many others)
Every table in the database model, regardless it's a system or company table, is exposed in the schema with a type that has the same name as the table (the name that appears in the model, not the actual SQL name in the database). This type includes the table columns and their type, as well as relations to other columns. For instance, the table for the general leger accounts is available through the type called `GeneralLedgerAccount`. However, the schema defines different sets of types for queries and mutations.
Queries
/businessnxtapi/apireference/schema/queries
section
Learn how to read data using the query request in the Business NXT schema. For data modifications, refer to Mutation Type documentation.
2026-07-10T12:31:03+03:00
# Queries
Learn how to read data using the query request in the Business NXT schema. For data modifications, refer to Mutation Type documentation.
The Business NXT schema supports reading data (with a `query` request) as well as modifying data (with a `mutation` request). These two operations are exposed at the top of the schema with the `query` and `mutation` fields, as shown in the following image:
Here, you will learn about reading data. For inserts, updates, and deletes, see [The Mutation Type](../mutations/mutation.md).
The Query Type
/businessnxtapi/apireference/schema/queries/query
page
GraphQL Query type enables querying various tables with fields like useCompany for company data and useCustomer for system information.
2026-07-10T12:31:03+03:00
# The Query Type
GraphQL Query type enables querying various tables with fields like useCompany for company data and useCustomer for system information.
## Overview
The `Query` type is the root for all types used when you do a query (read) operation. This type contains the following fields:
| Field | Description |
| ----- | ----------- |
| `useCompany` | The entry point for accessing company tables. Has a single argument, the Visma.net company ID. |
| `useCustomer` | The entry point for accessing system tables. Has a single argument, the Visma.net customer ID. |
| `useModel` | The entry point for accessing model information. See [Model information](../modelinfo.md). |
| `asyncRequests` and `asyncResult` | See [Async queries](../async.md). |
| `availableCustomers` | See [Fetching user's available companies](../companies.md). |
| `availableCompanies` | See [Fetching user's available customers](../customers.md). |
Accessing company tables requires specifying a company number. Similarly, accessing a system table requires specifying a customer number. These are the Visma.net identifiers for the company and the customer and can be either found in the Visma.net portal or can be retrieved with a query (see the links mentioned above).
The following images show (partially), side-by-side, the `Query_UseCustomer` type, containing the system table connections, and the `Query_UseCompany` type containing company table connections. These are the types for the fields `useCustomer` and `useCompany`, that are top level fields of the `Query` type.
| System table | Company table |
| ----------- | --- |
|  |  |
## Understanding connection types
If you look at the types in these images, you will see they are named `Query_UseCustomer_ServiceAccount_Connection`, `Query_UseCompany_Associate_Connection`, `Query_UseCompany_GeneralLedgedAccount_Connection`, etc. These names have the following pattern: `__Connection`.
Here is how the `Query_UseCompany_GeneralLedgedAccount_Connection` type looks in the GraphiQL document explorer:
So, *what is a connection?* To understand this concept, let's consider the following example. When you want to query for records in this table, you do the following in GraphQL:
```graphql
generalLedgerAccount
{
items
{
accountNo
name
# more columns
}
}
```
What you can see here is that the table columns are available under a node called `items`, that is an array of values (in the example above of the type `GeneralLedgerAccount`). This makes it possible to add add other relevant information for a query, appart from the table columns. This also protects the schema against possible future changes; adding a new field would not break existing queries.
Every type representing a table has two more fiels: `totalCount` (representing the total number of records in the table that match the filter but ignoring pagination) and `pageInfo` that provides information to aid in pagination. These topics are addressed later in this document. Therefore, the shape of a table type is the following:
```graphql
generalLedgerAccount
{
totalCount
pageInfo
{
hasNextPage
hasPreviousPage
startCursor
endCursor
}
items
{
accountNo
name
# more columns
}
}
```
> [!TIP]
>
> Keep in mind that all of these fields are optional when making a query. The result will contain only the information that has been requested. This is a key feature of GraphQL, which makes it preferable to other web service architectures.
A GraphQL type that has this particular shape, with the fields `totalCount`, `pageInfo`, and `items`, is called a *connection*. The following image shows how the type `Query_UseCompany_GeneralLedgerAccount_Connection` looks in the GraphiQL Explorer:
The name of this type is prefixed with `Query_UseCompany` because that is the name of the parent type, and is suffixed with `_Connection` to indicate this is a connection type.
## Understanding column descriptions
When you look at the schema documentation in the Documentation Explorer in GraphiQL, for instance, you will see that each table field has a description. This description contains the SQL column name and the column identifier to help those already familiar with desktop Visma Business programming model that build integrations with the Business NXT API. The description can be preceeded by some tags, such as in `[PK] AcNo/1480`. These tags have the following meaning:
| Tag | Description |
| --- | ----------- |
| `[PK]` | Primary key |
| `[M]` | Memory column (not physically present in the database) |
| `[Fn/a]` | Formula not available for a memory column |
| `[B]` | Blob field whose value is returned as a base64-encoded string |
| `[S(n)]` | Limited string of maximum `n` characters |
For insert/update operations, for limited string fields, if the value exceeds the defined maximum size, the value is truncated.
## Accessing company tables
The general ledger account that we saw previously is a company table, therefore, when querying for it, you must specify the company first, which is done with the `useCompany` field. This field's type is `Query_UseCompany` and this is the parent for all company table connection types.
In order to query a company table, you must specify its Visma.net identifier. Let's look at an example:
```graphql { title = "Query" }
query
{
useCompany(no: 9112233)
{
generalLedgerAccount
{
totalCount
pageInfo
{
hasNextPage
hasPreviousPage
startCursor
endCursor
}
items
{
accountNo
name
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"generalLedgerAccount": {
"totalCount": 340,
"pageInfo": {
"hasNextPage": false,
"hasPreviousPage": false,
"startCursor": "MA==",
"endCursor": "MzQw"
},
"items": [
{
"accountNo": 1000,
"name": "Forskning og utvikling"
},
{
"accountNo": 1020,
"name": "Konsesjoner"
},
{
"accountNo": 1030,
"name": "Patenter"
},
{
"accountNo": 9999,
"name": "Observasjonskonto"
}
]
}
}
}
}
```
## Accessing system tables
Tables such as `User` and `Company`, which are system tables, are available from the `useCustomer` field, whose type is `Query_UseCustomer`. This is the parent type for all the system table connection types.
The connection type name for the `User` table is `Query_UseCustomer_User_Connection` and for the `Company` table is `Query_UseCustomer_Company_Connection`. The format for all system tables type names is `Query_UseCustomer__Connection`.
In order to query a system table, you must specify a customer's Visma.net identifier. Let's look at an example:
```graphql { title = "Query" }
query
{
useCustomer(no: 1111111)
{
user
{
items
{
userName
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCustomer": {
"user": {
"items": [
{
"userName": "john.doe"
},
{
"userName": "jane.doe"
},
{
"userName": "boaty.bcboatface"
}
]
}
}
}
}
```
## Joining tables
Tables, regardless they are system or company tables, have relationships with other tables. These could be either one-to-one or one-to-many. For example, the window (from the `Win` table) has an one-to-one relation to a folder (from the `Fldr` table). The field `FldrNo` (2495) in the `Win` table, appearing as `folderNo` in the schema, is a foreign key to the `FldrNo` (2482) in the `Fldr` table, appearing as `folderNo` in the GraphQL schema. The schema makes it possible to easily join these related tables based on these relationships. Such a relationship has an *upwards* direction and in our GraphQL API are available through nodes prefixed with `joinup`. The opposite are one-to-many relations, such as from an order to order lines. These have a *downwards* direction and are available through nodes prefixed with `joindown`.
An example for such a upwards join to a related table is show below. We fetch for the first three windows, the layout name and the number and name of the related folder.
```graphql { title = "Query" }
query
{
useCustomer(no: 1111111)
{
window(first: 3)
{
items
{
layoutName
joinup_Folder
{
folderNo
name
}
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCustomer": {
"window": {
"items": [
{
"layoutName": "10201. Purrebrev 1*",
"joinup_Folder": {
"folderNo": 18,
"name": "102. Utskriftsoppsett"
}
},
{
"layoutName": "10202. Purrebrev 2*",
"joinup_Folder": {
"folderNo": 18,
"name": "102. Utskriftsoppsett"
}
},
{
"layoutName": "10203. Rentenota 1*",
"joinup_Folder": {
"folderNo": 18,
"name": "102. Utskriftsoppsett"
}
}
]
}
}
}
}
```
In this example, the node name was `joinup_Folder`, there `Folder` is the name of the table that we joined from `Window`. Sometimes, a table can be joined from another via multiple relations. An example is the `Associate` table that can be joined via a customer, supplier, employee, or other relations. In this case, when multiple relations are available the node name has the form `joinup__via_`. For the mentioned example, these names are `joinup_Associate_via_Customer`, `joinup_Associate_via_Supplier`, `joinup_Associate_via_Employee`, etc. The example with `joinup_Folder` is a particular case of this general form, when the table and relation have the same name. For such cases the node name has the form `joinup_` (to avoid namings such as `joinup_Folder_via_Folder` which is unnecessarily repetitive).
In the next example, the `Associate` table is joined upwards twice from the `Order` table, once via the `Customer` relation, and once via the `Employee` relation.
```graphql { title = "Query" }
{
useCompany(no:9112233)
{
order(first: 2)
{
items
{
orderNo
customerNo
employeeNo
joinup_Associate_via_Customer
{
associateNo
customerNo
name
}
joinup_Associate_via_Employee
{
associateNo
employeeNo
name
}
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"order": {
"items": [
{
"orderNo": 1,
"customerNo": 10010,
"employeeNo": 101,
"joinup_Associate_via_Customer": {
"associateNo": 11,
"customerNo": 10010,
"name": "Nordic Designers"
},
"joinup_Associate_via_Employee": {
"associateNo": 967,
"employeeNo": 101,
"name": "Erika Karlson"
}
},
{
"orderNo": 2,
"customerNo": 10123,
"employeeNo": 114,
"joinup_Associate_via_Customer": {
"associateNo": 336,
"customerNo": 10123,
"name": "Lars Erikson"
},
"joinup_Associate_via_Employee": {
"associateNo": 425,
"employeeNo": 114,
"name": "Daniel Gunnarson"
}
}
]
}
}
}
}
```
For one-to-many relations, that have a downwards direction from parent to child, the prefixed, as mentioned above is `joindown`. The rest of the name format is the same, the general form being `joindown__via_`. When the table and the relation name are the same, the form is simplified to `joindown_`. However, the relation being one-to-many, the result is not a single record but an array of them. This is modeled in the API through connections. Therefore, a node such as `joindown_Translation_via_Window` or `joindown_OrderLine_via_Order` are *connections*.
We can see this in the following example, where we fetch the layout name of the first three windows, as well as the tag and Norwegian text from the translations table.
```graphql { title = "Query" }
query
{
useCustomer(no: 1111111)
{
window(first: 3)
{
items
{
layoutName
joindown_Translation_via_Window
{
items
{
tag
norwegian
}
}
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCustomer": {
"window": {
"items": [
{
"layoutName": "10201. Purrebrev 1*",
"joindown_Translation_via_Window": {
"items": [
{
"tag": "10201. Purrebrev 1*",
"norwegian": "10201. Purrebrev 1*"
},
{
"tag": "",
"norwegian": "10201. Purrebrev 1*"
}
]
}
},
{
"layoutName": "10202. Purrebrev 2*",
"joindown_Translation_via_Window": {
"items": [
{
"tag": "10202. Purrebrev 2*",
"norwegian": "10202. Purrebrev 2*"
},
{
"tag": "",
"norwegian": "10202. Purrebrev 2*"
}
]
}
},
{
"layoutName": "10203. Rentenota 1*",
"joindown_Translation_via_Window": {
"items": [
{
"tag": "10203. Rentenota 1*",
"norwegian": "10203. Rentenota 1*"
},
{
"tag": "",
"norwegian": "10203. Rentenota 1*"
}
]
}
}
]
}
}
}
}
```
A second example shows a query to the order table that is joined with the oder line table. We retrieve the first 10 orders and for each order the first three lines. We also fetch the total number of orders and for each order, the total number of lines.
```graphql { title = "Query" }
{
useCompany(no: 9112233)
{
order(first: 10)
{
totalCount
items
{
orderNo
joindown_OrderLine_via_Order(first: 3)
{
items
{
lineNo
amountDomestic
}
}
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"order": {
"totalCount": 1340,
"items": [
{
"orderNo": 1,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1,
"amountDomestic": 100
},
{
"lineNo": 2,
"amountDomestic": 250
}
]
}
},
{
"orderNo": 2,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1,
"amountDomestic": 980
},
{
"lineNo": 2,
"amountDomestic": 1500
},
{
"lineNo": 3,
"amountDomestic": 1999
}
]
}
},
...
]
}
}
}
}
```
> [!WARNING]
>
> Because the execution of queries for joined tables is optimized for performance, the `totalCount` and pagination does not work as described in this document. To understand the problem and the workaround see [Unoptimized queries](../../features/unoptimized.md).
## Parameters
In the previous examples we have seen the use of the `first` parameter when querying various tables. This is not the only available argument. Each connection type has several parameters, which are as follows:
- `first` and `after` (and optionally `skip`) for forward pagination (see [Pagination](../../features/pagination.md))
- `last` and `before` (and optionally `skip`) for backward pagination (see [Pagination](../../features/pagination.md))
- `filter` for filtering data (see [Filtering](../../features/filtering.md))
- `distinct` for returning only distinct values (see [Distinct](./distinct.md))
- `orderBy` for sorting the results (see [Sorting](../../features/sorting.md))
- `groupBy` for grouping the results (see [Grouping](./grouping.md))
- `having` for filtering the results after grouping (see [Grouping](./grouping.md))
- `unoptimized` for performing unoptimized request for some category of queries for joined tables that could potentially return incorrent results otherwise (see [Unoptimized queries](../../features/unoptimized.md))
These parameters will be described in the *GraphQL Features* sections.
Grouping
/businessnxtapi/apireference/schema/queries/grouping
page
API documentation on grouping data, including SQL examples, GraphQL equivalents, and parameters for filtering, sorting, paginating, and applying aggregate functions.
2026-07-10T12:31:03+03:00
# Grouping
API documentation on grouping data, including SQL examples, GraphQL equivalents, and parameters for filtering, sorting, paginating, and applying aggregate functions.
## Overview
An important scenario when working with data is grouping. Grouping allows you to aggregate data based on a specific column or columns. This enables fetching summary of data based on various aggregate functions.
For example, you may want to group orders by the customer column and then count the number of orders and their total value in each group. In SQL, this can be done using the `GROUP BY` clause as follows:
```sql
SELECT CustNo, Count([OrdNo]), SUM(DNOrdSum)
FROM [Ord]
GROUP BY CustNo
```
When grouping data, you can select:
- The columns that you want to group by. The rows with the same value in the selected columns are grouped together.
- The aggregate functions that you want to apply to the grouped data. The aggregate functions are applied to the columns that are not included in the `GROUP BY` clause.
Because the `WHERE` clause is evaluated before the `GROUP BY` clause, you can use the `WHERE` clause to filter the rows that are included in the grouping. For instance, if we want to take into account only the orders in a specific interval (let's say the current month) we can apply a filter as follows:
```sql
SELECT CustNo, Count(OrdNo), SUM(DNOrdSum)
FROM Ord
WHERE ChDt > 20231101
GROUP BY CustNo
```
However, filtering the rows in the `WHERE` clause is not always possible. For instance, if we want to retrieve data only for customers that made purchases over some specific amount, we cannot use the `WHERE` clause because the aggregated sum is not a table column.
In this case, we can use the `HAVING` clause to filter the groups. The `HAVING` clause is evaluated after the `GROUP BY` clause and it can be used to filter the groups based on aggregate functions.
An example is shown here:
```sql
SELECT CustNo, Count(OrdNo), SUM(DNOrdSum)
FROM Ord
WHERE ChDt > 20231101
GROUP BY CustNo
HAVING SUM(DNOrdSum) > 1000
```
You can also specify a sorting order for the resulting data using the `SORT BY` clause. The `SORT BY` clause is evaluated after the `HAVING` clause.
In the following example, data is sorted ascending by the customer number.
```sql
SELECT CustNo, Count(OrdNo), SUM(DNOrdSum)
FROM Ord
WHERE ChDt > 20231101
GROUP BY CustNo
HAVING SUM(DNOrdSum) > 1000
SORT BY CustNo ASC
```
The capabilities to group data and filter based on aggregate functions in available in Business NXT GraphQL API as well. The following sections describe how to use the `groupBy` and `having` clauses in Business NXT GraphQL.
## The connection type
In the previous section, we learned about the connection types and how to perform queries using them. Every connection types has a set of parameters that allows to filter, sort, paginate, but also group. An example is shown in the following image for the `order` table:
The following parameters can be used to group data:
| Parameter | Description |
| --------- | ----------- |
| `filter` | Specifies the filter expression. The filter expression is evaluated before the `groupBy` clause. |
| `groupBy` | Specifies the columns that you want to group by. The rows with the same value in the selected columns are grouped together. |
| `having` | Specifies the aggregate functions that you want to apply to the grouped data. The aggregate functions are applied to the columns that are not included in the `groupBy` clause. The `having` clause is applied to the data after grouping. |
| `orderBy` | Specifies the sort order of the grouped data. |
Additionally, the paginations arguments can be used to paginate the grouped data. The page size arguments `first` and `last` count groups, not underlying rows, and the `after` and `before` cursors page through the groups.
## Grouping data
The following example shows how to group data using the `groupBy` parameter. The example groups the orders by the customer number and then counts the number of orders and their total value in each group.
```graphql { title = "Query" }
query read_grouped_orders($cid : Int)
{
useCompany(no : $cid)
{
order(
groupBy : [{customerNo : DEFAULT}])
{
items
{
customerNo
aggregates
{
count
{
orderNo
}
sum
{
orderSumNetDomestic
}
}
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"order": {
"items": [
{
"customerNo": 0,
"aggregates": {
"count": {
"orderNo": 111
},
"sum": {
"orderSumNetDomestic": 3195
}
}
},
{
"customerNo": 10125,
"aggregates": {
"count": {
"orderNo": 1
},
"sum": {
"orderSumNetDomestic": 0
}
}
},
...
]
}
}
}
}
```
To filter the date, you can use the `filter` parameter. The following example groups the purchase orders by the customer number and then counts the number of orders and their total value in each group. The orders are filtered by amount, which must be positive, and by the order date.
```graphql { title = "Query" }
query read_grouped_orders($cid : Int)
{
useCompany(no : $cid)
{
order(
filter : {_and : [
{orderSumNetDomestic : {_gt : 0}},
{orderDate : {_gt : 20210101}},
{customerNo : {_not_eq : 0}}
]},
groupBy : [{customerNo : DEFAULT}])
{
items
{
customerNo
aggregates
{
count
{
orderNo
}
sum
{
orderSumNetDomestic
}
}
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"order": {
"items": [
{
"customerNo": 10000,
"aggregates": {
"count": {
"orderNo": 289
},
"sum": {
"orderSumNetDomestic": 305400
}
}
},
{
"customerNo": 10001,
"aggregates": {
"count": {
"orderNo": 3
},
"sum": {
"orderSumNetDomestic": 58047
}
}
},
...
]
}
}
}
}
```
You can also filter the aggregated data by using the `having` parameter. The following example groups the purchase orders by the customer number and then counts the number of orders and their total value in each group. The orders are filtered by amount, which must be positive, and by the order date. The aggregated data is filtered by the total value of the orders, which must be greater than 100000.
```graphql { title = "Query" }
query read_grouped_orders($cid : Int)
{
useCompany(no : $cid)
{
order(
filter : {_and : [
{orderSumNetDomestic : {_gt : 0}},
{orderDate : {_gt : 20210101}},
{customerNo : {_not_eq : 0}}
]},
groupBy : [{customerNo : DEFAULT}],
having : {
_sum : {
orderSumNetDomestic : {_gt : 100000}
}
})
{
items
{
customerNo
aggregates
{
count
{
orderNo
}
sum
{
orderSumNetDomestic
}
}
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"order": {
"items": [
{
"customerNo": 10000,
"aggregates": {
"count": {
"orderNo": 289
},
"sum": {
"orderSumNetDomestic": 305400
}
}
},
{
"customerNo": 10285,
"aggregates": {
"count": {
"orderNo": 186
},
"sum": {
"orderSumNetDomestic": 312975
}
}
}
]
}
}
}
}
```
Finally, you can also sort the data using the `orderBy` parameter. The following example, expands the previous one by retrieving the data sorted by descending customer number.
```graphql { title = "Query" }
query read_grouped_orders($cid : Int)
{
useCompany(no : $cid)
{
order(
filter : {_and : [
{orderSumNetDomestic : {_gt : 0}},
{orderDate : {_gt : 20210101}},
{customerNo : {_not_eq : 0}}
]},
groupBy : [{customerNo : DEFAULT}],
having : {
_sum : {
orderSumNetDomestic : {_gt : 100000}
}
},
orderBy : [{customerNo : DESC}])
{
items
{
customerNo
aggregates
{
count
{
orderNo
}
sum
{
orderSumNetDomestic
}
}
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"order": {
"items": [
{
"customerNo": 10285,
"aggregates": {
"count": {
"orderNo": 186
},
"sum": {
"orderSumNetDomestic": 312975
}
}
},
{
"customerNo": 10000,
"aggregates": {
"count": {
"orderNo": 289
},
"sum": {
"orderSumNetDomestic": 305400
}
}
}
]
}
}
}
}
```
## The groupBy argument
The type of the group by argument is an array of non-null objects of the type `_GroupByType`. An example is `Order_GroupByType` for the `Order` table. Each element of the array specifies one column for grouping. Their order in the `GROUP BY` clause is the one in which they appear in the array. Let's take the following example:
```graphql
groupBy : [{customerNo : DEFAULT}, {orderDate : DEFAULT}]
```
This groups the data by the `customerNo` and the `orderDate` columns.
When you specify a column for grouping, you must also specify the kind of grouping that you want to perform. The possible values are:
| Value | Description |
| ----- | ----------- |
| `DEFAULT` | The default grouping. The rows with the same value in the column are grouped together. |
| `ROLLUP` | The `ROLLUP` grouping. This creates a group for each combination of column expressions and also rolls up the results into subtotals and grand totals. |
While the column order is not important for the `DEFAULT` grouping, it is important for the `ROLLUP` grouping. For instance, `GROUP BY ROLLUP (A, B, C)` creates groups for each combination of column expressions as show in the following list:
```
A, B, C
A, B, NULL
A, NULL, NULL
NULL, NULL, NULL
```
To learn more about the `ROLLUP` grouping, see the [SELECT - GROUP BY- Transact-SQL](https://docs.microsoft.com/en-us/sql/t-sql/queries/select-group-by-transact-sql?view=sql-server-ver15#rollup) documentation.
To show how this work, lets take the following example: select transactions grouped by account number and period.
First, we use `DEFAULT` for account number and `ROLLUP` for `period`:
```graphql { title = "Query" }
query read_gla_transactions_grouped($cid : Int)
{
useCompany(no : $cid)
{
generalLedgerTransaction(
filter : {
_and: [
{accountNo : {_gte : 3000}},
{year : {_gte : 2020}}
]},
groupBy: [
{accountNo : DEFAULT},
{period : ROLLUP},
],
having : {
_sum : {postedAmountDomestic : {_not_eq : 0}}
})
{
items
{
accountNo
period
aggregates
{
sum
{
postedAmountDomestic
}
}
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"generalLedgerTransaction": {
"items": [
{
"accountNo": 3000,
"period": 12,
"aggregates": {
"sum": {
"postedAmountDomestic": -4950
}
}
},
{
"accountNo": 3000,
"period": 0,
"aggregates": {
"sum": {
"postedAmountDomestic": -4950
}
}
},
{
"accountNo": 4000,
"period": 12,
"aggregates": {
"sum": {
"postedAmountDomestic": 450
}
}
},
{
"accountNo": 4000,
"period": 0,
"aggregates": {
"sum": {
"postedAmountDomestic": 450
}
}
},
{
"accountNo": 4410,
"period": 12,
"aggregates": {
"sum": {
"postedAmountDomestic": 13035
}
}
},
{
"accountNo": 4410,
"period": 0,
"aggregates": {
"sum": {
"postedAmountDomestic": 13035
}
}
}
]
}
}
}
}
```
Due to the applied filter, the result includes the account numbers 3000, 4000, and 4410 and the period 12.
The result is a series of groups for the following combinations:
| Account number | Period |
| -------------- | ------ |
| 3000 | 12 |
| 3000 | 0 |
| 4000 | 12 |
| 4000 | 0 |
| 4410 | 12 |
| 4410 | 0 |
Next, we change the grouping type use `ROLLUP` for account number and `DEFAULT` for `period`:
```graphql { title = "Query" }
query read_gla_transactions_grouped($cid : Int)
{
useCompany(no : $cid)
{
generalLedgerTransaction(
filter : {
_and: [
{accountNo : {_gte : 3000}},
{year : {_gte : 2020}}
]},
groupBy: [
{accountNo : ROLLUP},
{period : DEFAULT},
],
having : {
_sum : {postedAmountDomestic : {_not_eq : 0}}
})
{
items
{
accountNo
period
aggregates
{
sum
{
postedAmountDomestic
}
}
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"generalLedgerTransaction": {
"items": [
{
"accountNo": 3000,
"period": 12,
"aggregates": {
"sum": {
"postedAmountDomestic": -4950
}
}
},
{
"accountNo": 4000,
"period": 12,
"aggregates": {
"sum": {
"postedAmountDomestic": 450
}
}
},
{
"accountNo": 4410,
"period": 12,
"aggregates": {
"sum": {
"postedAmountDomestic": 13035
}
}
},
{
"accountNo": 0,
"period": 12,
"aggregates": {
"sum": {
"postedAmountDomestic": 8535
}
}
}
]
}
}
}
}
```
The result is a series of groups for the following combinations:
| Account number | Period |
| -------------- | ------ |
| 3000 | 12 |
| 4000 | 12 |
| 4410 | 12 |
| 0 | 12 |
Finally, let's use `ROLLUP` for both account number and period:
```graphql { title = "Query" }
query read_gla_transactions_grouped($cid : Int)
{
useCompany(no : $cid)
{
generalLedgerTransaction(
filter : {
_and: [
{accountNo : {_gte : 3000}},
{year : {_gte : 2020}}
]},
groupBy: [
{accountNo : ROLLUP},
{period : ROLLUP},
],
having : {
_sum : {postedAmountDomestic : {_not_eq : 0}}
})
{
items
{
accountNo
period
aggregates
{
sum
{
postedAmountDomestic
}
}
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"generalLedgerTransaction": {
"items": [
{
"accountNo": 3000,
"period": 12,
"aggregates": {
"sum": {
"postedAmountDomestic": -4950
}
}
},
{
"accountNo": 3000,
"period": 0,
"aggregates": {
"sum": {
"postedAmountDomestic": -4950
}
}
},
{
"accountNo": 4000,
"period": 12,
"aggregates": {
"sum": {
"postedAmountDomestic": 450
}
}
},
{
"accountNo": 4000,
"period": 0,
"aggregates": {
"sum": {
"postedAmountDomestic": 450
}
}
},
{
"accountNo": 4410,
"period": 12,
"aggregates": {
"sum": {
"postedAmountDomestic": 13035
}
}
},
{
"accountNo": 4410,
"period": 0,
"aggregates": {
"sum": {
"postedAmountDomestic": 13035
}
}
},
{
"accountNo": 0,
"period": 0,
"aggregates": {
"sum": {
"postedAmountDomestic": 8535
}
}
}
]
}
}
}
}
```
This time, we get the following combinations:
| Account number | Period |
| -------------- | ------ |
| 3000 | 12 |
| 3000 | 0 |
| 4000 | 12 |
| 4000 | 0 |
| 4410 | 12 |
| 4410 | 0 |
| 0 | 0 |
## The having argument
The type of the `having` argument is an object of the type `_HavingType`. An example is `Order_HavingType` for the `Order` table. The `having` clause is applied to the data after grouping and defines filters on aggregated data. The `_HavingType` type has the following fields:
- all the columns in the table
- all the available aggregate functions, such as `SUM` and `COUNT`, but prefixed with an underscore: `_sum`, `_count`, etc.
- `_and` and `_or` operators that allow to combine multiple conditions
The available aggregate functions are listed in the following table:
| Aggregate | Column types | Description |
| --------- | ------------ | ----------- |
| `sum` | numerical | The sum of all the values. |
| `sumDistinct` | numerical | The sum of all distinct values. |
| `average` | numerical | The average of all the values. |
| `averageDistinct` | numerical | The averate of all distinct values. |
| `count` | all | The number of the items. |
| `countDistinct` | all | The number of distinct items. |
| `minimum` | numerical, date, time | The minimum value. |
| `maximum` | numerical, date, time | The maximum value. |
| `variance` | numerical | The statistical variance of all the values. |
| `varianceDistinct` | numerical | The statistical variance of all the distinct values. |
| `variancePopulation` | numerical | The statistical variance for the population of all the values. |
| `variancePopulationDistinct` | numerical | The statistical variance for the population of all the distinct values. |
| `standardDeviation` | numerical | The statistical standard deviation of all the values. |
| `standardDeviationDistinct` | numerical | The statistical standard deviation of all the distinct values. |
| `standardDeviationPopulation` | numerical | The statistical standard deviation for the population of all the values. |
| `standardDeviationPopulationDistinct` | numerical | The statistical standard deviation for the population of all the distinct values. |
In the previous example we have used this condition:
```graphql
having : {_sum : {orderSumNetDomestic : {_gt : 100000}}}
```
This is equivalent to the following SQL clause:
```sql
HAVIG SUM(DNOrdSum) > 100000
```
Because of the nature of GraphQL, the order of fields is:
1. aggregate function (AF)
2. column name (COL)
3. operator (OP)
4. value
Therefore, the specification `{AF : {COL : {OP : value}}}` is translated to `AF(COL) OP value` and not `AF(COL OP value)`.
You can build complex filters such as the following where we select all the groups either have the count of orders greater than 100 or the sum of the order values is between 100000 and 200000:
```graphql
having : {
_or: [
{_count :{orderNo : {_gt : 100}}},
{
_and : [
{_sum : {orderSumNetDomestic : {_gt : 100000}}},
{_sum : {orderSumNetDomestic : {_lt : 200000}}},
]
}
]
}
```
> [!TIP]
>
> The operators used in `having` clauses are the same used for filter expressions (for the `filter` argument). To learn more about these, see [Filtering](../../features/filtering.md).
For the `_count` and `_countDistinct` aggregate functions, the type used for comparing is `Int`, regardless of the type of the column.
That is because an expression such as `_count :{orderNo : {_gt : 100}` translates to `COUNT(orderNo) > 100` and not `COUNT(orderNo > 100)`.
## The orderBy argument
The `orderBy` argument can be used to specify the sort order of the grouped data. The type of the `orderBy` argument is an array of non-null objects of the type `OrderBy_`. An example is `OrderBy_ProductTransaction` for the `ProductTransaction` table.
Each element of the array specifies one column for sorting and the sort direction (ascending or descending).
The order of the elements in the array defines the priority of the sorting.
Ordering supports the aggregate functions listed above.
The following example show how to group the results by the customer number and order it by the sum of the `amountDomestic` column (in descending order):
```graphql
query OrderbyGrouped($companyNo: Int!)
{
useCompany(no: $companyNo)
{
productTransaction(
groupBy: {customerNo: DEFAULT},
orderBy: [{_sum: {amountDomestic: DESC}}])
{
items
{
customerNo
aggregates
{
sum
{
amountDomestic
}
}
}
}
}
}
```
If you try to use the `orderBy` argument with aggregates without specifying the `groupBy` argument, you will get an error:
```
Aggregate orderBy (e.g. _sum, _average, _minimum, _maximum, _count) is only valid on grouped queries. Add a groupBy argument.
```
## Limitations
There are also some limitations when grouping data that you must be aware of:
- You cannot group by or filter data from a joined table.
Aggregates
/businessnxtapi/apireference/schema/queries/aggregates
page
Aggregate functions in GraphQL for computing values in table fields. Supports sum, average, count, min, max, variance, and more.
2026-07-10T12:31:03+03:00
# Aggregates
Aggregate functions in GraphQL for computing values in table fields. Supports sum, average, count, min, max, variance, and more.
> [!WARNING]
>
> This schema section is obsolete and will be removed in the future.
>
> Use grouping for fetching aggregated data. See [Grouping](./grouping.md) for more information.
Business NXT GraphQL supports computing aggregate values for table fields. Aggregate functions ignore null values in the tables. These are deterministic and return the same value each time that they are called. They are similar to the aggregate functions available in SQL. The supported aggregates are listed in the following table. The returned values are computed from the selection determined by provided filter. The filter is optional and if not specified all the records in the table are included.
| Aggregate | Column types | Description |
| --------- | ------------ | ----------- |
| `sum` | numerical | The sum of all the values. |
| `sumDistinct` | numerical | The sum of all distinct values. |
| `average` | numerical | The average of all the values. |
| `averageDistinct` | numerical | The averate of all distinct values. |
| `count` | numerical | The number of the items. |
| `countDistinct` | numerical | The number of distinct items. |
| `minimum` | numerical, date, time | The minimum value. |
| `maximum` | numerical, date, time | The maximum value. |
| `variance` | numerical | The statistical variance of all the values. |
| `varianceDistinct` | numerical | The statistical variance of all the distinct values. |
| `variancePopulation` | numerical | The statistical variance for the population of all the values. |
| `variancePopulationDistinct` | numerical | The statistical variance for the population of all the distinct values. |
| `standardDeviation` | numerical | The statistical standard deviation of all the values. |
| `standardDeviationDistinct` | numerical | The statistical standard deviation of all the distinct values. |
| `standardDeviationPopulation` | numerical | The statistical standard deviation for the population of all the values. |
| `standardDeviationPopulationDistinct` | numerical | The statistical standard deviation for the population of all the distinct values. |
Aggregates can be computed on all the tables that can be querried from GraphQL. Every field in the schema used to query a table (having the same name as the table) has a companion field used to execute aggregate functions. This field has the name format `_aggregate`. For example, for reading data from the orders table, there is a field called `order` and for reading aggregate values there is a field called `order_aggregate`.
The `_aggregate` field has a query argument that represents a filter. This is the same filter object used to query data from the table. This is documented in the [Filtering](../../features/filtering.md) page.
The type of the `_aggregate` field has the name format `Query__Aggregate_Node`. For instance, for the `order_aggregate` field the type name is `Query_UseCompany_OrderAggregate_Node`. This type contains one field for each aggregate function listed in the above table. This can be seen in the GraphiQL document explorer as follows:
The `minimum` and `maximum` fields are of a type with the name format `WithDateTimeAggregate`. This type includes fields that represent dates and times. The others fields have a different the type that only contains numerical columns. This type has the name format `Aggregate`. For instance, for the `Order` table, the type that includes dates and times is called `OrderWithDateTimeAggregate`, and the type that only includes numerical fields is called `OrderAggregate`.
| Only numerical fields | Numerical + Date/Time fields |
| --------------------- | ---------------------------- |
|  |  |
Executing aggregate functions is demonstrated with the following example:
```graphql { title = "Query" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
order_aggregate
{
count
{
orderNo
}
sum
{
orderSumNetDomestic
vatAmountDomestic
}
average
{
orderSumNetDomestic
vatAmountDomestic
}
minimum
{
orderDate
orderSumNetDomestic
vatAmountDomestic
}
maximum
{
orderDate
orderSumNetDomestic
vatAmountInCurrency
}
variance
{
orderSumNetDomestic
vatAmountDomestic
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"order_aggregate": {
"count": {
"orderNo": 344
},
"sum": {
"orderSumNetDomestic": 26930,
"vatAmountDomestic": 7952.5
},
"average": {
"orderSumNetDomestic": 73.174085,
"vatAmountDomestic": 19.363742
},
"minimum": {
"orderDate": 20130105,
"orderSumNetDomestic": 0,
"vatAmountDomestic": 0
},
"maximum": {
"orderDate": 20151205,
"orderSumNetDomestic": 21950,
"vatAmountInCurrency": 5487.5
},
"variance": {
"orderSumNetDomestic": 1529866.15103014,
"vatAmountDomestic": 93992.56825201
}
}
}
}
}
```
To include a filter, you need to specify it as an argument to the `order_aggregate` field, as shown here:
```graphql { title = "Query" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
order_aggregate(filter :
{
orderDate : {_gt : 20140101}
})
{
count
{
orderNo
}
sum
{
orderSumNetDomestic
vatAmountDomestic
}
average
{
orderSumNetDomestic
vatAmountDomestic
}
minimum
{
orderDate
orderSumNetDomestic
vatAmountDomestic
}
maximum
{
orderDate
orderSumNetDomestic
vatAmountInCurrency
}
variance
{
orderSumNetDomestic
vatAmountDomestic
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"order_aggregate": {
"count": {
"orderNo": 312
},
"sum": {
"orderSumNetDomestic": 25127,
"vatAmountDomestic": 6642.5
},
"average": {
"orderSumNetDomestic": 82.553134,
"vatAmountDomestic": 21.453173
},
"minimum": {
"orderDate": 20140102,
"orderSumNetDomestic": 0,
"vatAmountDomestic": 0
},
"maximum": {
"orderDate": 20151205,
"orderSumNetDomestic": 21145,
"vatAmountInCurrency": 5675.5
},
"variance": {
"orderSumNetDomestic": 1542331.617824,
"vatAmountDomestic": 95752.0148624473
}
}
}
}
}
```
Distinct values
/businessnxtapi/apireference/schema/queries/distinct
page
Guide to fetch distinct table values using distinct argument, translating into SQL. Examples include account groups, customers, and order types, with equivalent groupBy queries.
2026-07-10T12:31:03+03:00
# Distinct values
Guide to fetch distinct table values using distinct argument, translating into SQL. Examples include account groups, customers, and order types, with equivalent groupBy queries.
It is possible to fetch distinct values from a table using the `distinct` argument. This is a boolean parameter that must be set to `true` to enable distinct data fetching. This translates into the `SELECT DISTINCT` SQL statement.
The following example shows how to fetch the distinct account groups from the general ledger table:
```graphql { title = "Query" }
query read_distinct_account_groups($cid : Int!)
{
useCompany(no: $cid)
{
generalLedgerAccount(distinct : true)
{
items
{
accountGroup
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"generalLedgerAccount": {
"items": [
{
"accountGroup": ""
},
{
"accountGroup": "100K_FORSKNING_UTVIKLING"
},
{
"accountGroup": "102K_KONSESJON_PATENT_LISENSER"
},
{
"accountGroup": "107K_UTSATT_SKATTEFORDEL"
},
{
"accountGroup": "108K_GOODWILL"
}
...
]
}
}
}
}
```
It is possible to select distinct values for multiple fields. The following example shows how to distinct customers and order types from the order table:
```graphql { title = "Query" }
query read_orders($cid : Int!, $dt : Int) {
useCompany(no: $cid) {
order(
filter : {changedDate : {_gt : $dt}},
distinct : true,
first : 10)
{
pageInfo
{
hasNextPage
startCursor
endCursor
}
items
{
customerNo
orderType
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"order": {
"pageInfo": {
"hasNextPage": false,
"startCursor": "MQ==",
"endCursor": "NQ=="
},
"items": [
{
"customerNo": 0,
"orderType": 1
},
{
"customerNo": 10000,
"orderType": 1
},
{
"customerNo": 10001,
"orderType": 1
},
{
"customerNo": 10002,
"orderType": 2
},
{
"customerNo": 10286,
"orderType": 1
}
]
}
}
}
}
```
As mentioned before, the use of the `distinct` argument will produce a `SELECT DISTINCT` SQL statement for fetching data. The following two SQL statements are roughly equivalent:
```sql
SELECT DISTINCT a,b,c FROM T
```
```sql
SELECT a,b,c FROM T GROUP BY a,b,c
```
Therefore, the same results can be achieved, typically, by using the `groupBy` argument. The following example shows how to fetch the same distinct customers and order types from the order table using the `groupBy` argument:
```graphql { title = "Query" }
query read_orders($cid : Int!, $dt : Int) {
useCompany(no: $cid) {
order(
filter : {changedDate : {_gt : $dt}},
groupBy : [
{customerNo : DEFAULT},
{orderType : DEFAULT}
],
orderBy : [
{ customerNo : ASC },
{ orderType : DESC }
],
first : 10)
{
pageInfo
{
hasNextPage
startCursor
endCursor
}
items
{
customerNo
orderType
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"order": {
"pageInfo": {
"hasNextPage": false,
"startCursor": "MQ==",
"endCursor": "NQ=="
},
"items": [
{
"customerNo": 0,
"orderType": 1
},
{
"customerNo": 10000,
"orderType": 1
},
{
"customerNo": 10001,
"orderType": 1
},
{
"customerNo": 10002,
"orderType": 2
},
{
"customerNo": 10286,
"orderType": 1
}
]
}
}
}
}
```
> [!NOTE]
>
> When requesting distinct values, the `totalCount` field will still return the total number of records in the table that match the provided filter (if any was given), not the number of distinct records.
>
> It is recommended that you do not use `totalCount` when fetching distinct values, as it will indicate a misleading quantity.
## Obsolete distinct values
> [!WARNING]
>
> This schema section is obsolete and will be removed in the future.
>
> It is recommended to use the `distinct` argument for fetching distinct values, as described above.
An option to fetch distinct values of a field is also available under the [aggregates](./aggregates.md) field with a subfield called `distinct`.
Aggregate types have the name of the form `Aggregate`, such as `AssociateAggregate`.
On the other hand, the field used for fetching distinct values have their own type, using the format `Distinct`, such as `AssociateDistinct`.
The distinct type have the same fields as the aggregate types, which are the columns of the database tables. However, their type is a list of values and not a single value.
The following image shows a snippet of the `AssociateDistinct` type:
The following table shows an example for fetching the distinct post codes and country codes from the `Associate` table:
```graphql { title = "Query" }
query($cid:Int)
{
useCompany(no: $cid)
{
associate_aggregate
{
distinct
{
postCode
countryNo
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"associate_aggregate": {
"distinct": {
"postCode": [
"",
"AL20 0XX",
"AL3 8JH",
"B11 2BH",
"B11 3RR",
"B42 1DU",
"B60 3DR",
...
"WV10 7Ln",
"WV14 OQL",
"WV15 5HR"
],
"countryNo": [
0,
1,
33,
44,
46,
47,
353
]
}
}
}
}
}
```
You can use the same filters as for the aggregate functions. Here is an example:
```graphql { title = "Query" }
query read($cid:Int)
{
useCompany(no: $cid)
{
associate_aggregate(filter:{
postalArea : {_eq : "London"}
})
{
distinct
{
postCode
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"associate_aggregate": {
"distinct": {
"postCode": [
"L63 4DJ",
"MW10 2XA"
]
}
}
}
}
}
```
Fetching distinct values for unique primary keys will not provide any benefit over a regular query for that specific field.
In other words, the following two queries will return the same date, although in different forms.
```graphql { title = "Query" }
query read($cid:Int)
{
useCompany(no: $cid)
{
associate_aggregate(filter:{
postalArea : {_eq : "London"}
})
{
distinct
{
associateNo
}
}
associate(filter:{
postalArea : {_eq : "London"}
})
{
items
{
associateNo
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"associate_aggregate": {
"distinct": {
"associateNo": [
28,
149
]
}
},
"associate": {
"items": [
{
"associateNo": 28
},
{
"associateNo": 149
}
]
}
}
}
}
```
Mutations
/businessnxtapi/apireference/schema/mutations
section
Guides you on using mutations for inserts, updates, deletes, and running tasks within a GraphQL schema.
2026-07-10T12:31:03+03:00
# Mutations
Guides you on using mutations for inserts, updates, deletes, and running tasks within a GraphQL schema.
You can perform inserts, updates, and deletes on all the company and system tables. This is possible with the `mutation` operation. Additional mutation operations include running processings and reports as well as executing queries asynchronously.
Mutations are available with the `mutation` field at the top of the GraphQL schema, as shown in the following image:
The Mutation Type
/businessnxtapi/apireference/schema/mutations/mutation
page
Root Mutation type defines operations on company and system tables, enabling create, update, delete, and asynchronous queries.
2026-07-10T12:31:03+03:00
# The Mutation Type
Root Mutation type defines operations on company and system tables, enabling create, update, delete, and asynchronous queries.
The `Mutation` type is the root of all types that define table objects used in these operations, in the same way the `Query` type was the root for all types used in reading operations. In fact, `Mutation` and `Query` are very similar, as `Mutation` contains the following fields:
| Field | Description |
| ----- | ----------- |
| `useCompany` | Provides access to operations on the company tables. |
| `useCustomer` | Provides access to operations on the system tables. |
| `asyncQuery` | A field for executing another GraphQL query asynchronously. See [Async queries](../async.md). |
The type of the `useCompany` field is `Mutation_UseCompany`. This type contains a field for each of the create, update, and delete operation for every company table.
Similarly, the type of the `useCustomer` field is `Mutation_UseCustomer`. This type contains a field for each of the create, update, and delete operation for every system table.
You can see the two types, `Mutation_UseCustomer` and `Mutation_UseCompany`, side-by-side in the following table:
| System table | Company table |
| ----------- | --- |
|  |  |
Inserts
/businessnxtapi/apireference/schema/mutations/inserts
page
GraphQL Insert Operations - Define _create mutation fields, arguments, type structure, and example queries, emphasizing field order and inserting between records.
2026-07-10T12:31:03+03:00
# Inserts
GraphQL Insert Operations - Define _create mutation fields, arguments, type structure, and example queries, emphasizing field order and inserting between records.
Insert operations are available through a field having the name of the form `_create` of a type having the name of the form `__Result`. For instance, for the `Associate` table, the field is called `associate_create` and its type is `Mutation_UseCompany_Associate_Result`.
The form of this operation is the following:
```graphql
associate_create(values: [Associate_Input!]!,
insertAtRow: FilterExpression_Order,
insertPosition: InsertPosition): Mutation_UseCompany_Associate_Result
```
The `_create` field has several arguments:
- one mandatory called `values` which is a non-nullable array of objects of type `_Input`. For instance, for the `Associate` table, the input type is `Associate_Input`.
- one optional called `insertAtRow` which is a filter expression that identifies the row where the new records should be inserted.
- one optional called `insertPosition` which is an enum of type `InsertPosition` that can have the values `BEFORE` and `AFTER`, which is used in conjunction with the `insertAtRow` argument to define the direction of the insertion of the new records.
- one optional called `suggest` which is object of type `Suggest__Input`. For instance, for the `Associate` table, this input type is called `Suggest_Associate_Input`.
> [!WARNING]
>
> The `suggest` argument for requesting suggested values is now deprecated.
The input types for the `values` argument expose all the columns of the table, except for:
- the primary key column (which is automatically incremented)
- in-memory columns
- utility columns `createdDate` (SQL name `CreDt`), `createdTime` (SQL name `CreTm`), `createdByUser` (SQL name `CreUsr`), `changedDate` (SQL name `ChDt`), `changedTime` (SQL name `ChTm`), and `changedByUser` (SQL name `ChUsr`), which are present in every table.
If a table has more than one column as primary keys, then all but the last of these primary key columns must be filled in. The last primary key column is automatically incremented but the others must be explicitly supplied. These are foreign keys to other tables and the records they point to must exist for the operation to succeed. In this case, the type name has the form `_Insert_Input`.
The following image shows a snippet of the `Associate_Input` type from the GraphiQL document explorer:
Similarly, the next image shows a snippet of the `AssociateInformation_Insert_Input`, that has two primary key fields:
- `associateNo` is also a foreign key to the `Associate` table and must be supplied with an existing value
- `lineNo` is a primary key that is auto incremented, and, therefore, not present in the input type.
The mutation result type (`__Result`) has two fields:
- `affectedRows` indicated the number of rows successfully affected by the operation (in the case of inserts the number of records that were successfully inserted)
- `items` an array of objects affected by the mutation operation (for inserts, these are the records that were successfully inserted).
Here is a snippet of the `Mutation_UseCompany_Associate_Result` from the GraphiQL document explorer:
The objects in the `items` field have the same type that is used for query operations. For the `Associate` table, this is called `Associate` and looks like this:
An insert operation has the following form:
```graphql { title = "Query" }
mutation insert($cid : Int!)
{
useCompany(no: $cid)
{
associate_create(values:[
{
name:"Erik Larson",
shortName :"Erik",
customerNo: 30101
},
{
name :"Frida Olson",
shortName:"Frida",
customerNo: 30102
}
])
{
affectedRows
items
{
associateNo
customerNo
name
shortName
languageNo
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"associate_create": {
"affectedRows": 2,
"items": [
{
"associateNo": 547,
"customerNo": 30101,
"name": "Erik Larson",
"shortName": "Erik",
"languageNo": 0
},
{
"associateNo": 548,
"customerNo": 30102,
"name": "Frida Olson",
"shortName": "Frida",
"languageNo": 0
}
]
}
}
}
}
```
> [!NOTE]
>
> If an empty value (`{}`) is specified in the `values` array, then an empty record with only the primary key columns assigned will be created.
## Fields order
> [!TIP]
>
> The order of fields given in the `values` argument is important, because the fields are assigned in this user-given order. Listing the fields in some particular order may result in unexpected results (such as fields having default values).
Here is an example when creating an order. When `customerNo` is given before `dueDate`, the results are as expected:
```graphql { title = "Query" }
mutation create_order($cid : Int!)
{
useCompany(no : $cid)
{
order_create(
values:[
{
customerNo : 10000
dueDate: 20221124
}
]
)
{
affectedRows
items
{
orderNo
dueDate
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"order_create": {
"affectedRows": 1,
"items": [
{
"orderNo": 6,
"dueDate": 20221124,
}
]
}
}
}
}
```
However, if the `dueDate` is specified before `customerNo`, then the `dueDate` is not set:
```graphql { title = "Query" }
mutation create_order($cid : Int!)
{
useCompany(no : $cid)
{
order_create(
values:[
{
dueDate: 20221124
customerNo : 10000
}
]
)
{
affectedRows
items
{
orderNo
dueDate
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"order_create": {
"affectedRows": 1,
"items": [
{
"orderNo": 6,
"dueDate": 0,
}
]
}
}
}
}
```
## Suggested values
When you create a new record, you can ask the system to automatically fill in values for numerical fields. The API for this has changed over time. The correct way of using this feature is to:
- specify the fields in the objects in the `values` array in their correct order (see the previous section on fields order)
- specify the fields for which you want the system to automatically set a value with the `suggest` argument, or
- specify the fields for which you want the system to automatically set a value with the `_suggest` special field available on every record.
Both the argument `suggest` and the `_suggest` special field have an input type containing all the fields from the table for which the system can automatically fill in values.
Here is an example of the `Suggest_Associate_Input` type for the `Associate` table:
The field of all these input types are of one of the following two types:
- `Boolean`, in which case you must use the value `true` to include the column in the suggestions list.
- `SuggestIntervalType`, in which case you must specify a `from` and `to` value to bound the numeric interval for the value of the field.
> [!NOTE]
>
> A limited number of fields in the data model support specifying an interval.
Here is an example for suggesting values using the `suggest` argument:
```graphql { title = "Query" }
mutation create_voucher($cid : Int!,
$bno : Int!,
$cno : Int!)
{
useCompany(no : $cid)
{
voucher_create(
values: [{
batchNo : $bno
voucherNo : 0
voucherDate : 0
valueDate : 0
debitAccountNo : 1930
creditAccountNo: $cno
customerNo : $cno
amountDomestic : 100
}],
suggest : {
voucherNo : true,
voucherDate : true
valueDate : true
}
)
{
affectedRows
items
{
batchNo
voucherNo
voucherDate
valueDate
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"voucher_create": {
"affectedRows": 1,
"items": [
{
"batchNo": 2,
"voucherNo": 60003,
"voucherDate": 20220715,
"valueDate": 20220715
}
]
}
}
}
}
```
The fields `voucherNo`, `voucherDate`, and `valueDate` are present both in the `values` object and in the `suggest` argument. However, the assignment value (in the above example 0) is ignored and the system automatically fills in the values for these fields.
> [!NOTE]
>
> The fields need to be present in both places because the assignments is performed in the order given in the `values` object, but we also need to specify which fields should be automatically filled in by the system.
> [!NOTE]
>
> The order of fields in the `suggest` argument does not matter.
The same can be achieved by using the special `_suggest` field, as shown in the following example:
```graphql { title = "Query" }
mutation create_voucher($cid : Int!,
$bno : Int!,
$cno : Int!)
{
useCompany(no : $cid)
{
voucher_create(
values: [{
batchNo : $bno
voucherNo : 0
voucherDate : 0
valueDate : 0
debitAccountNo : 1930
creditAccountNo: $cno
customerNo : $cno
amountDomestic : 100
_suggest : {
voucherNo : true,
voucherDate : true,
valueDate : true
}
}],
)
{
affectedRows
items
{
batchNo
voucherNo
voucherDate
valueDate
}
}
}
}
```
There are several fields in the data model that support suggesting an interval as a value. These fields are:
- `customerNo`, `suppliedNo`, and `exployeeNo` in `Associate`
- `capitalAssetNo` in `CapitalAsset`
- `resourceNo` in `Resource`
For these fields, you can specify the interval in two ways.
The first method is to use the `suggest` argument as before, providing an interval with `from` and `to` values for the field. Here is an example:
```graphql { title = "Query" }
mutation create_customer($cid : Int!)
{
useCompany(no : $cid)
{
associate_create(
values: [{
customerNo : 0
name : "Test Customer
}],
suggest : {
customerNo : {
from : 10000
to : 19999
}
}
)
{
affectedRows
items
{
associateNo
customerNo
name
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"associate_create": {
"affectedRows": 1,
"items": [
{
"associateNo": 187,
"customerNo": 10928,
"name": "Test Customer",
}
]
}
}
}
}
```
This will ignore the value 0 specified in the `values` object and automatically assign a value in the given interval, 10000 - 19999.
The main difference between the `suggest` argument and the `_suggest` field is that the first is applied to all the values in the `values` array, while the second is applied only to the record where it is specified.
This means you can create multiple records with different suggest specifications (such as what fields should be suggested or what interval values should be used).
Moreover, the `_suggest` field supports suggesting in composite object creation (order-order line and batch-voucher). This is exemplified in the following snippet:
```graphql { title = "Query" }
mutation create_batch($cid : Int!, $vsn : Int!, $sno : Int!,
$debit1 : Int!, $debit2 : Int!)
{
useCompany(no : $cid)
{
batch_create(values:[
{
batchNo : 0
voucherSeriesNo : $vsn
vouchers : [
{
voucherNo: 0
voucherDate : 0
amountDomestic: 1300
creditAccountType: 2
creditAccountNo: $sno
_suggest : {
voucherNo : true
voucherDate : true
}
},
{
voucherNo: 0
voucherDate : 0
amountDomestic: 600
debitAccountType: 3
debitAccountNo: $debit1
_suggest : {
voucherNo : true
voucherDate : true
}
},
{
voucherNo: 0
voucherDate : 0
amountDomestic: 700
debitAccountType: 3
debitAccountNo: $debit2
_suggest : {
voucherNo : true
voucherDate : true
}
}
]
_suggest : {
batchNo : true
}
}
])
{
affectedRows
items
{
batchNo
joindown_Voucher_via_Batch
{
items
{
batchNo
voucherNo
voucherDate
debitAccountNo
creditAccountNo
amountDomestic
}
}
}
}
}
}
```
The second method is to use the companion `_suggest_interval` field. These special fields are of the type `SuggestIntervalType` that has a `from` and `to` field to define the bounds of the interval.
For instance, for the `customerNo` field in the `Associate` table, a `customerNo_suggest_interval` field is available. This is shown in the following example:
```graphql { title = "Query" }
mutation CreateAssociate($cid : Int)
{
useCompany(no :$cid)
{
associate_create(values:[{
name : "Demo Customer AS",
customerNo_suggest_interval : {
from : 10000,
to : 20000
},
countryNo : 47,
currencyNo : null
}])
{
affectedRows
items
{
associateNo
customerNo
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"associate_create": {
"affectedRows": 1,
"items": [
{
"associateNo": 1234,
"customerNo": 15726
}
]
}
}
}
}
```
Notice that in this case the `suggest` argument is not needed at all.
> [!TIP]
>
> The rules of thumb for providing inputs are as follows:
>
> - fields must be specified in the correct order
> - if a field should have a specific value, provide it as an input
> - if a field should remain unassigned, do not list it in the input
> - if a field should have a system given value, specify any value but also include it in the `suggest` argument
> - if a field can have a suggest value in a given interval and you want to specify the interval, use the `_suggest_interval` suffixed field, such as `customerNo_suggest_interval`. If you do not want to specify the interval, use the same suggest solution as for the other fields.
### Deprecated suggested values
Suggeting a value is also possible by specifying the `null` value for a field. This has the advantage that the `suggest` argument is not needed at all. However, it conflicts with the need to be possible to specify fields in variables for instance but with a `null` value. For this reason, although still supported, this method is deprecated and should be avoided.
Here is an example of suggesting values for `voucherNo` and `voucherDate` by specifying `null` for these fields:
```graphql { title = "Query" }
mutation create_voucher($cid: Int, $batchId: Int!)
{
useCompany(no: $cid)
{
voucher_create(values: [
{
batchNo: $batchId
voucherNo : null
voucherDate: null
amountDomestic: 1300
creditAccountType: 2
creditAccountNo: 50000
},
{
batchNo: $batchId
voucherNo : null
voucherDate: null
amountDomestic: 600
debitAccountType: 3
debitAccountNo: 4300
},
{
batchNo: $batchId
voucherNo : null
voucherDate: null
amountDomestic: 700
debitAccountType: 3
debitAccountNo: 1930
}])
{
affectedRows
items
{
batchNo
voucherNo
voucherDate
debitAccountNo
creditAccountNo
amountDomestic
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"voucher_create": {
"affectedRows": 3,
"items": [
{
"batchNo": 10002,
"voucherNo": 60002,
"voucherDate": 20220101,
"debitAccountNo": 0,
"creditAccountNo": 50000,
"amountDomestic": 1300
},
{
"batchNo": 10002,
"voucherNo": 60002,
"voucherDate": 20220101,
"debitAccountNo": 4300,
"creditAccountNo": 0,
"amountDomestic": 600
},
{
"batchNo": 10002,
"voucherNo": 60002,
"voucherDate": 20220101,
"debitAccountNo": 1930,
"creditAccountNo": 0,
"amountDomestic": 700
}
]
}
}
}
}
```
The downside of this is that **fields that are not supposed to be assigned should not be specified at all**. Passing `null` for their value results in them being automatically filled in by the system (provided that it's possible). Here is an example:
```graphql { title = "Query" }
mutation create_customers(
$cid: Int!,
$customers: [Associate_Input!]!) {
useCompany(no: $cid) {
associate_create(
values: $customers
suggest: {
customerNo: {
from: 65000
to: 69999
}
}
) {
affectedRows
items {
associateNo
name
customerNo
companyNo
}
}
}
}
```
```graphql { title = "Variables" }
{
"cid": 12345678,
"customers": [
{
"name": "Test Company AS",
"companyNo": null,
"addressLine1": "GraphQL gate 44",
"addressLine2": "",
"postCode": "0110",
"postalArea": "Oslo",
"countryNo": 0,
"emailAddress": ""
}
}
```
In this example, the field `companyNo` is assigned the value `null`. Which means, the system will automatically assign a value to it. In order to avoid that, leave the field out of the input at all.
## Assigning fields from unset variables
When fields are assigned from variables, but the variables are not set, the fields are ignored as they were not provided in insert and update operations.
For instance, consider the following query:
```graphql { title = "Query" }
mutation update_c_ompany(
$companyID: Int!
$customerNo: Int!,
$phone: String,
$mobilePhone: String,
$privatePhone: String,
)
{
useCompany(no: $companyID)
{
associate_update(
filter:
{
customerNo: {_eq: $customerNo }
},
value:
{
phone: $phone
mobilePhone: $mobilePhone
privatePhone: $privatePhone
}
)
{
affectedRows
}
}
}
```
```graphql { title = "Result" }
{
"companyID" : 1234567,
"customerNo": 11000,
"phone": "9411223344"
}
```
The `$mobilePhone` and `$privatePhone` are not set in the variables dictionary. Therefore, the query becomes equivalent to the following:
```graphql
mutation update_c_ompany(
$companyID: Int!
$customerNo: Int!,
$phone: String
)
{
useCompany(no: $companyID)
{
associate_update(
filter:
{
customerNo: { _eq: $customerNo }
},
value:
{
phone: $phone
}
)
{
affectedRows
}
}
}
```
## Insert between existing records
It is possible to insert new records between existing ones. This is done by using the `insertAtRow` and `insertPosition` optional arguments for the `_create` fields.
The `insertAtRow` argument defines a filter for indetifying the position where the new records should be inserted. This filter is applied for every object in the `values` array. Although the filter can be anything, it should include the primary key at least partially. If more that one row matches the filter, the first one is considered the insertion point.
The `insertPosition` argument defines where the new records should be inserted in relation to the row identified by the `insertAtRow` filter. The possible values are `BEFORE` and `AFTER`. This argument is optional and if missing, the default value is `BEFORE`.
> [!NOTE]
>
> The objects in the `values` array should not assign values to the primary key fields. These are automatically assigned by the system from the values of the record matching the `insertAtRow` argument.
```graphql { title = "Query" }
mutation insert_order_line($cid : Int!,
$ono : Int!,
$pno3 : String)
{
useCompany(no : $cid)
{
orderLine_create(values:[
{
productNo : $pno3,
quantity : 1
}
],
insertAtRow: { _and : [
{orderNo : {_eq : $ono}},
{lineNo : {_eq : 1}},
]},
insertPosition : AFTER)
{
affectedRows
items
{
orderNo
lineNo
sortSequenceNo
productNo
quantity
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"orderLine_create": {
"affectedRows": 1,
"items": [
{
"orderNo": 2024,
"lineNo": 3,
"sortSequenceNo": 2,
"productNo": "PRO-01",
"quantity": 1
}
]
}
}
}
}
```
To understand how this works, let's consider the following example of inserting new order lines between existing ones for a particular order. Let's start with the following data for the `OrderLine` table:
| OrderNo | LineNo | SortSequenceNo | ProductNo |
| ------- | ------ | -------------- | --------- |
| 2024 | 1 | 1 | PRO-01 |
| 2024 | 2 | 2 | PRO-02 |
If we insert a new line with product number `PRO-03` _before_ the line with the primary key `OrderNo=2024, LineNo=1`, the result will be:
| OrderNo | LineNo | SortSequenceNo | ProductNo |
| ------- | ------ | -------------- | --------- |
| 2024 | 1 | 2 | PRO-01 |
| 2024 | 2 | 3 | PRO-02 |
| 2024 | 3 | 1 | PRO-03 |
However, if we insert the same line but _after_ the one with the primary key `OrderNo=2024, LineNo=1`, the result will be:
| OrderNo | LineNo | SortSequenceNo | ProductNo |
| ------- | ------ | -------------- | --------- |
| 2024 | 1 | 1 | PRO-01 |
| 2024 | 2 | 3 | PRO-02 |
| 2024 | 3 | 2 | PRO-03 |
On the other hand, if we insert two order lines at the same time, one for product `PRO-03` and one for product `PRO-04`, the result will be the following when inserting _before_ the record with the primary key `OrderNo=2024, LineNo=1`:
| OrderNo | LineNo | SortSequenceNo | ProductNo |
| ------- | ------ | -------------- | --------- |
| 2024 | 1 | 3 | PRO-01 |
| 2024 | 2 | 4 | PRO-02 |
| 2024 | 3 | 1 | PRO-03 |
| 2024 | 4 | 2 | PRO-04 |
Similarly, if the insertion occurs _after_, the result will be:
| OrderNo | LineNo | SortSequenceNo | ProductNo |
| ------- | ------ | -------------- | --------- |
| 2024 | 1 | 1 | PRO-01 |
| 2024 | 2 | 4 | PRO-02 |
| 2024 | 3 | 3 | PRO-03 |
| 2024 | 4 | 2 | PRO-04 |
This is because the insertion point is determined each time a new record is inserted (and not just once for all records in a create operation).
## Inserting head and line rows
The data model defines several head and line tables. It is possible to insert both the head row and the lines with a single mutation operation for:
- `Order` and `OrderLine`
- `Batch` and `Voucher`
The following example shows how to create two orders, the first one with two lines and the second one with a single line:
```graphql { title = "Query" }
mutation create_order_and_lines($cid : Int!,
$customer : Int,
$prod1 : String,
$prod2 : String)
{
useCompany(no : $cid)
{
order_create(values:[
{
customerNo : $customer,
orderLines : [
{ productNo : $prod1, quantity : 1 },
{ productNo : $prod2, quantity : 2 },
]
},
{
customerNo : $customer,
orderLines : [
{ productNo : $prod1, quantity : 1 }
]
}]
)
{
affectedRows
items
{
orderNo
customerNo
orderLines: joindown_OrderLine_via_Order
{
items
{
orderNo
lineNo
productNo
quantity
priceInCurrency
}
}
}
}
}
}
```
Although the `orderNo` field is avaiable for the `orderLines` input objects, it should not be specified because it is automatically assigned by the system (from the parent order).
## Temporary rows
In some cases, it is useful to create temporary rows. A typical example is for determining the customer price for a product. There is no specific API for fetching customer prices, but it is possible by creating an order, with an order line for the product and customer in question, and then fetching the price from the order line. After this operation, the order should be deteled. To avoid creating table rows and deleting them afterwards, it is possible to create temporary rows, that are only stored in memory and that are automatically deleted at the end of the execution of the request, without being preserved (even for a short time) into the database.
Temporary rows are created by specifying `true` for the optional `temporary` argument, available in all `_create` fields.
```graphql { title = "Query" }
mutation get_customer_price($cid : Int!, $customer : Int, $prod : String)
{
useCompany(no : $cid)
{
order_create(
values:[
{
customerNo : $customer,
orderLines : [
{ productNo : $prod, quantity : 1 },
]
}
],
temporary : true
)
{
affectedRows
items
{
orderNo
customerNo
orderLines: joindown_OrderLine_via_Order
{
items
{
orderNo
lineNo
productNo
quantity
priceInCurrency
}
}
}
}
}
}
```
When creating temporary records, the primary keys are assigned negative values. These values are irrelevant. If you retrieve back the values for the primary key fields, you will see they have negative values. Here is an example result for the previous query:
```graphql { title = "Response" }
{
"data": {
"useCompany": {
"order_create": {
"affectedRows": 1,
"items": [
{
"orderNo": -2147483648,
"customerNo": 10001,
"orderLines": {
"items": [
{
"orderNo": -2147483648,
"lineNo": -2147483648,
"productNo": "1001",
"quantity": 1,
"priceInCurrency": 995
}
]
}
}
]
}
}
}
}
```
## Error handling
It is possible to decide how the system should behave when an error occurs during the execution of a create operation. This is done by using an optional `onError` argument.
This argument can be specified either on the `useCompany` / `useCustomer` fields or for the individual `_create` fields. When present in both locations, the table value at the table operation level overrides that from `useCompany` / `useCustomer`.
The possible values for this argument are:
| Value | Description |
| ----- | ----------- |
| `CONTINUE` | Field-assignment errors are reported but do not stop the creation of the row; the row is still persisted with the successful assignments. This is default, backwards compatible behavior. |
| `FAIL_ROW` | A failed field assignment fails the entire row. Other rows in the same table operation continue. Failed rows appear as `null` in the `items` array at their original input index. |
| `FAIL_TABLE` | A failed field assignment fails the entire table operation. No rows are persisted, the `items` field contains `null` for every inserted record, and `affectedRows` is 0, as other operations in the same request also fail. |
This argument can be used together with edit cache. When an edit cache session is active, and `FAIL_ROW` or `FAIL_TABLE` is used, the previous state of the edit cache is not affected by the discarding of records in the current operation. This is true both for insert, update, and delete operations.
To exemplify this, let's consider the following query:
```graphql { title = "Query" }
useCompany(no : $cid)
{
associate_create(values:[
{
customerNo : 123456
},
{
name : "must fail"
orgUnit1 : 12345678
},
{
associateNo : 9999,
name : "must succeed"
}
],
onError : CONTINUE)
{
affectedRows
items
{
associateNo
customerNo
name
orgUnit1
}
}
}
```
For this, we assume that there is no customer with number 123456 and no cost unit with number 12345678.
### CONTINUE
The `CONTINUE` value for `onError` is the default behavior, same as if when argument is missing. It reports errors, but continues to execute anything else that is possible to execute.
In this case, the result will be the following:
```json
{
"errors": [
{
"message": "Error: Field value can only be allocated automatically, in accordance to choice in Company data.",
"path": [
"useCompany",
"associate_create",
"values/0",
"customerNo"
],
"extensions": {
"data": {
"status": 9,
"status_name": "notLegalToEditField"
},
"details": "GraphQL.ExecutionError: Error: Field value can only be allocated automatically, in accordance to choice in Company data."
}
},
{
"message": "Error: Avdeling 12345678 does not exist.",
"path": [
"useCompany",
"associate_create",
"values/1",
"orgUnit1"
],
"extensions": {
"data": {
"status": 16,
"status_name": "referenceNotAccepted"
},
"details": "GraphQL.ExecutionError: Error: Avdeling 12345678 does not exist."
}
}
],
"data": {
"useCompany": {
"associate_create": {
"affectedRows": 2,
"items": [
null,
{
"associateNo": 10001,
"customerNo": 0,
"name": "must fail",
"orgUnit1": 0
},
{
"associateNo": 9999,
"customerNo": 0,
"name": "must succeed",
"orgUnit1": 0
}
]
}
}
}
}
```
The first record failed because it's not allowed to assign explicit values to the customer number (according to system settings).
The second record succeeded even though the cost unit 12345678 does not exist and the assignment on `orgUnit1` failed.
The third record succeeded without any error.
The return data is:
- `affectedRows` is 2
- `items` contains `null` for the first record and non-null values for the second and third
### FAIL_ROW
The `FAIL_ROW` option tells the system to elevate a field assignment error to the row level. That means that when an assignment fails, the entire row fails. However, other row operations in the same request may be inserted successfully.
When `FAIL_ROW` is used for the request above the response is:
```json
{
"errors": [
{
"message": "Error: Field value can only be allocated automatically, in accordance to choice in Company data.",
"path": [
"useCompany",
"associate_create",
"values/0",
"customerNo"
],
"extensions": {
"data": {
"status": 9,
"status_name": "notLegalToEditField"
},
"details": "GraphQL.ExecutionError: Error: Field value can only be allocated automatically, in accordance to choice in Company data."
}
},
{
"message": "Error: Avdeling 12345678 does not exist.",
"path": [
"useCompany",
"associate_create",
"values/1",
"orgUnit1"
],
"extensions": {
"data": {
"status": 16,
"status_name": "referenceNotAccepted"
},
"details": "GraphQL.ExecutionError: Error: Avdeling 12345678 does not exist."
}
}
],
"data": {
"useCompany": {
"associate_create": {
"affectedRows": 1,
"items": [
null,
null,
{
"associateNo": 9999,
"customerNo": 0,
"name": "must succeed",
"orgUnit1": 0
}
]
}
}
}
}
```
The first record failed because it's not allowed to assign explicit values to the customer number (according to system settings).
The second record failed because the cost unit 12345678 does not exist and the assignment on `orgUnit1` failed.
The third record succeeded without any error.
The return data is:
- `affectedRows` is 1
- `items` contains `null` for the first and second records and a non-null value for third
### FAIL_TABLE
The `FAIL_TABLE` option tells the system to fail the entire table operation when an assignment fails.
When `FAIL_TABLE` is used for the request above the response is:
```json
{
"errors": [
{
"message": "Error: Field value can only be allocated automatically, in accordance to choice in Company data.",
"path": [
"useCompany",
"associate_create",
"values/0",
"customerNo"
],
"extensions": {
"data": {
"status": 9,
"status_name": "notLegalToEditField"
},
"details": "GraphQL.ExecutionError: Error: Field value can only be allocated automatically, in accordance to choice in Company data."
}
},
{
"message": "Error: Avdeling 12345678 does not exist.",
"path": [
"useCompany",
"associate_create",
"values/1",
"orgUnit1"
],
"extensions": {
"data": {
"status": 16,
"status_name": "referenceNotAccepted"
},
"details": "GraphQL.ExecutionError: Error: Avdeling 12345678 does not exist."
}
}
],
"data": {
"useCompany": {
"associate_create": {
"affectedRows": 0,
"items": [
null,
null,
null
]
}
}
}
}
```
The first record failed because it's not allowed to assign explicit values to the customer number (according to system settings).
The second record failed because the cost unit 12345678 does not exist and the assignment on `orgUnit1` failed.
The third record succeeded without any error but it was discarded because the previous rows failed.
The return data is:
- `affectedRows` is 0
- `items` contains `null` for the three records that were requested to be inserted
Updates
/businessnxtapi/apireference/schema/mutations/updates
page
API documentation detailing update operations using GraphQL. Highlights use of filter/value pairs and filters/values pairs, with examples.
2026-07-10T12:31:03+03:00
# Updates
API documentation detailing update operations using GraphQL. Highlights use of filter/value pairs and filters/values pairs, with examples.
Update operations are available through a field having the name of the form `_update` of a type having the name of the form `__Result`. For instance, for the `Associate` table, the field is called `associate_update` and its type is `Mutation_UseCompany_Associate_Result`. The result type is the same for inserts, updates, and deletes.
The form of this operation is the following:
```graphql
associate_update(
filter: FilterExpression_Associate
value: Associate_Input
filters: [FilterExpression_Associate]
values: [Associate_Input!]
): Mutation_UseCompany_Associate_Result
```
The `_update` field has two pairs arguments, that you must use together. The first pair is:
- An argument called `filter` which defines the selection filter for the records to be updated. The type of this argument is the same used for filters in queries and will be described in details later in the document.
- An argument `value` which is an object of type `_Input`. For instance, for the `Associate` table, the input type is `Associate_Input`. This is the same input type used for insert operations for tables with a single primary key column. For tables with more than one primary key columns, it's a type slightly different than the one used for inserting, none of the primary key columns being available for updating.
You can use this if you want to update all records matching the filter with the same values. If you want to update each (or different) record with a different value, you must use the second pair of arguments:
- An argument called `filters` which is a list of filters, one for each record to be updated. The type of the elements of `filters` is the same used as the type of `filter.
- An argument called `values` which is a list of objects of type `_Input`.
> [!NOTE]
>
> The `filter` \ `value` pair is considered deprecated and will be removed in the future. You should use the `filters` \ `values` pair instead.
An update operation has the following form (in this example, we set the `languageNo` field to 44 for all associates that have the `associateNo` field greater than 546):
```graphql { title = "Query" }
mutation update_lang($cid : Int!)
{
useCompany(no:$cid)
{
associate_update(
filter : {associateNo : {_gt : 546}},
value:{languageNo:44})
{
affectedRows
items
{
associateNo
customerNo
name
shortName
languageNo
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"associate_update": {
"affectedRows": 2,
"items": [
{
"associateNo": 547,
"customerNo": 30101,
"name": "Erik Larson",
"shortName": "Erik",
"languageNo": 44
},
{
"associateNo": 548,
"customerNo": 30102,
"name": "Frida Olson",
"shortName": "Frida",
"languageNo": 44
}
]
}
}
}
}
```
You can collect multiple edits in a single update operation. You can do that with the use of `filters` and `values`. The following examples shows how to update multiple lines of an order with the different values. One filter and one value are provided for each line:
```graphql
mutation multi_order_line_update($cid : Int!, $ono : Int!)
{
useCompany(no : $cid)
{
orderLine_update(
filters: [
# filter for line 1
{_and:[
{orderNo : {_eq : $ono}}
{lineNo : {_eq : 1}}]},
# filter for line 2
{_and:[
{orderNo : {_eq : $ono}}
{lineNo : {_eq : 2}}]}
]
values: [
# value for line 1
{
priceInCurrency : 199.99,
invoiceNow : 1.0
},
# value for line 2
{
priceInCurrency : 59.99,
invoiceNow : 1.0
},
])
{
affectedRows
items
{
orderNo
lineNo
quantity
priceInCurrency
invoiceNow
}
}
}
}
```
You can transform any query using `filter` and `value` into a query using `filters` and `values`. An example is the following query:
```graphql { title = "filter & value" }
mutation update_lang($cid : Int!)
{
useCompany(no:$cid)
{
associate_update(
filter : {associateNo : {_gt : 546}},
value:{languageNo:44})
{
affectedRows
items
{
associateNo
customerNo
name
shortName
languageNo
}
}
}
}
```
```graphql { title = "filters & values" }
mutation update_lang($cid : Int!)
{
useCompany(no:$cid)
{
associate_update(
filters : [{associateNo : {_gt : 546}}],
values: [{languageNo:44}] )
{
affectedRows
items
{
associateNo
customerNo
name
shortName
languageNo
}
}
}
}
```
>[!TIP]
>
> If the `values` (or `value`) argument is empty, `[{}]` (or `{}`), no object is updated and `affectedRows` is 0. However, if you ask for `items`, a read operation is performed and the items matching the filter(s), if any is specified, or all otherwise, are returned.
## Error handling
The same mechanism for error handling used for insert operations with the `onError` argument is used for updates too.
See [Inserts - Error handling](./inserts/#error-handling) for details.
>[!NOTE]
>
> In case of a failed row update (when using `FAIL_ROW` or `FAIL_TABLE` error handling policies), the `items` field (if requested) will return, for the failed row, the values of the row before the update operation.
Every failed row is indicated, with a descriptive message and a reference path, in the `errors` array of the response.
Deletes
/businessnxtapi/apireference/schema/mutations/deletes
page
Delete table records using _delete(filter), with results shown in affectedRows. Works similarly to update filters. Example provided.
2026-07-10T12:31:03+03:00
# Deletes
Delete table records using _delete(filter), with results shown in affectedRows. Works similarly to update filters. Example provided.
Delete operations are available through a field having the name of the form `_delete` of a type having the name of the form `__Result`. For instance, for the `Associate` table, the field is called `associate_delete` and its type is `Mutation_UseCompany_Associate_Result`. The result type is the same for inserts, updates, and deletes.
The form of this operation is the following:
```graphql
associate_delete(filter: FilterExpression_Associate): Mutation_UseCompany_Associate_Result
```
The `_delete` field has a single argument called `filter` which defines the selection filter for the records to be delete. This is the same filter used for update operations.
A delete operation has the following form (in this example we delete all the associates that have the `associateNo` field greater than 546):
```graphql { title = "Query" }
mutation delete_associate($cid : Int!)
{
useCompany(no: $cid)
{
associate_delete(filter : {
associateNo : {_gt : 546}})
{
affectedRows
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"associate_delete": {
"affectedRows": 2
}
}
}
}
```
The value of the `items` field of the return type will always be `null` for a delete operation. The API does not return the value of the records that were deleted.
Processings
/businessnxtapi/apireference/schema/mutations/processings
page
Backend processings perform tasks like canceling orders or importing data via GraphQL mutations, potentially running long and requiring specific table fields like order_processings.
2026-07-10T12:31:03+03:00
# Processings
Backend processings perform tasks like canceling orders or importing data via GraphQL mutations, potentially running long and requiring specific table fields like order_processings.
Processings are business logic operations that are performed in the backend. Examples of processings include canceling or finishing an order, validating or updating batches, importing data into a company, or create payment suggestions. In GraphQL, these are available as mutations.
> [!WARNING]
>
> Processings are potentially long-running operations. Depending on the nature of the processing and the volume of data it has to process (and return) may increase significantly and exceed the timeout for the HTTP request. In this case, you would get back an error status even though the process continues to run in the background and may finish successfully.
Processings are associated with a table and a table can have multiple processes. For each table, a field called `_processings` is available. This is a field of the type `Processings`. For instance, for the `Order` table, the field is called `order_processings` and its type is called `OrderProcessings`. You can see this in the following image:
Under this field, there is one field for each available processing. These fields have the name of the processing. For instance, the `Order` table has processings called `finish`, `cancel`, `confirm`. These are available as fields under the `order_processings` field. This is exemplified here:
Here is an example for executing a processing. The following GraphQL requests executes the finish process on an order.
```graphql { title = "Query" }
mutation finish_order($cid : Int!,
$orderno : Int!)
{
useCompany(no : $cid)
{
order_processings
{
finish(
args :
{
finishType :0
},
filter :
{
orderNo : {_eq : $orderno}
}
)
{
succeeded
items
{
handledOrderLine
{
lineNo
finishedNow
}
}
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"order_processings": {
"finish": {
"succeeded": true,
"items": [
{
"handledOrderLine": [
{
"lineNo": 1,
"finishedNow": 1
}
]
}
]
}
}
}
}
}
```
Each processing field has one or two arguments, as follows:
- `filter`: allows for selecting the table rows that will be processed. This is the same filter used for querying data from the table. You can read more about that here: [Filtering](../../features/filtering.md).
- `args`: is an optional argument present for the processings that have parameters. When present, this is an object of a type with the name having the form `Processing__Parameters`, such as in `OrderProcessing_Transfer_Parameters`. The fields of this type are different for each processing.
The `args` field allows to specify arguments for the processing. This could be either:
- arguments for the overall processing, which are available in the root, or
- arguments for each processed row, which are provided as an array, one element for each row. It is possible to have recursive data, i.e. arrays of arrays, on multiple levels.
The following example shows possible arguments for the finish order processing:
```graphql
mutation run_processing($cid : Int!, $orderno : Int)
{
useCompany(no : $cid)
{
order_processings
{
finish(
args:
{
finishType : 0
group : [
{
key : "1"
quantity : 1
},
{
key : "2"
quantity : 1
},
{
key : "3"
quantity : 2
}
]
},
filter :
{
orderNo : { _gte : $orderno}
}
)
{
succeeded
items
{
handledOrderLine
{
lineNo
finishedNow
}
}
}
}
}
}
```
In this example:
- `finishType` is an argument for the entire processing
- `group` is a node containing a collection of objects with two properties, `key` and `quantity`. Each object in this collection is used for one processed row (which are selected here with a filter). If the number of rows is greater than the provided arguments (elements of the array) the rest of the rows are processed as if no arguments were supplied.
A similar structure is used for returning results. There are results:
- per processing, available directly in the root of the result object. All processings have a Boolean field called `succeeded` that indicate whether the processing completed successfully or not. Additional results, are available at this level.
- per row, available under the `items` field, which is an array. Each element in the array represents the result for a processed row.
For the previous request of order finishing, the following is a potential result:
```json
{
"data": {
"useCompany": {
"order_processings": {
"finish": {
"succeeded": true,
"items": [
{
"handledOrderLine": [
{
"lineNo": 1,
"finishedNow": 1
},
{
"lineNo": 2,
"finishedNow": 1
}
]
},
{
"handledOrderLine": [
{
"lineNo": 1,
"finishedNow": 1
},
{
"lineNo": 2,
"finishedNow": 1
},
{
"lineNo": 3,
"finishedNow": 2
}
]
},
{
"handledOrderLine": [
{
"lineNo": 1,
"finishedNow": 1
}
]
}
]
}
}
}
}
}
```
You can see here that for each order that was processed, there is an object in the `items` array. The property `handledOrderLine` is also an array and contains one object for each order line.
The following table shows another example of a process running on the `CompanyInformation` table that fetches access restrictions.
```graphql { title = "Mutation" }
mutation get_access($cid : Int!)
{
useCompany(no : $cid)
{
companyInformation_processings
{
getAccessRestrictions
{
succeeded
tableAccess
{
tableNo
noTableRead
noInsert
noUpdate
noDelete
}
functionAccess
{
processingAccess
{
processingNo
noProcessingAccess
}
reportAccess
{
reportNo
noReportAccess
}
}
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"companyInformation_processings": {
"getAccessRestrictions": {
"succeeded": true,
"tableAccess": [
{
"tableNo": 361,
"noTableRead": 0,
"noInsert": 1,
"noUpdate": 1,
"noDelete": 1
},
{
"tableNo": 362,
"noTableRead": 0,
"noInsert": 1,
"noUpdate": 1,
"noDelete": 1
},
...
],
"functionAccess": [
{
"processingAccess": [
{
"processingNo": 754,
"noProcessingAccess": 1
},
{
"processingNo": 1045,
"noProcessingAccess": 1
},
...
],
"reportAccess": [
{
"reportNo": 251,
"noReportAccess": 0
},
{
"reportNo": 162,
"noReportAccess": 0
},
...
]
}
]
}
}
}
}
}
```
From this snippet, you can see that:
- the processing returns information about access restrictions to tables, processings, and reports
- table access information is gathered under the `tableAccess` field, which is an array of objects, each containing information about a single table
- processing and report access information is available under the `processingAccess` and `reportAccess` fields, both being children of the `functionAccess` field. Also, like `tableAccess`, both `processingAccess` and `reportAccess` are arrays
This example shows a pattern that defines the general structure of processing results. Notice that even though `tableAccess` and `functionAccess` are themselves arrays, they represent overall processing data, and not results per row.
> [!TIP]
>
> If you don't know what processings are available for each table, or what each process is doing, you can get this information using the schema explorer, available in both GraphiQL and Insomnia.
The images at the beginning of this page demonstrate this.
Reports
/businessnxtapi/apireference/schema/mutations/reports
page
Comprehensive guide on executing and customizing report mutations, including parameters and result structures, for generating business documents in software applications.
2026-07-10T12:31:03+03:00
# Reports
Comprehensive guide on executing and customizing report mutations, including parameters and result structures, for generating business documents in software applications.
Reports are business logic operations that typically result in one or more documents. Reports have many similarities with [processings](processings.md).
They have the very same structure for parameters and results. They are also available as mutation requests. However, unlike processings, they return documents and attachments.
> [!WARNING]
>
> Line, processings, they are potentially long running operations. The time to execute a report may exceed the timeout of the HTTP request.
In this case, you would get back an error status even though the process continues to run in the background and may finish successfully.
Reports are associated with a table and a table can have multiple reports. However, not all tables have reports. For each table that provides reports, a field called `_reports` is available. The type of this field is called `Reports`. For instance, for the `Order` table, the reports field is called `order_reports` and its type is called `OrderReports`. You can see this in the following image:
Under each field of this form, there is one field for each report available for the table. For instance, for the `Order` table, there are multiple reports such as `pickList`, `packingSlips`, `orderConfirmations`, `orderPrints`, etc. These are available under the field `order_reports`. This is shown in the next image:
The following query shows an example for executing the order confirmation report for an order.
```graphql { title = "Query" }
mutation run_report($cid : Int!,
$ono : Int!)
{
useCompany(no : $cid)
{
order_reports
{
orderConfirmations(
filter :
{
orderNo :{_eq: $ono}
}
)
{
succeeded
documents
{
name
content
}
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"order_reports": {
"orderConfirmations": {
"succeeded": true,
"documents": [
{
"name": "200022.pdf",
"content": "JVBERi0xLjQKJdDExrT...",
}
]
}
}
}
}
}
```
## Arguments
Reports may have multiple arguments, as shown in the following table. All these arguments are optional.
| Field | Type | Description |
| ----- | ---- | ----------- |
| `filter` | `FilterExpression_` | Allows for selecting the table rows that will be processed. This is the same filter used for querying data from the table. You can read more about that here: [Filtering](../../features/filtering.md). |
| `args` | `Reports__Parameters` | Provides various arguments for the reporting process. |
| `returnDocuments` | `bool` | Indicates whether documents should be returned as part of the result. When present, their content is available as base64-encoded text. |
| `splitAttachments` | `bool` | Indicates whether attachments, when available, should be split into separate PDFs. Attachment content is available as base64-encoded text. |
| `approval` | `bool` | When this value is `true` (which is the default if not specified) tables in the database will be updated, if applicable for the report. E.g. for order documents (like invoices), the tables with order lines and reservations will accumulate quantities processed so far. The documents may be archived in the database, and vouchers may be produced. The `Approval` property can be set to `false` when you only preview results. |
| `documentDate` | `date` | Can be used by the business logic, depending on the actual report (e.g. as the invoice date), as well as be displayed on the printed form. |
| `valueDate` | `date` | Used when producing vouchers (as part of the approval processing), to determine the accounting period and VAT period, if applicable for the report. |
| `formNo` | `int` | The form number for the document type/form type. The value 0 (the default) indicates the default form. |
| `printDestination` | `PrintDestination` | Specify different options for the result documents. |
| `landscape` | `bool` | Indicates whether the report should be printed in landscape orientation. |
| `mergeDocuments` | `bool` | Indicates whether the generated documents should be merged into a single PDF file. |
| `zipDocuments` | `bool` | Indicates whether generated documents to be returned as a single ZIP archive. |
| `breakBy` | `[_BreakBy!]` | Indicates whether the report should be split into multiple documents based on the specified break by options. |
| `subTableQuery` | `_TableQuery` | Query options (filter, ordering, aggregation) applied to the report's sub-table. Available only for reports that define a sub-table. |
### Printing
The following options are available for printing destination:
| Destination | Description |
| ----------- | ----------- |
| `PRINT_TO_PDF` | Produces PDF files. This is the default value. |
| `PRINT_TO_DEFINED_DESTINATIONS` | Distributes the documents according to "Document delivery methods" on the order/associate, if applicable for the report. The destination can be a selection for whether to use one or more of mail, e-mail, fax, EDI, and AutoInvoice, depending on the actual order; suggested from the customer or supplier. |
| `SEND_EMAIL` | Sends PDFs by e-mail. |
| `ONLY_APPROVAL` | Approves the documents without printing them (i.e. writes only to the database). |
The execution of the order confirmation report is shown again here, this time with all the possible arguments:
```graphql { title = "Mutation" }
mutation run_report($cid : Int!,
$ono : Int!)
{
useCompany(no : $cid)
{
order_reports
{
orderConfirmations(
returnDocuments :true
splitAttachments : true
approval : true
formNo : 0
printDestination : PRINT_TO_PDF
documentDate : "2022-03-01"
valueDate : "2022-03-01"
filter :
{
orderNo :{_eq: $ono}
}
)
{
succeeded
documents
{
name
content
attachments
{
name
content
}
}
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"order_reports": {
"orderConfirmations": {
"succeeded": true,
"documents": [
{
"name": "200022.pdf",
"content": "JVBERi0xLjQKJdDExrT...",
"attachments": []
}
]
}
}
}
}
}
```
### The breakBy argument
The `breakBy` is an optional argument that controls how report rows are grouped into sections (page breaks).
You specify an ordered list of columns. Each column defines a break level.
When the value of a break column changes between rows, a new section/page break is inserted in the report.
Example:
```graphql
breakBy: [
{ invoiceCustomerNo: true },
{ paymentTerms: true },
{ currencyNo: true }
]
```
Each element in the array is an object with a single column set to true. The order of elements defines the break hierarchy (first element = outermost break level).
However, for the `Order` table only, you can specify break columns for the `OrderLine` sub-table.
```graphql
breakBy: [
{ invoiceCustomerNo: true },
{ paymentTerms: true },
{ currencyNo: true },
{_thenBy : {orderNo : true}}
]
```
`_thenBy` can only be used when at least one break column is also specified.
The following snippet shows how to execute the `invoicesAndCreditNotes` report on the `Order` table.
```graphql
mutation invoice_order($cid: Int!, $ono1: Int, $ono2 : Int)
{
useCompany(no: $cid)
{
order_reports
{
invoicesAndCreditNotes(
filter: {orderNo: {_in: [$ono1, $ono2]}}
approval: true
printDestination: PRINT_TO_PDF
returnDocuments : true
args:
{
formNo: 61,
userDefinedSorting: 1,
accounting: 1,
directUpdate: 1,
batchInvoices: 1,
groupingByOrder: 1
},
breakBy : [
{invoiceCustomerNo : true},
{paymentTerms : true},
{currencyNo : true},
{_thenBy : {orderNo : true}}
]
)
{
succeeded
documents
{
name
content
}
}
}
}
}
```
Requirements for `breakBy` columns:
| Report | Table | breakBy columns | themBy columns |
| ------ | ----- | --------------- | -------------- |
| `invoicesAndCreditNotes` | `Order` | `invoiceCustomerNo`, `paymentTerms`, `currencyNo` | `orderNo` |
> [!TIP]
>
> If you don't know what reports are available for each table, or what each report is doing, you can get this information using the schema explorer, available in both GraphiQL and Insomnia.
The images at the beginning of this page demonstrate this.
### The subTableQuery argument
`subTableQuery` is an optional argument available for reports that define a sub-table. It allows you to specify query options (filter, ordering, aggregation) applied to the report's sub-table.
The following snippet shows how to execute the `invoicesAndCreditNotes` report on the `Order` table, with a `subTableQuery` argument.
```graphql
mutation invoice_order($cid: Int!, $ono1: Int, $ono2 : Int)
{
useCompany(no: $cid)
{
order_reports
{
invoicesAndCreditNotes(
filter: {orderNo: {_in: [$ono1, $ono2]}}
approval: true
printDestination: PRINT_TO_PDF
returnDocuments : true
args:
{
batchInvoices: 1,
groupingByOrder: 1
},
subTableQuery :{
filter : {
free3 : {_gt : 0}
},
orderBy : [{customerNo :DESC}],
includeTotalLine : true
},
breakBy : [
{invoiceCustomerNo : true},
{paymentTerms : true},
{currencyNo : true},
{_thenBy : {orderNo : true}}
]
)
{
succeeded
documents
{
name
content
}
}
}
}
}
```
Async queries
/businessnxtapi/apireference/schema/async
page
Async queries allow for the execution of GraphQL queries and mutations asynchronously, useful for long-running operations that might exceed timeouts.
2026-07-10T12:31:03+03:00
# Async queries
Async queries allow for the execution of GraphQL queries and mutations asynchronously, useful for long-running operations that might exceed timeouts.
Some GraphQL requests, such as the execution of processings or reports, may take long times to execute. These times could exceed internal GraphQL timeouts or HTTP timeouts (for instance when you're executing a query from a browser-based IDE such as GraphiQL), in which case the status and the result of the execution will be lost, even though it would complete successfully. To avoid this problem, you can run any Business NXT GraphQL request asynchronously. This works as follows:
- You request the excution of a query ascynhronously. The service will queue the request and immediatelly return an operation identifier. This identifier will then be used to fetch the result.
- You will ask for the result of the async query using the previously returned operation identifier. If the operation is taking a long time to execute, you will have to periodically poll for the result.
- In addition, you can request the list of all your asynchronous queries, which would return their operation identifier and status.
> [!NOTE]
>
> An asynchronous query carries the request of executing a synchronous query/mutation. The system executes this query normally (in a synchronous way) but hides the details from the caller and then makes its result available on a further request upon completion.
> [!TIP]
>
>There are several important thing to note:
>
> - A company or customer can have up to 20 asynchronous queries in the queue at a given time.
> - A company or customer can only have 5 concurrently running asynchronous queries at a time.
> - Rate limits are combined for the company or customer, for both asynchronous queries from the frontend and all GraphQL users/integrators for the company/customer.
> - (_Note_: These numbers may be subject to change.)
> - You cannot execute an asynchronous query within an asynchronous query.
> - The result of the asynchronous query is the stringified JSON of the synchronous query.
> [!WARNING]
>
> Aynchronous queries cannot contain join operations (`joinup_` and `joindown_` fields) or an `@export` directive.
>
> If you try to execute an asynchronous query containing any of these, you will not get the expected results. This is because an async query containing joins or the `@export` directive implies a sequence of requests to the backend: a first one to retrieve a set of data, and then another one after, based on the previously retrieved data. However, in the case of async queries, the first batch of requests are sent to the backend, but the response is not awaited for. Instead, the API returns an operation ID that is later used to query for the result. Only when you ask for the result of the async query, the response from the backend is read and interpreted. Therefore, the expected sequence of requests to the backend cannot be executed in the case of async queries.
> [!NOTE]
>
> The result of an asynchronous request is stored on the server for 7 days after the job finished. During this time, you can read the result multiple times.
After this period, the result is deleted and will no longer be available for reading.
## Making an asynchronous request
An asynchronous execution is requested with a mutation operation using the `asyncQuery` field.
The `asyncQuery` field has two arguments:
| Field | Type | Description |
| ----- | ---- | ----------- |
| `query` | `String` | Contains the GraphQL query to be executed ascynhronously (it can either be a query or a mutation). |
| `args` | `Dictionary` | Contains the key-value pairs representing the arguments for the query. |
The result of executing an asynchronous query contains the following fields:
| Field | Type | Description |
| ----- | ---- | ----------- |
| `operationId` | `String` | The identifier of the requested operation. |
| `status` | `TaskStatus` | An enumeration with several possible values: `ERROR`: the operation execution finished because of an error, `SUCCESS`: the request has completed successfully, and `QUEUED`: the request has been received and placed in a queue but the execution has not started. |
Here is an example that requests the first five general ledger accounts in an asynchronous way:
```graphql { title = "Query" }
mutation
{
asyncQuery(query:"""
query {
useCompany(no: 123456)
{
generalLedgerAccount(first: 5) {
totalCount
items {
accountNo
name
}
}
}
}
""")
{
operationId
status
}
}
```
```graphql { title = "Result" }
{
"data": {
"asyncQuery": {
"operationId": "29bb4abe-5299-4542-b1e4-c05aca11c3ed",
"status": "QUEUED"
}
},
"extensions": {
"vbnxt-trace-id": "43c281879ec08b257563ddbb5668a12b"
}
}
```
Typically, you would need to pass arguments to the query that needs to be executed asynchronously. This is done using the `args` argument of the `asyncQuery` field. The next example shows the previous query modified to contain arguments for the company number and the page size:
```graphql { title = "Query" }
mutation ($args: Dictionary)
{
asyncQuery(query:"""
query read($cid : Int!, $pagesize : Int!){
useCompany(no: $cid)
{
generalLedgerAccount(first: $pagesize) {
totalCount
items {
accountNo
name
}
}
}
}
""", args: $args)
{
operationId
status
}
}
```
```graphql { title = "Variables" }
{
"args" : {
"cid" : 123456,
"pagesize" : 5
}
}
```
The returned `operationId` must be used to read the result with another request.
## Reading the result of an asynchronous request
Reading the result of an asynchronous request is done with the `asyncResult` field of the [Query](queries/query.md) type. This field has a single argument, `operationId`, which is a string containing the identifier returned by an `asyncQuery` request.
```graphql { title = "Query" }
query fetch_results($oid : String!)
{
asyncResult(id: $oid)
{
operationId
status
error
data
createdAt
completedAt
}
}
```
```graphql { title = "Result" }
{
"data": {
"asyncResult": {
"operationId": "caa8812d-fdb2-4546-86a9-eab30e9dde20",
"status": "SUCCESS",
"error": null,
"data": "{\"data\":{\"useCompany\":{\"generalLedgerAccount\":{\"totalCount\":342,\"items\":[{\"accountNo\":1000,\"name\":\"Forskning og utvikling\"},{\"accountNo\":1020,\"name\":\"Konsesjoner\"},{\"accountNo\":1030,\"name\":\"Patenter\"},{\"accountNo\":1040,\"name\":\"Lisenser\"},{\"accountNo\":1050,\"name\":\"Varemerker\"}]}}}}",
"createdAt": "2022-09-23T12:34:07Z",
"completedAt": "2022-09-23T12:34:11Z"
}
},
"extensions": {
"vbnxt-trace-id": "ad02666f0531856aaadfc74625dc37f1"
}
}
```
The result is available as a string containing the JSON result of the requested query. You would deserialize this just as you'd do if the request was executed synchronously.
However, data may not be available immediatelly. If the operation is long-runnning and not yet completed, the returned status would be `QUEUED`, as shown next:
```json
{
"data": {
"asyncResult": {
"operationId": "caa8812d-fdb2-4546-86a9-eab30e9dde20",
"status": "QUEUED",
"error": null,
"data": "null",
"createdAt": "2022-09-23T12:34:07Z",
"completedAt": null
}
},
"extensions": {
"vbnxt-trace-id": "eb52491bfe7268e89d61a1121c0453af"
}
}
```
In this case, you have to poll periodically for the result until the status changes to `SUCCESS` or `ERROR`.
## Getting the list of asynchronous request
The result of the requests that executed asynchronously is available for 96 hours on the server. During this time, you can read it multiple times.
If you want to know what asynchronous operations you have requested and are still available on the server, you can do so with a query using the `asyncRequests` field. What you get back is the operation identifier and the status of each operation:
```graphql { title = "Query" }
query
{
asyncRequests
{
operationId
status
}
}
```
```graphql { title = "Result" }
{
"data": {
"asyncRequests": [
{
"operationId": "caa8812d-fdb2-4546-86a9-eab30e9dde20",
"status": "SUCCESS"
},
{
"operationId": "dd2a0f07-bcc2-45fb-bf3f-057b0f5eb5fa",
"status": "SUCCESS"
},
{
"operationId": "c9e979bc-2b03-4b56-91ed-738ffb17dbd4",
"status": "QUEUED"
}
]
},
"extensions": {
"vbnxt-trace-id": "c7415ed35a81b7362c602024ff88b77f"
}
}
```
## Deleting an asynchronous request
An async request that has been queue for execution can be deleted if it is not running (it's either queued or finished). This can be done using the `asyncQuery_delete` field in the mutation scheme. What you need to provide is the operation identifier of the request you want to delete:
```graphql { title = "Query" }
mutation delete_async_query($id : String!)
{
asyncQuery_delete(id: $id)
{
operationId
status
}
}
```
```graphql { title = "Result" }
{
"data": {
"asyncQuery_delete": {
"operationId": "4918391E-95C2-46E3-B771-3AD99BCA78B0",
"status": "DELETED"
}
}
}
```
The possible status values are:
| Status | Description |
| ------ | ----------- |
| `DELETED` | The request job has been deleted. |
| `DENIED` | The request job cannot be deleted. |
| `NOT_FOUND` | The request operation identifier was not found. |
| `UNKNOWN` | An unexpected error has occurred. |
Edit cache
/businessnxtapi/apireference/schema/editcache
page
Edit cache a system level transactional system that enables you to make edits across a session before saving or discarding them.
2026-07-10T12:31:03+03:00
# Edit cache
Edit cache a system level transactional system that enables you to make edits across a session before saving or discarding them.
BXNT provides an application-level transactional system called _edit cache_, which allows you to make edits across a session before saving them to the database or discarding them. This works as follows:
- you start an edit session by setting the `persistEditCache` argument to `true` on the first request, and any consecutive requests except the last one
- you receive a session identifier called `partialRequestId`
- in any consecutive request, you can make edits or read from the edit cache by specifying the `partialRequestId` from the first request
- at the end of the session you either save or discard the edit cache
- if any partial request in the session specifies the `partialRequestId` but not the `persistEditCache`, then the request completes with the saving of the edit cache
Edit cache requests can be executed both synchronously and asynchronously.
Let us look at several examples to understand how this works in practice.
In the following query, we are creating a order with one order line, and then add one more line to the newly created order.
```graphql { title = "Query" }
mutation create_order($cid:Int!,
$cno : Int,
$pno1 : String,
$pno2 : String,
$ono : Int = 0)
{
useCompany(no:$cid, persistEditCache : true)
{
partialRequestId
order_create(values:[
{
customerNo : $cno
orderLines : [
{
productNo : $pno1,
quantity : 1
}
]
}
])
{
affectedRows
items
{
orderNo @export(as: "ono")
customerNo
}
}
orderLine_create(values:[{
orderNo : $ono,
productNo : $pno2,
quantity : 1
}])
{
affectedRows
items
{
orderNo
lineNo
productNo
quantity
priceInCurrency
}
}
}
}
```
```json { title = "Result" }
{
"data": {
"useCompany": {
"partialRequestId": "097ADD2B-C197-4AD3-B639-4FF5BB197325",
"order_create": {
"affectedRows": 1,
"items": [
{
"orderNo": 3442,
"customerNo": 10001
}
]
},
"orderLine_create": {
"affectedRows": 1,
"items": [
{
"orderNo": 3442,
"lineNo": 2,
"productNo": "101",
"quantity": 1,
"priceInCurrency": 0
}
]
}
}
}
}
```
We can continue making edits using the same session ID. For instance, we can add one more line to the order:
```graphql { title = "Query" }
mutation create_order($cid:Int!,
$reqid : String,
$ono : Int,
$pno : String)
{
useCompany(no:$cid, partialRequestId : $reqid, persistEditCache : true)
{
orderLine_create(values:[{
orderNo : $ono,
productNo : $pno,
quantity : 1
}])
{
affectedRows
items
{
orderNo
lineNo
productNo
quantity
}
}
}
}
```
When the session is completed, we can save the edits by making a request without `persistEditCache` argument, using the `finishEditCache` field with the `action` argument set to `SAVE`:
```graphql { title = "Query" }
mutation save_editcache($cid:Int!)
{
useCompany(no:$cid, partialRequestId:"097ADD2B-C197-4AD3-B639-4FF5BB197325")
{
finishEditCache(action : SAVE)
{
success
}
}
}
```
If instead you want to discard the edits, you make a similar request but with the `action` argument set to `DISCARD`:
```graphql { title = "Query" }
mutation discard_editcache($cid:Int!)
{
useCompany(no:$cid, partialRequestId:"097ADD2B-C197-4AD3-B639-4FF5BB197325")
{
finishEditCache(action : DISCARD)
{
success
}
}
}
```
If a request specifies the `partialRequestId` without setting `persistEditCache` to `true` that completes the session, saving the edits. For instance, the following query will add an order line to and order and then complete the session persisting all the changes to the database:
```graphql { title = "Query" }
mutation create_order($cid:Int!,
$reqid : String,
$ono : Int,
$pno : String)
{
useCompany(no:$cid, partialRequestId : $reqid)
{
orderLine_create(values:[{
orderNo : $ono,
productNo : $pno,
quantity : 1
}])
{
affectedRows
items
{
orderNo
lineNo
productNo
quantity
}
}
}
}
```
If you want to discard or save an edit cache session that no longer exists, you get one of the following errors:
- for discarding: "Failed to discard edit cache. The partial request ID <sessionid> was not found."
- for saving: "Failed to save edit cache. The partial request ID <sessionid> was not found."
Date and time fields
/businessnxtapi/apireference/schema/datetime
page
Date and time fields API documentation - describes field formats, conversion examples, and usage in GraphQL queries and mutations.
2026-07-10T12:31:03+03:00
# Date and time fields
Date and time fields API documentation - describes field formats, conversion examples, and usage in GraphQL queries and mutations.
## Basic types
The Business NXT data model has featured fields that represent either dates or time values. These are stored in the database as integer values with some specific formats, as described in the following table:
| Type | Format | Examples |
| ---- | ------ | -------- |
| date | `yyyymmdd` | `20190101` for 1 January 2019 |
| time | `hhmm` | `0` for `00:00`, `101` for `01:01`, `2330` for `23:30` |
| precision time | `(((h * 60 + m) * 60) + s) * 1000 + ms` | `0` for `00:00:00.000`, `3661001` for `01:01:01.001`, `2862000500` for `23:30:30.500` |
Since October 2024, all tables contain two new timestamp fields for created and changed date-time values. These are T-SQL `datetime2` values (which in GraphQL are represented as `DateTime` values).
| Type | Format | Examples |
| ---- | ------ | -------- |
| timestamp | `yyyy-MM-dd HH:mm:ss[.nnnnnnn]` | `2024-10-01 12:45:33.798` for 1 October 2024, 12:45:33.798 |
> [!TIP]
>
> These fields, `createdTimestamp` and `changedTimestamp`, should be preferred for use in filters due to their higher precision.
>
> However, these fields are not available for already existing rows, only for new or modified rows after the release date.
> [!TIP]
>
> The date/time values represent the local time of the server. They do not indicate the timezone.
Since the GraphQL API exposes the data model as it is internally defined, the date and time fields appear in the API as integers. Here is an example:
```graphql { title = "Query" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
order(
first : 2,
filter : {orderDate : {_gt : 20150101}}
)
{
items
{
orderNo
orderDate
createdDate
createdTime
changedDate
changedTime
}
}
}
}
```
```json { title = "Result" }
{
"data": {
"useCompany": {
"order": {
"items": [
{
"orderNo": 75,
"orderDate": 20150115,
"createdDate": 20200511,
"createdTime": 1325,
"changedDate": 20200511,
"changedTime": 1325,
"changeTimeInMs": 48308716
},
{
"orderNo": 76,
"orderDate": 20150115,
"createdDate": 20200511,
"createdTime": 1325,
"changedDate": 20200511,
"changedTime": 1325,
"changeTimeInMs": 48308716
}
]
}
}
}
}
```
The use of the date and time fields require conversions as follow:
For date:
``` { title = "From integer" }
value = 20210122
year = value / 10000
value = value % 10000
month = value / 100
day = value % 100
```
``` { title = "To integer" }
value = year \* 10000 + month \* 100 + day
```
For time:
``` { title = "From integer" }
value = 1245
hour = value / 100
minute = value % 100
```
``` { title = "To integer" }
value = hour \* 100 + minute
```
For precision time:
``` { title = "From integer" }
value = 2862000500
ms = value % 1000
timeValue = value / 1000
hour = timeValue / 3600
timeValue = timeValue % 3600
minute = timeValue / 60
second = timeValue % 60
```
``` { title = "To integer" }
value = (((hour \* 60 + minute) \* 60) + second) \* 1000 + ms
```
The `changeTimeInMs` field is the only precision time field. However, this is only available on a limited number of tables, listed below:
- `Associate`
- `AssociateReference`
- `AssociateInformation`
- `Appointment`
- `Resource`
- `Product`
- `Barcode`
- `PriceAndDiscountMatrix`
- `Order`
- `OrderLine`
- `IncomingDocumentChange`
On the other hand, the new timestamp fields apear as fields of the `DateTime` type, as shown in the following example:
```graphql { title = "Query" }
query read_orders($cid : Int!)
{
useCompany(no: $cid)
{
order(
first : 2,
orderBy : {changedTimestamp : DESC})
{
items
{
orderNo
orderType
customerNo
changedDate
changedTime
changedDateTime
changedTimestamp
createdDate
createdTime
createdDateTime
createdTimestamp
}
}
}
}
```
```json { title = "Result" }
{
"data": {
"useCompany": {
"order": {
"items": [
{
"orderNo": 4656,
"orderType": 6,
"customerNo": 10002,
"changedDate": 20241010,
"changedTime": 1022,
"changedDateTime": "2024-10-10T10:22:30.399",
"changedTimestamp": "2024-10-10T10:22:30.399",
"createdDate": 20241010,
"createdTime": 1022,
"createdDateTime": "2024-10-10T10:22:00",
"createdTimestamp": "2024-10-10T10:22:29.958"
},
{
"orderNo": 1,
"orderType": 2,
"customerNo": 10002,
"changedDate": 20240207,
"changedTime": 813,
"changedDateTime": "2024-02-07T08:13:14.764",
"changedTimestamp": null,
"createdDate": 20240217,
"createdTime": 1325,
"createdDateTime": "2024-02-17T13:25:00",
"createdTimestamp": null
}
]
}
}
}
}
```
## Date fields and time fields
In order to make it easier to work with date and time values, GraphQL is exposing all these fields also in an ISO date format and, respectively, a time format, according to the following table:
| Type | Format | Examples |
| ---- | ------ | -------- |
| date | `yyyy-mm-dd` | `2019-01-01`, `2021-12-31` |
| time | `hh:mm` | `00:00`, `01:01`, `23:30` |
| precision time | `hh:mm:ss.ms` | `00:00:00.000`, `01:01:01.001`, `23:30:30.500` |
To make this possible, every date or time field has a companion with the same name, but the suffix `AsDate` for dates and, respectively, `AsTime` for time. This is exemplified below:
| Field | Type | Value |
| ----- | ---- | ----- |
| `orderDate` | integer | `20211022` |
| `orderDateAsDate` | date | `2021-10-22` |
| `estimatedTime` | integer | `1710` |
| `estimatedTimeAsTime` | string | `"17:10"` |
| `changeTimeInMs` | integer | `48308716` |
| `changeTimeInMsAsTime` | string | `"13:25:08.716"` |
**Note**: There is no natural date type to represent a time value without a date. Therefore, the type of the time fields with the `AsTime` suffix is actually string.
These date and time fields are available for:
- [connection types](queries/query.md) (used for reading data)
- [aggregate types](queries/aggregates.md) (only for the `minimum` and `maximum` aggregate functions)
- [input types](mutations/inserts.md) (used with mutations for inserting or updating records)
- [filter types](../features/filtering.md) (used for filtering records)
Several examples are provided below.
Example: reading data from the system.
```graphql { title = "Query" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
generalLedgerAccount(first: 2)
{
items {
accountNo
name
changedDate
changedDateAsDate
changedTime
changedTimeAsTime
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"generalLedgerAccount": {
"items": [
{
"accountNo": 1000,
"name": "Forskning og utvikling",
"changedDate": 20210218,
"changedDateAsDate": "2021-02-18",
"changedTime": 1710,
"changedTimeAsTime": "17:10"
},
{
"accountNo": 1020,
"name": "Konsesjoner",
"changedDate": 20210219,
"changedDateAsDate": "2021-02-19",
"changedTime": 1020,
"changedTimeAsTime": "10:20"
}
]
}
}
}
}
```
Example: filtering data.
```graphql { title = "Query" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
order(
first : 2,
filter : {
orderDateAsDate : {_gt : "2015-01-01"}
}
)
{
totalCount
items {
orderNo
orderDate
orderDateAsDate
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"order": {
"totalCount": 268,
"items": [
{
"orderNo": 75,
"orderDate": 20150115,
"orderDateAsDate": "2015-01-15"
},
{
"orderNo": 76,
"orderDate": 20150116,
"orderDateAsDate": "2015-01-16"
}
]
}
}
}
}
```
Example: input values in insert and update mutations.
```graphql { title = "Query" }
mutation create($cid : Int!)
{
useCompany(no: $cid)
{
order_create(values :[{
orderNo : 999,
orderDateAsDate : "2021-10-25"
}])
{
affectedRows
items
{
orderNo
orderDate
orderDateAsDate
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"order_create": {
"affectedRows": 1,
"items": [
{
"orderNo": 999,
"orderDate": 20211025,
"orderDateAsDate": "2021-10-25"
}
]
}
}
}
}
```
Example: computing aggregates `minimum` and `maximum`.
```graphql { title = "Query" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
order_aggregate
{
minimum
{
orderDate
orderDateAsDate
changedTime
changedTimeAsTime
}
maximum
{
orderDate
orderDateAsDate
changedTime
changedTimeAsTime
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"order_aggregate": {
"minimum": {
"orderDate": 20130105,
"orderDateAsDate": "2013-01-05",
"changedTime": 901,
"changedTimeAsTime": "09:01"
},
"maximum": {
"orderDate": 20151205,
"orderDateAsDate": "2015-12-05",
"changedTime": 1945,
"changedTimeAsTime": "15:45"
}
}
}
}
}
```
## Datetime special fields
Every Business NXT table contains the following fields:
| Field | Type | Description |
| ----- | ---- | ----------- |
| `createdTimestamp` | datetime | The time point when the record was created (e.g. `2021-10-12 13:24:54.165`). |
| `createdDate` | integer | The date when the record was created (e.g. `20211012`). |
| `createdTime` | integer | The time when the record was created (e.g. `1324`). |
| `createdUser` | integer | The ID of the user that created the record. |
| `changedTimestamp` | datetime | The time point when the record was changed (e.g. `2021-10-12 09:02:13.843`). |
| `changedDate` | integer | The date when the record was last changed (e.g. `20211023`). |
| `changedTime` | integer | The time when the recod was last changed (e.g. `902`). |
| `changedUser` | integer | The ID of the user that made the last change to the record. |
> [!TIP]
>
> For precise values, prefer to use the `createdTimestamp` and `changedTimestamp` fields. These fields are available for all tables and have a higher precision than the date and time fields.
>
> If these fields are `null` then you need to use `createdDate`/`createdTime` and `changedDate`/`changedTime`, respectively.
> [!WARNING]
>
> The created/changed date, time, and timestamp fields are only set when the records are physically preserved to the database. The backend performs the requested operations in memory and preserves results to the database at the end of the request. When you perform an insert and read back values for the created records, the read operation is performed while the records are still in memory. Therefore, if you retrieve after an insert the created date/time/timestamp fields, their value will be `null` or `0`. A separate read operation (decoupled from the insert) will return the actual values.
The pair `createdDate`/`createdTime` represents the point in time when the record was created. Similarly, the pair `changedDate`/`changedTime` represent the point in time when the record was last changed. As previously mentioned, some tables have another field called `changeTimeInMs` that includes seconds and miliseconds to the time. These are important in different contexts, such as fetching data created or changed after a particular moment in time.
In order to simplify the use of these date-time values, the API makes these two pairs available through a compound field, as described in the following table:
| Field | Type | Examples |
| ----- | ---- | ----------- |
| `createdDateTime` | datetime | `2021-10-21T13:20:00` |
| `changedDateTime` | datetime | `2021-10-22T14:59:00` or `2021-10-22T14:59:22.456` (where `changeTimeInMs` is available) |
These values do not indicate the timezone (as previously mentioned). They represent the local time of the server. A companion set of fields suffixed with `Utc` are available, which represent the same date-time values, but in the Coordinated Universal Time (UTC) timezone.
| Field | Type | Examples |
| ----- | ---- | ----------- |
| `createdDateTimeUtc` | datetime | `2021-10-21T13:20:00Z` |
| `changedDateTimeUtc` | datetime | `2021-10-22T14:59:00Z` or `2021-10-22T14:59:22.456Z` (where `changeTimeInMs` is available) |
In the following example, the `changedDateTime` is used to select all the general ledger accounts that have been modified since `2021-10-01 17:00:00`.
```graphql { title = "Query" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
generalLedgerAccount(filter : {
changedDateTime : {
_gte: "2021-10-01T17:00:00"}
})
{
totalCount
items
{
accountNo
name
createdDateTime
createdDateTimeUtc
changedDateTime
changedDateTimeUtc
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"generalLedgerAccount": {
"totalCount": 2,
"items": [
{
"accountNo": 9001,
"name": "Special ACC",
"createdDateTime": "2021-10-21T13:20:00",
"createdDateTimeUtc": "2021-10-21T13:20:00Z",
"changedDateTime": "2021-10-21T13:21:00",
"changedDateTimeUtc": "2021-10-21T13:21:00Z"
},
{
"accountNo": 9002,
"name": "Extra ACC",
"createdDateTime": "2021-10-21T13:20:00",
"createdDateTimeUtc": "2021-10-21T13:20:00Z",
"changedDateTime": "2021-10-21T13:21:00",
"changedDateTimeUtc": "2021-10-21T13:21:00Z"
}
]
}
}
}
}
```
The use of the `changedDateTime` or `createdDateTime` field is equivalent to the use of an expression built with the `changedDate`/`changedTime` or `changedDate`/`changeTimeInMs` fields (when available) or, respectively, the `createdDate`/`createdTime` fields. Alternatively, the `changedDateAsDate`/`changedTimeAsTime` and the `createdDateAsDate`/`createdTimeAsTime` fields can be used.
Expression:
```
changedDateTime OP 2021-10-21T13:20:00
```
Equivalent to:
```
(changedDate OP 20211021) OR (changedDate == 20211021 AND changedTime OP 1320)
or
(changedDateAsDate OP "2021-10-21") OR (changedDateAsDate == "2021-10-21" AND changedTimeAsTime OP "13:20")
```
Expression (where `changeTimeInMs` exists):
```
changedDateTime OP 2021-10-21T13:20:10.500
```
Equivalent to:
```
(changedDate OP 20211021) OR (changedDate == 20211021 AND changeTimeInMs OP 48010500)
or
(changedDateAsDate OP "2021-10-21") OR (changedDateAsDate == "2021-10-21" AND changedTimeInMsAsTime OP "13:20:10.500")
```
Where `OP` is `_gt`, `_gte`, `_lt`, `lte`.
An example for the filter expression `changedDateTime >= "2021-10-01T07:00:00"` is provided below:
```graphql { title = "Query" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
generalLedgerAccount(filter : {
changedDateTime : {
_gte : "2021-10-01T07:00:00"},
})
{
totalCount
items
{
accountNo
name
createdDateTime
changedDateTime
}
}
}
}
```
```graphql { title = "Equivalent" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
generalLedgerAccount(filter : {
_or : [
{changedDate : {_gt : 20211001}},
{
_and : [
{changedDate : {_eq : 20211001}},
{changedTime : {_gte : 700}}
]
}
]
})
{
totalCount
items
{
accountNo
name
createdDateTime
changedDateTime
}
}
}
}
```
To filter with a date time value that includes second and milliseconds the query and its equivalent are as follows (example for `changedDateTime >= "2023-05-16T07:17:28.659"`):
```graphql { title = "Query" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
order(
filter : {
changedDateTime : {
_gte : "2023-05-16T07:17:28.659"}
}
)
{
totalCount
items
{
orderNo
orderDate
changedDateTime
}
}
}
}
```
```graphql { title = "Equivalent" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
order(filter : {
_or : [
{changedDate : {_gt : 20230516}},
{
_and : [
{changedDate : {_eq : 20230516}},
{changeTimeInMs : {_gte : 26248659}}
]
}
]
})
{
totalCount
items
{
orderNo
orderDate
changedDateTime
}
}
}
}
```
The datetime format has the ISO8601 compliant form `yyyy-mm-ddTHH:mm:ss.ms`, such as `2021-10-01T07:00:00` and `2023-05-16T07:17:28.659` in the examples above.
In the case of filter objects, the `changedDateTime` and `createdDateTime` fields have a companion field called `changedDateTimeTZ` and `createdDateTimeTZ`, respectively. The values for thse two fields is expected to be in a specific timezone. Therefore, it will be converted to the local time before being compared with date and time values in the database.
```
query read($cid : Int!)
{
useCompany(no: $cid)
{
order(
filter : {
changedDateTimeTZ : {
_gte : "2023-05-16T09:17:28.659+02:00"}
}
)
{
totalCount
items
{
orderNo
orderDate
changedDateTimeUtc
}
}
}
}
```
The Business NXT time fields to not store seconds, only hours and minutes. For the tables that have the `changeTimeInMs` field available, seconds and milliseconds are also available. However, for the majority of tables, this field is not present. Regardless the case, when you use the `createdDateTime` and `changedDateTime` fields and specify a date-time value, you must also supply a value for seconds. Failure to do so, such as in the example `2021-10-01T07:00` will result in the following GraphQL error:
```json { title = "Equivalent" }
{
"errors": [
{
"message": "Argument 'filter' has invalid value. In field 'changedDateTime': [In field '_gte': [Expected type 'DateTime', found \"2021-10-01T07:00\".]]",
"locations": [
{
"line": 5,
"column": 26
}
],
"extensions": {
"code": "ARGUMENTS_OF_CORRECT_TYPE",
"codes": [
"ARGUMENTS_OF_CORRECT_TYPE"
],
"number": "5.6.1"
}
}
]
}
```
Bitflags
/businessnxtapi/apireference/schema/bitflags
page
Bitflags allow managing preferences and statuses using bit flags in integer columns. GraphQL queries and mutations simplify interacting with these fields.
2026-07-10T12:31:03+03:00
# Bitflags
Bitflags allow managing preferences and statuses using bit flags in integer columns. GraphQL queries and mutations simplify interacting with these fields.
Some table columns store various preferences, statuses, or other kind of data that is defined using bit flags. These columns have the type `Int`.
Working with them directly, however, requires good knowledge of the corresponding bitflags (both their value and their meaning).
To ease this scenarios, all such columns have a corresponding columns with the same name but suffixed with `Flags`, which is defined as an array of an enumeration.
An example of such a column is `OrderPreferences` from the `Order` table. It can store a combination of the following flags:
| Name | Value | Description |
| ---- | ----- | ----------- |
| CreditNote | 2 | Credit note |
| BatchInvoice | 4 | Batch invoice |
| JustifyExchangeRates | 8 | Justify exchange rate |
| ExemptFromInvoiceFee | 16 | Exempt from invoice fee |
| GrossOrder | 256 | Gross order |
| ReserveOnSave | 512 | Reserve on save |
| AcceptChangesManually | 1024 | Accept changes manually |
| ReservationWithinLeadTime | 2048 | Reserve within lead time |
| ProduceCid | 4096 | Produce CID code |
| PickWholeOrder | 8192 | Pick complete order |
| InvoiceNoFromLabel | 16384 | Invoice no. from 'Label'. |
| DeductFromClientBankAccount | 32768 | Withdrawal from client bank account |
| PostToClientBankAccount | 65536 | Post to client bank account |
| UseClientResponsibility2 | 131072 | Use client responsibility 2 |
| FreeOfInterest | 262144 | Ref. Entry Free of interest |
| Prepayment | 524288 | Prepayment |
| FreeOfReminderFee | 1048576 | Ref. Entry Free of reminder fee |
| DontCopyFromRemittanceSupplier | 2097152 | Do not copy from payment supplier |
| UseClientResponsibility3 | 4194304 | Use client responsibility 3 |
| ExcludeFromReduplication | 8388608 | Exclude from reduplication |
| DontMoveConfirmedDeliveryDateEarlier | 16777216 | Do not move confirmed delivery date to earlier |
| UseOriginalExchangeRateOnCreditNotes | 33554432 | Use original exchange rate on credit notes |
In the GraphQL schema, the following two fields are available, for the `OrderPreferences` column:
The field `orderPreferences` is an integer, while the field `orderPreferencesFlags` is an array of the enumeration type `OrderPreferencesDomain`, shown below:
We can query these fields as follows:
```graphql { title = "Query" }
query read_order_preferences($cid : Int!)
{
useCompany(no: $cid)
{
order
{
items
{
orderPreferences
orderPreferencesFlags
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"order": {
"items": [
{
"orderPreferences": 16640,
"orderPreferencesFlags": [
"GrossOrder",
"InvoiceNoFromLabel"
]
},
{
"orderPreferences": 0,
"orderPreferencesFlags": []
},
...
]
}
}
}
}
```
The bitflags can be used when inserting new records or when updating an existing record. This is shown in the next examples:
```graphql { title = "Query" }
mutation insert_order($cid: Int)
{
useCompany(no: $cid)
{
order_create(values: [
{
orderPreferencesFlags : [
GrossOrder,
PickWholeOrder,
FreeOfReminderFee
]
}
])
{
affectedRows
items
{
orderNo
orderPreferences
orderPreferencesFlags
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"order_create": {
"affectedRows": 1,
"items": [
{
"orderNo": 4498,
"orderPreferences": 1057024,
"orderPreferencesFlags": [
"GrossOrder",
"PickWholeOrder",
"FreeOfReminderFee"
]
}
]
}
}
}
}
```
```graphql { title = "Update" }
mutation update_order($cid: Int, $ono : Int!)
{
useCompany(no: $cid)
{
order_update(
filter : {orderNo : {_eq : $ono}},
value: {
orderPreferencesFlags : [
GrossOrder,
InvoiceNoFromLabel
]
})
{
affectedRows
items
{
orderNo
orderPreferences
orderPreferencesFlags
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"order_update": {
"affectedRows": 1,
"items": [
{
"orderNo": 4498,
"orderPreferences": 16640,
"orderPreferencesFlags": [
"GrossOrder",
"InvoiceNoFromLabel"
]
}
]
}
}
}
}
```
To reset (erase) all the bitflags of a column, you can choose between:
- Using the integer column and set the value to `0` (e.g. `orderPreferences : 0`).
- Using the flags column and set the value to an empty array, i.e. `[]` (e.g. `orderPreferencesFlags : []`). This second option is exemplified next:
```graphql { title = "Update" }
mutation update_order($cid: Int, $ono : Int!)
{
useCompany(no: $cid)
{
order_update(
filter : {orderNo : {_eq : $ono}},
value: {
orderPreferencesFlags : []
})
{
affectedRows
items
{
orderNo
orderPreferences
orderPreferencesFlags
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"order_update": {
"affectedRows": 1,
"items": [
{
"orderNo": 4498,
"orderPreferences": 0,
"orderPreferencesFlags": []
}
]
}
}
}
}
```
The bitflag fields can also be used in filters, with one of the following operators:
| Operator | Description |
| -------- | ----------- |
| `_is_on` | The specified flag is active (present among the enabled flags). |
| `_is_off` | The specified flag is not active (not present among the enabled flags). |
| `_eq` | The column value is set to exactly the specified flag (the specified flag is the only one that is active). |
| `_not_eq` | The column valus is not set to exactly the specified flag. |
An example is used in the following snippet:
```graphql { title = "Query" }
query read_order($cid: Int)
{
useCompany(no: $cid)
{
order(filter : {
orderPreferencesFlags : {_is_on : GrossOrder}})
{
totalCount
items
{
orderNo
orderPreferences
orderPreferencesFlags
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"order": {
"totalCount": 10,
"items": [
{
"orderNo": 132,
"orderPreferences": 16640,
"orderPreferencesFlags": [
"GrossOrder",
"PostToClientBankAccount"
]
},
...
]
}
}
}
}
```
Flags can be provided as a variable as shown in the following examples:
```graphql { title = "Update" }
mutation update_order($cid: Int,
$ono : Int!,
$opf : [OrderPreferencesDomain])
{
useCompany(no: $cid)
{
order_update(
filter : {orderNo : {_eq : $ono}},
value: {
orderPreferencesFlags : $opf
})
{
affectedRows
items
{
orderNo
orderPreferences
orderPreferencesFlags
}
}
}
}
```
```graphql { title = "Variables" }
{
"cid" : 123456789,
"ono" : 42,
"opf": [
"GrossOrder",
"PickWholeOrder",
"FreeOfReminderFee"
]
}
```
```graphql { title = "Update" }
mutation update_order($cid: Int,
$ono : Int!,
$ord : Order_Input!)
{
useCompany(no: $cid)
{
order_update(
filter : {orderNo : {_eq : $ono}},
value: $ord)
{
affectedRows
items
{
orderNo
orderPreferences
orderPreferencesFlags
}
}
}
}
```
```graphql { title = "Variables" }
{
"cid" : 12345678,
"ono" : 42,
"ord": {
"orderPreferencesFlags" : [
"GrossOrder",
"PickWholeOrder",
"FreeOfReminderFee"
]
}
}
```
## Setting and clearing individual bits
It is possible to set or clear individual bits (flags) without affecting the other bits, by using several special fields that are available for each bitflag column:
- a field named `SetOn` (such as `orderPreferencesSetOn`), of an integer type, that can be used to set one or more bits (flags) on the column, without affecting the other bits
- a field named `SetOff` (such as `orderPreferencesSetOff`) , of an integer type, that can be used to clear one or more bits (flags) on the column, without affecting the other bits
- a field name `FlagsSetOn` (such as `orderPreferencesFlagsSetOn`), of an array of enumeration type, that can be used to set one or more bits (flags) on the column, without affecting the other bits
- a field name `FlagsSetOff` (such as `orderPreferencesFlagsSetOff`), of an array of enumeration type, that can be used to clear one or more bits (flags) on the column, without affecting the other bits
Examples for using these fields are shown below:
```graphql { title = "Update" }
mutation set_on($cid: Int, $ono: Int!)
{
useCompany(no: $cid) {
order_update(
filters: [{ orderNo: { _eq: $ono } }],
values: [{ orderPreferencesSetOn: 20480 }]
)
{
affectedRows
items
{
orderNo
orderPreferences
}
}
}
}
```
```graphql { title = "Update" }
mutation set_on($cid: Int, $ono: Int!)
{
useCompany(no: $cid) {
order_update(
filters: [{ orderNo: { _eq: $ono } }],
values: [{ orderPreferencesSetOff: 256 }]
)
{
affectedRows
items
{
orderNo
orderPreferences
}
}
}
}
```
The `setOn` and `setOff` fields can be used at the same time, except that:
- They cannot set and clear the same bit (flag) at the same time.
- They cannot be used together with the base field (for instance set both `orderPreferences` and `orderPreferencesSetOn` in the same operation).
If any of these happens, an error occurs and the operation is not performed.
```graphql { title = "Update" }
mutation set_on($cid: Int, $ono: Int!)
{
useCompany(no: $cid) {
order_update(
filters: [{ orderNo: { _eq: $ono } }],
values: [{
orderPreferencesSetOn: 20480
orderPreferencesSetOff: 256
}]
)
{
affectedRows
items
{
orderNo
orderPreferences
}
}
}
}
```
The examples previously shown can be rewritten using the `FlagsSetOn` and `FlagsSetOff` fields, which are more readable:
```graphql { title = "Update" }
mutation set_on($cid: Int, $ono: Int!)
{
useCompany(no: $cid) {
order_update(
filters: [{ orderNo: { _eq: $ono } }],
values: [{ orderPreferencesFlagsSetOn: [ProduceCid, InvoiceNoFromLabel] }]
)
{
affectedRows
items
{
orderNo
orderPreferencesFlags
}
}
}
}
```
```graphql { title = "Update" }
mutation set_on($cid: Int, $ono: Int!)
{
useCompany(no: $cid) {
order_update(
filters: [{ orderNo: { _eq: $ono } }],
values: [{ orderPreferencesFlagsSetOff: [GrossOrder] }]
)
{
affectedRows
items
{
orderNo
orderPreferencesFlags
}
}
}
}
```
```graphql { title = "Update" }
mutation set_on($cid: Int, $ono: Int!)
{
useCompany(no: $cid) {
order_update(
filters: [{ orderNo: { _eq: $ono } }],
values: [
{
orderPreferencesFlagsSetOn: [ProduceCid, InvoiceNoFromLabel],
orderPreferencesFlagsSetOff: [GrossOrder]
}]
)
{
affectedRows
items
{
orderNo
orderPreferencesFlags
}
}
}
}
```
You can also set and clear individual bits when using extensions. In this case, use the `setOn` and `setOff` fields. An example (equivalent for the previous query) is shown in the following snippet:
```graphql { title = "Update" }
mutation set_on($cid: Int, $ono: Int!)
{
useCompany(no: $cid) {
table_update(
name : "order",
filters: [{
column: "orderNo",
integerValue: { _eq: $ono }
}],
values: [{
column: "orderPreferences",
setOn: 20480,
setOff: 256
}]
)
{
affectedRows
items
{
orderNo : integerValue
orderPreferences : integerValue
}
}
}
}
```
Enum fields
/businessnxtapi/apireference/schema/enumdomains
page
Some columns, arguments, or result values are enumeration values. GraphQL defines fields suffixed with AsEnum to handle them using native enumeration values.
2026-07-10T12:31:03+03:00
# Enum fields
Some columns, arguments, or result values are enumeration values. GraphQL defines fields suffixed with AsEnum to handle them using native enumeration values.
Columns, as well as arguments and result values for processings and reports, have an associated domain for their value. This can be integer, decimal, string, or binary for example. However, there are cases when the domain is an enumeration type. Examples for this include the `orderType` for an order, or the `finishType` argument for the order finish processing.
In GraphQL, for every such column, parameter, or result whose value is an enumeration type, there are two fields available:
- a field with the same name as the column, parameter, or result, which returns the value as the underlying integral type (e.g. `orderType`, `finishType`)
- a field with the same name as the column, parameter, or result, but suffixed with `AsEnum`, which returns the value as an enumeration type (e.g. `orderTypeAsEnum`, `finishTypeAsEnum`)
The `AsEnum` fields enable you to define query without having to know what are the exact numerical values for a field and what they actually mean, since their meaning is defined by the name of enumeration values. For instance, the `orgUnit1Processing` to `orgUnit12Processing` fields have the following possible values:
| Name | Value |
| ---- | ----- |
| Blocked | 0 |
| InUse | 1 |
| Stop | 2 |
| Mandatory | 3 |
These fields can be used as follows:
```graphql { title = "Query" }
mutation create_gla($cid : Int!, $no : Int!, $name : String!)
{
useCompany(no: $cid)
{
generalLedgerAccount_create(values:[
{
accountNo : $no,
name: "demo",
orgUnit1ProcessingAsEnum : Mandatory
orgUnit2ProcessingAsEnum : InUse
}
])
{
affectedRows
items {
accountNo
name
shortName
orgUnit1ProcessingAsEnum
orgUnit2ProcessingAsEnum
orgUnit3ProcessingAsEnum
orgUnit1Processing
orgUnit2Processing
orgUnit3Processing
editStatusAsEnum
}
}
}
}
```
```json { title = "Result" }
{
"data": {
"useCompany": {
"generalLedgerAccount_create": {
"affectedRows": 1,
"items": [
{
"accountNo": 12345,
"name": "Demo",
"shortName": "",
"orgUnit1ProcessingAsEnum": "Mandatory",
"orgUnit2ProcessingAsEnum": "InUse",
"orgUnit3ProcessingAsEnum": "Blocked",
"orgUnit1Processing": 3,
"orgUnit2Processing": 1,
"orgUnit3Processing": 0,
"editStatusAsEnum": "Inserted"
}
]
}
}
}
}
```
Model information
/businessnxtapi/apireference/schema/modelinfo
page
Query model information using useModel to retrieve details on tables, columns, relations, domains, processings, reports, and folders.
2026-07-10T12:31:03+03:00
# Model information
Query model information using useModel to retrieve details on tables, columns, relations, domains, processings, reports, and folders.
## Overview
You can query information from the data model. This is possible using the `useModel` field in the top-level query. This allows to retrieve information about the following entities:
- tables
- columns
- relations
- domains and domain members
- processings
- reports
- folders
You can query the core model only, the extension model only, or both models together.
The information that is available for each entity include:
- primary key (such as `tableNo` for tables, `columnNo` and `tableNo` for columns, etc.)
- identifier, which is a language-independent name of the field; this is what the GraphQL schema uses for entity names
- name, which is a language-specific name for the entity
- access restrictions and availability
In addition, each type of entity has it's own specific fields.
The languages supported for translations are:
- English (this is the default, if no language is specified)
- Norwegian
- Swedish
- Danish
- Finnish
## Examples
Here is an example for fetching table information: ID, identifier, name in Norwgian, and the database type it belongs to (which can be either `COMPANY` or `SYSTEM`) for all the existing tables in the core model:
```graphql { title = "Query" }
query get_tables_info
{
useModel(lang: NORWEGIAN)
{
tables
{
tableNo
name
identifier
databaseType
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useModel": {
"tables": [
{
"tableNo": 1,
"name": "ArbeidsomrÃ¥deÂvindu",
"identifier": "WorkspaceWindow",
"databaseType": "SYSTEM"
},
{
"tableNo": 2,
"name": "ArbeidsomrÃ¥deÂelement",
"identifier": "WorkspacePageElement",
"databaseType": "SYSTEM"
},
# ...
{
"tableNo": 457,
"name": "Inngående betalingslinje",
"identifier": "AutopayVipPaymentLine",
"databaseType": "COMPANY"
},
{
"tableNo": 458,
"name": "Inngående betaling ekstratekst",
"identifier": "AutopayVipTextInfo",
"databaseType": "COMPANY"
}
]
}
}
}
```
On the other hand, it's possible to ask for this information for a specific table by specifying the table number:
```graphql { title = "Query" }
query get_table_info
{
useModel(lang: NORWEGIAN)
{
tables(tableNo : 152)
{
tableNo
name
identifier
databaseType
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useModel": {
"tables": [
{
"tableNo": 152,
"name": "Aktør",
"identifier": "Associate",
"databaseType": "COMPANY"
}
]
}
}
}
```
For a table it is possible to fetch the following information:
- the list of columns
- the list of processings and reports
- the list of relations from and to the table
The following example shows how to do this:
```graphql { title = "Query" }
query get_table_info
{
useModel(lang: NORWEGIAN)
{
tables(tableNo : 65)
{
tableNo
name
identifier
databaseType
view
primaryKeyClustered
orgUnitClass
folderNo
formView
primaryKeyAssignment
columns
{
columnNo
name
identifier
domain
{
domainNo
domainTypeNo
domainMembers
{
name
identifier
groupName
valueNo
}
}
}
fromRelationsNo
fromRelations
{
relationNo
name
identifier
fromTableNo
toTableNo
fromColumnsNo
toColumnsNo
}
toRelationsNo
toRelations
{
relationNo
name
identifier
fromTableNo
toTableNo
fromColumnsNo
toColumnsNo
}
processingsNo
processings
{
processingNo
name
identifier
description
rowIndependent
}
reportsNo
reports
{
reportNo
name
identifier
description
}
visible
cloudVisible
insertable
cloudInsertable
updatable
cloudUpdatable
deletable
cloudDeletable
readAccess
cloudReadAccess
insertAccess
cloudInsertAccess
updateAccess
cloudUpdateAccess
deleteAccess
cloudDeleteAccess
availability
}
}
}
```
Similarly, you can query, for instance, for:
- all the columns in the system
- all the columns of a specified table
- a single column specifed by its column number
In the next example, we query information about all the columns from the `Associate` table:
```graphql { title = "Query" }
query get_columns_info
{
useModel(lang: NORWEGIAN)
{
columns(tableNo : 152)
{
columnNo
tableNo
name
identifier
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useModel": {
"columns": [
{
"columnNo": 4028,
"name": "Aktørnr",
"identifier": "AssociateNo"
},
{
"columnNo": 4029,
"name": "Navn",
"identifier": "Name"
},
# ...
]
}
}}
```
On the other hand, in the next example, we query information about the associate number column (from the `Associate` table):
```graphql { title = "Query" }
query get_column_info
{
useModel(lang: NORWEGIAN)
{
columns(columnNo: 4028)
{
columnNo
tableNo
name
identifier
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useModel": {
"columns": [
{
"columnNo": 4028,
"tableNo": 152,
"name": "Aktørnr",
"identifier": "AssociateNo"
}
]
}
}
}
```
You can additionaly query for domain information for a column, as shown in the following example:
```graphql { title = "Query" }
query read_column_info
{
useModel(lang: NORWEGIAN)
{
columns(columnNo : 3363)
{
columnNo
tableNo
name
domain
{
domainNo
name
length
columnWidth
storeFixedDecimals
displayFixedDecimals
fixedDecimals
dataType
fieldJustification
fileName
domainMembers
{
name
identifier
valueNo
includeValue
initiallyOn
}
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useModel": {
"columns": [
{
"columnNo": 3363,
"tableNo": 52,
"name": "Ordrenr",
"domain": {
"domainNo": 555,
"name": "Ordrenr",
"length": 0,
"columnWidth": 8,
"storeFixedDecimals": false,
"displayFixedDecimals": false,
"fixedDecimals": 0,
"dataType": "INT_32",
"fieldJustification": "RIGHT",
"fileName": false,
"domainMembers": []
}
}
]
}
}
}
```
You can also query domains directly, by specifying the domain number:
```graphql { title = "Query" }
query read_domain_info
{
useModel(lang: NORWEGIAN)
{
domains(domainNo : 555)
{
domainNo
name
length
columnWidth
storeFixedDecimals
displayFixedDecimals
fixedDecimals
dataType
fieldJustification
fileName
domainMembers
{
name
identifier
groupName
valueNo
includeValue
groupIncludeValue
initiallyOn
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useModel": {
"domains": [
{
"domainNo": 555,
"name": "Ordrenr",
"length": 0,
"columnWidth": 8,
"storeFixedDecimals": false,
"displayFixedDecimals": false,
"fixedDecimals": 0,
"dataType": "INT_32",
"fieldJustification": "RIGHT",
"fileName": false,
"domainMembers": []
}
]
}
}
}
```
Some domains are enumeration types. They define a set of possible values that can be stored in a column. The `domainMembers` field in the domain information query returns a list of domain members. An example is shown below:
```graphql { title = "Query" }
query read_domain_info
{
useModel(lang: NORWEGIAN)
{
domains(domainNo : 111)
{
domainNo
name
length
columnWidth
storeFixedDecimals
displayFixedDecimals
fixedDecimals
dataType
fieldJustification
fileName
domainMembers
{
name
identifier
groupName
valueNo
includeValue
groupIncludeValue
initiallyOn
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useModel": {
"domains": [
{
"domainNo": 111,
"name": "Dok.Âtype",
"length": 0,
"columnWidth": 8,
"storeFixedDecimals": false,
"displayFixedDecimals": false,
"fixedDecimals": 0,
"dataType": "INT_32",
"fieldJustification": "RIGHT",
"fileName": false,
"domainMembers": [
{
"name": "Purrebrev",
"identifier": "Reminder",
"groupName": "",
"valueNo": 1,
"includeValue": -1,
"groupIncludeValue": -1,
"initiallyOn": false
},
{
"name": "Rentenota",
"identifier": "InterestNote",
"groupName": "",
"valueNo": 2,
"includeValue": -1,
"groupIncludeValue": -1,
"initiallyOn": false
}
]
}
]
}
}
}
```
## Selecting the model
It is possible to query the core mode, the customer specific extensions to the model, or both together. This is done using the `model` argument for the `useModel` field, which can take the following values:
| Value | Description |
| ----- | ----------- |
| `CORE` | Only the core model is queried. This is the default value. |
| `EXTENSIONS` | Only the extension model is queried. |
| `ALL` | Both the core and the extension model are queried. |
If you specify a core model but a model number such as table number or column number from the extensions or vice versa, no results will be returned, since the specified model does not contain the specified entity.
When the model is explicitly specified, a customer number is also required, since extensions are customer specific. If a customer number is not specified, an error will be returned.
The following example shows how to query all the tables from the extensions:
```graphql { title = "Query" }
query read_tables($cno : Int!)
{
useModel(customer : $cno, model : EXTENSIONS)
{
tables
{
tableNo
name
identifier
databaseType
}
}
}
```
## Query arguments
There are several arguments that allow you to customize the query:
| Argument | Description |
| -------- | ----------- |
| `lang` | Specifies the language for the translated text fields. Possible values are `ENGLISH`, `NORWEGIAN`, `SWEDISH`, and `DANISH`. |
| `langNo` | Specifies the language for the translated text fields using a numeric value. Possible values are `44` (English), `45` (Danish), `46` (Swedish), and `47` (Norwegian). If both `lang` and `langNo` are specified, `lang` is used and `langNo` is ignored. |
| `transform` | Indicates how the text of the name field should be transformed. |
| `transformArgs` | Defines the transformation arguments when the `CUSTOM` value is specified for the `transform` argument. More information about text transformation can be found in the next section. |
These areguments are found on the `useModel` field. A deprecated way to specify the arguments is on the individual fields such as `tables`, `columns`, etc. When present on both the `useModel` field and the individual fields, the arguments on the individual fields are ignored.
In addition to these arguments, each field for retrieving model information (such as `tables`, `columns`, etc.) has its own specific arguments, typically for selecting a single entity, we was shown in the examples above (e.g. `tableNo` for tables, `columnNo` for columns, etc.).
### Language selection
The language for the translations can be specified in two ways:
- using the `lang` argument in the query, with one of the following values: `ENGLISH`, `NORWEGIAN`, `SWEDISH`, `DANISH`
- using the `langNo` argument in the query, with one of the following values: `44` (English), `45` (Danish), `46` (Swedish), `47` (Norwegian)
If both arguments are specified, the `lang` argument is used (`langNo` is ignored).
The following two examples are equivalent:
```graphql { title = "Query" }
query get_tables_info
{
useModel(lang: NORWEGIAN)
{
tables
{
tableNo
name
identifier
databaseType
}
}
}
```
```graphql { title = "Result" }
query get_tables_info
{
useModel(langNo: 47)
{
tables
{
tableNo
name
identifier
databaseType
}
}
}
```
The `langNo` argument is useful for specifying the language based directly on settings, such as the user's language preference (from the `User` table).
### Text transformations
The translated text may contain several application-specific escape characters or sequences. These are:
- `^` for a hyphen
- `|` for a new line (`\n`)
- `&` for an access key accelerator
- `{Ampersand}` for an `&` character
When you retrieve the translated texts, these are automatically replaced with the appropriate character or sequence of characters. However, you can opt to perform your own custom replacement. This is possible with the following two arguments, available for all the fields under `useModel`:
| Argument | Description |
| -------- | ----------- |
| `transform` | Indicates the transformation type: `AUTO` (the default option, application defined transformations), `NONE` (no transformation is performed), and `CUSTOM` (user-specified transformations are applied). |
| `transformArgs` | Defines the transformation arguments when the `CUSTOM` value is specified for the `transform` argument. |
The properties of the `transformArgs` parameter are as follows:
| Property | Type | Description |
| -------- | ---- | ----------- |
| `modifyOptionalHyphen` | Boolean | Indicates whether hyphen replacement will be performed. |
| `optionalHyphen` | String | Text for replacing the escape character (`^`) for a hyphen. |
| `modifyManualLineBreak` | Boolean | Indicates whether manual line break replacement will be performed. |
| `manualLineBreak` | String | Text replacing the escape character for manual line break. |
| `modifyAccessKey` | Boolean | Indicates whether access key replacement will be performed. |
| `accessKey` | String | Text for replacing the escape character (`&`) for an access key. |
| `modifyAmpersandSubstitute` | Boolean | Indicates whether ampersand substitute replacement will be performed. |
| `ampersandSubstitute` | String | Text for replacing the `{Ampersand}` escape sequence. |
Here is an example for fetching raw texts:
```graphql { title = "Query" }
query get_table_info
{
useModel(lang: NORWEGIAN, transform : NONE)
{
tables(tableNo : 138)
{
tableNo
name
identifier
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useModel": {
"tables": [
{
"tableNo": 138,
"name": "Ordre^journal",
"identifier": "OrderJournal"
}
]
}
}
}
```
On the other hand, the following sample shows how to perform user-defined transformations:
```graphql { title = "Query" }
query get_table_info
{
useModel(lang: NORWEGIAN,
transform : CUSTOM,
transformArgs : {
modifyOptionalHyphen : true
optionalHyphen : "-"
})
{
tables(tableNo : 138)
{
tableNo
name
identifier
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useModel": {
"tables": [
{
"tableNo": 138,
"name": "Ordre-journal",
"identifier": "OrderJournal"
}
]
}
}
}
```
## Access restrictions and availability
Most model entities provide properties that indicate the availability and access restrictions. These properties are:
| Property | Type | Description | Applies to |
| -------- | ---- | ----------- | ---------- |
| `visible` | `Bool` | Indicates whether the entity is visible in the on-premise application. | All |
| `cloudVisible` | `Bool` | Indicates whether the entity is visible in the Business NXT front-end application. | All |
| `writable` | `Bool` | Indicates whether the entity is writable in the on-premise application. | Columns, domain members |
| `cloudWritable` | `Bool` | Indicates whether the entity is writable in the Business NXT front-end application. | Columns, domain members |
| `insertable` | `Bool` | Indicates whether the entity is insertable in the on-premise application. | Tables |
| `cloudInsertable` | `Bool` | Indicates whether the entity is insertable in the Business NXT front-end application. | Tables |
| `updatable` | `Bool` | Indicates whether the entity is updatable in the on-premise application. | Tables |
| `cloudUpdatable` | `Bool` | Indicates whether the entity is updatable in the Business NXT front-end application. | Tables |
| `deletable` | `Bool` | Indicates whether the entity is deletable in the on-premise application. | Tables |
| `cloudDeletable` | `Bool` | Indicates whether the entity is deletable in the Business NXT front-end application. | Tables |
| `readAccess` | `Access` | Indicates the read access level for the entity in the on-premise application. | All |
| `cloudReadAccess` | `CloudAccess` | Indicates the read access level for the entity in the Business NXT front-end application. | All |
| `writeAccess` | `Access` | Indicates the write access level for the entity in the on-premise application. | Columns, domain members |
| `cloudWriteAccess` | `CloudAccess` | Indicates the write access level for the entity in the Business NXT front-end application. | Columns, domain members |
| `insertAccess` | `Access` | Indicates the insert access level for the entity in the on-premise application. | Tables |
| `cloudInsertAccess` | `CloudAccess` | Indicates the insert access level for the entity in the Business NXT front-end application. | Tables |
| `updateAccess` | `Access` | Indicates the update access level for the entity in the on-premise application. | Tables |
| `cloudUpdateAccess` | `CloudAccess` | Indicates the update access level for the entity in the Business NXT front-end application. | Tables |
| `deleteAccess` | `Access` | Indicates the delete access level for the entity in the on-premise application. | Tables |
| `cloudDeleteAccess` | `CloudAccess` | Indicates the delete access level for the entity in the Business NXT front-end application. | Tables |
| `deleteAccess` | `Access` | Indicates the delete access level for the entity in the on-premise application. | Tables |
| `cloudDeleteAccess` | `CloudAccess` | Indicates the delete access level for the entity in the Business NXT front-end application. | Tables |
| `executionAccess` | `Access` | Indicates the execution access level for the entity in the on-premise application. | Processings, reports |
| `cloudExecutionAccess` | `CloudAccess` | Indicates the execution access level for the entity in the Business NXT front-end application. | Processings, reports |
| `availability` | `Availability` | Indicates whether the entity is available for use (`CURRENT`), it will be available in the future (`FUTURE`), or it is available but it is deprecated and will be removed (`OBSOLETE`). | All |
The `Default` value for `CloudAccess` indicates that the access level is inherited from the on-premise application.
For a column to be available in GraphQL for reading, the following conditions must be met:
- `availability` should be `CURRENT`
- `cloudReadAccess` must be different than `NONE` and `DEFAULT`
- if `cloudReadAccess` is `DEFAULT` then `readAccess` must be different than `NONE`
Similar rules are used for writing, inserting, updating, deleting, and executing access.
## Model information properties
### Tables
The following properties are available for tables :
| Property | Type | Description |
| -------- | ---- | ----------- |
| `tableNo` | `Long` | The table number. |
| `name` | `String` | The translated name of the table. |
| `identifier` | `String` | A language-independent identifier of the table. |
| `databaseType` | `DatabaseTypeNo` | One of `COMPANY` or `SYSTEM`. |
| `view` | `bool` | Indicates whether the table is a view. |
| `primaryKeys` | `[Long]` | The primary keys' column numbers in the order they're defined in the database. |
| `primaryKeyClustered` | `Bool` | Indicates whether the primary key is clustered. |
| `orgUnitClass` | `OrgUnitClass` | The property returns one of the twelve values `ORGUNITCLASS01` (1) – `ORGUNITCLASS12` (12) if the table is associated with an organisational unit class, else `NONE` (0). The table will not be visible if the corresponding `CompanyInformation.OrgUnit1Name` – `OrgUnit12Name` column is empty. |
| `folderNo` | `Long` | The folder number the table belongs to, or 0 if none. |
| `formView` | `Bool` | `true` if new table page elements against this table should initially be displayed in Form view (instead of Grid view). |
| `primaryKeyAssignment` | `PrimaryKeyAssignment` | Returns one of the following values for how the last primary key column is assigned a value on rows in the table: `NORMAL` - the ordinary behaviour of the table, `INCREMENTAL` - the last primary key column will get the next unused value when a value suggestion is requested, or `IDENTITY` - The last primary key column is created as an IDENTITY column in the database (the last two only for top tables that does not have a sort sequence column). |
| `columns` | `[Query_UseModel_Tables_Columns]` | A collection of column objects for the columns in the table. |
| `fromRelationsNo` | `[Long]` | A collection of relation numbers **from** the table. |
| `fromRelations` | `[Query_UseModel_Tables_Relations]` | A collection of relation **from** the table. |
| `toRelationsNo` | `[Long]` | A collection of relation numbers for the relations **to** the table. |
| `toRelations` | `[Query_UseModel_Tables_Relations]` | A collection of relation **to** the table. |
| `processingsNo` | `[Long]` | A collection of processing numbers for the processings in the table. |
| `processings` | `[Query_UseModel_Tables_Processings]` | A collection of processing in the table. |
| `reportsNo` | `[Long]` | A collection of report numbers for the reports in the table. |
| `reports` | `[Query_UseModel_Tables_Reports]` | A collection of report in the table. |
### Relations
The following properties are available for relations:
| Property | Type | Description |
| -------- | ---- | ----------- |
| `relationNo` | `Long` | The relation number. |
| `name` | `String` | The translated name of the relation. |
| `identifier` | `String` | A language-independent identifier of the relation. |
| `fromTableNo` | `Long` | The table number that this relation refers from. |
| `toTableNo` | `Long` | The table number that this relation refers to. |
| `fromColumnsNo` | `[Long]` | A collection of column numbers that define the from columns. |
| `toColumnsNo` | `[Long]` | A collection of column numbers that define the to columns. |
| `switchOfColumnNo` | `Long` | The number of a column for this relation to apply to. |
| `switchValue` | `Int` | The value that a column needs to have for this relation to apply. E.g. the debit (or credit) account type column on a voucher row that determines whether the debit (or credit) account number column refers to (1) a customer, (2) supplier, (3) general ledger account, or (4) capital asset. |
| `noLookup` | `Bool` | `true` if the relation is not applicable for lookup, but e.g. only for (left outer) join purposes in i.a. layouts. |
| `necessity` | `Necessity` | Returns one of the following values for how necessary a corresponding reference is: `REQUIRED`, `OPTIONAL`, or `PASS`. |
| `deleteRule` | `DeleteRule` | Returns one of the following values to determine behavior when deleting or discarding a parent row: `CASCADE` will also delete or discard child rows, recursively downwards the hierarchy, or `RESTRICT` that demands that no references exist, e.g. to reject deletion of accounts with transactions. |
### Columns
The following properties are available for columns:
| Field | Type | Description |
| ----- | ---- | ----------- |
| `columnNo` | `Long` | The column number. |
| `tableNo` | `Long` | The table number that this column belongs to. |
| `name` | `String` | The translated name of the column. |
| `identifier` | `String` | A language-independent identifier of the column. |
| `orgUnitClass` | `OrgUnitClass` | One of the twelve values `ORGUNITCLASS01` – `ORGUNITCLASS12` if the column is associated with an organisational unit class, else `NONE`. The column will not be visible if the corresponding `CompanyInformation.OrgUnit1Name` – `OrgUnit12Name` column is empty. |
| `suggestValueInInterval` | `Bool` | `true` if the column supports suggesting values in intervals. |
| `breakValues` | `Bool` | `true` if the column by default should show an aggregated value on group and total rows. |
| `accumulateOnMerge` | `Bool` | true if the value in the column should be accumulated when rows are merged, e.g. on collection invoices. |
| `recalculation` | `Recalculation` | one of the following values for whether the value in the column should be recalculated according to the actual value on the current, parent row (order line), when page elements (e.g. stock balance or shipment) are joined via an underlying table (e.g. product): `NO`, `UNIT`, or `PRICE`. |
| `formatting` | `Formatting` | one of the following values for whether the column should apply formatting defined on the row: `NO`, `ROWFRONT`, or `UNDERLINE`. |
| `viewZero` | `ViewZero` | one of the following values for whether 0 should be shown if the column is empty: `NO`, `ZEROIFEMPTY`, or `ZEROIFNOTSUMLINE`. |
| `debitCreditType` | `DebitCreditType` | one of the following values for how the memory column should be calculated: `NONE`, `DEBIT`, `CREDIT`. |
| `currencyHandling` | `CurrencyHandling` | one of the following values for whether the column is involved in currency calculations: `NORMAL`, `LOGISTICSDOMESTICVALUE`, `ACCOUNTINGCURRENCYVALUE`, `ACCOUNTINGDOMESTICVALUE`, `EUROVALUE`, or `CURRENCY2VALUE`. |
| `lookupProcessingNo` | `Long` | The number of the processing that declares the lookup dialog for this column, if any. |
| `domain` | `Query_UseModel_Columns_Domains` | Information about the domain for the column. |
| `sqlName` | `String` | The actual name of the column in the database. |
### Domains and domain members
The following properties are available for domains:
| Field | Type | Description |
| ----- | ---- | ----------- |
| `domainNo` | `Long` | The domain number. |
| `name` | `String` | The translated name of the domain. |
| `identifier` | `String` | A language-independent identifier of the domain. |
| `domainTypeNo` | `Int` | The domain type as a numeric value. |
| `domainTypeNoAsEnum` | `DomainTypeNo` | The domain type as an enumeration value. Can be one of: `VALUE` (1), `TEXTTYPE` (2), `MODELNO` (3), `FLAGS` (4), `INTEGER` (5), `DECIMAL` (6), `LIMITEDSTRING` (7), `UNLIMITEDSTRING` (8), `BLOB` (9), or `DATETIME` (10). |
| `dataType` | `DataType` | The kind of data that is stored in the column. Can be one of: `INT_8`, `INT_16`, `INT_32`, `INT_64`, `DECIMAL`, `LIMITED_STRING`, `UNLIMITED_STRING`, `BLOB`. |
| `lenght` | `Int` | The maximum number of characters that can be stored, or 0 if the domain type is not `LIMITED_STRING`. |
| `columnWidth` | `Decimal` | The default column width, measured in the average number of characters that will fit in the column. |
| `storeFixedDecimals` | `Bool` | `true` if the domain type is `DECIMAL` and a fixed number of decimals should be stored. |
| `displayFixedDecimals` | `Bool` | `true` if the domain type is `DECIMAL` and a fixed number of decimals should be displayed by default. |
| `fixedDecimals` | `Int` | The actual number of fixed decimals (up to 6) that may be applied by default if the domain type is `DECIMAL`, else 0. |
| `fieldJustification` | `FieldJustification` | Returns one of the following values for how the values (and the column heading in grid view) should be aligned by default: `CENTER`, `LEFT`, or `RIGHT`. |
| `fileName` | `Bool` | `true` if the domain type is LimitedString and file name lookup is applicable. |
| `domainMembers` | [`Query_UseModel_Domains_DomainMembers`] | A list of domain member objects. |
The following properties are available for domain members:
| Field | Type | Description |
| ----- | ---- | ----------- |
| `valueNo` | `Long` | Unique domain member indentification number. |
| `identifier` | `String` | A language-independent identifier of the domain member. |
| `name` | `String` | The name of the domain member. |
| `includeValue` | `Int` | An integer value to include in the name, or -1 if not applicable. |
| `groupName` | `String` | The name of the group the domain member belongs to. |
| `groupIncludeValue` | `Int` | An integer value to include in the group name, or -1 if not applicable. |
| `initiallyOn` | `Bool` | `true` if this flag domain member is intended to be initially ON. |
### Processings
The following properties are available for processings:
| Field | Type | Description |
| ----- | ---- | ----------- |
| `processingNo` | `Long` | The processing number. |
| `name` | `String` | The translated name of the processing. |
| `identifier` | `String` | A language-independent identifier of the processing. |
| `description` | `String` | A textual description of the processing. |
| `dialogOnly` | `Bool` | `true` if the processing is intended to only show a dialog, typically visualizing one or more columns. Such processings have no parameters, and no processing contributions in the backend, so operations for getting data for a processing dialog, or executing a processing, should not be performed on them. |
| `rowIndependent` | `Bool` | `true` if the processing is row-independent. |
### Reports
The following properties are available for reports:
| Field | Type | Description |
| ----- | ---- | ----------- |
| `processingNo` | `Long` | The report number. |
| `name` | `String` | The translated name of the report. |
| `identifier` | `String` | A language-independent report of the processing. |
| `description` | `String` | A textual description of the report. |
### Folders
The following properties are available for folders:
| Field | Type | Description |
| ----- | ---- | ----------- |
| `folderNo` | `Long` | The folder number. |
| `name` | `String` | The translated name of the folder. |
| `identifier` | `String` | A language-independent identifier of the folder. |
| `isRoot` | `Lool` | `true` if the folder is a root folder. |
| `parentFolderNo` | `Long` | The number of the parent folder, or 0 if the folder is a root folder. |
| `childFoldersNo` | `[Long]` | A collection of folder numbers for the child folders. |
Available customers
/businessnxtapi/apireference/schema/customers
page
Fetch multiple customers linked to a user via GraphQL, using the availableCustomers query field with optional pagination and sorting.
2026-07-10T12:31:03+03:00
# Available customers
Fetch multiple customers linked to a user via GraphQL, using the availableCustomers query field with optional pagination and sorting.
Typically, a user is associated with a single Visma.net customer. However, it is possible that one user is linked to multipled customers. Business NXT GraphQL allows to fetch all these customers. The list of customers linked to the authenticated user is available with a special field under the `Query` type. This field is called `availableCustomers`. It is similar to the connection types seen so far, except that the `pageInfo` field is missing.
Here is a query example:
```graphql { title = "Query" }
{
availableCustomers
{
totalCount
items
{
name
vismaNetCustomerId
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"availableCustomers": {
"totalCount": 1,
"items": [
{
"name": "Test Customer for Business NXT",
"vismaNetCustomerId": 1234567
}
]
}
}
}
```
The `availableCustomers` field has several optional arguments:
- an argument called `first` that indicates the number of elements to be fetched from the top of the customers list
- an argument called `last` that indicates the number of elements to be fetched from the back of the customers list; if both `first` and `last` are present, `first` is used and `last` is ignored
- an argument called `orderBy` that defines the sorting order of the result
- a deprecated argument called `sortOrder` that defines the sorting order of the result
Available companies
/businessnxtapi/apireference/schema/companies
page
Retrieve a list of companies available to an authenticated user using the availableCompanies GraphQL field, with optional filtering and sorting arguments.
2026-07-10T12:31:03+03:00
# Available companies
Retrieve a list of companies available to an authenticated user using the availableCompanies GraphQL field, with optional filtering and sorting arguments.
The list of companies available to the authenticated user is available with a special field available under the `Query` type. This field is called `availableCompanies`. It is similar to the connection types seen so far, except that the `pageInfo` field is missing.
Here is a query example:
```graphql { title = "Query" }
{
availableCompanies
{
totalCount
items
{
name
vismaNetCompanyId
vismaNetCustomerId
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"availableCompanies": {
"totalCount": 2,
"items": [
{
"name": "Marius Test AS",
"vismaNetCompanyId": 5280...
"vismaNetCustomerId": 9123...
},
{
"name": "JAM&WAFFLES",
"vismaNetCompanyId": 5199...
"vismaNetCustomerId": 9456...
}
]
}
}
}
```
The `availableCompanies` field has several optional arguments:
- an argument called `customerNo` that indicates the Visma.net number of the customer for which available companies should be retrieved
- an argument called `first` that indicates the number of elements to be fetched from the top of the companies list
- an argument called `last` that indicates the number of elements to be fetched from the back of the companies list; if both `first` and `last` are present, `first` is used and `last` is ignored
- an argument called `orderBy` that defines the sorting order of the result
- a deprecated argument called `sortOrder` that defines the sorting order of the result
To fetch companies specific to a particular customer, pass its Visma.net identifier in the `customerNo` parameter, as shown in the following example:
```graphql { title = "Query" }
{
availableCompanies(customerNo : 12345678)
{
totalCount
items
{
name
vismaNetCompanyId
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"availableCompanies": {
"totalCount": 2,
"items": [
{
"name": "Marius Test AS",
"vismaNetCompanyId": 5280...
},
{
"name": "JAM&WAFFLES",
"vismaNetCompanyId": 5199...
}
]
}
}
}
```
If the `customerNo` parameter is missing, the companies available to all the available customers in the list are returned.
To retrieve the list of available customers see [Available customers](customers.md).
## Service context
When you authenticate with client credentials (using a client ID and a client secret), fetching the list of available companies requires specifying a customer no (as described earlier).
You can find out the customer number in two ways:
- Authenticate with a Visma.net user and use the `availableCustomers` field to fetch the list (see [Available customers](customers.md)).
- Retrieve this information from Visma.Net Admin.
To do the latter:
- Logon to
- Open the *Configuration* tab
- Copy the value for *Visma.net Customer ID*
When then customer ID is not provided, an error is returned, as follows:
```json
{
"errors": [
{
"message": "GraphQL.ExecutionError: Could not fetch the list of available companies. Customer number is mandatory."
}
],
"data": {
"availableCompanies": null
},
"extensions": {
"vbnxt-trace-id": "..."
}
}
```
Features
/businessnxtapi/apireference/features
section
Comprehensive GraphQL features - filtering, sorting, pagination, fragments, aliases, directives, error handling, unoptimized queries, batch requests.
2026-07-10T12:31:03+03:00
# Features
Comprehensive GraphQL features - filtering, sorting, pagination, fragments, aliases, directives, error handling, unoptimized queries, batch requests.
Filtering
/businessnxtapi/apireference/features/filtering
page
API filtering enables precise data retrieval using logical operators like _gt, _lt, _like, _in, and _between. It supports complex queries and comparisons.
2026-07-10T12:31:03+03:00
# Filtering
API filtering enables precise data retrieval using logical operators like _gt, _lt, _like, _in, and _between. It supports complex queries and comparisons.
## Overview
Filtering is a key feature of the API. You can specify the filter as a parameter to a connection. Let's look at some examples:
In this first example, we fetch all the general ledger accounts that have the account number greater or equal than 6000 and lower than 7000.
```graphql { title = "Query" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
generalLedgerAccount(
filter: {_and :[
{accountNo :{_gte : 6000}},
{accountNo :{_lt : 7000}}
]}
)
{
totalCount
items
{
accountNo
name
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"generalLedgerAccount": {
"totalCount": 46,
"items": [
{
"accountNo": 6000,
"name": "Avskr. bygn. og annen eiendom"
},
{
"accountNo": 6010,
"name": "Avskr. maskiner, inventar mv."
},
...
]
}
}
}
}
```
We can complicate the query a bit, and ask only for those general ledger accounts in the range 6000 - 7000 that start with "Leie". In this case, the filter would look as follows:
```graphql { title = "Query" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
generalLedgerAccount(
filter: {_and :[
{accountNo :{_gte : 6000}},
{accountNo :{_lt : 7000}},
{name :{_like:"Leie%"}}
]}
)
{
totalCount
items
{
accountNo
name
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"generalLedgerAccount": {
"totalCount": 6,
"items": [
{
"accountNo": 6300,
"name": "Leie lokaler"
},
{
"accountNo": 6400,
"name": "Leie maskiner"
},
{
"accountNo": 6410,
"name": "Leie inventar"
},
{
"accountNo": 6420,
"name": "Leie datasystemer"
},
{
"accountNo": 6430,
"name": "Leie andre kontormaskiner"
},
{
"accountNo": 6440,
"name": "Leie transportmidler"
}
]
}
}
}
}
```
In the next example, we fetch all the associates that are either customers with the number in the range 10000 - 10010, or suppliers, with the number in the range 50000 - 50010.
```graphql { title = "Query" }
query read($cid : Int!)
{
useCompany(no: $cid) {
associate (
filter:{
_or:
[
{
_and : [
{customerNo :{_gt:10000}},
{customerNo :{_lt:10010}}
]
},
{
_and : [
{supplierNo : {_gt:50000}},
{supplierNo : {_lt:50010}},
]
}
]
}
)
{
totalCount
items {
name
customerNo
supplierNo
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"associate": {
"totalCount": 18,
"items": [
{
"name": "YoYo Solutions AS",
"customerNo": 10001,
"supplierNo": 0
},
{
"name": "Spire Business",
"customerNo": 10002,
"supplierNo": 0
},
...
{
"name": "Scorpio Services Limited",
"customerNo": 0,
"supplierNo": 50001
},
{
"name": "Atlas Systems",
"customerNo": 0,
"supplierNo": 50002
},
...
]
}
}
}
}
```
Filtering is very similar to an open-source GraphQL implementation for Postgres databases. You can read more about that [in the Hasura docs](https://hasura.io/docs/1.0/graphql/core/queries/query-filters.html#using-multiple-filters-in-the-same-query-and-or). This document can be used for finding more examples.
The filter for each table type (connection) has its own type. For instance, the filter type for the `Associate` table is called `FilterExpression_Associate`. You can see this if you explore the schema with GraphiQL, for instance:
`FilterExpression_Associate` type, in turn, has field for each column in the table. This fields are of a type called *_FilterClause*, such as `Int32_FilterClause`, `LimitedString_FilterClause`, etc. Two additional fields, `_and` and `_or`, of the same `FilterExpression_Associate` allow composing complex filter with the AND and OR logical operators.
The filter clause type, in turn, has fields representing operators, such as `_lt` or "lower than" or `_like` for the text comparison *like* operator.
The following table lists the available operators:
| Operator | Description |
| -------- | ----------- |
| `_eq` | equal to `value` |
| `_gt` | greater than `value` |
| `_gte` | greater than or equal to `value` |
| `_in` | in list of values |
| `_is_not_null` | is not `null` |
| `_is_null` | is `null` |
| `_is_off` | is `off` - available for bit field columns only |
| `_is_on` | is `on` - available for bit field columns only |
| `_lt` | less than `value` |
| `_lte` | less than or equal to `value` |
| `_like` | like `value` |
| `_not_eq` | not equal `value` |
| `_not_in` | not in list of values |
| `_not_like` | not like `value` |
| `_between` | between `from` and `to` (inclusive bounds) |
| `_not_between` | not between `from` and `to` (exclusive bounds) |
The filter can also be provided as an argument to the query. The filter value is an object of the filter expression type. This is shown in the following example:
```graphql { title = "Query" }
query GetGLAs(
$companyNo: Int,
$filter : FilterExpression_GeneralLedgerAccount)
{
useCompany(no: $companyNo)
{
generalLedgerAccount(filter: $filter)
{
totalCount
items
{
accountNo
name
}
}
}
}
```
```graphql { title = "Variables" }
{
"companyNo": 9112233,
"filter": {"_and" :[
{"accountNo" :{"_gte" : 6000}},
{"accountNo" :{"_lt" : 7000}}]}
}
```
## \_in and \_not\_in operators
Most of the operators take a single value. The `_in` and `_not_in` operators, however, take an array of values, as show in the following example:
```graphql
query read($cid : Int!)
{
useCompany(no: $cid)
{
associate (filter : {customerNo : {_in: [10001,10002,10003]}})
{
totalCount
items
{
name
associateNo
customerNo
supplierNo
}
}
}
}
```
These two operators (`_in` and `_not_in`) are helpful for simplifying more complex filters. The following two tables show a filter using these two operators, and the equivalent expression without them.
```graphql { title = "With_in" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
associate (filter : {
customerNo : {_in: [10001,10002,10003]}})
{
totalCount
items
{
name
associateNo
customerNo
supplierNo
}
}
}
}
```
```graphql { title = "Without_in" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
associate (filter : {_or: [
customerNo : {_eq: 10001},
customerNo : {_eq: 10002},
customerNo : {_eq: 10003}
]})
{
totalCount
items
{
name
associateNo
customerNo
supplierNo
}
}
}
}
```
```graphql { title = "With_in" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
associate (filter : {
customerNo : {_not_in: [10001,10002,10003]}})
{
totalCount
items
{
name
associateNo
customerNo
supplierNo
}
}
}
}
```
```graphql { title = "Without_in" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
associate (filter : {_and: [
customerNo : {_not_eq: 10001},
customerNo : {_not_eq: 10002},
customerNo : {_not_eq: 10003}
]})
{
totalCount
items
{
name
associateNo
customerNo
supplierNo
}
}
}
}
```
If the argument for the `_in` or `_not_in` operators is an empty array, the result will be an empty set.
An example is shown below, where we first query the `Order` table, exporting the value of the `sellerOrBuyer` column to the variable `sellers`. We then query the `Associate` table, filtering for the employees with the numbers in the `sellers` array. Because no order matches the filter, the result is an empty `sellers` array, which results in no data being returned.
```graphql { title = "Query" }
query find_selers($cid: Int!, $sellers: [Int!] = [])
{
useCompany(no: $cid)
{
order(
filter: {sellerOrBuyer: {_gt: 999}},
first: 5)
{
items
{
sellerOrBuyer @export(as: "sellers")
}
}
associate(
filter: {employeeNo: {_in: $sellers}})
{
items
{
employeeNo
name
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"order": {
"items": null
},
"associate": {
"items": null
}
}
}
}
```
If the `_in` or `_not_in` operators are used in an `AND` expression, and the argument is an empty array, the resulting filter will be an empty expression, and no data will be returned.
```graphql
order(
filter: {_and: [
{changeDateTime : {_gte: {"2024-01-24T12:00:00"}}}
{orderNo: {_in: []}}
]})
{
items
{
orderNo
dueDate
}
}
```
This results in an empty filter. No data is returned when a filter is provided but it is empty. On the other hand, when no filter is provided, all the data is returned.
If the `_in` or `_not_in` operators are used in an `OR` expression and the argument is an empty array, the subexpression is removed from the filter expression, which may still produce a valid filter that can return data.
```graphql { title = "Filter" }
filter: {_or: [
{changeDateTime :
{_gte: {"2024-01-24T12:00:00"}}}
{orderNo: {_in: []}}
]}
```
```graphql { title = "Equivalent" }
filter: {_or: [
{changeDateTime :
{_gte: {"2024-01-24T12:00:00"}}}
]}
```
## \_between / \_not\_between operators
These two operators require two values that define the lower and upper bounds of the range. The range is inclusive, meaning that the values that are equal to the lower or upper bound are included in the result.
```graphql
query read_glas($cid : Int!, $pagesize : Int!)
{
useCompany(no: $cid)
{
generalLedgerAccount(
first: $pagesize,
filter : {accountNo : {_between : {from: 1000, to: 2000}}})
{
totalCount
items
{
accountNo
name
}
}
}
}
```
These operators are support for fields of the following types:
- numeric (`Int`, `Long`, `Decimal`, etc.)
- Date
- Time
- DateTime
The following example shows an expression using both the `_between` operator (for an int field) and the `_not_between` operator (for a datetime field):
```graphql
query read_glas($cid : Int!)
{
useCompany(no: $cid)
{
generalLedgerAccount(filter: { _and : [
{accountNo : {
_not_between : {
from : 3000,
to : 5000
}
}},
{changedDateTime : {
_between : {
from : "2024-05-01T12:00:00",
to : "2024-05-30T23:59:59"
}
}}
]})
{
totalCount
items
{
accountNo
name
}
}
}
}
```
## Filtering on joined tables
When reading data, you can fetch data from a table as well as all tables that are joined to it. There are two types of joins:
- `_joinup` fields that refer to one-to-one relationships. Examples include order-to-customer (an order can have a single customer) or order line-to-product (an order line can have a single product).
- `_joindown` fields that refer to one-to-many relationships. Examples include order-to-order lines (an order can have multiple order lines) or batch-to-voucher (a batch can have multiple vouchers).
You can specify filters on these joins. The input types for the `filter` arguments have the same join fields as the output types.
In the following example, we fetch all the orders of a customer indicated by name:
```graphql
query read_orders($cid:Int!, $name : String)
{
useCompany(no:$cid)
{
order(
filter : {
joinup_Associate_via_Customer : {
name : {_eq : $name}
}
}
)
{
totalCount
items
{
orderNo
joinup_Associate_via_Customer
{
associateNo
customerNo
name
}
}
}
}
}
```
In the next example, we fetch all the orders that have at least one order line with a product whose description matches the specified one:
```graphql
query read_orders($cid:Int!, $desc : String)
{
useCompany(no:$cid)
{
order(
filter : {
joindown_OrderLine_via_Order : {
_some : {
joinup_Product : {
description : {
_eq : $desc
}
}
}
}
}
)
{
totalCount
items
{
orderNo
joindown_OrderLine_via_Order
{
items
{
lineNo
productNo
joinup_Product
{
productNo
description
}
}
}
}
}
}
}
```
In the case of `_joindown` fields, the filter selection produces a collection of items, therefore, a collection quantifier *must* be used. The currently supported one is `_some`, which means that at least one item in the collection must match the filter expression.
> [!NOTE]
>
> In the future `_all` and `_none` quantifiers might be supported.
## Comparing with current date/time
The model define various fields for date and time. All the nodes that have the type `Date_FilterClause`, `Time_FilterClause`, `DateTime_FilterClause`, or `Timestampt_FilterClause` can be compared with the current date/time. These GraphQL types, have, in addition for fields defining operators, an additional field called `_cmp` whose type is `ReferenceDateTime_FilterClause`, which looks as follows:
This type features nodes for all the comparison operators available for date and time fields. However, their type is `ReferenceDateTime` that has the following fields:
| Name | Type | Description |
| ---- | ---- | ----------- |
| `day` | `ReferenceDays` | The day this moment refers to. One of `YESTERDAY`, `TODAY`, or `TOMORROW`. |
| `dayOffset` | `Int` | The number of days to offset from the current date. For instance `TODAY` with an offset of one is `TOMORROW`, and `TODAY` with an offset of -1 is `YESTERDAY`. This value is optional. The default is 0. |
| `time` | `ReferenceTimePoints` | Can only have the value `NOW`. |
| `minuteOffset` | `Int` | The number of minutes to offset from the current time. This value is optional. The default is 0. |
The following fields of a `ReferenceDateTime` value must be provided, depending on the type of the field being compared:
| Field type | Required fields of `ReferenceDateTime` | Error message if not provided |
| ---------- | --------------------------------------- | ----------------------------- |
| `Date_FilterClause` | `day` | "Error in filter expression. The date value must contain the day field." |
| `Time_FilterClause` | `time` | "Error in filter expression. The time value must contain the time field." |
| `DateTime_FilterClause` | `day` (`time` implied as `NOW`) | "Error in filter expression. The datetime value must contain at least the day." |
| `Timestamp_FilterClause` | `day` (`time` implied as `NOW`) | "Error in filter expression. The datetime value must contain at least the day." |
The following example shows a query that fetches all orders that where changed in the last hour:
```graphql
query read_orders ($cid: Int)
{
useCompany(no: $cid)
{
order(filter :
{
_and : [
{
changedDateAsDate : {
_cmp : {
_eq : {day : TODAY, dayOffset : 0}
}
}
},
{
changedTimeAsTime : {
_cmp : {
_gte : {time : NOW, minuteOffset: -60}
}
}
}
]
})
{
totalCount
items
{
orderNo
}
}
}
}
```
This particular query can be simplified by using the `changedDateTime` field, as shown bellow:
```graphql
query read_orders ($cid: Int)
{
useCompany(no: $cid)
{
order(filter :
{
changedDateTime : {
_cmp : {
_gte : {
day : TODAY,
time : NOW,
minuteOffset : -60}
}
}
})
{
totalCount
items
{
orderNo
}
}
}
}
```
It is recommended to use the timestamp fields (`createdTimestamp` and `changedTimestamp`), available on all tables. However, these fields have the value `NULL` for records created (or modified) before they were added to the model, in which case you'd have to use the `createdDateTime` or `changedDateTime` fields instead for the query to properly work.
```graphql
query read_orders ($cid: Int)
{
useCompany(no: $cid)
{
order(filter :
{
changedTimestamp : {
_cmp : {
_gte : {
day : TODAY,
time : NOW,
minuteOffset : -60}
}
}
})
{
totalCount
items
{
orderNo
}
}
}
}
```
## Having expressions
The same operators described here for filters can be used for `having` clauses in queries that include aggregations.
To learn more about this, see [Grouping: The having argument](../schema/queries/grouping.md#the-having-argument).
Sorting
/businessnxtapi/apireference/features/sorting
page
API documentation explaining how to specify custom sorting of query results using the orderBy parameter in GraphQL queries.
2026-07-10T12:31:03+03:00
# Sorting
API documentation explaining how to specify custom sorting of query results using the orderBy parameter in GraphQL queries.
For every query, you can specify a sorting expression through the `orderBy` parameter on each connection. Every connection has the `orderBy` parameter, although its type differs for each connection. The name format is `OrderBy_`. Therefore, the sort order types have names such as `OrderBy_Associate` or `OrderBy_GeneralLedgerAccount`. This sort order type contains fields for all the columns of the table, except for the in-memory ones which cannot be searched or sorted. The type of all these fields is called `SortOrder` and is an enumeration with two values: `ASC` for asceding order and `DESC` for descending order. Therefore, this makes it possible to sort the results ascending or desceding by any column in the table.
The following image shows a partial view of the `OrderBy_Associate` type of the `orderBy` parameter of the `UseCompany_Associate_Connection` connection.
Here is an example of a query for the first 10 customers from the associates table sorted descending by their name.
```graphql { title = "Query" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
associate(first: 10,
filter:{customerNo:{_not_eq:0}},
orderBy:[{name:DESC}])
{
totalCount
items
{
associateNo
customerNo
name
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"associate": {
"totalCount": 319,
"items": [
{
"associateNo": 286,
"customerNo": 10285,
"name": "Yggdrasil Ltd."
},
{
"associateNo": 12,
"customerNo": 10011,
"name": "Wilbur Andersen"
},
{
"associateNo": 285,
"customerNo": 10284,
"name": "Werner Systems AS"
},
...
]
}
}
}
}
```
As you can see, the `orderBy` is an array of values which makes it possible to define multiple sorting columns. They are considered in the give order.
```graphql { title = "Query" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
postalAddress(
first :5,
orderBy: [
{postalArea:ASC},
{postCode:ASC}
]
)
{
totalCount
items
{
postCode
postalArea
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"postalAddress": {
"totalCount": 53,
"items": [
{
"postCode": "0001",
"postalArea": "Bergen"
},
{
"postCode": "0010",
"postalArea": "Bergen"
},
{
"postCode": "0015",
"postalArea": "Bergen"
},
{
"postCode": "0018",
"postalArea": "Oslo"
},
{
"postCode": "0021",
"postalArea": "Oslo"
}
]
}
}
}
}
```
The sort order can also be passed as a variable. Here is an example:
```graphql { title = "Query" }
query read($cid : Int!,
$size : Int!,
$order : [OrderBy_PostalAddress]!)
{
useCompany(no: $cid)
{
postalAddress(
first :$size,
orderBy: $order)
{
totalCount
items
{
postCode
postalArea
}
}
}
}
```
```graphql { title = "Variables" }
{
"cid": 9112233,
"size": 10,
"order": [
{"postalArea" : "ASC"},
{"postCode" :"ASC"}
]
}
```
## Deprecated sorting
The sorting order can be specified with the `sortOrder` argument, is similar to `orderBy`, except that it is a single object instead of an array.
> [!WARNING]
>
> The `sortOrder` argument is deprecated and will be removed in the future. Therefore, it is recommended to use the `orderBy` argument instead.
When you need to specify more than one column for sorting, the only way to do it when using `sortOrder` is by using the composition field `_thenBy`. This is exemplified in the next query, where we fetch the first 10 postal addresses, sorted first by postal area, asceding, and then by postal code, also ascending.
```graphql { title = "Query" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
postalAddress(
first :5,
sortOrder:{
postalArea:ASC
_thenBy : {
postCode:ASC}})
{
totalCount
items
{
postCode
postalArea
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"postalAddress": {
"totalCount": 53,
"items": [
{
"postCode": "0001",
"postalArea": "Bergen"
},
{
"postCode": "0010",
"postalArea": "Bergen"
},
{
"postCode": "0015",
"postalArea": "Bergen"
},
{
"postCode": "0018",
"postalArea": "Oslo"
},
{
"postCode": "0021",
"postalArea": "Oslo"
}
]
}
}
}
}
```
Any number or fields can be chained to define the sort order in this manner. However, only one table column per level can be specified without the `_thenBy` field. Otherwise, an error message is returned and the result wil be sorted in the alphabetical order of the specified columns.
```graphql { title = "Query" }
query read($cid: Int!)
{
useCompany(no :$cid)
{
postalAddress(
first : 3,
sortOrder:
{
postalArea:ASC
postCode:ASC
})
{
totalCount
items
{
postCode
postalArea
}
}
}
}
```
```graphql { title = "Result" }
{
"errors": [
{
"message": "More than one field is specified in one sort clause (postCode,postalArea). The result may be incorrect. Use the _thenBy field to chain multiple table fields in the sort order."
}
],
"data": {
"useCompany": {
"postalAddress": {
"totalCount": 5093,
"items": [
{
"postCode": "0001",
"postalArea": "OSLO"
},
{
"postCode": "0010",
"postalArea": "OSLO"
},
{
"postCode": "0015",
"postalArea": "OSLO"
}
]
}
}
}
}
```
Pagination
/businessnxtapi/apireference/features/pagination
page
Pagination uses relay style, supporting forward and backward navigation.
2026-07-10T12:31:03+03:00
# Pagination
Pagination uses relay style, supporting forward and backward navigation.
## Overview
Pagination is implemented in the relay style. Reference documentation can be found at [relay.dev](https://relay.dev/graphql/connections.htm). Both forward and backward pagination are supported:
- the arguments for forward pagination are `first` (specifing the maximum number of items to return) and `after` (which is an opaque cursor, typically pointing to the last item in the previous page)
- the arguments for backward pagination are `last` (specifying the maximum number of items to return) and `before` (which is an opaque cursor, typically pointing to the first item in the next page)
- a `skip` argument is available for both forward and backward pagination and specifies a number of records to be skipped (from the given cursor) before retrieving the requested number of records.
> [!NOTE]
>
> The values for `first`, `last`, and `skip` must be positive integers.
> [!WARNING]
>
> Pagination does not work with grouping (`groupBy` and `having` arguments).
Information about a page is returned in the `pageInfo` node. This contains the following fields:
| Field | Description |
| ----- | ----------- |
| `hasNextPage` | Indicates whether there are more records to fetch after the current page. |
| `hasPreviousPage` | Indicates whether there are more records to fetch before the current page. |
| `startCursor` | An opaque cursor pointing to the first record in the current page. |
| `endCursor` | An opaque cursor pointing to the last record in the current page. |
> [!NOTE]
>
> The cursors are considered opaque, which means that their values should not be interpreted in any way by the client. The client should only use them as arguments for the `after` and `before` parameters when performing pagination. The server uses these cursors to identify the position of records in the table, but the client should not make any assumptions about how this is done. Any such assumption may not hold in the future if the internal implementation and their representation changes.
When forward pagination is performed, the `hasNextPage` field is `true` if there are more records to fetch after the current page. When backward pagination is performed, the `hasNextPage` field is `true` if there are more records to fetch before the current page.
Similarly, when forward pagination is performed, the `hasPreviousPage` field is `true` if there are more records to fetch before the current page. When backward pagination is performed, the `hasPreviousPage` field is always `false`.
## Understanding pagination
In the following example, we fetch the first 5 associtates. This being the first page, there is no argument for the `after` parameter. Passing a `null` value for the `after` parameter is equivalent to not passing it at all.
```graphql { title = "Query" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
associate(first: 5)
{
pageInfo
{
hasNextPage
hasPreviousPage
startCursor
endCursor
}
items
{
associateNo
name
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"associate": {
"pageInfo": {
"hasNextPage": true,
"hasPreviousPage": false,
"startCursor": "MQ==",
"endCursor": "NQ=="
},
"items": [
{
"associateNo": 1,
"name": "Et Cetera Solutions"
},
{
"associateNo": 2,
"name": "Rock And Random"
},
{
"associateNo": 3,
"name": "Handy Help AS"
},
{
"associateNo": 4,
"name": "EasyWay Crafting"
},
{
"associateNo": 5,
"name": "Zen Services AS"
}
]
}
}
}
}
```
For a following page, we need to take the value of the `endCursor` return from a query and supply it as the argument to `after`. This is shown in the following example, where `"NQ=="` from the query above was supplied for the `after` parameter:
```graphql { title = "Query" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
associate(first: 5, after: "NQ==")
{
pageInfo
{
hasNextPage
hasPreviousPage
startCursor
endCursor
}
items
{
associateNo
name
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"associate": {
"pageInfo": {
"hasNextPage": true,
"hasPreviousPage": true,
"startCursor": "Ng==",
"endCursor": "MTA="
},
"items": [
{
"associateNo": 6,
"name": "Smart Vita AS"
},
{
"associateNo": 7,
"name": "Full Force Services"
},
{
"associateNo": 8,
"name": "HomeRun Auto AS"
},
{
"associateNo": 9,
"name": "Trade Kraft AS"
},
{
"associateNo": 10,
"name": "Nodic Cool Sports AS"
}
]
}
}
}
}
```
Requests with backwards pagination are performed similarly, exept that `last` and `before` are used instead of `first` and `after`. In the following example, the value of `before` is taken from the value of `startCursor` returned by the previous query that returned the second page of associates (with five records per page). As a result, the data returned from this new query is actually the first page of associates.
```graphql { title = "Query" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
associate(last: 5, before: "Ng==")
{
pageInfo
{
hasNextPage
hasPreviousPage
startCursor
endCursor
}
items
{
associateNo
name
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"associate": {
"pageInfo": {
"hasNextPage": true,
"hasPreviousPage": false,
"startCursor": "MQ==",
"endCursor": "NQ=="
},
"items": [
{
"associateNo": 1,
"name": "Et Cetera Solutions"
},
{
"associateNo": 2,
"name": "Rock And Random"
},
{
"associateNo": 3,
"name": "Handy Help AS"
},
{
"associateNo": 4,
"name": "EasyWay Crafting"
},
{
"associateNo": 5,
"name": "Zen Services AS"
}
]
}
}
}
}
```
Providing both forward and backward pagination arguments (`first`/`after` and `last`/`before`) is illegal and the query will fail with an error.
If pagination arguments are not supplied a default page size of 5000 records is used.
When you fetch data in pages (which is recommended for most scenarious) you can fetch the total number of objects in the table with disregard to the page that is fetched or the size of the page. This is possible with the `totalCount`. This will return the number of records that match the filter (if any) but ignoring paginagion (if any).
This feature is exemplified below. We, again, fetch the first 5 associates that have a customer number greater or equal than 11000 but also request the total number of records that match this filter.
```graphql { title = "Query" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
associate(
first: 5,
filter: {customerNo :{_gte: 11000}})
{
totalCount
pageInfo
{
hasNextPage
hasPreviousPage
startCursor
endCursor
}
items
{
associateNo
customerNo
name
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"associate": {
"totalCount": 29,
"pageInfo": {
"hasNextPage": true,
"hasPreviousPage": false,
"startCursor": "MQ==",
"endCursor": "NQ=="
},
"items": [
{
"associateNo": 308,
"customerNo": 11000,
"name": "Auto Glory AS"
},
{
"associateNo": 309,
"customerNo": 11001,
"name": "Home Team Business"
},
{
"associateNo": 310,
"customerNo": 11003,
"name": "Corpus Systems"
},
{
"associateNo": 311,
"customerNo": 11004,
"name": "Dash Credit AS"
},
{
"associateNo": 312,
"customerNo": 11007,
"name": "Smart Help Services AS"
}
]
}
}
}
}
```
You can skip a number of records before feetching a page (with the size indicated by either the `first` or the `last` arguments) using the argument `skip`. This is an optional argument. When present, it indicates the number of records to be skipped. Here is an example:
```graphql { title = "Forward" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
generalLedgerAccount(skip : 5,
first: 10)
{
totalCount
items
{
accountNo
}
}
}
}
```
```graphql { title = "Backward" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
generalLedgerAccount(skip : 5,
last : 10,
before: "MTE=")
{
totalCount
items
{
accountNo
}
}
}
}
```
> [!WARNING]
>
> Because the execution of queries for joined tables is optimized for performance, pagination does not work as described in this document. To understand the problem and the workaround see [Unoptimized queries](./unoptimized.md).
## Pagination in depth
To understand how pagination works, we will consider the following example, where the general ledger account table contains 25 records. It could look like this:
```
page 1 (10 records) page 2 (10 records) page 3 (5 records)
|---------------------------------|---------------------------------|---------------------------------|
| 1000 | 1020 | ... | 1100 | 1120 | 1130 | 1140 | ... | 1240 | 1250 | 1260 | 1270 | 1280 | 1300 | 1310 |
```
### Forward pagination
To fetch the records from the beginning, we perform a query like this:
```graphql { title = "Query" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
generalLedgerAccount(first : 10,
after: null)
{
pageInfo
{
hasNextPage
hasPreviousPage
startCursor
endCursor
}
items
{
accountNo
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"generalLedgerAccount": {
"pageInfo": {
"hasNextPage": true,
"hasPreviousPage": false,
"startCursor": "MQ==",
"endCursor": "MTA="
},
"items": [
{
"accountNo": 1000
},
{
"accountNo": 1020
},
...
{
"accountNo": 1100
},
{
"accountNo": 1120
}
]
}
}
}
}
```
This returns the first ten records, from index 1 to 10, and the `startCursor` and `endCursor` are pointing to the first and last elements in the set.
```
page 1 (10 records)
|---------------------------------|
| 1000 | 1020 | ... | 1100 | 1120 | 1130 | 1140 | ... | 1240 | 1250 | 1260 | 1270 | 1280 | 1300 | 1310 |
^ ^
| |
startCursor endCursor
```
To fetch the next page of 10 records, we provide the value of `endCursor` as the argument for `after`:
```graphql { title = "Query" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
generalLedgerAccount(first : 10,
after: "MTA=")
{
pageInfo
{
hasNextPage
hasPreviousPage
startCursor
endCursor
}
items
{
accountNo
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"generalLedgerAccount": {
"pageInfo": {
"hasNextPage": true,
"hasPreviousPage": true,
"startCursor": "MTE=",
"endCursor": "MjA="
},
"items": [
{
"accountNo": 1130
},
{
"accountNo": 1140
},
...
{
"accountNo": 1240
},
{
"accountNo": 1250
}
]
}
}
}
}
```
This returns the second page of ten records, from index 11 to 20, and the `startCursor` and `endCursor` are pointing to the first and last elements in the set.
```
after page 2 (10 records)
| |---------------------------------|
v
| 1000 | 1020 | ... | 1100 | 1120 | 1130 | 1140 | ... | 1240 | 1250 | 1260 | 1270 | 1280 | 1300 | 1310 |
^ ^
| |
startCursor endCursor
```
To fetch the next page of 10 records, we repeat the operation, again, using the `endCursor` for the value of the `after` argument:
```graphql { title = "Query" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
generalLedgerAccount(first : 10,
after: "MjA=")
{
pageInfo
{
hasNextPage
hasPreviousPage
startCursor
endCursor
}
items
{
accountNo
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"generalLedgerAccount": {
"pageInfo": {
"hasNextPage": false,
"hasPreviousPage": true,
"startCursor": "MjE=",
"endCursor": "MjU="
},
"items": [
{
"accountNo": 1260
},
{
"accountNo": 1270
},
{
"accountNo": 1280
},
{
"accountNo": 1300
},
{
"accountNo": 1310
},
]
}
}
}
}
```
This returns a page of only 5 records, from index 21 to 25, and the `startCursor` and `endCursor` are pointing to the first and last elements in the set.
```
after page 3 (5 records)
| |----------------------------------|
v
| 1000 | 1020 | ... | 1100 | 1120 | 1130 | 1140 | ... | 1240 | 1250 | 1260 | 1270 | 1280 | 1300 | 1310 |
^ ^
| |
startCursor endCursor
```
The value of the `hasNextPage` field is `false` because there are no more records to fetch.
> [!NOTE]
>
> The value used for the `after` argument should be the value of the `endCursor` from the previous page (unless it's `null`, in which case it means the fetching should start from the beginning). The `after` cursor identifies the position of the last record in a (previous) page. The record at the position represented by the cursor passed to the `after` argument is not included in the result set. A page starts with the record following the one identified by `after`.
It is also possible to skip records before fetching a page. This is done by providing the `skip` argument. The following example skips the first 3 records before fetching a page of 10 records. We don't start from the beginning, but at the end of the first page of 10 records, as exemplify below:
```
after skip 3 records page of 10 records
| >-------------------<|-----------------------------------------------|
v
| 1000 | 1020 | ... | 1100 | 1120 | 1130 | 1140 | 1150 | 1160 | ... | 1240 | 1250 | 1260 | 1270 | 1280 | 1300 | 1310 |
^ ^
| |
startCursor endCursor
```
```graphql { title = "Query" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
generalLedgerAccount(first : 10,
skip : 3,
after: "MTA=")
{
pageInfo
{
hasNextPage
hasPreviousPage
startCursor
endCursor
}
items
{
accountNo
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"generalLedgerAccount": {
"pageInfo": {
"hasNextPage": true,
"hasPreviousPage": true,
"startCursor": "MTQ=",
"endCursor": "MjM="
},
"items": [
{
"accountNo": 1160
},
{
"accountNo": 1200
},
...
{
"accountNo": 1270
},
{
"accountNo": 1280
}
]
}
}
}
}
```
### Backward pagination
Backward pagination works similarly, except that the `last` and `before` arguments are used instead of `first` and `after`. The argument `last` indicates how many records the page should contain. The argument `before` represents the position of the record before which the page is located. The record at the `before` position is not included in the result set.
Therefore, if in the preceding example we fetched all the records in the table, and now want to move backwards, but use the value of the `endCursor` as the arguement for `before`, then this last record will not be included in the returned page.
```
page of 10 records before
|---------------------------------------------------------------------| |
v
| 1000 | 1020 | ... | 1160 | 1200 | 1210 | 1220 | 1230 | 1240 | 1250 | 1260 | 1270 | 1280 | 1300 | 1310 |
^ ^
| |
startCursor endCursor
```
```graphql { title = "Query" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
generalLedgerAccount(last : 10,
before: "MjU=")
{
pageInfo
{
hasNextPage
hasPreviousPage
startCursor
endCursor
}
items
{
accountNo
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"generalLedgerAccount": {
"pageInfo": {
"hasNextPage": true,
"hasPreviousPage": false,
"startCursor": "MTU=",
"endCursor": "MjQ="
},
"items": [
{
"accountNo": 1200
},
{
"accountNo": 1210
},
...
{
"accountNo": 1280
},
{
"accountNo": 1300
}
]
}
}
}
}
```
Fragments
/businessnxtapi/apireference/features/fragments
page
Documentation on using and nesting fragments in GraphQL queries to efficiently construct reusable sets of fields.
2026-07-10T12:31:03+03:00
# Fragments
Documentation on using and nesting fragments in GraphQL queries to efficiently construct reusable sets of fields.
You can build fragments to construct sets of fields and then include them in queries where you need to. Nested fragments are supported.
Here is an example of a query constructed using a fragment called `associateBasic`, which in turn uses two other fragments, `associateContact` and `associateAddress`.
```graphql { title = "Query" }
query read($cid : Int!)
{
useCompany(no: $cid)
{
associate
{
items
{
...associateBasic
customerNo
supplierNo
}
}
}
}
fragment associateBasic on Associate
{
name
userName
... associateContact
... associateAddress
}
fragment associateContact on Associate
{
emailAddress
phone
}
fragment associateAddress on Associate
{
addressLine1
postCode
postalArea
countryNo
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"associate": {
"items": [
{
"name": "ABB Installasjon AS",
"userName": "",
"emailAddress": "",
"phone": "12345678",
"addressLine1": "Ole Deviks Vei 10",
"postCode": "1375",
"postalArea": "Billingstad",
"countryNo": 0,
"customerNo": 10000,
"supplierNo": 0
},
{
"name": "ABB Kraft AS",
"userName": "",
"emailAddress": "",
"phone": "12345678",
"addressLine1": "Jacob Borchs Gate 6",
"postCode": "3002",
"postalArea": "Drammen",
"countryNo": 0,
"customerNo": 10001,
"supplierNo": 0
}
]
}
}
}
}
```
Named queries and parameters
/businessnxtapi/apireference/features/parameters
page
GraphQL supports named queries and variables, enhancing query clarity. Example includes defining and utilizing variables for efficient data retrieval.
2026-07-10T12:31:03+03:00
# Named queries and parameters
GraphQL supports named queries and variables, enhancing query clarity. Example includes defining and utilizing variables for efficient data retrieval.
GraphQL supports variables and naming queries, which should always be used since they make the query more clear while reading.
Let's look at an example. In the following snippet, `GetCustomers` is a named query that returns a page associates. This query has three parameters: `$companyNo` specifies the Visma.net company number that uniquely identifies the company within the system, `$pageSize` the maximum number of records to be returned, and `$after` the cursor that indicates the position after which the records are to be fetched. If nothing is specified, this means the first `$pageSize` records are to be fetched.
```graphql
query GetCustomers($companyNo: Int, $pageSize: Int, $after :String)
{
useCompany(no: $companyNo)
{
associate(first: $pageSize, after: $after)
{
totalCount
pageInfo
{
hasNextPage
hasPreviousPage
startCursor
endCursor
}
items
{
associateNo
customerNo
name
}
}
}
}
```
If you use GraphiQL, you can define the variables in the query variable pane in the lower left of the IDE, as shown in the following image:
When you perform the request to GraphQL programmatically, or from a tool that does not directly support GraphQL variables, you must put the request containing both the query and variables in the body, as `application/json`.
```json
{
"query" : "query GetCustomers($cid: Int, $pageSize: Int, $after :String)\n{\n useCompany(no: $cid)\n {\n associate(first: $pageSize, after: $after)\n {\n totalCount\n items\n {\n associateNo\n customerNo\n name\n }\n }\n }\n}",
"variables":"{\"cid\": 1234567, \"pageSize\": 10, \"after\": \"MVx0MTAwMjA=\"}"
}
```
Details about the raw form of a GraphQL query were presented in an earlier section of this tutorial.
Aliases
/businessnxtapi/apireference/features/aliases
page
GraphQL API documentation on using aliases to rename fields and query the same field multiple times with different arguments.
2026-07-10T12:31:03+03:00
# Aliases
GraphQL API documentation on using aliases to rename fields and query the same field multiple times with different arguments.
GraphQL allows you to rename the result of a field to anything you want. This is possible with the help of [aliases](https://graphql.org/learn/queries/#aliases).
You can use this feature to:
- rename long fields and use name that you prefer over fields from the schema
- query for the same field multiple times but with different arguments
Here is an example:
```graphql
query GetPaymentLines($cid: Int!)
{
useCompany(no: $cid)
{
paymentLine(first: 1)
{
items {
paymentNo
lineNo
currency : joinup_Currency {
isoCode
}
supplier : joinup_Associate_via_Supplier {
bankAccount
country : joinup_Country {
isoCode
}
}
}
}
}
}
```
Aliases can be used in:
- queries (example shown above)
- inserts and updates
- aggregates
Here is another example in an aggregate function:
```graphql
query GetAgregates($cid: Int!)
{
useCompany(no: $cid)
{
order_aggregate
{
totalvat : sum
{
vatAmountDomestic
}
}
}
}
```
As previously mentioned, an important use case is to query for the same field multiple times but using different arguments. An example is shown below:
```graphql { title = "Query" }
query ($cid : Int!)
{
useCompany(no : $cid)
{
some : generalLedgerAccount(first : 2)
{
items
{
accountNo
name
}
}
more : generalLedgerAccount(first : 2,
filter : {accountNo : {_gt : 6000}})
{
items
{
accountNo
name
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"some": {
"items": [
{
"accountNo": 1000,
"name": "Forskning og utvikling"
},
{
"accountNo": 1020,
"name": "Konsesjoner"
}
]
},
"more": {
"items": [
{
"accountNo": 6010,
"name": "Avskr. maskiner, inventar mv."
},
{
"accountNo": 6020,
"name": "Avskr. immaterielle eiendeler"
}
]
}
}
},
"extensions": {
"vbnxt-trace-id": "02c029a3a07c7a..."
}
}
```
Directives
/businessnxtapi/apireference/features/directives
page
GraphQL directives modify query execution, including core directives like @include and @skip, and custom ones like @export.
2026-07-10T12:31:03+03:00
# Directives
GraphQL directives modify query execution, including core directives like @include and @skip, and custom ones like @export.
Directives are a GraphQL feature that affect the execution of a query in any way the server desires. Directives can be attached to different parts of the schema (field, fragment inclusion, etc.). There are several core GraphQL directives:
| Directive | Attached to | Description |
| --------- | ----------- | ----------- |
| `@include` | field, fragment inclusion | Only include this field in the result if the argument is true. |
| `@skip` | field, fragment inclusion | Skip this field if the argument is true. |
In addition, we provide custom directives:
| Directive | Attached to | Description |
| --------- | ----------- | ----------- |
| `@export` | field, fragment inclusion | Export the value of a field into a variable that can be used somewhere else in the query. |
| `@dependsOn` | field, fragment inclusion | Specify that a field depends on another field. |
## The @include directive
Includes a field or fragment in the result only if the Boolean argument is `true`.
**Syntax**:
```graphql
@include(if: Boolean!)
```
**Example**:
```graphql
query($cid : Int!, $pagesize : Int, $withdetails : Boolean!)
{
useCompany(no : $cid)
{
order(first : $pagesize)
{
totalCount
items
{
orderNo
orderDate
lines : joindown_OrderLine_via_Order(first: 2) @include(if: $withdetails)
{
totalCount
items
{
lineNo
transactionDate
}
}
}
}
}
}
```
**Result**:
```graphql { title = "$withdetails is false" }
{
"data": {
"useCompany": {
"order": {
"totalCount": 451,
"items": [
{
"orderNo": 1,
"orderDate": 20210212
},
{
"orderNo": 2,
"orderDate": 20130203
}
]
}
}
}
}
```
```graphql { title = "$withdetails is true" }
{
"data": {
"useCompany": {
"order": {
"totalCount": 451,
"items": [
{
"orderNo": 1,
"orderDate": 20210212,
"lines": {
"totalCount": 6,
"items": [
{
"lineNo": 1,
"transactionDate": 0
},
{
"lineNo": 2,
"transactionDate": 0
}
]
}
},
{
"orderNo": 2,
"orderDate": 20130203,
"lines": {
"totalCount": 5,
"items": [
{
"lineNo": 1,
"transactionDate": 20140904
},
{
"lineNo": 2,
"transactionDate": 20140904
}
]
}
}
]
}
}
}
}
```
## The @skip directive
Skips a field if the Boolean argument is `true`.
**Syntax**:
```graphql
@skip(if: Boolean!)
```
**Example**:
```graphql
query($cid : Int!, $pagesize : Int, $nodetails : Boolean!)
{
useCompany(no : $cid)
{
order(first : $pagesize)
{
totalCount
items
{
orderNo
orderDate
lines : joindown_OrderLine_via_Order(first: 2) @skip(if: $nodetails)
{
totalCount
items
{
lineNo
transactionDate
}
}
}
}
}
}
```
**Result**:
```graphql { title = "$nodetails is true" }
{
"data": {
"useCompany": {
"order": {
"totalCount": 451,
"items": [
{
"orderNo": 1,
"orderDate": 20210212
},
{
"orderNo": 2,
"orderDate": 20130203
}
]
}
}
}
}
```
```graphql { title = "$nodetails is false" }
{
"data": {
"useCompany": {
"order": {
"totalCount": 451,
"items": [
{
"orderNo": 1,
"orderDate": 20210212,
"lines": {
"totalCount": 6,
"items": [
{
"lineNo": 1,
"transactionDate": 0
},
{
"lineNo": 2,
"transactionDate": 0
}
]
}
},
{
"orderNo": 2,
"orderDate": 20130203,
"lines": {
"totalCount": 5,
"items": [
{
"lineNo": 1,
"transactionDate": 20140904
},
{
"lineNo": 2,
"transactionDate": 20140904
}
]
}
}
]
}
}
}
}
```
## The @export directive
The `@export` directive in GraphQL exports the value of a field into a variable that is used somewhere else in the query. This can be either a single value or an array.
**Syntax**:
```graphql
@export(as: "variablename", distinct : true)
```
**Example**: Fetch the cutomer number of the associate whose indentifier is specified and then use the customer number to fetch orders.
```graphql { title = "Query" }
query($cid : Int!,
$ano : Int!,
$pagesize: Int,
$customerId : Int = 0)
{
useCompany(no: $cid)
{
associate(filter : {associateNo : {_eq: $ano}})
{
items
{
customerNo @export(as: "customerId")
}
}
order(first : $pagesize,
filter : {customerNo : {_eq : $customerId}})
{
totalCount
items
{
orderNo
orderDate
customerNo
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"associate": {
"items": [
{
"customerNo": 10000
}
]
},
"order": {
"totalCount": 14,
"items": [
{
"orderNo": 81,
"orderDate": 20150115,
"customerNo": 10000
}
]
}
}
}
}
```
**Example**: Add one order and two order lines for the order with a single request.
```graphql { title = "Query" }
mutation ($cid: Int,
$cno : Int,
$pid1 : String,
$pid2 : String,
$orderId: Int = 0)
{
useCompany(no: $cid)
{
order_create(
values: [
{
orderDate: 20221104,
customerNo: $cno,
orderType: 1,
transactionType: 1
}
]
)
{
affectedRows
items
{
orderNo @export(as: "orderId")
}
}
orderLine_create(
values: [
{
orderNo: $orderId,
productNo: $pid1,
quantity: 1
},
{
orderNo: $orderId,
productNo: $pid2,
quantity: 2
}
]
)
{
affectedRows
items
{
lineNo
orderNo
productNo
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"order_create": {
"affectedRows": 1,
"items": [
{
"orderNo": 632
}
]
},
"orderLine_create": {
"affectedRows": 2,
"items": [
{
"lineNo": 1,
"orderNo": 632,
"productNo": "1001"
},
{
"lineNo": 2,
"orderNo": 632,
"productNo": "1002"
}
]
}
}
}
}
```
There are several things to keep in mind when using this directive:
- The variable into which the field value is exported must be defined in the query parameter list. Otherwise, when you use the variable later on in another part of the query, the server will complain that it is not defined.
- You can only export the value of one field into one variable. If you attempt to write values from multiple fields into the same variable they will be overwritten based of the order of evaluation.
- If you export multiple values into the same variable, the last field that is evaluated will define the value of the variable.
- If the variable is defined as an array, you can store multiple values.
In the previous examples, we have used a variable that could store a single value. Therefore, if a query returned multiple elements, a field would get evaluated multiple times and each time the variable would be overritten. The value from the last evaluation is the one that is finally stored in the variable.
However, all the values can be preserved in an array. The only change is that you need to define the variable of an array type. Moreover, you can use the Boolean optional argument `distinct` to retain only the distict values and discard duplicates. An array variable can be used for instance with the `_in` and `_not_in` filters.
The following example shows a query that fetches information about all the orders that have lines that were updated after a given moment in time:
```graphql
query read_modified_orders($cid : Int!, $dt : DateTime,
$ono : [Int] = [])
{
useCompany(no : $cid)
{
orderLine(filter : {changedDateTime : {_gt : $dt}})
{
items
{
orderNo @export(as : "ono", distict : true)
}
}
order(filter : {orderNo : {_in : $ono})
{
items
{
orderNo
orderDate
customerNo
}
}
}
}
```
### Ordering and @export
In most cases the consuming field references the exported variable in its arguments, either directly or nested inside an input object or list. When that happens, the server picks up the reference and evaluates the consuming field after the exporting one. The examples above work this way: the `order(filter: {customerNo: {_eq: $customerId}})` argument references the `customerId` exported just above it, and `orderLine_create` does the same with `orderId`.
For ordering requirements that are not visible from the arguments, use `@dependsOn`, described next.
## The @dependsOn directive
The `@dependsOn` directive specifies that a field depends on another field and must be executed after it. To optimize execution the server packs independent fields together before sending them to the back-end, which can shuffle the visible order of fields in the query. Argument-driven dependencies (including those introduced by `@export`) are sequenced automatically, so `@dependsOn` is reserved for cases where one field has a side effect that a later field relies on, but neither passes a variable to the other.
The example below shows this case: `uploadToFileService` does not reference the `$batchId` exported by `batch_create`, but it must still run after `addNewDocument` has registered the document, so the ordering is declared explicitly.
**Syntax**:
```graphql
@dependsOn(field: "name")
```
**Example**:
```graphql
mutation CreateBatchWithAttachment ($cid: Int,
$batchId: Int = 0,
$fina: String,
$fiby: String,
$tok: String)
{
useCompany(no: $cid) {
# create the batch
batch_create(
values: {
voucherSeriesNo: 1,
valueDate: 20250121
description: "Demo batch"
}
)
{
affectedRows
items {
batchNo @export(as: "batchId")
}
}
# create the voucher
voucher_create(
values: {
batchNo: $batchId
voucherDate: null
voucherType: 21
voucherNo: null
debitAccountNo: 5000
creditAccountNo: 1920
amountDomestic: 500.00
text: "first voucherline"
}
)
{
affectedRows
items {
batchNo
voucherNo
}
# add a document to the batch
voucher_processings {
addNewDocument(
filter: {batchNo: {_eq: $batchId}},
args: {
fileName: $fina,
fileBytes: $fiby
}
)
{
succeeded
}
}
# upload the document to the file service
incomingAccountingDocumentAttachment_processings {
uploadToFileService(
filter: {fileName: {_eq: $fina}},
args: {connectToken: $tok}
) @dependsOn(field: "addNewDocument")
{
succeeded
}
}
}
}
```
## References
You can learn more about the core GraphQL directives from these articles:
- [Directives](https://graphql-dotnet.github.io/docs/getting-started/directives/)
- [GraphQL Directives](https://spec.graphql.org/October2021/#sec-Type-System.Directives)
Unoptomized queries
/businessnxtapi/apireference/features/unoptimized
page
Learn about the limitations and handling of optimized queries for joined tables, including performance trade-offs and the usage of the unoptimized Boolean argument for accurate pagination and counting.
2026-07-10T12:31:03+03:00
# Unoptomized queries
Learn about the limitations and handling of optimized queries for joined tables, including performance trade-offs and the usage of the unoptimized Boolean argument for accurate pagination and counting.
Because of the way fetching data from the backend is optimized, several features do not work for joined tables (the fields that start with the `joindown_` or `joinup_` prefix):
- pagination (requesting data in pages and diplaying paging information - the `pageInfo` field)
- counting the total number of rows that match the filter (the `totalCount` field)
In order to have these features working properly, you must explicitly request that the execution of the query is not optimized by the system. This is done with a Boolean field argument called `unoptimized`. The way this works is described below. First, let's understand the problem.
## Query optimization
When you request data from joined tables we are faced with a problem called the N+1 problem. Let's say you want to fetch the last 10 orders of a customer, but along with the order heads also the order lines info. Typically, this means we will do one request to fetch the order heads first, and then, for each order, we perform one request to fetch the lines. For 10 orders that is 10 more request for the lines, amounting to a total of 11 requests. For N orders, that amounts to N+1 requests. This incurs a performace loss and this is aggravated if more tables are joined together. For instance, fetching the orders, and for each order the order lines, and for each order line the order notes, just to give an example.
To avoid the performance penalty, our system is optimizing the queries. As a result, we are performing only 2 requests instead of N+1. For the orders and orders line example, we perform a first request to fetch the heads and then a second request to fetch the lines.
The result is a potential 10x or more speed-up for executing a query. The downside is the features mentioned above no longer work.
## The problem with the optimization
The understand the problem with optimization let us discuss the following scenario.
Consider a query that fetches the first 10 orders and for each order the first 3 order lines. That means that for each order, the query should return a maximum of 3 order lines, therefore, potentially, a total of 30 order lines in total. However, some orders may have less than 3 order lines others may have more. The current implementation takes the first 30 order lines (that match the given filter, if any) regardless to which order they belong. Let's explain this with an example:
| Order no | No. of order lines | No. of expected returned lines | No. of actual returned lines |
| -------- | ------------------ | ------------------------------ | ---------------------------- |
| 1 | 2 lines | 2 lines | 2 lines |
| 2 | 5 lines | 3 lines | 5 lines |
| 3 | 2 line | 2 lines | 2 lines |
| 4 | 1 lines | 1 lines | 1 lines |
| 5 | 7 lines | 3 lines | 7 lines |
| 6 | 3 lines | 3 lines | 3 lines |
| 7 | 5 lines | 3 lines | 5 lines |
| 8 | 8 lines | 3 lines | 5 lines |
| 9 | 5 lines | 3 lines | 0 lines |
| 10 | 2 lines | 2 lines | 0 lines |
The third column in this table shows the expected result when you ask for the first 3 order lines for each order. What is returned instead is the data of the fourth column. This is shown with the following query:
```graphql { title = "Query" }
query ($cid :Int!, $pagesize : Int)
{
useCompany(no: $cid)
{
order(first: $pagesize)
{
totalCount
items
{
orderNo
joindown_OrderLine_via_Order(first: 3)
{
items
{
lineNo
}
}
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"order": {
"totalCount": 348,
"items": [
{
"orderNo": 1,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1
},
{
"lineNo": 2
}
]
}
},
{
"orderNo": 2,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1
},
{
"lineNo": 2
},
{
"lineNo": 3
},
{
"lineNo": 4
},
{
"lineNo": 5
}
]
}
},
{
"orderNo": 3,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1
},
{
"lineNo": 2
}
]
}
},
{
"orderNo": 4,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1
}
]
}
},
{
"orderNo": 5,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1
},
{
"lineNo": 2
},
{
"lineNo": 3
},
{
"lineNo": 4
},
{
"lineNo": 5
},
{
"lineNo": 6
},
{
"lineNo": 7
}
]
}
},
{
"orderNo": 6,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1
},
{
"lineNo": 2
},
{
"lineNo": 3
}
]
}
},
{
"orderNo": 7,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1
},
{
"lineNo": 2
},
{
"lineNo": 3
},
{
"lineNo": 4
},
{
"lineNo": 5
}
]
}
},
{
"orderNo": 8,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1
},
{
"lineNo": 2
},
{
"lineNo": 3
},
{
"lineNo": 4
},
{
"lineNo": 5
}
]
}
},
{
"orderNo": 9,
"joindown_OrderLine_via_Order": {
"items": null
}
},
{
"orderNo": 10,
"joindown_OrderLine_via_Order": {
"items": null
}
}
]
}
}
}
}
```
The reason for this is that we fetch a total of 10\*3 order lines from the order lines table, in a single request. This means the result is not what was actually requested from with the query.
Notice this is not a problem when no pagination is requested. The following example, that fetches some orders and all their order lines works without any problem.
```graphql { title = "Query" }
query ($cid :Int!, $pagesize : Int)
{
useCompany(no: $cid)
{
order(first: $pagesize)
{
totalCount
items
{
orderNo
joindown_OrderLine_via_Order
{
items
{
lineNo
}
}
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"order": {
"totalCount": 348,
"items": [
{
"orderNo": 1,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1
},
{
"lineNo": 2
}
]
}
},
{
"orderNo": 2,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1
},
{
"lineNo": 2
},
{
"lineNo": 3
},
{
"lineNo": 4
},
{
"lineNo": 5
}
]
}
},
{
"orderNo": 3,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1
},
{
"lineNo": 2
}
]
}
},
{
"orderNo": 4,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1
}
]
}
},
{
"orderNo": 5,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1
},
{
"lineNo": 2
},
{
"lineNo": 3
},
{
"lineNo": 4
},
{
"lineNo": 5
},
{
"lineNo": 6
},
{
"lineNo": 7
}
]
}
},
{
"orderNo": 6,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1
},
{
"lineNo": 2
},
{
"lineNo": 3
}
]
}
},
{
"orderNo": 7,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1
},
{
"lineNo": 2
},
{
"lineNo": 3
},
{
"lineNo": 4
},
{
"lineNo": 5
}
]
}
},
{
"orderNo": 8,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1
},
{
"lineNo": 2
},
{
"lineNo": 3
},
{
"lineNo": 4
},
{
"lineNo": 5
},
{
"lineNo": 6
},
{
"lineNo": 7
},
{
"lineNo": 8
}
]
}
},
{
"orderNo": 9,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1
},
{
"lineNo": 2
},
{
"lineNo": 3
},
{
"lineNo": 4
},
{
"lineNo": 5
}
]
}
},
{
"orderNo": 10,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1
},
{
"lineNo": 2
}
]
}
}
]
}
}
}
}
```
However, fetching the total count of order lines per each order and displaying paging information for each chunk of order lines does not work in this case either.
## Unoptimized queries
To solve the problem of the optimized queries for joined tables, you can explicitly request to run the query without optimizations. This means there will be N+1 requests to the backend and the execution time will increase significantly. However, counting records from the joined table and fetching data in pages works as expected.
The unoptimized execution is requested with a Boolean argument for the field called `unoptimized` that must be set to `true`. This is shown in the following example:
```graphql { title = "Query" }
query ($cid :Int!, $pagesize : Int)
{
useCompany(no: $cid)
{
order(first: $pagesize)
{
totalCount
items
{
orderNo
joindown_OrderLine_via_Order(first: 3,
unoptimized: true)
{
items
{
lineNo
}
}
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"order": {
"totalCount": 348,
"items": [
{
"orderNo": 1,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1
},
{
"lineNo": 2
}
]
}
},
{
"orderNo": 2,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1
},
{
"lineNo": 2
},
{
"lineNo": 3
}
]
}
},
{
"orderNo": 3,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1
},
{
"lineNo": 2
}
]
}
},
{
"orderNo": 4,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1
}
]
}
},
{
"orderNo": 5,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1
},
{
"lineNo": 2
},
{
"lineNo": 3
}
]
}
},
{
"orderNo": 6,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1
},
{
"lineNo": 2
},
{
"lineNo": 3
}
]
}
},
{
"orderNo": 7,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1
},
{
"lineNo": 2
},
{
"lineNo": 3
}
]
}
},
{
"orderNo": 8,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1
},
{
"lineNo": 2
},
{
"lineNo": 3
}
]
}
},
{
"orderNo": 9,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1
},
{
"lineNo": 2
},
{
"lineNo": 3
}
]
}
},
{
"orderNo": 10,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1
},
{
"lineNo": 2
}
]
}
}
]
}
}
}
}
```
The `unoptimized` flag is an argument to a connection (see [Queries](../schema/queries/query.md)). However, a connection may contain other inner connections. These are the joindown tables discussed here and seen in the previous examples.
When you are requesting the fetching of data in an unoptimized manner, this applies not only to the connection on which the argument was specified, but also on all its descendants.
This behavior can be overridden by using the `unoptimized` argument again on a descendant connection. Here are several examples:
- the order lines are fetched in an optimized manner but not the order line notes
```graphql
query ($cid :Int!, $pagesize : Int)
{
useCompany(no: $cid)
{
order(first: $pagesize)
{
totalCount
items
{
orderNo
joindown_OrderLine_via_Order(first: 3)
{
items
{
lineNo
joindown_OrderLineNote_via_OrderLine(unoptimized : true)
{
items
{
note
}
}
}
}
}
}
}
}
```
- both the order lines and the order line notes are fetched unoptimized
```graphql
query ($cid :Int!, $pagesize : Int)
{
useCompany(no: $cid)
{
order(first: $pagesize)
{
totalCount
items
{
orderNo
joindown_OrderLine_via_Order(first: 3, unoptimized : true)
{
items
{
lineNo
joindown_OrderLineNote_via_OrderLine
{
items
{
note
}
}
}
}
}
}
}
}
```
- the order lines are fetched unoptimized but the fetching of order line notes is optimized
```graphql
query ($cid :Int!, $pagesize : Int)
{
useCompany(no: $cid)
{
order(first: $pagesize)
{
totalCount
items
{
orderNo
joindown_OrderLine_via_Order(first: 3, unoptimized : true)
{
items
{
lineNo
joindown_OrderLineNote_via_OrderLine(unoptimized : false)
{
items
{
note
}
}
}
}
}
}
}
}
```
Using the `unoptimized` flag on a top-level table (such as the orders table in these examples) has no effect on fetching data from that table. However, it will affect the manner of fetching data from all its joined tables (the fields prefixed with either `joindown_` or `joinup_`).
## Asynchronous execution
Executing the queries with joined down tables fast and having pagination or counting the total items in the joined down table are mutually exclusive. However, if you do need these features but do not want to wait for the execution of the query you can execute the query asynchronously.
To learn more about this, see [Async queries](../schema/async.md).
Batch requests
/businessnxtapi/apireference/features/batches
page
Batch multiple GraphQL queries or mutations in a single API request, with results returned after complete execution.
2026-07-10T12:31:03+03:00
# Batch requests
Batch multiple GraphQL queries or mutations in a single API request, with results returned after complete execution.
A GraphQL request is basically a JSON object that has the following form:
```json
{
"query" : "..."
"variables" : {}
"operationname" : "..."
}
```
The `OperationName` property is optional, but if present, it must match the operation name from the query. To exemplify, let's consider the following request:
```graphql { title = "Query" }
query read_accounts($cid : Int,
$pagesize : Int){
useCompany(no: $cid) {
generalLedgerAccount(first: $pagesize) {
totalCount
pageInfo {
hasNextPage
hasPreviousPage
startCursor
endCursor
}
items {
accountNo
name
}
}
}
}
```
```graphql { title = "Result" }
{
"cid" : 987654321,
"pagesize" : 10
}
```
This query is formatted as the following JSON content when dispatched to the GraphQL API:
```json
{
"query" : "query read_accounts($cid : Int,\n $pagesize : Int){\n useCompany(no: $cid) {\n generalLedgerAccount(first: $pagesize) {\n totalCount\n pageInfo {\n hasNextPage\n hasPreviousPage\n startCursor\n endCursor\n }\n items {\n accountNo\n name\n }\n }\n }\n}",
"variables": {"cid": 987654321, "pagesize" : 10},
}
```
> [!NOTE]
>
> Notice that JSON does not support multiple line strings. Therefore, new lines must be escaped, and the entire query provided as a single line string.
The result you get back is also a JSON object, such as the following:
```json
{
"data": {
"useCompany": {
"generalLedgerAccount": {
"totalCount": 412,
"pageInfo": {
"hasNextPage": true,
"hasPreviousPage": false,
"startCursor": "MA==",
"endCursor": "MTA="
},
"items": [
{
"accountNo": 1200,
"name": "Plant and machinery"
},
{
"accountNo": 1209,
"name": "Depreciation plant and machinery"
}
]
}
}
},
"extensions": {
"vbnxt-trace-id": "a2f3f1ad045d7bd2f62f833e136ff0b0"
}
}
```
It is possible that a single request contains multiple parts. For instance, you can query orders, products, and customers in a single request. You can also create an order and its order lines in a single mutation.
However, it's not possible to mix queries and mutations inside the same request.
Business NXT GraphQL allows you to batch multiple queries inside a single API requests. That is possible by sending an array of JSON objects, as follows:
```json
[
{
"query" : "..."
"variables" : {}
"operationname" : "..."
},
{
"query" : "..."
"variables" : {}
"operationname" : "..."
}
]
```
The result, is also an array of objects, one for each requested operation.
```
[
,
,
...
;
]
```
An example with two requests (a query and a mutation) batched together is shown below:
```json
[
{
"query" : "query read($cid : Int, $pagesize : Int){\n useCompany(no: $cid) {\n generalLedgerAccount(first: $pagesize) {\n totalCount\n pageInfo {\n hasNextPage\n hasPreviousPage\n startCursor\n endCursor\n }\n items {\n accountNo\n name\n }\n }\n }\n}",
"variables": {"cid": 987654321, "pagesize" : 10},
"operationname" : "read"
},
{
"query" : "mutation update_gla($cid : Int!, $no : Int!, $name : String!)\n{\n useCompany(no: $cid) \n {\n generalLedgerAccount_update(\n filter : {accountNo : {_eq: $no}},\n value : {shortName : $name})\n {\n affectedRows\n items {\n accountNo\n name\n shortName\n }\n }\n }\n}",
"variables": {"cid": 987654321, "no" : 9999, "name": "test"},
"operationname" : "update_gla"
}
]
```
```json
[
{
"data": {
"useCompany": {
"generalLedgerAccount": {
"totalCount": 117,
"pageInfo": {
"hasNextPage": true,
"hasPreviousPage": false,
"startCursor": "MA==",
"endCursor": "MTA="
},
"items": [
{
"accountNo": 1200,
"name": "Plant and machinery"
},
{
"accountNo": 1209,
"name": "Depreciation plant and machinery"
},
{
"accountNo": 1210,
"name": "Buildings"
},
{
"accountNo": 1211,
"name": "Land"
},
{
"accountNo": 1219,
"name": "Depreciation, Buildings"
},
{
"accountNo": 1220,
"name": "Office Equipment"
},
{
"accountNo": 1229,
"name": "Depreciation, Office Equipment"
},
{
"accountNo": 1240,
"name": "Motor vehicles"
},
{
"accountNo": 1249,
"name": "Depreciation motor vehicles"
},
{
"accountNo": 1300,
"name": "Goodwill"
}
]
}
}
}
},
{
"data": {
"useCompany": {
"generalLedgerAccount_update": {
"affectedRows": 1,
"items": [
{
"accountNo": 9999,
"name": "SUSPENSE ACCOUNT",
"shortName": "test"
}
]
}
}
}
}
]
```
It is possible to batch both queries and mutations together in any order. They are executed individually, one by one, in the order they where provided.
When batching multiple request, the results will only be returned after all the requests have been executed. A large number of requests could make the overall operation exceed the HTTP timeout interval.
In this case, the operation will timeout and the result will be lost.
> [!NOTE]
>
> There is currently a limit of the number of requests that can be batched together. This limit is set to 32 requests.
>
> This limit may be subject to future changes.
> [!TIP]
>
> Use batching requests judiciously, making sure their overall execution time will not trigger an operation timeout!
Extensions
/businessnxtapi/apireference/extensions
section
GraphQL schema for data model extensions.
2026-07-10T12:31:03+03:00
# Extensions
GraphQL schema for data model extensions.
The GraphQL schema is dynamically built from the core data model. It exposes tables, columns, relations, processings, reports the way they are defined in the core model.
Business NXT supports extending the model with new tables, columns, relations, and others. These data model extensions (DMEs for short) are accessible through GraphQL just like the core model.
However, these extensions are not available the same way the core model is. GraphQL features a single schema, and that cannot expose all customer-specific extensions in a strongly-type named. For this reason, generic extensions are available everywhere DMEs are possible.
> [!TIP]
> Although these generic extensions to the schema are designed for DMEs, it is possible to also query the core model using them. However, we advice that you only use them for DMEs.
## Getting started with extensions
Extensions are referenced using their name identifiers, and not model numbers:
- columns and tables by their name
- relations by their name and where necessary to avoid ambiguity, also by their source and target table name
A few examples are provided here to get you started.
```graphql
query read_order($cid:Int!)
{
useCompany(no:$cid)
{
order(first:5)
{
items
{
orderNo
orderDate
extensions
{
customerNo : integerValue
createdAt : dateValue(name: "createdDate")
}
}
}
}
}
```
The `extensions` field is available on all tables, and it exposes all extension columns defined for that table. You can query the extension columns by their name using the appropriate typed field. There are two ways to query a field:
- using an alias, which is interpreted as the name of the extension column, such as in `customerNo : integerValue`
- using the `name` argument to specify the name of the extension column, such as in `createdAt : dateValue(name: "createdDate")`
When both an alias and the `name` argument are used, the `name` argument takes precedence and the alias is not considered for identifying the company.
The possible field names for extension columns are:
- `integerValue`
- `decimalValue`
- `stringValue`
- `booleanValue`
- `dateValue`
- `timeValue`
- `timestampValue`
Each column has a domain with a specific data type. Data types can be integer, decimal, boolean, string, date, timestamp. If the requested data type (such as `integer` for `integerValue`) does not match the domain data type of the extension column, the value `null` is returned.
The following example utilizes a relation extension to query related data from an extension table:
```graphql
query read_order($cid:Int!)
{
useCompany(no:$cid)
{
order(first:5)
{
items
{
orderNo
orderDate
extensions
{
customerNo : integerValue
createdAt : dateValue(name: "createdDate")
}
joinup_Associate_via_Customer
{
name
extensions
{
joinup(relation: "Country")
{
name : stringValue
}
}
}
}
}
}
}
```
The last example here shows how to query a table, use filters and sorting, and also do joins using the generic extensions schema:
```graphql
query read_table($cid:Int!)
{
useCompany(no:$cid)
{
table(
name : "order",
first: 5,
filter : {
joindown : {
relation : {
name : "Order",
from : "OrderLine"
}
_some : {
joinup :{
relation : {
name : "Product"
},
column : "Description",
stringValue : {
_eq : "Product 103"
}
}
}
}
}
orderBy : [
{column : "customerNo", order : DESC},
{column : "orderDate", order : ASC},
{column : "orderNo"}
])
{
items
{
orderNo : integerValue
customerNo : integerValue
address : stringValue (name : "addressLine1")
orderDate : dateValue
createdDate : dateValue
createdTime : timeValue
createdTimestamp : timestampValue
totalDiscountPercent : decimalValue
editStatus : integerValue
joindown(relation : "Order", from : "OrderLine")
{
items
{
orderNo : integerValue
lineNo : integerValue
joinup(relation : "Product")
{
description : stringValue
}
}
}
joinup(relation : "Customer")
{
name : stringValue
joinup(relation : "Country")
{
name : stringValue
joinup(relation : "Language")
{
name : stringValue
}
}
}
}
}
}
}
```
This query uses the core model entirely and is the equivalent of the following:
```graphql
query read_order($cid:Int!)
{
useCompany(no:$cid)
{
order(
first: 5,
filter : {
joindown_OrderLine_via_Order : {
_some : {
joinup_Product : {
description : {
_eq : "Product 103"
}
}
}
}
}
orderBy : [
{customerNo : DESC},
{orderDate : ASC},
{orderNo : ASC}
])
{
items
{
orderNo
customerNo
joindown_OrderLine_via_Order
{
items
{
orderNo
lineNo
joinup_Product
{
description
}
}
}
joinup_Associate_via_Customer
{
name
joinup_Country
{
name
joinup_Language
{
name
}
}
}
}
}
}
}
```
Read extensions
/businessnxtapi/apireference/extensions/readextensions
page
GraphQL API documentation on schema read generic extensions.
2026-07-10T12:31:03+03:00
# Read extensions
GraphQL API documentation on schema read generic extensions.
Business NXT GraphQL schema extensions for data model extensions reads are documented in this section.
There is no difference between querying the core model or a model extension. However, it is recommended that you use the extensions schema for DMEs only.
## Querying an extension column
To query an extension column, there are two options:
- use an alias to indicate the actual column name (`customerNo : integerValue`), or
- use the `name` argument to indicate the column name (`cno : integerValue(name : "customerNo")`)
The case of the name value is irrelevant. But if both an alias and the `name` argument are present, the `name` argument is used to identify the column.
Each table type has a special field along the table column fields used for querying the extension columns. This field is called `extensions`. This field includes the following subfields:
- `integerValue`
- `decimalValue`
- `stringValue`
- `booleanValue`
- `dateValue`
- `timeValue`
- `timestampValue`
Each column has a domain with a specific data type. Data types can be integer, decimal, boolean, string, date, timestamp. If the requested data type (such as `integer` for `integerValue`) does not match the domain data type of the extension column, the value `null` is returned.
In the following example, `extensions` is used to fetch the value of the `customerNo` and `createdDate` fields from the `Order` table.
```graphql { title = "Query" }
query read_order($cid:Int!)
{
useCompany(no:$cid)
{
order(first : 1)
{
items
{
orderNo
orderDate
extensions
{
customerNo : integerValue
createdAt : dateValue(name: "createdDate")
}
}
}
}
}
```
```json { title = "Result" }
{
"data": {
"useCompany": {
"order": {
"items": [
{
"orderNo": 1,
"orderDate": 20210212,
"extensions": {
"customerNo": 10002,
"createdAt": "2020-05-11"
}
}
]
}
}
}
}
```
## Joinup extensions
Data model extensions can include relations. These can be one-to-one (called `joinup`) or one-to-many (called `joindown`).
Custom joinup relations can be querying by specifying:
- the relation name (identifier)
- optionally the source and target table name, if the relation name is ambiguous
The following example shows up-joining from the Order table to Associate, to Country, and finally to Language. All the joins are done using the extension `joinup` field.
```graphql { title = "Query" }
query read_order($cid:Int!)
{
useCompany(no:$cid)
{
order(first : 1)
{
items
{
orderNo
extensions
{
joinup(relation : "Customer")
{
name : stringValue
joinup(relation: "Country")
{
name : stringValue
joinup(relation: "Language")
{
name : stringValue
}
}
}
}
}
}
}
}
```
```json { title = "Result" }
{
"data": {
"useCompany": {
"order": {
"items": [
{
"orderNo": 1,
"extensions": {
"joinup": {
"name": "Access Vital AS",
"joinup": {
"name": "Norway",
"joinup": {
"name": "Norsk"
}
}
}
}
}
]
}
}
}
}
```
## Joindown extensions
The `joindown` relations are similar to `joinup`, except that their GraphQL type is a connection type.
The following example shows fetching the order lines for an order using the `extensions` field.
```graphql { title = "Query" }
query read_order($cid:Int!)
{
useCompany(no:$cid)
{
order(first : 1)
{
items
{
orderNo
orderDate
extensions
{
joindown(relation: "Order", from: "OrderLine")
{
items
{
orderNo : integerValue
lineNo : integerValue
productNo : stringValue
joinup(relation: "Product")
{
name : stringValue(name: "description")
}
}
}
}
}
}
}
}
```
```json { title = "Result" }
{
"data": {
"useCompany": {
"order": {
"items": [
{
"orderNo": 1,
"orderDate": 20210212,
"extensions": {
"joindown": {
"items": [
{
"orderNo": 1,
"lineNo": 1,
"productNo": "312",
"joinup": {
"name": "Callaway Big Bertha 4-PW grafitt Herre"
}
},
{
"orderNo": 1,
"lineNo": 2,
"productNo": "313",
"joinup": {
"name": "Callaway Big Bertha Fusion jern"
}
}
]
}
}
}
]
}
}
}
}
```
## Filter extensions
Extension columns can be used in filters too. However, arguments are defined by input types and these cannot have arguments themselves. Therefore, for all input types, the schema is sligtly different. For columns, you need to specify the column name and the value expression.
The following examples shows how to fetch orders that belong to the customer with number 10010:
```graphql { title = "Query" }
query read_order($cid:Int!)
{
useCompany(no:$cid)
{
order(
first : 3,
filter : {
extensions : {
column : "customerNo",
integerValue : {
_eq : 10010
}
}
}
)
{
items
{
orderNo
customerNo
}
}
}
}
```
```json { title = "Result" }
{
"data": {
"useCompany": {
"order": {
"items": [
{
"orderNo": 86,
"customerNo": 10010
},
{
"orderNo": 97,
"customerNo": 10010
},
{
"orderNo": 136,
"customerNo": 10010
}
]
}
}
}
}
```
## Filter joinup extensions
It is possible to filter on the value of columns from joined tables. For one-to-one relations, this is done using the `joinup` input field.
In the previous example, we queried orders for a customer indicated by its number. However, we can do the same using the name of the customer, from the Associate table. This is possible with a filter join. For extensions, this requires the `extensions` and the `joinup` fields:
```graphql { title = "Query" }
query read_order($cid:Int!)
{
useCompany(no:$cid)
{
order(
first : 3,
filter : {
extensions : {
joinup : {
relation : {
name : "Customer",
to : "Associate"
},
column : "Name",
stringValue : {
_eq : "American Designers"
}
}
}
}
)
{
items
{
orderNo
customerNo
}
}
}
}
```
```json { title = "Result" }
{
"data": {
"useCompany": {
"order": {
"items": [
{
"orderNo": 86,
"customerNo": 10010
},
{
"orderNo": 97,
"customerNo": 10010
},
{
"orderNo": 136,
"customerNo": 10010
}
]
}
}
}
}
```
In this example, notice the following:
- The input field `relation` is used to indicate the relation to join through. It contains fields for the relation name as well as optionally for the `from` and `to` table names. When the `from` argument is missing, it's implied as the name of the table from which the join is defined.
- The `column` field is used to indicate the name of the column in the target table (`Associate` in this case) to filter on.
- The actual filter expression is provided in the field corresponding to the data type of the column (`stringValue` in this case).
## Filter joindown extensions
It's possible to use joins to filter on one-to-multiple relations too. This is possible using the equivalent `joindown` input field.
For instance, in the following example we query orders that have at least one order line for product number `"103"`:
```graphql { title = "Query" }
query read_order($cid:Int!)
{
useCompany(no:$cid)
{
order(
first : 1,
filter : {
extensions : {
joindown : {
relation : {
name : "Order",
from : "OrderLine"
},
_some : {
column : "productNo",
stringValue : {
_eq : "103"
}
}
}
}
}
)
{
items
{
orderNo
joindown_OrderLine_via_Order
{
items
{
lineNo
productNo
}
}
}
}
}
}
```
```json { title = "Result" }
{
"data": {
"useCompany": {
"order": {
"items": [
{
"orderNo": 4,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1,
"productNo": "311"
},
{
"lineNo": 2,
"productNo": "311"
},
{
"lineNo": 3,
"productNo": "1001"
},
{
"lineNo": 4,
"productNo": "103"
}
]
}
}
]
}
}
}
}
```
We can expand the example, to perform the same query but using the name of the product, as defined in the `Product` table, instead of its number:
```graphql { title = "Query" }
query read_order($cid:Int!)
{
useCompany(no:$cid)
{
order(
first : 1,
filter : {
extensions : {
joindown : {
relation : {
name : "Order",
from : "OrderLine"
},
_some : {
joinup : {
relation : {
name : "Product"
},
column : "Description",
stringValue : { _eq : "Product 103" }
}
}
}
}
}
)
{
items
{
orderNo
joindown_OrderLine_via_Order
{
items
{
lineNo
productNo
joinup_Product
{
description
}
}
}
}
}
}
}
```
```json { title = "Result" }
{
"data": {
"useCompany": {
"order": {
"items": [
{
"orderNo": 4,
"joindown_OrderLine_via_Order": {
"items": [
{
"lineNo": 1,
"productNo": "311",
"joinup_Product": {
"description": "Callaway Big Bertha Fusion FT 3 Driver"
}
},
{
"lineNo": 2,
"productNo": "311",
"joinup_Product": {
"description": "Callaway Big Bertha Fusion FT 3 Driver"
}
},
{
"lineNo": 3,
"productNo": "1001",
"joinup_Product": {
"description": "Olyo MS 0703 Carbon Crown Rescue Wood"
}
},
{
"lineNo": 4,
"productNo": "103",
"joinup_Product": {
"description": "Product 103"
}
}
]
}
}
]
}
}
}
}
```
## Ordering extensions
Extension columns can be used to define the sorting order too. In this case, you need to specify the column name and, optionally, the order direction. If the order direction is not specified, ascending order is used by default.
The following example shows how to orders by their `customerNo` extension column in descending order:
```graphql { title = "Query" }
query read_order($cid:Int!)
{
useCompany(no:$cid)
{
order(
first : 3,
orderBy : [
{
extensions : {
column : "customerNo",
order : DESC
}
}
]
)
{
items
{
orderNo
customerNo
}
}
}
}
```
```json { title = "Result" }
{
"data": {
"useCompany": {
"order": {
"items": [
{
"orderNo": 47,
"customerNo": 49999
},
{
"orderNo": 356,
"customerNo": 30018
},
{
"orderNo": 358,
"customerNo": 30012
}
]
}
}
}
}
```
## Grouping extensions
To group by column extensions, use the `extensions` field. You need to specify the column name and, optionally, the grouping order, which can be either `DEFAULT` or `ROLLUP`. If the grouping order is not specified, `DEFAULT` is used.
The following example shows fetching data from the general ledger transactions table, on account 3000 and year 2020, grouping the results by the `AccountNo` column with `ROLLUP` grouping, and the period, also with the `ROLLUP` grouping:
```graphql { title = "Query" }
query read_gla_transactions_grouped($cid : Int)
{
useCompany(no : $cid)
{
generalLedgerTransaction(
filter : {
_and: [
{accountNo : {_gte : 3000}},
{year : {_gte : 2020}}
]},
groupBy: [
{
extensions : {
column : "AccountNo",
grouping : ROLLUP
}
},
{period : ROLLUP}
])
{
items
{
accountNo
period
aggregates
{
sum
{
postedAmountDomestic
}
}
}
}
}
}
```
```json { title = "Result" }
{
"data": {
"useCompany": {
"generalLedgerTransaction": {
"items": [
{
"accountNo": 3000,
"period": 4,
"aggregates": {
"sum": {
"postedAmountDomestic": -100
}
}
},
{
"accountNo": 3000,
"period": 12,
"aggregates": {
"sum": {
"postedAmountDomestic": -4950
}
}
},
{
"accountNo": 3000,
"period": 0,
"aggregates": {
"sum": {
"postedAmountDomestic": -5050
}
}
},
{
"accountNo": 4000,
"period": 12,
"aggregates": {
"sum": {
"postedAmountDomestic": 450
}
}
},
{
"accountNo": 4000,
"period": 0,
"aggregates": {
"sum": {
"postedAmountDomestic": 450
}
}
},
{
"accountNo": 4410,
"period": 4,
"aggregates": {
"sum": {
"postedAmountDomestic": 400
}
}
},
{
"accountNo": 4410,
"period": 12,
"aggregates": {
"sum": {
"postedAmountDomestic": 13035
}
}
},
{
"accountNo": 4410,
"period": 0,
"aggregates": {
"sum": {
"postedAmountDomestic": 13435
}
}
},
{
"accountNo": 0,
"period": 0,
"aggregates": {
"sum": {
"postedAmountDomestic": 8835
}
}
}
]
}
}
}
}
```
## Having clause extensions
The `having` clause expressions are very similar to the filter expressions. You need to specify the column name and its value expression.
In the following example, we run the same query as above, except that a having clause is used to filter and retain only the groups where the sum of the `postedAmountDomestic` is greater than 100:
```graphql { title = "Query" }
query read_gla_transactions_grouped($cid : Int)
{
useCompany(no : $cid)
{
generalLedgerTransaction(
filter : {
_and: [
{accountNo : {_gte : 3000}},
{year : {_gte : 2020}}
]},
groupBy: [
{
extensions : {
column : "AccountNo",
grouping : ROLLUP
}
},
{period : ROLLUP}
],
having : {
_sum : {
extensions : {
column : "postedAmountDomestic"
decimalValue : {
_gt : 100
}
}
}
})
{
items
{
accountNo
period
aggregates
{
sum
{
postedAmountDomestic
}
}
}
}
}
}
```
```json { title = "Result" }
{
"data": {
"useCompany": {
"generalLedgerTransaction": {
"items": [
{
"accountNo": 4000,
"period": 12,
"aggregates": {
"sum": {
"postedAmountDomestic": 450
}
}
},
{
"accountNo": 4000,
"period": 0,
"aggregates": {
"sum": {
"postedAmountDomestic": 450
}
}
},
{
"accountNo": 4410,
"period": 4,
"aggregates": {
"sum": {
"postedAmountDomestic": 400
}
}
},
{
"accountNo": 4410,
"period": 12,
"aggregates": {
"sum": {
"postedAmountDomestic": 13035
}
}
},
{
"accountNo": 4410,
"period": 0,
"aggregates": {
"sum": {
"postedAmountDomestic": 13435
}
}
},
{
"accountNo": 0,
"period": 0,
"aggregates": {
"sum": {
"postedAmountDomestic": 8835
}
}
}
]
}
}
}
}
```
## Aggregate extensions
Previously, we have see how to use extension columns in grouping and having clauses. These are connection arguments. But the extensions columns can be used in the projected aggregated results too. The syntax is similar to that of regular columns.
In the following example, the sum of the `postedAmountDomestic` is fetched using the schema extensions:
```graphql { title = "Query" }
query read_gla_transactions_grouped($cid : Int)
{
useCompany(no : $cid)
{
generalLedgerTransaction(
filter : {
_and: [
{accountNo : {_gte : 3000}},
{year : {_gte : 2020}}
]},
groupBy: [
{
extensions : {
column : "AccountNo",
grouping : ROLLUP
}
},
{period : ROLLUP}
],
having : {
_sum : {
extensions : {
column : "postedAmountDomestic"
decimalValue : {
_gt : 100
}
}
}
})
{
items
{
accountNo
period
aggregates
{
sum
{
extensions
{
postedAmountDomestic : decimalValue
}
}
}
}
}
}
}
```
```json { title = "Result" }
{
"data": {
"useCompany": {
"generalLedgerTransaction": {
"items": [
{
"accountNo": 4000,
"period": 12,
"aggregates": {
"sum": {
"extensions": {
"postedAmountDomestic": 450
}
}
}
},
{
"accountNo": 4000,
"period": 0,
"aggregates": {
"sum": {
"extensions": {
"postedAmountDomestic": 450
}
}
}
},
{
"accountNo": 4410,
"period": 4,
"aggregates": {
"sum": {
"extensions": {
"postedAmountDomestic": 400
}
}
}
},
{
"accountNo": 4410,
"period": 12,
"aggregates": {
"sum": {
"extensions": {
"postedAmountDomestic": 13035
}
}
}
},
{
"accountNo": 4410,
"period": 0,
"aggregates": {
"sum": {
"extensions": {
"postedAmountDomestic": 13435
}
}
}
},
{
"accountNo": 0,
"period": 0,
"aggregates": {
"sum": {
"extensions": {
"postedAmountDomestic": 8835
}
}
}
}
]
}
}
}
}
```
## Table extensions
The data model extensions allows adding new tables, as well as relations between these tables and existing (core model) tables.
To query an extension table, you need to use the generic `table` connection. This is defined by a connection type like all the other connection fields in the schema, with the same arguments. However, instead of defining name columns, it uses all the extension features shown above. The key difference is that the `table` connection being an extension itself, it does not define inner fields called `extensions`, like we have seen above.
Jut like for columns, to specify the table you can either use the `name` argument or an alias for the connection field. If both are present, the `name` argument is used to identify the table.
The following example shows how to query a table using the `table` connection.
```graphql { title = "Query" }
query read_table($cid:Int!)
{
useCompany(no:$cid)
{
table(
name : "order",
first: 3,
filter : {
joindown : {
relation : {
name : "Order",
from : "OrderLine"
}
_some : {
joinup :{
relation : {
name : "Product"
},
column : "Description",
stringValue : {
_eq : "Product 103"
}
}
}
}
}
orderBy : [
{column : "customerNo", order : DESC},
{column : "orderDate", order : ASC},
{column : "orderNo"}
])
{
items
{
orderNo : integerValue
customerNo : integerValue
address : stringValue (name : "addressLine1")
orderDate : dateValue
createdDate : dateValue
createdTime : timeValue
createdTimestamp : timestampValue
totalDiscountPercent : decimalValue
editStatus : integerValue
joindown(relation : "Order", from : "OrderLine")
{
items
{
orderNo : integerValue
lineNo : integerValue
joinup(relation : "Product")
{
description : stringValue
}
}
}
joinup(relation : "Customer")
{
name : stringValue
joinup(relation : "Country")
{
name : stringValue
joinup(relation : "Language")
{
name : stringValue
}
}
}
}
}
}
}
```
This example can also be written using an alias for the `table` connection instead of the `name` argument, as follows:
```graphql { title = "Query" }
query read_table($cid:Int!)
{
useCompany(no:$cid)
{
order : table(first: 3)
{
items
{
orderNo : integerValue
customerNo : integerValue
}
}
}
}
```
Write extensions
/businessnxtapi/apireference/extensions/writeextensions
page
GraphQL API documentation on schema write generic extensions.
2026-07-10T12:31:03+03:00
# Write extensions
GraphQL API documentation on schema write generic extensions.
Business NXT GraphQL schema extensions for data model extensions writes are documented in this section.
There is no difference between performing mutation operations on the core model or a model extension. However, it is recommended that you use the extensions schema for DMEs only.
## Writing extension columns
When entering input values for extension columns, you must specify the column name and its value. For this, a special type called `InputValueExtension` is used. This type has the following fields:
| Field | Type | Description |
| ----- | ---- | ----------- |
| column | String! | Name of the column |
| integerValue | Int | An integer value |
| stringValue | String | A string value |
| decimalValue | Decimal | A decimal value |
| booleanValue | Boolean | A boolean value |
| dateValue | Date | A date value |
| timeValue | String | A time value |
| timestampValue | DateTime | A timestamp value |
The `column` field is mandatory and specifies the name of the extension column. The other fields are optional and represent the value to be set for the column. Only one of these value fields should be provided per input. If more than one is provided, an error will be returned.
Here is an example of how to create an order and line both using extensions:
```graphql { title = "Query" }
mutation create_order($cid :Int!)
{
useCompany(no : $cid)
{
order_create(values : [
{
extensions : [
{
column : "customerNo",
integerValue : 10010
}
]
orderLines : [
{
productNo : "103",
extensions : [
{
column : "quantity",
integerValue : 2
}
]
}
]
}
])
{
affectedRows
items
{
orderNo
customerNo
joindown_OrderLine_via_Order
{
items
{
orderNo
lineNo
productNo
quantity
}
}
}
}
}
}
```
```json { title = "Result" }
{
"data": {
"useCompany": {
"order_create": {
"affectedRows": 1,
"items": [
{
"orderNo": 2913,
"customerNo": 10010,
"joindown_OrderLine_via_Order": {
"items": [
{
"orderNo": 2913,
"lineNo": 1,
"productNo": "103",
"quantity": 2
}
]
}
}
]
}
}
}
}
```
## Updating extension columns
The syntax for updating extension columns is similar to that of writing them. You need to specify the column name and the new value using the `InputValueExtension` type. Filters are written in the same way as for reads.
Here is an example of how to update an order using extensions syntax:
```graphql { title = "Query" }
mutation update_order($cid :Int!, $ono : Int!)
{
useCompany(no : $cid)
{
order_update(
filters : [
{
extensions : {
column : "orderNo",
integerValue : {_eq : $ono}
}
}
]
values : [
{
extensions : [
{
column : "Name",
stringValue : "Lars Olafson"
}
]
}
]
)
{
affectedRows
items
{
orderNo
name
}
}
}
}
```
```json { title = "Result" }
{
"data": {
"useCompany": {
"order_update": {
"affectedRows": 1,
"items": [
{
"orderNo": 2913,
"name": "Lars Olafson"
}
]
}
}
}
}
```
## Deleting with filter extensions
To delete data from an existing table using fileters on extension columns, you can define filters in the same way as for updating values.
The following example shows how to delete records from the order line and order tables using filter extensions for the `orderNo` column:
```graphql { title = "Query" }
mutation delete_order($cid : Int!, $ono : Int!)
{
useCompany(no : $cid)
{
orderLine_delete(filter : {
extensions : {
column : "orderNo",
integerValue : {_eq : $ono}
}
})
{
affectedRows
}
order_delete(filter : {
extensions : {
column : "orderNo",
integerValue : {_eq : $ono}
}
})
{
affectedRows
}
}
}
```
```json { title = "Result" }
{
"data": {
"useCompany": {
"orderLine_delete": {
"affectedRows": 1
},
"order_delete": {
"affectedRows": 1
}
}
}
}
```
## Writing extension tables
In order to write table to an exentension table, you need to use the `table_create` field. This is similar to existing table create fields, such as `order_create` or `batch_create`. However, in this case, the fields called `extensions` are missing from the schema.
A mutation to create a new order may look like this:
```graphql { title = "Query" }
mutation create_orders($cid :Int!)
{
useCompany(no : $cid)
{
table_create(
name : "order",
values : [
[
{
column : "customerNo",
integerValue : 10010
},
{
column : "orderType",
integerValue : 6
}
],
[
{
column : "customerNo",
integerValue : 10002
},
{
column : "orderType",
stringValue : 1
}
]
])
{
affectedRows
items
{
orderNo : integerValue
customerNo : integerValue
orderType : integerValue
}
}
}
}
```
```json { title = "Result" }
{
"data": {
"useCompany": {
"table_create": {
"affectedRows": 2,
"items": [
{
"orderNo": 2913,
"customerNo": 10010,
"orderType": 6,
},
{
"orderNo": 2914,
"customerNo": 10002,
"orderType": 1,
}
]
}
}
}
}
```
## Updating extension tables
In order to update records in an extension table, you need to use the `table_update` field. This is similar to existing table update fields, such as `order_update` or `batch_update`. However, in this case, the fields called `extensions` are missing from the schema.
In the following examples, two orders are updated with a single request. One filter and one update value is specified for each order.
```graphql { title = "Query" }
mutation update_order($cid :Int!, $ono1 : Int!, $ono2 : Int!, $cn : String!, $val1 : String!, $val2 : String!)
{
useCompany(no : $cid)
{
table_update(
name : "order",
filters : [
{
column : "orderNo",
integerValue : {_eq : $ono1}
},
{
column : "orderNo",
integerValue : {_eq : $ono2}
}
]
values : [
{
column : "Name",
stringValue : "Lars Olafson"
},
{
column : "Name",
stringValue : "Olaf Larson"
}
]
)
{
affectedRows
items
{
orderNo : integerValue
name : stringValue
}
}
}
}
```
```json { title = "Result" }
{
"data": {
"useCompany": {
"table_update": {
"affectedRows": 2,
"items": [
{
"orderNo": 2913,
"name": "Lars Olafson"
},
{
"orderNo": 2914,
"name": "Olaf Larson"
}
]
}
}
}
}
```
## Deleting extension tables
The operation of deleting records from extension tables is done using the `table_delete` field. This is similar to existing table delete fields, such as `order_delete` or `batch_delete`. Again, as in the previous cases, the fields called `extensions` are missing from the schema.
Here is an example of deleting two orders from the `Order` table:
```graphql { title = "Query" }
mutation delete_order($cid : Int!, $ono1 : Int!, $ono2 : Int!)
{
useCompany(no : $cid)
{
table_delete(
name : "order",
filter : {
column : "orderNo",
integerValue : {_in : [$ono1, $ono2]}
}
)
{
affectedRows
}
}
}
```
```json { title = "Result" }
{
"data": {
"useCompany": {
"table_delete": {
"affectedRows": 2
}
}
}
}
```
DME
/businessnxtapi/apireference/extensions/dmes
page
GraphQL API documentation on data model extensions.
2026-07-10T12:31:03+03:00
# DME
GraphQL API documentation on data model extensions.
Data model extension contributions are created using the [Business NXT DME Admin](https://dme.business.visma.net/) tool. This tools allows you to:
- Create new contributions defining new tables, columns, relations, indexes and more.
- Import an existing contribution.
- Apply a contribution to a customer (which means it is applied to all the companies of that customer).
All data model extensions can be accessed through the GraphQL API using the GraphQL extensions schema. There are several things to keep in mind when working with DMEs in GraphQL:
- Tables, columns, and relations are referenced by their indentifier (and not by model numbers).
- Identifiers specified as strings (such as in `column : "myExtColumn"`, or `name : "myExtTable"`) are case-insensitive.
- The actual identifier of a table, column, or relation is composed from the contribution short name and the entities identifier. For instance, if a new table has the identifier `myExtTable` and the contribution short name is `MyDme`, then the actual table identifier is `MyDme_myExtTable`.
The following snippet shows an example:
```graphql { title = "Query" }
query read_dme_table($cid : Int)
{
useCompany(no: $cid)
{
table(name : "mydme_myExtTable")
{
items
{
MyDme_pk : integerValue
MyDme_description : stringValue
MyDme_createdTimestamp : timestampValue
}
}
}
}
```
If you do not want to have fields prefixed with the contribution short name in the result JSON, you can use aliases without the prefix but specify the full column identifier in the optional name argument, as shown in the following snippet:
```graphql { title = "Query" }
query read_dme_table($cid : Int)
{
useCompany(no: $cid)
{
table(name : "mydme_myexttable")
{
items
{
pk : integerValue(name : "MyDme_pk")
description : stringValue(name : "MyDme_description")
createdTimestamp : timestampValue(name : "MyDme_createdTimestamp")
}
}
}
}
```
Note that the casing of the identifiers in the previous examples varies to demonstrate that the identifiers are case-insensitive.
For input types (such as in `filters` or `values` arguments) the column names and values are specified with separate fields, as previously described. Here is an example:
```graphql { title = "Query" }
mutation create_reviews($cid :Int!, $pno : String!, $r1 : Int!, $r2 : Int!)
{
useCompany(no : $cid)
{
table_update(
name : "MyDme_ProductReview",
filters : [
{
_and : [
{
column : "MyDme_ProductNo",
stringValue : {_eq : $pno}
},
{
column : "MyDme_ReviewNo",
integerValue : {_eq : $r1}
}
]
}
],
values : [
[
{
column : "MyDme_Description",
stringValue : "A good product!"
}
]
])
{
affectedRows
items
{
MyDme_ProductNo : stringValue
MyDme_ReviewNo : integerValue
MyDme_Description : stringValue
}
}
}
}
```
When you specify a relation for a `joinup` or a `joindown` it is recommended that you also explicitly specify the `from` and `to` tables on which the relation is defined. This would eliminate any potential ambiguity for relation lookup in the data model.
Error handling
/businessnxtapi/apireference/errors
page
GraphQL API error handling - status codes, error messages, syntax errors, multiple request outcomes, execution tracing for troubleshooting, and detailed error property explanations.
2026-07-10T12:31:03+03:00
# Error handling
GraphQL API error handling - status codes, error messages, syntax errors, multiple request outcomes, execution tracing for troubleshooting, and detailed error property explanations.
A GraphQL query is an HTTP POST request with the content type `application/json` and the body having the form:
```json
{
"query" : "...",
"variables" : "..."
}
```
If the authorization for a request fails (no authorization header, expired token, etc.) the return status code is `401` (`Unauthorized)` and the response body is the following:
```html
401 Authorization Required
401 Authorization Required
nginx
```
However, for most requests, whether they are successful or they failed, the return status code is `200`. When a successful query is executed, the JSON object that is returned contains a property called `data` whose value is an object representing the returned data. Here is an example:
```json
{
"data": {
"useCompany": {
"generalLedgerAccount": {
"items": [
{
"accountNo": 9001,
"name": "Special account",
}
]
}
}
}
}
```
When an error occurs during the execution of the request, the return JSON object contains both the `data` property, as well as a property called `errors`, which is an array of objects containing information about the error(s) that occurred. The following is an example:
```json
{
"errors": [
{
"message": "Error: Could not get authorize user using VismaNetCompanyId: 1234567. Description: External integration error. Status: 18."
}
],
"data": {
"useCompany": {
"generalLedgerAccount": null
}
}
}
```
If the GraphQL query has a syntax error, the returned information contains not just a message but also detains about the location of the error within the query. This is exemplified below:
```graphql { title = "Query" }
query read($cid : Int!)
{
useCompany(no : $cid) {
generalLedgerAccount {
totalRows
}
}
}
```
```graphql { title = "Result" }
{
"errors": [
{
"message": "GraphQL.Validation.Errors.FieldsOnCorrectTypeError: Cannot query field 'totalRows' on type 'Query_UseCompany_GeneralLedgerAccount_Connection'. Did you mean 'totalCount'?",
"locations": [
{
"line": 4,
"column": 7
}
],
"extensions": {
"code": "FIELDS_ON_CORRECT_TYPE",
"codes": [
"FIELDS_ON_CORRECT_TYPE"
],
"number": "5.3.1"
}
}
]
}
```
A GraphQL query may contain multiple requests (such as reading from different tables). It is possible that some may be successful, while other will fail. The result will contain data that was fetched successfully but also information about the errors that occurred for the other requests. Here is an example:
```graphql { title = "Query" }
query read($cid : Int!)
{
useCompany(no : $cid) {
generalLedgerAccount(first: 2) {
totalCount
items {
accountNo
name
}
}
generalLedgerBalance(last: 10) {
totalCount
items {
accountNo
sumDebitObDomestic
sumCreditObDomestic
}
}
}
}
```
```graphql { title = "Result" }
{
"errors": [
{
"message": "The cursor 'before' must have a value.",
"path": [
"useCompany",
"generalLedgerBalance"
]
}
],
"data": {
"useCompany": {
"generalLedgerAccount": {
"totalCount": 340,
"items": [
{
"accountNo": 1000,
"name": "Forskning og utvikling"
},
{
"accountNo": 1020,
"name": "Konsesjoner"
}
]
},
"generalLedgerBalance": null
}
}
}
```
On the other hand, an operation may be successful (such as inserting a new row) although sub-operations (such as assigning a value to a column) may fail. GraphQL returns the result as well as all the errors messages from executing the request.
```graphql { title = "Query" }
mutation create_batch($cid : Int!)
{
useCompany(no: $cid)
{
batch_create(values:
[
{
valueDate: 20211122
voucherSeriesNo: 3
orgUnit1 : 0
orgUnit2 : 0
orgUnit3 : 0
orgUnit4 : 0
orgUnit5 : 0
period :11
year :2021
}
])
{
affectedRows
items
{
batchNo
valueDate
voucherSeriesNo
}
}
}
}
```
```graphql { title = "Result" }
{
"errors": [
{
"message": "Error: Illegal value date 11/22/2021. Check suspension date and the accounting periods and VAT periods tables..",
"path": [
"useCompany",
"batch_create",
"values/0",
"valueDate"
],
"extensions": {
"data": {
"status": 0
}
}
},
{
"message": "Error: Org unit class not named. Description: Not read access to destination column. Column: OrgUnit3.",
"path": [
"useCompany",
"batch_create",
"values/0",
"orgUnit3"
],
"extensions": {
"data": {
"status": 3,
"status_name" : "NotReadAccessToDestinationColumn"
}
}
},
{
"message": "Error: Org unit class not named. Description: Not read access to destination column. Column: OrgUnit4.",
"path": [
"useCompany",
"batch_create",
"values/0",
"orgUnit4"
],
"extensions": {
"data": {
"status": 3,
"status_name" : "NotReadAccessToDestinationColumn"
}
}
},
{
"message": "Error: Org unit class not named. Description: Not read access to destination column. Column: OrgUnit5.",
"path": [
"useCompany",
"batch_create",
"values/0",
"orgUnit5"
],
"extensions": {
"data": {
"status": 3,
"status_name" : "NotReadAccessToDestinationColumn"
}
}
}
],
"data": {
"useCompany": {
"batch_create": {
"affectedRows": 1,
"items": [
{
"batchNo": 26,
"valueDate": 20211122,
"voucherSeriesNo": 3
}
]
}
}
}
}
```
## Understanding error information
When an error occurs during the execution of the query, you may see the following information for each returned error:
- `message`: always present, contains a description of the error
- `path`: contains the path in the query (schema) of the field that produced the error
- `extensions`: additional information about the error. An example is `data:status` that contains an internal error code that could be useful for troubleshouting a failed execution. In addition, `data:status_name` provides a symbolic name of the status code, such as `NotReadAccessToDestinationColumn`.
The `path` contains an array of node names from the GrapghQL query to indicate the source of error. For instance `["useCompany", "batch_create", "values/0", "valueDate"]` indicates that the error occurred when trying to assign a value to the `valueDate` field of the first object in the `values` array of the `batch_create` operation of the `useCompany` query.
Another example of an error message from attempting to create an order with a duplicate ID is shown below. You can see that `status` is 3 but `status_name` is set to `PrimaryKeyAssignmentFailed` to give you a better understanding of what the status code 3 means in this context.
```json
{
"errors": [
{
"message": "A record with the same primary key already exists.",
"path": [
"useCompany",
"order_create",
"values/0",
"accountNo"
],
"extensions": {
"data": {
"status": 3,
"status_name": "PrimaryKeyAssignmentFailed"
}
}
}
],
"data": {
"useCompany": {
"order_create": {
"items": null
}
}
}
}
```
For compound insert operations (such as creating a new order with multiple order lines), you may get error messages for both the main table (e.g. order) and the sub-table (e.g. order line). For example, you may get an error message for the order that a customer does not exist, and you may get an error message for an order line because a product does not exist.
In this case, the error messages may look as in the following example:
```graphql { title = "Query" }
mutation make_order_errors($cid : Int!)
{
useCompany(no :$cid)
{
order_create(values : [
{
customerNo : 1234567
orderLines :
{
productNo : "103",
quantity : 1
}
},
{
customerNo : 10020
orderLines : [
{
productNo : "103",
quantity : 1,
priceInCurrency : 100
},
{
productNo : "102",
quantity : 1,
priceInCurrency : 50
}
]
}
],
onError : FAIL_ROW)
{
affectedRows
items
{
orderNo
customerNo
joindown_OrderLine_via_Order
{
items
{
orderNo
lineNo
productNo
quantity
priceInCurrency
}
}
}
}
}
}
```
```json { title = "Result" }
{
"errors": [
{
"message": "Error: Customer 1234567 does not exist.",
"path": [
"useCompany",
"order_create",
"values/0",
"customerNo"
],
"extensions": {
"data": {
"status": 16,
"status_name": "referenceNotAccepted"
},
"details": "GraphQL.ExecutionError: Error: Customer 1234567 does not exist."
}
},
{
"message": "Error: Product 102 does not exist.",
"path": [
"useCompany",
"order_create",
"values/1",
"orderLine/1",
"productNo"
],
"extensions": {
"data": {
"status": 16,
"status_name": "referenceNotAccepted"
},
"details": "GraphQL.ExecutionError: Error: Product 102 does not exist."
}
}
],
"data": {
"useCompany": {
"order_create": {
"affectedRows": 1,
"items": [
null,
{
"orderNo": 3506,
"customerNo": 10020,
"joindown_OrderLine_via_Order": {
"items": [
{
"orderNo": 3506,
"lineNo": 1,
"productNo": "103",
"quantity": 1,
"priceInCurrency": 100
}
]
}
}
]
}
}
}
}
```
The path for the first error is `["useCompany","order_create","values/0","customerNo"]` which indicates the first order object, and the path for the second error is `["useCompany","order_create","values/1","orderLine/1","productNo"]` which indicates the second order line of the second order.
However, it is important to note that these status codes (and their names) are not unique. A request is composed of multiple operations, such as selecting a table, assigning a value to a field, etc. There are various status codes for each such contextual operation.
Therefore, an operation may return status code 3 that means `NotReadAccessToDestinationColumn`, or status code 3 that means `NotInsertAccessToTable`.
That is why the `status_name` field is useful to help you better understand the problem.
> [!TIP]
>
> For more information about the GraphQL engine errors (such as schema errors, input errors and processing errors) see [GraphQL.NET Error Handling](https://graphql-dotnet.github.io/docs/getting-started/errors/).
## Tracing query execution
Each GraphQL query that executes is assigned a unique identifier. This is used to trace the execution of the query and can be used for identifying problems with the execution. If you need to contact the Business NXT support for help to investigate a problem, you need to provide this unique identifier.
> [!NOTE]
>
> Traces are stored internally for 10 days. After this period, a trace ID can no longer be used to trace the execution of a request.
You can find this unique ID in the response of a GraphQL request. Although this was skipped in the examples shown in this tutorial (for simplicity), each response has a field called `extensions` that contains an object named `vbnxt-trace-id`.
```graphql { title = "Query" }
query read($cid : Int, $pagesize : Int) {
useCompany(no: $cid) {
generalLedgerAccount(first: $pagesize) {
totalCount
items {
accountNo
name
}
}
}
}
```
```graphql { title = "Result" }
{
"data": {
"useCompany": {
"generalLedgerAccount": {
"totalCount": 340,
"items": [
{
"accountNo": 1000,
"name": "Forskning og utvikling"
},
{
"accountNo": 1020,
"name": "Konsesjoner"
},
...
]
}
}
},
"extensions": {
"vbnxt-trace-id": "00000000000000000196b4ea383242fa"
}
}
```
Use the value of the `vbnxt-trace-id` when contacting the Business NXT support.
> [!TIP]
>
> The same trace identifier can be retrieved from the response headers. GraphQL responses have a custom `x-vbc-traceid` header containing the value of the trace identifier.
Rate limits
/businessnxtapi/apireference/ratelimits
page
Rate limiting for Business NXT API.
2026-07-10T12:31:03+03:00
# Rate limits
Rate limiting for Business NXT API.
## Overview
To keep the platform stable and fair for everyone, the Business NXT API applies rate limiting. There are two independent limits, checked in this order, and a request must satisfy both to be processed.
There are two independent limits, and a request must satisfy both to be processed.
### 1. Per-token request rate limit
Checked first, at the gateway - before the request reaches the application. It enforces a request-rate limit keyed on the Authorization token (i.e. per authenticated user/application):
| Setting | Value |
| ------- | ----- |
| Requests allowed | 600 per minute (per Authorization token) |
Exceeding this limit returns HTTP 429 `Too Many Requests` from the gateway. Keep your per-token request rate under 600/minute and spread bursts out over time.
### 2. Concurrent (outstanding) request limit
This caps how many of your requests may be in progress at the same time (per company/customer).
A request occupies a slot from the moment it is accepted until it completes.
This protects the backend from being overwhelmed by many simultaneous long-running calls.
| Setting | Value |
| ------- | ------- |
| Concurrent requests allowed | 60 |
A slot is released as soon as its request finishes. If a request never completes normally (for example, your client disconnects or times out), its slot is automatically freed after 30 minutes so it cannot block future requests indefinitely.
This limit is applied per company or per customer, and the two scopes are counted independently: a request made in a company context does not count toward the customer total, and vice versa. Activity from one company (or customer) never consumes another's allowance.
When exceeded, the request is rejected and surfaced as a GraphQL error in the errors array:
```json
{
"errors": [
{
"message": "Company 12345 has 60 requests in progress. Limit is 60.",
"extensions": {
"code": "OUTSTANDING_LIMIT_EXCEEDED",
"limit": 60
}
}
]
}
```
For a customer-scoped request the message begins "Customer 12345 has ...".
There is no fixed retry time for this limit - a slot frees up only when one of your in-flight requests completes. Retry with a short exponential back-off rather than waiting a fixed interval.
## Integrator guidance
- **Handle both rejection formats**. The per-token limit returns a plain HTTP 429 from the gateway; the concurrent limit returns an HTTP 200 with a GraphQL error carrying `extensions.code = "OUTSTANDING_LIMIT_EXCEEDED"`.
- For the **per-token rate limit**, keep your request rate under 600/minute per Authorization token and spread out bursts.
- For the **concurrent request limit**, there is no fixed wait: back off and retry once your in-flight requests have had time to complete. Use exponential back-off with jitter.
- The per-token rate limit is per Authorization token, while the concurrent limit is per company/customer and counted independently. Parallelizing work across different companies or customers does not draw from a single shared concurrent-request quota.