Difference between pages "Equinox Integration" and "Establish Opening Balances"

From ADempiere
(Difference between pages)
Jump to: navigation, search
This Wiki is read-only for reference purposes to avoid broken links.
(Basics and JBoss Setup)
 
(Change Warehouse Default Account: add Bank in Transit)
 
Line 1: Line 1:
= Eclipse Equinox Plugins in ADempiere =
+
= Overview =
 +
When setting up your accounting you will need to establish opening balances.  The information in this page is based on the following post and https://sourceforge.net/forum/message.php?msg_id=4329875
  
Eclipse Equinox (http://www.eclipse.org/equinox) is an implementation of OSGi R4.
+
There are suggestions on how to make this [[Opening Balances Form|process]] much easier.
Moreover, it provides applications with a plugin mechanism based on extension points and extensions satisfying them.
+
  
Integration with ADempiere is now underway under [[User:Viola|Joerg Viola]].
+
= Process =
  
Currently, an alpha demo is available.
+
== Create new Account Elements ==
The vision is to integrate it into Adempiere core an have every further extension be delivered as a plugin.
+
Create new Account Element for Debtor Clearing, Creditor Clearing, Bank Clearing and Inventory Clearing. All the accounts should be Balance Sheet accounts and the account numbers can be anything.  
  
= Technical documentation =
+
== Create new Product ==
 +
Create Product named Opening Product in System. Setup the Product to be Sold, Purchased and Stocked. The Product can be setup to any Product Category. The Default Account for Revenue of the Product should be set to Debtor Clearing and the COGS Default Account should be set to Creditors Clearing.
  
The integration consists of four components, implemented each in its own project in an eclipse environment.
+
== Setup Standard Cost for Products in Product Costs Window ==
 +
Create Standard Cost record for all Products and update the Current Price field for each and every Product with the closing value of the Product.  
  
== Adempiere patch ==
+
== Change Warehouse Default Account ==
 +
The Inventory Adjustment Default Account for all Warehouses and Locators should be changed to Inventory Clearing. Note down the Default Account before change.
  
* This patch currently is very simple. It consists of
+
== Change Default Bank In Transit Acount ==
** The interface IExtension, a factory for IExtensions called Extension and two implementations:
+
For one bank account that you will use during imports, set the default bank in-transit to the Debtor Clearing account. Not down the Default Account before you make the change.
*** The DefaultExtension contains code extracted from ADempiere core classes.
+
*** Equinox contains code to delegate the functionality to equinox plugins.
+
*** Which extension is used, depends on a prefix of e.g. the given classname: osgi://formClassName would use Equinox whereas formClassName would use the DefaultExtension and thus provide a clean fallback
+
** Patched core classes, namely:
+
** class org.compiere.Adempiere: Start all extensions
+
** class org.compiere.apps.form.FormFrame: Form class loading
+
** class org.adempiere.util.ProcessUtil: Process class loading
+
** class org.compiere.model-GridTab: Callout class loading
+
** The Equinox Extension starts the Equinox container
+
*** It does so in a seperate thread, because the platform modifies the context classloader
+
*** It fires up an OSGi console on port 1234, so that you may connect to it via telnet and see whats going on
+
*** It then asks for the so-called "host service", an OSGi-Service gatewaying requests from the patched adempiere core into equinox
+
** A lib-folder that must be copied to the runtime classpath
+
*** In fact, I don't like the way, libraries are re-packages during Adempiere install
+
*** Nevertheless, the equinox osgi jar '''must''' stay intact in order to work, so I switched to only deploy the patch itself, not the supporting libraries re-packaged
+
** An build file that, after having setup a build.properties does the re-packaging and deploying into an installed JBoss.
+
  
== Adempiere Extension ==
+
== Obtain Closing Trial Balance ==
 +
Obtain Closing Trial Balance with details for balances of Debtors, Creditors and Closing Stock amounts stated in the Trial Balance. Details should include Invoices, dates, amounts of individual Invoices and Business Partners.
  
* This is an extension fragment to the system bundle (OSGi slang...)
+
== Create new GL Journal and key-in Trial Balance ==
* It provides the ADempiere classes to the classpath of all plugins
+
Key-in Trial Balance amounts into respective accounts in GL Journal. However, for the Debtors, Creditors, Bank in Transfer and Closing Stock amounts, select the account to be Debtor Clearing, Creditor Clearing, Bank Clearing and Inventory Clearing respectively. The accounting entries will be as follows:
* It is merely declarative and contains no code
+
 +
DR Debtors Clearing (TB Debtors Amount)
 +
DR Inventory Clearing (TB Closing Stock Amount)
 +
  CR Creditors Clearing (TB Creditors Amount)
 +
  CR Bank Clearing (TB Bank In Transfer Amount)
 +
 +
== Create Invoice (Customers) for individual Invoices that make up the TB Debtors Amount ==
 +
 +
Each Invoice should be created with 1 Invoice (Customer) in the System. The Business Partner selected should be the actual Business Partner of the individual Invoices. The Accounting Date is the Opening Date and the Movement Date should be the actual Invoice Date. In the Invoice Line, the Product selected should be the Opening Product created above and multiple lines in the actual Invoice can be summarized into 1 Line. The amount should be the Total Amount of the actual Invoice.
 +
 +
Upon completely keying in the Invoice (Customer), the Invoice should be Completed and Posted. The account posting that occur should be as follows:
 +
 +
DR Debtors (Invoice Amount)
 +
  CR Debtors Clearing (Invoice Amount)
 +
 +
== Check Debtors Clearing account balance ==
 +
 +
Upon completely creating, completing and posting all Invoices (Customer), the Debtors Clearing Account should have a 0 balance.
 +
 +
== Create Invoice (Vendor) for individual Invoices that make up the TB Creditors Amount ==
 +
 +
The procedure is the same as for Invoice (Customer) above. The account posting should be as follows:
 +
 +
  DR Creditor Clearing (Invoice Amount)
 +
    CR Creditor (Invoice Amount)
 +
 +
== Check Creditors Clearing account balance ==
  
== Adempiere Equinox bundle ==
+
== Create Payment for individual Unpresented cheque that make up the TB Bank In Transfer Amount ==
 +
 +
Each unpresented cheque should be created with 1 payment in the System. The Business Partner selected should be the actual Business Partner of the individual payment. The Accounting Date is the Opening Date and the Transaction Date should be the actual Payment Date. The amount should be the Total Amount of the actual Cheque Payment.
 +
 +
Upon completely keying in the Payment, the Payment should be Completed and Posted. The account posting that occur should be as follows:
 +
 +
  DR Bank Clearing (Payment Amount)
 +
    CR Bank In Transfer (Payment Amount)
 +
 +
== Check Bank Clearing account ==
 +
The bank clearing account should now have a balance of zero.  If not, please review your previous steps.
  
* This is a bundle that connects plugins to the ADempiere internals
+
== Create new Physical Inventory record. ==
* It will provide the extension points for ADempiere
+
* Currently, there are
+
Create new Physical Inventory and key-in individual inventory quantity balance of Closing Stock as per closing stock count. The type of Physical Inventory selected should be Inventory Adjustment. Be very careful on the Warehouse selected for each record.
** ModelValidator
+
** Form
+
== Complete and Post Physical Inventory record ==
** Callout
+
** Process
+
Upon completely keying-in the Physical Inventory, Complete and Post the Physical Inventory. The account posting should be as follows:
* It implements and registers the so-called "host-service" that receives requests from the adempiere core and dispatches is to bundles, typically via extension points.
+
* It implements and registers the "dictionary service", that uses PackIn to import PackOut.xml.
+
  DR Inventory (Standard Cost)
* It provides a Plugin base class, AbstractAdempierePlugin, that handles install and startup:
+
    CR Inventory Clearing (Standard Cost)
** If the plugin is started for the first time:
+
*** If /META-INF/PackOut.xml exists, it is PackedIn
+
== Check Inventory Clearing balance ==
*** If not, the plugin is manually registered as an imported package
+
*** The method install() of the bundle is called
+
Upon completion of all Physical Inventory postings, the Inventory Clearing balance in the System should be 0.  
** The Method start() of the bundle is called (this substitutes start(BundleContext) from OSGi)
+
** On stop, The Method stop() of the bundle is called (this substitutes stop(BundleContext) from OSGi)
+
== Revert Default Accounts ==
* So, if you want a full re-install of the plugin, you must increment the version number or delete the corresponding entry in "Imported packages"
+
* Caution: Name and Version in the bundle header and in PackOut.xml '''must''' correspond!
+
Revert the Default Accounts for Inventory Adjustment for each Warehouse to the original Default Account.  
 +
 +
== Deactivate Opening Product ==
 +
 +
Select the Active checkbox for Opening Product in the Product Masterdata setup to No.  
 +
 +
== Generate Trial Balance from the System ==
 +
 +
Generate the Trial Balance as at the Opening Date and compare against the Closing Trial Balance obtained earlier.
 +
 +
== Deactivate Debtor Clearing, Creditor Clearing, Bank Clearing and Inventory Clearing ==
 +
 +
Uncheck the Active checkbox for the above in the Account Element setup.
  
== The TestPlugin ==
+
= Summary Outcome =
 +
You should now have your opening balances established in Adempiere.
  
* This is a very simple plugin testing the above
+
[[Category:Accounting]]
* Its activator does nothing
+
* It provides extensions to the extension points ModelValidator, Callout and Process
+
* The extension consists of a ModelValidator class (you wouldn't have thought so, would you?)
+
 
+
= How to =
+
 
+
== Basics and JBoss Setup ==
+
 
+
* Install an eclipse, checkout the ADempiere trunk (as adempiere) an install it.
+
** adempiere/adempiere/Adempiere/jboss will then contain a jboss ready to run
+
* The Code is in this branch: [http://adempiere.svn.sourceforge.net/viewvc/adempiere/branches/osgi/ '''/branches/osgi/''']
+
** There are several projects to be seperately checked out aside adempiereTrunk
+
* Check the following libs at [http://adempiere.svn.sourceforge.net/viewvc/adempiere/branches/osgi/Adempiere-patch/lib/ '''/branches/osgi/Adempiere-patch/lib/'''] are in your '''Adempiere-patch/lib''':
+
** org.eclipse.core.contenttype_3.3.0.v20080604-1400.jar
+
** org.eclipse.core.jobs_3.4.0.v20080512.jar
+
** org.eclipse.core.runtime.compatibility.auth_3.2.100.v20070502.jar
+
** org.eclipse.core.runtime_3.4.0.v20080512.jar
+
** org.eclipse.equinox.app_1.1.0.v20080421-2006.jar
+
** org.eclipse.equinox.common_3.4.0.v20080421-2006.jar
+
** org.eclipse.equinox.preferences_3.2.201.R34x_v20080709.jar
+
** org.eclipse.equinox.registry_3.4.0.v20080516-0950.jar
+
** org.eclipse.osgi.services_3.1.200.v20071203.jar
+
** org.eclipse.osgi_3.4.2.R34x_v20080826-1230.jar
+
** org.eclipse.update.configurator_3.2.201.R34x_v20080819.jar
+
* edit [http://adempiere.svn.sourceforge.net/viewvc/adempiere/branches/osgi/Adempiere-patch/build.properties?view=log '''Adempiere-patch/build.properties'''] and set the path to the adempiere project
+
* run [http://adempiere.svn.sourceforge.net/viewvc/adempiere/branches/osgi/Adempiere-patch/build.xml?view=log '''Adempiere-patch/build.xml''']
+
** It will instrument your Adempiere JBoss with the patch, all required equinox library and configurations
+
* Open AdempiereEquinox/META-INF/MANIFEST.MF
+
[[Image:EclipseExtPoint.PNG]]
+
** The tab "extension points" contains the ModelValidator point.
+
** Click on the third icon in the header ("Export deployable...") or in the menu File/Export/Plugin Development/Deployable plugins and fragments.
+
[[Image:EclipseDeploy.PNG]]
+
** Select AdempiereEquinox, AdempiereExtension and the TestPlugin for deployment
+
** Choose as destination directory: <path to adempiere project>\adempiere\adempiere\Adempiere\jboss\server\adempiere\deploy\adempiere.ear\lib
+
** Click Finish
+
** In the ear deployment in JBoss, you should have a lib folder containing jar, a configuration folder and a plugins folder with the three plugins from above
+
* Start your JBoss
+
** Watch out for the lines:
+
INFO  [STDOUT] Starting Equinox...
+
INFO  [STDOUT] Listening on port 1234 ...
+
INFO  [STDOUT] Adempiere Host Bundle started
+
INFO  [STDOUT] Got Val Engine: ModelValidationEngine[Validators=#1, ModelChange=#1, DocValidate=#1]
+
INFO  [STDOUT] ModelValidator on: AD_User
+
INFO  [STDOUT] Hello World!!
+
Congrats! Your equinox container started, opened a telnet port, started the Host Bundle which in turn got a ModelValidation engine, found the TestPlugin listening on Table AD_User and registered it on the Engine.
+
* Now fire up the ZK Web UI, login and change a user
+
** You will see:
+
INFO  [STDOUT] ModelChange 2 on AD_User:1000000
+
INFO  [STDOUT] ModelChange 5 on AD_User:1000000
+
** Phew! Adempiere plugin via equinox is working!
+
* Now open TestPlugin/META-INF/MANIFEST.MF
+
[[Image:EclipseExt.PNG]]
+
** On the extension tab, you can see why it listens on AD_User: It was declared to the host bundle in the manifest!
+
 
+
== Swing Client Setup ==
+
 
+
If you have successfully installed Equinox into your JBoss, making it available in the Swing Client is easy:
+
* run [http://adempiere.svn.sourceforge.net/viewvc/adempiere/branches/osgi/Adempiere-patch/build.xml?view=log '''Adempiere-patch/build.xml''']
+
** Use the target dist-client for instrumenting your swing client
+
* Repeat the plugin deployment script above, using $ADEMPIERE_HOME/lib destination directory
+
* ... and eventually a nasty step: Edit the script $ADEMPIERE_HOME/lib/RUN_Adempiere.sh (or .bat) locate the line where the CLASSPATCH is set up and add $ADEMPIERE_HOME/lib/org.eclipse.osgi_3.4.2.R34x_v20080826-1230.jar to it.
+
 
+
== Build your own plugin ==
+
* simply create a new eclipse plugin project
+
* use AdempiereEquinox as required bundle
+
* register a ModelValidator class as the extension
+
* deploy the plugin to JBoss as above
+
* restart JBoss (or use the telnet session an stop/start the host bundle)
+
 
+
== Form extensions ==
+
It is now possible to deploy swing forms via a plugin. To do this, create a plugin and specifiy some dependencies:
+
 
+
[[Image:EclipseFormDep.PNG]]
+
 
+
Switch to the extension tab, click add and choose the AdempiereEquinox.Form extension point.
+
Right-click on the new extension and choose New.../client. Create or select the class (must be of type FormPanel)
+
 
+
[[Image:EclipseFormExt.PNG]]
+
 
+
Deploy the plugin.
+
As usual, as SuperUser create a new Form, spüecifying the class as above and a new Menu entry.
+
Try it!
+
 
+
== WebForm extensions ==
+
 
+
This works essentially the same as for Form above, extending the point WebForm of course.
+
Nevertheless, two things are different:
+
* Since plugins essentially are deployed in the EJB layer but must have access to classes in the web layer (org.adempiere.webui.* and org.zkoss.*), the JBoss WAR classloader has to be turned off. This is a drawback since we no longer have classpath separation between web- and ejb-tier. You do this by switching the attribute UseJBossWebLoader to true in $JBOSS/server/adempiere/deploy/jboss-web.deployer/META-INF/jboss-service.xml.
+
* You have to import several additional packages in your plugin, at least: org.adempiere.webui.component, org.adempiere.webui.panel,org.zkoss.zk.ui and org.zkoss.zk.ui.event.
+
 
+
= See Also =
+
* [http://sourceforge.net/forum/forum.php?thread_id=2143547&forum_id=610546 SourceForge discussion]
+
* [[ADempiere/OSGi Integration]]
+
* [[RoadmapToModularization]]
+
 
+
[[Category:Projects and Tools]]
+

Revision as of 08:02, 6 May 2010

Overview

When setting up your accounting you will need to establish opening balances. The information in this page is based on the following post and https://sourceforge.net/forum/message.php?msg_id=4329875

There are suggestions on how to make this process much easier.

Process

Create new Account Elements

Create new Account Element for Debtor Clearing, Creditor Clearing, Bank Clearing and Inventory Clearing. All the accounts should be Balance Sheet accounts and the account numbers can be anything.

Create new Product

Create Product named Opening Product in System. Setup the Product to be Sold, Purchased and Stocked. The Product can be setup to any Product Category. The Default Account for Revenue of the Product should be set to Debtor Clearing and the COGS Default Account should be set to Creditors Clearing.

Setup Standard Cost for Products in Product Costs Window

Create Standard Cost record for all Products and update the Current Price field for each and every Product with the closing value of the Product.

Change Warehouse Default Account

The Inventory Adjustment Default Account for all Warehouses and Locators should be changed to Inventory Clearing. Note down the Default Account before change.

Change Default Bank In Transit Acount

For one bank account that you will use during imports, set the default bank in-transit to the Debtor Clearing account. Not down the Default Account before you make the change.

Obtain Closing Trial Balance

Obtain Closing Trial Balance with details for balances of Debtors, Creditors and Closing Stock amounts stated in the Trial Balance. Details should include Invoices, dates, amounts of individual Invoices and Business Partners.

Create new GL Journal and key-in Trial Balance

Key-in Trial Balance amounts into respective accounts in GL Journal. However, for the Debtors, Creditors, Bank in Transfer and Closing Stock amounts, select the account to be Debtor Clearing, Creditor Clearing, Bank Clearing and Inventory Clearing respectively. The accounting entries will be as follows:

DR Debtors Clearing (TB Debtors Amount) 
DR Inventory Clearing (TB Closing Stock Amount) 
  CR Creditors Clearing (TB Creditors Amount) 
  CR Bank Clearing (TB Bank In Transfer Amount) 

Create Invoice (Customers) for individual Invoices that make up the TB Debtors Amount

Each Invoice should be created with 1 Invoice (Customer) in the System. The Business Partner selected should be the actual Business Partner of the individual Invoices. The Accounting Date is the Opening Date and the Movement Date should be the actual Invoice Date. In the Invoice Line, the Product selected should be the Opening Product created above and multiple lines in the actual Invoice can be summarized into 1 Line. The amount should be the Total Amount of the actual Invoice.

Upon completely keying in the Invoice (Customer), the Invoice should be Completed and Posted. The account posting that occur should be as follows:

DR Debtors (Invoice Amount) 
  CR Debtors Clearing (Invoice Amount) 

Check Debtors Clearing account balance

Upon completely creating, completing and posting all Invoices (Customer), the Debtors Clearing Account should have a 0 balance.

Create Invoice (Vendor) for individual Invoices that make up the TB Creditors Amount

The procedure is the same as for Invoice (Customer) above. The account posting should be as follows:

 DR Creditor Clearing (Invoice Amount) 
   CR Creditor (Invoice Amount) 

Check Creditors Clearing account balance

Create Payment for individual Unpresented cheque that make up the TB Bank In Transfer Amount

Each unpresented cheque should be created with 1 payment in the System. The Business Partner selected should be the actual Business Partner of the individual payment. The Accounting Date is the Opening Date and the Transaction Date should be the actual Payment Date. The amount should be the Total Amount of the actual Cheque Payment.

Upon completely keying in the Payment, the Payment should be Completed and Posted. The account posting that occur should be as follows:

 DR Bank Clearing (Payment Amount) 
   CR Bank In Transfer (Payment Amount) 

Check Bank Clearing account

The bank clearing account should now have a balance of zero. If not, please review your previous steps.

Create new Physical Inventory record.

Create new Physical Inventory and key-in individual inventory quantity balance of Closing Stock as per closing stock count. The type of Physical Inventory selected should be Inventory Adjustment. Be very careful on the Warehouse selected for each record.

Complete and Post Physical Inventory record

Upon completely keying-in the Physical Inventory, Complete and Post the Physical Inventory. The account posting should be as follows:

 DR Inventory (Standard Cost) 
   CR Inventory Clearing (Standard Cost) 

Check Inventory Clearing balance

Upon completion of all Physical Inventory postings, the Inventory Clearing balance in the System should be 0.

Revert Default Accounts

Revert the Default Accounts for Inventory Adjustment for each Warehouse to the original Default Account.

Deactivate Opening Product

Select the Active checkbox for Opening Product in the Product Masterdata setup to No.

Generate Trial Balance from the System

Generate the Trial Balance as at the Opening Date and compare against the Closing Trial Balance obtained earlier.

Deactivate Debtor Clearing, Creditor Clearing, Bank Clearing and Inventory Clearing

Uncheck the Active checkbox for the above in the Account Element setup.

Summary Outcome

You should now have your opening balances established in Adempiere.