Difference between revisions of "Matching service manual"

From 1Archive help
Jump to: navigation, search
(Created page with "==What?== The matching web-service implementation allows users, which are assigned to the web-service, to pull XML documents waiting for matching or to push matching results t...")
(No difference)

Revision as of 15:26, 24 October 2016

1 What?

The matching web-service implementation allows users, which are assigned to the web-service, to pull XML documents waiting for matching or to push matching results to the 1Archive archive.
The pushed data contains matching results. The pulled data will contain documents to be matched.

2 Register for matching

In order to get a user for external matching a request has to be filled in using this form.
After validation Onea will supply you with login credentials, the WS URL and the webservice name.

3 The web-service request and response

All actions of the web-service are called in a consistent way of working. The table below explains the basic set of parameters that should be specified for the request.

user The username provided by Onea after registration.
password The password provided by Onea after registration.
serviceName Name of the service configuration that should be called. Provided by Onea after registration.
action PULL_MATCHING_DOCUMENTS, PUSH_MATCHING.
request A string value containing the data that will be processed by the implemented web-service action. This will be a Base64 encoded XML.

The response of the web-service will return a Base 64 Encoded XML

4 Actions

There are 2 actions available for the matching:

4.1 PULL_MATCHING_DOCUMENTS

Via the PULL_MATCHING_DOCUMENTS action, documents assigned to the user performing the webservice call can be downloaded. The number of documents to fetch are limited to 20 per batch.

Request 

<soapenv:Envelope xmlns:soapenv=http://schemas.xmlsoap.org/soap/envelope/
                  xmlns:web="http://webservice.connectors.onea.be/">
   <soapenv:Header/>
    <soapenv:Body>
       <web:invoke>
           <user>###</user>
           <password>###</password>
           <serviceName>###</serviceName>
           <action>PULL_MATCHING_DOCUMENTS</action>
       </web:invoke>
    </soapenv:Body>
</soapenv:Envelope>


Result of the PULL_MATCHING_DOCUMENTS action, a Base64 encoded XML in the ScanPro Transfer Format (Appendix 1) is returned. The XML contains only the data concerning the documents. 

<soapenv:Envelope xmlns:soapenv=http://schemas.xmlsoap.org/soap/envelope/
                  xmlns:web="http://webservice.connectors.onea.be/">
   <soap:Body>
       <web:invokeResponse>
           <return>###</return>
       </web:invokeResponse>
   </soapenv:Body>
</soapenv:Envelope>

In case an error occurred (an invalid user for example), the return will not be Base64 encoded and the result will comply the XSD in Appendix 4.

4.2 PUSH_MATCHING

Via the PUSH_MATCHING action the result of the matching can be passed to the 1Archive application. The request should comply to the xsd specified in (Appendix 2). In the request you will need to pass the document id, the remarks and the matching status. Match or no match. When you send the match result, the document will be approved and will continue on in the approval flow. If there is no match the document will be rejected.

Request 

<soapenv:Envelope xmlns:soapenv=http://schemas.xmlsoap.org/soap/envelope/
                  xmlns:web="http://webservice.connectors.onea.be/">
   <soapenv:Header/>
    <soapenv:Body>
       <web:invoke>
           <user>###</user>
           <password>###</password>
           <serviceName>###</serviceName>
           <action>PUSH_MATCHING</action>
           <request>###</request>
       </web:invoke>
    </soapenv:Body>
</soapenv:Envelope>

As result of the PULL_MATCHING_DOCUMENTS action, a Base64 encoded XML in the ScanPro response format (Appendix 3) is returned. 

<soapenv:Envelope xmlns:soapenv=http://schemas.xmlsoap.org/soap/envelope/
                  xmlns:web="http://webservice.connectors.onea.be/">
   <soap:Body>
       <web:invokeResponse>
           <return>###</return>
       </web:invokeResponse>
   </soapenv:Body>
</soapenv:Envelope>

5 Appendix 1

Note.png This is a subset of the official 1Archive Transfer Format where only the relevant document section is filled out. 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" version="1.0">
    <xs:element name="TRANSFER" type="modScanProTransfer"/>
        <xs:complexType name="modScanProTransfer">
            <xs:sequence>
                <xs:element name="DOCUMENT" type="DOCUMENT" minOccurs="0" maxOccurs="unbounded"/>
                <xs:element name="ERRORMESSAGE" type="xs:string" minOccurs="0"/>
            </xs:sequence>
        </xs:complexType>
        <xs:complexType name="DOCUMENT">
            <xs:sequence>
                  <xs:element name="ATTACHMENTS" type="ATTACHMENTS" minOccurs="0"/>
                  <xs:element name="DETAILLINES" type="DETAILLINES" minOccurs="0"/>
                  <xs:element name="DOCUMENTID" type="xs:string" minOccurs="0"/>
                  <xs:element name="EXTERNALREFERENCE" type="xs:string" minOccurs="0"/>
                  <xs:element name="HEADER" type="HEADER" minOccurs="0"/>
                  <xs:element name="INVALIDATIONREASON" type="xs:string" minOccurs="0"/>
                  <xs:element name="MATCH" type="MATCH" minOccurs="0" maxOccurs="unbounded"/>
                  <xs:element name="NOTES" type="NOTES" minOccurs="0"/>
                  <xs:element name="POSTINGLINES" type="POSTINGLINES" minOccurs="0"/>
                  <xs:element name="TECHNICAL" type="TECHNICAL" minOccurs="0"/>
            </xs:sequence>
            <xs:attribute name="companyCode" type="xs:string"/>
            <xs:attribute name="documentTypeCode" type="xs:string"/>
            <xs:attribute name="id" type="xs:long"/>
            <xs:attribute name="instanceCode" type="xs:string"/>
            <xs:attribute name="isDeleted" type="xs:boolean"/>
            <xs:attribute name="receptionMethodCode" type="xs:string"/>
            <xs:attribute name="skipValidation" type="xs:boolean"/>
            <xs:attribute name="status" type="xs:string"/>
            <xs:attribute name="statusOrig" type="xs:string"/>
            <xs:attribute name="updateMode" type="modTransferUpdateMode"/>
            <xs:attribute name="workflowStatus" type="xs:string"/>
        </xs:complexType>
        <xs:complexType name="ATTACHMENTS">
            <xs:sequence>
                 <xs:element name="ATTACHMENT" type="ATTACHMENT" minOccurs="0" maxOccurs="unbounded"/>
            </xs:sequence>
            <xs:attribute name="clean" type="xs:boolean"/>
        </xs:complexType>
        <xs:complexType name="ATTACHMENT">
            <xs:simpleContent>
                 <xs:extension base="xs:string">
                    <xs:attribute name="contentType" type="xs:string"/>
                    <xs:attribute name="exportable" type="xs:boolean"/>
                    <xs:attribute name="fileName" type="xs:string"/>
                    <xs:attribute name="finishedPath" type="xs:string"/>
                    <xs:attribute name="id" type="xs:long"/>
                    <xs:attribute name="locked" type="xs:boolean"/>
                    <xs:attribute name="path" type="xs:string"/>
                    <xs:attribute name="publicKeyId" type="xs:long"/>
                    <xs:attribute name="removeAfterImport" type="xs:boolean"/>
                    <xs:attribute name="signatureId" type="xs:long"/>
                    <xs:attribute name="size" type="xs:long"/>
                    <xs:attribute name="sortOrder" type="xs:int"/>
                 </xs:extension>
            </xs:simpleContent>
        </xs:complexType>
        <xs:complexType name="DETAILLINES">
           <xs:sequence>
              <xs:element name="DETAILLINE" type="DETAILLINE" minOccurs="0" maxOccurs="unbounded"/>
           </xs:sequence>
           <xs:attribute name="clean" type="xs:boolean"/>
        </xs:complexType>
        <xs:complexType name="DETAILLINE">
           <xs:sequence>
              <xs:element name="FIELD" type="modTransferDetailLineField" minOccurs="0" maxOccurs="unbounded"/>
           </xs:sequence>
              <xs:attribute name="id" type="xs:long"/>
              <xs:attribute name="lineNumber" type="xs:int"/>
        </xs:complexType>
        <xs:complexType name="modTransferDetailLineField">
           <xs:simpleContent>
              <xs:extension base="FIELD"/>
           </xs:simpleContent>
        </xs:complexType>
        <xs:complexType name="FIELD">
           <xs:simpleContent>
              <xs:extension base="xs:string">
                 <xs:attribute name="code" type="xs:string"/>
                 <xs:attribute name="id" type="xs:long"/>
              </xs:extension>
           </xs:simpleContent>
        </xs:complexType>
        <xs:complexType name="HEADER">
           <xs:sequence>
              <xs:element name="FIELDOPTION" type="modTransferHeaderFieldOption" minOccurs="0" maxOccurs="unbounded"/>
              <xs:element name="FIELD" type="modTransferHeaderField" minOccurs="0" maxOccurs="unbounded"/>
           </xs:sequence>
        </xs:complexType>
        <xs:complexType name="modTransferHeaderFieldOption">
           <xs:simpleContent>
              <xs:extension base="FIELDOPTION"/>
           </xs:simpleContent>
        </xs:complexType>
        <xs:complexType name="FIELDOPTION">
           <xs:simpleContent>
              <xs:extension base="xs:string">
                 <xs:attribute name="code" type="xs:string"/>
              </xs:extension>
           </xs:simpleContent>
        </xs:complexType>
        <xs:complexType name="modTransferHeaderField">
           <xs:simpleContent>
              <xs:extension base="FIELD">
                 <xs:attribute name="ocrStatus" type="ocrStatus"/>
              </xs:extension>
           </xs:simpleContent>
        </xs:complexType>
        <xs:complexType name="MATCH">
           <xs:sequence/>
              <xs:attribute name="detailLineId" type="xs:long"/>
              <xs:attribute name="documentId" type="xs:long"/>
              <xs:attribute name="matchingCategoryId" type="xs:long"/>
              <xs:attribute name="postingLineId" type="xs:long"/>
        </xs:complexType>
        <xs:complexType name="NOTES">
           <xs:sequence>
              <xs:element name="NOTE" type="NOTE" minOccurs="0" maxOccurs="unbounded"/>
           </xs:sequence>
           <xs:attribute name="clean" type="xs:boolean"/>
        </xs:complexType>
        <xs:simpleType name="NOTE">
           <xs:restriction base="xs:string"/>
        </xs:simpleType>
        <xs:complexType name="POSTINGLINES">
           <xs:sequence>
              <xs:element name="POSTINGLINE" type="POSTINGLINE" minOccurs="0" maxOccurs="unbounded"/>
           </xs:sequence>
           <xs:attribute name="clean" type="xs:boolean"/>
        </xs:complexType>
        <xs:complexType name="POSTINGLINE">
           <xs:sequence>
              <xs:element name="FIELD" type="modTransferPostingLineField" minOccurs="0" maxOccurs="unbounded"/>
              <xs:element name="MATCH" type="MATCH" minOccurs="0" maxOccurs="unbounded"/>
           </xs:sequence>
           <xs:attribute name="id" type="xs:long"/>
           <xs:attribute name="lineNumber" type="xs:int"/>
        </xs:complexType>
        <xs:complexType name="modTransferPostingLineField">
           <xs:simpleContent>
              <xs:extension base="FIELD"/>
           </xs:simpleContent>
        </xs:complexType>
        <xs:complexType name="TECHNICAL">
           <xs:sequence>
              <xs:element name="FIELD" type="modTransferTechnicalField" minOccurs="0" maxOccurs="unbounded"/>
           </xs:sequence>
        </xs:complexType>
        <xs:complexType name="modTransferTechnicalField">
           <xs:simpleContent>
              <xs:extension base="FIELD"/>
           </xs:simpleContent>
        </xs:complexType>
        <xs:simpleType name="ocrStatus">
           <xs:restriction base="xs:string">
              <xs:enumeration value="NOT_IMPORTED"/>
              <xs:enumeration value="OCR_OK"/>
              <xs:enumeration value="OCR_NOTOK"/>
           </xs:restriction>
         </xs:simpleType>
         <xs:simpleType name="modTransferUpdateMode">
            <xs:restriction base="xs:string">
               <xs:enumeration value="ADD_ONLY"/>
               <xs:enumeration value="UPDATE_ONLY"/>
               <xs:enumeration value="ADD_OR_UPDATE"/>
               <xs:enumeration value="CLEAN_AND_ADD"/>
               <xs:enumeration value="DEACTIVATE_AND_ADD"/>
               <xs:enumeration value="REMOVE"/>
               <xs:enumeration value="DUPLICATE"/>
               <xs:enumeration value="DUPLICATE_AND_REPLACE"/>
            </xs:restriction>
         </xs:simpleType>
</xs:schema>

5.1 Example of a document

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TRANSFER>
   <DOCUMENT companyCode="NELE_NELE JVB" documentTypeCode="INCINV" id="2357" receptionMethodCode="C" status="NEW">
       <ATTACHMENTS clean="false">
           <ATTACHMENT contentType="application/pdf" exportable="true" fileName="sneeuwklokje.pdf" id="15450" size="95495" sortOrder="100"/>
       </ATTACHMENTS>
       <HEADER>
           <FIELD ocrStatus="NOT_IMPORTED" code="INVOICEINFO"></FIELD>
           <FIELD ocrStatus="NOT_IMPORTED" code="INVTYPE" id="5">F</FIELD>
           <FIELD ocrStatus="NOT_IMPORTED" code="INVTYPE_NAME" id="5">Invoice</FIELD>
           <FIELD ocrStatus="NOT_IMPORTED" code="JOURNAL" id="46267">AKF</FIELD>
           <FIELD ocrStatus="NOT_IMPORTED" code="JOURNAL_NAME" id="46267">Aankoop facturenboek</FIELD>
           <FIELD ocrStatus="NOT_IMPORTED" code="SUPPCODE" id="51589">1016</FIELD>
           <FIELD ocrStatus="NOT_IMPORTED" code="SUPPCODE_NAME" id="51589">'T BROODJESATELJEE BVBA</FIELD>
           <FIELD ocrStatus="NOT_IMPORTED" code="SUPPVATID">BE0808344649</FIELD>
           <FIELD ocrStatus="NOT_IMPORTED" code="PAYMENTTERM" id="46616">0</FIELD>
           <FIELD ocrStatus="NOT_IMPORTED" code="PAYMENTTERM_NAME" id="46616">0</FIELD>
           <FIELD ocrStatus="NOT_IMPORTED" code="INVOICENR">201606271</FIELD>
           <FIELD ocrStatus="NOT_IMPORTED" code="INVDATE">20160627</FIELD>
           <FIELD ocrStatus="NOT_IMPORTED" code="INVDUEDATE">20160627</FIELD>
           <FIELD ocrStatus="NOT_IMPORTED" code="YEAR" id="62689">2016</FIELD>
           <FIELD ocrStatus="NOT_IMPORTED" code="YEAR_NAME" id="62689">2016</FIELD>
           <FIELD ocrStatus="NOT_IMPORTED" code="COMMENT1"></FIELD>
           <FIELD ocrStatus="NOT_IMPORTED" code="OGM"></FIELD>
           <FIELD ocrStatus="NOT_IMPORTED" code="NETAMNT">100.00</FIELD>
           <FIELD ocrStatus="NOT_IMPORTED" code="VATAMNT">21.00</FIELD>
           <FIELD ocrStatus="NOT_IMPORTED" code="TOTAMNT">121.00</FIELD>
           <FIELD ocrStatus="NOT_IMPORTED" code="CURRENCY" id="46316">EUR</FIELD>
           <FIELD ocrStatus="NOT_IMPORTED" code="CURRENCY_NAME" id="46316">Euro</FIELD>
           <FIELD ocrStatus="NOT_IMPORTED" code="DISCAMNT"></FIELD>
           <FIELD ocrStatus="NOT_IMPORTED" code="QUICKVAT">FALSE</FIELD>
           <FIELD ocrStatus="NOT_IMPORTED" code="PAY">TRUE</FIELD>
           <FIELD ocrStatus="NOT_IMPORTED" code="BOOKINGINFO"></FIELD>
           <FIELD ocrStatus="NOT_IMPORTED" code="VOUCHERNR">3</FIELD>
           <FIELD ocrStatus="NOT_IMPORTED" code="VOUCHERDATE">20160627</FIELD>
       </HEADER>
       <POSTINGLINES clean="false">
           <POSTINGLINE lineNumber="1">
               <FIELD code="LINENETAMNT">100.00</FIELD>
               <FIELD code="ACCODE" id="45825">516230654</FIELD>
               <FIELD code="ACCODE_NAME" id="45825">HUUR MATERIEEL</FIELD>
               <FIELD code="VATTYPE" id="12">0</FIELD>
               <FIELD code="VATTYPE_NAME" id="12">Normal levy</FIELD>
               <FIELD code="VATRATE" id="10">3</FIELD>
               <FIELD code="VATRATE_NAME" id="10">21%</FIELD>
               <FIELD code="NONDED">0.00</FIELD>
               <FIELD code="PLACE"/>
               <FIELD code="PLACE_NAME"/>
               <FIELD code="UNIT"/>
               <FIELD code="UNIT_NAME"/>
               <FIELD code="SORT"/>
               <FIELD code="SORT_NAME"/>
               <FIELD code="LINEDESC"></FIELD>
               <FIELD code="VATFIELDS" id="29176">INCINV|F|0BE</FIELD>
               <FIELD code="VATFIELDS_NAME" id="29176">Inv [82] - BTW [59]</FIELD>
               <FIELD code="VATPCTG">0.21</FIELD>
           </POSTINGLINE>
       </POSTINGLINES>
       <TECHNICAL>
           <FIELD code="SCANBATCH"></FIELD>
           <FIELD code="SCANUSER"></FIELD>
           <FIELD code="SCANNINGDATE"></FIELD>
           <FIELD code="INCOMINGDATE">20160627105655</FIELD>
           <FIELD code="ACCOUNTANT">onea</FIELD>
           <FIELD code="BOOKINGDATE">20160628115230</FIELD>
           <FIELD code="CANCELREASON"/>
           <FIELD code="CANCELREASON_NAME"/>
           <FIELD code="TOFINISH"></FIELD>
           <FIELD code="TAXCOUNTRY" id="29036">BE</FIELD>
           <FIELD code="TAXCOUNTRY_NAME" id="29036">Belgium</FIELD>
       </TECHNICAL>
   </DOCUMENT>
</TRANSFER>

6 Appendix 2

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
 <xs:element name="TRANSFER" type="modScanProMatchTransfer"/>
 <xs:complexType name="modScanProMatchTransfer">
   <xs:sequence>
     <xs:element name="ERRORMESSAGE" type="xs:string" minOccurs="0"/>
     <xs:element name="MATCHRESULTS" type="modMatchResults" minOccurs="0"/>
   </xs:sequence>
 </xs:complexType>
<xs:complexType name="modMatchResults">
   <xs:sequence/>
   <xs:element name="MATCHRESULT" type="modMatchResult" minOccurs="0" maxOccurs="unbounded"/>
 </xs:complexType>
 <xs:complexType name="modMatchResults">
   <xs:sequence/>
   <xs:attribute name="comment" type="xs:string"/>
   <xs:attribute name="documentId" type="xs:long" use="required"/>
   <xs:attribute name="match" type="xs:boolean" use="required"/>
 </xs:complexType>
</xs:schema>

7 Appendix 3

<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
 <xs:element name="IMPORTRESPONSE" type="modXmlServiceImportResponse"/>
 <xs:complexType name="modXmlServiceImportResponse">
   <xs:sequence>
     <xs:element name="IMPORTRESPONSEITEM" type="importResponseItem" minOccurs="0" maxOccurs="unbounded"/>
     <xs:element name="STACKTRACE" type="xs:string" minOccurs="0"/>
   </xs:sequence>
   <xs:attribute name="status" type="responseStatus"/>
 </xs:complexType>
 <xs:complexType name="importResponseItem">
   <xs:sequence>
     <xs:element name="ERROR" type="xs:string" minOccurs="0" maxOccurs="unbounded"/>
     <xs:element name="ID" type="xs:long" minOccurs="0"/>
     <xs:element name="MESSAGE" type="xs:string" minOccurs="0"/>
   </xs:sequence>
   <xs:attribute name="skipCount" type="xs:int"/>
   <xs:attribute name="type" type="importType"/>
   <xs:attribute name="updateCount" type="xs:int"/>
 </xs:complexType>
 <xs:simpleType name="importType">
   <xs:restriction base="xs:string">
     <xs:enumeration value="DOCUMENT"/>
   </xs:restriction>
 </xs:simpleType>
 <xs:simpleType name="responseStatus">
   <xs:restriction base="xs:string">
     <xs:enumeration value="OK"/>
     <xs:enumeration value="ERROR"/>
     <xs:enumeration value="FATAL_ERROR"/>
   </xs:restriction>
 </xs:simpleType>
</xs:schema>

8 Appendix 4

<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <xs:element name="response" type="modResponse"/>
   <xs:complexType name="modResponse">
      <xs:sequence>
         <xs:element name="message" type="xs:string" minOccurs="0" maxOccurs="1"/>
      </xs:sequence>
      <xs:attribute name="status" type="responseStatus"/>
   </xs:complexType>
   <xs:simpleType name="responseStatus">
      <xs:restriction base="xs:string">
          <xs:enumeration value="OK"/>
          <xs:enumeration value="ERROR"/>
          <xs:enumeration value="FATAL_ERROR"/>
      </xs:restriction>
   </xs:simpleType>
</xs:schema>

9 Appendix 5

A sample application is provided, written in java.


The sample application is a Spring-Boot application that will use the webservice (PULL_DOCUMENTS) to retrieve the documents that can be matched. It will also provide a simple user interface allowing the user to match documents using the webservice (PUSH_DOCUMENTS).


Prerequisites :

- Zip file containing the sample application (File:Matching.zip)

- Credentials of a user that is allowed to perform matching.


How-to install :

1) unzip the sample application in a directory on your system.

2) fill out the properties in the src/main/resources/application.properties file. (server, port and the field codes according to your system)

3) start the application by typing the command "mvnw spring-boot:run" in the root directory of the unzipped application

4) open your preferred browser and enter "http://localhost:8080" in the address bar.

Retrieved from "https://help.onea.be/index.php?title=Matching_service_manual&oldid=1361"