Page History

This is the most common requirement, where you have to customize implementation of framework in some areas you are using. In some cases we need to implement something or extend something in an existing(OOTB) OFBiz component which is very specific to a client and not generalized enough to put back in OFBiz trunk. So to achieve this we usually follow following strategies for testing(staging) and production systems:

Maintaining Patches

...

...

Applying a Patch

1. Applying a patch is again a thing can be done from eclipse or from console.
2. Always If you are not sure about it, always apply a patch from OFBiz root directory.
3. In eclipse Eclipse click on OFBiz root directory and got to Team --> Apply Patch, just browse the path to patch file and follow the instructions.
4. If the changes are in the patch are already there in files being patched then it will show you conflicts in the file which should be resolved before applying the patch.

5. For applying a patch from console use following command from OFBiz root directory:

   Code Block
   patch -p0 < [patch file path]

6. While applying the patch if there is a conflict then system will prompt you to either postpond postpone or continue patching, follow the instructions.
7. Once the patch is applied you don't need to apply it again until you replace the patched file from source repository or there are conflicts. In case of conflicts you need to update the patch file and apply it again.

Extending an Existing webapp Only

If you only need to change a few things such then follow the instructions How to Extend an existing component in customized application 

Extending an Existing Component

 If a large set of code needs to be added or changed in a a specific component in an existing OFBiz OOTB component where you will need to add more new entities, services, screens, forms etc. then this strategy should can be adopted and complete component should can be overridden in hot-deploy directory, by creating a new component.

Following steps need to be performed for overriding an existing component:

1. Create custom component in hot-deploy directory by any name as you want to override, its just going be replica of existing OOTB OFBiz component structure with all the major directories and files required for setting up a component.
2. You can use ant create-component createComponent target on OFBiz root directory to create this component in hot-deploy directory.
3. Only those files need to be added which you need to have in overriding the component, webapp. Rest of the resources are going to be used from OOTB component so if you have used ant create-component gradlew createComponent target then you can safely delete some of the files like e.g. if you are not going to write a service then services.xml file can be deleted, or if you are not going to add or extend an existing entity then you can delete entitymodel.xml file and their entries from ofbiz-component.xml file of custom component.
4. Basically this is the thin line between extending a webapp and a component. If you are going to have major changes in services and entities then creating a new component should be preferred where you will be extending the existing webapp.
5. e.g. If you want to have a separate component for adding or extending existing functionalities from catalog application which is a webapp in product component then you can have component in hot-deploy dir by extending the catalog webapp from product component.
6. Follow these steps:

   1. Make sure to properly override the webapp in ofbiz-component file of custom component as example given below:

      Code Block
      <webapp name="catalog" title="Catalog" server="default-server" location="webapp/catalog" base-permission="OFBTOOLS,CATALOG" mount-point="/catalog" app-bar-display="true"/>

   2. Make sure to make entries of custom service defs(if-any), entity defs(if-any) and data files(if-any) in ofbiz-component file of custom component as example given below:

      Code Block
      <entity-resource type="model" reader-name="main" loader="main" location="entitydef/entitymodel.xml"/> <entity-resource type="data" reader-name="seed" loader="main" location="data/*TypeData.xml"/> <service-resource type="model" loader="main" location="servicedef/services.xml"/>

   3. Make sure to have same web.xml file from existing webapp.
   4. You can have new main-decorator defined for screens in webapp so if this is the case this needs to be changed in web.xml.

   5. Make sure to have controller.xml file in new webapp created and include the the controller from existing webapp and only include custom requests only rest will be taken care by included controller only, as shown bellow:

      Code Block
      <include location="component://product/webapp/catalog/WEB-INF/controller.xml"/>

   6. Make sure to have error.jsp inside extended webapp.
   7. Make sure to have index.jsp file with redirect path.

Patch Management Using Ant Targets

There are 4 targets, to create/apply/reapply/revert patches for the framework, applications and specialpurpose: they are available in the ant script for auto generated hot-deploy components (see in framework/resources/templates/build.xml)

1. create-ofbiz-patches
2. revert-ofbiz-patches
3. apply-ofbiz-patches
4. reapply-ofbiz-patches

Use "ant -p" in one of your components created with create-component to know more about them...

There are also 4 deployment targets available in the main build.xml.

The reason is to allow to patch different staging areas where URLs and other parameters vary.

1. build-dev
2. build-test
3. build-qa
4. build-production

...

1. 1. .

...

1. A "dev" environment/area (most of the time on developers own machines) where the development is done, maybe using Derby DB for instance. Anyway an area where all production constraints are not yet taken into account.
2. A "test" area, something like the "dev" area but with a different environment (clustered, not the same DB, etc.) something not yet similar to production but near. Because most of the time you don't have yet a production area ready when you begin to test. This area remains in the hand of developpers. Load tests for instance can be done there.
3. A "QA" area, this comes later and is a duplicate of the production area where all tests are finally done. It's in the hand of QA engineers who qualify/guarantee the development to be production ready.
4. A "production" area, this is the latest stage available when the development is production ready (though it might appears before QA sometimes when the shareholders are in a hurry...). It's in the hand of sysops (or devops if you prefer).

The purpose of those targets is to adapt the source to the areas. When used they calls the main build targets, but the build target does not depend on them, so can still be used w/o them. They complete the "create|apply|reapply|revert-ofbiz-patches" targets which target only the "dev" area or can be used in an early stage of the development.

How they work: depending on the target area, they simply scan all patches in all hot-deploy components (for instance in /hot-deploy/component-name/patches/test) and apply them. The "prepare-to-build-qa|production" targets have something specific. When you maintain URLs and misc. parameters variations inside properties files, it's often easier to directly maintain those files and copy them over in those areas than maintaining/updating patches for them which can be a repetitive and tedious task, those targets do it for you.

Now about the 1st build-dev target: sometimes you don't even create any hot-deploy components (eg. some projects might use OFBiz as a web services API with few modifications in OFBiz core), or you need to put patches somewhere before creating a hot-deploy-component, or your patches are common to all deployment areas and it does not make sense to maintain duplicates. Then to keep your OFBiz working copy free from modifications (which could else been put in one of your hot-deploy components patches directory, which is anyway not very logical but pragmatic),  you put your paches in the runtime/patches folder where "core" patches (those which change OFBiz as it's OOTB) are supposed to be. The "build-dev" target, purposely independent of other targets, is called by the main build target, exactly before anything else. The idea for the build-dev target is to keep patches with features separated (ie grouping different files changed for a feature in a patch), but you can, or may have to, do it on a file level, notably when 2 or more features impact the same file...

Then later, if you need to differentiate these files on different areas (URLs, ports in entityengine.xml comes to mind) you can move/duplicate them under the patches/test|qa|production directories of a hot-deploy component of your choice.

Extending an Existing webapp Only

If there not a large but changes in controller, groovy files and small extension to the screens and forms are there then this strategy can be adopted.
Following steps need to be performed for overriding an existing webapp:

Follow these steps:

...

Make sure to properly override the webapp in ofbiz-component.xml file of custom component with the webapp that you already have as example given below:

<webapp name="catalog"
    title="Catalog"
    server="default-server"
    location="webapp/catalog"
    base-permission="OFBTOOLS,CATALOG"
    mount-point="/catalog"
    app-bar-display="true"/>

...

Make sure to have controller.xml file in new webapp created and include the the controller from existing webapp and only include custom requests only rest will be taken care by included controller only, as shown bellow:

<include location="component://product/webapp/catalog/WEB-INF/controller.xml"/>

...