Import definition

Explore the comprehensive XML definition of cXML orders

To import orders created in an external application, Proactis uses the cXML standard.

Basic purchase order example

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.051/cXML.dtd">
<cXML version="0" payloadID="2022-12-21T09:51:[email protected]" timestamp="2022-12-21T09:51:17" xml:lang="en">
   <Header>
      <From>...</From>
      <To>...</To>
      <Sender>...</Sender>
   </Header>
   <Request deploymentMode="test">
      <OrderRequest>
         <OrderRequestHeader orderID="00041401" orderDate="2023-06-19T09:51:17" orderType="regular" type="new">
            <Total>
               <Money currency="EUR">121.0000</Money>
            </Total>
            <ShipTo>...</ShipTo>
            <BillTo>...</BillTo>
            <Tax>...</Tax>
            <Contact role="buyer">...</Contact>
            <Comments>...</Comments>
            <IdReference identifier="00041401" domain="OrderReference" />
            <Extrinsic name="ProactisSendSupplierOrder">true</Extrinsic>
            <Extrinsic name="ProactisSendERPOrder">true</Extrinsic>
         </OrderRequestHeader>
         <ItemOut quantity="5.0000" lineNumber="1" requestedDeliveryDate="2023-06-20T12:00:00" isAdHoc="yes">...</ItemOut>
      </OrderRequest>
   </Request>
</cXML>

Header

The purchase order starts with the Header which can used to authenticate the message and understand which buyer and supplier are used.

<Header>
   <From>
      <Credential domain="NetworkId">
         <Identity>BUYER IDENTIFIER</Identity>
      </Credential>
   </From>
   <To>
      <Credential domain="NetworkId">
         <Identity>SUPPLIER IDENTIFIER</Identity>
      </Credential>
   </To>
   <Sender>
      <Credential domain="NetworkId">
         <Identity>BUYER IDENTIFIER</Identity>
         <SharedSecret></SharedSecret>
      </Credential>
      <UserAgent>proactis-eu-agent</UserAgent>
   </Sender>
</Header>

The From Credential domain attribute and Identity element are used to identify the buyer domain who raised the purchase order.

The To Credential domain attribute and Identity element are used to identify the supplier the purchase order has to be sent to.

The Sender Credential domain attribute and Identity element are used to identify the buyer domain that has sent the purchase order. The SharedSecret element remains empty.

Request

The Request element contains the the OrderRequest and shows if this purchase order has been sent from a test or production environment.

UAT environment

<Request deploymentMode="test">

Production environment

<Request deploymentMode="production">

OrderRequestHeader

The OrderRequestHeader contains attributes that describe the orderID, orderDate, orderType and type.

<OrderRequestHeader orderID="00041401" orderDate="2023-06-19T09:51:17" orderType="regular" type="new" orderVersion="1">

The orderID attribute is the order identifier generated by the external application.

The orderDate attribute is the date and time the purchase order was generated by the external application in the format: YYYY-MM-DD'T'hh:mm:ss.

The orderType attribute is the type of purchase order. This is by default regular.

The type is the status of the purchase order: Only orders of type new are supported.

The orderVersion attribute shows the version number for this purchase order. By default this is version 1.

Total

The total element contains the Money element. The Money element shows the total value of all items included in the order including taxes. The currency attribute shows the currency code.

<Total>
   <Money currency="EUR">121.0000</Money>
</Total>

ShipTo

This ShipTo element contains address information on header level where the buyer would like the purchase order to be delivered.

<ShipTo>
   <Address isoCountryCode="NL">
      <Name xml:lang="en">Contact Address</Name>
      <PostalAddress>
         <Street>Damrak 123</Street>
         <City>Amsterdam</City>
         <State></State>
         <PostalCode>1000 AB</PostalCode>
         <Country isoCountryCode="NL">Netherlands</Country>
         <Extrinsic name="ProactisAddressee">John Doe</Extrinsic>
      </PostalAddress>
      <Phone name="Business">
         <TelephoneNumber>
            <CountryCode isoCountryCode="NL">31</CountryCode>
            <AreaOrCityCode>020</AreaOrCityCode>
            <Number>12345678</Number>
            <Extension></Extension>
         </TelephoneNumber>
      </Phone>
   </Address>
</ShipTo>

BillTo

This BillTo element contains address information on the billing address for the purchase order.

<BillTo>
   <Address isoCountryCode="NL">
      <Name xml:lang="en">Invoice</Name>
      <PostalAddress>
         <Street>Damrak 123</Street>
         <City>Amsterdam</City>
         <State></State>
         <PostalCode>1000 AB</PostalCode>
         <Country isoCountryCode="NL">Netherlands</Country>
      </PostalAddress>
      <Email name="default">[email protected]</Email>
      <Phone name="Business">
         <TelephoneNumber>
            <CountryCode isoCountryCode="NL">31</CountryCode>
            <AreaOrCityCode>030</AreaOrCityCode>
            <Number>12345678</Number>
            <Extension></Extension>
         </TelephoneNumber>
      </Phone>
   </Address>
</BillTo>

Tax

This is the summary Tax information for the purchase order.

<Tax>
   <Money currency="EUR">21.0000</Money>
   <Description xml:lang="en"></Description>
   <TaxDetail category="tax">
      <TaxableAmount>
         <Money currency="EUR">100.0000</Money>
      </TaxableAmount>
      <TaxAmount>
         <Money currency="EUR">21.0000</Money>
      </TaxAmount>
   </TaxDetail>
</Tax>

The TaxDetail element contains the category which is by default tax.

Contact

This contains the name and email address for the buyer. And Extrinsic with the name ProactisUserId is required to link the purchase order to a specific buyer as known in Proactis.

<Contact role="buyer">
   <Name xml:lang="en">John Doe</Name>
   <Email />
   <Phone>
      <TelephoneNumber>
         <CountryCode isoCountryCode="NL">31</CountryCode>
         <AreaOrCityCode>20</AreaOrCityCode>
         <Number>1234567</Number>
         <Extension></Extension>
      </TelephoneNumber>
   </Phone>
   <Extrinsic name="ProactisUserId">johndoe</Extrinsic>
</Contact>

Comments

This contains the comments added by the buyer. By default comments will not be shared with the supplier. To share comments with the supplier, add the attribute type="supplier".

<Comments>Comments
</Comments>

IdReference and Extrinsics

The IdReference contains the purchase order reference specified by the external application.

The Extrinsic with the name ProactisSendSupplierOrder will allows you the specify whether the purchase order still needs to be send to the supplier. Removing the Extrinsic will default to true.

The Extrinsic with the name ProactisSendERPOrder allows you to specify whether the purchase order needs to be send to the ERP application. Removing the Extrinsic will default to true.

<IdReference identifier="00041401" domain="OrderReference" />
<Extrinsic name="ProactisSendSupplierOrder">true</Extrinsic>
<Extrinsic name="ProactisSendERPOrder">true</Extrinsic>

ItemOut

The ItemOut element is repeated for each item that is included in the order.

<ItemOut quantity="5.0000" lineNumber="1" requestedDeliveryDate="2023-06-20T12:00:00" isAdHoc="yes">
   <ItemID>
      <SupplierPartID>FF1</SupplierPartID>
   </ItemID>
   <ItemDetail>
      <UnitPrice>
         <Money currency="EUR">10.0000</Money>
      </UnitPrice>
      <Description xml:lang="en">Blue Pen 22 cm
         <ShortName>Blue Pen</ShortName>
      </Description>
      <UnitOfMeasure>PCE</UnitOfMeasure>
      <PriceBasisQuantity quantity="1.0000" conversionFactor="1">
         <UnitOfMeasure>PCE</UnitOfMeasure>
      </PriceBasisQuantity>
      <Classification domain="" code=""></Classification>
   </ItemDetail>
   <ShipTo>...</ShipTo>
   <Tax>...</Tax>
   <Distribution>...</Distribution>
</ItemOut>

The ItemOut element contains attributes that describe the quantity, lineNumber, requestedDeliveryDate and type of product or service.

<ItemOut quantity="5.0000" lineNumber="1" requestedDeliveryDate="2023-06-20T12:00:00" isAdHoc="yes">

The ItemOut quantity attribute is the quantity ordered for the item.

The ItemOut lineNumber attribute is the line number for that item on the purchase order.

The requestedDeliveryDate attribute is the delivery date requested by the buyer. The attribute will only be present when the buyer has specified a delivery date.

The isAdHoc attribute indicates the item does not exist in a catalog, but is a free format line.

ItemID

This includes identifying codes for the item. The SupplierPartID element is the product/item/SKU code for the item.

<ItemID>
   <SupplierPartID>FF1</SupplierPartID>
</ItemID>

ItemDetail

This includes more descriptive elements about the item.

<ItemDetail>
   <UnitPrice>
      <Money currency="EUR">10.0000</Money>
   </UnitPrice>
   <Description xml:lang="en">Blue Pen 22 cm
      <ShortName>Blue Pen</ShortName>
   </Description>
   <UnitOfMeasure>PCE</UnitOfMeasure>
   <PriceBasisQuantity quantity="1.0000" conversionFactor="1">
      <UnitOfMeasure>PCE</UnitOfMeasure>
   </PriceBasisQuantity>
   <Classification domain="CommodityCode" code="2000">Facilities</Classification>
   <Classification domain="SpendingPool" code="2010">Office supplies</Classification>
   <Extrinsic name="Personal usage?">No</Extrinsic>
   <Extrinsic name="ProactisContractNumber">C1000000068</Extrinsic>
</ItemDetail>

The UnitPrice element is the price per unit excluding tax for the item.

The Description element is the name for the item.

The UnitOfMeasure element is the in which the unit is measured for the item.

The Classification elements are used to specify Commodity Code and Spending Pool.

Extrinsic elements are added for Smart Form fields. Fields that can be used to add buyer specific information.

A reference to a contract can be made by adding the Extrinsic with the name ProactisContractNumber.

ShipTo

This ShipTo element contains address information on where the customer would like the purchase order to be delivered.

<ShipTo>
   <Address isoCountryCode="NL">
      <Name xml:lang="en">Contact Address</Name>
      <PostalAddress>
         <Street>Damrak 123</Street>
         <City>Amsterdam</City>
         <State />
         <PostalCode>1000 AB</PostalCode>
         <Country isoCountryCode="NL">Netherlands</Country>
         <Extrinsic name="ProactisAddressee">John Doe</Extrinsic>
      </PostalAddress>
      <Email name="default" />
      <Phone name="Business">
         <TelephoneNumber>
            <CountryCode isoCountryCode="NL" />
            <AreaOrCityCode />
            <Number />
            <Extension />
         </TelephoneNumber>
      </Phone>
   </Address>
</ShipTo>

Tax

This is the Tax information for the item.

<Tax>
   <Money currency="EUR">10.5000</Money>
   <Description xml:lang="en">PLI Tax</Description>
   <TaxDetail category="tax" percentageRate="21.0000" taxRateType="3">
      <TaxableAmount>
         <Money currency="EUR">50.0000</Money>
      </TaxableAmount>
      <TaxAmount>
         <Money currency="EUR">10.5000</Money>
      </TaxAmount>
      <TaxLocation xml:lang="en"></TaxLocation>
   </TaxDetail>
</Tax>

The Money element total amount of tax for the item.

The Description element is the description of the tax being applied.

The category attribute is the type of tax that is being applied.

The percentageRate attribute is the tax rate being applied.

The taxRateType is a Proactis specific value assigned to the type of tax. The exact value can be seen in the Proactis settings for your organisation.

The TaxableAmount element is the subtotal amount excluding tax for the item.

The TaxAmount element is the amount of tax for the TaxableAmount.

Distribution

The Distribution contains the cost coding information assigned to the item.

<Distribution>
   <Accounting name="CostCoding">
      <Segment type="DepartmentId" id="A-2000" description="Finance" />
      <Segment type="CostCenterId" id="cc007" description="HR" />
      <Segment type="CostAccountId" id="CA01" description="CA01" />
      <Segment type="A10 Project code" id="A123" description="A123" />
   </Accounting>
   <Charge>
      <Money currency="EUR">60.5000</Money>
   </Charge>
</Distribution>

The Segment with the type DepartmentId contains the department ID linked to the item.

The Segment with the type CostCenterId contains the cost center value.

The Segment with the type CostAccountId contains the cost account value.

Cost Dimensions are added as separate Segment elements. The type being the name of the parent dimension.

Common cXML Elements

The tables show some examples on where to find common fields used from the Header and Item levels.

Header level

Detail	Path	Example
Customer	cXML/Header/From/Credential[@domain="NetworkId"]/Identity	BUYER IDENTIFIER
Supplier	cXML/Header/To/Credential[@domain="NetworkId"]/Identity	SUPPLIER IDENTIFIER
Sender	cXML/Header/Sender/Credential[@domain="NetworkId"]/Identity	BUYER IDENTIFIER
Environment	cXML/Request/@deploymentMode	test
Buyer Number	cXML/Request/OrderRequest/OrderRequestHeader/@orderID	00041401
Order Date	cXML/Request/OrderRequest/OrderRequestHeader/@orderDate	2022-12-21T09:51:17
Order Status	cXML/Request/OrderRequest/OrderRequestHeader/@type	new
Order Version	cXML/Request/OrderRequest/OrderRequestHeader/@orderVersion	1
Order Total	cXML/Request/OrderRequest/OrderRequestHeader/Total/Money	121.0000
Ship To	cXML/Request/OrderRequest/OrderRequestHeader/ShipTo
Bill To	cXML/Request/OrderRequest/OrderRequestHeader/BillTo
Total Tax Amount	cXML/Request/OrderRequest/OrderRequestHeader/Tax/Money	121.0000
Buyer Reference	cXML/Request/OrderRequest/OrderRequestHeader/IdReference[@domain="OrderReference"]	00041401

Item Level

Detail	Path	Example
Quantity	cXML/Request/OrderRequest/ItemOut[*]/@quantity	5.0000
Line Number	cXML/Request/OrderRequest/ItemOut[*]/@lineNumber	1
Delivery Date	cXML/Request/OrderRequest/ItemOut[*]/@requestedDeliveryDate	2023-06-20T12:00:00
Item Code	cXML/Request/OrderRequest/ItemOut[*]/ItemID/SupplierPartID	FF1
Unit Price	cXML/Request/OrderRequest/ItemOut[*]/ItemDetail/UnitPrice/Money	10.0000
Short Item Description	cXML/Request/OrderRequest/ItemOut[*]/ItemDetail/Description/ShortName	Blue Pen
Unit of Measure	cXML/Request/OrderRequest/ItemOut[*]/ItemDetail/UnitOfMeasure	PCE
Tax	cXML/Request/OrderRequest/ItemOut[*]/Tax/Money	10.5000
Department ID	cXML/Request/OrderRequest/ItemOut[*]/Distribution/Accounting/Segment[type="DepartmentId"]	A-2000
Cost Center ID	cXML/Request/OrderRequest/ItemOut[*]/Distribution/Accounting/Segment[type="CostCenterId"]	cc007
Cost Account ID	cXML/Request/OrderRequest/ItemOut[*]/Distribution/Accounting/Segment[type="CostAccountId"]	CA01