Package ch.aeis.exchange.web.ws.exchange_1_0

Class ExchangeWS

  • public class ExchangeWS
extends Object
    The BVG Exchange Webservice.

    As webservices are by definition non transactional and we did not want to implement heavy weight WS Transaction protocols we require clients to acknowledge every action that isn't idempotent.

    • Constructor Detail

      • ExchangeWS

        public ExchangeWS()

    • Method Detail

      • ping

        public String ping()
        Checks general availability of the webservice.
        Returns:
        Current date and version.

      • submitDocument

        public String submitDocument​(String userName,
                             String password,
                             String xmlDoc)
                      throws ExchangeFault
        Submits a xml document to the webservice.

        The submitted document is persisted. Processing continues after the submitter acknowledges the successful submit by calling ackSubmit(String, String, String)

        CALLING THIS METHOD BY ITSELF DOES (almost) NOTHING. You MUST acknowledge the submit.

        If no acknowledge is received the submitted document will eventually be discarded.

        Parameters:
        userName - user name
        password - password
        xmlDoc - String containing a complete XML Doc of a supported schema. The XML Doc MUST be explicitly UTF-8 encoded (<?xml version="1.0" encoding="UTF-8"?>). BVG Exchange will deliver the submitted XML unchanged (unless migration between schema is required).
        Returns:
        docIdent identifying this submit and document. This docIdent can be seen as the external primary key of the document and is used to reference this document in various other places.
        Throws:
        ExchangeFault - when
        See Also:
        Unternehmens-Identifikationsnummer (UID)

      • ackSubmit

        public boolean ackSubmit​(String userName,
                         String password,
                         String docIdent)
                  throws ExchangeFault
        Acknowledges that a previous call to submitDocument(String, String, String) has successfully returned. Processing of a submitted document begins after this method is called. Calls to this method may be repeated.

        if for some reason the sender does not receive an answer from the webservice the sender has no way of knowing if the webservice has received and processed a submission or not. The sender would be forced to resend a "failed" submission potentially submitting data twice. The chosen sequence of submit/ack ensures that a document is submitted only once.

        Parameters:
        userName - user name
        password - password
        docIdent - the String returned by a previous call to submitDocument(String, String, String)
        Returns:
        • true if this call changed the status of the document
        • false if the document submission was already acknowledged
        Throws:
        ExchangeFault - when

      • getIncomingDocumentIdents

        public List<String> getIncomingDocumentIdents​(String userName,
                                              String password,
                                              String veUid)
                                       throws ExchangeFault
        Returns a List of docIdents that are waiting to be retrieved by the caller. If no documents are pending, an empty List is returned.

        If the parameter veUid is set, the scope is limited that specific recipient. Otherwise all docIdents the calling user may retrieve are returned.

        docIdents will continue to be returned by this method until they are retrieved by calling retrieveIncomingDocument(String, String, String) and the retrieval is acknowledged by calling ackIncomingDocument(String, String, String)

        Parameters:
        userName - user name
        password - password
        veUid - the UID of a specific sender VE in machine readable Swiss UID format. May be null. If set only pending docIdents for that VE will be returned. If null all pending docIdents will be returned.
        Returns:
        a list of docIdents waiting to be retrieved.
        Throws:
        ExchangeFault - when
        See Also:
        Unternehmens-Identifikationsnummer (UID)

      • getPendingReceipts

        public List<LogRecordWS> getPendingReceipts​(String userName,
                                            String password,
                                            String veUid)
                                     throws ExchangeFault
        Returns all "delivery receipts" not yet retrieved and acknowledged.

        "Delivery receipts" are common log entries with LogRecordWS.getAction() = 'ACK_INCOMING'. These log entries are confirmation of delivery to the recipient.

        "Delivery receipts" will continue to be returned by this method until the receipt of these receipts is acknowledged by calling ackReceipts(String, String, Collection).

        Parameters:
        userName - user name
        password - password
        veUid - the UID of a specific sender in machine readable Swiss UID format. May be null. If set only pending receipts for the VE will be returned. If null all pending receipts will be returned.
        Returns:
        List of "delivery receipts".
        Throws:
        ExchangeFault - when
        See Also:
        Unternehmens-Identifikationsnummer(UID)

      • getDocument

        public DocumentWS getDocument​(String userName,
                              String password,
                              String docIdent)
                       throws ExchangeFault
        Returns the DocumentWS corresponding to the given docIdent.

        Only users that have submit, receive or get privileges for either the 'EMPFAENGER' or 'ABSENDER' are allowed to access documents.

        Note: The returned DocumentWS may contain more than one xml with different formats. This may occur whenever more than one schema is simultaneously supported and sender and recipient formats do not match. In this case BVG Exchange will migrate xml between formats, resulting in more than one xml per document.

        Parameters:
        userName - user name
        password - password
        docIdent - of the requested document
        Returns:
        DocumentWS corresponding to the given docIdent
        Throws:
        ExchangeFault - when

      • getDocumentBySenderIdent

        public DocumentWS getDocumentBySenderIdent​(String userName,
                                           String password,
                                           String veUid,
                                           String senderIdent)
                                    throws ExchangeFault
        Returns a DocumentWS based on the senderIdent defined and set by the sender.

        All supported schema define an element &lt;IDENT&gt; with following definition:
        IDENT is an arbitrary unique ID defined by the sender to identify this file. IDENT must be unique for a sender regardless of the date.

        The sender is responsible for setting unique enderIdents. BVG Exchange will not validate for unique senderIdents. Non-unique senderIdents will cause this method to throw an exception if that senderIdent is requested.

        Parameters:
        userName - user name
        password - password
        veUid - the UID of the sender in machine readable Swiss UID format
        senderIdent - the senderIdent set and defined by the sender of the requested document
        Returns:
        DocumentWS corresponding to the given senderIdent
        Throws:
        ExchangeFault - when
        See Also:
        Unternehmens-Identifikationsnummer (UID)

      • getPdf

        public PdfWS getPdf​(String userName,
                    String password,
                    String docIdent,
                    String language,
                    Long ahvOrSozv,
                    List<Integer> fzlPositions)
             throws ExchangeFault
        Returns a PdfWS representation of the document corresponding to the given docIdent.

        Note:This method may return null. For the moment all submits will generate a PDF. This might not be necessary depending on ABSENDER/EMPFAENGER configurations and BVG Exchange reserves the right to limit PDF generation to those cases where PDFs are required.

        Parameters:
        userName - user name
        password - password
        docIdent - of the requested document
        language - optionally if language of pdf should not be the default language
        ahvOrSozv - optionally define this filter if only the fzl with this ahv or sozv nr should be rendered
        fzlPositions - optionally define this filter if only specific fzl should be rendered. 0 is the first fzl in the xml.
        Returns:
        PDF representation of the requested document. May be null.
        Throws:
        ExchangeFault - when

      • getLogs

        public List<LogRecordWS> getLogs​(String userName,
                                 String password,
                                 String forUserName,
                                 String veUid,
                                 String docIdent,
                                 String action,
                                 String result,
                                 Date from,
                                 Date to,
                                 Integer maxResults,
                                 Integer offset,
                                 Boolean orderAsc)
                          throws ExchangeFault
        Returns a list of LogRecordWS matching the given criteria.

        A user may only access log records that directly affect the VE's for which the user has privileges.

        Note: Unless otherwise specified, invalid parameter values will not cause an exception to be thrown (e.g. veUid="CHE000000000" will not cause an exception). The only effect will be an empty result.

        Parameters:
        userName - user name
        password - password
        forUserName - if set only LogRecords of actions by forUserName are returned. At the time of writing users may only query their own LogRecords.
        veUid - if set only log records of actions for the given VE are returned. The UID must be in machine readable Swiss UID format.
        docIdent - if set only log records concerning the given docIdent are returned. Setting only this parameter returns the complete history of a specific document.
        action - if set only log records with a matching action (SUBMIT, ACK_SUBMIT, GET_INCOMING_DOC_IDENTS, RETRIEVE_DOC, ACK_INCOMING, GET_RECEIPTS, ACK_RECEIPT, GET) are returned. Unknown values will be ignored.
        result - if set only log records with a matching result (SUCCESS, FAIL, SECURITY) are returned. Unknown values will be ignored.
        from - if set only log records equal or after from are returned.
        to - if set only log records equal or before to are returned.
        maxResults - maximum number of results to be returned. The server limits this value to 1000. This method will return maxResults + 1 if more than maxResults match the query.
        offset - zero based offset for the results. This allows retrieval of missing log records if a previous query returned more than maxResults
        orderAsc - log records are queried ordered by timestamp. This parameter defines if ascending or descending.
        • true - ascending (default)
        • false - descending
        Returns:
        list of LogRecordWS matching the given criteria
        Throws:
        ExchangeFault - when
        See Also:
        Unternehmens-Identifikationsnummer (UID)

      • getAcceptingVes

        public List<CompanyWS> getAcceptingVes​(String userName,
                                       String password,
                                       Collection<String> supportedExtendedValidations)
                                throws ExchangeFault
        Returns a list of all VEs accepting incoming documents, i.e. you can send documents to any VE returned here.

        The parameter 'supportedExtendedValidations' is no longer supported. (The concept of fine grained quality contracts between sender and recipient has never caught on and is - in retrospect - to complicated. We're leaving the method signature in place in order not to break existing client impls.)

        Parameters:
        userName - user name
        password - password
        supportedExtendedValidations - No longer supported. Ignored.
        Returns:
        a list of all accepting VEs
        Throws:
        ExchangeFault - when the user is not authenticated (FaultCode.WRONG_CREDENTIALS)