!!!!! Westcon!Web!Services! Developer s!guide!!sap!order!status! Revision History Document Version. Publication Date 1.0 5/20/2015 Chakravarthy Sayani

Transcription

1 !!!!! Westcon!Web!Services! Developer s!guide!!sap!order!status! Revision History Document Version Publication Date Author 1.0 5/20/2015 Chakravarthy Sayani Record Description First Draft Page 1 of 17

2 ! Contents' Westcon Web Services... 1! Developer s Guide SAP Order Status... 1! Introduction... 3! Anatomy of the Web Service... 5! Security... 6! 1.1! Configure the Client for Security (for.net clients)... 7! 1.2! Configuring Security for non.net clients... 9! 2.! Order Status... 10! 2.0! Order Status SAMPLE REQUEST and RESPONSE (HTTP Soap Request and Response Platform Agnostic)... 11! 2.1! Order Status REQUEST SCHEMA... 15! 2.2! Order Status RESPONSE SCHEMA... 16!!! Page 2 of 17

3 Introduction! At Westcon Group, we help ease the flow of your own business process by providing you with the information you need on your transactions when you need it. The use of Web Services is an efficient method to exchange information directly between systems. These efficiencies are realized through the amount and frequency of distributor information which can be automatically entered directly into your system. The direct entry eliminates the manual keying of information as well as the time and cost of mailing and/or tracking documents. This document provides detailed instructions for using Westcon Web Services. These services will help you obtain pricing/availability/catalog related details as well as submitting a Purchase Order. At the end of the day, we would like you to run the Catalog Web Service and receive your custom catalog, search products and run Availability and Pricing transactions (Web Services) to get latest data. Depending on the response, form a Purchase Order document and submit it using the Purchase Order Web Service. Later, using the Order Tracking Web Service, check the status of your order; once shipped, track the status of the shipment using the Shipment Tracking Web Service. Finally, if there is a return of merchandise, use the RMA Web Service to execute it. Our end goal is to provide all of our sales-business-functions seamlessly and in a service-oriented way to you. Here are some topics covered in this guide:!!!! Guidelines Security (authentication and authorization) Web Service Methods and implementations Case Scenarios In our implementation, we chose to expose singular web services from which you would create a proxy class instance and call available web methods. At this point, these methods are expecting valid schemas that will be made available in this guide. We are trying to make sure that we provide detailed and clear exceptions and errors to ease your handling of calls. We are compliant to SOAP 1.1 and 1.2 and hosting our web services offerings via IIS 6.0. We use the WSE 3.0 security standards. We are hoping that you will be able to implement these services with no hassle. Below is a detailed look at our architecture: Page 3 of 17

4 Customer Partner... Go&to&eAcom& and&get&your& ws&key Authentication And&Logging 1"#SOAP#Calls: Inbound#calls#to#a# specific#web#method# under#proxy#web#services 4A&WS&Response: Web&Service&will&strip&down& the&incoming&xml&and&relay&the& necessary&information&to&the& customer 2 Proxy&Web&Services Availability Pricing PO Order&Status WEB&SERVER 2"#XML#Request: Your#request#will#go#through#a# series#of#validation#and# enrichment#phases#before# getting#submitted#to#sap Validation&and& Enrichment 3"#XML#Response: You#will#receive#SOAP#Fault# messages#in#case#the# validation#steps#fail.#upon# successful#submission#you# will#receive#a#confirmation# number Westcon SAP&Services Page 4 of 17

5 Anatomy!of!the!Web!Service! 1-! Customer makes a SOAP Call: before performing this call, the customer must obtain the WS-key (which with the account number will become the authentication username and password. 2-! Call is received by the Proxy Web Services, which authenticates the user. In case of an error, the connection is terminated with a SOAP Fault (login failed) 3-! After a successful login, user s web service method call executes another web service call to the SAP ERP environment: a.! SAP Web Service Call (Order Status) 4-! Response is forwarded back to the pending proxy web service method which forwards the request back to the customer. At this point, the transaction is terminated, however certain values are cached. Page 5 of 17

6 Security!! An important aspect for the consumption of the web services is Security. Although transactions such as pricing or availability are not very content sensitive; they are, fact, caller-sensitive; that is, we need make sure that the caller group is a limited, authenticated set of users that can use the site. One way of making sure that this is the case is to give them an authentication key; a randomly generated key that the user needs to include in the Web Services WSE proxy request. One of the ideal places that this key can be obtained is the e-commerce website!! The customer, when they login, would see a link that says please obtain your web services key here which would take them to a web page where the key would appear as well as instructions on how to integrate certain web services to their e-commerce architecture. This key would be an assignment to the account. This value resides in the web services database. This key can be changed only on an request at this point. In the future, this functionality will be embedded to our e-commerce sites. Currently, our implementation is using WSE 3.0 Web Services Extensions offered by Microsoft. The security mechanism used underneath is WS-Security 1.1 compliant. You can find more about WSE 3.0 at the following site: Page 6 of 17

7 1.1! Configure!the!Client!for!Security!(for!.NET!clients)! Add Service Reference 1.1.1! Binding!Configuration! Add the bindings in the client application s config file as below: <binding'name="saporderstatussoapbinding"'' ''''''''''closetimeout="00:30:00"'opentimeout="00:30:00"'' ''''''''''receivetimeout="00:30:00"'sendtimeout="00:30:00">' ''<security'authenticationmode="usernameovertransport"'' ''''''''''''allowinsecuretransport="true"'messageprotectionorder="signbeforeencrypt"'/>' ''<textmessageencoding'messageversion="soap11wsaddressingaugust2004"'/>' ''<httptransport'maxreceivedmessagesize=" "'/>' </binding>! 1.1.1! Endpoint!Configuration! <endpoint'address=" ''binding="custombinding"'bindingconfiguration="saporderstatussoapbinding"' ''contract="westconwssaporderstatus.saporderstatussoap"'name="saporderstatussoap"'/>! 1.1.2! Sample!Client!Code! //Assuming'you'named'the'service'reference'as'WestconWsSapOrderStatus' using'westconwebservicesclient.westconwssaporderstatus;'...' public'void'saporderstatustest()' {' ''''var'orderstatusproxy'='new'saporderstatussoapclient' ''''{' ''''''''ClientCredentials'=' ''''''''{' ''''''''''''UserName'='{'UserName'='CustomerNumber,'Password'='Password'}' ''''''''}' ''''};' ' ''''var'header'='new'westconwssaporderstatus.authenticationheader' ''''{' ''''''''username'='customernumber,' ''''''''password'='password' ''''};' ' ''''var'request'='new'westconwssaporderstatus.dt_westconorderstatusrequest' ''''{' ''''''''WestconOrderStatus'='new'WestconWsSapOrderStatus.DT_WestconOrderStatusRequestWestconOrderStatus' ''''''''{' ''''''''''''CustomerAccountNumber'='CustomerNumber,' ''''''''''''OrderNumberType'='"W",' ''''''''''''Orders'='new[]' ''''''''''''{' ''''''''''''''''new'arrayofdt_westconorderstatusrequestwestconorderstatusorderorder' ''''''''''''''''{' ''''''''''''''''''''OrderNumber'='" "' ''''''''''''''''}' ''''''''''''},' ''''''''''''ReturnSerialNumberAndMACAddress'='true,' ''''''''''''WestconMetadata'='new'WestconWsSapOrderStatus.WestconMetadata' ''''''''''''{' ''''''''''''''''Culture'='"E",' ''''''''''''''''OperationType'='"Get",' ''''''''''''''''SourceSystem'='"B2B",' ''''''''''''''''TimeStamp'='DateTime.Now,' ''''''''''''''''TransactionID'='"Westcon'Order'Status'1.0"' Page 7 of 17

8 ''''''''''''}' ' ''''''''}' ''''};' ' ''''try' ''''{' ''''''''var'response'='orderstatusproxy.orderstatus(header,'request);' ''''}' ''''catch'(exception'e)' ''''{' ''''''''HandleException(e);' ''''}' }! Page 8 of 17

9 1.2! Configuring!Security!for!non.NET!clients! You can use the following header section added to your SOAP Header. Please keep in mind that all Element IDs can be static (not changing). Timestamps would have to be updated and wsuexpires needs to be greater than the time of the call <soap:envelope!! xmlns:soap=" xmlns:xsi=" xmlns:xsd=" xmlns:wsa=" xmlns:wsse=" xmlns:web=" xmlns:wsu=" <soap:header>! <wsa:action> <wsa:messageid>urn:uuid:4a66732ebc9ceb4e6db95e6bcf598399a2c7</wsa:messageid>! <wsa:replyto>! <wsa:address> </wsa:replyto>! <wsa:to> <wsse:security!soap:mustunderstand="1">! <wsu:timestamp!wsu:id="timestampbbce68cebb656db4403b8fbfbfc386a51b787">! <wsu:created>2014b05b01t21:08:33z</wsu:created>! <wsu:expires>2021b05b01t21:08:33z</wsu:expires>! </wsu:timestamp>! <wsse:usernametoken!! xmlns:wsu=" 0cfed848Bf6e6B4549B80d0B2dfe22761bdc">! <wsse:username>{your!username!from!subscriber!details}</wsse:username>! <wsse:password!type=" 1.0#PasswordText">{your!PASSWORD!from!Subscriber!Details}</wsse:Password>! <wsse:nonce>q/hne+v6lz77at5nulsllg==</wsse:nonce>! <wsu:created>2014b05b01t21:08:33z</wsu:created></wsse:usernametoken>! </wsse:security>! </soap:header>!!!!!!!!!!<soap:body>!.!.! You can find a sample request below in SAP Order Status Sample Code section. Page 9 of 17

10 2.!Order!Status! For items found in the catalog, you can call the purchase order function to transmit a purchase order. Below are the objects required for the purchase order call: (if you called your web reference IPURProxy) Proxy! Request! ORDSTATProxy.purchaseOrderWse proxywse = new ORDSTATProxy.purchaseOrderWse(); ORDSTATProxy.POInboundRequest po = new ORDSTATProxy.POInboundRequest();! Response! ORDSTATProxy.POInboundResponse res = proxywse.westconpurchaseorder(po);! Where westconorderstatus is the web method executed. Please find the Order Status Request and Response fields below with examples. Required fields must be filled in, in order to get proper data. There are 4 main sections that you need to populate for a successful order request:! OrderNumberType: W or C for Westcon or Customer Order Number to be queried (respectively). If you will use your own value use C ; if you will use the Westcon Order Number to query use W in this field! ReturnSerialNumberAndMACAddress: provide true or false to instruct the service to return the Serial Number and MAC Address information in the call.! CustomerAccountNumber: Provide your username as it appears in the Subscriber s Details Document. (This value has to match the Username under UsernameToken in the Soap Header section)! OrderNumber: please include one or more Order Numbers in the Orders block. You cannot mix and match Customer and Westcon Order Numbers. Page 10 of 17

11 2.0!Order! Status! SAMPLE! REQUEST! and! RESPONSE!(HTTP! Soap! Request! and!response!!platform!agnostic)! For more details about the values, please refer to the Order Status Request and Response Schemas below. Caution: -! Please make sure to set your Content-Type to text/xml -! Please make sure to use the same date/time format as suggested SAMPLE!ORDER!STATUS! <soap:envelope!! xmlns:soap=" xmlns:xsi=" xmlns:xsd=" xmlns:wsa=" xmlns:wsse=" xmlns:web=" xmlns:wsu=" <soap:header>! <wsa:action> <wsa:messageid>urn:uuid:4a66732ebc9ceb4e6db95e6bcf598399a2c7</wsa:messageid>! <wsa:replyto>! <wsa:address> >! </wsa:replyto>! <wsa:to> <wsse:security!soap:mustunderstand="1">! <wsu:timestamp!wsu:id="timestampbbce68cebb656db4403b8fbfbfc386a51b787">! <wsu:created>2014b05b01t21:08:33z</wsu:created>! <wsu:expires>2021b05b01t21:08:33z</wsu:expires>! </wsu:timestamp>! <wsse:usernametoken!! xmlns:wsu=" wsu:id="securitytokenb0cfed848bf6e6b4549b80d0b2dfe22761bdc">! <wsse:username>use!your!username!from!subscriber s!details!document</wsse:username>! <wsse:password!type=" tokenbprofileb1.0#passwordtext">!use!your!password!(admin!key)!from!subscriber s!details! Document!</wsse:Password>! <wsse:nonce>q/hne+v6lz77at5nulsllg==</wsse:nonce>! <wsu:created>2014b05b01t21:08:33z</wsu:created></wsse:usernametoken>! </wsse:security>! </soap:header>!!!!<soap:body>!!!!!!!<web:orderstatus>! Page 11 of 17

12 !!!!!!!!!!!!!!!<web:request>!!! <WestconOrderStatus>!!!!!!!!!!!!!<OrderNumberType>W</OrderNumberType>!!! <ReturnSerialNumberAndMACAddress>true</ReturnSerialNumberAndMACAddress>!!!!!!!!!!!!!<CustomerAccountNumber>xxxxxxxxx</CustomerAccountNumber>!!!!!!!!!!!!!<Orders>!!!!!!!!!!!!!!!!<Order>!!!!!!!!!!!!!!!!!!!<OrderNumber>xxxxxxxxxxx</OrderNumber>!!!!!!!!!!!!!!!!</Order>!!!!!!!!!!!!!</Orders>!!!!!!!!!!</WestconOrderStatus>!!!!!!!!!!</web:request>!!!!!!!</web:orderStatus>!!!!</soap:Body>! </soap:envelope>! SAMPLE!ORDER!STATUS!RESPONSE! <soap:envelope xmlns:soap=" xmlns:xsi=" xmlns:xsd=" xmlns:wsa=" xmlns:wsse=" xmlns:wsu=" 1.0.xsd"> <soap:header> <wsa:action> <wsa:messageid>urn:uuid:da99da57-f44a-4105-b57c-c37aef35c2c7</wsa:messageid> <wsa:relatesto>urn:uuid:4a66732e-c9ce-4e6d-95e6-cf598399a2c7</wsa:relatesto> <wsa:to> <wsse:security> <wsu:timestamp wsu:id="timestamp-c2df5a27-2b1f c-b2d30c517ece"> <wsu:created> t22:06:38z</wsu:created> <wsu:expires> t22:11:38z</wsu:expires> </wsu:timestamp> </wsse:security> </soap:header> <soap:body> <orderstatusresponse xmlns=" <orderstatusresult> <WestconMetadata xmlns=""> <SourceSystem>B2B</SourceSystem> <TimeStamp> T22:06:36Z</TimeStamp> <OperationType>GET</OperationType> <Culture>E</Culture> <TransactionID>Westcon Order Status 1.0</TransactionID> Page 12 of 17

13 </WestconMetadata> <Orders xmlns=""> <Order> <ERPOrderNumber>xxxxxxxxxxxx</ERPOrderNumber> <CustomerOrderNumber>XXXXXX</CustomerOrderNumber> <OrderType>ZOR</OrderType> <HeaderStatusCode>74</HeaderStatusCode> <HeaderStatusDescription>Invoiced</HeaderStatusDescription> <OrderLines> <OrderLine> <ERPOrderLineNumber>000010</ERPOrderLineNumber> <ERPProductNumber>215180</ERPProductNumber> <LineQuantity>10.000</LineQuantity> <UnitOfMeasure>EA</UnitOfMeasure> <LineStatusCode>74</LineStatusCode> <LineStatusDescription>Invoiced</LineStatusDescription> <Tracking_Info> <Tracking_Number>XXXXXXXXXXXX</Tracking_Number> <Carrier_Name>US FDX 2-Day</Carrier_Name> </Tracking_Info> <ScheduleLines> <ScheduleLine> <PromisedDeliveryDate> </PromisedDeliveryDate> <PromisedQuantity>5.000</PromisedQuantity> <ScheduleLineStatusCode>74</ScheduleLineStatusCode> <ScheduleLineStatusDescription>Invoiced</ScheduleLineStatusDescription> </ScheduleLine> </ScheduleLines> <SerialNumbersandMACAddresses> <SerialNumberandMACAddress> <ProductSerialNumber/> <ProductMACAddress/> </SerialNumberandMACAddress> </SerialNumbersandMACAddresses> </OrderLine> <OrderLine> <ERPOrderLineNumber>000020</ERPOrderLineNumber> <ERPProductNumber>xxxxxxxxxx</ERPProductNumber> <LineQuantity>10.000</LineQuantity> <UnitOfMeasure>EA</UnitOfMeasure> <LineStatusCode>51</LineStatusCode> <LineStatusDescription>PO Sent</LineStatusDescription> <Tracking_Info> <Tracking_Number>xxxxxxxxxxxxx</Tracking_Number> <Carrier_Name>US FDX 2-Day</Carrier_Name> Page 13 of 17

14 </Tracking_Info> <ScheduleLines> <ScheduleLine> <PromisedDeliveryDate> </PromisedDeliveryDate> <PromisedQuantity>5.000</PromisedQuantity> <ScheduleLineStatusCode>51</ScheduleLineStatusCode> <ScheduleLineStatusDescription>PO Sent</ScheduleLineStatusDescription> </ScheduleLine> </ScheduleLines> <SerialNumbersandMACAddresses/> </OrderLine> </OrderLines> </Order> </Orders> </orderstatusresult> </orderstatusresponse> </soap:body> </soap:envelope> Page 14 of 17

15 2.1$Order$Status$REQUESTSCHEMA$ Merged$Schema$Name$ Required$ Repetitions$$ (0+,$1,$1+)$ Field$ Type/$ Length$ Example$ Comments$ WestconOrderStatus$!! 1!!!!! <WestconOrderStatus>$ CustomerAccountNumber! Required! 1! string(10)! !!! <CustomerAccountNumber> </CustomerAccountNumber>! OrderNumberType! Required! 1! string(1)! W! C!for!Customer!PO!Number,!W!for!Westcon!PO!Number!(W$is$ default)! ReturnSerialNumberAndMACAd determines!whether!serial!numbers!and!mac!addresses!are! Required! 1! boolean! TRUE! dress! returned! Orders$!! 1!!!!! <Orders>$ Order$!! 1!!!!! <Order>$!Repeat!for!multiple!orders! OrderNumber! Required!!! string(35)! ! Queried<OrderNumber>xxxx</OrderNumber>! Order$!! 1!!!!! <Order>$ Orders$!! 1!!!!! <Orders>$ WestconOrderStatus$!! 1!!!!! <WestconOrderStatus>$ Page 15 of 17

16 2.2$Order$Status$RESPONSE$SCHEMA$ Repetitio ns$$$(0+,$ 1,$1+)$ Merged$Schema$Name$ Field$Type/$ Length$ Example$ WestconOrderStatus$ 1!!!!! $$ Details$!!CustomerAccountNumber!!1! string(10)! ! Your!customer!account!number!returned! $$Errors$ 0+!!!!!!!!!ErrorNo!!!!! 1! Error!Number!!!!!ErrorDetail!!! text! System!Error.! Please!try! again! $$Errors$ 0+!!!!! $$ $$Orders$ 1!!!!! $$ This$block$will$be$populated$only$in$case$of$ system$errors$ Error!Details! $$$$Order$ 1+!!!!! $$!!!!!!ERPOrderNumber! 1! string(10)! 8500! Westcon!Order!Number!!!!!!!CustomerOrderNumber! 1!! String(40)! ! Customer!Order!Number!!!!!!!OrderType! 1! String(04)! ZOR,!ZRE! Order!Type!ZRE:!return!order,!ZOR:!regular!order!!!!!!!HeaderStatusCode! 1! String(02)! 71! Two!digit!number!!!!!!!HeaderStatusDescription! 1! String(40)! Invoiced! Description!for!the!HeaderStatusCode! $$$$$$OrderLines$ 1!!!!! $$ $$$$$$$$OrderLine$ 1+!!!!! $$!!!!!!!!!!ERPOrderLineNumber! 1! I(06)! 10! Order!Line!Number!!!!!!!!!!!ERPProductNumber! 1! String(18)! CP^7975G=! Item/Product/SKU!Number! LineQuantity! 1!!! 10! Quantity!! UnitOfMeasure! 1! String(02)! EA! Measurement!units!for!LineQuantity!!!!!!!!!!!LineStatusCode! 1! String(02)! IA! Internal!Order!Line!Status!Code!!!!!!!!!!!LineStatusDescription! 1! String(40)! Not!yet! Order!Line!Status!for!ZOR$Regular$Orders:!! Page 16 of 17

17 processed! Tracking_Info$ $$ $$ $$ $$ Tracking_Number!!!!!!!!! Carrier_Name!!!!!!!!! Tracking_Info$ $$ $$ $$ $$!!!!!!!!!!!!ScheduleLines! 1!!!!! $$ ScheduleLine$ 1+!!!!! $$!!!!!!!!!!!!!!ScheduleLineNumber! 1! I(06)! 1! Schedule!Line!Number!!!!!!!!!!!!!!!PromisedDeliveryDate! 1! DATS(08)! ! Promised!Delivery!Date!!!!!!!!!!!!!!!PromisedQuantity! 1! I(15)! 235! Promised!Quantity!!!!!!!!!!!!!!!ScheduleLineStatusCode! 1! String(02)! 71! Schedule!Line!Status!Code:!same!as!Line! Statuses,!not!all!Schedules!will!return!Status!!!!!!!!!!!!!!!ScheduleLineStatusDescription! 1!!! Invoiced! Description!for!ScheduleLineStatusCode! ScheduleLine$!!!!!! $$ ScheduleLines$!!!!!! $$ SerialNumbersandMACAddresses$ 0+!!!!! $$ SerialNumbersandMACAddress$ 0+!!!!! $$ ProductSerialNumber! 0+! String(20)! ! Serial!Number!for!given!Item!in!Schedule!Line! ProductMACAddress! 0+! String(20)! FF:AC:BB:22:3 3:44! MAC!Address!for!given!Item!in!Schedule!Line! SerialNumbersandMACAddress$ 0+!!!!! $$ SerialNumbersandMACAddresses$ 0+!!!!! $$ OrderLine$!!!!!! $$ OrderLines$!!!!!! $$ Order$!!!!!! $$ Orders$!!!!!! $$ WestconOrderStatus$!!!!!! $$ Page 17 of 17