Pipelines
Pipeline Elements
A pipeline is a logical model of a particular business process, similar to a flowchart (流程图) . Demandware UX Studio provides a visual representation of the process within the Eclipse IDE.
Pipelines are stored in XML files in the file system, both locally on your PC and on the server. Pipelines are defined and stored within the context of a cartridge.
When the storefront application attempts to reference (引用) a pipeline in a cartridge, it searches for the pipeline in the cartridge's path and uses the first one it finds. In other words, when a pipeline with the same name exists on two cartridges, the first one found in the path is used. Therefore, it is best to use unique pipeline names to ensure that the framework locates the correct pipeline.
There are fifteen different pipeline elements available to you for developing a pipeline. Each node has a specific function：
1. Start Node
Begins the logical branch of a pipeline.
2. Interaction Node （交互节点）
Used when a request requires a page as a response.
3. Transition Node （过渡节点）
Defines a path along a pipeline between pipeline nodes.
4. Call Node
Invokes a specified sub-pipeline. After the sub-pipeline execution the workflow returns to the calling pipeline.
5. End Node
Used to terminate a sub-pipeline, returns to the calling pipeline.
6. Jump Node
Used when the pipeline forwards the request to another pipeline.
7. Join Node
Provides a convergence point for multiple branches in workflow.
8. Interaction Continue Node (交互继续节点)
Processes a template based on user action via a browser.
9. Script Node
Used to execute Demandware scripts.
10. Eval Node (运算节点)
Evaluates an expression.
11. Assign Node (赋值节点)
Used to assign values to new or existing Pipeline Dictionary entries, using up to 10 configured pairs of dictionary-input and dictionary-output values.
12. Stop Node
Used to terminate a sub-pipeline and calling pipelines, stops execution immediately. Used in pipelines that executes a batch job.
13. Loop Node
Used to loop through an iterator.
14.Pipelet Placeholder (Pipelet占位符)
Placeholder for a script node.
15. Decision Node (决策节点)
Evaluates a condition and navigates to a different branch in the pipeline.
Creating a Pipeline
In order to create a new pipeline, you will need at least one Start node and one Interaction Node. When creating a new pipeline in Studio, the pipeline palette will be available in the Pipeline Editor.
If you do not see the palette when you create a new pipeline, be sure to click the button on the upper-right corner of the editor to open it up.
Start Nodes
A pipeline may have multiple Start nodes but each node must have a unique name. Every Start node is the beginning of a different logical branch within the pipeline.
Configuration properties include:
1. Name: Used in pipeline calls
2. Call mode: Specifies the accessibility of the pipeline from a browser.
a. Public: Can be called from the browser or from another pipeline
b. Private: Can be called from another pipeline via Call or Jump Nodes
3. Secure Connection Required:
a. False: Pipeline can be invoked with HTTP and HTTPS protocols
b. True: Start node can only be accessed via secure (HTTPS) protocol.
Interaction Node
This node specifies the template to display in the browser.
If Dynamic Template is:
1. true: Template Expression must be a variable containing a template name. The template to be called by an interaction node is not always hard-coded in the node. Instead, the name can be determined dynamically during runtime from the Pipeline Dictionary.
2. false: The template expression contains a path to the template under the templates/default folder
Transition Node
The transition node creates a transition between two nodes. You can easily create a transition between two nodes by clicking and dragging your mouse between two nodes in a pipeline.
Executing a Pipeline
Pipelines can be executed from the browser via an HTTP(S) request or via Call or Jump Nodes. If the pipeline Start node is set as ‘Private’ it can only be called via a Call or Jump node.
Calling a pipeline via a HTTP request requires the pipeline name and start node at the end of the storefront URL:
http://instance.realm.client.demandware.net/on/demandware.store/Sites-YourSite-Site/default/PipelineName-StartName?ParmName=ParamVal1&...
Checklist when first pipeline does not work
1. Make sure that you are in Navigator view before the next steps in this exercise.
2. Right-click DemandwareServer and then hover your mouse over
Demandware. You should be able to see Active Server and Auto-Upload checked. If you do not, then check them.
3. DemandwareServer >Properties >Project references. Check that your cartridges are checked.
4. DemandwareServer > Demandware > Change Upload Staging Directory. Make sure that the Target version directory and Active version directory matches.
5.DemandwareServer > Demandware > UpdateServer Configuration. Make sure that the configuration is correct.
6.Check your cartridge path. Navigate in your browser to Business Manager. Further Navigate to Administration > Sites > Manage Sites > Site Genesis >Settings tab. Check your Cartridge path. It should have the exact same name as the cartridges as in eclipse. There should be no spaces in the path. Make sure that there
are no semicolons(分号) in place of colons. Also be aware that the names are case sensitive.
7.Administration > Sites > Manage Sites > Site Genesis >Cache
Tab. Check if Time to live is 0 and Enable Page Caching is disabled.
8.If you have forgotten before, index your site now. Navigate to Site > Site Genesis > Search > Search Indexes.
Check all checkboxes and click on Reindex
9.Check if your project is configured to build automatically in eclipse as below. Project > Build Automatically
Troubleshooting with the Request Log Tool
The first tool you can use for troubleshooting error messages on your storefront is the Request Log tool which is part of the Storefront Toolkit that is available in all instances except for Production.
The Request Log tool displays the log for the last request and any request prior(优先) during the current session. You can see debug messages as well as error messages.
The most common errors you will make as a new Demandware developer are typographical. In the example below, a call was made to a pipeline named ‘Pipe2’with a start node called Start.
You may write: 'Pipe2-Start'
But Start name is 'Begin', so it's should be 'Pipe2-Begin'.
When looking at the request log, you can see the error is “Start node not found (Start)”
Call Nodes & End Nodes
Call nodes and End nodes work together to process specific functionality in a pipeline.
Call Nodes
A Call node invokes a specified sub-pipeline. A sub-pipeline is a pipeline that is designed for reusability and typically is defined as private, meaning that it cannot be invoked from a URL.
After the sub-pipeline execution the workflow returns to the calling pipeline by means of an End node. It basically behaves like a function call where the function might return one or multiple values.
A Call node requires only a Pipeline-Start node to invoke. This information can be provided as a fixed (固定) configuration value or from a pipeline dictionary key.
一个Call节点调用一个指定的sub-pipeline, 一个sub-pipeline, 一个Sub-pipeline 用于反复使用，通常定义成私有，意思说不能在URL中直接访问。
在sub-pipeline 执行完以后使用一个End Node返回被调用节点，它的基本行为是一个方法返回一个或者多个值。一个Call node只需要一个Pipeline-Start 节点来调用，这个信息可以在固定的pdict配置值中提供。
End Nodes
An End node finishes the execution of the called sub-pipeline and returns a value equal to the End node name. This name must be unique within the sub-pipeline and it may be used by the calling pipeline to control flow after the call.
After the call, a transition from the Call node with the same name as the returned value is followed. In the picture below, if the CheckValue sub-pipeline returns a notEmpty value, then that transition is followed on the Start pipeline.
Jump Nodes
A Jump node invokes a specified sub-pipeline. After the sub-pipeline's execution the workflow does not return to the calling pipeline. It is the responsibility of the sub-pipeline to complete the task.（由sub-pipeline负责完成task）
A jump node requires:
-
The name of the pipeline to be jumped to and
-
The name of the pipeline start node to be used
This information can be provided:
-
Either as a fixed configuration value OR
-
From a pipeline dictionary key
An example of using Jump nodes is the Default pipeline. This is a special pipeline that is called by the system if no pipeline name was provided in the URL. In SiteGenesis the Default-Start pipeline jumps to the Home-Show pipeline, which shows the homepage.
The Pipeline Dictionary
The pipeline dictionary or pdict is the main data container for each pipeline execution. It is created and initialized when a pipeline is invoked and remains in memory as long as the pipeline executes.
The structure of the pipeline dictionary is a hash table with key/value pairs.
The default keys in the pdict are:
-
CurrentDomain
-
CurrentOrganization
-
CurrentPageMetadata
-
CurrentSession
-
CurrentRequest
-
CurrentUser
-
CurrentHttpParameterMap
-
CurrentForms
-
CurrentCustomer
-
CurrentVersion
The pdict is passed across sub-pipeline calls: whenever a call or jump to another pipeline is executed, the same pdict is passed to the invoked sub-pipeline.
To view the values stored in the pipeline dictionary at run-time, run a pipeline from the storefront while in a debug session.
Passing Parameters
The parameters will get added to the
CurrentHttpParameterMap object inside the pdict. You can see the values stored in the pipeline dictionary when you run
the pipeline debugger. CurrentHttpParameterMap is an object of type HttpParameterMap. It contains a single key called param which in turn contains multiple values. One of them is the stringValue, which contains the string ‘1234’. You could also use the intValue if you wanted to use the integer value 1234 on a calculation.
Troubleshooting with the Pipeline Debugger
When you are testing your pipelines in the storefront and receive an error on execution, you can use the Request Log tool as well as the Studio Pipeline Debugger to help you troubleshoot your pipeline.
Pipeline Debugger
The Pipeline Debugger operates on the pipeline level, not at source code level. The Debugger allows for step-by-step tracking of pipeline execution and for examining(检查) the pdict at runtime.
The Debugger requires a running Demandware system and a properly configured Remote Server connection. You will also need to create a debug configuration before running the Debugger.
In order to execute the pipeline debugger properly, you will need a pipeline with breakpoints set on at least one node of the pipeline.
When a pipeline debugger is launched, the breakpoint color changes from a semi-transparent （半透明） green to a solid green
Debugging a Pipeline Using the Debugger
Once you have created a debug configuration, you still need one more step to use the Debugger. To execute a Pipeline Debugging Session, you will also need to set breakpoints in the pipeline where the Debugger will pause.
Pipelets
Now that we have introduced you to the pdict, let’s start using it to print information to a page using Pipelets.
A pipelet executes an individual business function within a Demandware pipeline. Pipelets are pre-coded pieces of functionality provided by Demandware but you can also use other types of pipelets from the palette such as:
-
Script: use to invoke a custom Demandware script file
-
Eval: use to evaluate data in the pdict.
-
Assign: use to assign values to specific keys on the pdict
Demandware Pipelets are available in Studio via the Pipelets view. They belong to the bc_api cartridge which is always downloaded as part of the Demandware API the first time you connect to a server. There is a published API available under Studio Help menus or in the Demandware documentation site.
Each Demandware pipelet has documentation on its functionality, input and output parameters. You can see this information in the Properties view when the pipelet is selected on the pipeline.