CONTRACT MODEL IPONZ DESIGN SERVICE VERSION 2 Author: Foster Moore Date: 20 September 2011 Document Version: 1.7 Level 6, Durham House, 22 Durham Street West PO Box 106857, Auckland City Post Shop, Auckland 1143, New Zealand Tel: +64 9 950 2300 Fax: +64 9 950 2301 www.fmit.co.nz
CONTENTS BusinessData Authentication... 4 Introduction... 4 HMAC (Hashed Message Authentication Code)... 4 Signature Generation... 4 Request/Response Standards... 7 SOAP Request Structure... 7 Attachments... 7 Full WSDL... 7 Design Service Description... 14 XML Schema Definitions... 14 iponz_design_application_v1.07.xsd... 14 iponz_design_renewal_v1.07.xsd... 18 Service Operations... 22 submitdesign... 23 Operation... 23 Example Request XML... 23 Example Response XML... 26 renewdesign... 30 Operation... 30 Example Request XML... 31 Example Response XML... 32 Appendix 1: authgen... 33 Installation... 33 Windows... 33 Mac/Linux... 33 Usage... 33 Signature Verification... 34 Appendix 2: SOAPui... 35 Importing a WSDL... 35 Endpoints... 35 Attachments... 35 <Authenticator> Header Element... 35 Appendix 3: Attachments... 37 IPONZ Design Service Version 2 Page 2 of 38
MTOM (Mime Transmission Optimization Mechanism)... 37 IPONZ Design Service Version 2 Page 3 of 38
BUSINESSDATA AUTHENTICATION Introduction BusinessData is the authentication service layer through which all business services are exposed. Each business service transaction is first authenticated in BusinessData before forwarding the transaction to the appropriate business service for processing. HMAC (Hashed Message Authentication Code) HMAC is the authentication mechanism used by BusinessData. A shared Secret Authentication Key is used by the client to create a signature based upon predefined message properties. Upon receiving the signature with the request the service will recalculate the signature to authenticate the user s identity. Each request should provide the signature and the data required as part of the source. Two pieces of information are required to generate a signature. Authentication Key ID - This is your unique identifier to verify that you are a BusinessData user. This will not change. Secret Authentication Key - Used to generate a signature from the String to Sign. This Secret Authentication Key is never transmitted in a message and should never be passed to a client machine. Signature Generation The String to Sign is the final string which is signed using a SHA256 digest to create the signature. It is built up from the following attributes of an HTTP request. ATTRIBUTE DESCRIPTION REQUIRED/ OPTIONAL SUPPLIED AS HTTP Method HTTP method used for the request. Only the POST method is allowed for this service. (Note: All SOAP-based web services in BusinessData support only the POST method.) Required Host Standard HTTP header. Required Request URI URI of service being requested. Required Timestamp Time that the signature was generated. Required SOAP header in the format yyyymmddhhmmss z Authentication Key ID Identifies the BusinessData client. Required As part of the SOAP Authorization header. IPONZ Design Service Version 2 Page 4 of 38
Client The registered IPONZ user ID (i.e., the user ID used by the client to log in to the IPONZ website). Required SOAP header. Context A client identifier for the transaction. If supplied this must be unique to each service usage. (i.e., user and service combination). Optional SOAP header. The String to Sign is built up from these values separated by a new line character ( \n ). The construction of the String to Sign follows the template shown below: <HTTP Method>\n<Host>\n<Request URI>\n<Timestamp>\n<Authentication Key ID>\n<Client>\n<Context>\n Example Source String POST www.businessdata.govt.nz /data/app/ws/sws/designservice-2.0 20091221084626 NZDT T4WZUVoufkaGfsrK 100075277 CTX001 A Base64 encoded SHA256 hash is then applied to this string using your Secret Authentication Key (not the Authentication Key ID) to produce the signature. An example signature may look like the following: wftzpfddah9kul6zenlvvmrydwmvqjlxagnucpmygtm= This signature must be added to the request as a SOAP header in the form <Authentication Key ID>:<Signature> : <Authorization> T4WZUVoufkaGfsrK:wFtZpfdDAh9kul6ZEnlvvmRYdWmvqjLxagNUcpMYGTM=</Authorization> A SOAP envelope header would look as follows: <soapenv:header> <Authenticator> <ServiceName>I01</ServiceName> <Authorization> T4WZUVoufkaGfsrK:wFtZpfdDAh9kul6ZEnlvvmRYdWmvqjLxagNUcpMYGTM=</Authorization> <Timestamp>20100419135948 NZDT</Timestamp> <Client>100075277</Client> IPONZ Design Service Version 2 Page 5 of 38
<Context>CTX001</Context> </Authenticator> </soapenv:header> If no context element is supplied the signature will only be valid for 60 seconds after its generation time. The timestamp used for generation on the server must match that to be supplied in the SOAP header. It is recommended that the server be synchronized with a NTP server. The service name element is required and must match the service operation that is being invoked. The Design Service has the following operations and matching service names: OPERATION submitdesign renewdesign SERVICE NAME I01 I02 IPONZ Design Service Version 2 Page 6 of 38
REQUEST/RESPONSE STANDARDS SOAP Request Structure This is a SOAP-based web service. Each transaction must contain the BusinessData client s authentication data and the input XML required by the business service. Authentication Data The client s authentication data must be supplied in the SOAP request Header element. Input XML The input XML required by the business service must be supplied in the SOAP request Body element. Attachments This service supports MTOM (Mime Transmission Optimization Mechanism) as the attachment mechanism. See Appendix 3. Full WSDL The following is the WSDL for the call to the IPONZ Design Service Version 2. It follows the required BusinessData standard: URL: http://www.businessdata.govt.nz/data/app/ws/sws/designservice-2.0.wsdl <?xml version="1.0" encoding="utf-8"?> <wsdl:definitions targetnamespace="http://ipol.webservices.g2b.fmit.co.nz" xmlns:app="http://www.iponz.govt.nz/xmlschema/designs/application" xmlns:renew="http://www.iponz.govt.nz/xmlschema/designs/renewal" xmlns:impl="http://ipol.webservices.g2b.fmit.co.nz" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:xsd="http://www.w3.org/2001/xmlschema"> <wsdl:types> <schema targetnamespace="http://ipol.webservice.g2b.fmit.co.nz" xmlns="http://www.w3.org/2001/xmlschema" xmlns:app="http://www.iponz.govt.nz/xmlschema/designs/application" xmlns:renew="http://www.iponz.govt.nz/xmlschema/designs/renewal"> <import namespace="http://www.iponz.govt.nz/xmlschema/designs/renewal" schemalocation="../iponz_design_renewal_v1.07.xsd"/> IPONZ Design Service Version 2 Page 7 of 38
<import namespace="http://www.iponz.govt.nz/xmlschema/designs/application" schemalocation="../iponz_design_application_v1.07.xsd"/> <element name="submitdesign"> <complextype> <sequence> <element ref="app:transaction"/> </sequence> </complextype> </element> <element name="submitdesignreturn"> <complextype> <sequence> <element ref="app:transactionresponse"/> </sequence> </complextype> </element> <element name="renewdesign"> <complextype> <sequence> <element ref="renew:transaction"/> </sequence> </complextype> </element> <element name="renewdesignreturn"> <complextype> <sequence> <element ref="renew:transactionresponse"/> </sequence> </complextype> </element> </schema> </wsdl:types> <wsdl:message name="submitdesignresponse"> <wsdl:part element="impl:submitdesignreturn" name="submitdesignreturn"/> </wsdl:message> <wsdl:message name="submitdesignrequest"> <wsdl:part element="impl:submitdesign" name="part"/> </wsdl:message> <wsdl:message name="renewdesignresponse"> IPONZ Design Service Version 2 Page 8 of 38
<wsdl:part element="impl:renewdesignreturn" name="renewdesignreturn"/> </wsdl:message> <wsdl:message name="renewdesignrequest"> <wsdl:part element="impl:renewdesign" name="part"/> </wsdl:message> <wsdl:porttype name="design"> <wsdl:operation name="submitdesign"> <wsdl:input message="impl:submitdesignrequest" name="submitdesignrequest"/> <wsdl:output message="impl:submitdesignresponse" name="submitdesignresponse"/> </wsdl:operation> <wsdl:operation name="renewdesign"> <wsdl:input message="impl:renewdesignrequest" name="renewdesignrequest"/> <wsdl:output message="impl:renewdesignresponse" name="renewdesignresponse"/> </wsdl:operation> </wsdl:porttype> <wsdl:binding name="designservicesoapbinding" type="impl:design"> <wsdlsoap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> <wsdl:operation name="submitdesign"> <wsdlsoap:operation soapaction=""/> <wsdl:input name="submitdesignrequest"> <wsdlsoap:body use="literal"/> </wsdl:input> <wsdl:output name="submitdesignresponse"> <wsdlsoap:body use="literal"/> </wsdl:output> </wsdl:operation> <wsdl:operation name="renewdesign"> <wsdlsoap:operation soapaction=""/> <wsdl:input name="renewdesignrequest"> <wsdlsoap:body use="literal"/> </wsdl:input> <wsdl:output name="renewdesignresponse"> <wsdlsoap:body use="literal"/> </wsdl:output> </wsdl:operation> </wsdl:binding> IPONZ Design Service Version 2 Page 9 of 38
<wsdl:service name="designservice"> <wsdl:port binding="impl:designservicesoapbinding" name="designservice"> <wsdlsoap:address location="https://www.businessdata.govt.nz/app/ws/sws/designservice-2.0"/> </wsdl:port> </wsdl:service> </wsdl:definitions> The authentication data is sent as SOAP headers while the forwarding business service request is sent as the SOAP body. The specification for the IPONZ business service request body is described in subsequent sections of this document. A complete SOAP request for a design application request looks like the following: <?xml version="1.0" encoding="utf-8" standalone="no"?> <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ipol="http://ipol.webservice.g2b.fmit.co.nz" xmlns:app="http://www.iponz.govt.nz/xmlschema/designs/application" xmlns:des="http://www.iponz.govt.nz/xmlschema/designs"> <soapenv:header> <Authenticator> <ServiceName>I01</ServiceName> <Authorization>rAGXQfPS5NfPFKHB:l0fbDaPwee4QEqy/e+BfLvqxyBfAwa7c8eD4pv26uRo=< /Authorization> <Timestamp>20100913105325 NZST</Timestamp> <Client>100095730</Client> <Context>CTX0059</Context> </Authenticator> </soapenv:header> <soapenv:body> <ipol:submitdesign> <app:transaction> <app:designtransactionbody> <app:transactioncontentdetails> <app:transactionidentifier>ctx0059 Transaction Identifier</app:TransactionIdentifier> <app:transactioncode>design E-Filing</app:TransactionCode> <app:transactiondata> <app:designapplicationdetails> <app:designapplication> <app:registrationofficecode>nz</app:registrationofficecode> <app:designapplicationreference>ctx0059 Des App IPONZ Design Service Version 2 Page 10 of 38
Ref</app:DesignApplicationReference> <app:applicationcontact>applicant</app:applicationcontact> <app:designdetails> <des:design> <des:designapplicationkind>set of Articles</des:DesignApplicationKind> <des:designtitle languagecode="en" sequencenumber="1">ctx0059 Des Title</des:DesignTitle> <des:designdescription languagecode="en" sequencenumber="1">ctx0059 Des Desc</des:DesignDescription> <des:designspecialcase>wallpaper</des:designspecialcase> <des:noveltystatement languagecode="en" sequencenumber="1">ctx0059 Nov State</des:NoveltyStatement> <des:designrepresentationsheetdetails> <des:designrepresentationsheet> <des:representationsheetfilename>upload_pdf_document_01.pdf</des:representati onsheetfilename> <des:attachment>cid:1</des:attachment> </des:designrepresentationsheet> </des:designrepresentationsheetdetails> <des:prioritydetails> <des:priority> <des:prioritycountrycode>au</des:prioritycountrycode> <des:prioritynumber>1234567</des:prioritynumber> <des:prioritydate>2009-08-13</des:prioritydate> <des:prioritydocument> <des:documentfilename>upload_pdf_document_02.pdf</des:documentfilename> <des:attachment>cid:2</des:attachment> </des:prioritydocument> <des:designapplicantpriorityrelationshipdetails> <des:designapplicantpriorityrelationship>assignee</des:designapplicantpriorit yrelationship> <des:assigneebyvirtueof languagecode="en" sequencenumber="1">ctx0048 ByVirtue</des:AssigneeByVirtueOf> </des:designapplicantpriorityrelationshipdetails> </des:priority> </des:prioritydetails> <des:applicantdetails> <des:designapplicant contact="true"> <des:newapplicant> <des:applicantlegalentity>company</des:applicantlegalentity> <des:applicantincorporationcountrycode>nz</des:applicantincorporationcountryc IPONZ Design Service Version 2 Page 11 of 38
ode> <des:applicantaddressbook> <des:formattednameaddress> <des:name> <des:formattedname> <des:organizationname>opendata1 Limited</des:OrganizationName> </des:formattedname> </des:name> <des:address> <des:addresscountrycode>nz</des:addresscountrycode> <des:formattedaddress> <des:addressline languagecode="en" sequencenumber="1">ctx0059 Addr1</des:AddressLine> <des:addressline languagecode="en" sequencenumber="2">ctx0059 Addr2</des:AddressLine> <des:addressline languagecode="en" sequencenumber="3">ctx0059 Addr3</des:AddressLine> <des:addressline languagecode="en" sequencenumber="4">ctx0059 Addr4</des:AddressLine> <des:addressline languagecode="en" sequencenumber="5">ctx0059 Addr5</des:AddressLine> <des:addresssuburb>ctx0059 Suburb</des:AddressSuburb> <des:addresscity>ctx0059 City</des:AddressCity> <des:addressstate>ctx0059 State</des:AddressState> <des:addresspostcode>1234</des:addresspostcode> </des:formattedaddress> </des:address> </des:formattednameaddress> <des:postaladdress> <des:addresscountrycode>nz</des:addresscountrycode> <des:formattedaddress> <des:addressline languagecode="en" sequencenumber="1">ctx0059 Addr1</des:AddressLine> <des:addressline languagecode="en" sequencenumber="2">ctx0059 Addr2</des:AddressLine> <des:addressline languagecode="en" sequencenumber="3">ctx0059 Addr3</des:AddressLine> <des:addressline languagecode="en" sequencenumber="4">ctx0059 Addr4</des:AddressLine> <des:addressline languagecode="en" sequencenumber="5">ctx0059 Addr5</des:AddressLine> IPONZ Design Service Version 2 Page 12 of 38
<des:addresssuburb>ctx0059 Suburb</des:AddressSuburb> <des:addresscity>ctx0059 City</des:AddressCity> <des:addressstate>ctx0059 State</des:AddressState> <des:addresspostcode>1234</des:addresspostcode> </des:formattedaddress> </des:postaladdress> </des:applicantaddressbook> </des:newapplicant> </des:designapplicant> </des:applicantdetails> </des:design> </app:designdetails> <app:authorization> <des:authorizationkind>specific Authorization</des:AuthorizationKind> <des:authorizationdocument> <des:documentfilename>upload_pdf_document_03.pdf</des:documentfilename> <des:attachment>cid:3</des:attachment> </des:authorizationdocument> </app:authorization> </app:designapplication> </app:designapplicationdetails> </app:transactiondata> </app:transactioncontentdetails> </app:designtransactionbody> </app:transaction> </ipol:submitdesign> </soapenv:body> </soapenv:envelope> IPONZ Design Service Version 2 Page 13 of 38
DESIGN SERVICE DESCRIPTION The IPONZ service facilitates the application and renewal of designs. The service must meet the BusinessData authentication standards. SERVICE PROPERTY VALUE Name Version 2.0 Application/Registry Service URL WSDL URL DesignService IPONZ http://www.businessdata.govt.nz/data/app/ws/sws/designservice-2.0 http://www.businessdata.govt.nz/data/app/ws/sws/designservice- 2.0.wsdl XML Schema Definitions The following XSD files contain the schema definitions that form the basis of the request and response for this service. These schema definitions conform to the WIPO standards. Note: These XSD files will be published on the BusinessData production website. iponz_design_application_v1.07.xsd URL: http://www.businessdata.govt.nz/data/app/ws/iponz_design_application_v1.07.xsd <?xml version="1.0" encoding="utf-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/xmlschema" xmlns="http://www.iponz.govt.nz/xmlschema/designs/application" xmlns:iponz="http://www.iponz.govt.nz/xmlschema/designs" targetnamespace="http://www.iponz.govt.nz/xmlschema/designs/application" elementformdefault="qualified" attributeformdefault="unqualified" version="1.07"> <!--<![CDATA[ ********************************************************************** * * * IPONZ Design Application Schema * * * * Filename : iponz_design_application_v1.07.xsd * * Author : IPONZ * * Version : 1.07 * * Last Update : 2011-05-06 * IPONZ Design Service Version 2 Page 14 of 38
* Contact : www.iponz.govt.nz * * * ********************************************************************** ]]>--> <xs:annotation> <xs:documentation>iponz Design Application Schema </xs:documentation> </xs:annotation> <!--<![CDATA[ ====================================================================== Import IPONZ Design Common Types Library ====================================================================== ]]>--> <xs:import namespace="http://www.iponz.govt.nz/xmlschema/designs" schemalocation="common/iponz_design_common_types_v1.07.xsd" /> <!--<![CDATA[ ====================================================================== Design Application Transaction Request Root Element ====================================================================== ]]>--> <xs:element name="transaction" type="transactiontype"/> <!--<![CDATA[ ====================================================================== Design Application Transaction Response Root Element ====================================================================== ]]>--> <xs:element name="transactionresponse" type="transactionresponsetype"/> <!--<![CDATA[ ********************************************************************** * TRANSACTION/MESSAGE TYPES (in alphabetical order by name) * ********************************************************************** ]]>--> <xs:simpletype name="delayofregistrationinmonthstype"> IPONZ Design Service Version 2 Page 15 of 38
<xs:restriction base="xs:integer"> <xs:mininclusive value="1"/> <xs:maxinclusive value="15"/> </xs:restriction> </xs:simpletype> <xs:complextype name="designapplicationsummaryreporttype"> <xs:element name="designapplicationreference" type="xs:token" /> <xs:element name="applicationcontact" type="iponz:nz_applicationcontacttype"/> <xs:element name="designapplicationdetails" type="iponz:nz_designapplicationdetailstype"/> <xs:element name="delayofregistrationinmonths" type="delayofregistrationinmonthstype" minoccurs="0" /> <xs:complextype name="designapplicationtype"> <xs:element name="registrationofficecode" type="iponz:wipost3codetype" fixed="nz" /> <xs:element name="designapplicationreference" type="xs:token" /> <xs:element name="applicationcontact" type="iponz:nz_applicationcontacttype" /> <xs:element name="designdetails" type="iponz:nz_designdetailstype"/> <xs:element name="authorization" type="iponz:authorizationtype" minoccurs="0"/> <xs:element name="delayofregistrationinmonths" type="delayofregistrationinmonthstype" minoccurs="0" /> <xs:complextype name="transactionbodytype"> <xs:element name="transactioncontentdetails"> <xs:complextype> <xs:element name="transactionidentifier" type="xs:token" minoccurs="0"/> <xs:element name="transactioncode" type="iponz:nz_transactioncodetype" fixed="design E-Filing"/> <xs:element name="transactiondata" type="transactiondatatype"/> IPONZ Design Service Version 2 Page 16 of 38
</xs:element> <xs:complextype name="transactiondatatype"> <xs:element name="designapplicationdetails"> <xs:complextype> <xs:element name="designapplication" type="designapplicationtype"/> </xs:element> <xs:complextype name="transactionerrortype"> <xs:element name="transactionerrorcode" type="xs:token" /> <xs:element name="transactionerrortext" type="iponz:texttype" /> <xs:complextype name="transactionresponsebodytype"> <xs:choice> <xs:element name="transactionerrordetails"> <xs:complextype> <xs:element name="transactionidentifier" type="xs:token" minoccurs="0" /> <xs:element name="transactioncode" type="iponz:nz_transactioncodetype" fixed="design E-Filing" /> <xs:element name="transactionerror" type="transactionerrortype" maxoccurs="unbounded" /> </xs:element> <xs:element name="transactionresponsecontentdetails"> IPONZ Design Service Version 2 Page 17 of 38
<xs:complextype> <xs:element name="transactionidentifier" type="xs:token" minoccurs="0" /> <xs:element name="transactioncode" type="iponz:nz_transactioncodetype" fixed="design E-Filing" /> <xs:element name="transactionresponsedata" type="transactionresponsedatatype" /> </xs:element> </xs:choice> <xs:complextype name="transactionresponsedatatype"> <xs:element name="designapplicationsummaryreport" type="designapplicationsummaryreporttype" /> <xs:complextype name="transactionresponsetype"> <xs:element name="designtransactionresponsebody" type="transactionresponsebodytype" /> <xs:complextype name="transactiontype"> <xs:element name="designtransactionbody" type="transactionbodytype"/> </xs:schema> iponz_design_renewal_v1.07.xsd URL: http://www.businessdata.govt.nz/data/app/ws/iponz_design_renewal_v1.07.xsd <?xml version="1.0" encoding="utf-8"?> IPONZ Design Service Version 2 Page 18 of 38
<xs:schema xmlns:xs="http://www.w3.org/2001/xmlschema" xmlns="http://www.iponz.govt.nz/xmlschema/designs/renewal" xmlns:iponz="http://www.iponz.govt.nz/xmlschema/designs" targetnamespace="http://www.iponz.govt.nz/xmlschema/designs/renewal" elementformdefault="qualified" attributeformdefault="unqualified" version="1.07"> <!--<![CDATA[ ********************************************************************** * * * IPONZ Design Renewal Schema * * * * Filename : iponz_design_renewal_v1.07.xsd * * Author : IPONZ * * Version : 1.07 * * Last Update : 2010-09-27 * * Contact : www.iponz.govt.nz * * * ********************************************************************** ]]>--> <xs:annotation> <xs:documentation>iponz Design Renewal Schema </xs:documentation> </xs:annotation> <!--<![CDATA[ ====================================================================== Import IPONZ Design Common Types Library ====================================================================== ]]>--> <xs:import namespace="http://www.iponz.govt.nz/xmlschema/designs" schemalocation="common/iponz_design_common_types_v1.07.xsd" /> <!--<![CDATA[ ====================================================================== Design Renewal Transaction Request Root Element ====================================================================== ]]>--> IPONZ Design Service Version 2 Page 19 of 38
<xs:element name="transaction" type="transactiontype"/> <!--<![CDATA[ ====================================================================== Design Renewal Transaction Response Root Element ====================================================================== ]]>--> <xs:element name="transactionresponse" type="transactionresponsetype"/> <!--<![CDATA[ ********************************************************************** * TRANSACTION/MESSAGE TYPES (in alphabetical order by name) * ********************************************************************** ]]>--> <xs:complextype name="designrenewalsummaryreporttype"> <xs:element name="renewalreference" type="xs:token" /> <xs:element name="designrenewaldetails" type="iponz:nz_designrenewaldetailstype"/> <xs:complextype name="designrenewaltype"> <xs:element name="designrenewaldetails"> <xs:complextype> <xs:element name="renewalreference" type="xs:token" /> /> <xs:element name="registrationnumber" type="xs:positiveinteger" </xs:element> <xs:complextype name="transactionbodytype"> IPONZ Design Service Version 2 Page 20 of 38
<xs:element name="transactioncontentdetails"> <xs:complextype> <xs:element name="transactionidentifier" type="xs:token" minoccurs="0" /> <xs:element name="transactioncode" type="iponz:nz_transactioncodetype" fixed="design E-Renewal" /> <xs:element name="transactiondata" type="transactiondatatype" /> </xs:element> <xs:complextype name="transactiondatatype"> <xs:element name="designrenewal" type="designrenewaltype" /> <xs:complextype name="transactionerrortype"> <xs:element name="transactionerrorcode" type="xs:token" /> <xs:element name="transactionerrortext" type="iponz:texttype" /> <xs:complextype name="transactionresponsebodytype"> <xs:choice> <xs:element name="transactionerrordetails"> <xs:complextype> <xs:element name="transactionidentifier" type="xs:token" minoccurs="0" /> <xs:element name="transactioncode" type="iponz:nz_transactioncodetype" fixed="design E-Renewal" /> <xs:element name="transactionerror" type="transactionerrortype" maxoccurs="unbounded" /> </xs:element> IPONZ Design Service Version 2 Page 21 of 38
<xs:element name="transactionresponsecontentdetails"> <xs:complextype> <xs:element name="transactionidentifier" type="xs:token" minoccurs="0" /> <xs:element name="transactioncode" type="iponz:nz_transactioncodetype" fixed="design E-Renewal" /> <xs:element name="transactionresponsedata" type="transactionresponsedatatype" /> </xs:element> </xs:choice> <xs:complextype name="transactionresponsedatatype"> <xs:element name="designrenewalsummaryreport" type="designrenewalsummaryreporttype" /> <xs:complextype name="transactionresponsetype"> <xs:element name="designtransactionresponsebody" type="transactionresponsebodytype" /> <xs:complextype name="transactiontype"> <xs:element name="designtransactionbody" type="transactionbodytype"/> </xs:schema> Service Operations This service contains two operations: IPONZ Design Service Version 2 Page 22 of 38
1. submitdesign 2. renewdesign submitdesign Operation <wsdl:operation name="submitdesign"> <soap11:operation soapaction=""/> <wsdl:input name="submitdesignrequest"> <soap11:body use="literal"/> </wsdl:input> <wsdl:output name="submitdesignresponse"> <soap11:body use="literal"/> </wsdl:output> </wsdl:operation> Example Request XML <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ipol="http://ipol.webservice.g2b.fmit.co.nz" xmlns:app="http://www.iponz.govt.nz/xmlschema/designs/application" xmlns:des="http://www.iponz.govt.nz/xmlschema/designs"> <soapenv:header> <Authenticator> <ServiceName>I01</ServiceName> <Authorization>rAGXQfPS5NfPFKHB:l0fbDaPwee4QEqy/e+BfLvqxyBfAwa7c8eD4pv26uRo=< /Authorization> <Timestamp>20100913105325 NZST</Timestamp> <Client>100095730</Client> <Context>CTX0059</Context> </Authenticator> </soapenv:header> <soapenv:body> <ipol:submitdesign> <app:transaction> <app:designtransactionbody> <app:transactioncontentdetails> <app:transactionidentifier>ctx0059 Transaction IPONZ Design Service Version 2 Page 23 of 38
Identifier</app:TransactionIdentifier> <app:transactioncode>design E-Filing</app:TransactionCode> <app:transactiondata> <app:designapplicationdetails> <app:designapplication> <app:registrationofficecode>nz</app:registrationofficecode> <app:designapplicationreference>ctx0059 Des App Ref</app:DesignApplicationReference> <app:applicationcontact>applicant</app:applicationcontact> <app:designdetails> <des:design> <des:designapplicationkind>set of Articles</des:DesignApplicationKind> <des:designtitle languagecode="en" sequencenumber="1">ctx0059 Des Title</des:DesignTitle> <des:designdescription languagecode="en" sequencenumber="1">ctx0059 Des Desc</des:DesignDescription> <des:designspecialcase>wallpaper</des:designspecialcase> <des:noveltystatement languagecode="en" sequencenumber="1">ctx0059 Nov State</des:NoveltyStatement> <des:designrepresentationsheetdetails> <des:designrepresentationsheet> <des:representationsheetfilename>upload_pdf_document_01.pdf</des:representati onsheetfilename> <des:attachment>cid:1</des:attachment> </des:designrepresentationsheet> </des:designrepresentationsheetdetails> <des:prioritydetails> <des:priority> <des:prioritycountrycode>au</des:prioritycountrycode> <des:prioritynumber>1234567</des:prioritynumber> <des:prioritydate>2009-08-13</des:prioritydate> <des:prioritydocument> <des:documentfilename>upload_pdf_document_02.pdf</des:documentfilename> <des:attachment>cid:2</des:attachment> </des:prioritydocument> <des:designapplicantpriorityrelationshipdetails> <des:designapplicantpriorityrelationship>assignee</des:designapplicantpriorit yrelationship> <des:assigneebyvirtueof languagecode="en" sequencenumber="1">ctx0048 ByVirtue</des:AssigneeByVirtueOf> </des:designapplicantpriorityrelationshipdetails> IPONZ Design Service Version 2 Page 24 of 38
</des:priority> </des:prioritydetails> <des:applicantdetails> <des:designapplicant contact="true"> <des:newapplicant> <des:applicantlegalentity>company</des:applicantlegalentity> <des:applicantincorporationcountrycode>nz</des:applicantincorporationcountryc ode> <des:applicantaddressbook> <des:formattednameaddress> <des:name> <des:formattedname> <des:organizationname>opendata1 Limited</des:OrganizationName> </des:formattedname> </des:name> <des:address> <des:addresscountrycode>nz</des:addresscountrycode> <des:formattedaddress> <des:addressline languagecode="en" sequencenumber="1">ctx0059 Addr1</des:AddressLine> <des:addressline languagecode="en" sequencenumber="2">ctx0059 Addr2</des:AddressLine> <des:addressline languagecode="en" sequencenumber="3">ctx0059 Addr3</des:AddressLine> <des:addressline languagecode="en" sequencenumber="4">ctx0059 Addr4</des:AddressLine> <des:addressline languagecode="en" sequencenumber="5">ctx0059 Addr5</des:AddressLine> <des:addresssuburb>ctx0059 Suburb</des:AddressSuburb> <des:addresscity>ctx0059 City</des:AddressCity> <des:addressstate>ctx0059 State</des:AddressState> <des:addresspostcode>1234</des:addresspostcode> </des:formattedaddress> </des:address> </des:formattednameaddress> <des:postaladdress> <des:addresscountrycode>nz</des:addresscountrycode> <des:formattedaddress> <des:addressline languagecode="en" sequencenumber="1">ctx0059 Addr1</des:AddressLine> <des:addressline languagecode="en" sequencenumber="2">ctx0059 IPONZ Design Service Version 2 Page 25 of 38
Addr2</des:AddressLine> <des:addressline languagecode="en" sequencenumber="3">ctx0059 Addr3</des:AddressLine> <des:addressline languagecode="en" sequencenumber="4">ctx0059 Addr4</des:AddressLine> <des:addressline languagecode="en" sequencenumber="5">ctx0059 Addr5</des:AddressLine> <des:addresssuburb>ctx0059 Suburb</des:AddressSuburb> <des:addresscity>ctx0059 City</des:AddressCity> <des:addressstate>ctx0059 State</des:AddressState> <des:addresspostcode>1234</des:addresspostcode> </des:formattedaddress> </des:postaladdress> </des:applicantaddressbook> </des:newapplicant> </des:designapplicant> </des:applicantdetails> </des:design> </app:designdetails> <app:authorization> <des:authorizationkind>specific Authorization</des:AuthorizationKind> <des:authorizationdocument> <des:documentfilename>upload_pdf_document_03.pdf</des:documentfilename> <des:attachment>cid:3</des:attachment> </des:authorizationdocument> </app:authorization> </app:designapplication> </app:designapplicationdetails> </app:transactiondata> </app:transactioncontentdetails> </app:designtransactionbody> </app:transaction> </ipol:submitdesign> </soapenv:body> </soapenv:envelope> Example Response XML <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:body> IPONZ Design Service Version 2 Page 26 of 38
<submitdesignreturn xmlns="http://ipol.webservice.g2b.fmit.co.nz"> <TransactionResponse xmlns="http://www.iponz.govt.nz/xmlschema/designs/application"> <DesignTransactionResponseBody> <TransactionResponseContentDetails> <TransactionIdentifier>CTX0059 Transaction Identifier</TransactionIdentifier> <TransactionCode>Design E-Filing</TransactionCode> <TransactionResponseData> <DesignApplicationSummaryReport> <DesignApplicationReference>CTX0059 DES APP REF</DesignApplicationReference> <ApplicationContact>Applicant</ApplicationContact> <DesignApplicationDetails> <IPNewZealandDesignApplication xmlns="http://www.iponz.govt.nz/xmlschema/designs"> <DesignApplicationNumber>1002020</DesignApplicationNumber> <StatusCode>20</StatusCode> <StatusDescription>Filed</StatusDescription> <NZFilingDate>2010-09-13</NZFilingDate> <DesignApplicationKind>Set of Articles</DesignApplicationKind> <DesignTitle>CTX0059 Des Title</DesignTitle> <DesignDescription>CTX0059 Des Desc</DesignDescription> <DesignSpecialCase>Wallpaper</DesignSpecialCase> <NoveltyStatement>CTX0059 Nov State</NoveltyStatement> <PriorityDetails> <Priority> <PriorityCountryCode>AU</PriorityCountryCode> <PriorityNumber>1234567</PriorityNumber> <PriorityDate>2009-08-13</PriorityDate> <PriorityDocument>Upload_PDF_Document_02.pdf</PriorityDocument> <DesignApplicantPriorityRelationshipDetails> <DesignApplicantPriorityRelationship>Assignee</DesignApplicantPriorityRelationship> <AssigneeByVirtueOf>CTX0048 ByVirtue</AssigneeByVirtueOf> </DesignApplicantPriorityRelationshipDetails> </Priority> </PriorityDetails> <ApplicantDetails> <DesignApplicant contact="true"> <Applicant> <ApplicantKey> IPONZ Design Service Version 2 Page 27 of 38
<Identifier>5084</Identifier> </ApplicantKey> <ApplicantLegalEntity>Company</ApplicantLegalEntity> <ApplicantIncorporationCountryCode>NZ</ApplicantIncorporationCountryCode> <ApplicantAddressBook> <FormattedNameAddress> <Name> <FormattedName> <OrganizationName>OPENDATA1 Limited</OrganizationName> </FormattedName> </Name> <Address> <AddressCountryCode>NZ</AddressCountryCode> <FormattedAddress> <AddressLine>CTX0059 Addr1</AddressLine> <AddressLine>CTX0059 Addr2</AddressLine> <AddressLine>CTX0059 Addr3</AddressLine> <AddressLine>CTX0059 Addr4</AddressLine> <AddressLine>CTX0059 Addr5</AddressLine> <AddressSuburb>CTX0059 Suburb</AddressSuburb> <AddressCity>CTX0059 City</AddressCity> <AddressState>CTX0059 State</AddressState> <AddressPostcode>1234</AddressPostcode> </FormattedAddress> </Address> </FormattedNameAddress> <ContactInformationDetails> <Phone> <CountryCode/> <AreaCode/> <Number/> </Phone> </ContactInformationDetails> <PostalAddress> <AddressCountryCode>NZ</AddressCountryCode> <FormattedAddress> <AddressLine>CTX0059 Addr1</AddressLine> <AddressLine>CTX0059 Addr2</AddressLine> <AddressLine>CTX0059 Addr3</AddressLine> <AddressLine>CTX0059 Addr4</AddressLine> IPONZ Design Service Version 2 Page 28 of 38
<AddressLine>CTX0059 Addr5</AddressLine> <AddressSuburb>CTX0059 Suburb</AddressSuburb> <AddressCity>CTX0059 City</AddressCity> <AddressState>CTX0059 State</AddressState> <AddressPostcode>1234</AddressPostcode> </FormattedAddress> </PostalAddress> </ApplicantAddressBook> </Applicant> </DesignApplicant> </ApplicantDetails> <ContactDetails> <Contact> <ContactKey> <Identifier>5084</Identifier> </ContactKey> <ContactLegalEntity>Company</ContactLegalEntity> <ContactIncorporationCountryCode>NZ</ContactIncorporationCountryCode> <ContactAddressBook> <FormattedNameAddress> <Name> <FormattedName> <OrganizationName>OPENDATA1 Limited</OrganizationName> </FormattedName> </Name> <Address> <AddressCountryCode>NZ</AddressCountryCode> <FormattedAddress> <AddressLine>CTX0059 Addr1</AddressLine> <AddressLine>CTX0059 Addr2</AddressLine> <AddressLine>CTX0059 Addr3</AddressLine> <AddressLine>CTX0059 Addr4</AddressLine> <AddressLine>CTX0059 Addr5</AddressLine> <AddressSuburb>CTX0059 Suburb</AddressSuburb> <AddressCity>CTX0059 City</AddressCity> <AddressState>CTX0059 State</AddressState> <AddressPostcode>1234</AddressPostcode> </FormattedAddress> </Address> </FormattedNameAddress> IPONZ Design Service Version 2 Page 29 of 38
<ContactInformationDetails> <Phone> <CountryCode/> <AreaCode/> <Number/> </Phone> </ContactInformationDetails> <PostalAddress> <AddressCountryCode>NZ</AddressCountryCode> <FormattedAddress> <AddressLine>CTX0059 Addr1</AddressLine> <AddressLine>CTX0059 Addr2</AddressLine> <AddressLine>CTX0059 Addr3</AddressLine> <AddressLine>CTX0059 Addr4</AddressLine> <AddressLine>CTX0059 Addr5</AddressLine> <AddressSuburb>CTX0059 Suburb</AddressSuburb> <AddressCity>CTX0059 City</AddressCity> <AddressState>CTX0059 State</AddressState> <AddressPostcode>1234</AddressPostcode> </FormattedAddress> </PostalAddress> </ContactAddressBook> </Contact> </ContactDetails> </IPNewZealandDesignApplication> </DesignApplicationDetails> </DesignApplicationSummaryReport> </TransactionResponseData> </TransactionResponseContentDetails> </DesignTransactionResponseBody> </TransactionResponse> </submitdesignreturn> </soapenv:body> </soapenv:envelope> renewdesign Operation IPONZ Design Service Version 2 Page 30 of 38
<wsdl:operation name="renewdesign"> <soap11:operation soapaction=""/> <wsdl:input name="renewdesignrequest"> <soap11:body use="literal"/> </wsdl:input> <wsdl:output name="renewdesignresponse"> <soap11:body use="literal"/> </wsdl:output> </wsdl:operation> Example Request XML <?xml version="1.0" encoding="utf-8" standalone="no"?> <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance"> <soapenv:header> <Authenticator> <ServiceName>I02</ServiceName> <Authorization>T4WZUVoufkaGfsrK:/2TiKU+Oj/UCHIeIKgguHZ0ZaYNYZAafMJ4+J+jWQLg=< /Authorization> <Timestamp>20100419142929 NZST</Timestamp> <Client>100075277</Client> <Context>CTX002</Context> </Authenticator> </soapenv:header> <soapenv:body> <renewdesign xmlns="http://ipol.webservice.g2b.fmit.co.nz"> <ns1:transaction xmlns="http://www.iponz.govt.nz/xmlschema/designs/renewal" xmlns:ns1="http://www.iponz.govt.nz/xmlschema/designs/renewal"> <ns1:designtransactionbody> <ns1:transactioncontentdetails> <ns1:transactionidentifier>string</ns1:transactionidentifier> <ns1:transactioncode>design E-Renewal</ns1:TransactionCode> <ns1:transactiondata> <ns1:designrenewal> <ns1:designrenewaldetails> <ns1:renewalreference>string</ns1:renewalreference> <ns1:registrationnumber>30984</ns1:registrationnumber> </ns1:designrenewaldetails> </ns1:designrenewal> IPONZ Design Service Version 2 Page 31 of 38
</ns1:transactiondata> </ns1:transactioncontentdetails> </ns1:designtransactionbody> </ns1:transaction> </renewdesign> </soapenv:body> </soapenv:envelope> Example Response XML <?xml version="1.0" encoding="utf-8" standalone="no"?> <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance"> <soapenv:body> <renewdesignreturn xmlns="http://ipol.webservice.g2b.fmit.co.nz"> <TransactionResponse xmlns="http://www.iponz.govt.nz/xmlschema/designs/renewal"> <DesignTransactionResponseBody> <TransactionErrorDetails> <TransactionIdentifier>string</TransactionIdentifier> <TransactionCode>Design E-Renewal</TransactionCode> <TransactionError> <TransactionErrorCode>GIPR-REF3</TransactionErrorCode> <TransactionErrorText languagecode="en">iprenewalreference element value already used. Please supply a new one.</transactionerrortext> </TransactionError> </TransactionErrorDetails> </DesignTransactionResponseBody> </TransactionResponse> </renewdesignreturn> </soapenv:body> </soapenv:envelope> IPONZ Design Service Version 2 Page 32 of 38
APPENDIX 1: AUTHGEN To assist in testing a command line application is available to generate the XML Soap Header element required for authentication with BusinessData. This application requires a Java 1.6 JRE. Installation Before installation ensure a Java 1.6 JRE is installed on the PC. To check the Java version run the command java version from a command line. If Java is not found or the version is less than 1.6 go to http://www.oracle.com and download and install Java for your computer. Unzip the fmit-businessdata-x.x.zip to a directory on your PC. Windows Execute with no parameters to verify installation. (e.g., authgen.cmd). This should print the help instructions for the application. Update the properties accesskey and secretkey in your auth.properties with your Authencation Key ID and Secret Authentication Key. Mac/Linux Make the file authgen.sh executable. (e.g, chmod +x authgen.sh) Execute with no parameters to verify installation. (e.g.,./authgen.sh). This should print the help instructions for the application. Update the properties accesskey and secretkey in your auth.properties with your Authencation Key ID and Secret Authentication Key. Usage Running the program with no parameters will display usage information. Run the program to generate a header by using either authgen.sh or authgen.cmd. At minimum a command line parameter of the service name must be passed in. E.g.,./authgen.sh -servicename I01. Parameters such as service endpoint, access key and secret key are read from a properties file. By default configuration settings will be read in from a file named auth.properties. The configuration file to be used may be overridden using the props parameter. E.g.,./authgen.sh -servicename I01 - props eat.design.properties. The header will be written to standard out and a file will be written containing the header. By default this will be auth.txt. If a context parameter is provided (use of a context element is strongly recommended) the generated file will be <context>.txt. It is also possible to force the header to be generated into a specified file using the out parameter. IPONZ Design Service Version 2 Page 33 of 38
Signature Verification The authgen tool can also be used to generate a signature from a file containing a string to sign. IPONZ Design Service Version 2 Page 34 of 38
APPENDIX 2: SOAPUI SOAPui is a tool for testing web services. It supports a large range of standards and can be used to test both SOAP and REST services. An open source version of SOAPui is available from http://www.soapui.org/ and http://www.sourceforge.net. Importing a WSDL From the file menu choose New SOAPui project. This will bring up a project creation dialog. Enter the location of the WSDL file for the service being tested. This will populate the Project Name for you if you have not already filled this in. Upon clicking OK SOAPui will import the WSDL and show your new project in the Projects Navigator on the left of the window. Expand out the project and you will see all the operations of the service with a generated request for each. Endpoints When a WSDL is imported the location from the WSDL will become the initial service endpoint. New endpoints can easily be added by opening a request and selecting add new endpoint from the select box at the top of the window. Attachments When generating requests for an operation SOAPui will generate a CID for any attachment elements in the request. To attach a file to match the element click on the attachments tab at the bottom of the request pane. This will open up a section allowing attachments to be added. Click the + icon to choose an attachment. Select No when asked whether to cache the attachment in the request as this prevents switching between attachment mechanisms. Ensure that the Disable multiparts property is set to false. To send MTOM attachments, set the value of Enable MTOM to true in the operation properties. <Authenticator> Header Element To have requests authenticated by BusinessData it is necessary to generate the <Authenticator> header element using the authgen tool (Appendix 1). See the example below. <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ipol="http://ipol.webservice.g2b.fmit.co.nz" xmlns:app="http://www.iponz.govt.nz/xmlschema/designs/application" xmlns:trad="http://www.iponz.govt.nz/xmlschema/designs" xmlns:xm="http://www.w3.org/2005/05/xmlmime"> <soapenv:header> <Authenticator> <ServiceName>I01</ServiceName> IPONZ Design Service Version 2 Page 35 of 38
... <Authorization>T4WZUVoufkaGfsrK:2FLMlWGqCxnybWxBNtpsBiHaRfaRXBPooyB2qCmQIew=< /Authorization> <Timestamp>20100825144039 NZST</Timestamp> <Client>100075277</Client> <Context>4</Context> </Authenticator> </soapenv:header> IPONZ Design Service Version 2 Page 36 of 38
APPENDIX 3: ATTACHMENTS MTOM (Mime Transmission Optimization Mechanism) This service supports MTOM as the attachment mechanism. The following is an example of MTOM request showing the HTTP headers, Attachment element, and attachment mime header. POST http://www.businessdata.govt.nz/data/app/ws/sws/designservice-2.0 HTTP/1.0 Accept-Encoding: gzip,deflate SOAPAction: "" Content-Type: multipart/related; type="application/xop+xml"; start="<rootpart@soapui.org>"; start-info="text/xml"; boundary="---- =_Part_2_799593698.1282770134564" MIME-Version: 1.0 User-Agent: Jakarta Commons-HttpClient/3.1 Host: 192.168.70.125:8080 Proxy-Connection: Keep-Alive Content-Length: 65762 ------=_Part_2_799593698.1282770134564 Content-Type: application/xop+xml; charset=utf-8; type="text/xml" Content-Transfer-Encoding: 8bit Content-ID: <rootpart@soapui.org>... <des:representationsheetfilename>upload_pdf_document_01.pdf</des:representationshe etfilename> <des:attachment xm:contenttype="image/gif"><inc:include href="cid: 234523452345" xmlns:inc="http://www.w3.org/2004/08/xop/include"/></des:attachment>... ------=_Part_2_799593698.1282770134564 Content-Type: image/gif Content-Transfer-Encoding: binary Content-ID: <234523452345> An MTOM request can be identified by the content type application/xop+xml and the presence of a start-info token in the content type header. In MTOM an XOP element is injected inside the attachment element to reference the MIME Content- ID. IPONZ Design Service Version 2 Page 37 of 38
In SOAPui you can verify that the MTOM attachment mechanism has been used by selecting the Raw tab to the left of the Request pane. IPONZ Design Service Version 2 Page 38 of 38