Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

...

  1. Create entity definitions for the external database like you would for an OFBiz entity (except use the no-auto-stamp="true" attribute).
  2. Assign the entities to a different group (in entitygroup.xml), "advertpro" for example.
  3. Assign the "mysql-advertpro" datasource the the default delegator: <group-map group-name="myExternalDB" datasource-name="myExternalDB"/>
  4. Use the delegator to access the external database.

Anchor
RMI-Error-on-clientRMI-Error-on-client

RMI error on client side

Add the $OFBIZ/framework/base/config dir to the jar as a <resource> in your build file (Maven's pom.xml example, to be adapted for ant)

Code Block

<resources>
      <resource>
        <directory>../../../framework/base/config</directory>
      </resource>
      <resource>
        <directory>../../../framework/base/dtd</directory>
      </resource>
      <resource>
        <directory>../../../framework/datafile/dtd</directory>
      </resource>
      <resource>
        <directory>../../../framework/entity/dtd</directory>
      </resource>
      <resource>
        <directory>../../../framework/entityext/dtd</directory>
      </resource>
      <resource>
        <directory>../../../framework/minilang/dtd</directory>
      </resource>
      <resource>
        <directory>../../../framework/security/dtd</directory>
      </resource>
      <resource>
        <directory>../../../framework/service/dtd</directory>
      </resource>
      <resource>
        <directory>../../../framework/widget/dtd</directory>
      </resource>
      <resource>
        <directory>../../../framework/workflow/dtd</directory>
      </resource>
      <resource>
        <directory>../../../framework/applications/content/dtd</directory>
      </resource>
    </resources>

A Ryan's (from Sourcelab) tip

...

SendingMailsToContactLists
SendingMailsToContactLists

Sending mails to contact lists

In the marketing application, click on contact list, then find your list, then click on Comm Events and then Create New Contact List. Comm Event should land you here:
https://demo.ofbiz.org/marketing/control/EditContactListCommEvent?contactListId=9000&DONE_PAGE=/marketing/control/ListContactList based on the trunk demo server.

Set your from details and party roles (maybe N/A), fill your subject and content and click save.

When you're happy with it, change the status to "In-Progress" and click save again. The comm events should then start to trigger and the email flow, although you'll want to test it on a small list to start with. If the list is clean and processes through OK the status should automatically change to "Complete" when it is done but if there are badly formatted email addresses that can stick the status and you will need to manually mark as complete and you might review the logs to find the error.

At the time of this tip was wrote, the start and finish dates do not work as expected, leave them blank for your first testing.

A Ray Barlow's tip

Anchor
ImportCustomisedData
ImportCustomisedData

How to save customised data for import as demo data

Add a entity-resource entry of type "data" and reader-name as "ext" in ofbiz-components.xml of your application. For example:

Code Block

<entity-resource type="data" reader-name="ext" loader="main" location="data/GeoData_IN.xml"/>

And run the

Code Block

"run-install-extseed"

ant target instead of

Code Block

"run-install"

This should load your modified data along with the seed data and without any demo data.

Anchor
appserver
appserver

How to run inside a non embedded application server

Have a look at framework/appserver/README file. You might be also interested by Run OFBiz under outside Application Servers (WASCE 2.0.0.1, Geronimo 2.0.3, Tomcat 5.5 and 6, JBoss 4.2.2)

Anchor
createAcctgTransAndEntries
createAcctgTransAndEntries

Issue with createAcctgTransAndEntries service

If you see errors like

Error:Error trying to begin transaction, could not process method: The
current transaction is marked for rollback, not beginning a new
transaction
and aborting current operation; the rollbackOnly was caused by: Service
createAcctgTransAndEntries threw an unexpected
exception/errororg.ofbiz.service.ServiceValidationException: The following
required parameter is missing: OUT
createAcctgTransAndEntries.acctgTransId (The following required
parameter
is missing: OUT createAcctgTransAndEntries.acctgTransId) calling
service
balanceInventoryItems in receiveInventoryProduct

If you are not using the Accounting module much and specifically the GL section, than go to accounting ~> ofbiz-component.xml and comment the entry for secas_ledger.xml in that file, restart the server and try again. This should solve your problem.

A Mridul Pathak's tip

Anchor
BestPracticeModifyOrCreate
BestPracticeModifyOrCreate

What is the best practice to modify an existing component or create a new one?

From an old thread by Chris Howe and David Jones. Note that it's now easier to use the create-component ant target (just try "ant -p" to know more)

Chris Howe: Lets say that I want to create an application that most closely matches the ecommerce app. I should start with copied versions the following files only.

Code Block

ofbizhome/speciapurpose/myapp/build.xml
ofbizhome/speciapurpose/myapp/ofbiz-component.xml
ofbizhome/speciapurpose/myapp/webapp/myapp/WEB-INF/controller.xml
ofbizhome/speciapurpose/myapp/webapp/myapp/WEB-INF/web.xml
ofbizhome/speciapurpose/myapp/webapp/myapp/index.jsp

from this I should edit the following
+build.xml:+find "ecommerce"
replace with "myapp"

+ofbiz-component.xml:+find "ecommerce"
replace with "myapp"

+web.xml:+change display name and description from "ecommerce"
to "myapp"

Then change speciapurpose/component-load.xml to load
"myapp"

This should give you an exact duplication of functionality of the copied ecommerce application without the hundreds of thousands of lines of code. Then by simply copying/creating the files that need to be changed and changing the requests and views in controller.xml you will have your new application, but still benefit from svn updates. What is the potential downside of this?

David Jones: Yes, this is the best practice... Being able to do this is part of the design and intention of the screen widget. BTW, the hot-deploy directory may be easier to use than the speciapurpose directory, but of course you can mount a component from anywhere (the following paragraph explains with more details)

Anchor
BestPracticeCustomWebApp
BestPracticeCustomWebApp

What is considered the best practice in creating a custom web application with OFBIZ?

A David Jones's tipOne approach is to simply copy an entire component into a new directory and start hacking away at it until it fit your needs. This is a fine practice if you never have plans of bringing it up to date with a current revision or version. OFBIZ is currently making about 40 commits a week. By the time you complete your customizations, you are out of date.

Another approach is to make a different web app. This is where you copy the five essential files from a similar application that is being maintained by the project, make minor modifications to them.

Which one is right? It depends on on how much changes you are making. Modifying the following files will allow you to "customize" an application, whereas starting from scratch using an existing application as a template is better for a "custom application."

The Five Files

  • application\...\webapp\...\WEB-INF\controller.xml
    • <web-app>
      • change the <display-name>
      • change the <description>
  • application\...\webapp\...\index.jsp
    • change nothing
  • applicaton\build.xml
    • <project>
      • change the name
    • <target name="init">
      • change value of property "desc"
      • change value of property "name"
    • <target name="classpath">
      • ensure all fileset dir are correctly relative to the location of your app
  • application\ofbiz-component.xml
    • <ofbiz-component>
      • change the name
    • <webapp>
      • change the name
      • change the title
      • change the location
      • change the mount point

Now if you were to start OFBIZ and point your browser to mydomain.com/myapp you would see an exact duplicate of the application that you were modeling.

...

From there you need to understand how a page is rendered. It is more detailed than this, but this explanation will suffice for the majority of simple customizations.

  1. Client makes a request
  2. request (among other things) calls a view (controller.xml)
  3. view calls a screen (controller.xml)
  4. screen (Screens.xml) calls some actions and widgets (.bsh, *Forms.xml, *.ftl, etc)
  5. the page is rendered to the client.

The goal with the differences app is to create all of the customizations that you need without touching original OFBIZ code. That way when you update to more current versions, you're less likely to encounter significant conflicts. It makes your application close to being "turn-key".

The Decorator

Most likely the first thing your're going to want to customize is the decoration (the header, which screens are in the leftbar if you want to display a right bar, how the body is displayed, which UILabels you use, etc). For this you need to do two things. (As of revision 5539 you can only do this if your views are using the ecommerce application, it shouldn't be long before all of the applications support this)

  • Change the location of the mainDecoratorLocation in web.xml
    Code Block
    
    <context-param>
        <param-name>mainDecoratorLocation</param-name>
        <param-value>component://ecommerce/widget/CommonScreens.xml</param-value>
        <description>The location of the main-decorator screen to use for this webapp; referred to as a context variable in screen def XML files.</description>
    </context-param>
    
  • Create a screen with name="main-decorator" in the file you specified in the mainDecoratorLocation property (I imagine you'll want to copy an existing decorator screen and modify it rather than start from scratch)

Now your application is an exact copy of the model application with your customized decoration. The reason it's an exact copy is because you have essentially the same controller.xml files in both applications. All of the requests call the same views, which call the same screens, which in turn call the same actions and widgets. So now you want to make some more changes.

Customize Screens

  • controller.xml
    • <view-map>
      • change the name if necessary
      • change the location to a *Screens.xml file inside custom application
  • Screens.xml
    • create a new screen
    • remember they can call .bsh, .ftl, and forms from other applications
    • if you want to use a custom .ftl or .bsh be sure to us a similar directory structure as the original file so you can make easy comparisons when you update.

...

That's really all there is to it. If you call new services from the requests, make sure you create your file in component://myapp/servicedef/services.xml and make sure it gets loaded in the ofbiz-component.xml file. Same with ECAs. Need new classes, create them in your src directory and don't forget to build them with ant. Keep in mind two things and maintanence of your custom application will be easier and less error prone.

  1. REUSE REUSE REUSE. (If you don't change it, you don't have to maintain it, so don't change things just to change them)
  2. Only change copies of the OFBIZ files that are in your custom application

Anchor
ExtendExistingComponent
ExtendExistingComponent

How to Extend an existing component in customized application?

Scenario : For any customized application under hot-deploy if it is needed to extend the existing component then changes in following files are required.

(For instance we are extending the Marketing component.)
1) Inside webapp of your customize application create a folder for component name. (marketing/WEB-INF)
2) Add controller.xml, web.xml
3) In controller.xml file include the <include location="component://marketing/webapp/marketing/WEB-INF/controller.xml"/>
4) In ofbiz-component.xml (hot-deploy/customize_project/)
add following code :
<webapp name="marketing" title="Marketing-Customized" server="default-server" location="webapp/marketing" base-permission="OFBTOOLS,MARKETING" mount-point="/marketing"/>
(extending marketing component here.) Now here the basic setup for extend the component is completed, now you can add component specific request and view in controller.xml here. And create screens in the extanded componint. Note : Please add if some of the information is missing here.

Anchor
HowToSetSSL
HowToSetSSL

Configuring SSL

There are two main techniques in configuring SSL, through Apache (recommended), and through the JVM directly.

Apache

Configuring SSL through Apache is probably the preferred method, and is well documented.

JVM

It's also possible to have the SSL certificate in your JVM environment. The certificate is usually found in the $JAVA_HOME/jre/lib/security directory.

The default file that ships with OFBiz is called cacerts.

You will need to use the Java keytool utility to add certificates from other SSL sites (e.g. www.mywebsite.com) . Here is a pretty good tutorial on getting your SSL certificate setup

The basic steps are described here

Getting an SSL Certificate

Here are some Certificate vendors (this list is from 2005)

  • Verisign
  • Thawte - Thawte Certificate ~ $350 / 2 yrs
  • Comodo
  • GeoTrust
  • FreeSSL - Professional (Not actually Free by the way)
  • CACert.org

...

Budget Plans

...

  • FreeSSL - StarterSSL ~ 39 per year
  • Comodo - InstantSSL (Second Tier requiring multiple Certs be installed)

...

Free

...

Anchor
RMI-Error-on-client
RMI-Error-on-client

RMI error on client side

Add the $OFBIZ/framework/base/config dir to the jar as a <resource> in your build file (Maven's pom.xml example, to be adapted for ant)

Code Block

<resources>
      <resource>
        <directory>../../../framework/base/config</directory>
      </resource>
      <resource>
        <directory>../../../framework/base/dtd</directory>
      </resource>
      <resource>
        <directory>../../../framework/datafile/dtd</directory>
      </resource>
      <resource>
        <directory>../../../framework/entity/dtd</directory>
      </resource>
      <resource>
        <directory>../../../framework/entityext/dtd</directory>
      </resource>
      <resource>
        <directory>../../../framework/minilang/dtd</directory>
      </resource>
      <resource>
        <directory>../../../framework/security/dtd</directory>
      </resource>
      <resource>
        <directory>../../../framework/service/dtd</directory>
      </resource>
      <resource>
        <directory>../../../framework/widget/dtd</directory>
      </resource>
      <resource>
        <directory>../../../framework/workflow/dtd</directory>
      </resource>
      <resource>
        <directory>../../../framework/applications/content/dtd</directory>
      </resource>
    </resources>

A Ryan's (from Sourcelab) tip

Anchor
HowToUseRMIWithoutSSL
HowToUseRMIWithoutSSL

How to use RMI without SSL

By default, since OFBIz is under the Apache Software Fundation Licence, OFBiz comes with RMI using SSL. Before it was possible to use RMI without SSL. But due to licence constraint some code has been removed. If you need, for testing for instance, to use RMI without SSL follow this tip:
In framework/base/config/ofbiz-containers.xml comment out this snippet during tests

Code Block

<property name="client-factory" value="org.ofbiz.service.rmi.socket.ssl.SSLClientSocketFactory"/>
<property name="server-factory" value="org.ofbiz.service.rmi.socket.ssl.SSLServerSocketFactory"/>
<property name="ssl-keystore" value="framework/base/config/ofbizrmi.jks"/>
<property name="ssl-keystore-type" value="JKS"/>
<property name="ssl-keystore-pass" value="changeit"/>
<property name="ssl-keystore-alias" value="rmissl"/>
<property name="ssl-client-auth" value="false"/>

OR

...

Sending mails to contact lists

In the marketing application, click on contact list, then find your list, then click on Comm Events and then Create New Contact List. Comm Event should land you here:
https://demo.ofbiz.org/marketing/control/EditContactListCommEvent?contactListId=9000&DONE_PAGE=/marketing/control/ListContactList based on the trunk demo server.

Set your from details and party roles (maybe N/A), fill your subject and content and click save.

When you're happy with it, change the status to "In-Progress" and click save again. The comm events should then start to trigger and the email flow, although you'll want to test it on a small list to start with. If the list is clean and processes through OK the status should automatically change to "Complete" when it is done but if there are badly formatted email addresses that can stick the status and you will need to manually mark as complete and you might review the logs to find the error.

At the time of this tip was wrote, the start and finish dates do not work as expected, leave them blank for your first testing.

A Ray Barlow's tip

...

How to save customised data for import as demo data

Add a entity-resource entry of type "data" and reader-name as "ext" in ofbiz-components.xml of your application. For example:

Code Block

<entity-resource type="data" reader-name="ext" loader="main" location="data/GeoData_IN.xml"/>

And run the

Code Block

"run-install-extseed"

ant target instead of

Code Block

"run-install"

This should load your modified data along with the seed data and without any demo data.

...

How to run inside a non embedded application server

Have a look at framework/appserver/README file. You might be also interested by Run OFBiz under outside Application Servers (WASCE 2.0.0.1, Geronimo 2.0.3, Tomcat 5.5 and 6, JBoss 4.2.2)

...

Issue with createAcctgTransAndEntries service

If you see errors like

Error:Error trying to begin transaction, could not process method: The
current transaction is marked for rollback, not beginning a new
transaction
and aborting current operation; the rollbackOnly was caused by: Service
createAcctgTransAndEntries threw an unexpected
exception/errororg.ofbiz.service.ServiceValidationException: The following
required parameter is missing: OUT
createAcctgTransAndEntries.acctgTransId (The following required
parameter
is missing: OUT createAcctgTransAndEntries.acctgTransId) calling
service
balanceInventoryItems in receiveInventoryProduct

If you are not using the Accounting module much and specifically the GL section, than go to accounting ~> ofbiz-component.xml and comment the entry for secas_ledger.xml in that file, restart the server and try again. This should solve your problem.

A Mridul Pathak's tip

...

What is the best practice to modify an existing component or create a new one?

From an old thread by Chris Howe and David Jones. Note that it's now easier to use the create-component ant target (just try "ant -p" to know more)

Chris Howe: Lets say that I want to create an application that most closely matches the ecommerce app. I should start with copied versions the following files only.

Code Block

ofbizhome/speciapurpose/myapp/build.xml
ofbizhome/speciapurpose/myapp/ofbiz-component.xml
ofbizhome/speciapurpose/myapp/webapp/myapp/WEB-INF/controller.xml
ofbizhome/speciapurpose/myapp/webapp/myapp/WEB-INF/web.xml
ofbizhome/speciapurpose/myapp/webapp/myapp/index.jsp

from this I should edit the following
+build.xml:+find "ecommerce"
replace with "myapp"

+ofbiz-component.xml:+find "ecommerce"
replace with "myapp"

+web.xml:+change display name and description from "ecommerce"
to "myapp"

Then change speciapurpose/component-load.xml to load
"myapp"

This should give you an exact duplication of functionality of the copied ecommerce application without the hundreds of thousands of lines of code. Then by simply copying/creating the files that need to be changed and changing the requests and views in controller.xml you will have your new application, but still benefit from svn updates. What is the potential downside of this?

David Jones: Yes, this is the best practice... Being able to do this is part of the design and intention of the screen widget. BTW, the hot-deploy directory may be easier to use than the speciapurpose directory, but of course you can mount a component from anywhere (the following paragraph explains with more details)

...

What is considered the best practice in creating a custom web application with OFBIZ?

A David Jones's tipOne approach is to simply copy an entire component into a new directory and start hacking away at it until it fit your needs. This is a fine practice if you never have plans of bringing it up to date with a current revision or version. OFBIZ is currently making about 40 commits a week. By the time you complete your customizations, you are out of date.

Another approach is to make a different web app. This is where you copy the five essential files from a similar application that is being maintained by the project, make minor modifications to them.

Which one is right? It depends on on how much changes you are making. Modifying the following files will allow you to "customize" an application, whereas starting from scratch using an existing application as a template is better for a "custom application."

The Five Files

  • application\...\webapp\...\WEB-INF\controller.xml
    • <web-app>
      • change the <display-name>
      • change the <description>
  • application\...\webapp\...\index.jsp
    • change nothing
  • applicaton\build.xml
    • <project>
      • change the name
    • <target name="init">
      • change value of property "desc"
      • change value of property "name"
    • <target name="classpath">
      • ensure all fileset dir are correctly relative to the location of your app
  • application\ofbiz-component.xml
    • <ofbiz-component>
      • change the name
    • <webapp>
      • change the name
      • change the title
      • change the location
      • change the mount point

Now if you were to start OFBIZ and point your browser to mydomain.com/myapp you would see an exact duplicate of the application that you were modeling.

From there you need to understand how a page is rendered. It is more detailed than this, but this explanation will suffice for the majority of simple customizations.

  1. Client makes a request
  2. request (among other things) calls a view (controller.xml)
  3. view calls a screen (controller.xml)
  4. screen (Screens.xml) calls some actions and widgets (.bsh, *Forms.xml, *.ftl, etc)
  5. the page is rendered to the client.

The goal with the differences app is to create all of the customizations that you need without touching original OFBIZ code. That way when you update to more current versions, you're less likely to encounter significant conflicts. It makes your application close to being "turn-key".

The Decorator

Most likely the first thing your're going to want to customize is the decoration (the header, which screens are in the leftbar if you want to display a right bar, how the body is displayed, which UILabels you use, etc). For this you need to do two things. (As of revision 5539 you can only do this if your views are using the ecommerce application, it shouldn't be long before all of the applications support this)

  • Change the location of the mainDecoratorLocation in web.xml
    Code Block
    
    <context-param>
        <param-name>mainDecoratorLocation</param-name>
        <param-value>component://ecommerce/widget/CommonScreens.xml</param-value>
        <description>The location of the main-decorator screen to use for this webapp; referred to as a context variable in screen def XML files.</description>
    </context-param>
    
  • Create a screen with name="main-decorator" in the file you specified in the mainDecoratorLocation property (I imagine you'll want to copy an existing decorator screen and modify it rather than start from scratch)

Now your application is an exact copy of the model application with your customized decoration. The reason it's an exact copy is because you have essentially the same controller.xml files in both applications. All of the requests call the same views, which call the same screens, which in turn call the same actions and widgets. So now you want to make some more changes.

Customize Screens

  • controller.xml
    • <view-map>
      • change the name if necessary
      • change the location to a *Screens.xml file inside custom application
  • Screens.xml
    • create a new screen
    • remember they can call .bsh, .ftl, and forms from other applications
    • if you want to use a custom .ftl or .bsh be sure to us a similar directory structure as the original file so you can make easy comparisons when you update.

That's really all there is to it. If you call new services from the requests, make sure you create your file in component://myapp/servicedef/services.xml and make sure it gets loaded in the ofbiz-component.xml file. Same with ECAs. Need new classes, create them in your src directory and don't forget to build them with ant. Keep in mind two things and maintanence of your custom application will be easier and less error prone.

  1. REUSE REUSE REUSE. (If you don't change it, you don't have to maintain it, so don't change things just to change them)
  2. Only change copies of the OFBIZ files that are in your custom application

...

How to Extend an existing component in customized application?

Scenario : For any customized application under hot-deploy if it is needed to extend the existing component then changes in following files are required.

(For instance we are extending the Marketing component.)
1) Inside webapp of your customize application create a folder for component name. (marketing/WEB-INF)
2) Add controller.xml, web.xml
3) In controller.xml file include the <include location="component://marketing/webapp/marketing/WEB-INF/controller.xml"/>
4) In ofbiz-component.xml (hot-deploy/customize_project/)
add following code :
<webapp name="marketing" title="Marketing-Customized" server="default-server" location="webapp/marketing" base-permission="OFBTOOLS,MARKETING" mount-point="/marketing"/>
(extending marketing component here.) Now here the basic setup for extend the component is completed, now you can add component specific request and view in controller.xml here. And create screens in the extanded componint. Note : Please add if some of the information is missing here.

...

Configuring SSL

There are two main techniques in configuring SSL, through Apache (recommended), and through the JVM directly.

Apache

Configuring SSL through Apache is probably the preferred method, and is well documented.

JVM

It's also possible to have the SSL certificate in your JVM environment. The certificate is usually found in the $JAVA_HOME/jre/lib/security directory.

The default file that ships with OFBiz is called cacerts.

You will need to use the Java keytool utility to add certificates from other SSL sites (e.g. www.mywebsite.com) . Here is a pretty good tutorial on getting your SSL certificate setup

The basic steps are described here

Getting an SSL Certificate

Here are some Certificate vendors (this list is from 2005)

  • Verisign
  • Thawte - Thawte Certificate ~ $350 / 2 yrs
  • Comodo
  • GeoTrust
  • FreeSSL - Professional (Not actually Free by the way)
  • CACert.org

...

Budget Plans

...

  • FreeSSL - StarterSSL ~ 39 per year
  • Comodo - InstantSSL (Second Tier requiring multiple Certs be installed)

...

Free

...

...

How to use RMI without SSL

By default, since OFBIz is under the Apache Software Fundation Licence, OFBiz comes with RMI using SSL. Before it was possible to use RMI without SSL. But due to licence constraint some code has been removed. If you need, for testing for instance, to use RMI without SSL follow this tip:

  1. In framework/base/config/ofbiz-containers.xml replace (or better comment out this snippet during tests Code Block <!--property )
    <property name="client-factory" value="org.ofbiz.service.rmi.socket.ssl.SSLClientSocketFactory"/>
    <property name="server-factory" value="org.ofbiz.service.rmi.socket.ssl.SSLServerSocketFactory"/>
    by
    Code Block
    ssl.SSLServerSocketFactory"/>
    <property name="ssl-keystore" value="framework/base/config/ofbizrmi.jks"/>
    <property name="ssl-keystore-type" value="JKS"/>
    <property name="sslclient-keystore-passfactory" value="changeitorg.ofbiz.service.rmi.socket.zip.CompressionClientSocketFactory"/>
    <property name="sslserver-keystore-aliasfactory" value="rmisslorg.ofbiz.service.rmi.socket.zip.CompressionServerSocketFactory"/>
    <property name="ssl-client-auth" value="false"/-->
    
  2. Unzip in framework\service\src\org\ofbiz\service\rmi\socket\zip the content of this attachment

Anchor
HowToTestIfRMIIsWorking
HowToTestIfRMIIsWorking

...

Simply run the testRmi service from Webtools (not sure this is sufficient...)
OR
Unzip somewhere on you disk this attachment. From there I guess it's pretty simple.

Anchor
SomethingsYouShouldKnowAboutRMI
SomethingsYouShouldKnowAboutRMI

...