Web2Plan Users Guide Follow

Web2Plan provides a communication method between your Web-to-print system and Printer’s Plan. It is designed to handle the following request types:

  • Order Requests: Web2Plan receives order data from your Web-to-print system and adds it to Printer’s Plan.  
    • /XmlListener.aspx
  • Price Requests: Web2Plan sends template price lists from Printer’s Plan to your Web-to-print system.
    • /Listener.aspx

Examples:

  • 255.1.1.1/PlanWeb/Listener.aspx
  • www.domain/PlanWeb/XmlListener.aspx

This article explains how Web2Plan handles these requests.

Order Requests. 

Web2Plan communicates with your Web-to-print system using a cXML document, which is a simple text file containing information about buyer and order specs. After receiving a request, Web2Plan converts the appropriate cXML data to a Printer’s Plan “Web Order”, with no human intervention.

This chapter explains the functional and technical specifications for standard cXML integration.

About cXML

cXML (Commerce eXtensible Markup Language) is a well-defined language designed specifically for B2B e-commerce. cXML allows you to easily automate order processing.

cXML Documents

cXML documents are simple text files containing values enclosed by predefined tags. There are two types of predefined tags: Elements and Attributes.

Elements

  • Elements are used to describe discrete items, such as Name, and subdivisions, such asPostalAddress.
  • Element names begin with an uppercase letter.
  • Element names are case-sensitive and use whole words with capitals (no hyphens) separating the words.

Attributes

  • Attributes are used to modify elements or provide contexts, such as addressID and quantity.
  • Attribute names begin with a lowercase letter.

Element and Attribute names are case-sensitive and use whole words with capitals (no hyphens) separating the words.

If optional elements and attributes have no content (they are null), leave them out entirely. Avoid empty or whitespace elements, because missing values can affect some parsers.

 

 

Key Elements and Attributes of Order Request (Purchase Order)

The following is a sample cXML document. The key elements and attributes are highlighted. Download a sample here to follow the explanation: http://printersplan.com/PlanWeb/JobRequests/Sample-UsingTemplate.xml 

<Header> Element 
The Header element contains addressing and authentication information. 

<ShipTo> Element 
ShipTo data is used either to add a new address or to determine the Printer’s Plan Customer number. Name, DeliverTo, and Street values are used to find the ShipTo address in Printer’s Plan database. 

< BillTo > Element 
BillTo data may be used to determine the Printer’s Plan Customer number. Name and Street values are used to find the BillTo in the database.

<Contact> Element 
Email is the most important element Web2Plan uses to determine the Buyer.

<Payment> Element
Payment data is added to Work Order notes not entered as a payment transaction.  Extrinsic elements of <OrderRequestHeader> are added to Work Order notes. Comments are ignored.

<ItemOut> Elements 
Order requests may include multiple ItemOut elements. Each ItemOut element is added to the order as a Printer’s Plan Item.
SupplierPartID is a key element. Web2Plan uses it to copy and paste Items from your catalog.
Quantity and Unit Price values are used to calculate the Item Price. 
URL element may contain the web address of an art file. If available, Web2Plan downloads the file to a special folder created for each customer.
Extrinsic elements contain additional information related to the order but are not defined by the cXML protocol. Web2Plan adds them to Item notes. 
Web2Plan ignores Comments. They contain information for human use.

How Web2Plan Processes Order Requests

  1. Authenticate Request

Web2Plan, currently, does not authenticate the sender of the request yet. Future version will use the “Sender” element to authenticate.

  1. Determine Request Type

If the type attribute of OrderRequestHeader element is"RFQ", Web2Plan processes the request as a “Web-Quote”<OrderRequestHeader type="RFQ">, otherwise, “Web-Order”. 

  1. Determine Buyer (Contact)

Web2Plan searches the Printer’s Plan database to:

  1. Find Contact by <Email> value of <Contact> or <BillTo> or <ShipTo> element, whichever is available first, starting with the <Contact> element.
  2. Find BillTo by <Name> and <Street> values of <BillTo> element. If no matching address is found, Web2Plan uses the Customer# of Contact; it does NOT add a new Customer to the database.
  3. Find ShipTo by <Name>, <DeliverTo>, and <Street> values of <ShipTo> element. If a matching address is not found, Web2Plan adds it the database.

Depending on the search result of Contact, Web2Plan determines the Buyer and the Customer#.

  1. If it finds only one Contact, Web2Plan uses its Customer# as the BillTo and Contact# as the Buyer.
  2. If it finds more than one Contact with the same email address, Web2Plan selects the Contact who has the same Customer# of the BillTo or ShipTo found above. This condition occurs when the purchasing agent of a parent company is also added as a buyer to child companies.
  3. If it does not find any Contact, Web2Plan uses the Customer# of BillTo or ShipTo, if found above, otherwise, it uses the default Web Customer# 20.

  1. Add Items

Web2Plan adds each <ItemOut> element as a Printer’s Plan Item. How each Item is added depends on the Template Number, which is the value of <SupplierPartID> (default) or <SupplierPartAuxiliaryID> element.

 

Depending on how the Template Number is formatted, Web2Plan copies and pastes Item(s) from your catalog. The following examples explain different options.

 

 

Examples - How Web2Plan Uses Template Number to add Items

 Example 1 - Template Number: 10-1

  1. Finds the Item #1 of Template #10 in Printer’s Plan.
  2. Reads the Requested Quantity (value of quantity attribute of <ItemOut> element).
  1. If the Requested Quantity = Item Quantity, it pastes Item #1 as is.
  2. If the Requested Quantity is different, it searches other Items of the template and pastes the one that matches the Requested Quantity and the Product Type of Item #1. 
  3. If there is no match, Web2Plan pastes Item #1, sets Item Quantity = Requested Quantity, and adds a note to show the New and Old quantities.
  1. Reads or calculates “Web Price” and adds a note to show the “Web Price”:
  1. If the request contains <ItemPrice> value (special to Web2Plan),
    Web Price = the value of <    ItemPrice>.
  2. If the request contains <UnitPrice>, <UnitOfMeasure>, and quantity values,
    Web Price =     quantity x UnitPrice / UnitOfMeasure.
    Acceptable <UnitOfMeasure> values are:  EA, EACH, LOT, M, and any number greater than zero.
  1. If the “Web Price” is different than the Item Price, it adds a note. If the Item price is not locked, it applies the “Web Price” to the Item Price.
  2. Sets Item Description = the value of <Description> or <ShortName> element of <ItemOut>.
  3. Adds all <Extrinsic> elements that have values to Item notes.
  4. If URL element contains the address of a file (document), download it to a special folder created for the customer.
     

 Example 2 - Template Number: 10 (no Item Number)

  1. Pastes ALL Items of Template# 10.
  2. Sets the description of the first Item = the value of <Description> or <ShortName> element of <ItemOut>.
  3. Sets the quantity of the ALL Items equal to the value of quantity attribute of <ItemOut> element.
  4. Prices all Items that are not locked.

 Example 3 - No Template Number Assigned (or Template not Found)

  1. Adds an Item with no Services.
  2. Sets Item Description = the value of <Description> or <ShortName> element of <ItemOut>.
  3. Sets the Item Quantity = the value of quantity attribute of <ItemOut> element.
  4. Adds “Web Price” and all <Extrinsic> elements that have values to Item notes.

To see a flowchart of how Web2Plan uses Template Numbers to add Items, click:

http://www.printersplan.com/WebSolutions/FlowChart-AddItems.pdf

 

Your Web-to-print system may request template prices from Web2Plan. A valid request must contain a Printer’s Plan template number and a quantity value. How Web2Plan processes price requests and how it responds depends on Template Number, Quantity, and Price Lock:

  1. Does the request include only Template Number or both Template and Item Numbers?
  2. Does the request include a single quantity or multiple quantities?
  3. Is the Printer’s Plan Item locked or not.

To see a flowchart of how Web2Plan processes Price Requests, click:

http://www.printersplan.com/WebSolutions/FlowChart-PriceRequest.pdf

There are two basic price requests. Default Price Request and Custom Price Request. The examples on the next pages explain each type and its variations.

Sample C# code to send an HttpWebRequest:

SendRequest(“http://franksprinting-dev.printvelocity.net/PlanWeb/Listener.aspx? todo=GetItemPrice&type=Template&jobno=10-1&quantity=500”);

protected string SendRequest(string RequestToSend)        
{
    try
    {
// create a POST request
HttpWebRequest request = (HttpWebRequest)WebRequest.Create(RequestToSend); 
request.Credentials         = CredentialCache.DefaultCredentials;                                
request.Method                         = "POST";        
request.ContentLength         = 0;
// set referrer to receive the response (REQUIRED)
request.Referer                         = Request.UrlReferrer.ToString();
// post the request and get a response
HttpWebResponse response = (HttpWebResponse)request.GetResponse();        
// get the stream to read the body of the response
Stream ResponseStream         = response.GetResponseStream();                                        
StreamReader reader         = new StreamReader(ResponseStream, Encoding.UTF8);
string sResponse                 = reader.ReadToEnd();
reader.Close();                                                                                        
ResponseStream.Close();
response.Close();
// see the response examples on the following pages
return sResponse;
    }
    catch (Exception ex)
    {
return "";
    }
  }

 

 

Examples - How Web2Plan Responds to Price Requests

Example 1 - Default Price Request - One Item

“Default Price Request” is the basic request for common product types, such as letterheads, envelopes, flyers, etc. To receive a “default” price for one Item:

  • The request must include both Template and Item Numbers.
  • Printer’s Plan Item must be unlocked.

This example shows two different requests for the following Printer’s Plan Template 10-1:

  1. Default Price Request for 500 Envelopes:
    http://franksprinting-dev.printvelocity.net/PlanWeb/Listener.aspx? 
    todo=GetItemPrice&type=Template&jobno=10-1&quantity=500

Response:

<Template_Item_10-1>
  <PriceRow>
    <Quantity>500</Quantity>
    <Price>58.15</Price>
    <Each>0.1163</Each>
  </PriceRow>
</Template_Item_10-1>
  1. Price List Request for 500, 1000, and 2000 Envelopes:
    (You may request up to 10 quantities, separated with commas).
    http://franksprinting-dev.printvelocity.net/PlanWeb/Listener.aspx?
    todo=GetItemPrice&type=Template&jobno=10-1&quantity=500,1000,2000 

Response:

<Template_Item_10-1>
  <PriceRow>
    <Quantity>500</Quantity>
    <Price>58.15</Price>
    <Each>0.1163</Each>
  </PriceRow>
  <PriceRow>
    <Quantity>1000</Quantity>
    <Price>86.05</Price>
    <Each>0.0860</Each>
  </PriceRow>
…
…
</Template_Item_10-1>

 

 

 Example 2 - Default Price Request - Multi-Part Item (Booklet)

This example also shows two different requests for the Printer’s Plan Template 7-1, which is a Booklet Job with SubItems.  Each Item is unlocked to receive Printer’s Plan default prices.

Web2Plan returns the sum of the default prices of sub-items (1.1, 1.2, and 1.3).

  1. Default Price Request for 500 Booklets:
    http://franksprinting-dev.printvelocity.net/PlanWeb/Listener.aspx?
    todo=GetItemPrice&type=Template&jobno=7-1&quantity=500

Response:

<Template_Item_7-1>
  <PriceRow>
    <Quantity>500</Quantity>
    <Price>1736.36</Price>
    <Each>3.4727</Each>
  </PriceRow>
</Template_Item_7-1>
  1. Default Price List Request for 500, 750, and 1000 Booklets:
    (You may request up to 10 quantities, separated with commas).
    http://franksprinting-dev.printvelocity.net/PlanWeb/Listener.aspx?
    todo=GetItemPrice&type=Template&jobno=7-1&quantity=500,750,1000 

Response:

<Template_Item_7-1>
  <PriceRow>
    <Quantity>500</Quantity>
    <Price>1736.36</Price>
    <Each>3.4727</Each>
  </PriceRow>
  <PriceRow>
    <Quantity>750</Quantity>
    <Price>2247.22</Price>
    <Each>2.9963</Each>
  </PriceRow>
…
…
</Template_Item_7-1>

Related articles

Powered by Zendesk