Document Properties
Kbid24Y887
Last Modified04-Feb-2020
Added to KB11-Jul-2013
Public AccessEveryone
StatusOnline
Doc TypeGuidelines, Concepts & Cookbooks
Product
  • ICM 7.6
  • ICM 7.7
  • ICM 7.8
  • ICM 7.9
  • ICM 7.10

Guide - Pipeline Style Guide

1 Introduction

This section contains a quick overview of conventions and rules that are outlined and discussed in more detail in the remaining sections of this document. Use this checklist whenever developing or reworking pipelines.

Things you should do:

  • Make sure your pipeline name fits the pipeline-naming scheme.
  • Make sure you assigned the pipeline to a meaningful pipeline group.
  • Make sure you assigned the pipeline to the correct pipeline type (view, process).
  • Make sure your pipeline is secure.
  • Make sure you documented the I/O parameters of the pipeline (on the start node).
  • Make sure you set the 'NULL' alias for unused pipelet input and output parameters.
  • Make sure you are using the common user interaction patterns.
  • Make sure you used the pipeline transaction handling.
  • Make sure your pipeline is readable. Divide pipelines into smaller sub-pipelines if they become too complex.

Things you should not do:

  • Avoid using common names for dictionary aliases in processing pipelines.
  • Never transform strings into object representations. Use formatter utility pipelets instead.
  • Do not use non-ASCII characters in the source code.

2 Pipeline Security

2.1 General

The following general rules apply:

  • All start nodes that are not to be called from external users have to be marked as private. This includes start nodes of scheduled jobs and start nodes called during dbinit.
  • Start nodes marked as public have to be secured depending on the context in which they are used:
    • If they are accessible for anonymous users, no further checks are required.
    • Make appropriate entries in the pipeline-acl.properties file (see Pipeline Access Control Lists below).
    • For buying organization front end and supplier front end, call the CheckApplicationContext pipeline first.

2.2 Pipeline Access Control Lists

Pipeline access control lists provide in conjunction with the prefix-pipeline a way to define for each pipeline which permissions a user needs to execute this pipeline.
The general syntax of entries in the pipeline-acl.properties file looks like this:

<PipelineName>[-<StartNodeName>]=[<Context>:<PermissionID>][;<Context>:<PermissionID>]

Here are some examples:

// An empty list – no permission required
ViewCatalog-Dispatch=
// More than on entry – all permissions required
ViewCatalog-Edit=Organization:VIEW_CATALOG;Catalog:MANAGE_CATALOG
// No start node given – those entries are used for all start nodes
// that are not explicitly defined
ViewCatalog=Organization:VIEW_CATALOG
// Valid Contexts are defined by the application,
// e.g. the Organization and Channel are provided
ViewHelp=

3 Process Pipelines

3.1 Separating View and Process Pipelines

Usually viewing pipelines model the page flow of an application whereas process pipelines provide access to the Java business logic at pipeline level. This separation ensures that:

  • The page flow can be changed on project base without re-implementing the business logic.
  • Pipelines for business logic can be reused and view pipelines can be kept simple.

The following rules help to ensure high quality standards for process pipelines:

  • Move pipeline logic (pipelets) from view- to process pipelines.
  • View pipelines should not contain pipelets. They should only contain calls to generic process pipelines.
  • Process pipelines should not use webforms.
  • Avoid process pipelines with dynamic call nodes. Often dynamic call nodes are used to create customizable process pipelines. However, it is very hard for an "outsider" to figure out what such a pipeline does. Therefore, they should be
    avoided.
  • If possible locate process pipelines in business components, remove them from the back office application cartridge and from channel plugins.
  • Avoid nested process pipelines. Try to move the call nodes into the view pipeline.
    This is an example of a well-defined process pipeline:

3.2 Input Parameters

In regards to input parameters to process pipelines mind the following notes:

  • parameter naming
    Objects that are expected as input by a process pipeline should not have a name starting with the prefix "Current...".
    If "Current" is part of the dictionary key, it can cause overlappings with other objects in the dictionary. Using the Keymapper-Pipelet is not an option since it adds to the complexity of the pipeline.
    If a process pipeline expects a UUID, the dictionary key must be named "UUID". There is one exception to this rule: the domainID must be named "DomainID" although it is actually a UUID.
  • object vs. object reference
    Decide very carefully if it is necessary to pass the whole object or its ID (i.e. its UUID) to a process pipeline (and vice versa).
    In some cases (i.e. removing an object) it is sufficient to pass only an ID to the process pipeline.
    Whenever an object needs to be updated it should be passed to the process pipeline together with the data. This provides more flexibility in customer projects, prevents redundant code, extended runtime of the pipeline, and decreases the complexity of the pipelines.
    In some cases pipelines are required that can handle the whole object as well as the object's semantic or internal ID. In these cases the pipeline needs to have two separate start nodes. Do not use a single start node for both cases since this would require additional pipeline logic afterwards to tell the different cases apart.
  • convert form parameter into integer, boolean, etc.
    In many cases it is necessary to instantiate form parameters (Strings) into their real representation (Integer, Boolean, Date, Double).
    It is okay to put the Integer, Boolean, Date or Double object into the pipeline dictionary under the same name as the form parameter. This reduces the number of keys in the pipeline dictionary.
    However, use a different key for Integer, Boolean, Date or Double if the form parameter should be displayed again and no webform can be used (i.e. in an error case).

3.3 Process Pipelines in Business Components vs. in Application Cartridges

Process pipelines must be generic enough to be located in a business component.
There might be cases where a certain application requires a certain implementation of a process pipeline. For example, a process pipeline to validate the user input is specific in a way that it can only be used in a sellside back office application. As an exception such process pipelines can be located in the back office application cartridge ( sld_enterprise_app or sld_ch_base).
Pipelines that manipulate real business objects should be analyzed very carefully to decompose it into more generic process pipelines if possible. By decomposing the pipelines and building a stable pipeline API the process pipelines become more reusable resulting in reduced development effort.
Templates should not be located in a business component cartridge. Exception: Templates used by the XML export to generate the XML data or templates to convert import data from a proprietary format into Intershop 7 XML. Such templates may be located in business component cartridges.

3.4 Migration of Process Pipelines

The business logic of existing process pipelines should not be changed to ease migration.
If parts of a process pipeline need modification, do not create a new process pipeline. Instead create a new start node in the same pipeline and copy the pipeline logic. Mark the "outdated" start node deprecated and name the new start node to be used in the future.

4 Pipeline Naming Guidelines

4.1 Presentation Pipelines

This section provides recommendations regarding the naming of presentation pipelines. All presentation pipelines should start with the View prefix. The prefix is followed by the name of the business object to be viewed.

4.1.1 View<Object>List

This type of pipeline is used whenever a pageable/non-pageable list of business objects is to be viewed. It is also used to perform an action on a set of selected business objects, e.g., delete. This pipeline usually displays the entry page of an HTML back office module.

Examples: ViewDepartmentList, ViewUserList, ViewBuyingOrganizationList

Start Node

Description

ListAll

Determines all business objects to be shown.

Search

Performs a search to determine a set of business objects to be shown. Use this start node name in case you do not distinguish between simple and advanced search.

SimpleSearch

Performs a simple search to determine a set of business objects to be shown.

AdvancedSearch

Performs an advanced search to determine a set of business objects to be shown.

Paging

Determines the next page of business objects to be shown.

Delete

Deletes a selected set of business objects.

Refresh

Re-displays the currently active page in case of a pageable list or simply all business objects (jump to node ListAll). This start node should be called whenever we jump back to the list, i.e., after update. Hint: Use page locator pipelets in bc_foundation to store the current pageable as session object.

4.1.2 View<Object>

This type of pipeline is used whenever a single business object is to be created/edited/deleted. It is also used to perform an action on a single business object, e.g., set as default, copy.

Examples: ViewDepartment, ViewUser, ViewBuyingOrganization

Start Node

Description

New

This start node prepares the creation of a new business object. In most cases it simply creates a new webform and sets the creation template. Hint: To reduce template complexity, do not use the same template for create and update.

Edit

This start node prepares the update of a new business object. In most cases it determines the business object to be edited, creates a new webform and sets the update template.

Show

This start node is used to show a new business object in read only mode. In most cases it determines the business object to be shown, prepares data and sets the update template.

Create

This start node creates a new business object. If the object could not be created successfully, the creation template is shown again (there should be an error message shown somewhere on the template).

Update

This start node updates an existing business object. If the object could not be updated successfully, the update template is shown again (there should be an error message shown somewhere on the template).

Delete

Deletes a given single business object. If the object deletion succeeded, the corresponding list template is shown again.

4.1.3 View<Object><AssociatedObject>List

This type of pipeline is used whenever associated objects or object relations of a single business object are to be listed. In most cases these pipelines are used to display a "tab" in an object detail view.

Example: ViewDepartmentUserList, ViewProductCustomAttributeList, ViewProductAttachmentList, ViewProductBundledProductList

Start Node

Description

ListAll

Determines all associated business objects to be shown.

Search

Performs a search to determine a set of associated business objects to be shown. Use this start node name if you do not distinguish between simple and advanced search.

SimpleSearch

Performs a simple search to determine a set of associated business objects to be shown.

AdvancedSearch

Performs an advanced search to determine a set of associated business objects to be shown.

Paging

Determines the next page of associated business objects to be shown.

New

This start node prepares the creation of a new associated business object. In most cases, it simply creates a new Web-form and sets the creation template. If the creation/update process is very complex or uses a wizard-approach, you may consider using a separate pipeline, i.e., ViewDepartmentUser, ViewProductCustomAttribute. Hint: To reduce template complexity, do not use the same template for create and update.

Edit

This start node prepares the update of an associated business object. In most cases it determines the associated business object to be edited, creates a new webform and sets the update template.

Create

This start node creates a new associated business object. If the object could not be created successfully, the creation template is shown again (there should be an error message shown somewhere on the template).

Update

This start node updates an existing associated business object. If the object could not be updated successfully, the update template is shown again (there should be an error message shown somewhere on the template).

4.1.4 View<Object><AssociatedObject>

This type of pipeline is used whenever an associated object or object relation of a single business object is to be created/edited/deleted. This functionality can also be included into the corresponding list pipeline in case of a simple creation/update/deletion process.

Example: ViewDepartmentUser, ViewProductCustomAttribute, ViewProductAttachment

Start Node

Description

New

This start node prepares the creation of a new associated business object. In most cases, it simply creates a new Web-form and sets the creation template. Hint: To reduce template complexity, do not use the same template for create and update.

Edit

This start node prepares the update of an associated business object. In most cases, it determines the associated business object to be edited, creates a new Web-form and sets the update template.

Create

This start node creates a new associated business object. If the object could not be created successfully, the creation template is shown again (there should be an error message shown somewhere on the template).

Update

This start node updates an existing associated business object. If the object could not be updated successfully, the update template is shown again (there should be an error message shown somewhere on the template).

Select<Object>

Use this start node name in case of a wizard-like creation/update process. Example: SelectRole, SelectSupplier

4.2 Process Pipelines

To facilitate the reuse of process pipelines, they should be named according to the task they perform, and not after their position in a workflow or the business process they represent. Thus process pipelines can be called from different places.

Examples: CreateBasket, LoginUser

Different entry points to the pipeline or special result handling methods should be reflected by defining separate start nodes.

Example: ProcessPayment-AuthorizationFailed

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets