Document Properties
Kbid2857N6
Last Modified31-Aug-2020
Added to KB23-Mar-2018
Public AccessEveryone
StatusOnline
Doc TypeGuidelines, Concepts & Cookbooks
Product
  • IOM 2.9
  • IOM 2.15

Concept - IOM Invoice and Credit Note Generation

1 Introduction

An invoice is a commercial document issued by a seller to the buyer, indicating the products, quantities, and agreed prices for products or services the seller has provided to the buyer. An invoice indicates that the buyer must pay the seller, according to the payment terms.

Intershop Order Management (IOM) has the ability to create invoices or credit notes. This can happen in selected business processes, e.g., on receiving of order, dispatch, return or if an order is approved. This document describes the basic concepts of how to generate, design and customize invoices and credit notes within the IOM. The target audience are consultants and developers.

1.1 Glossary

Term

Description

Communication partnerA relation from IOM to an external 3rd-party system with which a defined communication exists. E.g., a shop, supplier or payment provider.
Also named partner in this document.

FO

Formatting Objects

FOP

Formatting Objects Processor

IOM

The abbreviation for Intershop Order Management

IOM Business Process Configuration FrameworkA framework to extend or modify the default business processes of IOM.
IOM Event Framework

A framework to extend or modify the default business processes of IOM based on events.

Message transmitterAn implementation that processes a transmission

PDF

Portable Document Format

TransmissionAn internal object of IOM that represents the requests and content for an external communication

XSL

Extensible Stylesheet Language

XSL-FO

XSL Formatting Objects

XSLT

XSL Transformation

1.2 References

2 Business Process Customization

The invoice creation is a process that must be configured. By default, after the initial setup of IOM, there is no configuration that uses invoicing events. Using the IOM Business Process Configuration Framework and the IOM Event Framework, it is possible to configure the time at which business process and process task generate invoices and credit notes. For business processes where the creation of an invoice can be useful, see Possible Processes for Invoicing Events.

Please refer to Overview - IOM Database Documentation for all processes (ProcessDO) and all invoicing types (TransmissonTypeDefDO) that are supported by the application by default.

The following model gives an overview of the processes for which creating invoices and credit memos can be useful. This overview represents three business processes, starting with the Order Business Process of IOM. Exemplary several customization points of the business process are marked which show where invoices can be created within the Order Business Process (e.g., at order received or order approved) and Order-Dispatch Business Process (e.g., at dispatch received or dispatch successfully processed). Furthermore, by default, the creation of credit notes can be configured at return received or return successfully processed within the Order-Return Business Process.

Business Process Invoice

3 Generation Process

IOM has the ability to generate invoices and credit notes at various times, e.g., on receiving of order, dispatch, return, on approving of orders and more. Therefore several configurations are required to fulfill the requirements of the business owner. The following sections will explain the major processes and how they are used to generate invoices or credit notes.

Using the IOM it is important to recognize the difference between invoicing process and invoice document generation. While invoicing involves calculating, checking processes, generating invoice numbers and many validation processes (see Invoicing Process), the generation process takes care of the actual creation of an invoice or credit note document.

3.1 Configuration of Invoicing Events

The invoice creation is a process that must be configured. By default, after the initial setup of IOM, there is no configuration that uses invoicing events. Please refer to the Recipe - Create Invoice at order received for more details about the major configuration steps to enable a customized event.

3.2 Invoices and Credit Notes Generation Process

Invoices and credit notes are generated via XSLT and Apache FOP. XSLT is part of the Extensible Stylesheet Language and is used for transforming XML documents into XSL-FO (please see XSL-Transformations (XSLT)). The Apache FOP is a Java application that is used to convert the XSL-FO file to PDF (see Apache Formatting Objects Processor (FOP)).

Creating Invoices

As shown in the diagram above, the XSLT processor takes a XML source document and a XSLT stylesheet. The XSLT processor loads the source XML document and starts processing from the root node. It finds the templates that match each node and processes them as described in the templates. The processor processes child elements recursively, continues until the processor returns to the root element and there are no more templates to be processed (see Invoice Document Templates).

3.3 Invoicing Process And Document Generation Workflow

The following model shows the workflow starting by the invoicing process. Depending on the configuration, a communication partner may exist which is required for the further process (see Recipe - Create Invoice at order received ). Create Invoicing Transmission generates an invoicing transmission for the communication partner with the transmission type CREATE_DOCUMENT. Accordingly, various checks and validations are carried out with the help of the data from the invoicing transmission. The process transmitter Create Invoicing Document calls the generation of invoice documents via the Message Transmitter. According to the Communication Partner configuration and the information in Invoicing Transmission the invoice/credit note documents will be generated by the Document Creation Message Transmitter.

InvoiceCreationGenerationProcessTrigger

4 Invoice Document Templates

The design and structure of invoices and credit notes is realized by a stylesheet and an XML schema. This allows the partner or the customer to determine the design of invoices or credit notes.

4.1 Stylesheet

4.1.1 General

Stylesheets are used to visually design the message content of invoices or credit notes. To create an XSL, different rules must be followed (e.g., XSLT namespace, template rules, etc.).

The stylesheet consists of set of templates. Each of these templates is applied so that the elements of the source XML can be processed. Please note that the XSLT stylesheet maps block elements and inline elements in source element to formatting objects.

The <fo:root> element of the XSLT is the root (top) node for the XSL-FO document. The children of the <fo:root> object are a single <fo:layout-master-set> object (which holds all masters used in the document), an optional <fo:declarations> object, and one or more <fo:page-sequence> objects.

Multiple sequences

An XSL-FO document can contain multiple <fo:page-sequences> (e.g., each chapter of a document could be a separate <fo:page-sequence> - this would allow chapter-specific content, such as the chapter title, to be placed within the header or footer).

The next diagram provides a rough representation of the page elements structure. A description for the main element used by default in the Stylesheet is shown in the diagram below.

XSLT Elements Structure

For more information about the main elements used in the stylesheet please see Reference - IOM Invoice and Credit Note Generation section XSLT Elements.

For more Informations about the XSTL-Stylesheet please refer to XSL-Transformations (XSLT).

4.1.2 Default Template

IOM comes with a default XSLT-template that can be used as a blueprint for customization. It is located at $OMS_HOME/ var/xslt/shop_default/supplier_default/invoice_credit_note_pdf.xslt. To create a new stylesheet for a specific purpose (e.g., for a new shop), a new folder (location) should be created:

  • New location for the shop: $OMS_HOME/ var/xslt/MyNewShop /supplier_default

with the following naming conventions:

  • MyNewShop = shop_<description required>_<shopID>

Note

File Naming Conventions - Special Characters Not Allowed

Please note that you can name the folder - MyNewShop - using only letters, numbers and the underscore.

E.g., new shop with shopIdD = 200:

Possible folder names:

shop _myNewShop_ 200

shop_1_myNew_Shop_200

shop_1_200

Please refer to Cookbook - IOM Invoice and Credit Note Generation for information about creating a new stylesheet for invoices and credit notes.

Also see Guide - Intershop Order Management - Installation for information about $OMS_HOME.

4.2 XML Schema (XSD)

The XML schema describes what a given XML document can contain, in the same way as a database schema describes the data that can be contained in a database (i.e., table structure, data types, constraints etc.). That means the XML schema defines the shape, or structure, of an XML document as well as rules for data content and semantics, e.g., which fields an element can contain, which sub elements it can contain and how many items can be present. Therefore, it is used as the basis for generating the XML-Document that can be treated as programming object.

The Document.xsd consists of:

  • Elements, which define properties of elements. These include the element name and target namespace. An important property is the type of the element, which constrains what attributes and children the element can have.
  • Types, which are described in the following section.

For more information refer to XML Schema Components and W3C XML Schema Definition Language (XSD).

4.3 Generated Document.xml

Based on the XML schema, Java beans are used to determine a lot of information about an order, and an XML file is created. For more details please see Invoice XML Document.

5 Further Notes

5.1 Decision Criteria for Processing

In contrast to the default business process, when invoices or credit notes have to be created or processed, further configurations need to be done. Often, additional prerequisites are required in order to start invoicing processes. These criteria are tested in decision beans. A decision bean is a filter that reflects whether an action should be processes or not. The major parameter is a business object like an order, a dispatch or a return. The methods of the bean can check if an action has to be executed on a business object, e.g., invoicing, document.

See Cookbook - IOM Invoice and Credit Note Generation of how to use a decision bean.

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets