API

Domain values

The concept of domain values is used a lot in the RamBase API resources. Domain values are a set of values that is possible to use (or have been used) for one or more fields in the API resources. One domain value is sometimes referred to as a DOV, and has the following properties:

  • Key
    The key/value used and stored in the API resources.
  • Description
    Description of the domain value. Visible in GET requests by adding query parameter $showDomainDescriptions=true.
  • Priority
    The sorting index to be used for the domain value. When equal priority, domain values are sorted by the key.

In most of the RamBase client applications these fields are presented as drop downs, both when filtering and when selecting value to update and store.

Applicable domain values

Sales order and shipping advices in RamBase has a property called ShippingDay, which specifies when the goods should be shipped. The selected value will be used to calculate the scheduled shipping date for each item. The field is of datatype string, but only strings matching the keys of the domain values is allowed: V1, V2 ,V3, V4, V5, W1, W2, W3, W4, W5, D0, D1, D2, D3, D4, D5, D6, D7, D8, D9, D21

Note that these domain values represent all possible domain values. The applicable domain values might be a different list pending on the requesting user, company requesting in, activated modules and more. When hovering a field with domain values in the API documentation, a link to the API resource to use for retrieving these applicable domain values is presented. It is also possible to retrieve this URL by using a metadata request. The following URL would be retrieved for the ShippingDay field:

GET https://api.rambase.net/system/domain-values/applicable-values?object=CUSDOC&field=SHIPDAY&$top=80

The result could be like this:

1
{
2
  'domainValues': [
3
    {
4
      'key': 'V1',
5
      'description': 'Monday week before delivery date'
6
    },
7
    {
8
      'key': 'V2',
9
      'description': 'Tuesday week before delivery date'
10
    },
11
    {
12
      'key': 'V3',
13
      'description': 'Wednesday week before delivery date'
14
    },
15
    {
16
      'key': 'V4',
17
      'description': 'Thursday week before delivery date'
18
    },
19
    {
20
      'key': 'V5',
21
      'description': 'Friday week before delivery date'
22
    },
23
    {
24
      'key': 'W1',
25
      'description': 'Monday week of delivery date'
26
    },
27
    {
28
      'key': 'W2',
29
      'description': 'Tuesday week of delivery date'
30
    },
31
    {
32
      'key': 'W3',
33
      'description': 'Wednesday week of delivery date'
34
    },
35
    {
36
      'key': 'W4',
37
      'description': 'Thursday week of delivery date'
38
    },
39
    {
40
      'key': 'W5',
41
      'description': 'Friday week of delivery date'
42
    },
43
    {
44
      'key': 'D0',
45
      'description': 'On delivery date'
46
    },
47
    {
48
      'key': 'D1',
49
      'description': '1 day before delivery date'
50
    },
51
    {
52
      'key': 'D2',
53
      'description': '2 days before delivery date'
54
    },
55
    {
56
      'key': 'D3',
57
      'description': '3 days before delivery date'
58
    },
59
    {
60
      'key': 'D4',
61
      'description': '4 days before delivery date'
62
    },
63
    {
64
      'key': 'D5',
65
      'description': '5 days before delivery date'
66
    },
67
    {
68
      'key': 'D6',
69
      'description': '6 days before delivery date'
70
    },
71
    {
72
      'key': 'D7',
73
      'description': '7 days before delivery date'
74
    }
75
  ],
76
  'paging': {
77
    'position': 1
78
  }
79
}

Note that it is possible to use $filter and $orderBy like described in the filtering and sorting page. You can filter and order by priority, description and key.

GET system/domain-values/applicable-values?object=QIS&field=CATEGORY&$orderBy=Priority,Description&$filter=Key ne 100100

The $showDomainDescription query parameter

When retrieving, creating and updating fields with domain values in the RamBase API, only the key to the domain value is presented and used.

As an example, in the shipment element in sales orders there are 4 fields with domain values: DeliveryTerms, ShippingDay, ShippingAdviceConsolidationField and ShippingAdviceItemSortBy:

GET sales/orders/101000?$select=SalesOrderId,Shipment&$format=json
1
{
2
  'salesOrder': {
3
    'salesOrderId': 101000,
4
    'shipment': {
5
      'deliveryTerms': 'CIF',
6
      'onlyShipEntireSalesOrder': true,
7
      'onlyShipEntireSalesOrderItems': true,
8
      'avoidMultipleShipmentsOnSameDate': false,
9
      'shipBasedOnConfirmedDeliveryDate': true,
10
      'freightForEachShipment': true,
11
      'shippingDay': 'V1',
12
      'consolidateShippingAdvices': false,
13
      'shippingAdviceConsolidationField': 'YOURREF',
14
      'shippingAdviceItemSortBy': 'PART'
15
    }
16
  }
17
}

To include the description in GET requests, set the $showDomainDescriptions to True:

GET sales/orders/101000?$select=SalesOrderId,Shipment&$format=json&$showDomainDescriptions=True
1
{
2
  'salesOrder': {
3
    'salesOrderId': 101000,
4
    'shipment': {
5
      'deliveryTerms': 'CIF',
6
      'deliveryTermsDomainDescription': 'CIF - Cost, insurance and freight',
7
      'onlyShipEntireSalesOrder': true,
8
      'onlyShipEntireSalesOrderItems': true,
9
      'avoidMultipleShipmentsOnSameDate': false,
10
      'shipBasedOnConfirmedDeliveryDate': true,
11
      'freightForEachShipment': true,
12
      'shippingDay': 'V1',
13
      'shippingDayDomainDescription': 'Monday week before delivery date',
14
      'consolidateShippingAdvices': false,
15
      'shippingAdviceConsolidationField': 'YOURREF',
16
      'shippingAdviceConsolidationFieldDomainDescription': 'Customers reference',
17
      'shippingAdviceItemSortBy': 'PART',
18
      'shippingAdviceItemSortByDomainDescription': 'Product name'
19
    }
20
  }
21
}

If specified, the description will be translated to the language provided in the $lang query parameter (if a translation is available in provided language).