Handleiding BackOffice XML Connector service Versie 1.03 (gemaakt voor BackOffice XML Connector versie 1.0.24)
Handleiding BackOffice XML Connector Drukfouten voorbehouden, eventueel getoonde prijzen zijn fictief
- 1 -
Handleiding BackOffice XML Connector Inhoud Handleiding ...................................................................................................................................................... 1 Inhoud.................................................................................................................................................... 2 1 Algemeen ...................................................................................................................................... 3 1.1 Communicatie .......................................................................................................................... 3 1.2 Installatie .................................................................................................................................. 3 1.3 Divers ........................................................................................................................................ 3 2 Twinfield ....................................................................................................................................... 4 2.1 Input syntax(es) ........................................................................................................................ 4 2.2 Opmerkingen ............................................................................................................................ 4 2.3 Result codes.............................................................................................................................. 4 2.4 Voorbeeld ................................................................................................................................. 4 3 Nostradamus ................................................................................................................................. 6 3.1 Push (_NOSTRA_PUSH_)........................................................................................................... 6 3.1.1 Input syntax(es) ........................................................................................................................ 6 3.1.2 Result codes.............................................................................................................................. 6 3.1.3 Voorbeeld ................................................................................................................................. 7 3.2 Fetch (_NOSTRA_FETCH_) ........................................................................................................ 7 3.2.1 Input syntax(es) ........................................................................................................................ 7 3.2.2 Result codes.............................................................................................................................. 7 3.2.3 Voorbeeld ................................................................................................................................. 7 4 BackOffice Online.......................................................................................................................... 8 4.1 Import (_BOONLINE_IMP_) ...................................................................................................... 8 4.1.1 Input syntax(es) ........................................................................................................................ 8 4.1.2 Export Types (meerdere regels /types mogelijk)...................................................................... 8 4.1.3 Filtertype opties ....................................................................................................................... 8 4.1.4 Result codes.............................................................................................................................. 9 4.2 Sync (_BOONLINE_SYNC_) ...................................................................................................... 11 4.2.1 Input syntax(es) ...................................................................................................................... 11 4.2.2 SyncType (meerdere regels /types mogelijk) ......................................................................... 11 4.3.3 Filtertype opties ..................................................................................................................... 11 4.3.4 Result codes............................................................................................................................ 12 5 Log van BackOffice XML Connector uitlezen .............................................................................. 13 5.1 Opvragen (_READ_LOG_) ....................................................................................................... 13 5.1 Input syntax(es) ...................................................................................................................... 13 5.2 Result ...................................................................................................................................... 13
Handleiding BackOffice XML Connector Drukfouten voorbehouden, eventueel getoonde prijzen zijn fictief
- 2 -
1
Algemeen
1.1
Communicatie
OrgaplanXml_Connector (BackOfficeXmlConnector) luistert standaard naar poort 5601 (is instelbaar in bestand OrgaplanXML_Connector.ini => ServerSocketPort), berichten eindig je met ETC (decimaal karakter 03). Berichten die je terug krijgt na je call worden ook beëindigd met ETC (decimaal karakter 03). Je moet altijd eerst het type call aangeven met een carriage return (_TWINF_JOURNAL_ / _NOSTRA_PUSH_ / _NOSTRA_FETCH_) Bij SETTINGS kan je altijd aangeven of je de output (naar de server) en input (antwoord van server) wilt wegschrijven. Deze worden in de mappen XML_Input en XML_Output in de hoofdmap van de server weggeschreven. Van de voorbeelden hieronder heb ik de bestanden bijgevoegd.
1.2
Installatie
Je kan dit programma in een map op de server zetten, dan met rechtermuisknop als administrator uitvoeren en dan krijg je een installatie scherm. Kies install. Op een server kan je naar services.msc gaan en op de eigenschappen van OrgaplanXml_Connector klikken en bij de tab Systeemherstel bij eerste fout, tweede fout en volgende fouten kiezen "Service opnieuw starten". Om te testen kan je bij de tab algemeen het opstarttype op "Handmatig" zetten. De service wordt dan niet onnodig automatisch opgestart bij het opstarten van de pc, en je kan hem zelf op starten drukken wanneer nodig.
1.3
Divers
Je kan het versienummer van het programma opvragen via het commando: _GET_VERSION_ +
+ <03>
Handleiding BackOffice XML Connector Drukfouten voorbehouden, eventueel getoonde prijzen zijn fictief
- 3 -
2
Twinfield
2.1
Input syntax(es)
SETTINGS
+ + + +
LOGIN SESSION TRANS_HDR TRANS_HDR_DATA TRANS_LINE TRANS_LINE_DATA
2.2
+ + + + + +
+ URL + UseHTTPS (T/F/0/1) + + Write XML input + Write XML output + + Login name + Login password + + Organisation/Omgevingsnaam + + SessionKey + + Cluster + [LOGIN row not needed, resuming with existing sessionkey] + + + + + + <node value 1> + + <node value n..> + + + + + + + <node value 1> + + <node value n..> +
Opmerkingen
Let op dat je regels van hetzelfde type onder elkaar zet, dus alle details (type:detail) onder elkaar, alle vat (type:vat) onder elkaar etc!
2.3
Result codes
200 500 501 502 901 902 921 922 980 9001 9002
Call seems ok (200 + + OK) Error in transaction node of call Error in header node of call Error in lines node of call Error with login call, http result is returned Error with login call, result is no valid xml document Error with ProcessXmlDocument call, http result or fault message is returned Error with ProcessXmlDocument call, result is no valid xml document Error with call, System errorcode 12057, error requesting for revoked SSL certificate, please try again Error with call for login + + Error Error with call to url + + Error
2.4
Voorbeeld
_TWINF_JOURNAL_ SETTINGS /webservices/processxml.asmx true true true LOGIN NLG001216 Virtess2013 TWF-SAAS TRANS_HDR destiny:temporary office code currency date TRANS_HDR_DATA NLA001237 KAS EUR 20150403 TRANS_LINE type:total dim1 debitcredit value TRANS_LINE_DATA 1000 debit 121.00 TRANS_LINE type:detail dim1 rate debitcredit description basevalue value TRANS_LINE_DATA 8020 1 credit Laptops 100.00 100.00 VH 20150403 TRANS_LINE type:vat dim1 vatcode debitcredit description basevalue value TRANS_LINE_DATA 4340 VH credit BTW 19% 21.00 21.00
vatcode
currencydate
Gegenereerde output volgens voorbeeld: <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:twin="http://www.twinfield.com/"> <soapenv:Header> 807398cc-cc4e-4b7d-8a17-7592f1cd9d05 <soapenv:Body> NLA001237 KAS <currency>EUR 20150403 1000 <debitcredit>debit 121.00
Handleiding BackOffice XML Connector Drukfouten voorbehouden, eventueel getoonde prijzen zijn fictief
- 4 -
8020 1 <debitcredit>credit <description>Laptops 100.00 100.00 VH <currencydate>20150403 4340 VH <debitcredit>credit <description>BTW 19% 21.00 21.00
Handleiding BackOffice XML Connector Drukfouten voorbehouden, eventueel getoonde prijzen zijn fictief
- 5 -
3
Nostradamus
3.1
Push (_NOSTRA_PUSH_)
3.1.1 Input syntax(es) SETTINGS LOGIN GROUP_REC SUBGROUP_REC ARTICLES EMPL_REC POINT_REC HOUR_REC SALE_REC_TRS
SALE_REC_ITM
+ + account + UseHTTPS (T/F/0/1) + + TestMessage (T/F/0/1) + + Write XML input + + Write XML output + + + key + + + id + + office_id + + name + + + id + + parent + + office_id + + name + + + Plu.PK(article_id) + + group_id + + subgroup_id + + office_id + + name + + price + + tax + + state + + + Wtr.PK(employee_id) + + staff_id(can be empty) + + office_id + + name + + + id + + office_id + + name + + + id + + employee_id + + staff_id + + office_id + + department_id + + team_id + + enter + + exit + + + id of TRS(internal can be string of pk/uk/datetime) + office_id + + enter + + ticket_id + + table + + guests + + Wtr.PK(employee_id) + + staff_id(can be 0) + + erase(T/F/0/1) + + erase_date(empty if erase = 0) + !!! IF SALE_REC_TRS is used with erase_date then don't mix with normal sales, send separatly + + id of TRS(internal can be string of pk/uk/datetime) + datetime + + pos_id + + Plu.PK(article_id) + + ordering(can be 0) + + amount + + value + + Wtr.PK(employee_id) + + + staff_id(can be 0) + [is tag product under node sale]
3.1.2 Result codes 200
Call seems ok: GROUP_REC SUBGROUP_REC ARTICLES EMPL_REC POINT_REC HOUR_REC SALE_REC SALE_REC_ITM
200 + + OK + CR + + rows + + success + + failed + + + rows + + success + + failed + + + rows + + success + + failed + + + rows + + success + + failed + + + rows + + success + + failed + + + rows + + success + + failed + + + rows + + success + + failed + + + products + + success + + failed +
902 903 9001
Error with call, result is no valid xml document Error with call, no 200 result: 903 + + + Error with call for login + + Error
Handleiding BackOffice XML Connector Drukfouten voorbehouden, eventueel getoonde prijzen zijn fictief
- 6 -
3.1.3 Voorbeeld Sturen van gemixte data: _NOSTRA_PUSH_ SETTINGS unitouch true LOGIN ZcpWf7f7^Z3tDX GROUP_REC 1 GROUP_REC 2 GROUP_REC 3 GROUP_REC 4 GROUP_REC 5 SUBGROUP_REC 1 SUBGROUP_REC 2 ARTICLE_REC 101 ARTICLE_REC 301 ARTICLE_REC 805 EMPL_REC 2 1195 EMPL_REC 3 EMPL_REC 4 EMPL_REC 5 EMPL_REC 6 EMPL_REC 7 EMPL_REC 8 EMPL_REC 9 POINT_REC 1 POINT_REC 2 POINT_REC 3 HOUR_REC 1 9 HOUR_REC 1 9 HOUR_REC 1 9 HOUR_REC 1 9 SALE_REC_TRS 148_148 SALE_REC_ITM 148_148 SALE_REC_ITM 148_148
true
true
true
1 Dranken 1 Bijgerechten 1 Voorgerechten 1 Hoofdgerechten 1 Nagerechten 1 1 Alcoholische Dranken 2 1 Salades 1 1 1 Koffie 2.25 6 1 1 1 1 Amaretto 4.25 21 1 2 2 1 Makreel maaltijd salade 6.75 1 Ober2 1 Ober3 1 Ober4 1 Ober5 1 Ober6 1 Ober7 1 Ober8 1 Chantal 1 Kassa node 1 1 Kassa node 2 1 Kassa node 3 0 1 1 1 2015-06-03 11:00:00 0 1 1 1 2015-06-03 11:45:00 0 1 1 1 2015-06-04 10:53:00 0 1 1 1 2015-06-03 09:59:00 1 2015-03-25 12:03:24 148 301 0 2015-03-25 11:38:24 1 101 0 1 2015-03-24 12:02:55 1 805 0 1
6
1
2015-06-03 2015-06-03 2015-06-04 2015-06-03 3 0 2.25 9 6.75 9
20:02:00 20:19:00 20:16:00 19:53:00 false 0 0
Sturen van een wiscommando van verkopen op een bepaalde datum (niet mixen met andere omzet data): _NOSTRA_PUSH_ SETTINGS unitouch true LOGIN ZcpWf7f7^Z3tDX SALE_REC_TRS dummy
3.2
true
true
true
0
""
0
0
0
0
0
true
2015-03-25
Fetch (_NOSTRA_FETCH_)
3.2.1 Input syntax(es) SETTINGS LOGIN FETCHTYPES
+ + + +
+ + + +
account + UseHTTPS (T/F/0/1) + + TestMessage (T/F/0/1) Write XML input + + Write XML output + key + staff, planning, new_reservations, cancelled_reservations, edited_reservations>
3.2.2 Result codes 200
902 903 9001
Call seems ok: 200 + + OK + CR STAFF + + id + + name + + lastname + + key_id(wtr.pk?) + SCHEDULE + + date + + name + + start + + end + + workplace_id + + workplace_name + Error with call, result is no valid xml document Error with call, no 200 result: 903 + + + Error with call for login + + Error
3.2.3 Voorbeeld _NOSTRA_FETCH_ SETTINGS unitouch true true LOGIN ZcpWf7f7^Z3tDX FETCHTYPES staff,planning
true
true
Handleiding BackOffice XML Connector Drukfouten voorbehouden, eventueel getoonde prijzen zijn fictief
- 7 -
4
BackOffice Online
4.1
Import (_BOONLINE_IMP_)
Import vraagt data op van de BackOffice Online (voor de BackOffice Online is dit dus een export)
4.1.1 Input syntax(es) SETTINGS LOGIN EXPORTTYPE FILTERTYPE
+ + + +
+ + + +
<settingtype> + + <setting value> + key + type (bijvoorbeeld ACCOUNT) + + + +
Settings opties: WRITEINPUT Schrijf een input bestand "BOONLINE_IMP_IN_.xml" WRITEOUTPUT Schrijf een input bestand "BOONLINE_IMP_OUT_.xml" SOAPSERVER niet verplicht: svc3.unitouch.eu <= svr2.unitouch.eu voor testomgeving WS_POSTACTION niet nodig (standaard waarde is /UNITOUCHCRM_SOAPSERVER_WEB/awws/UnitouchCRM_SoapServer.awws) ID__BoCompanyID Bedrijfsnummer BackOffice Online gebruiker UserName Inlognaam BackOffice Online gebruiker UserPass wachtwoord BackOffice Online gebruiker
4.1.2 Export Types (meerdere regels /types mogelijk) ACCOUNT BODEALERS BOUSERS ORDERS PROJECTS HOURS
Binnenhalen Binnenhalen Binnenhalen Binnenhalen Binnenhalen Binnenhalen
van van van van van van
de accounts (klanten) van BackOffice Online CRM de Dealers in BackOffice Online de gebruikers van ingelogd bedrijf (SETTING ID__BoCompanyID) de orders van BackOffice Online aangemaakte projecten in BackOffice Online CRM geregistreerde uren in BackOffice Online CRM
4.1.3 Filtertype opties De filter type opties zijn afhankelijk van de export types. EXPORTTYPE ACCOUNT: Filter naam ========================== acc.SyncType acc.LimitFromTo
verpl. ====== nee nee
acc.ResultAccountsFields
nee
acc.ResultAddressFields
nee
acc.ResultContactsFields
nee
acc.ID__AccountsID
nee
omschrijving ========================================================= modified / full (standaard is modified) je kan in blokken binnenhalen, syntax: <start,count> bijvoorbeeld: "1,200", daarna "200,200" etc... Velden die je wilt binnenhalen, niet opgegeven zijn alle velden. Velden die je wilt binnenhalen, niet opgegeven zijn alle velden. Velden die je wilt binnenhalen, niet opgegeven zijn alle velden. Filter op een account (acc.LimitFromTo wordt genegeerd)
EXPORTTYPE BODEALERS: Filter naam verpl. omschrijving ========================== ====== =========================================================
EXPORTTYPE BOUSERS: Filter naam verpl. omschrijving ========================== ====== =========================================================
Handleiding BackOffice XML Connector Drukfouten voorbehouden, eventueel getoonde prijzen zijn fictief
- 8 -
EXPORTTYPE ORDERS: Filter naam ========================== cOrder.FromDate cOrder.TillDate cOrder.IgnoreMarking
verpl. ====== ja nee nee
cOrder.LimitFromTo
nee
cOrder.ResultOrderFields
nee
cOrder.ResultOrderRowFields nee
omschrijving ========================================================= Vanaf datum om de orders te ontvangen (yyyymmdd) Tot datum om de orders te ontvangen (yyyymmdd) Als true (true/1), alle (ook ongewijzigde) orders worden toegevoegd aan het result je kan in blokken binnenhalen, syntax: <start,count> bijvoorbeeld: "1,200", daarna "200,200" etc... Velden die je wilt binnenhalen, niet opgegeven zijn alle velden. Velden die je wilt binnenhalen, niet opgegeven zijn alle velden.
EXPORTTYPE PROJECTS: Filter naam verpl. omschrijving ========================== ====== ========================================================= cProject.ID__BoUserID nee Filter op een gebruiker
EXPORTTYPE HOURS: Filter naam ========================== hours.FromDate hours.TillDate hours.ID__BoUserID hours.ID__AccountsID hours.ID__cProjectsID hours.ID__TicketsID
verpl. ====== ja nee nee nee nee nee
omschrijving ========================================================= Vanaf datum om de uren te ontvangen (yyyymmdd) Tot datum om de uren te ontvangen (yyyymmdd) Filter op een gebruiker Filter op een account Filter op een project Filter op een ticket
4.1.4 Result codes 200 901 902 903 990 999 9001
Call seems ok: 200 + + OK + Error with http call (901 + + Error description) exception parsing xml result from server (902 + + Result + + Exception) HTTP result code other then 200! (903 + + HTTP Code + + Result) Fault envelope from server (990 + + fault code + + fault description) Various errors, read description (999 + + ErrorCode + + Description) Various errors, read description (9001 + + Exception)
Bij 999 krijg je de error code en omschrijving terug: 999 + + Errorcode + + Description ( is omgezet naar \n) ErrorCodes: 801 DateTimeForSession not between timeframe! 802 No valid login credentials! 803 Invalid session key! 900 Filter 'LimitFromTo', syntax error (<startpos>,) 901 Filter 'LimitFromTo', syntax error startpos and count must be higher then 0! 903 Query fout 940 ORDERS: no valid cOrder.FromDate given ! 9001 Exception in Call! + \n + <exception description>
Bij 200 OK krijg je afhankelijk van je De eerste records zijn standaard: Succeeded + + aantal Failed + + aantal PartiallyFailed + + aantal
aanvraag diverse regels met data terug. gelukt + exporttypes compleet mislukt + mislukt +
Per ExportType krijg je een regel met het resultaat: EXPORTTYPERESULT_<ExportType> + + <errorcode> + + Dus bijvoorbeeld: EXPORTTYPERESULT_ACCOUNTS + + 901 + + Filter 'LimitFromTo', syntax error startpos and count must be higher then 0! Als je errorcode 0 krijgt is alles gelukt voor dit export type
Handleiding BackOffice XML Connector Drukfouten voorbehouden, eventueel getoonde prijzen zijn fictief
- 9 -
EXPORTTYPE ACCOUNT: ACCOUNTS (eerste regel) ACCOUNTS (volgend) ADDRESSES (eerste regel) ADDRESSES (volgend) CONTACTS (eerste regel) CONTACTS (volgend)
+ + + + + +
+ + + + + +
Veldnamen gescheiden met Waarde per veldnaam gescheiden met Veldnamen gescheiden met Waarde per veldnaam gescheiden met Veldnamen gescheiden met Waarde per veldnaam gescheiden met
Bij ACCOUNT zitten de adressen en contacten aan het ID van accounts gekoppeld, dit ID komt altijd mee ongeacht of je specifieke velden hebt opgegeven. Het ID is: ID__AccountsID
EXPORTTYPE BODEALERS: BODEALER (eerste regel) BODEALER (volgend)
+ + Veldnamen gescheiden met + + Waarde per veldnaam gescheiden met
Bij BODEALERS komt het ID altijd mee ongeacht of je specifieke velden hebt opgegeven. Het ID is: ID__BoDealerID
EXPORTTYPE BOUSERS: BOUSER (eerste regel) BOUSER (volgend)
+ + Veldnamen gescheiden met + + Waarde per veldnaam gescheiden met
Bij BOUSERS komt het ID altijd mee ongeacht of je specifieke velden hebt opgegeven. Het ID is: ID__BoUserID
EXPORTTYPE ORDERS: ORDER (eerste regel) ORDER (volgend) ORDERROW (eerste regel) ORDERROW (volgend)
+ + + +
+ + + +
Veldnamen gescheiden met Waarde per veldnaam gescheiden met Veldnamen gescheiden met Waarde per veldnaam gescheiden met
Bij ORDER komt het ID altijd mee ongeacht of je specifieke velden hebt opgegeven. Het ID is: ID__cOrderID Bij ORDERROWS komt het ID altijd mee ongeacht of je specifieke velden hebt opgegeven. Het ID is: ID__cOrderRowID Bij ORDERROWS komen ook de volgende velden mee: RootID__ID__cOrderRowID, de order regel hoort bij het ID van een andere order regel (denk aan modules van de BackOffice) RootID__cPluID, de order regel hoort bij een andere PLU RootID__cMixedPluID, de order regel hoort bij een samengesteld PLU (ID__cMixedPluID)
EXPORTTYPE PROJECTS: PROJECT (eerste regel) PROJECT (volgend)
+ + Veldnamen gescheiden met + + Waarde per veldnaam gescheiden met
Bij PROJECT komt het ID altijd mee ongeacht of je specifieke velden hebt opgegeven. Het ID is: ID__WorkHoursID
EXPORTTYPE HOURS: HOUR (eerste regel) HOUR (volgend)
+ + Veldnamen gescheiden met + + Waarde per veldnaam gescheiden met
Bij HOURS komt het ID altijd mee ongeacht of je specifieke velden hebt opgegeven. Het ID is: ID__WorkHoursID
Handleiding BackOffice XML Connector Drukfouten voorbehouden, eventueel getoonde prijzen zijn fictief
- 10 -
4.2
Sync (_BOONLINE_SYNC_)
Sync synchroniseert gegevens naar de Unitouch BackOffice Online. Momenteel alleen gebruikt om gemarkeerde records die je geïmporteerd hebt te markeren als geïmporteerd.
4.2.1 Input syntax(es) SETTINGS LOGIN SYNCTYPE FILTERTYPE
+ + + +
