XML ImportExport Interface UniFLOWHelix - V1.4
XML ImportExport Interface UniFLOWHelix - V1.4
Version 5.x
Version 2.x
Table of Contents
Foreword 1 2 3 4
4.1 4.2 4.3
4.3.1 4.3.2 4.3.3 4.3.4 4.3.5 4.3.6 4.3.7 4.3.8
0 1 1 2 2
2 4 5
XML MOMIO Element ......................................................................................................................................................... 5 XML USER Element ......................................................................................................................................................... 7 XML USER-BUDGET Element ......................................................................................................................................................... 9 XML COSTCENTER Element ......................................................................................................................................................... 11 XML COSTCENTER-BUDGET Element ......................................................................................................................................................... 13 XML GROUP Element ......................................................................................................................................................... 15 XML GROUP-BUDGET Element ......................................................................................................................................................... 16 DTD for Basic ......................................................................................................................................................... 18 Objects
4.4
4.4.1 4.4.2
19
Description of......................................................................................................................................................... 20 the single XML Elements DTD for Statistic Export ......................................................................................................................................................... 22
Index
Versioning Information
Versioning Information Version: Date: First Draw-up Date: Author: Revision history: 1.4 02.01.2012 08.04.2009 Karsten Huster Version: 1.0 1.1 1.2 1.3 1.4 Technologies concerned: Revision date: 08.04.2009 27.10.2009 05.11.2010 19.12.2011 02.01.2012
Karsten Huster
The information and technology in this White Paper refers to the date it was written or revised. We do our best to keep the content as up to date as possible.
Introduction
This document describes the import and export formats of the the two systems: uniFLOW and HelixPW. The import and export is essentially based on XML, therefore the XML programming language serves for the coding of all individual information. In principle, HelixPW and uniFLOW support two kinds of data export: the export of Base Data and the export of Statistical Data.
XML Structure
For the definition of the XML structure, we took great care to not only build a static interface for data import and export, but also to create an interactive interface for modifying or deleting data. All master data (user, groups and cost centers) are delivered as a single XML file. Both the parser on the HelixPW / uniFLOW side as well as the parser on the user side, are able to filter out the desired data.
Fundamentals
All records in the HelixPW / uniFLOW system are guided by a so-called GUID (Globally Unique Identifier). GUIDs make it possible to identifiy a record independently of the creating workstation. A GUID is invisible for the user. In general GUIDs are structured as follows: {475A965B-1714-42A4-9B35-698AB6506420} If a record is referenced in an XML, it is best to use the GUID field. However, the XML language also allows the use of a different field as an identifier, for example to exchange a record with a specific login. Building XML data for basic objects In the following you can find a description of the structure of an XML file for the HelixPW / uniFLOW system.
4.1
Example 1
Example 1: (Sample can also be found under: http://www.nt-ware.com/xml/mombsample.xml) <MOMIO> <USER action="add"> <NAME>Dagobert Duck</NAME> <ADDRESSONE>Street 12</ADDRESSONE> <ADDRESSTWO/> <ZIP>12345</ZIP> <CITY>DuckCity</CITY> <PHONE>123-132415</PHONE> <FAX>123-451515</FAX> <LOGIN>DagobertD</LOGIN> <TERMINALID /> <STDGROUP>{475A965B-1714-42A4-9B35-698AB6506420}</ STDGROUP> <STDCOSTCENTER>{ACF6E6A2-055B-4D87-AF54-A08B0512FE30}</
STDCOSTCENTER> </USER> <USER action="add" lookupkey="NAME" lookupvalue="Donald Duck"> <NAME>Donald Duck</NAME> <ADDRESSONE>Street 12</ADDRESSONE> <ADDRESSTWO>(second floor)</ADDRESSTWO> <ZIP>12345</ZIP> <CITY>DuckCity</CITY> <LOGIN>DonaldD</LOGIN> <TERMINALID>3312</TERMINALID> <STDGROUP/> <STDCOSTCENTER/> <BUDGET enabled="true"> <INITIALBALANCE>10.0000</INITIALBALANCE> <WARNINGBALANCE>2.0000</WARNINGBALANCE> <EXCEEDBEHAVIOUR>WarnOnly</EXCEEDBEHAVIOUR> <RESETTYPE>Overwrite</RESETTYPE> <RESETINTERVAL>Monthly</RESETINTERVAL> <NOTIFICATIONMETHOD>WebPopup</NOTIFICATIONMETHOD> </BUDGET> </USER> <USER action="remove" id="{B810A19CE-7641-42B9-82659E5D48C248C3}"/> <USER action="change" id="{8AFC938C-4652-489E-83C8A3457FF3CE62}"> <NAME>Robert Frost</NAME> </USER> <USER action="remove" lookupkey="LOGIN" lookupvalue="KarstenH"/> <USER action="change" lookupkey="NAME" lookupvalue="Robert Frost"> <LOGIN>RFrost</LOGIN> </USER> <COSTCENTER action="add"> <NAME>0 100 000</NAME> <DESCRIPTION>Technical Department, Drawings</ DESCRIPTION> <TERMINALID>1234</TERMINALID> </COSTCENTER> <GROUP action="add"> <NAME>Students</NAME> <DESCRIPTION>Students, who also print on Sundays</ DESCRIPTION> <TERMINALID>5547</TERMINALID> <STDCOSTCENTER>{ACF6E6A2-055B-4D87-AF54-A08B0512FE30}</ STDCOSTCENTER> </GROUP> </MOMIO>
The XML file carries out the following tasks: adding a user (Dagobert Duck) changing and adding a user (Donald Duck), search criteria is the name; This user also has a budget monitoring. deleting a user with a certain ID changing the name of a user with a certain ID deleting a user with a certain login-name changing the login-name of a certain user, searched by name adding a cost center adding a group
4.2
Example 2
Example 2: In the following youll find another example with a meaningful configuration. <MOMIO> <COSTCENTER action="add" id="{ACF6E6A2-055B-4D87-AF54A08B0512FE30}"> <NAME>0 100 000</NAME> <DESCRIPTION>Technical Department, Drawings</ DESCRIPTION> <TERMINALID>1234</TERMINALID> </COSTCENTER> <GROUP action="add" id="{475A965B-1714-42A4-9B35698AB6506420}"> <NAME>Students</NAME> <DESCRIPTION>Students, who also print on Sundays</ DESCRIPTION> <TERMINALID>5547</TERMINALID> <STDCOSTCENTER>{ACF6E6A2-055B-4D87-AF54-A08B0512FE30}</ STDCOSTCENTER> </GROUP> <USER action="add" id="{8AFC938C-4652-489E-83C8A3457FF3CE62}"> <NAME>Dagobert Duck</NAME> <ADDRESSONE>Strasse 12</ADDRESSONE> <ADDRESSTWO/> <ZIP>12345</ZIP> <CITY>DuckCity</CITY> <PHONE>123-132415</PHONE> <FAX>123-451515</FAX> <LOGIN>DagobertD</LOGIN> <TERMINALID />
<BUDGET enabled="true"> <INITIALBALANCE>10.0000</INITIALBALANCE> <WARNINGBALANCE>2.0000</WARNINGBALANCE> <EXCEEDBEHAVIOUR>WarnOnly</EXCEEDBEHAVIOUR> <RESETTYPE>Overwrite</RESETTYPE> <RESETINTERVAL>Monthly</RESETINTERVAL> <NOTIFICATIONMETHOD>WebPopup</NOTIFICATIONMETHOD> </BUDGET> <STDGROUP>{475A965B-1714-42A4-9B35-698AB6506420}</ STDGROUP> <STDCOSTCENTER>{ACF6E6A2-055B-4D87-AF54-A08B0512FE30}</ STDCOSTCENTER> </USER> <USER action="add"> <NAME>Robert Frost</NAME> <LOGIN>RFrost</LOGIN> </USER> <USER action="remove" lookupkey="LOGIN" lookupvalue="KarstenH"/> </MOMIO>
4.3
The following tables show the format of the XML data records in detail:
4.3.1
Name
syncUsers
syncGroups
Attribute
Set group handling. Only when importing true deletes all group accounts in HelixPW / uniFLOW if they are not part of this XML file false adds all groups from this XML file to HelixPW / uniFLOW without deleting known HelixPW / uniFLOW accounts (default)
syncCostCenters
Attribute
Set cost center handling. Only when importing true deletes all cost centers accounts in HelixPW / uniFLOW if they are not part of this XML file false adds all cost centers from this XML file to HelixPW / uniFLOW without deleting known HelixPW / uniFLOW accounts (default)
4.3.2
Name
action
Attribute Shows the action. Only when importing add adding or changing a record (default) deleting a record changing a record remove change
Id lookupkey lookupvalue
Attribute Shows the GUID of the record when changing, deleting or exporting Attribute Shows the data base field according to which a record should be selected. Only when importing. Attribute Shows the value of a data base field according to which a record should be selected. Only when importing. Attribute Determines, whether existing identities will be deleted on import. Only when importing. yes all identities attached to the user account will be deleted. no identities attached to the user account will be preserved, new identities will be added
removeothers
type
Attribute Specifies the identity type used in the IDENTITY element. Can have the following values: SMTPMailAddress LDAPLogin HostLogin CardNumber PINCode IMEINumber TIC InternetGatewayLogin Attribute Determines, whether the identity specified in the IDENTITY element will be the default identity after import. yes|no
default
IDENTITIES* IDENTITY*
Element Identity section, can contain one or more IDENTITY elements. Element Specifies one identity of the user.
NAME ADDRESSONE ADDRESSTWO ZIP CITY PHONE FAX LOGIN TERMINALID STDGROUP STDCOSTCENTER EMAIL SAPNAME PERSONALFOLDER
Element Name of the user Element Address 1 of the user Element Address 2 of the user Element Zip code Element City Element Telephone number Element Fax number Element Login name Element Chipcard number Element ID of the standard group Element ID of the standard cost center Element Email address of the user Element Special field for the SAP username Element Used for the SMTP Email gateway to send to a personal folder. Works just with an XML import and cannot be exported. Element The timestamp contains the time when HelixPW / uniFLOW wrote the descriptor file, as the time of the actual scan is unknown to HelixPW / uniFLOW. HelixPW / uniFLOW only knows when the iR sent the scan. The TIMESTAMP uses the following format: "yyyymmddhhmmss".
TIMESTAMP
PIN
Element PIN Code of the user. Works with an XML import only and cannot be exported.
4.3.3
Name
enabled
WARNINGBALANCE INITIALBALANCE
Element Element The start balance, and also the updated balance value, if the RESETINTERVAL is not set to None. Element The behavior on exceeding the balance None Nothing happens WarnOnly The user gets a warning information, but the print job will be printed Block The user gets a warning, that his print job will be deleted BlockColorOnly The user gets a warning, that his print/copy job will be deleted, if the job includes color.
EXCEEDBEHAVIOUR
RESETTYPE
Element The Reload Behavior Add - Adds the INITIALBALANCE after the RESETINTERVAL to the CURRENTBALANCE Overwrite Reset the CURRENTBALANCE to the INITIALBALANCE after the RESETINTERVAL Element Sets the reload interval for the balance update Never never Daily daily update Weekly weekly update Monthly monthly update quarterly update yearly update method for the
RESETINTERVAL
Element The current balance. Only for export. Element To set or influence a budget. Use the following syntax: <VALUE action="add">12.50</VALUE> Attribute action The following values for the attribute action are possible: add - simply adds the given amount to the current budget reset - Sets the budget back to '0.00', the value is ignored new - Sets the budget to the value given ignore - does nothing
4.3.4
Name
action
Attribute Shows the action. Only when importing add adding and changing a record (default) deleting a record changing a record remove change
Id lookupkey lookupvalue
Attribute Shows the GUID of the record when changing, deleting or exporting Attribute Shows the data base field according to which a record should be selected. Only when importing. Attribute Shows the value of a data base field according to which a record should be selected. Only when importing. Attribute Determines, whether existing identities will be deleted on import. Only when importing. yes all identities attached to the user account will be deleted. no identities attached to the cost center will be preserved, new identities will be added
removeothers
type
Attribute Specifies the identity type used in the IDENTITY element. Can have the following values: SMTPMailAddress LDAPLogin HostLogin CardNumber PINCode IMEINumber TIC InternetGatewayLogin Attribute Determines, whether the identity specified in the IDENTITY element will be the default identity after import. yes|no
default
IDENTITIES* IDENTITY*
Element Identity section, can contain one or more IDENTITY elements. Element Specifies one identity of the cost center
Element Name of the cost center Element Description of the cost center Element Number of the cost center at the PayCon (keyboard entry) or on a chip card. Element Configure a linked parent cost center via a key/ value lookup or via the GUID: <PARENT lookupkey="key" lookupvalue="value"> {guid} </PARENT> Element Configure an unlinked cost center. Enter digits 1 - 9 to specify the hierarchy level: <HIERARCHYLEVEL>2</HIERARCHYLEVEL>
HIERARCHYLEVEL**
**
Within one <COSTCENTER> element, either <PARENT> or <HIERARCHYLEVEL> can be used, never both.
4.3.5
Name
enabled
action
Attribute The following values for the attribute action are possible: add - Simply adds the given amount to the current budget. reset - Sets the budget back to '0.00', the value is ignored. d - Sets the budget to the value given. ignore - Does nothing.
WARNINGBALANCE INITIALBALANCE
Element Element The start balance, and also the updated balance value, if the RESETINTERVAL is not set to None. Element The behaviour on exceeding the balance None Nothing happens WarnOnly The user gets a warning information but the print job will be printed Block The user gets a warning that his print job will be delete BlockColorOnly The user gets a warning that his print/copy job will be deleted, if the job includes color
EXCEEDBEHAVIOUR
RESETTYPE
Element The Reload Behaviour Add - Adds the INITIALBALANCE after the RESETINTERVAL to the CURRENTBALANCE Overwrite Reset the CURRENTBALANCE to the INITIALBALANCE after the RESETINTERVAL Element Set the reload interval for the balance update Never Daily Weekly never daily update weekly update
RESETINTERVAL
Monthly
Element Set the notification EXCEEDBEHAVIOUR. None Email no notification notification via email
Element The current balance. Only for export. Element To set or influence a budget. Use the following syntax: <VALUE action="add">12.50</VALUE>
4.3.6
Name
Action
Id Lookupkey
Attribute Attribute
Shows the GUID of the record when changing, deleting or exporting Shows the data base field according to which a record should be selected. Only when importing. Shows the value of a data base field according to which a record should be selected. Only when importing.
Lookupvalue
Attribute
Name of the group. Description of the group. ID of the standard cost center. Number of the group at the PayCon (keyboard entry) or on a chip card.
4.3.7
Name
enabled
action
Attribute The following values for the attribute action are possible: add - simply adds the given amount to the current budget reset - Sets the budget back to '0.00', the value is ignored new - Sets the budget to the value given ignore - does nothing
WARNINGBALANCE INITIALBALANCE
Element Element The start balance, and also the updated balance value, if the RESETINTERVAL is not set to None. Element The behavior on exceeding the balance None Nothing happens WarnOnly The user gets a warning information but the print job will be printed Block The user gets a warning that his print job will be deleted BlockColorOnly The user gets a warning that his print/copy job will be deleted, if the job includes color
EXCEEDBEHAVIOUR
RESETTYPE
Element The Reload Behavior. Add - Adds the INITIALBALANCE after the RESETINTERVAL to the CURRENTBALANCE Overwrite Reset the CURRENTBALANCE to the INITIALBALANCE after the RESETINTERVAL Element Set the reload interval for the balance update. Never Daily Weekly never daily update weekly update
RESETINTERVAL
Monthly
Element Set the notification EXCEEDBEHAVIOUR. None Email Log no notification notification via email
WebPopup
CURRENTBALANCE VALUE
Element The current balance. Only for export. Element To set or influence a budget. Use the following syntax: <VALUE action="add">12.50</VALUE>
4.3.8
The following DTD can be used for validating the XML I/O language: (copy available under http://www.nt-ware.com/xml/momobjio.dtd) <!DOCTYPE MOMIO [ <!ELEMENT MOMIO (COSTCENTER*, GROUP*,USER*) > <!ELEMENT USER (NAME?,ADDRESSONE?,ADDRESSTWO?,ZIP?,CITY?, PHONE?,FAX?,LOGIN?,TERMINALID?,STDGROUP?,STDCOSTCENTER?) > <!ELEMENT COSTCENTER (NAME?,DESCRIPTION?,TERMINALID?,PARENT?, HIERARCHYLEVEL?) > <!ELEMENT GROUP (NAME?,DESCRIPTION?,TERMINALID?, STDCOSTCENTER?) > <!ATTLIST USER action CDATA "" id CDATA "" lookupvalue CDATA "" lookupkey CDATA "" > <!ATTLIST COSTCENTER action CDATA "" id CDATA "" lookupvalue CDATA "" lookupkey CDATA "" > <!ATTLIST GROUP action CDATA "" id CDATA "" lookupvalue CDATA "" lookupkey CDATA "" > <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT ]> NAME (#PCDATA) > ADDRESSONE (#PCDATA) > ADDRESSTWO (#PCDATA) > ZIP (#PCDATA) > CITY (#PCDATA) > PHONE (#PCDATA) > FAX (#PCDATA) > LOGIN (#PCDATA) > TERMINALID (#PCDATA) > STDGROUP (#PCDATA) > STDCOSTCENTER (#PCDATA) > DESCRIPTION (#PCDATA) >
4.4
In the following the structure of the XML interface for data export is described: (also available under http://www.nt-ware.com/xml/momsample.xml) <?xml version = "1.0" standalone="yes" ?> <MOMSTAT> <STATENTRY id="{4597E5C5-BE71-4584-B6B8-A136CB123AAD}"> <SERVICE id="{BFB52142-D1AE-11D4-8F1D-0010A4A4E1AA}" type="196609">Druck DIN A4</SERVICE> <USER id="{57890D70-D1D3-11D4-8F1F0010A4A4E1AA}">KarstenH</USER> <PRINTER id="{59DADAD6-8191-4586-BEFD118691D5C4E1}">Canon CLC 1000</PRINTER> <GROUP id="{475A965B-1714-42A4-9B35698AB6506420}">Employee</GROUP> <COSTCENTER id="{94C34CA8-9C69-4390-A69EEE9062D88FF5}">0 100 000</COSTCENTER> <CARDINALITY>12</CARDINALITY> <PRICE>1.30</PRICE> <CARDNUMBER/> <TIMEBEGIN>2001/05/24 12:30:00</TIMEBEGIN> <TIMEEND>2001/05/24 12:31:02</TIMEEND> <SUBSERVICE id="{1319A3A6-2D53-49D9-9F8F-E9C18FDED4DB}" type="524291"> <NAME>HolePunching</NAME> <PDLNAME>*FinisherOptPunch</PDLNAME> <CARDINALITY>12</CARDINALITY> <PRICE>0.00</PRICE> </SUBSERVICE> <SUBSERVICE id="{F154A632-336F-4F7D-987D-3FCF7CB12DF7}" type="524292"> <NAME>Stapling</NAME> <PDLNAME>*EFOptionSorter</PDLNAME> <CARDINALITY>12</CARDINALITY> <PRICE>0.00</PRICE> </SUBSERVICE> </STATENTRY> </MOMSTAT> The general structure follows the rules described below: Each single statistical entry is a STATENTRY element. Within the STATENTRY elements, the linked users, groups and cost centers are stated. For further attributes, for example stapling or hole punching, SUBSERVICE elements are inserted.
All elements are listed with their GUID, if existing in the data structure. By the GUID or the name a link can be created in other applications.
4.4.1
Name
SERVICE
Element -
USER
Element -
PRINTER
Element -
GROUP
Element -
COSTCENTER
Element -
Element JJJJ/ Shows the time, when the entry has started, for MM/TT example when the print job has reached the HH:MM: spooler. SS Element JJJJ/ Shows the time, when the entry has been MM/TT finished, for example when the print job has been HH:MM: taken out of the spooler. SS Element Further options for a print job, for example stapling, hole punching, sorting etc. CARDINALITY and PRICE element show how often the option has been used; attribute type or element NAME show the kind of option taken.
TIMEEND
SUBSERVICE
Description None / empty General copy DIN A4 copy DIN A3 copy DIN B4 copy DIN B3 copy colour DIN A4 copy colour DIN A3 copy colour DIN B4 Copy colour DIN B3 print DIN A4 print DIN A3 print DIN B4 print DIN B3 print colour DIN A4 print colour DIN A3 print colour DIN B4 print colour DIN B3 finishing option Cutter Finishing option Sorter Finishing Punching option
Type HEX 0 0xFFFFFFFF 0x00010001 0x00010002 0x00010003 0x00010004 0x00020001 0x00020002 0x00020003 0x00020004 0x00030001 0x00030002 0x00030003 0x00030004 0x00040001 0x00040002 0x00040003 0x00040004 0x00080001 0x00080002 Hole 0x00080003 0x00080004
Type Decimal 0 -1 65537 65538 65539 65540 131073 131074 131075 131076 196609 196610 196611 196612 262145 262146 262147 262148 524289 524290 524291 524292
0x00080005
524293
4.4.2
The following DTD validates the statistic export: (also available under http://www.nt-ware.com/xml/MOMSTAT.dtd)
< !DOCTYPE
MOMSTAT [ <!ELEMENT MOMSTAT (STATENTRY*) > <!ELEMENT STATENTRY (SERVICE,USER,PRINTER,GROUP,COSTCENTER, CARDINALITY,PRICE,CARDNUMBER?, TIMEBEGIN,TIMEEND,SUBSERVICE*) > <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT <!ELEMENT SERVICE (#PCDATA) > USER (#PCDATA) > PRINTER (#PCDATA) > GROUP (#PCDATA) > COSTCENTER (#PCDATA) > CARDINALITY (#PCDATA) > PRICE (#PCDATA) > CARDNUMBER (#PCDATA) > TIMEBEGIN (#PCDATA) > TIMEEND (#PCDATA) >
<!ELEMENT SUBSERVICE (NAME,PDLNAME,CARDINALITY,PRICE) > <!ELEMENT NAME (#PCDATA) > <!ELEMENT PDLNAME (#PCDATA) > <!ATTLIST SERVICE id CDATA "" type CDATA "" > <!ATTLIST STATENTRY id CDATA "" > <!ATTLIST USER id CDATA "" > <!ATTLIST PRINTER id CDATA "" > <!ATTLIST GROUP id CDATA "" > <!ATTLIST COSTCENTER id CDATA "" > <!ATTLIST SUBSERVICE id CDATA "" type CDATA "" > ]>