RE: [ubl] What is the purpose for ItemInstance?

["G. Ken Holman" <gkholman@CraneSoftwrights.com>]

Thanks, Martin!

At 2008-04-28 23:02 +0200, Martin Forsberg wrote:
>The ItemInstance describes an actual physical instance of the product/item.
>If the product is Sony Vaio TZ, the ItemInstance is a physical computer
>with, perhaps, a serial number (that can be carried in the ItemInstance
>ABIE).

What are examples of items that are not a physical instances?  I 
suppose services.

I also suppose since I'm working with charges for the rental of items 
the customer is paying for the rental, not for the item itself:

    <cac:InvoiceLine>
      <cbc:ID>1</cbc:ID>
      <cbc:InvoicedQuantity>7</cbc:InvoicedQuantity>
      <cbc:LineExtensionAmount currencyID="CAD">29.17</cbc:LineExtensionAmount>
      <cac:Item>
        <cbc:Description>Thing-one</cbc:Description>
        <cac:AdditionalItemProperty>
          <cbc:Name>Base Cost Currency</cbc:Name>
          <cbc:Value>CAD</cbc:Value>
        </cac:AdditionalItemProperty>
        <cac:AdditionalItemProperty>
          <cbc:Name>Base Cost Amount</cbc:Name>
          <cbc:Value>1000</cbc:Value>
        </cac:AdditionalItemProperty>
        <cac:AdditionalItemProperty>
          <cbc:Name>Monthly Days Applicable</cbc:Name>
          <cbc:Value>30</cbc:Value>
        </cac:AdditionalItemProperty>
        <cac:AdditionalItemProperty>
          <cbc:Name>Monthly Rental Rate</cbc:Name>
          <cbc:Value>.025</cbc:Value>
          <cac:UsabilityPeriod>
            <cbc:StartDate>2008-04-15</cbc:StartDate>
            <cbc:EndDate>2008-04-20</cbc:EndDate>
            <cbc:DurationMeasure unitCode="DAY">5</cbc:DurationMeasure>
          </cac:UsabilityPeriod>
        </cac:AdditionalItemProperty>
      </cac:Item>
      <cac:Price>
        <cbc:PriceAmount currencyID="CAD">4.17</cbc:PriceAmount>
        <cbc:BaseQuantity unitCode="EA">1</cbc:BaseQuantity>
        <cbc:PriceType>Calculated as base * monthly rate / monthly
days * days</cbc:PriceType>
      </cac:Price>
    </cac:InvoiceLine>

Should I move the base cost to be a property of the item instance as follows?

   <cac:InvoiceLine>
     <cbc:ID>1</cbc:ID>
     <cbc:InvoicedQuantity>7</cbc:InvoicedQuantity>
     <cbc:LineExtensionAmount currencyID="CAD">29.17</cbc:LineExtensionAmount>
     <cac:Item>
       <cbc:Description>Thing-one</cbc:Description>
       <cac:AdditionalItemProperty>
         <cbc:Name>Monthly Days Applicable</cbc:Name>
         <cbc:Value>30</cbc:Value>
       </cac:AdditionalItemProperty>
       <cac:AdditionalItemProperty>
         <cbc:Name>Monthly Rental Rate</cbc:Name>
         <cbc:Value>.025</cbc:Value>
         <cac:UsabilityPeriod>
           <cbc:StartDate>2008-04-15</cbc:StartDate>
           <cbc:EndDate>2008-04-20</cbc:EndDate>
           <cbc:DurationMeasure unitCode="DAY">5</cbc:DurationMeasure>
         </cac:UsabilityPeriod>
       </cac:AdditionalItemProperty>
       <cac:ItemInstance>
         <cac:AdditionalItemProperty>
           <cbc:Name>Base Cost Currency</cbc:Name>
           <cbc:Value>CAD</cbc:Value>
         </cac:AdditionalItemProperty>
         <cac:AdditionalItemProperty>
           <cbc:Name>Base Cost Amount</cbc:Name>
           <cbc:Value>1000</cbc:Value>
         </cac:AdditionalItemProperty>
       </cac:ItemInstance>
     </cac:Item>
     <cac:Price>
       <cbc:PriceAmount currencyID="CAD">4.17</cbc:PriceAmount>
       <cbc:BaseQuantity unitCode="EA">1</cbc:BaseQuantity>
       <cbc:PriceType>Calculated as base * monthly rate / monthly 
days * days</cbc:PriceType>
     </cac:Price>
   </cac:InvoiceLine>

If so, this would lead to the conclusion that:

   - use <cac:Item> to describe that which is being paid for on the invoice
   - use <cac:ItemInstance> to describe the physical object related 
to that which is being paid for on the invoice (which might be the 
object itself or just related to the object)

Thanks for your patience with this level of questioning ... I'm 
worried we haven't documented the distinctions well enough in the 
descriptions in the common library:

   Item: "An association to Item."
   ItemInstance: "An association to Item Instance."

I just realized now that these ABIEs have their own definitions:

   Item: "Information directly relating to an item."
   ItemInstance: "Information about a specific instance of an item."

... but I'm thinking where they are associated should have the same 
level of detail in case it is contextually different because if its use.

If the invoice were for five Sony Vaio TZ computers, then I'm 
guessing the <cac:Item> would have the description "Sony Vaio TZ" and 
have five <cac:ItemInstance> children each with a different serial number.

Thanks again.

. . . . . . . . . Ken

--
World-wide corporate, govt. & user group XML, XSL and UBL training
RSS feeds:     publicly-available developer resources and training
G. Ken Holman                 mailto:gkholman@CraneSoftwrights.com
Crane Softwrights Ltd.          http://www.CraneSoftwrights.com/o/
Box 266, Kars, Ontario CANADA K0A-2E0    +1(613)489-0999 (F:-0995)
Male Cancer Awareness Nov'07  http://www.CraneSoftwrights.com/o/bc
Legal business disclaimers:  http://www.CraneSoftwrights.com/legal