CKO2 reporting feedbacks description for A2A channel using SOAP
Contents
1. So participants can unzip using e WinZip even older versions always in legacy mode no encryption no extra features e Zipx will probably not be able to unzip the output files e Tests with gZip proofed it is also capable of doing the unzip 2 An output file size splitting limit parameter will be used to determine if an output file is too big before compression to send without splitting it into several smaller files If the size before compression of an output file to be sent is greater than this parameter splitting will be performed The initial value of this parameter will be Bei and remain so until a nevv value vvill be communicated to all participants 1Mb being 3 The participants will be able to detect if splitting has been performed by using the output sequence number defined in the administration part of the output XML file An XML file with the total output sequence number equal to 1 has not been split in several smaller files 4 The output files will not be present in the replies of the webservices or HTTPS entrypoints used to request outputs only URL s referring to the output files will be present With each URL the participant can then fetch the corresponding output file via simple HTTPS GET request Example following the defined rules a participant with an output file of 10Mb unzipped will receive 10 or more files of maximum 1Mb 1 http www iana org assignments media types application zi2. The result would look like this Messages list SOAP response lt SOAP ENV Envelope xmlns SOAP ENV http schemas xmlsoap org soap envelope xmlns esb http www onegate eu 2010 01 01 esb gt lt SOAP ENV Header gt lt SOAP ENV Body gt lt esb MessageListResponse gt lt esb MessageListResponse gt lt SOAP ENV Body lt SOAP ENV Envelope gt 16 OneGate CRO2 XML Protocols A typical SOAP request to retrieve the identifiers of unread DCD messages vvould be similar to the follovving example Messages list SOAP request CSOAP ENV Envelope xmlns SOAP ENV http schemas xmlsoap org soap envelope xmlns esb http www onegate eu 2010 01 01 esb gt lt SOAP ENV Header gt lt SOAP ENV Body gt lt esb MessageListRequest gt lt esb NotRead gt lt esb MessageTypeCode gt DCD lt esb MessageTypeCode gt lt esb MessageListRequest gt lt SOAP ENV Body gt lt SOAP ENV Envelope gt 5 1 2 MessageRequest Here follows a typical SOAP request to retrieve the message for a given identifier The example retrieves the message associated with identifier 148 Message SOAP request lt SOAP ENV Envelope xmlns SOAP ENV http schemas xmlsoap org soap envelope xmlns esb http www onegate eu 2010 01 01 esb gt lt SOAP ENV Header gt lt SOAP ENV Body gt lt esb MessageRequest gt lt esb Messageld gt 148 lt esb Messageld gt lt esb MessageRequest gt lt SOAP ENV Body gt lt SOAP
3. iii e CRO2 output for REPORT aaaa PRODUCT CODE bbbb PERIOD1 cccc PERIOD2 dddd FORMAT eeee APPLICATION ffff PARTICIPANT CODE iiii NU This structure regroups several information e REPORT indicates the type of the output e g PARTICIPANT DIRECTORY e PRODUCT CODE indicates the code of the product e PERIOD indicates the period format YYYY MM for which the output is generated e PERIOD1 indicates the first period format YYYY MM for which the output is generated it is only used when the output concerns two periods e PERIOD2 indicates the second period format YYYY MM for which the output is generated it is only used when the output concerns two periods e FORMAT indicates the format of the output e APPLICATION indicates the code of the application will always be CCCR PARTICIPANT CODE indicates the code of the participant e g 1500 Here follows two examples of message bodies e CKO2 output for REPORT AUTOMATIC_ RETURN PRODUCT CODE 0123 PERIOD1 2010 05 PERIOD2 201 0 06 LE ES APPLICATION CCCR PARTICIPANT CODE 0123 e CKO2 output for REPORT PARTICIPANT DIRECTORY PRODUCT_CODE 0125 PERIOD 2010 08 ae Aa APPLICATION CCCR PARTICIPANT CODE 1500 S49 OneGate CRO2 XML Protocols 4 5 4 Error messages 4 5 4 1 SOAP error messages Error message Corrective action Validation error The SOAP request is not valid against the messa
4. be obtained on demand via a specific form to be filled in OneGate Format The participant s directory default format is an XML file However if the XML file contains few debtors up to maximum 100 debtors and if the participant has requested it when filling the request form the participants directory will also be delivered in an HTML format in French Dutch or both The participant can get the participant s directory of a specific month in the attachment s of a message with a specific body message subject in his incoming mailbox The participant s directory file s will always be zipped OneGate CRO2 XML Protocols 3 Volumes and compression As defined in the references 03 and 04 automatic return and participants directory xml attachments will always be zipped Some participants will send large volumes of report data and will then receive large automatic return and participants directory files For them compression zipping will not be enough and splitting of the output files will be necessary to avoid problems related to sending and processing large files long transfer times timeouts server memory problems Output xml attachments will therefore always be zipped and only when necessary to avoid problems split in several smaller files as described by the following rules 1 The compression algorithm used will be the popular zip which corresponds to the content type application zip
5. defined content format frequency they are not part of this document 2 1 Automatic return Definition The automatic return contains the credit situation of the participant s debtors based on the two most recent complete reporting months It could be that no data is present in the output but only a specific information message although the participant subscribed to it the reason is that the participant did not report any data for that month Frequency The automatic return is a monthly output which is delivered to a participant if he has subscribed to it This subscription must be done via a specific form to be filled in OneGate Format The automatic return default format is an XML file However if the XML file contains few debtors up to maximum 100 debtors and if the participant has requested it when filling the request form the automatic return will also be delivered in an HTML format in French Dutch or both The participant can get the automatic return in the attachment s of a message with a specific body message subject in his incoming mailbox The automatic return file s will always be zipped OneGate CRO2 XML Protocols 2 2 Participants directory Definition The participant s directory contains all the data reported by the participant for one month chosen by the participant among the last 12 available months Frequency The participants directory is a unique output which can
6. CRO2 XML Protocols CRO2 outputs APA general description Author NBB IT Department Service IT Applications PRSM Date 12 05 2011 Document version V0 4 N Nationale DE BELGIQUE CRO2 XML Protocols Table of Contents 1 Introduction 1 1 Document history 1 2 References 1 3 Context 2 CKO2 outputs definition 2 1 Automatic return 2 2 o Participants directory 3 Volumes and compression 4 Generic output services 4 1 Introduction 4 2 Webservices overview 4 3 HTTPS entrypoints overview 4 4 Request list of available messages SOAP and HTTPS requests 4 4 1 Description 4 4 2 Input 4 4 3 Output 4 4 4 Error messages 4 5 _ Request message SOAP and HTTPS requests 4 5 1 Description 4 5 2 Input 4 5 3 Output 4 5 4 Error messages 4 6 Request attachment 4 6 1 Description 4 6 2 HTTPS request 4 6 3 Error message 5 Examples 5 1 SOAP 5 1 1 MessageListRequest 5 1 2 MessageRequest 5 2 CURL 5 2 1 Parameters 5 2 2 Request list of messages 5 2 3 Request message 5 2 4 Get attachment for message oO WW CO ow D O OneGate CRO2 XML Protocols 1 Introduction This document provides a general description of the different services available to the participant to retrieve the CKO2 outputs 1 1 Document history Date Version Description of change 15 09 2010 0 1 draft 1 2 References Ref Title 01 OneGate CSSR Manuel d utilisation pour le d clarant FR version 11 2009 pdf 02 OneGa
7. ENV Envelope gt The result would look like this the content of the body has been reduced to improve readability Message SOAP response with several attachments lt SOAP ENV Envelope xmlns SOAP ENV http schemas xmlsoap org soap envelope xmlns esb http www onegate eu 2010 01 01 esb gt lt SOAP ENV Header gt lt SOAP ENV Body gt lt esb MessageResponse gt lt esb Message gt eso Body CKhOZ output for esb body lt esb Attachment contentType lt esb Attachment contentType lt esb Message gt lt esb MessageResponse gt lt SOAP ENV Body gt lt SOAP ENV Envelope gt The URL s will refer to an URL that is accessible on the Websphere Application Server WAS This implies that an A2A authenticated user that has access to the webservices will also be given the ability to authenticate to the WAS application and get access to the requested URL The application also verifies that the A2A user has the authority to access the specified URL This is done to prevent a participant from accessing data of another participant The attachment URL can be accessed automatically in the client application or semi automatically by using CURL or SoapUl by performing an HTTPS GET request on the URL 17 OneGate CRO2 XML Protocols 5 2 CURL ae 5 2 1 Parameters data binary lt data gt HTTP This posts data exactly as specified with no extra processing whatsoever If you start the data with the le
8. XML Protocols The content of the MessageResponse is one or several URL s where the message output file can be retrieved The message can be retrieved using an HTTPS GET request to this URL It implies that if the participant works with SOAP requests for the two first steps he must use two different sessions SOAP and HTTPS sessions and must authenticate in both sessions More detailed information concerning the webservices can be found in reference 05 while more detailed information concerning the HTTPS entrypoints is available in reference 06 The file retrieved with the HTTPS GET request will have the structure defined in reference 03 and 04 4 2 Webservices overview i de messageListReguest E input r MessagelistRequest e MessageListRequest E CRS ESB https ffonegate certificat A output r MessageListResponse e MessageListResponse d messageRequest E input F MessageRequest el MessageRequest i output P MessageResponse e MessageResponse Figure 2 Webservices described in the WSDL Figure 2 gives an overview of the webservices used by the participant to fully automate the message retrieving process data exchange with the OneGate application 4 3 HTTPS entrypoints overview messageListRequest User A2A messageRequest Figure 3 HTTPS entrypoints services Figure 3 gives an overview of the HTTPS entrypoints used by the participant to fully automate the messag
9. e retrieving process data exchange with the OneGate application OneGate CRO2 XML Protocols 4 4 Request list of available messages SOAP and HTTPS requests 4 4 1 Description The service messageListRequest is used to request the list of message identifiers available Only the identifiers of messages destined to this userld will be sent back Messages associated with the userld of another user but for a common declarer will not be sent back The participant can choose between requesting a list of either new messages not read by the requesting user or messages already read retrieved during a specified time frame The second option offers the possibility to request messages that have been retrieved earlier Messages are available during a period of 3 months The participant can call the messageListRequest service any time he wants each time he will receive the list of identifiers of messages that are available for reading download If no message matching the request parameters is currently available for reading download the participant will receive a NoMessage answer 1 Except during OneGate closing time from 8h30 to 13h30 on Sundays OneGate CRO2 XML Protocols 4 4 2 Input Request only the message that have never been requestedireaded ReadType sss MessageListRequest Request a list al messagi identifier available For request EF Request only the message thal have been a
10. ge definition Please consult the validation error detalls Identification with code userld You have access to OneGate but not to the requested data not found e Check that you use the right URL to access the webservices e Contact the CCCR back office to request if you have access for the CCCR institute and your specific business domain CC1 Table 7 MessageRequest SOAP error messages description 4 5 4 2 HTTPS error messages Status code Reason phrase Corrective action 400 You have access to OneGate but not for the requested institute Identification with code userld not e Check that you use the right URL found e Contact the CCCR back office to request if you have access for the CCCR institute and your specific business domain CC1 400 The requested message doesn t exist Identification with code not found 4xx range Client error The request contains bad syntax or cannot be fulfilled 5xx range Server error The server failed to fulfill the request Please try again later and if the problem persists contact the CCCR back office Table 8 MessageRequest HTTPS error messages description 1 In order to access OneGate in A2A a specific URL must be used 14 2 OneGate CRO2 XML Protocols 4 6 Request attachment 4 6 1 Description Each attachment of a MessageResponse should be retrieved by its unique URL using an HTTPS GET request 4 6 2 HTTPS request The attachment can be accessed automatical
11. he validation error details Identification with code userld You have access to OneGate but not for the requested data not found e Check that you use the right URL to access the webservices e Contact the CCCR back office to request if you have access for the CCCR institute and your specific business domain CC1 Table 3 MessageListRequest SOAP error messages description 4 4 4 2 HTTPS error messages Status code Reason phrase Corrective action 400 You have access to OneGate but not to the requested institute Identification with code userld e Check that you use the right URL not found e Contact the CCCR back office to request if you have access for the CCCR institute and your specific business domain CC1 4xx range Client error The request contains bad syntax or cannot be fulfilled 5xx range Server error The server failed to fulfill the request Please try again later and if the problem persists contact the CCCR back office Table 4 MessageListRequest HTTPS error messages description 4 5 Request message SOAP and HTTPS requests 4 5 1 Description The service messageRequest is used to request a specific message by providing its identifier received in the reply of the messageListRequest service 4 5 2 Input MessageRequest E cre Messageld Request a specific message Identifier of the requested message Figure 6 MessageRequest Element Description MessageReque
12. lready requestedireaded during the specihed time Mare Figure 4 MessageListRequest Element Description MessageListRequest Contains the attributes to request the list of message identifiers available for the requester NotRead Used to request the identifiers of new messages Read Used to request identifiers associated to messages already retrieved by requesting user earlier during the specified time frame TimeFrame Used to specify the time frame during which the messages have been retrieved the first time mm Table 1 MessageListRequest elements description 44 3 Output HoMessage Mo message Found MessageListResponse List of identifier of the message available For the requested parameters Messageldentification To Figure 5 MessageListResponse Element Description MessageListResponse Contains the list of available message identifiers NoMessage No message of the requested type found for the specified search criteria e Not read no new message e Read no message read during the specified time frame Messageld Contains the identifier of the message internal OneGate identifier Table 2 MessageListResponse elements description 10 OneGate CRO2 XML Protocols 4 4 4 Error messages 4 4 4 1 SOAP error messages Error message Corrective action Validation error The SOAP request is not valid against the message definition Please consult t
13. ly in the client application or semi automatically by using cURL for example by performing a GET operation on the URL 4 6 3 Error message Status code Reason phrase Corrective action 4xx range Client error The request contains bad syntax or cannot be fulfilled 5xx range Server error The server failed to fulfill the request Please try again later and if the problem persists contact the CCCR back office Table 9 Get attachment HTTPS error messages description OneGate CRO2 XML Protocols 5 Examples 5 1 SOAP 5 1 1 MessageListRequest Here follows a typical SOAP request to retrieve identifiers of an already read message In this example the participant would like to get all the identifiers of DCD messages already retrieved from 2010 06 09 to 2010 06 15 Dates must be defined using the full dateTime syntax YYYY MM DDThh mmi ss Messages list SOAP request lt SOAP ENV Envelope xmlns SOAP ENV http schemas xmlsoap org soap envelope xmlns esb http www onegate eu 2010 01 01 esb gt lt SOAP ENV Header gt lt SOAP ENV Body gt lt esb MessageListRequest gt lt esb Read gt lt esb TimeFrame gt lt esb FromTime gt 2010 06 09T00 00 00 lt esb FromTime gt lt esb lTolime gt 2010 06 15123259 59 lt 7esb lolime lt esb TimeFrame gt lt esb Read gt lt esb MessageTypeCode gt DCD lt esb MessageTypeCode gt lt esb MessageListRequest gt lt SOAP ENV Body gt lt SOAP ENV Envelope gt
14. onse example lt xml vwersi1on 1 02 gt lt esb MessageListResponse xmlns esb http www onegate eu 2010 01 01 esb gt lt esb MessageListResponse gt 5 2 3 Request message Command cURL Curl y E lt certiitveste pemipassword gt datea binary t request Message xml k https onegate cecr a2a test nbb be ccer esb invoke requestMessage v2 0 HTTPS request requestMessage xml example lt xmL version 170 2 lt esb MessageRequest xmlns esb http www onegate eu 2010 01 01 esb gt lt esb MessageId gt 154 lt esb MessagelId gt lt esb MessageRequest gt HTTPS response example the content of the body has been reduced to improve readability lt exml wersron OUS lt esb MessageResponse xmlns esb http www onegate eu 2010 01 01 esb gt lt esb Message gt lt esb Body gt ChOZ output fOr esb Pody lt esb Attachment contentType gt lt esb Attachment contentType J gt lt esb Message gt lt esb MessageListResponse gt 5 2 4 Get attachment for message Command cURL curl y E Scertiticate pem passvordo u m The HTTPS response is a en XML file with the structure defined in reference 03 for participant s directory or 04 for automatic return 19
15. p Because the underlying compression algorithm is deflate used in WinZip and gZip OneGate CRO2 XML Protocols 4 Generic output services This chapter describes the different webservices and HTTPS entrypoints provided to get an output file The webservices use the SOAP protocol 4 1 Introduction To fetch an output file the data exchange with the OneGate application consists of three chronological activities e The participant requests the list of available messages e The participant requests a specific message e The participant submits an HTTPS request with the URL s of the different attachments in the specific message and the server responds with the content of the attachment Participant A2A ES OneGate CSSR MessageListRequest MessageListRequest MessageListResponse For each entry of the MessageListResponse MessageRequest MessageRequest SOAP or HTTPS request MessageResponse MessageResponse contains only URL S where messages can be retrieved Message File Server For each attachment in the MessageResponse HTTPS GET lt attachment URL gt l using URL s received in MessageResponse Message HTTPS request Figure 1 Data exchange with OneGate for A2A message retrieving process Message type will be defined in a later chapter of this document OneGate CRO2
16. st Contains the information about the requested message Messageld Contains the identifier of the requested message internal OneGate identifier Table 5 MessageRequest elements description 1 In order to access OneGate in A2A a specific URL must be used An overview of HTTPS error codes can be found in http www rfc editor org rfc rfc2616 txt 11 OneGate CRO2 XML Protocols 4 5 3 Output F cts P E A MessageResponse Figure 7 MessageResponse Element Description MessageResponse Contains the requested message Message Contains at least one body and can also contain one or several attachments Body Contains the body of the message in plain text Attachment Contains an attachment of the message contentType Specifies the type of the attachment using the Internet media type it will always be application zip URL Contains the URL to which the message can be retrieved using an HTTPS GET request Table 6 MessageResponse elements description 1 An Internet media type originally called MIME type is a two part identifier for file formats on the internet A media type is composed of two parts a type and a subtype e g text plain image jpeg application pdf 12 OneGate CRO2 XML Protocols The body of the message will always have one of the two following structure e CKO2 output for REPORT aaaa PRODUCT CODE bbbb PERIOD cccc FORMAT ddda APPLICATION eeee PARTICIPANT CODE hhhh
17. te CSSR Handleiding voor de aangever NL versie 11 2009 pdf 03 Technical documentation Participant s directory function Description of the data returned v1 0 01 08 2010 pdf 04 Technical documentation Automatic return function Description of the data returned v1 0 01 08 2010 pdf 05 OneGate CSSR Webservices End User Manual v2 0 10 09 2010 pdf 06 OneGate CSSR HTTPS entrypoints End User Manual v2 0 10 09 2010 pdf 1 3 Context The goal of this document is to describe the different services proposed to the participants to retrieve the return and participant directory via A2A Participants searching for a detailed description of content should consult references 03 and 04 For U2A ms a specific interface is being developed to provide an nr view of these outputs and its attachment s It is also possible for U2A users to get the attachment s in an XML format with a structure identical to the one proposed to A2A users A detailed description of the U2A consultation is available in references 01 and 02 OneGate CRO2 XML Protocols 2 CKO2 outputs definition This chapter describes in generic terms the two outputs that are already fully defined automatic return and participant s directory Sectorial and geographical selective or historical statistics can be supplied to participants on request or periodically Since those outputs are yet to be
18. tter the rest should be a filename Data is posted in a similar manner as data ascii does except that newlines are preserved and conversions are never done E cert lt certificate password gt SSL Tells CURL to use the specified certificate file when getting a file with HTTPS or FTPS The certificate must be in PEM format If the optional password isn t specified it will be queried for on the terminal Note that this option assumes a certificate file that is the private key and the private certificate concatenated See cert and key to specify them independently H header lt header gt HTTP Extra header to use when getting a web page You may specify any number of extra headers Note that if you should add a custom header that has the same name as one of the internal ones CURL would use you externally set header will be used instead of the internal one v verbose Makes the fetching more verbose talkative Mostly useful for debugging 5 2 2 Request list of messages Command cURL curl y E lt CertlrlCate pem password gt data binary request MessagelLast mir k https onegate cocr a2a test nbb be ccer esb invoke requestMessageList v2 0 HTTPS request requestMessageList xml example Vers Oe Os lt esb MessageListRequest xmlns esb http www onegate eu 2010 01 01 esb gt lt esb NotRead gt lt esb MessageListRequest gt 18 OneGate CRO2 XML Protocols HTTPS resp
Download Pdf Manuals
Related Search