Hyper Open Edge Cloud

How To Understand And Use Business Template

How To showing how to group related objects together similar to folders.
  • Last Update:2016-02-26
  • Version:001
  • Language:en

Business templates are a handy way of transferring results of your work between erp5 instances, and also of distributing them publicly. You can use them also for version control - since the bt5 format is (almost) human-readable, you can store daily builds of your bt5 in an svn and track differences.

Table of Contents

What's a business template

Business template is a collection of ERP5/Zope objects (ZPT templates, Formulator forms, portal types, Python scripts etc) serialized into a human-readable format. By installing a business template you make your ERP5 recreate these object in your ZODB. Usually, a business template (which we'll call a bt5) forms a complete application or a working part of an application.

bt5's are a very convenient way to exchange and distribute applications or certain functional 'modules' build within the ERP5 framework.

Composition of a business template

A business template is made of ZODB objects of all possible types. The logic is that it should form a complete functional unit - either a complete application, or a set of objects that together serve a particular purpose. For example, an erp5_crm business template contains forms, templates, portal_types, modules, base categories and workflows which put together allow you to register phone calls and emails and follow sale opportunities and support requests. Another template may contain only a general accounting plan (GAP) for a country, or a message catalog for user interface translation.

Most of what you do in erp5 is creating forms, scripts and templates - it is advisable to create a separate skin folder for what you do, to keep things in order and to ease creation of a business template.

Putting a template together

Go to /portal_templates, create a new template. Give it an id that reflects the scope of what the template is supposed to bring. Optionally, you can add version information, change log etc.

Now, type in ids of objects you want to export - skin folders, modules, workflows, base categories. If you need to add specific objects (contained in a module), add them to the 'paths' box.

If you added some portal_types or altered exising ones, go to the second tab and type them into the top box. Then, from the 'Action' box, select 'Get portal type properties' - all the remaining boxes will be filled automatically.

Each component will be detailed below.

Build and export

To build a template, select 'Build business template' from the 'Action' box. Once done, click the 'Import/Export' button. You will be given two options - if you choose 'save', the template will be saved locally on your server as a directory; if you chose 'export', it will be shipped straight to you as a .bt5 file, which is the same but tar-gzipped. The directory/file name will be composed of the template's id and its version numer.

Content of a Business Template

TODO

General

Most of fields in the General tab are obvious, but the following may require an extra explanation:

  • Title
  • This is the name of the business template. It will be used when exporting the business template. Business template system will compare business title to know if a business template is installed or not.

  • Revision Number
  • This is an automatic build id that can be used in addition to version to know which installed business template is the most recent.

  • Dependencies
  • Dependencies are checked when installing business template from repositories.

  • Provision
  • Dependencies can be expressed using the title of a business template title or a 'meta business template'. For instance, both erp5_html_style and erp5_xhtml_style provides erp5_view_style.

  • Modules
  • This is used to create the module if it's not present and to update security settings on a module.

  • Categories
  • This will actually create Base Categories. No categories content will be exported; export them as Path if you want them.

  • Skin Folders
  • This is skin folders for portal_skins. Skin folders will be installed in all skins selections (unless explicitly listed in 'Registered Skin Selection' described below). To control the ordering of skins folders, you'll have to set a float property named 'business_template_skin_layer_priority' on the skin folder using 'Properties' tab from the ZMI. When adding a new skin folder, the list of skin folders will be sorted using this property (which defaults to 0). This is useful if you want to make sure that your skin folder will have priority over "standards" skins folders

  • Registered Skin Selection
  • This is the list of skin selections in which a skin folder will be included. It has the form

     skin_folder_name | SkinSelection1
     skin_folder_name | SkinSelection2
    

    If not defined explicitly, the skin folder is added to all skin selections. If it uses a skin selection that does not exist when installing the business template, this skin selection will be added to portal_skins. The new skin selection will be initialized with all skin folders, except skin folders taht are explicitly listed as Registered Skin Selection in other business templates.

  • Workflows
  • Workflows from portal workflow are added using this fields, workflow chains are not installed. They are configured from the portal type tab. When a workflow is removed, workflow chains are removed, to keep consistency inside the workflow tool.

  • Path
  • This is the list of path to export. By default, it supports glob style expansion. If you want all objects recursivly, you have to use ** :

      account_module/sale*
      portal_categories/my_category
      portal_categories/my_category/**
    

    Example uses:

        portal_categories/my_category/another_category
    

    Exports another_category document in the path of portal_category/my_category (but thoses path elements are not exported).

        portal_categories/my_category/another_category/*
    

    Exports all subdocuments in another_category, but not another_category itself, and not subdocuments's subdocuments (we only export the first level).

        portal_categories/my_category/another_category
        portal_categories/my_category/another_category/**
    

    Exports another_category and all subdocuments inside, recursivly.

        portal_categories/my_category/**
    

    Exports everything inside my_category recursivly. my_category is a base category, so it should be not exported as a path, but rather as Categories (see below).

    Note that workflow history is not exported, this means that the current states of objects on workflow will be lost, and the objects will be in the initial states. Also note that manage_afterClone will be called on created documents, so if the portal type define a type based method ${portal_type}_afterClone, this method will be called on the new object. This manage_afterClone call is done for obscure technical reasons, and this situation may evolve.

Portal Types

Portal types and their configuration are defined separately. In the Portal Types view of the business template UI, you have the following fields:

  • Portal Types
  • This is to add the portal type itself. Only the group, factory method, meta type, init script, description and icon will be exported.

  • Workflow Chains
  • This way, you can specify which workflows are associated to a portal type:

        Person | improved_person_validation_workflow
    

    You can remove workflow chains by preceding the workflow name by a - sign (this feature is currently only available for workflow chains):

        Person | -validation_workflow
    

    Note that, in the above example, neither portal_types nor workflow have to be included in the business template, but if they are not present when the business template will be installed, installation will fail.

  • Allowed Content Types
  • You specify which portal types can be added in another portal type.

        Person Module | Person
    

    Note that, in the above example, neither Person nor Person Module have to be included in the business template. Of course, you must make sure both portal types will exist when the business template will be installed.

  • Hidden Content Types
  • Hidden content types is an ERP5TypeInformation extension to hide some allowed content types from the add menu. The syntax is:

        Person | Telephone
    

    This will make Telephone portal type hidden from Person add menu, but Telephone will still be allowed as content of Person.

  • Property Sheets
  • Property Sheets that are defined on the type information.

        Person | Account
    

    The above will associate the Account property sheet to the Person type information. Account property sheet can be located on the file system in any product or in the 'Local repository' from $INSTANCE_HOME/PropertySheet; in that case, you may want to add the property sheet in the business template as well.

  • Base Categories
  • Base Categories that are defined on the type information. See HowToConfigureRelationField for a quick overview of base categories.

        Person | source_decision
    

    In this example, we associate source_decision category to the Person portal type.

  • Actions
  • Describes all actions that are defined by this business template, using the format:

        Person | improved_view
    

    This, way the business template will include an action with id improved_view. When installing the business template, the action will be installed on the portal type, Person in the example. A note for actions ordering: CMF uses current actions ordering to display actions, as actions on a portal type can be added by multiple business templates, the orderring needs to be included in the action, hence the priority property on actions. When installing a business template, when a new action is added to a portal type, all actions are sorted by their priority property.

Catalog Methods

  • Catalog Methods
  • Put here ZSQL Methods, line by line, example:

        erp5_mysql/methodname
    
  • Catalog Result Tables
  • Put here tables, which shall be added to sql_search_tables, example:

        mytable
    

    TODO

Details

  • Zope Roles
  • Roles to add on the portal; erp5_core contains the 5 defaults roles.

  • Site Properties
  • Properties to add on the portal. Only include here the property id, and it will be exported.

  • Document Classes
  • Classes to export, must be in $INSTANCE_HOME/Documents/ . Files will are exported as is.

  • Property Sheets
  • Property Sheets to export, must be in $INSTANCE_HOME/PropertySheet/

  • Extensions
  • Extensions to export, must be in $INSTANCE_HOME/Extensions/ .

  • Update Tools
  • Recreate tools ? XXX read the code

  • Update Business Template Workflow
  • Check if business template workflows in bootstrap folder have changed, and reimport them if necessary.

  • Zope Products
  • Unsupported

  • Unit Test Classes
  • Local tests to export, must be in $INSTANCE_HOME/tests/ .

  • Message Translations
  • Specify the language and message catalogs to export. With this example, you export erp5_content and erp5_ui for language with code wo:

    wo | erp5_content
    wo | erp5_ui
    
  • Constraints Classes
  • Local Constraints to export, must be in $INSTANCE_HOME/Constraints/ .

  • Portal Type Roles
  • Include portal type names here, then all roles for those portal types will be exported.

  • Local Roles
  • To export local roles defined on a module, specify the id of the module in that field, when exporting the business template, all local roles defined on the module are exported as is. When installing the business template, this module local roles will be erased and set to what is defined in the business template.

Related Articles