DEALER
Nick Name Password
 
XML Real-time Error Messages   |   XML Availability Schedule and Naming Conventions   |   XML format for sending orders to Morris

 

SPECIFICATION FOR MORRIS REALTIME XML PROTOCOL
FOR WEB CUSTOMERS ONLY

Also see "XML Availability Schedule and Naming Conventions", and
"XML Format for Sending Orders"

General posting/XML notes:

This system actually includes two separate systems. One is the posting of XML to and from the Morris server on a real-time basis. The second is a real-time inquiry system, allowing your software to ask Morris's system for information.

In an ideal world a real-time interface would include both. For example, your system would POST and order to Morris's system. Over time various real-time POSTs of order status will get sent to your system by Morris's server. However, if you need information more quickly or believe that for some reason a POST was missed, then your software should then inquire on the status of the order.

always post to: machine.domain/cgi-bin/doxml.cgi. The current machine is morris.morriscostumes.com You will need to be assigned a user id and password.

There is great flexibility as to what gets POSTed to you when. You can get real-time availability updates, or simply daily batches and many things in between. You can get order POSTs when we receive it, pick it, invoice it, and ship it ... or just when we ship it.

incoming format always:

userid=xxxxxx
password=xxxxxx
xml_url=full path (URL) to xml file
message=done

The "command" is always the root of the XML document.

The cgi script will execute and will decide if it is an inquiry or something to process later or garbage.

outgoing format for garbage and processing is always:

Status=XXX
Text=XXXX {optional}
message=done

outgoing format for inquiry functions is always:

In the case of failure same as above.
In the case of success, no "Text", instead "xml_url" same as incoming.

Possible status:
    OK   (in this case Text may not appear)
    Rejected   (got it, did not like it, your fault :-)
    Failed   (got it, system error, my fault :-)
    (your/my is not personal comment, indicates which system had error)

Note on XML files given to you: they will persist a few days so you can get them whenever it pleases you. I would prefer you do the same although I am grabbing them at the time you post.

Possible values of "Code" in XML are the same as "Status" in POST with the addition of "Warning" which you may treat as "OK" and perhaps put on an exception report ...

In both XML and POST ignore capitalization, it has no meaning: OrderDetail = orderdetail = orderDETail
**EXCEPT: in rare cases where it may matter in data.

In both XML and POST the order of tags/name-value pairs has no meaning.

Your PO number is always converted to upper case in our system!

"Count" tags MUST match actual counts or you will be rejected (such as line count or order count)

Generic validation notes: on batches only the count and batch number are validated when sent. In fact it only goes back a few days to check batch numbers. On orders the count and po nummber are validated when sent, again only back a few days. Complete validation is performed when a daemon runs and loads the orders.

When the daemon runs, a URL is POSTED with the results. The daemon will do one POST for all "order" documents in a cycle. It will simply list po number and status. It will do one POST for each batch. You must supply me a URL for this.

I will also need a URL for automatic updates of available and orderdetail. I prefer ONE URL for all purposes --> you can parse it out :-) Everything sent to you via POST uses the exact same method and name/value pairs except I don't send my login information to you.

On order create commands, if an order is OK or WARNING it is added to our system. If Failed or Rejected it is not (actually failed is uncertain in that certain system errors could kill me before I can delete the order). I will also delete the XML, allowing you to thereby send again (with correction :-)

Posting script is:
     morris.morriscostumes.com/cgi-bin/doxml.cgi?userid=xxxx&password=yyyyy&xml_url=piggy&message=done

** "xxxx" is the username
** "yyyy" is the password

Status=Rejected
Text=Server Error 101
message=done


Instruction:
Note that the URL includes your site, your cgi-script, a "?" and then the name/value pairs separated by "&".  The correct response to the above is:  Status=Rejected Text=URL piggy not found message=done Because, of course, "piggy" is not a valid URL. If one uses his XML URL in the post it will work and upload the file. A good google is:  "how to post" url cgi (note that is all one search with "how to post" in quotes.  This search tells how to do it in many languages from perl to java.


~Inquiry functions~

Commands are:

Incoming:
<available>
  <sku>####</sku>
  <loc>###</loc> {optional, none given = all locations combined}
  <Detail>#</Detail> {option y or n, if not sent it is n}
</available>

Outgoing:
<available>
  <Sku>####</Sku>
  <part>###</part> <!-- Morris catalog part number -->
  <Loc>###</Loc> {optional, only if you gave it to me}

<!-- optional block if detail = y -->

  <Qty>###</Qty>
  <Detail>
    <Desc>########</Desc>
    <Weight>####</Weight>
    <Price>###</Price>
  </Detail>
  <Time>hh:mm:ss</time> (military)
</available>

Incoming:
<OrderDetail>
  <po>####</po>    <!-- OR -->
  <ordernum>#####</ordernum>    <!-- OR -->
  <tracknum>#####</tracknum>    <!-- OR -->
  <invoice>#####</invoice>    <!-- OR -->
</OrderDetail>

NOTE: if you pass more than one, the order of precedence is as above and the first found will be used.

po returns all orders (including splits) and all shipments (including multi-shipments) - the rest return one Morris order (either open or shipped)

Outgoing:
<OrderDetail>
  <Order> <!-- block repeats for POs with splits/multi -->
    <Status>###<Status>
    <!-- values: open, picking, invoiced, shipped -->
    <!-- invoice & shipped have mm/dd/yyyy appended -->
    <Header>
       <OrderNum>###</OrderNum>
       <InvoiceNum>###<InvoiceNum>
       <Location>###</Location>
       <Shipment>###</Shipment> <-- zero means no shipments -->
       <po>###</po> <! optional tags only if shipped and non-zero -->
       <InvAmt>###.##</InvAmt>
       <ChargeAmt>###.##</ChargeAmt>
       <DiscAmt>###.##</DiscAmt>
       <Shipping>###.##</Shipping>
       <Tax>###.##</Tax> <! optional tag only if NOT shipped -->
       <Total>###.##</Total>
       <Terms>##-#####</Terms> <! -- numeric code dash desc -->
       <Via>##-#####</Via> <! -- numeric code dash desc -->
       <BillTo>
         <Address>
           <Line1>####</Line1>
           <Street1>###</Street1>
           <Street2>###</Street2> <!-- optional if not blank -->
           <City>###</City>
           <State>###</State>
           <Zip>###</Zip>
           <Country>###</Country> <!-- optional, if not US -->
           <Residential>#</Residential> <!-- optional Y/N, default Y -->
         </Address>
       </BillTo>
       <ShipTo>
         <Address>
           <Line1>####</Line1>
           <Street1>###</Street1>
           <Street2>###</Street2> <!-- optional if not blank -->
           <City>###</City>
           <State>###</State>
           <Zip>###</Zip>
           <Country>###</Country> <!-- optional, if not US -->
           <Residential>#</Residential> <!-- optional Y/N, default Y -->
         </Address>
       </ShipTo>
     </Header>
     <Line> <!-- repeats for every line item -->
       <No>##</No> <!-- line number -->
       <Sku>##</Sku>
       <Location>##</Location> <!-- optional if not same as Header -->
       <Ordered>###</Ordered>
       <Ship>###</Ship> <!-- optional if shippable/shipped -->
       <Backorder>###</Backorder> <!-- optional if NOT shippable/shipped -->
     </Line>
<!-- optional blocks on UPS only shipments -->
     <Box> <!-- repeats for every box if shipped -->
       <No>##</No>
       <TrackNum>##</TrackNum>
     </Box>
<!-- optional tag on NON-UPS shipments if shipped -->
     <UntrackedBoxes>###</UntrackedBoxes> <!-- qty -->
   </Order>
   <RequestStatus>
     <Code>###</Code>
     <Text>###</Text> {optional, only if need}
     <Date>mm/dd/yyyy</Date>
     <Time>hh:mm:ss</time> (military)
   </RequestStatus>
</OrderDetail>

Order create functions:

Incoming:


<Batch>
  <Number>####</Number> <!-- may be A/N ... no punctuation -->
  <Count>###</Count> <!-- number of orders in batch -->
<!-- everything else is repeating blocks -->
</Batch>

Outgoing:

<Batch>
  <Number>####</Number>
  <Count>###</Count>
<!-- everything else is repeating blocks, usually order -->
  <order>stuff</order>
<!-- UNLESS there is an error so bad I don't know PO -->
  <error>
    <Text>####</Text>
    <FileName>###</FileName>
  </error>
  <BatchStatus>##</BatchStatus>
  <Status>###</Status>
  <Text>###</Text> <!-- optional -->mm/dd/yyyy</Date>
  <Time>hh:mm:ss</Time>
</Batch>

Incoming:
NOTE: the entire block "order" is also used in "batch"

<Order>
  <po>###</po>
  <via>###</via> <!-- optional, default from customer file -->
  <count>###</count> <!-- number of lines on order -->

  <BillTo>
    <Address>
      <Line1>####</Line1>
      <Street1>###</Street1>
      <Street2>###</Street2> <!-- optional if not blank -->
      <City>###</City>
      <State>###</State>
      <Zip>###</Zip>
      <Country>###</Country> <!-- optional, if not US -->
    </Address>
  </BillTo>
  <ShipTo>
    <Address>
      <Line1>####</Line1>
      <Street1>###</Street1>
      <Street2>###</Street2> <!-- optional if not blank -->
      <City>###</City>
      <State>###</State>
      <Zip>###</Zip>
      <Country>###</Country> <!-- optional, if not US -->
    </Address>
  </ShipTo>
<!-- repeat block for each line item -->
  <Line>
    <sku>##</sku>
    <qty>##</qty>
    <location>##</location> <!-- optional, don't use!!! ->
  </Line>
</Order>

OH: it would have been more consistent to put the header stuff into a header block like the orderdetail ... less fields so I did not bother. If it bugs you, let me know.

Outgoing:

NOTE: the entire block "order" is also used in "batch"

<Orders>
<!-- repeating block of all orders in cycle identical to <batch> -->
  <Order>
    <po>###</po>
    <Status>###</Status> <!-- OK, Warning, etc -->
    <Text>###</Text> <!-- optional -->
    <FileName>###</FileName> <!-- optional, usually only if errors -->
  </Order>
<!-- error blocks also possible, see batch -->
</Orders>

Update Functions:

These are functions where I send you automatic updates.
You will need to provide a URL; I will post to you the following:

    xml_url=full path (URL) to xml file
    message=done

The XML files are identical to the inquiry functions plus some additional batch uploads. The XML files will persist for days so you can get them anytime. The file names will not change for a given POST so if I send you (for example) available and then send it again 15 minutes later, the first XML file will have been overwritten and getting the second will be sufficient. You may choose to wait to reduce traffic.

Single updates:
    <available> will be sent whenever qty changes.
    <orderdetail> whenever an order changes (actually any order on a po)

There will be NO RequestStatus block, just a date and time.

Batch updates:
    <AvailableBatch> will be sent several times a day w/out detail

Will be sent weekly with detail:

    <detail>#</detail> <!-- y or n ... if y detail is sent -->
    <date>mm/dd/yyyy</date> <!-- for the batch! -->

<!-- This will be repeating blocks of the in the inquiry EXCEPT no RequestStatus block, only time -->

  <available>
    <sku>####</sku>
    <loc>###</loc> {optional, only if you gave it to me}
<!-- optional block if detail = y -->
    <detail>
      <desc>########</desc>
      <weight>####</weight>
      <price>###</price>
    </detail>
    <time>hh:mm:ss</time> (military)
  </available>
<AvailableBatch>

<OpenOrders> will be sent daily

You will get:

<OpenOrders>
  <date>mm/dd/yyyy</date> <!-- for the batch! -->
  <Time>hh:mm:ss</time>
<!-- repeating block -->
  <Order>
    <po>###</po>
    <OrderNum>###</OrderNum>
    <Status>###</Status> <!-- Open or Picking -->
  </Order>
</OpenOrders>

NOTE: it would be more consistent to have RequestStatus blocks but I did not bother (waste of bandwidth) ... if this bugs you let me know.

NOTE: I post results of batch and order creates realtime to you. This can at times fail. If so, the data is stored on disk. A daemon will wake every so often and re-send these to you.

NOTE: the definition of failure is me not getting back the "message=done" ... that is all you have to send.

NOTE: There will be no email messages any more, all POST/XML !

 


XML Real-time Error Messages   |   XML Availability Schedule and Naming Conventions   |   XML format for sending orders to Morris
©2009 Morris Costumes. All Rights Reserved.
     Programmed by Star Web Creations