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:

OrderPreferences

The field orderPreferences is an integer, while the field orderPreferencesFlags is an array of the enumeration type OrderPreferencesDomain, shown below:

OrderPreferences

We can query these fields as follows:

Query


query read_order_preferences($cid : Int!)
{
  useCompany(no: $cid)
  {
    order
    {
      items
      {
        orderPreferences
        orderPreferencesFlags
      }
    }
  }
}

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:

Query


mutation insert_order($cid: Int)
{
  useCompany(no: $cid)
  {
    order_create(values: [
      {
        orderPreferencesFlags : [
          GrossOrder,
          PickWholeOrder,
          FreeOfReminderFee
        ]
      }
    ])
    {
      affectedRows
      items
      {
        orderNo
        orderPreferences
        orderPreferencesFlags
      }
    }
  }
}

Result


{
  "data": {
    "useCompany": {
      "order_create": {
        "affectedRows": 1,
        "items": [
          {
            "orderNo": 4498,
            "orderPreferences": 1057024,
            "orderPreferencesFlags": [
              "GrossOrder",
              "PickWholeOrder",
              "FreeOfReminderFee"
            ]
          }
        ]
      }
    }
  }
}

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
      }
    }
  }
}

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:

Update


mutation update_order($cid: Int, $ono : Int!)
{
  useCompany(no: $cid)
  {
    order_update(
      filter : {orderNo : {_eq : $ono}},
      value: {
        orderPreferencesFlags : []
      })
    {
      affectedRows
      items
      {
        orderNo
        orderPreferences
        orderPreferencesFlags
      }
    }
  }
}

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:

Query


query read_order($cid: Int)
{
  useCompany(no: $cid)
  {
    order(filter : {
      orderPreferencesFlags : {_is_on : GrossOrder}})
    {
      totalCount
      items
      {
        orderNo
        orderPreferences
        orderPreferencesFlags
      }
  }
}

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:

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
      }
    }
  }
}

Variables


{
  "cid" : 123456789,
  "ono" : 42,
  "opf": [
    "GrossOrder",
    "PickWholeOrder",
    "FreeOfReminderFee"
  ]
}

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
      }
    }
  }
}

Variables


{
  "cid" : 12345678,
  "ono" : 42,
  "ord": {
    "orderPreferencesFlags" : [
      "GrossOrder",
      "PickWholeOrder",
      "FreeOfReminderFee"
    ]
  }
}

Last modified September 24, 2024