REST interface

Architecture


1. Horizon is an ERP system with broad scope of available functionality. Users and user roles are defined using Horizon GUI application. Horizon has a desktop GUI application (fat-client) as well as an application server (FTGServer), each of which requires connection to the database. Horizon have two types of users – GUI user (Horizon user) and WEB user. Several WEB users are linked to a GUI user, sharing access/authorization options of the respective Horizon user. When used together with web users, Horizon user acts as a role definition.

2. The central element of Horizon system is the database. It stores data and is also used to enable deployment of executable files to the client infrastructure/user workstations. The database is usually hosted in client’s infrastructure. Horizon supports Microsoft SQL database.

3. FTG server is the name of Horizon application server, which is a console application. The server provides two APIs – FTG (Java or .NET FTGClient library) and REST (an HTTP based protocol). Both API-s: FTG and REST can be used simultaneously.

For the application server management, the Agent application is installed on the same computer as FTGServer, running as Windows system process. The Agent's task is to manage server instances and deploy binary file updates of the application server. Upon starting, the Agent is registered at Horizon database – database holds a centralised view of all running Agent instances and servers they manage.

To access FTGServer a Web user is needed. In order to create one, a Horizon GUI user has to be set up with, defining it’s access permissions/restrictions. After that Web users can be created, linking them to the appropriate technical Horizon user. The Web user may be associated with a set Horizon system object, for example, a person or a customer. If so, data retrieved from the application server can have a restricted scope.

4. HorizonWEB is a Horizon self-service portal. It is an IIS Web application. WEB application accesses data through FTGClient library that is connected to a FTG server instance.

5. User of the self-service portal can be any employee of the company. Portal is accessible using a web browser.

6. To access the REST API any tool or technology that supports HTTP protocol can be used. HTTP is the technology behind any Web application, therefore it is supported in various programming IDEs. Most of the information provided by REST interface is viewable in a web browser.

Enabling REST API

Starting from Horizon version 440. REST API is included in FTG server, but it is not enabled by default. To enable REST API a port number must be supplied in server configuration file (file config.xml, which is located next to FTGServer.exe).


It should be ensured that the port number supplied is free. Port 80 indicated in this example is the default HTTP interface port, and for security reasons it is advised to pick some other port number to be used, leaving port 80 served by a classic HTTP server, such as Apache or Microsoft IIS. A classic HTTP server can be used to enable HTTPS protocol to access REST API.

REST interface concept

Functionality of Horizon uses 2 basic elements – lists (also reports) for data queries and entities/form’s representing a single data element (record/card/document). Behind each visual element, Horizon system has a class containing its specific business logics. Instances of these classes are the objects that can be accessed and manipulated through the REST API. A list class will be referred to as a collection and a class representing single data element will be referred to as an entity.


For example, list of customers (corresponding class name TDdmKlSar) looks like this:


Horizon customer list illustration has the first column as System ID. This field shows the primary key value of the customer record. The System ID field is shown in the user interface only if the executable is started using a command line parameter -s. By default it is hidden.

For example, FTG20.exe -s.


The entry form (corresponding class TDdmCustomer) allowing editing information about one customer looks like this:


In Horizon desktop GUI, the list of all defined entities and their collections is available indirectly in the administrative role configuration window (all collections) and administrative filter variables (all entities).



In REST API, each list/entity class has its own first-level resource, accessible using the name of the class. The resource can be compared to a folder created in a computer file system: all relevant files can be stored in it. Thus, sub-resources specific to a class are available under a class resource.


The REST API is set up to be self-descriptive where possible: accessing the REST interface in a web browser we can view all available first-level resources. If we go to a specific class resource, we can view next-level resources – which can be either sub-resources or operations depending on the context. When searching for a resource it’s description field can be used -  it usually contains same info as is visible in Horizon interface.



The REST API operates by exchanging XML data representations and using HTTP protocol elements as resources, various request methods and status codes. HTTP elements’ description used by each class resource is available in a WADL sub-resource (or by requesting by OPTIONS method), and XML data structure description is available as an XSD sub-resource.

Entity resource

A primary key value supplied in a REST request (96 in the example below) is used to locate a particular entry. In the XML received, we see the field values of a chosen customer entry.


XML shows the values of data fields, each value is shown between opening and closing tags. Name of the tag is the name of the field. There are different types of fields.

For simple values, such as name (element NOSAUK), XML element shows the same data as is visible in Horizon GUI.

For foreign keys (references to other entities), for example, customer's country of residence (element PK_VALSTS) "Latvia", the value is shown as a link to another resource /rest/TdmBLValsts/4. It means that the field value is a reference (foreign key) to a particular state record with the primary key 4. This resource directing allows knowing both the key value (4) and also the class resource where the values description can be found (TdmBLValsts).

For values of enumerable type, such as customer type (element DBKRPAZ), only numeric values are shown, for example, 1. The meaning of enum’s value can be found in class’s XSD description: 1 – "Debtor".

 

The root resource of a class describes other sub-resources are available.


The following resources can be useful:

1. /rest/TDdmCustomer/{pk} – resource for reading entity’s data referenced by its primary key value;

2. /rest/TDdmCustomer/TDdmCustomer.xsd – XML schema showing data types, field labels, enum definitions, etc.;

3. /rest/TDdmCustomer/TDdmCustomer.wadl – definition of the class resource, its sub-resources and available operations using WADL (Web Application Definition Language) format;

4. /rest/TDdmKlSar – a collection resource corresponding to the client's entity


XML schema (XSD) is the formal description of the XML structure. It defines XML elements, value types and limitations. XSD sub-resource name is the same as object's class name. Thus, by viewing the customer’s  XSD resource, we can get XML structure description.



The XML schema describes fields available and their data types. For example, the schema shows that element PK_DOKT is a reference to another resource /rest/TdmDocType. For a simple value, element KODS allows up to 15 symbol long textual value. In turn, element TIPS is an enumeration, in which, for example, value 3 means an "Individual", and 6 – "Company".


The resource /rest/TDdmCustomer also contains a reference to the corresponding collection resource -  /rest/TDdmKlSar. The collection resource for any entity resource can be determined by applying a simple XPath request to XML content: /resource/link/href[@rel='collection']/text()

Entity collection resource

Similarly as the entity resource, a collection root resource /rest/TDdmKlSar lists its sub-resources.



The information found on the root page:


1. Collection resource label. In this case it is "Klientu izvēles saraksts" (Customer selection list);

2. What are the names of fields containing the primary key (element K.PK_KLIENTS) and entity code (element K.KODS) respectively;

3. Sub-resource /rest/TDdmKlSar/query for data requests;

4. Sub-resource /rest/TDdmKlSar/TDdmKlSar.xsd XML schema description;

5. Sub-resource /rest/TDdmKlSar/criteria contains a list of predefined selection criteria for the class. Filtering by any field is possible as well, like it is in Horizon GUI.


A sample data request: /rest/TDdmKlSar/query?columns=K.KODS,K.NOSAUK&filter=K.PK_KLIENTS eq 96


The data request indicates a ‘filter’ parameter to select entries with value 96 stored in the field PK_KLIENTS. Parameter ‘columns’ states that the response should include customer code and name fields (K.KODS and K.NOSAUK). In addition, every query response will include the primary keys (K.PK_KLIENTS) and counter fields.


In Horizon GUI fields to be retrieved are configured using the layout window.



Available fields are grouped by table wherefrom they are selected. Each group (table) has a name and a short label.

The XML schema of a collection displays the same hierarchical structure.

First level fields of the customer table are grouped by XML element <K>.  Fields of a joined table are available under the respective grouping XML element named using a technical table alias. As the Horizon collection objects are constructed by joining different entity objects, the available fields are not found directly in the collection scheme, but can be found by querying their respective entity schemas.

NB! Not all entity fields are guaranteed to be available in any collection an entity is referenced in. A field might be excluded for technical or logical reasons. Unavailability of a field is not an error. Horizon GUI layout window can be used as a reference to find out which fields are actually available.

The columns to be included in the response should be indicated using HTTP parameter ‘columns’. For example, in customer query response using parameter columns=K.TIPS,K.KODS,K.NOSAUK,K.DBKRPAZ,K.REG_NR will contain the columns requested.

The collection resource provides the same filtering options as are available in Horizon GUI.


In the example above the Horizon customer list is filtered to select only companies with a settlement type "debtor". By analogy, the client collection resource can be filtered same way, using HTTP parameter ‘filter’.

filter=K.TIPS eq 3 and K.DBKRPAZ eq 1

Operations on an entity resource

HTTP method usage for CRUD operations

An acronym CRUD is used to denote basic operations on data - create, read, update and delete.

REST concept allows access to data by using different resources. For each resource, HTTP protocol methods (GET, POST) are used to allow operations on data The table below provides an overview of available operations, using customer entity as an example.


HTTP method


Resource

Explanation

POST

/rest/TDdmCustomer

Creation of a new entity. See the example the creation of a simple entity (client address)

GET

/rest/TDdmCustomer/{pk}

Reading of entity’s data.

POST

/rest/TDdmCustomer/{pk}

Update of entity’s data.

DELETE

/rest/TDdmCustomer/{pk}

Deletion of an entity.

GET

/rest/TDdmCustomer/template/{pk}

Obtaining data for a chosen template to be used in new entity’s creation.

POST

/rest/TDdmCustomer/template/{pk}

Creation of a new entity using a chosen template.

Selection of entity data

Entities’ data can be retrieved by addressing a sub-resource {pk} of the particular class, where {pk} is the key value for the particular entity (primary key):


Example of a request:

GET /rest/TNdmAdr/555 HTTP/1.1

Connection: Keep-Alive


By default, the response will provide data in XML format.

Response to a request:

HTTP/1.1 200 OK

Connection: keep-alive

Content-Type: application/xml; charset=UTF-8

Content-Length: 1143

Date: Wed, 03 Jun 2015 07:47:09 GMT

 

<resource xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance" >

   <description>Entītijas ieraksts</description>

   <entity xsi:schemaLocation="TNdmAdr.xsd TNdmAdr.xsd"  xmlns="TNdmAdr.xsd">

      <COUNTER>0</COUNTER>

      <ADRESE>Kronvalda bulv.3/5, Rīga, LV-1010, Latvija</ADRESE>

      <KONTAKTP/>

      <KONTAKTP_LNG1/>

      <KONTAKTP_LNG2/>

      <KONTAKTP_LNG3/>

      <LIC_NR/>

      <LIC_DAT/>

      <PIEZIMES/>

      <PK_ADRESE>

         <href rel="self">/rest/TNdmAdr/555</href>

      </PK_ADRESE>

      <PK_KLIENTS>

         <href>/rest/TDdmCustomer/-11</href>

      </PK_KLIENTS>

      <STATUSS>1</STATUSS>

      <PK_REGIONS/>

      <PK_REISS/>

      <ADRESE1/>

      <ADRESE1_LNG1/>

      <ADRESE1_LNG2/>

      <ADRESE1_LNG3/>

      <ADRESE2/>

      <ADRESE2_LNG1/>

      <ADRESE2_LNG2/>

      <ADRESE2_LNG3/>

      <ADRESE3/>

      <ADRESE3_LNG1/>

      <ADRESE3_LNG2/>

      <ADRESE3_LNG3/>

      <PASTA_IND/>

      <PASTA_IND_LNG1/>

      <PASTA_IND_LNG2/>

      <PASTA_IND_LNG3/>

      <PK_VALSTS>

         <href>/rest/TdmBLDValsts/3</href>

      </PK_VALSTS>

      <LEG_ADR>2</LEG_ADR>

      <POST_ADR/>

      <KILOMETRI/>

      <PK_KLKPERS/>

      <PK_ADR2/>

      <PRIMADR/>

   </entity>

   <link>

      <href>/rest/TNdmAdr/555/print</href>

      <description>Izdrukas</description>

   </link>

</resource>

Creation of a new entity using template (document types)

Documents

To create a new document, use of a previously defined template is required. Templates in Horizon are called document types. Templates can be defined using Horizon GUI. Typically a template is set up describing default values for the fields, auto numbering options, additional mandatory fields, uniqueness constraints, etc.

When importing data into Horizon from other systems, it is advised to define and use a separate template for the imported data, so enabling to distinguish data entered manually from data imported by other means.

In Horizon GUI when creating a new document, the user chooses a template and a new entry form is opened with fields pre-filled with default values. The user then completes the document and saves it in the database.

The REST interface provides resources to achieve an identical scenario. For each defined template, its own sub-resource is created. The sub-resources corresponding to all the defined templates are shown in the root resource of an entity class.

The sub-resource of each template contains a link to the sub-resource using a primary key of the template, document type code and document type name. The name is the same as seen in Horizon upon creating a new document.

Usually, a template to be used in integration solutions is identified by its code. This allows decreasing of the system dependencies – the code is a visible and simply maintainable way to make a link between systems. The template resource corresponding to the code can be found by a XPath request. For example, request below finds a template resource with code CRM

/resource/templates/link/href[@rel='CRM']/text()

NB! Please note that primary key values for data as well as for the templates are not transferable between Horizon installations or even two legal entities residing in one installation. It is strongly advised not to hardcode them!


The entity data upon which a template is applied can be obtained by using the GET method on a template resource. Response will contain pre-filled default values, if any. The field values can be modified where necessary and after that the same XML used in a POST method on initial template resource. The operation will result in a new entry. The response will include a link to the newly created resource.


This scenario allows visualisation of a prefilled template if it is necessary.

Classifiers

For entity classes not having document types, the creation scenario is almost identical: the template data are obtained directly from ‘template’ sub-resource by GET method and stored by POST method on the same resource:

POST /rest/TNdmAdr/template HTTP/1.1

Content-type: application/xml;charset=UTF-8

 

<resource>

   <entity>

      <ADRESE>3 Kronvalda bulv., Riga, Latvia</ADRESE>

      <LEG_ADR>1</LEG_ADR>

      <PK_KLIENTS>

        <href>/rest/TDdmCustomer/19615</href>

      </PK_KLIENTS>

      <PK_VALSTS>

        <href>/rest/TdmBLDValsts/662</href>

      </PK_VALSTS>

      <STATUSS>1</STATUSS>

   </entity>

</resource>

Creation of a new entity

The REST interface provides means to create an entity with a single request – without using the templates. The new entry can be created by sending a POST request to the entity class root resource and supplying the template/document type code in the element ‘docType’ and field values to be set. If a new classifier entry is to be created, then docType is not mandatory). It is not necessary to provide values for all fields – omitted fields either will remain empty or will be filled with default values.

In the case of bulk-loading of data this is the most effective method to insert data.


Example: create a customer: a company named "Jauns klients" (New Client) with a registration number 123456789.


Request to create an entry

POST /rest/TDdmCustomer HTTP/1.1

Content-Type: application/xml;charset=UTF-8

 

<resource>

  <docType>CRM</docType>

  <entity>

    <TIPS>3</TIPS>

    <NOSAUK>Jauns klients</NOSAUK>

    <REG_NR>123456789</REG_NR>

  </entity>

</resource>


Response code 201 confirms a successful creation of a new entity with primary key value 18938.

Response to an entry creation

HTTP/1.1 201 Created

Content-Type: application/xml; charset=UTF-8

Date: Mon, 28 Jul 2014 09:33:42 GMT

Organization: 2, "SIA Kalns"

 

<?xml version="1.0" encoding="UTF-8"  standalone="no"?>

<result>

  <link>

    <href>/rest/TDdmCustomer/18938</href>

  </link>

</result>


Example: to create a sales invoice with a payment schedule.

Creation of a new invoice

POST /rest/TNdmPvzSale HTTP/1.1

Content-Type: application/xml;charset=UTF-8

 

<resource>

    <docType>PARD</docType>

    <entity>

        <PK_KLIENTS>

            <href>/rest/TDdmCustomer/17893</href>

        </PK_KLIENTS>

        <PK_ESPATS>

            <href>/rest/TNdmNol/11321</href>

        </PK_ESPATS>

        <DAT_DOK>2015-06-01</DAT_DOK>

        <PK_VAL>

            <href>/rest/TsdmValName/5</href>

        </PK_VAL>

        <DOK_NR>pvz pvz</DOK_NR>

        <APM_TERM>2015-07-01</APM_TERM>

        <DOK_NR2>20150701/1</DOK_NR2>

        <SADAL_APM>1</SADAL_APM>

        <dmDApmSadRBL>

            <row>

                <DATUMS>2015-06-15</DATUMS>

                <SUMMA>25</SUMMA>

                <PK_VAL>5</PK_VAL>

            </row>

            <row>

                <DATUMS>2015-07-01</DATUMS>

                <SUMMA>23.40</SUMMA>

                <PK_VAL>5</PK_VAL>

            </row>

        </dmDApmSadRBL>

        <tblRindas>

            <row>

                <RN_VEIDS>0</RN_VEIDS>

                <PK_NOM>98946</PK_NOM>

                <DAUDZ>1</DAUDZ>

                <PK_VIEN>1008</PK_VIEN>

                <FCENA>50</FCENA>

                <ATLAIDE>20</ATLAIDE>

                <DATUMS>2015-06-01</DATUMS>

            </row>

        </tblRindas>

    </entity>

</resource>


Invoice rows are found in sub-element tblRindas and the payment schedule - in sub-element dmDApmSadRBL.

Update of an entity

The entity is addressed using sub-resource supplying the primary key value, for example, /rest/TDdmCustomer/18938 . The GET method can be used read data, and the POST method can be used to set data. When using POST either all fields or only changed fields can be supplied. Omitted fields will remain unchanged. If a field is present in XML, the value supplied will be set. If a field in XML  is present and empty, the field value will be cleared.


The minimum contents of the XML is the primary key value (doubles the resource POST is sent to) and value of the COUNTER field. The COUNTER field is an update counter used to implement an optimistic locking mechanism. It is incremented after each update of the entity. The value of the COUNTER field must be read using GET and supplied when doing a POST. The update will be successful if and only if the counter value supplied matches the counter value in the database.  If the values does not match the update will fail and HTTP response will have the code 500 responses and an error message to the effect that another user has changed the record.


Example: update of the registration number of the customer – company "Jauns klients"  (New Client).


Request to update an entry

POST /rest/TDdmCustomer/18938 HTTP/1.1

Content-Type: application/xml;charset=UTF-8

 

<resource>

  <entity>

    <COUNTER>1</COUNTER>

    <PK_KLIENTS>

      <href rel="self">/rest/TDdmCustomer/18938</href>

    </PK_KLIENTS>

    <REG_NR>000000001</REG_NR>

  </entity>

</resource>


The response contains operation code 200, indicating success.

Response to an entry correction

HTTP/1.1 200 OK

Date: Mon, 28 Jul 2014 09:54:24 GMT

Organization: 2, "SIA Kalns"

Deletion of an entity

To delete an entity, a DELETE request must be sent to the entity resource that needs to be deleted:


Request to delete an entity

DELETE /rest/TdmCustomer/18938 HTTP/1.1

Content-length: 0

 

If deletion has been successful, the response will contain HTTP response code 204:

HTTP/1.1 204 No Content

Connection: keep-alive

Content-Length: 0

Date: Wed, 03 Jun 2015 07:19:34 GMT

Entity XML data structures

The REST interface provides resources describing the elements used in data XML representation. XML Schema (XSD) standard is used.


XML schema sub-resource of a class is addressed using the class name and adding extension "xsd", for example, resource schema "Ekonomiskā būtība" (economic classification) is available as /rest/TEkButBL/TEkButBL.xsd.


All Horizon objects have been made of table-type data elements. The objects can have several elements with different cardinality in reference to the class in question. For example, in a master–detail relationship, master element is a table with a single row, detail element is a table with several rows. The master element is linked to the detail element by relation 1:n. The objects can have several elements bound to the master element by cardinality 1:1 – such an element will contain a single row.

The example below shows a fragment describing sales invoice entity that containing elements NdmPvzAddition and tblRindas.

Element tblRindas describes rows of the invoice. This is a detail element that can contain several rows (<row> elements, cardinality 1:n). Element NdmPvzAddition relates to the master element by 1:1.

<xsd:complexType name="TNdmPvzSaleEntity">

    <xsd:complexContent>

        <xsd:extension base="TNdmPvzSaleStructure">

            <xsd:sequence>

                <xsd:element name="tblRindas">

                    <xsd:complexType>

                        <xsd:sequence>

                            <xsd:element  name="row" maxOccurs="unbounded"  type="tblRindasStructure"/>

                        </xsd:sequence>

                    </xsd:complexType>

                </xsd:element>

                <xsd:element name="NdmPvzAddition"  type="TNdmPvzAdditionStructure"/>

            </xsd:sequence>

        </xsd:extension>

    </xsd:complexContent>

</xsd:complexType>


The economic type is a simple element that has only one data element.



For the root element, the type name is made as class name + Entity. The complex type describes what data elements the entity consists of and what cardinality each of the elements has.



The complex type of the data element shows fields, their types and names.


The type can show that the field is a reference to another entity. For example, field PK_GRUPA is a reference to group resource /rest/TEkButGrupaBL of the economic classification.


The type can be a simple type. For example, field NOSAUK is a text-type field with the maximum length of 100 symbols.


The enumeration type lists all possible values. For example, the possible values for a field IITIPS are shown in description of TEkButBLIITIPSType.

All simple type definitions used are found at the end of the schema. For example, type Size100StringType definition states that the value must be xsd:string and the maximum length may not exceed 100 symbols. For the enumerable TEkButBLIITIPSType the only values allowed are 0 or 1.

Operations on an entity collection resource

Basic filtering

In the REST interface the filter is supplied by using the request parameter filter. For example, filter=K.TIPS eq 3 and K.DBKRPAZ eq 1.


A filter clause consists of:

Clauses are combined using  logical operators AND and OR. The logical operators can be combined according to the rules defined as conjunctive normal form that means an AND of ORs.  


For example, the following condition is valid: (clause1 or clause2) and clause3 . If a filter condition is not in conjunctive normal form the REST interface will report an error.


As an exception the interface will accept and convert a simple condition in form (clause1 and clause2) OR clause3 into (clause1 or clause3) and (clause2 or clause3).


Operation

REST

Explanation

=

field eq value

The field value is equal to the ‘value’

<>

field ne value

The field value is not equal to the ‘value’

<

field lt value

The field value is less than the ‘value’

<=

field le value

The field value is less or equal to the ‘value’

>

field gt value

The field value is greater than the ‘value’

>=

field ge value

The field value is greater or equal to the ‘value’.

K.REG_DAT ge 2015-01-01


IR TUKŠS

isnull(field)

The field is empty

NAV TUKŠS

not isnull(field)

The field is not empty

SĀKAS AR

startswith(field, 'value')

Only for text fields. The field value starts with the indicated symbols (a template according to SQL ‘LIKE’ operator rules can be used)

PĒC ŠABLONA

like(field, 'value')

Only for text fields. The field value complies with the template

NAV PC ŠABLONA

not like(field, 'value')

Only for text fields. The field value does not comply the template

NESĀKAS AR

not startswith(field, 'value')

Only for text fields. The field value does not start with the indicated symbols (a template can be indicated)

BEIDZAS AR

endswith(field, 'value')

Only for text fields. The field value ends with the indicated symbols

STARP

between(field, value1, value2)

Only for date fields. From one indicated date to the other indicated date, including the endpoints.

between(K.REG_DAT,2014-01-01,2014-12-31)

ŠODIEN

dtoday(field)

Only for date fields. Current date

PĒDĒJĀS

dlast(field, n)

Only for date fields. Time period - the last n days, counting from today (n is the number of days)

NĀKAMĀS

dnext(field, n)

Only for date fields. Time period - the following n days counting from today (n is the number of days)

PIEDER

childof(field, 1)

Only for a field that is included in a hierarchical list. Select values that belong to the indicated item or any of its sub-items

NEPIEDER

not childof(field, 1)

Only for a field that is included in a hierarchical list. Select values that do not belong to the indicated item or any of its sub-items

IEKĻAUJ

parentof(field, 1)

Only for a field that is included in a hierarchical list. Select parent items of the indicated item.


The filter conditions are part of the URL of the request and therefore have to be coded according to specification RFC 1738. Web browsers perform this coding automatically.

GET /rest/TDmKlSar/query?filter=K.KODS%20eq%20%27Visma%20Enterprise%27


Date constants must be formed according to standard ISO 8601. For example,

Text constants must be included in apostrophes. If the text contains an apostrophe as a value, it should be doubled, for example, 'McDonald''s'

GET /rest/TDmKlSar/query?filter=K.KODS%20eq%20%27McDonald%27%27s%27


References to other entities can be indicated either as a simple number - primary key value,  or as a reference, for example, /rest/TDmCustomer/100. In the example below, both filter conditions are equivalent.

K.PK_KLIENTS eq 100

K.PK_KLIENTS eq /rest/TDmCustomer/100


Below is shown an example for a filter condition on a date field where the end date can be empty. The example needs to select valid entries as of 23.02.2015

(isnull(LAT.BEIG_DAT) or (LAT.BEIG_DAT ge 2015-02-23)) and (LAT.SAK_DAT le 2015-02-23)


Section Entity collection resource contains a sample for filter conditions, showing Horizon customer list filtered to select only companies whose settlement type is "debtor".

Additional filtering – parameters

Horizon lists, reports especially, can have entry fields allowing to set parameters for the report calculation. Parameters can be different for each list.

For example, contract balance is calculated by a report Atskaites -> Līgumi -> Līgumu atlikumi.



The image below shows the data selected in Horizon.


The REST interface publishes information about parameters which can be used in the report. The information is available at the sub-resource criteria , tag reportParams. Example below shows parameters of contract balance report /rest/TdmLigAtlSL/criteria.

For example, the request below can be used to obtain the same data in the REST interface /rest/TdmLigAtlSL/query?UzDatums=2016-01-01&columns=KLIG.NUMURS,KLIG.DNV.SUMMA_DB_PV,KLIG.DNV.SUMMA_KR_PV

Additional filtering – criteria

Horizon have pre-defined filtering conditions named criteria. This option does not have a direct visual analogue in Horizon GUI, but is used behind the scenes.


The criteria can have parameters. The criteria can have synonyms defined that can combine several other criteria. At present, only criteria names and parameter names are accessible using REST. The logic behind the definition, if not trivial, can be enquired about in FMS integrator support forum.


For example, using FTG technology, Javadoc documentation class TadmSamvSar includes the following sample: to open a list of payment types filtered by the group.

TadmSamvSar list=(TadmSamvSar)client.getRemoteObject("TadmSamvSar");

list.setColumnRequired("KST_KODS,KST_NOSAUK,APR_NOSAUK,KST_PK_GRUPA,KST_M_TIPS", true);

list.setCriteriaParam("PK_GRUPA", "102");

list.open("GRUPA");


Analogous REST request is /rest/TadmSamvSar/query?criteria=GRUPA&PK_GRUPA=102&columns=KST.KODS,KST.NOSAUK,KST.PK_GRUPA,KST.M_TIPS


The information available at the resource /rest/TadmSamvSar/criteria:

Sorting

Data returned by the collection can be sorted by selected fields. To specify fields the list is to be sorted on a parameter ‘order by’ should be supplied. It is comma-separated field list which can contain modifiers asc (ascending) and desc (descending) as well. Example below sorts on fields ADRESE ascending and PK_ADRESE descending.

GET /rest/TdmNAdresesSar/query?orderby=A.ADRESE,A.PK_ADRESE%20desc HTTP/1.1

Collection XML data structures

Entity collection resource has an XML Schema resource.

In Horizon, any list is organized in an hierarchical view usually having a root element, for example <EkB>, and child elements (or joined elements), for example <Gr>.


XSD example, obtained by addressing the resource /rest/TekButSL/query?columns=GEK.PAMV_ID,GEK.KODS,GEK.NOSAUK,GEK.GEKGRP.KODS,GEK.GEKGRP.NOSAUK.



The field definitions are available in the XML schema. For example, resource /rest/TekButSL/TekButSL.xsd  shows available fields of economic classification item collections.



XML schema of a collection resource shows fields that could be included in the data request. As the collection object is made of the same data elements as the entity object, references to data element’s entity resources are used. The example above shows a reference to group entity schema resource /rest/TEkButGrupaBL/TEkButGrupaBL.xsd of the economic classification items.


Designed reports and document printouts

Horizon lets users design their own reports and document printouts using the built-in report designer. REST interface gives access to the output of the reporting engine. Printouts are available either for the entity or entity collection (list) resources. The printout designs available for each entity class and collection are listed in the sub-resource print of the respective entity and collection resource. The contents of the printout is obtained by submitting GET request to the selected printout design resource. The request must indicate the output format (using Accept header). If necessary, the request can indicate the printout parameters.

GET  http://localhost:81/rest/TNdmNom/99143/print/rtQRRepDoc/1/2947  HTTP/1.1

Accept: application/pdf

Connection: Keep-Alive


Entity printout

The available printout designs for  an entity class are listed in entity sub-resource print.


Request

GET  http://localhost:81/rest/TNdmNom/99143/print  HTTP/1.1 

Response

<resource xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance" >

   <description>Izdrukas</description>

   <group>

      <description>Nomenklatūras svītrkods</description>

      <link>

         <href rel="original">/rest/TNdmNom/99143/print/rtQRRepDoc/1/0</href>

         <description>Nomenklatūras svītrkods</description>

      </link>

      <link>

         <href>/rest/TNdmNom/99143/print/rtQRRepDoc/1/1779</href>

         <description>a4</description>

      </link>

      <link>

         <href>/rest/TNdmNom/99143/print/rtQRRepDoc/1/2714</href>

         <description>ssdfa</description>

      </link>

      <link>

         <href>/rest/TNdmNom/99143/print/rtQRRepDoc/1/2947</href>

         <description>ar tipu</description>

      </link>

      <link>

         <href>/rest/TNdmNom/99143/print/rtQRRepDoc/1/-1</href>

         <description>Nomenklatūras svītrkods (LVL)</description>

      </link>

   </group>

</resource>


The printouts are shown in groups the same as in Horizon GUI. Each group has one report marked as the hardcoded original, based on which copies with modifications might have been created. The original can be distinguished by attribute rel <href rel="original"> .


Entity collection printout

Printouts for entity collection resource are listed in sub-resource print.


Request

GET  http://localhost:81/rest/TNdmNomIzvSar/print HTTP/1.1

Response

<resource xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance" >

   <description>Izdrukas</description>

   <group>

      <description>Ātrā saraksta izdruka</description>

      <link>

         <href rel="original">/rest/TNdmNomIzvSar/print/rtQRFastRep/1/0</href>

         <description>Ātrā saraksta izdruka</description>

      </link>

   </group>

   <group>

      <description>Cenas lapa</description>

      <link>

         <href rel="original">/rest/TNdmNomIzvSar/print/rtQRRepSar/1/0</href>

         <description>Cenas lapa</description>

      </link>

      <link>

         <href>/rest/TNdmNomIzvSar/print/rtQRRepSar/1/2283</href>

         <description>Spec Test</description>

      </link>

      <link>

         <href>/rest/TNdmNomIzvSar/print/rtQRRepSar/1/2403</href>

         <description>Cenas lapa ar papgr</description>

      </link>

      <link>

         <href>/rest/TNdmNomIzvSar/print/rtQRRepSar/1/2404</href>

         <description>Spec Test ar papgr</description>

      </link>

      <link>

         <href>/rest/TNdmNomIzvSar/print/rtQRRepSar/1/2503</href>

         <description>valsts kods</description>

      </link>

      <link>

         <href>/rest/TNdmNomIzvSar/print/rtQRRepSar/1/2572</href>

         <description>Attēlu kartiņu saraksta izdruka</description>

      </link>

      <link>

         <href>/rest/TNdmNomIzvSar/print/rtQRRepSar/1/2584</href>

         <description>ar attelu</description>

      </link>

      <link>

         <href>/rest/TNdmNomIzvSar/print/rtQRRepSar/1/3649</href>

         <description>koko</description>

      </link>

   </group>

</resource>


The printouts are shown in groups the same as in Horizon GUI. Each group has one report marked as the hardcoded original, based on which copies with modifications might have been created. The original can be distinguished by attribute rel <href rel="original"> .

Printout parameters

The following parameters can be indicated for all printouts:


Parameter

Type

Explanation

Default value

copyCount

URL parameter

Number of copies

1

fromPage

URL parameter

Page number to start printing

1

toPage

URL parameter

Page number to stop printing

Last printout page

Accept

Header

Printout output format. Mandatory parameter.

No default value, always must be supplied explicitly. Possible values can be found in wadl sub-resource.


The request below indicates that the returned printout should print pages from starting from second to the tenth and two copies should be created. The result should be a PDF file (in the header: Accept value application/pdf).

GET http://localhost:81/rest/TNdmNom/99143/print/rtQRRepDoc/1/2947?fromPage=2&toPage=10&copyCount=2 HTTP/1.1

Accept: application/pdf

Connection: Keep-Alive

Cookie: IDHTTPSESSIONID=FqRaCoiQrwyv4bG

Printout output format

The printout format can be indicated using request header Accept.

GET http://localhost:81/rest/TNdmNom/99143/print/rtQRRepDoc/1/2947 HTTP/1.1

Accept: application/pdf

Connection: Keep-Alive

Cookie: IDHTTPSESSIONID=FqRaCoiQrwyv4bG


Output formats supported by the particular resource printout can be obtained from WADL resource of the entity. The WADL fragment below shows four supported output formats: PDF, HTML, Excel and RTF.

<resource path="rtQRRepSar/1/2283">

    <method name="GET" id="get">

        <request>

            <param name="copyCount"  type="xsd:integer" style="query" required="false"/>

            <param name="fromPage"  type="xsd:integer" style="query" required="false"/>

            <param name="toPage"  type="xsd:integer" style="query" required="false"/>

            <param name="Accept"  type="xsd:string" style="header" required="true"/>

        </request>

        <response status="200">

            <representation mediaType="application/pdf"/>

            <representation mediaType="text/html"/>

            <representation mediaType="application/vnd.ms-excel"/>

            <representation mediaType="application/rtf"/>

        </response>

    </method>

</resource>

Working with binary data

Binary fields

Obtaining the contents of binary fields

The handling of binary field contents is controlled by the request parameter bindata:


Value

Explanation

Link

Contents of the binary fields are not returned. Instead, the field element has sub-elements size and href . The element size contains the data size in bytes, and element href  contains a link to the resource that has the binary data

Embed

The request response will  provide binary field contents base64-encoded


Examples:

http://localhost:81/rest/TNdmNom/1?bindata=link

http://localhost:81/rest/TNdmNomIzvSar/query?columns=N.NBD.BILDE&bindata=embed

By default (if the request omits bindata), contents of the binary fields contents is not returned, operation is the same as indicating parameter bindata=link.

GET  http://localhost:81/rest/TNdmNom/1 HTTP/1.1


Response

<resource xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance" >

   <description>Entītijas ieraksts</description>

   <entity xsi:schemaLocation="TNdmNom.xsd TNdmNom.xsd"  xmlns="TNdmNom.xsd">

      <NomBilde>

         <COUNTER>0</COUNTER>

         <PK_NOM>1</PK_NOM>

         <BILDE>

            <size>4566</size>

            <href>/rest/TNdmNom/1/BILDE</href>

         </BILDE>

         <PIELIKUMS>1</PIELIKUMS>

      </NomBilde>

   </entity>

   <link>

      <href>/rest/TNdmNom/1/BILDE</href>

      <description>Binārie dati</description>

   </link>

</resource>


By indicating parameter bindata=embed in the request, the response will return the contents of a binary field in sub-elements size and data. The element size  contains data size in bytes and the element data contains field contents base64-encoded:

GET  http://localhost:81/rest/TNdmNom/1?bindata=embed  HTTP/1.1

Response

<resource xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance" >

   <description>Entītijas ieraksts</description>

   <entity xsi:schemaLocation="TNdmNom.xsd TNdmNom.xsd"  xmlns="TNdmNom.xsd">

      <NomBilde>

         <COUNTER>0</COUNTER>

         <PK_NOM>1</PK_NOM>

         <BILDE>

            <size>4566</size>

            <data>

/9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAkGBxAREBUUERAVFRAUFRUUFBYVFBgXFxQWG

…

EREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQP/Z

</data>

         </BILDE>

         <PIELIKUMS>1</PIELIKUMS>

      </NomBilde>

   </entity>

   <link>

      <href>/rest/TNdmNom/1/BILDE</href>

      <description>Binārie dati</description>

   </link>

</resource>

Creation of a new entity containing binary data

There are two ways to include binary data (BLOB) field contents in the request:

  1. include base64-encoded binary data in the respective field element;
  2. use multipart/form-data request and include the binary data in a separate part of the request.

Binary data included in the entity element

Binary data should be base64-encoded.

Request example

Creation of a stock item with image attached (XML)


POST  http://localhost:81/rest/TNdmNom  HTTP/1.1

Content-Type: application/xml

Content-Length: 3422

Host: localhost:81

Connection: Keep-Alive

 

<resource>

    <docType>ut.nnom1</docType>

    <entity>

     <KODS>ut.0000002</KODS>

      <NOSAUK>ut.0000002</NOSAUK>

     <PK_NOMGR>

         <href>/rest/TNdmNomGr/1</href>

      </PK_NOMGR>

      <PK_VIEN>

         <href>/rest/TNdmVien/1</href>

      </PK_VIEN>

     <NomBilde>

        <BILDE>

            <data>/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAIBAQIBAQICAgICAgICAwUDAwMDAwYEBAMFBwYHBwcGBwcICQsJCAgKCAcHCg0KCgsMDAwMBwkODw0MDgsMDAz/…

kCoAKKKKACiiigAooooA/v8ooooAKKKKACiiigD4A/4Ojv+UFHxz/7gH/qQaZX8gVFFABRRRQAUUUUAFFFFAH/2Q==</data>

        </BILDE>

     </NomBilde>

   </entity>

</resource>


/image/


Creation of a stock item with image attached (JSON)

POST http://localhost:81/rest/TNdmNom HTTP/1.1

Content-Type: application/json

Content-Length: 3422

Host: localhost:81

Connection: Keep-Alive

  

{

  "resource": {

    "docType": "ut.nnom1",

    "entity": {

      "KODS": "ut.0000002",

      "NOSAUK": "ut.0000002",

      "PK_NOMGR": { "href": "/rest/TNdmNomGr/1" },

      "PK_VIEN": { "href": "/rest/TNdmVien/1" },

      "NomBilde": {

        "BILDE": { "data": "/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAIBAQIBAQICAgICAgICAwUDAwMDAwYEBAMFBwYHBwcGBwcICQsJCAgKCAcHCg0KCgsMDAwMBwkODw0MDgsMDAz/…gAooooA+AP8Ag6O/5QUfHP8A7gH/AKkGmV/IFX9fv/B0d/ygo+Of/cA/9SDTK/kCoAKKKKACiiigAooooA/v8ooooAKKKKACiiigD4A/4Ojv+UFHxz/7gH/qQaZX8gVFFABRRRQAUUUUAFFFFAH/2Q=="  }

      }

    }

  }

}

multipart/form-data type request

With this type of request, the data to be sent are divided in several parts. A separate part of the request is formed for each parameter and binary data content. The Content-Disposition parameter name  of the respective header should contain the parameter name it refers to. For example, entity's parameter part should contain the following Content-Disposition  header:

Content-Disposition: form-data; name="entity"

Field values that contain binary data can be manipulated by indicating the respective field in the entity element and including the field data in a separate part of the request. Each field must have a separate part. The parameter name of the part's header Content-Disposition  should indicate full path to the field the part refers to. The path elements must be separated by a slash /. For example, a stock item image is stored in data item NomBilde, field BILDE. To indicate that a request part contains binary data of images, this part should have the following Content-Disposition header:

Content-Disposition: form-data; name="entity/NomBilde/BILDE"


Request sample

The below sample creates a new stock item. The newly created stock item will contain an image.

The request consists of request headers and three parts. Each part in turn consists of its headers and data.

The first part contains the value docType parameter

Content-Disposition: form-data; name="docType"

The second part contains entity data.

The third part contains the stock item’s image


Creation of a stock item with image attached (multipart/form-data with XML entity)

POST  http://localhost:81/rest/TNdmNom  HTTP/1.1

Content-Type: multipart/form-data; boundary="----=_Part_0_824329818.1423661296117"

MIME-Version: 1.0

Content-Length: 3267

Host: localhost:81

Connection: Keep-Alive

  

------=_Part_0_824329818.1423661296117

Content-Type: text/plain; charset=Cp1257

Content-Transfer-Encoding: binary

Content-Disposition: form-data; name="docType"

ut.nnom1

------=_Part_0_824329818.1423661296117

Content-Type: text/xml; charset=Cp1257; name=post-entity.xml

Content-Transfer-Encoding: binary

Content-Disposition: form-data; name="entity"; filename="post-entity.xml"

<entity>

 <KODS>ut.0000002</KODS>

  <NOSAUK>ut.0000002</NOSAUK>

 <PK_NOMGR>

     <href>/rest/TNdmNomGr/1</href>

  </PK_NOMGR>

  <PK_VIEN>

     <href>/rest/TNdmVien/1</href>

  </PK_VIEN>

 <NomBilde>

    <BILDE>

        <data/>

    </BILDE>

 </NomBilde>

</entity>

------=_Part_0_824329818.1423661296117

Content-Type: image/jpeg

Content-Transfer-Encoding: binary

Content-Disposition: form-data; name="entity/NomBilde/BILDE"; filename="post-NomBilde_BILDE.jpg"

 

(BINĀRIE DATI)

 

------=_Part_0_824329818.1423661296117--

  

It should be noted that a tag data  for the field to be modified needs to be present; otherwise the system will view it as an omitted field and will not modify its contents. For example, upon creating a new stock item and failing to indicate element entity/NomBilde/BILDE/data, image will NOT be attached to this item, even if a part entity/NomBilde/BILDE is present:


Creation of a stock item, image IS NOT saved

POST  http://localhost:81/rest/TNdmNom  HTTP/1.1

Content-Type: multipart/form-data; boundary="----=_Part_0_824329818.1423661296117"

MIME-Version: 1.0

Content-Length: 3267

Host: localhost:81

Connection: Keep-Alive

  

------=_Part_0_824329818.1423661296117

Content-Type: text/plain; charset=Cp1257

Content-Transfer-Encoding: binary

Content-Disposition: form-data; name="docType"

ut.nnom1

------=_Part_0_824329818.1423661296117

Content-Type: text/xml; charset=Cp1257; name=post-entity.xml

Content-Transfer-Encoding: binary

Content-Disposition: form-data; name="entity"; filename="post-entity.xml"

<entity>

 <KODS>ut.0000002</KODS>

 <NOSAUK>ut.0000002</NOSAUK>

 <PK_NOMGR>

     <href>/rest/TNdmNomGr/1</href>

  </PK_NOMGR>

  <PK_VIEN>

     <href>/rest/TNdmVien/1</href>

  </PK_VIEN>

 <!-- Nomenklatūra bez attēla, jo nav elementa NomBilde/BILDE/data-->

</entity>

------=_Part_0_824329818.1423661296117

Content-Type: image/jpeg

Content-Transfer-Encoding: binary

Content-Disposition: form-data; name="entity/NomBilde/BILDE"; filename="post-NomBilde_BILDE.jpg"

 

(BINĀRIE DATI)

  

------=_Part_0_824329818.1423661296117--


File attachments to documents

Viewing the files

Information about attached files is available in sub-resource attachments of the entity root resource.

Request

GET http://localhost:81/rest/TNdmNom/99143/attachments HTTP/1.1


Response

<resource xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance" >

   <description>Pievienotie faili</description>

   <title>Pievienotie faili</title>

   <collection xsi:schemaLocation="TNdmNomAttachmentSL.xsd TNdmNomAttachmentSL.xsd"  xmlns="TNdmNomAttachmentSL.xsd">

      <metadata>

        <!-- metadata (omitted in this example) -->

      </metadata>

      <row>

         <MULTISEL>0</MULTISEL>

         <ATTC>

            <PK_OBJ>99143</PK_OBJ>

            <PAMV_ID>2015</PAMV_ID>

            <FILENAME>test-00001.jpg</FILENAME>

            <COUNTER>0</COUNTER>

            <PK_ATTACHMENT>

               <href>/rest/TNdmNom/99143/attachments/1792</href>

            </PK_ATTACHMENT>

            <STOR>

               <PK_STORAGE>

                  <href>/rest/TdmStorageBL/27</href>

               </PK_STORAGE>

               <CONF>

                  <size>21</size>

                  <href>/rest/TNdmNom/99143/attachments/1792/CONF</href>

               </CONF>

               <VEIDS>0</VEIDS>

               <APRAKSTS>\\fs\kkus_repo</APRAKSTS>

               <STATUSS>0</STATUSS>

            </STOR>

         </ATTC>

      </row>

      <link>

         <href>/rest/TNdmNom/99143/attachments/TNdmNomAttachmentSL.xsd</href>

         <description>XSD shēma</description>

      </link>

      <link>

         <href>/rest/TNdmNom/99143/attachments/TdmAttachmentBL.xsd</href>

         <description>Entītijas datu XSD shēma</description>

      </link>

      <link>

         <href>/rest/TNdmNom/99143/attachments/{pk}</href>

         <description>Pievienotais fails</description>

      </link>

   </collection>

</resource> 


Information about a particular file is available in sub-resource {pk} of attachments resource. Request parameter bindata  determines whether the element FILSIZE will provide a link to the resource with the file contents or contain base64-encoded content of the file. In both cases the link is available as a separate element link at the same level as the entity element.


Request

GET /rest/TNdmNom/99143/attachments/1792 HTTP/1.1


Response

<resource xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance" >

   <description>Pievienotais fails</description>

   <entity xsi:schemaLocation="TdmAttachmentBL.xsd TdmAttachmentBL.xsd"  xmlns="TdmAttachmentBL.xsd">

      <COUNTER>0</COUNTER>

      <PK_ATTACHMENT>

         <href rel="self">/rest/TNdmNom/99143/attachments/1792</href>

      </PK_ATTACHMENT>

      <PK_OBJ>99143</PK_OBJ>

      <PK_STORAGE>

         <href>/rest/TdmStorageBL/27</href>

      </PK_STORAGE>

      <PAMV_ID>2015</PAMV_ID>

      <FILEID>test-00001.jpg</FILEID>

      <FILENAME>test-00001.jpg</FILENAME>

      <AUTHOR>File Author</AUTHOR>

      <CREATED>2015-01-01T10:15:54.000+02:00</CREATED>

      <KOMENTARS/>

      <FILSIZE>

         <size>2287</size>

         <href>/rest/TNdmNom/99143/attachments/1792/test-00001.jpg</href>

      </FILSIZE>

      <PK_REPNOM>

         <href>/rest/TdmRDRepNomBL/0</href>

      </PK_REPNOM>

      <PK_RPDGRP>0</PK_RPDGRP>

   </entity>

   <link>

      <href>/rest/TNdmNom/99143/attachments/1792/test-00001.jpg</href>

      <description>Binārie dati</description>

   </link>

</resource>


Embedded file (base64-encoded)

Request

GET /rest/TNdmNom/99143/attachments/1792?bindata=embed HTTP/1.1


Response

<resource xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance" >

   <description>Pievienotais fails</description>

   <entity xsi:schemaLocation="TdmAttachmentBL.xsd TdmAttachmentBL.xsd"  xmlns="TdmAttachmentBL.xsd">

      <COUNTER>0</COUNTER>

      <PK_ATTACHMENT>

         <href rel="self">/rest/TNdmNom/99143/attachments/1792</href>

      </PK_ATTACHMENT>

      <PK_OBJ>99143</PK_OBJ>

      <PK_STORAGE>

         <href>/rest/TdmStorageBL/27</href>

      </PK_STORAGE>

      <PAMV_ID>2015</PAMV_ID>

      <FILEID>test-00001.jpg</FILEID>

      <FILENAME>test-00001.jpg</FILENAME>

      <AUTHOR>File Author</AUTHOR>

      <CREATED>2015-01-01T10:15:54.000+02:00</CREATED>

      <KOMENTARS/>

      <FILSIZE>

         <size>2287</size>

         <data>/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQH/…+NB9s9bTeJj7/AMeuL9gOf5/98ebdlZE2x2xwrZ/DKbANvqIHHcWohmjg14MLY/PJ8SDjZu8ptia/96YaQ5808v2nKjUa1siAABAFhGIVhb/qqIaIhoib9P5/T/OiJzRE36fz+n+dETmiIaIv/9k=</data>

      </FILSIZE>

      <PK_REPNOM>

         <href>/rest/TdmRDRepNomBL/0</href>

      </PK_REPNOM>

      <PK_RPDGRP>0</PK_RPDGRP>

   </entity>

   <link>

      <href>/rest/TNdmNom/99143/attachments/1792/test-00001.jpg</href>

      <description>Binārie dati</description>

   </link>

</resource>

Adding files

To create and attach a file to the entity, a POST request should be made to sub-resource attachments of this entity. The file content should be indicated in field FILSIZE, in the same way any binary data is indicated (see above).


multipart/form-data request example

POST  http://localhost:81/rest/TNdmNom/99143/attachments  HTTP/1.1

Content-Type: multipart/form-data; boundary="----=_Part_0_910410645.1423741572728"

MIME-Version: 1.0

Content-Length: 157349

Connection: Keep-Alive

 

------=_Part_0_910410645.1423741572728

Content-Type: text/xml; charset=Cp1257; name=post-entity.xml

Content-Transfer-Encoding: binary

Content-Disposition: form-data; name="entity"; filename="post-entity.xml"

<entity>

  <PK_STORAGE>

     <href>/rest/TdmStorageBL/27</href>

  </PK_STORAGE>

  <FILENAME>test-00002.jpg</FILENAME>

  <AUTHOR>File Author</AUTHOR>

  <CREATED>2015-01-01T10:15:54.000+02:00</CREATED>

  <FILSIZE>

       <data/>

  </FILSIZE>

</entity>

------=_Part_0_910410645.1423741572728

Content-Type: image/jpeg; name=post-FILSIZE.jpg

Content-Transfer-Encoding: binary

Content-Disposition: form-data; name="entity/FILSIZE"; filename="post-FILSIZE.jpg"

 (FAILA SATURS)

------=_Part_0_910410645.1423741572728--

Deletion of a file

To delete an attached file, a DELETE request should be made to the resource of the attached file. If the file is successfully deleted, the response will contain status code 204.


Request

DELETE  http://localhost:81/rest/TNdmNom/99143/attachments/1793 HTTP/1.1


Response

HTTP/1.1 204 No Content

Content-Length: 0

Date: Thu, 12 Feb 2015 12:01:46 GMT

Response formats: XML, JSON

REST interface allows responses to be received in one of two formats: either XML, or JSON. The response format can be indicated in the Accept header. XML is the default.

Accept value

Response format

application/xml

XML

application/json

JSON


By default, the response does not include whitespace characters. This reduces the amount of data to be sent. If the response needs to be more human-readable retaining whitespaces and carriage return characters, the parameter prettyprint=true can be used.


The sample below shows a request with response format JSON, retaining whitespaces:


Request

GET /rest/TNdmAdr/555?prettyprint=true HTTP/1.1

Accept: application/json


Response

HTTP/1.1 200 OK

Connection: keep-alive

Content-Type: application/json; charset=UTF-8

Content-Length: 948

 

{

   "description": "Entītijas ieraksts",

   "entity":    {

      "COUNTER": 0,

      "ADRESE": "Kronvalda bulv.3/5, Rīga, LV-1010, Latvija",

      "KONTAKTP": null,

      "KONTAKTP_LNG1": null,

      "KONTAKTP_LNG2": null,

      "KONTAKTP_LNG3": null,

      "LIC_NR": null,

      "LIC_DAT": null,

      "PIEZIMES": null,

      "PK_ADRESE": {

        "href": "/rest/TNdmAdr/555",

        "rel": "self"

      },

      "PK_KLIENTS": {"href": "/rest/TDdmCustomer/-11"},

      "STATUSS": 1,

      "PK_REGIONS": null,

      "PK_REISS": null,

      "ADRESE1": null,

      "ADRESE1_LNG1": null,

      "ADRESE1_LNG2": null,

      "ADRESE1_LNG3": null,

      "ADRESE2": null,

      "ADRESE2_LNG1": null,

      "ADRESE2_LNG2": null,

      "ADRESE2_LNG3": null,

      "ADRESE3": null,

      "ADRESE3_LNG1": null,

      "ADRESE3_LNG2": null,

      "ADRESE3_LNG3": null,

      "PASTA_IND": null,

      "PASTA_IND_LNG1": null,

      "PASTA_IND_LNG2": null,

      "PASTA_IND_LNG3": null,

      "PK_VALSTS": {"href": "/rest/TdmBLDValsts/3"},

      "LEG_ADR": 2,

      "POST_ADR": null,

      "KILOMETRI": null,

      "PK_KLKPERS": null,

      "PK_ADR2": null,

      "PRIMADR": null

   },

   "link": [   {

      "href": "/rest/TNdmAdr/555/print",

      "description": "Izdrukas"

   }]

}

Authentication

To use REST API, user context must be supplied, providing web user credentials. Web users are administered by Horizon Sistēma → Administrēt → WEB lietotāji. Without authentication only the root entry point is available (listing all first-level resources) and the resource /rest/global. All authentication methods identifies a Web user to provide further authorization.


REST API resources:


Resource

Explanation

/rest

The entry point to REST API. Lists all first-level resources available. Authentication is not needed.

/rest/global

Horizon system information available without authentication. Provides version info, and allows to download FTG interface client library. Authentication is not needed.

/rest/system

Horizon system information. Provides access to the system configuration parameters: Sistēma → Uzstādījumi → Uzskaites parametri.

/rest/user

Information about the user – list of organizations (for a given Horizon installation) the user may log on to, Horizon objects linked to the user, and option to switch the active organisation for the session.

/rest/TDdmCustomer

Any entity or collection resource. Customer (TDdmCustomer) resource in this example.


Horizon can be used in multi-tenant mode, keeping data on several organizations. When logging in the user chooses the organization to work with. Organizations the Web user may connect to are specified using Horizon GUI. One is indicated as the default.

Upon connection to REST API, a work session is created connected to the default organization. After that, the session can be switched to use another organization. Please note that primary key values used as resources are valid only in the context of the organization they belong to. Data of other organizations will contain other primary key values. To identify the current organization, the header of each response includes the name and the key of the active organization.

Organization: 2, "SIA Kalns"

Authentication methods

Authentication methods supported by REST API:

Upon authentication, a user session is created in the scope of which further communication with FTG server takes place.

Switching the active organisation

After connection to FTG server, list of organizations the web user will be able to connect to can be read using GET request to resource /rest/user/organization


REST request

GET /rest/user/organization HTTP/1.1

Host: localhost:81

Accept: application/xml

Cookie: IDHTTPSESSIONID=KFkMKGN8nACndAC


The received data contains keys and names of available organizations.


REST response

HTTP/1.1 200 OK

Content-Type: application/xml; charset=UTF-8

Organization: 2, "SIA Kalns"

Date: Wed, 10 Jun 2015 10:34:59 GMT

 

<?xml version="1.0" encoding="UTF-8"  standalone="no"?>

<resource xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance" >

    <description>Lietotājam atļautas firmas</description>

    <link>

        <href>/rest/user/organization/change</href>

        <description>Pārslēgt sesijas aktīvo firmu</description>

    </link>

    <results>

        <collection>

            <row>

                <PK_FIRMA>2</PK_FIRMA>

                <IS_DEFAULT>true</IS_DEFAULT>

                <KODS>Izstrade</KODS>

                <NOSAUK>SIA Kalns</NOSAUK>

            </row>

            <row>

                <PK_FIRMA>4</PK_FIRMA>

                <IS_DEFAULT>false</IS_DEFAULT>

                <KODS>Tests</KODS>

                <NOSAUK>SIA Leja</NOSAUK>

            </row>

        </collection>

    </results>

</resource>


Received data in the example show that by default the connection has been made to identifier 2 "SIA Kalns", but a company with identifier 4 "SIA Leja" is also accessible.


The active organisation is switched by sending POST request to resource /rest/user/organization/change.


REST request

POST /rest/user/organization/change HTTP/1.1

Host: localhost:81

Content-Type: application/xml

Cookie: IDHTTPSESSIONID=KFkMKGN8nACndAC

 

<resource>

  <PK_FIRMA>4</PK_FIRMA>

</resource>


Further requests during the same session will apply to organisation 4 "SIA Leja".

HTTP Basic Authentication

Horizon REST API supports HTTP Basic Authentication.


Example for authentication of user FTGCLIENT with password ftgclient.


User name and password are merged in one data unit separated by ":"

FTGCLIENT:ftgclient


The value obtained must be Base64-encoded

RlRHQ0xJRU5UOmZ0Z2NsaWVudA==


Full authorization header

Authorization: Basic RlRHQ0xJRU5UOmZ0Z2NsaWVudA==

Authentication process

Step 1 - addressing the resource


REST request. Authorization data are not supplied.

GET /rest/user HTTP/1.1

Host: localhost:81


REST response is error - 401 Unauthorized because resource is not accessible without authentication. The response includes information that the server supports authentication method Basic.

HTTP/1.1 401 Unauthorized

Content-Type: application/xml; charset=UTF-8

Date: Tue, 02 Jun 2015 08:29:52 GMT

WWW-Authenticate: Basic realm="Horizon REST API", WebUser realm="Horizon REST API"


<?xml version="1.0" encoding="UTF-8" standalone="no"?>

<error>

  <class>ERestException</class>

  <message>Nepieciešama autentifikācijas informācija!</message>

</error>


Step 2 - addressing the resource by indicating the user name and password


REST request. The request includes authorisation header in compliance with HTTP Basic authentication.

GET /rest/user HTTP/1.1

Host: localhost:81

Authorization: Basic RlRHQ0xJRU5UOmZ0Z2NsaWVudA==


REST response successful - 200 OK. The data have been received.

HTTP/1.1 200 OK

Content-Type: application/xml; charset=UTF-8

Date: Tue, 02 Jun 2015 08:29:58 GMT

Organization: 2, "Programmas izstrade - MSSQL"

 

<?xml version="1.0" encoding="UTF-8" standalone="no"?>

<resource xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  <description>Lietotāja resursi</description>

  <link>

    <href>/rest/user/organization</href>

    <description>Lietotājam atļautas firmas</description>

  </link>

  <link>

    <href>/rest/user/changePassword</href>

    <description>ChangePassword</description>

  </link>

</resource>

Horizon specific authentication

Horizon ensures several specific authentication scenarios. All these scenarios are implemented by indicating one or more parameters using the same authentication method WebUser.

        Authorisation: WebUser

        Authorization: WebUser key1="value1", key2="value2"


Supported authentication scenarios:

Certification-signed identity

Horizon supports identity forwarding without specifying a password. Authentication header must contain web user's name and signature. User identification by personal ID or e-mail is also available, depending on settings.


Parameters to be indicated in the authorisation header.


Parameter

Explanation

login

Indicates web user's login name

timestamp

Indicates the time of connection in UTC time zone specified in seconds, starting from 1 January 1970

signature

Signature calculated on both previous data units. FTG server tries to verify the signature using all certificates registered in Horizon’s certificate storage.


Header example.

Authorization: WebUser login="lietotājs", timestamp="laiks", signature="paraksts"


Example

Signature, when user FTGCLIENT signs on 2015-06-01 14:46:07.

User name.

        FTGCLIENT

Time value of the signature moment (2015-06-01 14:46:07).

        1433159167

Data unit to be signed.

        FTGCLIENT1433159167

Data unit to be signed as a byte array in UTF8

46 54 47 43 4C 49 45 4E 54 31 34 33 33 31 35 39

31 36 37

Data unit signature (SHA256 with RSA).

0A 32 94 42 5C 87 35 2D B0 81 CF B5 EE 8C B1 4C

14 47 64 D7 CE 1C 9C EE 67 C1 0A D4 14 90 84 5D

D4 D1 8D 09 FF BF 46 BD A7 6E 75 87 04 D3 1B 36

07 17 8B 91 78 A9 01 AC 58 BF 3E 2A 5B D7 33 C0

B4 FC 16 B6 E6 A9 D1 54 9F B9 20 38 FF 54 F9 96

ED 90 FE 97 49 59 63 19 65 6D EF 72 F7 B9 00 A2

72 E7 EA B1 1D 90 4B 3F 69 8C 52 17 1A D6 C0 7D

38 5F C3 32 47 58 61 B3 A2 4E 5C BE 96 15 5F 6B

8A B0 B4 5C E4 DE 0E 3A A6 01 80 FD 5D FC 68 AF

A0 19 99 DE EA 07 0E A8 07 31 C6 87 8B A6 AF E4

79 FE D1 95 E3 97 B8 B9 B1 FD 9F F1 F5 FB 0F CF

1E 1F D8 C7 69 53 DD FD 3A 5B 6B B6 86 38 3C 49

2B D1 06 F2 71 48 E3 D2 85 E3 37 88 19 EA 26 78

E8 3C D6 D4 6C 47 DF D3 6B ED 44 7E A7 A9 1C E6

90 32 9A 01 0D A4 97 CF B8 1C A7 1F AB 30 CC CB

58 A9 0D 3F 14 BD 15 8C 56 E4 5E C7 49 4D E6 B4

Data unit signature Base64-encoded.

CjKUQlyHNS2wgc+17oyxTBRHZNfOHJzuZ8EK1BSQhF3U0Y0J/79GvadudYcE0xs2

BxeLkXipAaxYvz4qW9czwLT8FrbmqdFUn7kgOP9U+ZbtkP6XSVljGWVt73L3uQCi

cufqsR2QSz9pjFIXGtbAfThfwzJHWGGzok5cvpYVX2uKsLRc5N4OOqYBgP1d/Giv

oBmZ3uoHDqgHMcaHi6av5Hn+0ZXjl7i5sf2f8fX7D88eH9jHaVPd/Tpba7aGODxJ

K9EG8nFI49KF4zeIGeomeOg81tRsR9/Ta+1EfqepHOaQMpoBDaSXz7gcpx+rMMzL

WKkNPxS9FYxW5F7HSU3mtA==

REST request.

GET /rest/user HTTP/1.1

Accept: application/xml, text/xml, application/xhtml+xml, application/atom+xml

Authorization: WebUser login="FTGCLIENT", timestamp="1433159167", signature="CjKUQlyHNS2wgc+17oyxTBRHZNfOHJzuZ8EK1BSQhF3U0Y0J/79GvadudYcE0xs2BxeLkXipAaxYvz4qW9czwLT8FrbmqdFUn7kgOP9U+ZbtkP6XSVljGWVt73L3uQCicufqsR2QSz9pjFIXGtbAfThfwzJHWGGzok5cvpYVX2uKsLRc5N4OOqYBgP1d/GivoBmZ3uoHDqgHMcaHi6av5Hn+0ZXjl7i5sf2f8fX7D88eH9jHaVPd/Tpba7aGODxJK9EG8nFI49KF4zeIGeomeOg81tRsR9/Ta+1EfqepHOaQMpoBDaSXz7gcpx+rMMzLWKkNPxS9FYxW5F7HSU3mtA=="

Host: localhost:81

Proxy-Connection: Keep-Alive

REST response.

HTTP/1.1 200 OK

Connection: keep-alive

Content-Type: application/xml; charset=UTF-8

Content-Length: 372

Date: Mon, 01 Jun 2015 11:46:11 GMT

Organization: 2, "Programmas izstrade - MSSQL"

Set-Cookie: IDHTTPSESSIONID=N6fdHW6XOdWR9cS; Path=/


<?xml version="1.0" encoding="UTF-8" standalone="no"?>

<resource xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><description>Lietotāja resursi</description><link><href>/rest/user/organization</href><description>Lietotājam atļautas firmas</description></link><link><href>/rest/user/changePassword</href><description>ChangePassword</description></link></resource>

Private key used for test purposes (PKCS #8 plain).

-----BEGIN PRIVATE KEY-----

MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQC3S70Qdl91lW+F

oML1o80KsyQ/WkyO5/HhKvluMUIw+2r8LW/pMM4lZP+zliSubcTQ2+fxHDy+rNzk

HuZaTw5QiusifyOg32IGInU57cKoAdxXhjZ7vQl2678GqIRoPrd5XMRC2R0swz1n

M4LjavS3Hd7oPNvbD7B2uIn5cDoPVGERaY6kctPQALDluRh6RqNV4fgl3G9bWvAv

oM3sNq5ezJBArZK60Ukp94QqO67rKMRdJcuRJtknCR1nP36Tke4OJR75zBF+UuOT

TzPb7J7cqqyeusEFfl3gNkSsM4udmwv2ZPDz0rFptIsOT3Nnx6aZNfgoVD1rMjn9

K56sMJ+BAgMBAAECggEAIGu9HVRSvjGYcEJnOZungOT+3FXUhNJx7inzxJHh61gN

LF29FboUPHkI4XMFOfUggvDirbsY44Ef8RmmFQM2vPhVbtyeKK5aYEtoAL8VVzI9

Dx4mNOzS5737I+pawTWWrljCPjC5AFnoWoC5/g/FCT63Vsys9qpnxBgQD5bSLjOo

/7G9T0kWu0rI7Ta0/nXBC1Nr4LMwDkZ0VO4DCj5P5uwyE+jJR9DPC5KfEozTYLeX

yXqeOqt79Go20aqsbTLGCdatTFzBiP1FxIKdXHG03phioXWa0XQcjIiYJiUb6MWV

qBSKnulUays+qavOyxgNm9qaWBgZ+PV2nWTEG6CToQKBgQD9yPGifqhQuGK9POWM

of9DDKiv6QVRR9Y6bNU9ow0wN1BhqA/UuLvvC3IDj6CpETOiyVGwN+uMiKf/lT04

DPT1JFivtMFSqfqliIMN4tBVszcA/xsALFWDc0Lgyi/9lLc9Dzof+pTFRqkdjLrL

QxVuE485NNNrKK119Nq1yaic4wKBgQC45UtKSsBPDbCWBcPGCHMzvY2Ss/BdeEFW

/Tjs22r9xgwmHQ7gF8SjKlJiocNZpiBnsXTi33c41V2C9/XzUL7SeSdDkG+sJuCp

a5srHg5MsFB8O/mV7/lfRRXqLsAyY1BSC93nVbtJf3PNJ5lqr2kP+kBQpbZ8BQx1

4TJP4HwDSwKBgF8cHLqqPwgpYg/Lr7eZyqFlMB7k9HI2uumgefYkkj+8qyo+Iti0

9vGqV2tQO4TBBpn+WtfwzR0Y5eUaGBxWdsMcgQQweLczLtU0qPDeTPehN37vHD5f

XxjpbGn0PDILtvRyLXVoorKgPabuY97jYDelqupkistBLmjjf8fbMI7DAoGAd2DE

beE5rVD/dL2gG5qVFxEJ+XBof1EHjuzL9lHtEJDwgyM72YA/G8JVkw0yng1e2tR+

zYTO60kHqWoDyOeXbTmAGmWFVLd9UqYBd6NeRDGKpcvrZ92bOuHWNm+c9GufDnpO

+fAmjlvWHt20dmdvBDvljqyP2B9CXlHaNCySpWUCgYAj8Nfr8+2a33rhEZCPFvpi

a7NZl/AoIwNsdBRSQli9uifO33QlcVaZkCu7BriAFw5Es5lbUmrUxZRaT01TvyEQ

ErYtKpiOeEQoC3a6r9ublFwWM0l9DfDuRjEYlxVkAJ7963DFdhK+koLA0BUQtMu8

vR84Rha/i9jSssMQMySOGA==

-----END PRIVATE KEY-----

Certificate for this private key (X.509).

-----BEGIN CERTIFICATE-----

MIIDRTCCAi2gAwIBAgIES5Pu0DANBgkqhkiG9w0BAQsFADBTMQswCQYDVQQGEwJM

VjENMAsGA1UECBMEUmlnYTENMAsGA1UEBxMEUmlnYTEOMAwGA1UEChMFVmlzbWEx

FjAUBgNVBAMTDXRlc3QudmlzbWEubHYwHhcNMTUwNTE5MTQxMzM5WhcNMjUwMjE1

MTQxMzM5WjBTMQswCQYDVQQGEwJMVjENMAsGA1UECBMEUmlnYTENMAsGA1UEBxME

UmlnYTEOMAwGA1UEChMFVmlzbWExFjAUBgNVBAMTDXRlc3QudmlzbWEubHYwggEi

MA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC3S70Qdl91lW+FoML1o80KsyQ/

WkyO5/HhKvluMUIw+2r8LW/pMM4lZP+zliSubcTQ2+fxHDy+rNzkHuZaTw5Qiusi

fyOg32IGInU57cKoAdxXhjZ7vQl2678GqIRoPrd5XMRC2R0swz1nM4LjavS3Hd7o

PNvbD7B2uIn5cDoPVGERaY6kctPQALDluRh6RqNV4fgl3G9bWvAvoM3sNq5ezJBA

rZK60Ukp94QqO67rKMRdJcuRJtknCR1nP36Tke4OJR75zBF+UuOTTzPb7J7cqqye

usEFfl3gNkSsM4udmwv2ZPDz0rFptIsOT3Nnx6aZNfgoVD1rMjn9K56sMJ+BAgMB

AAGjITAfMB0GA1UdDgQWBBRDa9ZMiYkhDRuiyFUgJSI56IrjkDANBgkqhkiG9w0B

AQsFAAOCAQEAkd929cUJ2DI73lUsZQGMTE2lEBcWzKzMotB3o7vb24eqvX4HJYEf

9TtBWdJsJj4ix7i+bagLo8vgoSGv6hTE4HqX6EhZ5NT+gXZ8pCZWT75yFYiA/4Uj

AXObq8z/l9YCx3lkysqv5/QFSsCQTEuk5V8iUOuXSU2fau85n1nAd6eLsJzF95g1

362HdCCrp4q7QU2z4OjtYyq5adCE5A/7G1G+kMsRaSMjipe99XdZYp8r41Awu/pL

745+SaIWJ2GTPKT1oa9B1xWhYnpRH2zuxy7sf/MdGhW6MG8WYlA2k8lJRhJ8xziA

zBxWKriVDlqQIe4zRcJwcLXDuai+g/RZwg==

-----END CERTIFICATE-----

Import certificate in Horizon Sistēma → Administrēt → Sertifikātu glabātuve

Application identification

Horizon allows to identify the application as well as the user connected to FTG server. The solution is based on the fact that both parties know the secret password used to calculate hash function using HMAC-SHA1 algorithm, thus obtaining an application signature.


Parameters to be indicated in the authorization header.

 

Parameter

Explanation

context

Indicates the application identifier

timestamp

Indicates the connection moment in UTC time zone, in seconds since 1 January 1970

context_signature

Signature of the value that includes both previous data units. To obtain the signature, HMAC-SHA1 algorithm is used.


Example of header. Together with the application identification, a user identification method should be used; the example shows only parameters for the application identification.

Authorization: WebUser timestamp="laiks", context="pielietojums", context_signature="paraksts"


Example

Example is created for application Test  by signing on 2015-06-01 18:07:17. Horizon has a built-in test application that can be used to test application signature. Test application cannot be used to work with Horizon entities or collections.

Application identifier.

Test

Secret password for the application.

kAcSOqF21Fu85e7zjz7ZN2U4ZRhfV3WpwPAoE3Z7kBw

Time value of the signature moment.

1433171237

Data unit to be signed

Test1433171237

Hash value obtained by HMAC-SHA1 algorithm.

4F 3B A1 B6 D0 0E 0C 9E 2E 5A FC FC 0B 12 51 B4

66 CC 98 7F

 Signature value in Base64-encoding

TzuhttAODJ4uWvz8CxJRtGbMmH8=

 REST request

GET /rest/user HTTP/1.1

Accept: application/xml, text/xml, application/xhtml+xml, application/atom+xml

Authorization: WebUser basic="RlRHQ0xJRU5UOmZ0Z2NsaWVudA==", timestamp="1433171237", context="Test", context_signature="TzuhttAODJ4uWvz8CxJRtGbMmH8="

Host: localhost:81

Proxy-Connection: Keep-Alive

 REST response

HTTP/1.1 200 OK

Connection: keep-alive

Content-Type: application/xml; charset=UTF-8

Content-Length: 372

Date: Mon, 01 Jun 2015 15:07:17 GMT

Organization: 2, "Programmas izstrade - MSSQL"

Set-Cookie: IDHTTPSESSIONID=wact9ARozhwgasE; Path=/


<?xml version="1.0" encoding="UTF-8" standalone="no"?>

<resource xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><description>Lietotāja resursi</description><link><href>/rest/user/organization</href><description>Lietotājam atļautas firmas</description></link><link><href>/rest/user/changePassword</href><description>ChangePassword</description></link></resource>

Authentication with user name and password

Horizon authentication allows to supply user name and password like it is done in HTTP Basic authentication. Depending on the authentication settings personal ID or e-mail can be used for user identification.


Parameters to be indicated in the authorization header.


Parameter

Explanation

Basic

User name and password Base64-encoded


Example of header value

Authorization: WebUser basic="lietotājs,parole"


Example

Authentication example for user FTGCLIENT.

User name.

FTGCLIENT

 User password.

ftgclient

 Data unit for the user authentication.

FTGCLIENT:ftgclient

Data unit for the user authentication in Base64-encoded.

RlRHQ0xJRU5UOmZ0Z2NsaWVudA==

REST request.

GET /rest/user HTTP/1.1

Accept: application/xml, text/xml, application/xhtml+xml, application/atom+xml

Authorization: WebUser basic="RlRHQ0xJRU5UOmZ0Z2NsaWVudA=="

Host: localhost:81

Proxy-Connection: Keep-Alive

 REST response.

HTTP/1.1 200 OK

Connection: keep-alive

Content-Type: application/xml; charset=UTF-8

Content-Length: 372

Date: Mon, 01 Jun 2015 15:07:17 GMT

Organization: 2, "Programmas izstrade - MSSQL"

Set-Cookie: IDHTTPSESSIONID=wact9ARozhwgasE; Path=/


<?xml version="1.0" encoding="UTF-8" standalone="no"?>

<resource xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><description>Lietotāja resursi</description><link><href>/rest/user/organization</href><description>Lietotājam atļautas firmas</description></link><link><href>/rest/user/changePassword</href><description>ChangePassword</description></link></resource>

Adding a Web user

Horizon WEB users are configured using Horizon GUI in WEB user list.

Horizon WEB users can be linked to employees of an organization, as well as other persons defined for this organization.

For each WEB user, login credentials are defined – user name and password.

WEB user list in Horizon GUI is available at: Sistēma → Administrēt → WEB lietotāji.

A new WEB user can be added:

- manually, by pressing button Jauns in the WEB user list and filling in the entry form of a WEB user as described below.

- automatically by generating from Horizon GUI Person list (Pamatdati → Personāla uzskaite → Personas kartiņas) - select items (persons) and pick menu item Darbības->Veikt operāciju → Izveidot WEB lietotājus from list’s toolbar.

Manual creation

To add a new user, at least the mandatory fields should be filled in:


Login name. To use Windows domain authorisation, WEB user login name should be the same as domain user name and must be entered with the domain prefix. For example, by indicating the login name "DOMAIN\LIETOTAJS", "DOMAIN" is Windows domain and "LIETOTAJS" is the user name. The system does not support a user name formed as e-mail address.


Horizon user - Horizon user linked to the WEB user (RVS Horizon menu Sistēma → Administrēt → Lietotāji). Linked Horizon user determines the WEB user's role and data access permissions. One Horizon user can serve as a role for several WEB users. If needed, new Horizon users having the necessary permissions can be created.


Other information can be indicated, if necessary (see Horizon WEB help for details).


WEB user is authorised by using the login name and password and pressing button Pievienoties (Connect).


If a user connects to Horizon WEB using Windows authentication, the user's login name <DOMAIN\LIETOTAJS> should be indicated in Horizon WEB login screens and button Windows authentication pressed. If user is identified, he/she is given access to the system.


Upon remote (outside domain) connection to Horizon WEB (if security regulations allow it), both user's login name <DOMAIN\LIETOTAJS> and password must be entered in Horizon WEB login screen..


WEB users cannot be deleted, only disabled using checkbox Aktīvs (Active). 

Automatic generation of a Web user


WEB users can be created automatically by using an option in Horizon GUI Person list (Pamatdati → Personāla uzskaite → Personas kartiņas).


Rows the operation is to be applied to should be selected and menu Darbības (Operations)  -> Veikt operāciju → Izveidot WEB lietotājus.


Window "Veidot WEB lietotājus" is opened.


 


The field Horizon user should be specified. List of Horizon users is to be found at Horizon GUI menu Sistēma → Administrēt → Lietotāji.


The linked Horizon user sets WEB user's role and access permissions.


To allow a WEB user/users to use Windows domain authorization, checkbox Prefikss should be checked and domain prefix DOMAIN\ should be indicated in the field next to it. The newly created login names made in form "DOMAIN\LIETOTAJS" might have to be manually adjusted afterwards.

By pressing button Labi (Ok), WEB users are created, which can be accessed in list of Horizon WEB users.


If Windows authentication is not used, then for all generated users passwords has to be set manually.

Error processing

Each response contains a response code. It could be any of the success codes, for example, 200 OK or 201 Created. Or it could be one of error codes, for example, 500 Internal Server Error or 400 Bad Request. In this case the response body will contain more information about the error.


See the example below.

An unsuccessful update request, failing to specify correct value of the update counter.

POST /rest/TDdmCustomer/18938 HTTP/1.1

Content-Type: application/xml;charset=UTF-8

 

<resource>

  <entity>

    <COUNTER>0</COUNTER>

    <PK_KLIENTS>

    <href rel="self">/rest/TDdmCustomer/189389</href>

    </PK_KLIENTS>

    <REG_NR>000000001</REG_NR>

  </entity>

</resource>


Failed update response, containing the message to the effect, that record has been changed by another user.

HTTP/1.1 500 Internal Server Error

Content-Type: application/xml; charset=UTF-8

Date: Mon, 28 Jul 2014 10:03:20 GMT

Organization: 2, "SIA Kalns"

 

<?xml version="1.0" encoding="UTF-8"  standalone="no"?>

<error>

  <class>Exception</class>

  <message>Ieraksts ir mainījies kopš nolasīšanas.

Pārlasiet to, lai redzētu izmaiņas!</message>

</error>

Advice and suggestions

Entry creation - two options

REST interface offers the following two options to create new entries:


1.        Use a template resource (Creation of a new entity on the basis of a template (document types) ). The method is used if the default values need to be known before POST for some purpose. The initial data is received from the template, fields filled in and POST request made.

2.        Make an entry in a single request (Creation of a new entity ) by specifying the document type code and the field values. The method is best used for bulk-insert.

Document types

Although REST interface allows using any template (document type), it is strongly recommended to create and use a dedicated template. Usually business users and builders of the integration code agree on templates and codes to be used. The REST API allows to specify the user assigned code of the template.

Viewing primary keys in Horizon GUI

In REST API entities are addressed using their primary key. It is useful to see primary key values in Horizon GUI. When adding command line parameter -s when starting Horizon, the system adds field "Sistēmas ID" to the available columns in Horizon GUI list layout windows.


FTG20.exe -s

How to find out column labels of a collection resource

To find out the field labels, first must be located in the respective Horizon GUI list – field name should be noted, as well as the branch in the hierarchical view the field belongs to.


For example, stock item group name is obtained from "Nomenklatūru grupa" and the field name is "Nosaukums"



The available fields for any list can be viewed in schema resource. For example, /rest/TNdmNomSar/TNdmNomSar.xsd . Find "Nomenklatūru grupa" and note the code – G in this example

The fields are defined in the namespace TNdmNomGr, structure TNdmNomGrStructure. The location of the schema can be found at the beginning of the XSD data.


It shows the resource /rest/TNdmNomGr/TNdmNomGr.xsd


Find the field list in TNdmNomGrStructure and establish that the field name is NOSAUK

Append G.NOSAUK to the columns to be retrieved, for example, /rest/TNdmNomSar/query?columns=N.KODS,N.NOSAUK,G.NOSAUK


See the response below. Names for fields in any other list are searched for in the same manner.


Creation of a simple entity (client address)

Compact insert (POST to /rest/TNdmAdr/)

Request

POST  http://localhost:81/rest/TNdmAdr/  HTTP/1.1

Accept-Encoding: gzip,deflate

Content-Type: application/xml;charset=UTF-8

Content-Length: 140

Host: dino.fms.lan:81

Connection: Keep-Alive

User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

Cookie: IDHTTPSESSIONID=84A213RxnFcscgV

Cookie2: $Version=1

Authorization: Basic RlRHQ0xJRU5UOmZ0Z2NsaWVudA==

 

<resource>

   <entity>

      <PK_KLIENTS>1</PK_KLIENTS>

      <ADRESE1>Glāžšķūnis, Rūķīšu iela 7</ADRESE1>

   </entity>

</resource>

 Response

HTTP/1.1 201 Created

Connection: keep-alive

Content-Type: application/xml; charset=UTF-8

Content-Length: 129

Date: Fri, 23 Jan 2015 07:10:51 GMT

Organization: 2, "Programmas izstrade - MSSQL"

Set-Cookie: IDHTTPSESSIONID=UVzlXxx9tMTlkAU; Path=/

 

<?xml version="1.0" encoding="UTF-8"  standalone="no"?>

<result>

  <link>

    <href>/rest/TNdmAdr/1879</href>

  </link>

</result>

Insert using template (POST to /rest/TNdmAdr/template)

A blank (with default values) XML is obtained by GET from the same resource:

Request

GET /rest/TNdmAdr/template HTTP/1.1 

Response

HTTP/1.1 200 OK

Connection: keep-alive

Content-Type: application/json; charset=UTF-8

  

<resource xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance" >

   <description>Jauna ieraksta sagatave</description>

   <entity xsi:schemaLocation="TNdmAdr.xsd TNdmAdr.xsd"  xmlns="TNdmAdr.xsd">

      <COUNTER/>

      <ADRESE/>

      <KONTAKTP/>

      <KONTAKTP_LNG1/>

      <KONTAKTP_LNG2/>

      <KONTAKTP_LNG3/>

      <LIC_NR/>

      <LIC_DAT/>

      <PIEZIMES/>

      <PK_ADRESE/>

      <PK_KLIENTS/>

      <STATUSS>1</STATUSS>

      <PK_REGIONS/>

      <PK_REISS/>

      <ADRESE1/>

      <ADRESE1_LNG1/>

      <ADRESE1_LNG2/>

      <ADRESE1_LNG3/>

      <ADRESE2/>

      <ADRESE2_LNG1/>

      <ADRESE2_LNG2/>

      <ADRESE2_LNG3/>

      <ADRESE3/>

      <ADRESE3_LNG1/>

      <ADRESE3_LNG2/>

      <ADRESE3_LNG3/>

      <PASTA_IND/>

      <PASTA_IND_LNG1/>

      <PASTA_IND_LNG2/>

      <PASTA_IND_LNG3/>

      <PK_VALSTS/>

      <LEG_ADR>2</LEG_ADR>

      <POST_ADR>2</POST_ADR>

      <KILOMETRI/>

      <PK_KLKPERS/>

      <PK_ADR2/>

      <KKUS_VIET_PK/>

   </entity>

</resource>

Upon filling in the data, only values for 2 fields PK_KLIENTS and ADRESE1 have been indicated. Values for the other fields have been left unchanged.


Creation request

POST /rest/TNdmAdr/template HTTP/1.1

Accept-Encoding: gzip,deflate

Content-Type: application/xml;charset=UTF-8

Content-Length: 1017

Host: localhost:81

Connection: Keep-Alive

User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

Cookie: IDHTTPSESSIONID=NoPWAFefPTZ5NsR

Cookie2: $Version=1

Authorization: Basic RlRHQ0xJRU5UOmZ0Z2NsaWVudA==

 

<resource xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance" >

   <description>Jauna ieraksta sagatave</description>

   <entity xsi:schemaLocation="TNdmAdr.xsd TNdmAdr.xsd"  xmlns="TNdmAdr.xsd">

      <COUNTER/>

      <ADRESE/>

      <KONTAKTP/>

      <KONTAKTP_LNG1/>

      <KONTAKTP_LNG2/>

      <KONTAKTP_LNG3/>

      <LIC_NR/>

      <LIC_DAT/>

      <PIEZIMES/>

      <PK_ADRESE/>

      <PK_KLIENTS>1</PK_KLIENTS>

      <STATUSS>1</STATUSS>

      <PK_REGIONS/>

      <PK_REISS/>

      <ADRESE1>Glāžšķūnis, Rūķīšu iela 7</ADRESE1>

      <ADRESE1_LNG1/>

      <ADRESE1_LNG2/>

      <ADRESE1_LNG3/>

      <ADRESE2/>

      <ADRESE2_LNG1/>

      <ADRESE2_LNG2/>

      <ADRESE2_LNG3/>

      <ADRESE3/>

      <ADRESE3_LNG1/>

      <ADRESE3_LNG2/>

      <ADRESE3_LNG3/>

      <PASTA_IND/>

      <PASTA_IND_LNG1/>

      <PASTA_IND_LNG2/>

      <PASTA_IND_LNG3/>

      <PK_VALSTS/>

      <LEG_ADR>2</LEG_ADR>

      <POST_ADR>2</POST_ADR>

      <KILOMETRI/>

      <PK_KLKPERS/>

      <PK_ADR2/>

      <KKUS_VIET_PK/>

   </entity>

</resource>

 Creation response

HTTP/1.1 201 Created

Connection: keep-alive

Content-Type: application/xml; charset=UTF-8

Content-Length: 129

Date: Fri, 23 Jan 2015 07:07:48 GMT

Organization: 2, "Programmas izstrade - MSSQL"

Set-Cookie: IDHTTPSESSIONID=yJfzsm6cWbBPsSR; Path=/

 

<?xml version="1.0" encoding="UTF-8"  standalone="no"?>

<result>

    <link>

        <href>/rest/TNdmAdr/1877</href>

    </link>

</result>

Classifier synchronisation

Horizon classifier synchronisation mechanism offers the option to track changes for selected classifiers from one moment in time to another. For example, an external application can use this mechanism to determine whether the entry has updated since it was read.


A REST user, who has been authenticated using the application identifier , can obtain information about new, updated and deleted entries. After processing the user can mark selected entries as processed.


After authentication using an application identifier, sub-resource sync becomes available to each classifier collection resource:

Request

GET /rest/TNdmNomIzvSar HTTP/1.1


Response

HTTP/1.1 200 OK

Connection: keep-alive

Content-Type: application/xml; charset=UTF-8

Content-Length: 1594

 

<resource xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance" >

   <description>Nomenklatūras</description>

   <keyfield>N.PK_NOM</keyfield>

   <codefield>N.KODS</codefield>

   <link>

      <href>/rest/TNdmNomIzvSar/query</href>

      <description>Veikt datu atlasi</description>

   </link>

 

. . . . .

 

   <link>

      <href>/rest/TNdmNomIzvSar/sync</href>

      <description>Sinhronizācijai</description>

   </link>

</resource>

Resource sync contains sub-resources new, edited, changed, deleted:

Request

GET /rest/TNdmNomIzvSar/sync HTTP/1.1 

Response

HTTP/1.1 200 OK

Connection: keep-alive

Content-Type: application/xml; charset=UTF-8

Content-Length: 638

 

<resource xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance" >

   <description>Sinhronizācijai</description>

   <link>

      <href>/rest/TNdmNomIzvSar/sync/new</href>

      <description>Atlasīt jaunos ierakstus</description>

   </link>

   <link>

      <href>/rest/TNdmNomIzvSar/sync/edited</href>

      <description>Atlasīt mainītos ierakstus</description>

   </link>

   <link>

      <href>/rest/TNdmNomIzvSar/sync/changed</href>

      <description>Atlasīt jaunos un mainītos ierakstus</description>

   </link>

   <link>

      <href>/rest/TNdmNomIzvSar/sync/deleted</href>

      <description>Atlasīt dzēstos ierakstus</description>

   </link>

</resource>


The response shows four sub-resources:

  1. new - new classifier entries.
  2. edited – entries updated since marking them as processed.
  3. changed – new and updated entries, this resource is a combination of the two previous resources.
  4. deleted - for work with entries that have been marked processed and have been deleted afterwards.

sub-resources new, edited and changed

API that shows new, edited and changed sub-resources is the same as for the respective collection query resource - filtering, criteria, metadata, arranging, column selection are supported. The returned data have the same format as the collections. To mark the entries processed, a POST request should be made to the respective resource. Format of both GET and POST request is identical to the response format of collection query resource GET request.


Obtaining non-processed classifiers

GET /rest/TNdmNomIzvSar/sync/new HTTP/1.1 

Response

HTTP/1.1 200 OK

Connection: keep-alive

Content-Type: application/xml; charset=UTF-8

 

<resource xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance" >

   <description>Atlasīt jaunos ierakstus</description>

   <title>Nomenklatūras</title>

   <collection xsi:schemaLocation="TNdmNomIzvSar.xsd TNdmNomIzvSar.xsd"  xmlns="TNdmNomIzvSar.xsd">

      <metadata>

         <column>

            <name>N.PK_NOM</name>

            <description>Nomenklatūra</description>

            <prefix>Nom</prefix>

            <width>15</width>

            <format/>

            <type>TNdmNom:TNdmNomForeignKeyStructure</type>

         </column>

         <column>

            <name>N.KODS</name>

            <description>Kods</description>

            <prefix>Nom</prefix>

            <width>18</width>

            <type>Size18StringType</type>

         </column>

         <column>

            <name>N.COUNTER</name>

            <description>COUNTER</description>

            <prefix>Nom</prefix>

            <width>15</width>

            <format/>

            <type>xsd:integer</type>

         </column>

      </metadata>

      <row>

         <N>

            <PK_NOM>

               <href>/rest/TNdmNom/1</href>

            </PK_NOM>

            <KODS>TARA2</KODS>

            <COUNTER>226</COUNTER>

         </N>

      </row>

      <row>

         <N>

            <PK_NOM>

               <href>/rest/TNdmNom/2</href>

            </PK_NOM>

            <KODS>pap</KODS>

            <COUNTER>90</COUNTER>

         </N>

      </row>

   </collection>

</resource>


To entries processed, the same request can be used as for reading them, using POST instead of GET. It is important that the content of POST request includes keyfield for the respective entries and COUNTER field values.

POST /rest/TNdmNomIzvSar/sync/new HTTP/1.1

Content-Type: application/xml;charset=UTF-8

  

<resource xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance" >

   <description>Atlasīt jaunos ierakstus</description>

   <title>Nomenklatūras</title>

   <collection xsi:schemaLocation="TNdmNomIzvSar.xsd TNdmNomIzvSar.xsd" xmlns="TNdmNomIzvSar.xsd">

      <metadata>

         <column>

            <name>N.PK_NOM</name>

            <description>Nomenklatūra</description>

            <prefix>Nom</prefix>

            <width>15</width>

            <format/>

            <type>TNdmNom:TNdmNomForeignKeyStructure</type>

         </column>

         <column>

            <name>N.KODS</name>

            <description>Kods</description>

            <prefix>Nom</prefix>

            <width>18</width>

            <type>Size18StringType</type>

         </column>

         <column>

            <name>N.COUNTER</name>

            <description>COUNTER</description>

            <prefix>Nom</prefix>

            <width>15</width>

            <format/>

            <type>xsd:integer</type>

         </column>

      </metadata>

      <row>

         <N>

            <PK_NOM>

               <href>/rest/TNdmNom/1</href>

            </PK_NOM>

            <KODS>TARA2</KODS>

            <COUNTER>226</COUNTER>

         </N>

      </row>

      <row>

         <N>

            <PK_NOM>

               <href>/rest/TNdmNom/2</href>

            </PK_NOM>

            <KODS>pap</KODS>

            <COUNTER>90</COUNTER>

         </N>

      </row>

   </collection>

</resource>

sub-resource deleted

For a deleted resource, API does not support standard collection query resource options. Only parameter hierarchy is supported. The returned data will always contain two columns: primary key field (keyfield) for the respective collection and COUNTER:

Request

GET /rest/TNdmNomIzvSar/sync/deleted HTTP/1.1

Response

HTTP/1.1 200 OK

Connection: keep-alive

Content-Type: application/xml; charset=UTF-8

  

<resource xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance" >

   <description>Atlasīt dzēstos ierakstus</description>

   <title>Nomenklatūras</title>

   <collection xsi:schemaLocation="TNdmNomIzvSar.xsd TNdmNomIzvSar.xsd"  xmlns="TNdmNomIzvSar.xsd">

      <metadata>

         <column>

            <name>N.PK_NOM</name>

            <description>Nomenklatūra</description>

            <prefix>Nom</prefix>

            <width>15</width>

            <format/>

            <type>TNdmNom:TNdmNomForeignKeyStructure</type>

         </column>

         <column>

            <name>N.COUNTER</name>

            <description>COUNTER</description>

            <prefix>Nom</prefix>

            <width>15</width>

            <format/>

            <type>xsd:integer</type>

         </column>

      </metadata>

      <row>

         <N>

            <PK_NOM>

               <href>/rest/TNdmNom/9555104</href>

            </PK_NOM>

            <COUNTER>101</COUNTER>

         </N>

      </row>

   </collection>

</resource>