Document Processing Basics

Overview

• What you’ll learn: How documents flow through their lifecycle in iDempiere — from creation as drafts to completion, voiding, and reversal — and how document types, sequences, and period controls govern this process.
• Prerequisites: Lesson 1 (Introduction to iDempiere), Lesson 3 (Navigating the Interface), Lesson 7 (Chart of Accounts Setup)
• Estimated reading time: 22 minutes

Introduction

In iDempiere, nearly every business transaction — placing a sales order, receiving goods, issuing an invoice, recording a payment — is represented as a document. Documents are not static records; they move through a carefully defined lifecycle controlled by document statuses and actions. This lifecycle enforces business rules, ensures data integrity, triggers accounting postings, and maintains a complete audit trail.

Understanding document processing is one of the most fundamental skills for any iDempiere user or administrator. This lesson explains the document lifecycle in detail, covering every status and action, and clarifies concepts that frequently cause confusion — such as the difference between voiding and reversing, or when to use Prepare versus Complete.

What Is a Document in iDempiere?

A document in iDempiere is a transactional record that passes through a defined processing workflow. Not every record in the system is a document — master data records like Business Partners, Products, and Chart of Accounts entries are not documents. Documents are specifically the records that represent business events and have a DocStatus and DocAction field.

The primary documents in iDempiere include:

• Sales Order (C_Order): A customer’s commitment to purchase goods or services.
• Purchase Order (C_Order): Your commitment to buy from a supplier. Sales and purchase orders share the same table but are distinguished by their document type.
• Material Receipt (M_InOut): Records the physical receipt of goods into your warehouse from a vendor.
• Shipment (M_InOut): Records the physical delivery of goods from your warehouse to a customer. Like orders, receipts and shipments share the M_InOut table.
• Accounts Payable Invoice (C_Invoice): A vendor’s bill for goods or services received.
• Accounts Receivable Invoice (C_Invoice): Your bill to a customer for goods or services delivered.
• Payment (C_Payment): Records a monetary transaction — receiving money from a customer or paying money to a vendor.
• Bank Statement (C_BankStatement): Records transactions from your bank for reconciliation purposes.
• GL Journal (GL_Journal): Manual accounting entries posted directly to the general ledger.
• Inventory Move (M_Movement): Records the transfer of goods between warehouses or locators.
• Physical Inventory (M_Inventory): Records inventory count adjustments.

Document Status (DocStatus)

The DocStatus field tracks where a document currently stands in its lifecycle. iDempiere defines the following statuses:

Primary Statuses

• Drafted (DR): The document has been created but not yet processed. It is fully editable. This is the initial state of every new document. Drafted documents have no impact on inventory, accounting, or commitments — they are essentially work-in-progress records that can be freely modified or deleted.
• In Progress (IP): The document has been prepared (validated) but not yet completed. In this state, iDempiere has performed validation checks — verifying that required fields are populated, quantities are valid, prices exist, and business rules are satisfied. The document reserves resources (e.g., inventory is reserved for a sales order) but has not yet been finalized. The document can still be modified, though some fields may become restricted.
• Completed (CO): The document has been fully processed. It is now a permanent, immutable record of a business event. Completed documents trigger their full effects: inventory quantities update, accounting entries post to the general ledger, commitments are recorded, and the document receives its definitive document number. A completed document cannot be edited. To change it, you must void it or create a reversal.
• Voided (VO): The document has been nullified. Voiding a document cancels its effects. For documents that have not yet been completed, voiding simply sets all quantities and amounts to zero. For completed documents, the behavior depends on the document type (see the section on Void vs. Reverse below).
• Reversed (RE): The document has been reversed by creating a new, offsetting document. The original document and the reversal document reference each other, creating a clear audit trail. The combined effect of the original and reversal is zero.
• Closed (CL): The document has been administratively closed. Closing is used for documents that are completed but have remaining open quantities or amounts that should be written off. For example, a purchase order for 100 units where only 80 were received can be closed to indicate that the remaining 20 units will never be received. The 80 received units remain valid; only the outstanding balance is cancelled.

Additional Statuses

• Unknown (??): An undefined or error state that should not occur during normal operations. If you encounter this status, it typically indicates a processing error that needs investigation.
• Waiting Payment (WP): Used in specific workflows where a document is held pending payment confirmation before further processing.
• Approved (AP): Indicates the document has been approved through an approval workflow. This is an intermediate state between In Progress and Completed, used when organizational policies require managerial approval before document completion.

Document Action (DocAction)

While DocStatus tells you where a document is, DocAction defines what can be done next. The available actions change depending on the current status. Here are the document actions:

Core Actions

• Prepare (PR): Validates the document and transitions it from Drafted to In Progress. Preparation runs a series of checks: Are all mandatory fields filled? Do the referenced products exist in the price list? Are quantities positive? Is the business partner valid? If all checks pass, the document moves to In Progress status. Preparation also reserves inventory for sales orders and calculates tax amounts. Think of Prepare as a “dry run” that catches errors before final commitment.
• Complete (CO): Finalizes the document and transitions it to Completed status. If the document is still in Draft, Complete will first Prepare it (running all validation checks) and then complete it in a single step. Completion triggers the document’s real-world effects — inventory movements, accounting postings, and commitment updates. This is the most significant action in the document lifecycle because it makes the document’s impact permanent and the document itself immutable.
• Void (VO): Cancels the document. The behavior depends on the current status:
  • If the document is Drafted or In Progress: quantities and amounts are set to zero, and the status changes to Voided. No reversal document is created because no permanent effects existed.
  • If the document is Completed: the behavior varies by document type. Some completed documents can be directly voided (setting amounts to zero), while others require a reversal.
• Close (CL): Administratively closes the document, writing off any remaining open quantities or amounts. Available only for completed documents. Closing does not reverse any processed quantities — it only eliminates unfulfilled portions.
• Reverse – Correct (RC): Creates a new document that exactly offsets the original, effectively undoing the transaction. The reversal document has the same date as the original and posts to the same accounting period. Both documents are cross-referenced. Use Reverse-Correct when you discover an error in the current period and want to undo the transaction as if it never happened.
• Reverse – Accrual (RA): Similar to Reverse-Correct, but the reversal document is dated today (the current date) rather than the original document’s date. This means the reversal posts to the current accounting period. Use Reverse-Accrual when you need to undo a transaction from a prior period that has already been closed — the original entry remains in its period, and the offsetting entry appears in the current period.
• None (–): No action. This is the default when no further actions are available or appropriate.

Approval-Related Actions

• Approve (—): Approves the document in an approval workflow, allowing it to proceed to completion.
• Reject (—): Rejects the document in an approval workflow, sending it back for revision.

The Document Lifecycle in Practice

Let us trace a typical document through its lifecycle using a Sales Order as an example:

1. Creation (Draft): A sales representative opens the Sales Order window and creates a new record. They select the customer, enter order lines with products, quantities, and prices. The order is saved with DocStatus = DR. At this point, the order is just a plan — nothing has been committed.
2. Preparation (In Progress): The user clicks the document action button and selects “Prepare.” iDempiere validates all order lines, checks product availability, calculates taxes, and verifies the price list. If everything is valid, the status changes to DocStatus = IP. Inventory is now reserved (soft allocation) but not yet physically committed. The user can still modify the order if needed.
3. Completion (Completed): The user selects “Complete.” The order is finalized with DocStatus = CO. The document number sequence is consumed (the order gets its official number), and the order becomes immutable. For a standard sales order, completion does not move inventory or create accounting entries — those happen when the shipment and invoice are completed. However, the sales order now represents a firm commitment.
4. Downstream Documents: From the completed sales order, the user generates a Shipment (to deliver the goods) and an Invoice (to bill the customer). Each of these is a separate document with its own lifecycle. The shipment completion will decrease inventory; the invoice completion will create accounting entries (debit Accounts Receivable, credit Revenue).
5. Closing or Reversal (if needed): If the customer cancels part of the order after partial shipment, the user can Close the sales order to write off the remaining undelivered quantity. If the entire order was an error, the user can Void or Reverse it (and must also deal with any downstream shipments and invoices).

Document Types and Sequences

Document Types (C_DocType)

Every document in iDempiere is associated with a Document Type stored in the C_DocType table. The document type controls several critical behaviors:

• Document Base Type: Identifies the fundamental category (e.g., Sales Order, AP Invoice, AR Invoice, Payment). This determines which processing logic iDempiere applies.
• Document Sub-Type: Further refines behavior within a base type. For sales orders, sub-types include Standard Order, Warehouse Order, Credit Order, POS Order, and Prepay Order — each with different effects on inventory reservation, invoicing, and payment handling.
• Document Sequence: Specifies which number sequence to use for generating document numbers.
• GL Category: Determines the General Ledger category for accounting postings.
• Document Copies: How many copies to print by default.

You can create custom document types to support specific business processes. For instance, you might create a “Consignment Sales Order” document type with particular processing rules, or a “Debit Note” document type for invoice corrections.

Document Numbering (Document Sequences)

Document sequences (AD_Sequence) control automatic numbering. Each document type references a sequence that generates unique document numbers. Key sequence settings include:

• Prefix and Suffix: Text added before or after the number (e.g., prefix “SO-” produces numbers like SO-10001, SO-10002).
• Increment: The step between consecutive numbers (usually 1).
• Current Next: The next number to be assigned.
• Auto Numbering: When enabled, numbers are assigned automatically. When disabled, users must enter the document number manually (useful for vendor invoice numbers).

iDempiere supports both definitive numbering (assigned at completion) and provisional numbering (assigned at creation). For most document types, the definitive number is assigned when the document is completed, ensuring no gaps in the sequence — gaps could cause compliance issues in jurisdictions with strict sequential numbering requirements.

Period Control

Accounting Periods (C_Period)

iDempiere divides the fiscal year into periods (typically months) stored in the C_Period table. Each period has a start date, end date, and a status that controls whether documents can be posted to that period.

Period statuses include:

• Open: Documents can be completed and posted to this period. Normal day-to-day operations require the current period to be open.
• Closed: No new documents can be posted to this period. Closing a period is a standard month-end procedure that prevents accidental backdating of transactions.
• Permanently Closed: Like Closed, but cannot be reopened. Used after final audit to ensure no changes.

Period control can be configured at a granular level — you can close a period for AP Invoices while keeping it open for GL Journals, allowing the accounting team to post adjusting entries while preventing new vendor invoices from being backdated.

If a user attempts to complete a document with a date in a closed period, iDempiere will reject the action with an error. The administrator must either reopen the period or the user must change the document date to fall within an open period.

How Accounting Posting Works

The Fact_Acct Table

When a document is completed, iDempiere generates accounting entries in the Fact_Acct table. This table is the actual general ledger — every debit and credit resulting from every completed document lands here. The posting process:

1. The document completion triggers the posting engine.
2. The engine reads the document type’s accounting rules, the product category’s account mappings, the business partner’s accounting defaults, and the organization’s accounting schema.
3. It generates the appropriate journal entries. For example, completing an AR Invoice creates: Debit Accounts Receivable, Credit Revenue (and Tax Payable if applicable).
4. The entries are written to Fact_Acct with references back to the source document, enabling drill-down from any accounting entry to the originating transaction.

If posting fails (due to missing account mappings, for example), the document is still completed, but it is flagged with a posting error. The Post Immediately system setting controls whether posting happens synchronously (during completion) or asynchronously (via a background process). Administrators can view and resolve posting errors through the “Not Posted” process.

Void vs. Reverse: When to Use Which

One of the most common sources of confusion in iDempiere is the distinction between Void, Reverse-Correct, and Reverse-Accrual. Here is a clear guide:

• Void: Use for documents that have not yet been completed or for completed documents in the current period where you want to cancel without creating a visible reversal trail. Voiding zeroes out the document’s quantities and amounts. For completed documents, the accounting entries are reversed within the same document.
• Reverse – Correct: Use for completed documents when you need a clear, auditable reversal. This creates a new document with opposite signs, cross-referenced to the original. Both documents remain in the system with their original dates. This is the preferred method in most cases because it maintains a complete audit trail.
• Reverse – Accrual: Use when reversing a transaction from a prior, closed period. The reversal posts to the current date and current period, leaving the original period’s books undisturbed. This is essential for period-end integrity — you should never reopen a closed period just to reverse a document.

Common Document Processing Errors and Solutions

As you work with documents, you will inevitably encounter processing errors. Here are the most common ones and how to resolve them:

• “No Price found”: The product does not have a price in the price list associated with the business partner or the order. Solution: Add the product to the appropriate price list version, ensuring the version’s Valid From date is on or before the document date.
• “Period Closed”: The document date falls in a closed accounting period. Solution: Change the document date to a date in an open period, or ask the administrator to reopen the period.
• “Insufficient Inventory”: Attempting to ship more than the available on-hand quantity (when negative inventory is not allowed). Solution: Receive the goods first, adjust inventory, or reduce the shipment quantity.
• “Document Posting Error”: The document completed but failed to post to the general ledger, usually due to a missing account mapping. Solution: Check the product category accounting, business partner accounting, or bank account accounting for the missing account. Fix the mapping and repost.
• “Approval required”: The document requires approval from a supervisor before it can be completed. Solution: Route the document through the approval workflow or have an authorized user approve it.
• “Cannot Void/Reverse – dependent documents exist”: You are trying to void an order that already has completed shipments or invoices. Solution: Void or reverse the dependent documents first (invoices, then shipments), then void the order.

Key Takeaways

• Documents in iDempiere are transactional records (orders, invoices, payments, shipments) that follow a defined lifecycle controlled by DocStatus and DocAction.
• The primary lifecycle is Draft (DR) → In Progress (IP) → Completed (CO), with additional statuses for Voided (VO), Reversed (RE), and Closed (CL).
• Prepare validates a document without finalizing it; Complete makes it permanent and triggers accounting postings.
• Reverse-Correct creates an offsetting document with the original date; Reverse-Accrual uses today’s date — essential for handling corrections across closed periods.
• Document Types define processing behavior, numbering sequences, and accounting categories.
• Period Control prevents posting to closed periods, maintaining the integrity of finalized financial statements.
• The Fact_Acct table stores all accounting entries, linked back to source documents for full traceability.
• Most processing errors relate to missing prices, closed periods, insufficient inventory, or missing account mappings — all resolvable with proper setup.

What’s Next

With a solid understanding of how documents flow through iDempiere, Lesson 11 will introduce you to Basic Reporting. You will learn how to use print formats, report views, and Jasper Reports to extract meaningful information from the data your documents have created.