Field	Explanation
Vc code	This is the register code, this specifies which data the end-point is serving and updating.
ImportTag	This currently has no effect on anything
MainKey	This is the name of the main key (primary key) for this register. You will need to know this, to configure the end-point properly. Most of the time you can guess this name by the "main" field in the register. For registers with numbered records this will typically be "SerNr", for records with a Code field it's typically "Code", but can sometimes also be called "MainKey" or something else. To be safe, you will need to consult with a HAL programmer, if you are not one yourself.
Import date and time	These are informative fields and show when the definition was imported.
Support variable fields	These are used in more advanced use cases of the API. These support variables ar maintained throughout the lifecycle of each API request and are available in all HAL hook functions. You can store temporary data (e.g. implementing a cache of some data you do not wish to be re-read from the database for each record in a record set). You can specify multiple variables or even arrays or vectors of a variable type, depending on your need.
Block	Checked when the end-point is made for a block not register.
Export Attachments	When checked, information about attached files will be included in the JSON data for records accessed via this end-point.
View Attachments	When checked, an additional interface will be generated for attachment retrieval.
Add Attachments	When checked, an additional interface will be generated for adding attachments to records accessed via this end-point.
Delete Attachments	When checked, an additional interface will be generated for deleting attachments to records accessed via this end-point.
Do not use SequenceNumbers	No longer necessary, used in older versions of the API - the usage of SequenceNumbers for registers is detected automatically.
Field configuration
Column	Explanation
Name, Type, Length, Location	These describe the field's parameters in the database structure.
In list	This determines whether the field is included when requesting the short/list version of the data. Typically used for retrieving record list with general data of the record (for displaying in record lists or other similar data overviews).
In full	This determines whether the field is included in the full set of record's data.
Filter by	Whether to enable filtering by this field when making API requests.
Index names (3 columns)	These all serve the same purpose - for listing comma-separated index names in which the field is included. This then enables proper sorting by these indexes. You do not need to list all indexes a field is used in, just the ones you actually wish to use. You also do not need to list an index on all of the index's fields, just the ones you actually wish to set your sort on or lookup records by. Same limitations apply as with using indexes in HAL - you can't omit a key field from the middle of an index.

...

File Role

halcust/serverJSON/generated-interfaces/JSON_InterfaceCallers.hal

This is is the main entry point for all API calls. Think of it as a router. Everything will go through this file and get re-routed to the appropriate API sub-routines.

Info
You won't need to ever make changes to this file.

Note
This file will always be re-generated when changing the API configuration.

Info
The register code for Orders - `ORVc` - is used, but this part of the filename will change according to whatever register you are setting up the API for.

halcust/serverJSON/generated-interfaces/JSON_ORVc.hal

This is the main Read API functionality. It contains code for all the indexing, filtering and include/exclude options you selected.

Info
You won't need to ever make changes to this file.

Note
This file will always be re-generated when changing the API configuration.

halcust/serverJSON/generated-interfaces/JSON_ORVc_Tools.hal

This file is where the Read API customisation happens. This contains all the available HAL hooks that you can take advantage of to either include additional data or add custom filtering or other behavior to the API.

The various possibilities are documented towards the end of the documentation.

halcust/serverJSON/generated-interfaces/JSON_Save_ORVc.hal

This is the main Write API functionality. It's responsible for populating the record with the field values that you pass via the API.

Info
You won't need to ever make changes to this file.

Note
This file will always be re-generated when changing the API configuration.

halcust/serverJSON/generated-interfaces/JSON_Save_ORVc_Tools.hal

This file is where the Write API customisation happens. This contains all the available HAL hooks that you can take advantage of to either include record validations, additional calculations, changes to other linked records etc.

The various possibilities are documented towards the end of the documentation.

...

Section

Column

width	60%

Documentation

Examples

Code Block

language

bash

title

Simple record list retrieval using curl

linenumbers

Parameter Usage

token

without request number prefix

Must be included, if you've set up a security token in your API Settings.

query

This routes the API to the specific register's end-point. This is supplied in the following format:

Code Block
Web_JSON_<register-code>_List.hal

So for example for the Orders register with code ORVc the end-point becomes Web_JSON_ORVc_List.hal

company The company number from which you wish to the data to be retrieved.

full

(optional)

Set this to true to retrieve the full data set (as defined using the "In full" column in the API Register Definition record as described earlier).

Defaults to false

count

(optional)

The number of records to return.

Defaults to 50

offset

(optional)

Used together with the count paramete to skip the first set of records when employing a paginated record retrieval approach (i.e. offset of 50 with count of 50 would mimic requesting a second page of 50 records).

since_seq

(optional)

All data sets for registers that support sequencing/sequence numbers are returned along with the current database sequence number - a counter that is increased when a change is made in the respective register. If you record this number and then use it as the since_seq parameter in subsequent calls, you can retrieve only the records that have changed since the previous data request.

index

(optional)

Select the index you wish your data to be sorted by or looked up by. Must be defined in the API Register Definition.

Defaults to the main key specified on the API Register Definition.

sort_only

(optional)

If you do not wish to lookup data by specific values of the fields in the specified index, you can set this to true to only apply a sort by this index.

Defaults to false

sort_order

(optional)

Set to back to apply a descending sort order.

Defaults to forward

fieldcnt

(optional)

When looking up data by specific index field values, you must specify the index segment/field count to use.

Defaults to none

fieldlist

(optional)

When looking up data by specific index field values, you must specify the field names by which to perform the lookup.

This is then accompanied with additional dynamic fieldname-named parameters.

Example: index=CustCode&fieldcnt=1&fieldlist=CustCode&CustCode=05131

Note
This is a pseudo-example, as you always have to prepend the parameter names with the request's index. In single-request calls use `0` (`0_index` and so on).

Info

When using indexes with date fields for lookups you can either lookup by a single specific date or use a date range. To use a lookup by range, add another parameter along with the date field, with the string "-until" appended.

Example: When using field OrderDate you can use either just the OrderDate=2020-01-01 for a single date or both OrderDate=2020-01-01 and OrderDate-until=2020-01-31 for a full month.

You do not need to list the -until parameter in fieldlist

Date format is YYYY-MM-DD everywhere on the API.

new

(optional)

This parameter will return a blank record to be used as a template for populating a new record.

debug

(optional)

Set this to on to enable debug logging in hansa.log for each API call. This will give performance statistics of the call.

Default value is off

paramlist

(optional)

Use this to list parameter names that you wish to see the values of dumped to the debug information log.

Column

width	40%

any fieldname

(optional)

You can pass any field name with a value to use as a filter. For example, you could use the Order field InvFlag value set to 0, to only filter Orders that need to be invoiced.

Note
You need to explicitly configure the fields you wish to filter by in this manner by setting the matrix column Filter by to "Include" in the API definition record.

Column

width	40%

Examples

Code Block

language	bash
title	Simple record list retrieval using curl
linenumbers	true

curl "https://your.server.address/Web_JSON_Composer.hal \
  ?token=security_token
  &0_query=Web_JSON_ORVc_List.hal
  &0_company=1
  &0_count=5"

Code Block

language	js
title	Result
linenumbers	true
collapse	true

{
  "0": {
    "addinfo": {},
    "db-seq-nr": 1082107131,
    "records": [
      {
        "SerNr": 200000,
        "OrdDate": "2019-12-04",
        "CustCode": "02306",
        "Addr0": "Smith and Sons"
      },
.. 5 records in total ..
    ]
  }
}

Info
You will notice that the result is also returned in numbered blocks to match your query request index(-es).

-

Code Block

language	bash
title	Simple record list retrieval using curl, also demonstrating the use of multiple requests in one call
linenumbers	true

curl "https://your.server.address/Web_JSON_Composer.hal \
  ?token=security_token
  &0_query=Web_JSON_ORVc_List.hal
  &0_company=1
  &0_index=SerNr
  &0_fieldlist=SerNr
  &0_fieldcnt=1
  &0_SerNr=200000
  &1_query=Web_JSON_ORVc_List.hal
  &1_company=1
  &1_index=SerNr
  &1_fieldlist=SerNr
  &1_fieldcnt=1
  &1_SerNr=200001"

Code Block

language	js
title	Result
linenumbers	true
collapse	true

{
  "0": {
    "addinfo": {},
    "db-seq-nr": 1082107131,
    "records": [
      {
        "SerNr": 200000,
        "OrdDate": "2019-12-04",
        "CustCode": "02306",
        "Addr0": "Smith and Sons"
      }
    ]
  },
  "1": {
    "addinfo": {},
    "db-seq-nr": 1082107131,
    "records": [
      {
        "SerNr": 200001,
        "OrdDate": "2019-12-04",
        "CustCode": "02921",
        "Addr0": "Only Smith's Sons"
      }
    ]
  }

}

-

Code Block

language	bash
title	Retrieving a full record
linenumbers	true

curl "https://your.server.address/Web_JSON_Composer.hal \
  ?token=security_token
  &0_query=Web_JSON_ORVc_List.hal
  &0_company=1
  &0_full=true
  &0_index=SerNr
  &0_fieldlist=SerNr
  &0_fieldcnt=1
  &0_SerNr=200000"

Code Block

language	js
title	Result
linenumbers	true
collapse	true

{
  "0": {
    "addinfo": {},
    "db-seq-nr": 1082107131,
    "records": [
      {
        "SerNr": 200000,
        "OrdDate": "2019-12-04",
        "CustCode": "02306",
        "Addr0": "Smith and Sons",
        "Addr1": "13 Grange Road",
        "Addr2": "",
        "Addr3": "Bermondsey",
        "OurContact": "",
        "CustContact": "Miss Yolanda Sweet",
        "ExportFlag": 0,
        "InvFlag": 2,
        "ShipFlag": 1,
        "Prntdf": 1,
        "PayDeal": "30",
        "CustCat": "VIP",
        "InvMark": true,
        "ShipMark": true,
        "Objects": ["Z413", "D02306", "VIP"],
        "ShipMode": "",
        "OrderStatus": 0,
        "SalesMan": ["SJ"],
        "Sign": "",
        "ShipDeal": "",
        "ShipAddr0": "",
        "ShipAddr1": "",
        "ShipAddr2": "",
        "ShipAddr3": "",
        "CurncyCode": "GBP",
.. other defined fields ..
        "$matrix": [
          {
            "stp": 1,
            "ArtCode": "ITEM1",
            "Quant": 1,
            "Price": 19,
            "Sum": 19,
            "vRebate": 0,
            "SalesAcc": "4010",
            "Shipd1": 1,
            "Shipd2": 1,
            "Invd": 1,
            "Objects": ["SGR", "TPB", "ORI"],
            "BasePrice": 16.13,
            "rowGP": 2.87,
            "Spec": "Main Item With Interesting Example Name",
            "VATCode": "0",
.. other row fields ..
          },
          {
            "stp": 1,
            "ArtCode": "ITEM1",
            "Quant": 1,
            "Price": 19,
            "Sum": 19,
            "vRebate": 0,
            "SalesAcc": "4010",
            "Shipd1": 1,
            "Shipd2": 1,
            "Invd": 1,
            "Objects": ["SGR", "TPB", "ORI"],
            "BasePrice": 16.13,
            "rowGP": 2.87,
            "Spec": "Main Item With Interesting Example Name",
            "VATCode": "0",
.. other row fields ..
          },
          {
            "stp": 1,
            "ArtCode": "ITEM1",
            "Quant": 1,
            "Price": 19,
            "Sum": 19,
            "vRebate": 0,
            "SalesAcc": "4010",
            "Shipd1": 1,
            "Shipd2": 1,
            "Invd": 1,
            "Objects": ["SGR", "TPB", "ORI"],
            "BasePrice": 16.13,
            "rowGP": 2.87,
            "Spec": "Main Item With Interesting Example Name",
            "VATCode": "0",
.. other row fields ..
          }
        ]
      }
    ]
  }
}

...

Write API - pending polishing

...

width	30%

...

width	70%

Advanced Use

HAL hook functions

...

Entry point

All Write API is accessed via the following single entry-point URL:

Code Block

language	text

 https://your.server.address/Web_JSON_UpdatingComposer.hal

Writing records

API Expects a POST request with JSON formatted post data, all of the neccessary data should be inserted into the body instead

Info

Column

width	20%

Request:

Code Block

language	bash
title	Simple record list retrieval using curl, also demonstrating the use of multiple requests in unsafe-one call
linenumbers	true

curl "https://your.server.address/Web_JSON_UpdatingComposer.hal \
  ?token=security_token"

Column

width	35%

POST Body data:

Code Block

language	bash
title	Simple record list retrieval using curl, also demonstrating the use of multiple requests in unsafe-one call
linenumbers	true

{
	"0": {
		"name": "WEB_JSON_ORVc_Save.hal",
		"company": 1,        
		"data": {
            "action": "insert",	
			"CustCode": "10101",
            "OrdDate": "2024-04-15",
			"matrix": [
				{
					"ArtCode": "16X20DAL",
					"Quant": 1,
					"Price": 26300.00
				},
				{
					"ArtCode": "ABUS12829.L",
					"Quant": 1,
					"Price": 565.00,
                    "returnfull": "adsf"
				}
			]
		}
    },
	"1": {
		"name": "WEB_JSON_ORVc_Save.hal",
		"company": 1,
		"data": {
			"action": "insert",
			"CustCode": "10101",
			"matrix": [
				{
					"ArtCode": "16X20DAL",
					"Quant": 1,
					"Price": 26300.00
				},
				{
					"ArtCode": "ABUS12829.L",
					"Quant": 1,
					"Price": 565.00
				}
			]
		}
	}
}

Column

width	35%

Successfull Response

Code Block

language	bash
title	Simple record list retrieval using curl, also demonstrating the use of multiple requests in unsafe-one call
linenumbers	true

 {
    "0": {
        "sernr": 3900005,
        "errors": [],
        "warnings": []
    },
    "1": {
        "sernr": 3900006,
        "errors": [],
        "warnings": []
    }
}

File Upload API - pending polishing

Entry point

All Write API is accessed via the following single entry-point URL:

Code Block

language	text

 https://your.server.address/Web_JSON_UploadingComposer.hal

Advanced Use

HAL hook functions

This section requires advanced knowledge of HAL/SERP programming.

Section

Column

width	50%

Read API

Functions are available in the register's Read interface's Tools file as previously mentioned.

Function	Usage
`AddInfoGeneral`	Allows to add any additional information in the response JSON. This will appear as the contents of the response block's `addinfo` JSON property
`Options`	Allows to set specific options for this request block (e.g. things like JSON formatting options)
`AddInfoRec`	Allows to add any additional information in the response JSON of specific records. This will appear as sibling data to the record's fields. If you wish to separate, you need to explicitly make a wrapping property.
`AddInfoRow`	Allows to add any additional information in the response JSON of specific records rows. This will appear as sibling data to the row's fields. If you wish to separate, you need to explicitly make a wrapping property.
`LoopTest`	Allows to add additional test conditions for record loops, that are more complex that checking agains a single value of a field
`LoginTest`	Allows to add authentication logic that's specific to a register's API
`NewExtra`	Allows to add extra information when retrieving a blank record template with the `new` parameter.

Column

width	50%

Write API

Functions are available in the register's Write interface's Tools file as previously mentioned.

Function	Usage
`SaveCheck`	Allows to add RecordCheck-like validations or even a full RecordCheck call
`DeleteCheck`	Allows to add custom logic for validation record deletion
`SaveWarnings`	Add custom warnings that do not fail the storing of record, but simply provide some warning-level feedback
`SaveExtra`	Allows to perform additional actions when storing records
`DownloadFileTest`	Allows to implement custom logic when determining whether attachment download is allowed for a record
`UploadFileTest`	Allows to implement custom logic when determining whether attachment upload is allowed for a record
`RemoveFileTest`	Allows to implement custom logic when determining whether attachment removal is allowed for a record
`PasteValue`	Can add actions that should be run after setting a value for each or separate fields. This is similar to AfterEditField Window Actions

...

Versions Compared

Old Version 57

New Version Current

Key

Table of Contents

Retrieving the database structure of a register

Example

Documentation

Examples

Examples

Write API - pending polishing

Advanced Use

HAL hook functions

Entry point

Writing records

File Upload API - pending polishing

Entry point

Advanced Use

HAL hook functions

Read API

Write API

Page Comparison

Versions Compared

Old Version 57

New Version Current

Key

Retrieving the database structure of a register

Example

Documentation

Examples

Examples

Write API - pending polishing

Advanced Use

HAL hook functions

Entry point

Writing records

File Upload API - pending polishing

Entry point

Advanced Use

HAL hook functions

Read API

Write API