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.
In IOM, the creation of invoices or credit notes can take place during selected business processes, e.g. order entry, order approval, dispatch or return.
This document describes the basic concepts of how to generate, design, and customize invoices and credit notes within the IOM.
This document is aimed at project developers.
Glossary
Term | Description |
|---|---|
Communication partner | A relation from IOM to an external 3rd-party system with which a defined communication exists. E.g., a shop, supplier or payment provider. |
FO | Formatting Objects, Apache Formatting Objects Processor (FOP) |
FOP | Formatting Objects Processor, Apache Formatting Objects Processor (FOP) |
Business Process Configuration Framework | A framework to extend or modify the default business processes of IOM. |
Event Framework | A framework to extend or modify the default business processes of IOM based on events. |
Message transmitter | An implementation that processes a transmission |
Transmission | An internal object of IOM that represents the requests and content for an external communication |
XSL | Extensible Stylesheet Language, see XSL-Transformations (XSLT) |
XSL-FO | XSL Formatting Objects, see Apache Formatting Objects Processor (FOP) and XSL-Transformations (XSLT) |
XSLT | XSL Transformation, see XSL-Transformations (XSLT) |
References
Business Process Customization
Invoice or credit note 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 tasks generate invoices and credit notes. For business processes where the creation of an invoice can be useful, see Possible Processes for Invoicing Events.
Please also 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 diagram gives an overview of the processes for which creating invoices and credit memos can be useful. The overview represents three business processes, starting with the Order Business Process. 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 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 Return Business Process.
Generation Process
First, 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.
Configuration of Invoicing Events
Invoice creation is a process that must be configured. By default, there is no configuration that uses invoicing events. Please refer Guide - IOM Dispatch Business Process | Create an Invoice for a concrete implementation.
Invoicing Process And Document Creation
The following model shows the workflow starting with the invoicing process. Depending on the configuration, a communication partner may exist which is required for the further process (see ). Create Invoicing Transmission generates an invoicing transmission for the communication partner with the transmission type CREATE_DOCUMENT. (Refer to Reference - IOM Document Creation Business Process.) 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.
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 (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)).
As shown in the diagram above, the XSLT processor takes an XML source document and an 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 continue until the processor returns to the root element and there are no more templates to be processed (see Concept - IOM Invoice and Credit Note Generation#Invoice Document Templates).
Invoice Document Templates
The design and structure of invoices and credit notes are realized by a stylesheet and an XML schema. This allows the partner or the customer to determine the design of invoices or credit notes.
Also, see Guide - IOM Dispatch Business Process | Create an Invoice.
Stylesheet
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 a 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 the source element to format 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 of the main element used by default in the Stylesheet is shown in the diagram below.
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 information about the XSTL-Stylesheet please refer to XSL-Transformations (XSLT).
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.
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 a 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 are described in the following section.
For more information refer to XML Schema Components and W3C XML Schema Definition Language (XSD).
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.
Further Notes
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 processed or not. A 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, or document.
See Guide - IOM Dispatch Business Process | Create an Invoice of how to use a decision bean.