Webservices – Dimensions Twinfield v5.4 September 2010 Twinfield International NV De Wel 20-b 3871 MV Hoevelaken Netherlands Twinfield Web services – Dimension Xml Page 1 of 36 Important message No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, photocopying, recording, or otherwise, without prior written consent of Twinfield. This specification is provided “as is” without any express or implied warranty. If you submit any comments or suggestions to Twinfield International NV, and Twinfield modifies the XML structure based on your input, Twinfield shall own the modified XML version. Information in this document is subject to change without notice. contact information Twinfield International N.V. De Wel 20-b 3871 MV Hoevelaken Tel. +31 (0)30-2982242 Fax. +31 (0)33-4677005 www.twinfield.com
[email protected] support: login page https://login.twinfield.com publish information copyright © 2005 – 2010 - Twinfield International N.V. version 1.3 Feedback can be send to:
[email protected] Printed in the Netherlands on recycled paper or digitally published in Portable Document Format (PDF). Twinfield Web services – Dimension Xml Page 2 of 36 Table of contents Important message................................................................................................................. 2 contact information ................................................................................................................ 2 publish information ................................................................................................................. 2 Table of contents.................................................................................................................... 3 Preface .................................................................................................................................. 4 Audience and Prerequisites..................................................................................................... 4 General Xml recommendations ............................................................................................... 5 Error handling ........................................................................................................................ 5 Field definitions ...................................................................................................................... 6 Attributes in the response Xml ................................................................................................ 6 Dimension types .................................................................................................................... 7 Example ................................................................................................................................. 12 Determine the next dimension code......................................................................................... 14 General Ledger accounts (GL accounts) ................................................................................. 15 Customers ............................................................................................................................. 19 Suppliers................................................................................................................................ 24 Payment and direct debit settings ........................................................................................... 28 Cost Centers .......................................................................................................................... 30 Project ................................................................................................................................... 32 Dimension actions .................................................................................................................. 35 Dimension read ...................................................................................................................... 36 International payments ........................................................................................................... 36 Twinfield Web services – Dimension Xml Page 3 of 36 Preface This document describes the Xml message to add or modify users in Twinfield. The Xml messages, which are described in this document, can be used by using the Twinfield ProcesXml Web service function. A full description of the available Twinfield Web services can be downloaded from the F.A.Q. in Twinfield (see also the paragraph “Related documents”). Audience and Prerequisites This document is intended for developers who are designing or developing Twinfield Web service enabled applications. The Twinfield User Interface (GUI) corresponds directly with the Twinfield Xml layer. When you need to build an integration with Twinfield we strongly advice to „simulate‟ the interface (e.g. dimension settings and posting journals) manually in Twinfield. The (error) messages generated by the Twinfield client are the same as the error messages returned in the Web services response Xml messages. Readers should have a working knowledge of the Twinfield concepts and HTTP, Xml, SOAP or Web services communication standard. General information on Xml, SOAP or web services can be found on http://www.w3schools.com Related documents Description of all available Twinfield Web services and Xml messages are described in the corresponding manuals. These manuals can be downloaded from the F.A.Q. in Twinfield, with the keywords: Webservices, SOAP or XML. Twinfield Web services – Dimension Xml Page 4 of 36 General Xml recommendations The Twinfield Web services are based on Xml, which requires all documents to be well formed. If an Xml document is not well formed it will raise an error event. Xml Encoding Xml documents may contain foreign characters, like Norwegian æ ø å , or French ê è é. To let your Xml parser understand these characters, you should save your Xml documents as Unicode. The preferred encoding is “ISO-8859-1” Illegal Xml characters have to be replaced by entity references. If you place a character like “ & „ “ Description Less than Greater than Ampersand Apostrophe Quotation mark Note: Only the characters “Dimensions>Type o General Ledger o o o Relations o o o o o Customers, code DEB Suppliers, code CRD Balance, code BAS Profit & Loss, code PNL Cost centers, code KPL Fixed assets, code AST Projects, code PRJ Screen in Twinfield Twinfield Web services – Dimension Xml Page 7 of 36 Description of the dimension type XML elements Tag dimensiontype office code mask name shortname addresses label1 – label6 levels financials time fixedassets invoices Parent node dimensiontype dimensiontype dimensiontype dimensiontype dimensiontype dimensiontype addresses dimensiontype levels levels levels levels Description root node Office code Dimensiontype Dimension mask Dimension type name Dimension type shortname node Address labels, description of field1 – field6 in the dimension address element node Financial level Level in time & expenses Level in fixed assets (future use) Level in invoice articles (future use) Type definition CODE, optional CODE, mandatory CODE, optional STRING(36), optional STRING(20), optional STRING(20), optional - (read only) INTEGER, read only INTEGER, read only INTEGER, read only INTEGER, read only Example This example changes the dimension mask to “1####” for the Customers (DEB) dimension type. Request 0000 DEB 1#### Customers Twinfield Web services – Dimension Xml Page 8 of 36 Response XML 0000 DEB 1#### Customers AR 2 2 0 0 0 foa Address Postal address VAT nummer COC nummer Twinfield Web services – Dimension Xml Page 9 of 36 Dimension groups Screen in Twinfield Corresponding XML node: dimensiongroup Corresponding XML node: dimensions/dimension Structure of the dimension group elements Tag Attributes result="1" result="0" msg="" status=”active|deleted” Description OK Not OK, an error occurred, see also Error handling The status of the dimension group. Occurs 1 1- 0,1 0- Twinfield Web services – Dimension Xml Page 10 of 36 Description of the dimension group elements Tag dimensiongroups dimensiongroup office code name shortname dimensions dimension type code Parent node dimensiongroups dimensiongroup dimensiongroup dimensiongroup dimensiongroup dimensiongroup dimensions dimension dimension Description root node node Office code Dimensiontype Dimension type name Dimension type shortname node node Dimension type Dimension code Type definition CODE, mandatory CODE, mandatory STRING(36), optional STRING(20), optional - optional - optional CODE CODE Twinfield Web services – Dimension Xml Page 11 of 36 Example This example creates a new dimension group and adds the customer 1001 to this dimension group. 0000 LOC_CUST Customers DEB 1001 Response XML 0000 LOC_CUST Local customers 1 DEB 1001 Twinfield Web services – Dimension Xml Page 12 of 36 Dimensions Menu path: Accounting>Dimensions>Manage Structure of the dimensions XML Tag Attributes result="1" result="0" msg="" status=”active|hidden” Description OK An error occurred, see also Error handling Occur 1 type=”code|group|type” level=”1|2|3|4” Validiate against Dimension code, group or –type Dimension level 1- 0,1 0- 1 id="xx" default=”true|false” type="invoice|postal|cont act" Sequence number Default address Address type 0,1 0- id="xx" default="true/false" Sequence number Default bank 0,1 0- 0,1 0,1 1 0- 1 0,1 0- 0,1 0- 0,1 0- Twinfield Web services – Dimension Xml Page 13 of 36 Determine the next dimension code The option “next free code” is added to the dimension Xml. When the code field is not added to the dimension Xml, Twinfield will determine the code which must be used. Example Request Xml 0000 KPL Sales & Markerting Response Xml 0000 KPL Sales & Markerting 00004 true 2 notmatchable inherit maybe false false 0 0 false Twinfield Web services – Dimension Xml Page 14 of 36 General Ledger accounts (GL accounts) Balance Profit & Loss This documentation only the BAS Dimension type will be described, the PNL dimension type has the same XML structure. Only the fixed value of the “type” element is different, PNL (=Profit & Loss). Screens in Twinfield Corresponding XML node: dimension Corresponding XML node: banks/bank Corresponding XML node: groups/group Corresponding XML node: dimension financials and for the validation rules the corresponding XML node is: childvalidations/childvalidation Twinfield Web services – Dimension Xml Page 15 of 36 Description of the General Ledger elements Tag dimensions dimension office code Parent node dimensions dimension dimension Description root node node Office code dimension code, must be compliant with the mask in the Dimension type Dimension type, fixed to BAS or PNL Type definition - (optional) CODE, optional CODE, optional (see: “Determine the next dimension code”) FIXED VALUE STRING(40) INTEGER INTEGER INTEGER INTEGER node node Description of the (bank) account number Local bank account number node STRING(40) STRING(40) - (optional) CODE, optional node Is subanalyse to a customer, supplier or cost center needed. ENUMERATION: - true - false - maybe ENUMERATION: not matchable matchable relation type name beginyear beginperiod endyear endperiod banks bank ascription accountnumber groups group financials subanalyse dimension dimension dimension dimension dimension dimension dimension bank bank bank dimension groups dimension financials matchtype financials Sets the GL account match able value. The preferred value for suspense accounts is “matchable”. Type vat code, for future use Default VAT code, for future use Is the VAT code obligatory, for future use node vattype vatcode vatobligatory childvalidations financials financials financials financials CODE, optional BOOLEAN - Twinfield Web services – Dimension Xml Page 16 of 36 Tag childvalidation Parent node childvalidations Description Validation rule when sub analyses to a customer, supplier or cost center is needed. Validation to which Dimension type. Type definition type attrubute of childvalidation ENUMERATION: - code (=dimension code) - type (= Dimension type) - group (=dimension group) ENUMERATION: 1 (=GL account) 2 (= customer, supplier or cost center) 3 (=project or asset) 4 (= project activity) level attrubute of childvalidation Financial level Example This example adds a new Balance sheet account, “3101 Work in Progress - Consultants” in Twinfield. In this example we add also a validation rule. In the Twinfield input function the user must also enter a cost center and project when posting a journal on this GL account. Request 0000 3101 BAS Work in Progress - Consultants true KPL PRJ GLB30 SLB30.20 Twinfield Web services – Dimension Xml Page 17 of 36 Response XML 0000 3101 BAS false Work in Progress - Consultants system 0 0 0 0 0 false notmatchable balance true 0 1 false false 0 false KPL PRJ GLB30 SLB30.20 Twinfield Web services – Dimension Xml Page 18 of 36 Customers Screens in Twinfield Corresponding XML node: dimension Corresponding XML node: addresses/address Corresponding XML node: banks/bank. This customer is linked to the Dutch Clieop direct debit “payment file”. The bank settings are be different per payment (or direct debit) file. A full description can be found in the chapter: International payments. Corresponding XML node: financials Twinfield Web services – Dimension Xml Page 19 of 36 Corresponding XML node: creditmanagement Corresponding XML node: invoicing Corresponding XML node: postingrules Description of the customer elements Tag dimensions dimension office code type name website addresses address Parent node dimensions dimension dimension dimension dimension dimension dimension addresses Description root node node Office code dimension code, must be compliant with the mask in the Dimension type Dimension type, fixed to DEB Name of the customer Website node node Type definition - (optional) CODE CODE, optional (“Determine the next dimension code”) FIXED VALUE STRING(40) STRING(40) - Twinfield Web services – Dimension Xml Page 20 of 36 Tag id type Parent node attribute of address attribute of address Description Sequence number Address type Type definition INTEGER ENUMERATION: invoice postal contact default name field1 – field6 postcode city country telephone telefax email banks bank ascription accountnumber city financials duedays payavailable paycode vattype vatcode vatobligatory substitutewith attribute of address address address address address address address address address dimension banks bank bank bank dimension financials financials financials financials financials financials financials Is this the default address, only one default address is possible Company name User defined fields, the labels are configured in the Dimension type. Postal code City ISO country code. Boolean STRING(80) STRING(40) STRING(40) STRING(40) STRING(2)* STRING(15) STRING(15) E-mail address node node Name of the account number holder Bank account number City of the account number holder node STRING(128) - INTEGER Is a direct debit possible? Direct Debit code Type vat code, for future use Default VAT code, for future use Is the VAT code obligatory, for future use Default customer GL account. BOOLEAN CODE CODE BOOLEAN CODE Twinfield Web services – Dimension Xml Page 21 of 36 Tag ebilling ebillmail creditmanagement basecreditlimit responsibleuser sendreminder blocked Parent node financials financials dimension creditmanagement creditmanagement creditmanagement creditmanagement Description Send the invoice per email to the customer. E-mail address to send the invoice to. node Type definition BOOLEAN STRING(128) - Credit manager Remind Are the related projects for this customer blocked in Projects>Data entry Usage rights Segment code Comments node Item (discount article) CODE BOOLEAN BOOLEAN freetext1 freetext2 comment invoicing discountarticle creditmanagement creditmanagement creditmanagement dimension invoicing BOOLEAN STRING(20) TEXT CODE Example This example creates a new customer “10020 - Morgan Limited” in Twinfield. Request XML 10020 Morgan Limited DEB www.yourdomain.com FAO Mr J.P. Morgan Streetname 1234 AB Berlin DE 010-12345 010-1234 VAT12345 Twinfield Web services – Dimension Xml Page 22 of 36
[email protected] Morgan Ltd. 123456 Berlin 30 true 250NL true
[email protected] true Twinfield Web services – Dimension Xml Page 23 of 36 Suppliers Screen in Twinfield: Corresponding XML node: dimension Corresponding XML node: addresses/address Corresponding XML node: banks/bank. This customer is linked to the Dutch Clieop direct debit “payment file”. The bank settings are be different per payment (or direct debit) file. A full description can be found in the chapter: International payments. Corresponding XML node: financials Twinfield Web services – Dimension Xml Page 24 of 36 Description of the supplier elements Tag dimensions dimension office code type name website addresses address id type Parent node dimensions dimension dimension dimension dimension dimension dimension addresses attribute of address attribute of address Description root node Node Office code dimension code, must be compliant with the mask in the Dimension type Dimension type, fixed to CRD Name of the supplier Website node node Sequence number Address type Type definition - (optional) CODE CODE, optional (“Determine the next dimension code”) CODE, mandatory STRING(40) STRING(40) INTEGER ENUMERATION: - invoice - postal - contact BOOLEAN STRING(80) STRING(40) STRING(40) STRING(40) STRING(2) STRING(15) STRING(15) E-mail address node node Name of the account number holder STRING(128) STRING(40) default name field1 – field6 postcode city country telephone telefax email banks bank ascription attribute of address address address address address address address address address dimension banks bank Is this the default address, only one default address is possible Company name User defined fields, the labels are configured in the dimension type. Postal code City ISO country code. Twinfield Web services – Dimension Xml Page 25 of 36 Tag accountnumber city financials duedays payavailable paycode vattype vatcode vatobligatory relationsreference substitutewith Example Parent node bank bank dimension financials financials financials financials financials financials financials financials Description Bank account number City of the account number holder node Type definition STRING(40) STRING(40) INTEGER Is a payment possible? Payment code Type vat code, for future use Default VAT code, for future use Is the VAT code obligatory, for future use Customer reference, your customer number by the supplier Default supplier GL account. BOOLEAN CODE CODE - (BOOLEAN) STRING(40) CODE This example creates a new supplier “2001 – Vodafone Ltd.” in Twinfield. 2001 CRD Vodafone Ltd. FAO Mr J.P. Hone 145 Streetname EC1V 4UK London GB 010-12345 010-1234 VAT12345
[email protected] Vodafone Ltd. 98745 London Twinfield Web services – Dimension Xml Page 26 of 36 14 true 250NL 2345 Twinfield Web services – Dimension Xml Page 27 of 36 Payment and direct debit settings Corresponding XML node: dimension m = mandatory a = available x = not available or required NL NL NL DE IE FI AT AT FI FI (DOM) (INT) (INT) DE (INT) (DOM) (DOM) (DOM) (INT) GENERIC (INT) (INT) NO PAYMENT TYPE BTL91 - IBAN BTL91 - NON IBAN ULMP - IBAN m a m m a m a a m m a a a x x ULMP - NON IBAN a a m m a a a m a a a a a x x CLIEOP03 TWFPAY* country* a x x a country* a m a country* a a a x x PAYMUL (DOM) m m x x a a a AT a m a a a x x PAYMUL (INT) a a x x a a a a a a a a a x x DTAUS DTAZV EMTS m m x x a a a a a a a a a x x x x a IE x m x x x x x LM02 m m x x x x a m x x x x x x x BANK FIELDS Account holder Account number Address No. Bank name BIC code Branch Country IBAN National bank code Number Postcode State Way of payment Xmlfield ascription accountnumber address/field1 address/field2 bankname biccode m NONIBAN x x a IBAN a BOTH m m x x x x a NL x x x x x x x m a m m m m m m m a m a a a a a a m m m m m a a m a a a a m m x x x x x m x a x x x x x a a iban natbiccode postcode state wayofpayment IBAN NONIBAN a a a x x Pay address payaddress * mandatory fields are determined on country level Twinfield Web services – Dimension Xml Page 28 of 36 NL NL NL DE IE FI AT AT FI FI (DOM) (INT) (INT) DE (INT) (DOM) (DOM) (DOM) (INT) GENERIC (INT) (INT) NO PAYMENT TYPE BTL91 - IBAN BTL91 - NON IBAN ULMP - IBAN m m m ULMP - NON IBAN m m m CLIEOP03 TWFPAY* x x x PAYMUL (DOM) x x x PAYMUL (INT) x x x DTAUS DTAZV EMTS x x x LM02 x x x ADDRESS FIELDS Address City Country Xmlfield x x x x x x x m m x m m x x x Twinfield Web services – Dimension Xml Page 29 of 36 Cost Centers Screen in Twinfield: Corresponding XML node: dimension Description of the cost center elements Tag dimensions dimension office code type name Parent node dimensions dimension dimension dimension dimension Description root node node Office code Dimension code, must be compliant with the mask in the Dimension type Dimension type, fixed to KPL Dimension name Type definition - (optional) CODE, optional CODE, optional (“Determine the next dimension code”) FIXED VALUE STRING(40) Example This example creates a new cost center “00001 - Sales & Marketing” in Twinfield Request XML 0000 00001 KPL Sales & Markerting Twinfield Web services – Dimension Xml Page 30 of 36 Response XML 0000 00001 KPL Sales & Markerting false normal 0 0 0 0 0 false 2 notmatchable inherit maybe false false 0 0 false Twinfield Web services – Dimension Xml Page 31 of 36 Project Screen in Twinfield: Corresponding XML node: dimension Corresponding XML node: financials Corresponding XML node: projects Description of the project elements Tag dimensions dimension office code type name Parent node dimensions dimension dimension dimension dimension Description root node node Office code Dimension code, must be compliant with the mask in the Dimension type Dimension type, fixed to PRJ Dimension name Type definition - (optional) CODE, optional CODE, optional (“Determine the next dimension code”) FIXED VALUE STRING(40) Twinfield Web services – Dimension Xml Page 32 of 36 Tag financials substitutionlevel substitutewith projects invoicedescription startdate enddate authoriser authoriser@locked customer customer@locked billable billable@locked billable@inherit billable@forratio quantities quantity mandatory label rate billable billable@locked Parent node dimension financials financials dimension projects projects projects projects projects projects projects projects projects projects projects projects quantities quantity quantity quantity quantity quantity Description node Dimension level, fixed to 2 Cost center code node Invoice description Valid date (from) Valid date (to) Authoriser Attribute Customer Attribute; Can the customer code be changed during input Billable Attribute; Can the billable option be changed during input Attribute Attribute node node Use quantities Preferred label The project (quantity) rate code Are the quantities billable Type definition FIXED VALUE CODE STRING(256) DATE DATE CODE BOOLEAN CODE BOOLEAN BOOLEAN BOOLEAN BOOLEAN BOOLEAN BOOLEAN STRING(40) CODE BOOLEAN BOOLEAN Twinfield Web services – Dimension Xml Page 33 of 36 Example This example creates a new project “P001 - Consultancy” in Twinfield Request XML 0000 P001 PRJ Consultancy 2 00001 Twinfield Web services – Dimension Xml Page 34 of 36 Dimension actions This chapter describes the methods to delete or hide a dimension in Twinfield. When a journal entry has been posted on a dimension the deleted status is not available. To prevent users to post journals in the future to this dimension you need to hide this dimension. Description of the dimension actions elements Tag dimensions dimension status Parent node dimensions attribute of dimension Description root node node Delete or hides a dimension in Twinfield. When a dimension is hidden you can enable the dimension by setting the status to “active”. Office code Dimension code, must be compliant with the mask in the Dimension type Dimension type, fixed to KPL Type definition - (optional) ENUMERATION: - deleted - hide - active CODE, optional CODE, mandatory CODE, mandatory office code type dimension dimension dimension Example This example deletes customer 1000 in office 0000, hide customer 1001 in the current office and re-enables customer 1002. Request Xml 0000 1000 DEB DEB 1001 DEB 1002 Twinfield Web services – Dimension Xml Page 35 of 36 Dimension read This example reads the dimension setting of customer (DEB) 1000 in office 001. More information about the read Xml message is described in the manual: “Twinfield Web Services” Request Xml dimensions 001 DEB 1000 International payments Twinfield supports several payment formats, each payment format can have a different Twinfield Web services – Dimension Xml Page 36 of 36