Understanding Inbound E-Document Templates in JSON Format

Implementing an inbound e-document template enables the system to map which elements in the received XML file will provide data to which fields in the vendor bill or vendor credit record to be created from the XML file.

An inbound e-document template is in JSON format. For more information about JSON objects, go to the w3schools website JSON Introduction.

The bundle also includes a sample JSON template that can be used for parsing XML inbound e-documents for conversion into vendor bills or vendor credits. You can download the sample JSON template from the File Cabinet. You can view the count of inbound e-documents for conversion in the home page. To view this count, see Displaying the E-Documents Portlet on the Home Page.

The JSON inbound template contains the mapping to basic bill information:

tranid
trandate
currency
memo
item
- vendorname/vendorcode
- amount
- rate
- quantity
- description
- tax1amt
createdfrom

Note:

Following are the points applicable for inbound conversion of e-documents:

The alias for the inbound XML e-document object is ‘XML’. Use this when mapping the XML elements to keys. For example, ${XML.ParentElement.ChildElement}.
Inbound conversion does not support selecting subsidiaries in the transaction record. If the vendor is associated with multiple subsidiaries, the primary subsidiary of the vendor is selected in the transaction by default.

You can use or customize the sample JSON template that contains the mapping to basic vendor bill information:

          {
   "tranid": "${XML.Invoice.InvoiceHeader.InvoiceNumber}",
   "trandate": "${XML.Invoice.InvoiceHeader.InvoiceDate}",
   "currency": "${XML.Invoice.InvoiceHeader.Currency}",
   "memo": "${XML.Invoice.InvoiceHeader.Memo}",
   "createdfrom": "${XML.Invoice.InvoiceHeader.PONumber}",
   "item":[
      <#list XML.Invoice.InvoiceDetails.InvoiceItem as item>
      {
         "vendorcode": "${‌item.ItemName}",
         "quantity": "${‌item.Quantity}",
         "rate": "${item.UnitPrice?replace("$", "")}",
         "amount": "${item.LineItemSubtotal?replace("$", "")}",
         "description": "${‌item.Description}",
         "tax1amt": "${item.TaxAmount?replace("$", "")}"
      }
      <#if item_has_next>,</#if>
          </#list>  ],
   "expense":[
      <#list XML.Invoice.InvoiceDetails.InvoiceExpense as expense>
      {
         "amount": "${expense.Amount?replace("$", "")}",
         "memo": "${‌expense.Description}"
      }
      <#if expense_has_next>,</#if>
          </#list> ]
}

tranid, trandate, currency, memo, item, expense and createdfrom are called key names. Every key name must correspond to a field ID in the vendor bill record to be created from the received XML file. The key name is the reference that points to a field in the vendor bill record. Each key name must extract a value from the received XML file. The value of the key name will be the data that will be entered in the corresponding field of the vendor bill record.

tranid is a required key, used as reference number of the vendor bill. item is another required key name that is an of JSON objects with details of each item in the vendor bill.

createdfrom is a key name used if the vendor bill record to be created is from a Purchase Order. createdfrom will take up the value of the PO# of the source purchase order.

item is another required key name that is an of JSON objects with details of each item in the vendor bill. Under item is vendorcode, which is a required key name if the Multiple Vendor feature is enabled. vendorcode maps to the code assigned to a specific vendor of an item. If the Multiple Vendor feature is not enabled, the vendorname key name must be used. vendorname maps to the vendor name/code field of an item.

expense is also an of JSON objects that takes each expense in the vendor bill. Under expense are the amount and memo key names.

Note:

Ensure that your item records are updated and must have unique vendorname or vendorcode. Also, you must specify the Default Expense Account in the vendor record if you expect to receive bills for expense lines.

The JSON inbound template contains the mapping to basic bill credit information:

tranid
trandate
currency
memo
item
- vendorname/vendorcode
- quantity
- description
- amount
location
inventorydetailreq
createdfrom
apply

refnum

Note:

The alias for the inbound XML e-document object is ‘XML’. Use this when mapping the XML elements to keys. For example, ${XML[“ParentElement”][“ChildElement”]}.

Mapping is created so that the XML reference file is a valid credit memo PEPPOL generated e-document. Values for few keys have alias as custom because their logic of derivation is present in the inbound custom data source file named pl_custom_data_source_vendor_credit.js. This file is present in the bundle location Bundle 436209/src/comp/pl.

You can use this template along with custom data source implementation, or customize the sample JSON template and custom data source that contains the mapping to basic vendor credit information.

          {
"tranid": "${XML["D:CreditNote"]["cbc:ID"]}",
"trandate": "${custom["trandate"]}",
"duedate": "${custom["duedate"]}",
"memo": "${XML["D:CreditNote"]["cbc:Note"]}",
<#if custom["isMultiCurrency"] == "true">
"currency": "${custom["currencyISOCode"]}",
</#if>
"createdfrom": "${XML["D:CreditNote"]["cbc:BuyerReference"]}",
"item": [
<#assign index=0>
<#assign taxcodeString="taxcode_">
<#assign lineExtensionString ="lineextension_">
<#assign priceString ="price_">
<#list XML["D:CreditNote"]["cac:CreditNoteLine"] as item>
{
"account": "${item["cac:Item"]["cbc:Name"]}",
"vendorcode": "${item["cac:Item"]["cbc:Name"]}",
"vendorname": "${item["cac:Item"]["cbc:Name"]}",
"quantity": "${item["cbc:CreditedQuantity"]}",
"rate": "${custom[priceString+index]}",
"amount": "${custom[lineExtensionString+ index]}",
"location": "1",
"description": "${item["cac:Item"]["cbc:Name"]}",
"inventorydetailreq":false
<#assign index++>
}<#if item_has_next>,</#if>
</#list>
],
"apply": [
<#list XML["D:CreditNote"]["cac:BillingReference"] as ref>
{
"refnum": "${ref["cac:InvoiceDocumentReference"]["cbc:ID"]}",
}<#if ref?has_next>,</#if>
</#list>
]
}

tranid, trandate, currency, memo, item, apply, refnum, and createdfrom are called key names. Every key name must correspond to a field ID in the vendor credit record to be created from the received XML file. The key name is the reference that points to a field in the vendor credit record. Each key name must extract a value from the received XML file. The value of the key name will be the data that will be entered in the corresponding field of the vendor credit record.

tranid is a required key, used as reference number of the vendor credit.

createdfrom is a key name used if the vendor credit record to be created is from a purchase order.

createdfrom will take up the value of the PO# of the source purchase order.

item is another required key name that is an JSON object with details of each item in the vendor credit. Under item is vendorcode, which is a required key name if the Multiple Vendors feature is enabled. vendorcode maps to the code assigned to a specific vendor of an item. If the Multiple Vendors feature is not enabled, the vendorname key name must be used. vendorname maps to the vendor name or code field of an item. Items with vendor code will only be considered for inbound conversion. So, ensure that the items in the XML reference file have vendor code value under the Vendors section of the Purchasing tab in the item records along with the vendor's name. The vendor code should be same as the Item name.

apply is an optional key name that is present in an JSON object that contains the details of invoice (single or multiple) references that are applied on the credit memo. If the invoice ID is invalid, it will throw an error. Else, on a newly created vendor credit, the bills related to the invoice will be populated in Apply subtab.

At least the required key names must be present in an inbound e-document template. You must not change or edit required key names.

If you have custom records or fields, you can create your own key names that correspond to the field IDs of those custom fields. But make sure that your custom key names have data to extract from the XML files that you will receive from your vendors or other parties.

After setting up the key names and values of your JSON template, you can now implement it as an inbound e-document template. For more information, refer to step 6 of Creating E-Document Templates.

Related Topics