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.

Pipeline Security

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.

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=

Process Pipelines

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:

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).

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.

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.

Pipeline Naming Guidelines

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.

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

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

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

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

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