Skip to main content

Browse data

Introduction​

In order to get financial data out of Twinfield like general ledger transactions, sales invoices, and so on, use the browse data functionality. This functionality is based on so called browse codes. These browse codes are predefined definitions of financial data.

Regimes​

When retrieving financial transactions from Twinfield, it is important to consider regimes.

With the introduction of the new fixed assets module, financial transactions can be created within different regimes. Financial transactions can be posted within one of the following regimes:

  1. Generic
  2. Fiscal
  3. Economic
  4. Commercial

Notice that it is not obvious that regimes are used within a company. In case regimes are not used, a financial transaction will be created in the “Generic” regime by default. A company can contain financial transactions posted in one, two or all three regimes (apart from the generic regime which is always available).

So a Twinfield company will contain generic financial transactions and optional regime specific financial transactions. Overview of values of a company by regime are build up by the specific financial transactions by regime extended with the generic financial transactions.

Several browse codes contains a column by which financial transactions in a specific regime can be selected. The behavior is:

Browse codeBehavior
000If no regime is selected, all transactions lines will be shown.
Searching for Generic will return only Generic transaction lines.
Searching for Fiscal, Commercial or Economic will return those specific transaction lines, including all Generic lines.
Transaction lines will not be grouped and summed.
010If no regime is selected, all transactions lines will be shown.
Searching for Generic will return only Generic transaction lines.
Searching for Fiscal, Commercial or Economic will return those specific transaction lines, including all Generic lines.
Transaction lines will not be grouped and summed.
020If no regime is selected, all transactions lines will be shown.
Searching for Generic will return only Generic transaction lines.
Searching for Fiscal, Commercial or Economic will return those specific transaction lines, including all Generic lines.
Transaction lines will not be grouped and summed.
030_3If no regime is selected, all transactions lines will be shown.
Searching for Generic will return only Generic transaction lines.
Searching for Fiscal, Commercial or Economic will return those specific transaction lines, including all Generic lines.
Transaction lines will not be grouped and summed.
031_2If no regime is selected, all transactions lines will be shown.
Searching for Generic will return only Generic transaction lines.
Searching for Fiscal, Commercial or Economic will return those specific transaction lines, including all Generic lines.
Transaction lines will not be grouped and summed.
040_1Regime is mandatory.
Searching for Generic will return only Generic transaction lines.
Searching for Fiscal, Commercial or Economic will return those specific transaction lines, including all Generic lines.
Transaction lines will be grouped and summed.
050_1Regime is mandatory.
Searching for Generic will return only Generic transaction lines.
Searching for Fiscal, Commercial or Economic will return those specific transaction lines, including all Generic lines.
Transaction lines will be grouped and summed.
060Regime is mandatory.
Searching for Generic will return only Generic transaction lines.
Searching for Fiscal, Commercial or Economic will return those specific transaction lines, including all Generic lines.
Transaction lines will be grouped and summed.

Best practices​

In order to avoid technical error messages because of retrieving large data sets, apply the following best practices:

  1. Retrieve the transactions by period.
  2. Only add columns to your request for which you really need the values.

Steps to be taken​

When developing a query to extract data from Twinfield the follow steps need to be taken:

  1. Determine in Twinfield which browse definition to use.
  2. Read the browse definition.
  3. Fill in the selection criteria.
  4. Compose and send the (browse) query to Twinfield.

It is important to notice that the first two steps should only be taken once. At the moment the browse definition is clear and the browse query is created, it can be used in the calling software.

Web service type: XML Web Services

Determine which browse definition to use​

The available browse definitions correspond to the Transaction lines functionality in Twinfield and the available TwinCubes in Twinfield analysis. A browse definition is represented by a browse code. The following browse codes are available:

Browse codeDescription
000General ledger transactions
010Transactions still to be matched
020Transaction list
100Customer transactions
200Supplier transactions
300Project transactions
301Asset transactions
400Cash transactions
410Bank transactions
900Cost centers
030_1General Ledger (details)
030_2General Ledger (details) (v2)
030_3General Ledger (details) (v3)
031General Ledger (intercompany)
031_2General Ledger (intercompany)(v2)
040_1Annual Report (totals)
050_1Annual Report (YTD)
060Annual Report (totals multicurrency)
130_1Customers
130_2Customers (v2)
130_3Customers (v3)
164Credit Management
230_1Suppliers
230_2Suppliers (v2)
302_1Fixed Assets
610_1Time & Expenses (Totals)
620Time & Expenses (Multicurrency)
650_1Time & Expenses (Details)
651_1Time & Expenses (Totals per week)
652_1Time & Expenses (Totals per period)
660_1Time & Expenses (Billing details)
661_1Time & Expenses (Billing per week)
662_1Time & Expenses (Billing per period)
670Transaction summary
680Bank link details
680_2Bank link details (v2)
690Vat Return status
700Hierarchy access

Follow the link to this document to get a clear view of the most used browse codes and their fields.

Read the browse definition​

Once the browse definition to be used is clear, its content can be determined. Each browse definition exists of browse fields. These browse fields contains the data and some of those also acts as selection criteria. Which browse fields are available depends on the used browse definition. In order to get an overview of the available browse fields of a browse definition, use the read XML request.

Next example returns all available fields of browse code 000 - General ledger transactions - of company 001.

<read>
    <type>browse</type>
    <office>001</office>
    <code>000</code>
</read>

Besides some general information about the browse definition, all available columns of the specific browse definition are returned in the columns section.

Element name: column

NameTypeDescription
@idintegerColumn id.
fieldstring(40)Predefined field names of the particular browse code.
labelstring(255)Column header description.
visibletrue
false		If visible = true then the column will be shown in the result.
If visible = false the column will not be shown.
If the value of this property is set to false do not change it into true when using it in a browse request in order to prevent technical errors.
Read-only attribute.
asktrue
false		Can a selection criterion been entered.
Read-only attribute.
operatornone
equal
between		List of operators. Only applicable in case ask is true.
fromstring(40)Value from. When the operator is none the value will be ignored.
tostring(40)Value to. Only be filled in when the operator is between.
finderparamNot in use.

Fill in the selection criteria​

Once the available fields of a browse definition are determined, the available selection criteria are clear. All fields for which the tag ask is true can be used as a selection criterion.

Underneath example adds a selection criterion on the period field:

<column>
    <field>fin.trs.head.yearperiod</field>
    <operator>between</operator>
    <from>2021/01</from>
    <to>2021/12</to>
</column>

Compose the browse request and send it​

info

When retrieving data from Twinfield, the data of the company the user is currently logged in to will be retrieved. When the user is not logged in to the correct company, use the SelectCompany function in order to switch to another company.

Create based on the available fields of the browse definition and the available selection criteria the final browse request. Only add those fields for which data should be retrieved or which are used as a selection criterion.

In the browse request it is possible to add up to three sort fields. The data of the XML response will then be sorted based on these fields. Underneath an example:

<sort>
    <field order="descending">fin.trs.line.dim2</field>
    <...>
</sort>

Element name: sort

NameTypeDescription
fieldstring(40)Predefined field names of the particular browse code.
@orderascending
descending		The sorting order. ascending is the default value.

Besides the sorting order, the following attributes can be added to the request:

AttributeDescription
optimizeEnables or disables optimization of the output. Possible values are true and false. false is the default value. When set to true, the field, hideforuser and type attributes are removed from all <td> elements except those in the <th> element.
outputformatDetermines the output format of the data. Possible values are "XML" and "CSVEXCEL", "XML" is the default value. Output format XML creates a series of <tr> and <td> elements to store the data. Output format CSVEXCEL creates a single <csv> element containing CSV data optimized for use in MS Excel. The field separator is the tab character.

Browse fields​

As mentioned before, browse definitions exists of browse fields. Each browse fields has its own definition and can be determined by using the list XML. This is useful in particular for browse fields with predefined values like fin.trs.head.status or fin.trs.line.debitcredit.

Below example returns all available browse fields and their definition. Note that which browse fields can be used depends on the browse code, which is used.

<list>
    <type>browsefields</type>
</list>

Example​

Underneath an example of the General ledger transactions browse definition.

<columns code="000">
    <sort>
        <field>fin.trs.head.code</field>
    </sort>
    <column>
        <field>fin.trs.head.yearperiod</field>
        <label>Period</label>
        <visible>true</visible>
        <ask>true</ask>
        <operator>between</operator>
        <from>2021/01</from>
        <to>2021/12</to>
    </column>
    <column>
        <field>fin.trs.head.code</field>
        <label>Transaction type</label>
        <visible>true</visible>
    </column>
    <column>
        <field>fin.trs.head.shortname</field>
        <label>Name</label>
        <visible>true</visible>
    </column>
    <column>
        <field>fin.trs.head.number</field>
        <label>Trans. no.</label>
        <visible>true</visible>
    </column>
    <column>
        <field>fin.trs.line.dim1</field>
        <label>General ledger</label>
        <visible>true</visible>
        <ask>true</ask>
        <operator>between</operator>
        <from>1300</from>
        <to>1300</to>
    </column>
    <column>
        <field>fin.trs.head.curcode</field>
        <label>Currency</label>
        <visible>true</visible>
    </column>
    <column>
        <field>fin.trs.line.valuesigned</field>
        <label>Value</label>
        <visible>true</visible>
    </column>
    <column>
        <field>fin.trs.line.description</field>
        <label>Description</label>
        <visible>true</visible>
    </column>
</columns>