Introduction
IBM BPM provides a number of generic artifacts for modeling purposes.
These can be combined in a variety of ways in order to solve different
technical problems.
A design pattern is used to document how a
combination of model artifacts may be used together in order to solve a
specific technical problem. Unlike a framework or utility, a design
pattern cannot be deployed directly. A design pattern is rather like
having a pattern template for making clothes, where a tailor may use the
same template to create a number garments using different materials.
The design pattern provides a design template that allows the BPM
developer to solve the same technical problem consistently throughout
the model using different artifacts. Design patterns promote re-use and
improve maintainability. Example design patterns include Layered
Architecture, Task Services, Coach Services, Data Access Services and
Manual Unit Tests.
General Patterns
This page outlines a number of general design patterns.
If reading for the first time it is recommended that the reader should read these key patterns in the following order:
1. Smart Folder and Tagging
Design Pattern
Objective
Tags can be used to create specific smart folders making it easy to
manage and account for the development cycle of the assets being
created. Using the “By Tag” library view, a user will be able to sort
through a large asset library quickly.
You’re not limited to just one tag per component. For instance, if you
have a service/BPD/integration that tests your database connections it
would be tagged as both a test and a database service.
General (Pre-Exist in TW7)
Tag
|
Purpose |
| Data Access |
General data access integrations (CRUD) |
| Data Transform |
Transforms data from one form to another (e.g. when coming out of web services into a BPD) |
| Database |
To distinguish Integration services that interact with databases |
| Exceptions |
Used to handle exceptions |
| Deprecated |
Items that are kept around for backward compatibility but are no longer the recommended implementation |
| Installation |
Used for the installation of a process app or toolkit |
| Integration |
A specific integration implementation |
| Report |
Implementation that is used for reporting purposes |
| Reporting |
To distinguish which services, variables, tracking groups, etc are linked to reporting |
| Security |
Anything that is dealing with security, such as users and groups |
| Task |
Specifically used to implement a task in a process. Can be used on all first-level task services |
| Test |
To distinguish Test Harnesses |
| Top Level |
The top-level BPD or a top-level service. Can be useful with an associated Smart folder to know where the top items are |
| UI |
Helpers for human services, such as getting lists of text for a list |
| Utility |
A utility service |
| Web Services |
To distinguish Integration services that interact with web services |
Naming Convention
Tag services as required in the
Naming Conventions Pattern
Other Tagging Options
If your developers are the compulsively organizational type, try the
following ideas for tags, and let us know the results. We’re always
looking for feedback.
- Development Status Based Tags - Tag each and every artifact with its development status (To Do, In Progress, Completed, etc.).
- User Based Tags - Tag Task Services, Reports, and BPDs by the users/participant groups that will be using them.
- Process Based Tags - If you have a process app with multiple
processes, tag each process-specific artifact with a tag of the BPD it’s
associated with.
Smart Folders
Objective
While the new library in IBM BPM versions 7 and up eliminates the
cluttered, confusing nested library structure of previous Teamworks
versions, it also eliminated the ability to quickly access top-level
services and business process diagrams. We can eliminate this
deficiency, and improve our development experience, by using tagging and
smart folders.
Application
There are 4 types of IBM BPM artifacts that we want to be easily accessible. Create a
shared smart folder for each tag listed in the table below.
Smart Folder
|
Tag
|
Description
|
Example
|
Top-Level BPDs
|
Top-Level BPD
|
These BPDs should be the highest level BPDs in
your process app. You may only have a few, but the ability to get to
them quickly is important. |
An enterprise HR Onboarding process BPD. This
may live in the HR Process App, alongside other processes, but it stands
alone from others (i.e. offboarding, conflict resolution, etc.). We
would tag the HR Onboarding process with “Top-Level BPD”, and it would
add itself the top-level BPD smart folder. We would not tag any
sub-processes this BPD has (i.e. background check, adding to payroll
system, etc) |
Top-Level Services
|
Top-Level Service
|
These stand-alone services (primarily Human Services) do not exist in any BPDs. |
- A CRUD (create, read, update, delete) service used to allow users to manually manage database content, event schedules, etc.
- A service that contains a report embedded in a coach, which will be
deployed on the Left Side Navigation bar in the IBM BPM Portal.
- A service that allows users to drilldown through process instances and the data/statuses associated with each.
|
| Integrations |
(Use system specific tag)
|
These are services which contain integrations with other systems.
Note: To create this folder, use system specific tags (i.e.
Database, Document Management, Legacy System). This way, you’ll be able
to sort your smart folder by integration (sort by tag). |
- A service that updates customer information using a webservice
- A service that writes a document to a content management system.
|
Test Services
|
Unit Test
|
Services/BPDs used to test User Interfaces, Integrations, Process flow, etc. |
- A service used to test an integration with a document management system.
- A service used to test a user interface’s validation on a customer service coach.
- A BPD used to test proper process flow.
|
Examples
Smart Folder
|
Example Screenshot
|
Top-Level BPDs
|
|
Top-Level Services
|
 |
| Integrations |
 |
Test Services
|
 |
2. Naming Conventions
Purpose
To provide a standard method of naming TW artifacts to better
organize and manage process apps. Additionally, updating the standard
from Teamworks 6 in order to leverage new features in Teamworks 7 and
make this pattern easier to learn and use.
Noticeable Changes from the TW6 pattern
Prefixes
Because of the separation of process apps in Teamworks 7, there is no
longer a worry of cluttered libraries with artifacts from multiple
different process apps. This removes the need for prefixes.
Body
The use of reserved verbs will help to clarify the action/use of a service.
Abbreviated Suffixes
Due to the new service types in Teamworks 7, and the addition of tagging
capability, abbreviated suffixes, used heavily in Teamworks 6 naming
convention pattern, are no longer part of the pattern. This should help
make the naming pattern simpler and more user-friendly.
Artifacts
New service types allow artifacts to have simpler names, and the use of tags will allow clarification for users.
Tag
|
Artifact Type
|
Description
|
Notes
|
Examples
|
Tasks
|
Human Service or General System Service
|
A service that directly implements an activity. Such a service is responsible for coordinating a whole task for a user/system. |
|
Register Sales Opportunity
|
Coaches
|
Human Service
|
A service that implements a single coach. It is generally recommended that a service not have more than a single coach in it. |
If the coach service has the same name as the task service, add the suffix “Coach” to the coach service. |
Register Sales Opportunity Coach
|
Events
|
General System Service
|
A service that is used specifically to invoke an Event Driven UCA. |
The UCA has the same name as this service. If event based, append “Event” on both this service and the UCA
|
Start Sales Cycle Event
|
Event Implementation
|
General System Service
|
A service that directly implements an Event Driven UCA. |
To name this service, precede the UCA name with the reserved verb “Implement”. |
Implement Start Sales Cycle Event
|
Data Access
|
Integration Service or General System Service
|
A service whose specific purpose it is to get
some data from inside (EPV, properties, variable) or outside (DB, LDAP)
Teamworks and return it to the calling service/BPD. |
Use the reserved verb “Retrieve”.
|
Retrieve Company Info
|
Unit Test
|
Human Service, General System Service, BPD
|
A service designed to test another service or BPD. |
The unit test has the same name as the
service/BPD being tested with the reserved verb “Test”. This can apply
to any other type of service, such as task services, coach services, web
service services, etc. |
Test Register Sales Opportunity
|
Coach Validator
|
General System Service
|
A service used to encapsulate coach validation logic. |
This is used in conjunction with the Coach Validation Framework. Service name starts with reserved verb “Validate”.
|
Validate Sales Opportunity
|
Batch
|
General System Service
|
A service that directly implements a Batch/Chron driven UCA. |
To name this service, precede the UCA name with “Batch” and the reserved verb “Implement”. |
Batch Implement Sales Cycle Event
|
Utilities
|
General System Service
|
A service that implements some piece of utility functionality (such as text parsing for valid email format, etc) |
|
Parse Email Addresses
|
Inbound Web Service
|
Web Service
|
A service that directly implements a Teamworks hosted Web Service. |
|
ReceiveProductDetails
|
Outbound Web Service
|
Integration Service
|
A service that wraps a Web Service connector. |
|
Update Sales Opportunity in Salesforce.com
|
Constructor
|
General System Service
|
A service that initializes a variable. |
Precede the variable name with the reserved verb “Construct” |
Construct SalesforceOpportunity
|
Business Object
|
Variable Type
|
A variable type that resides within the
Business Object Model layer within a layered Teamworks architecture.
These are used to define a common view of business data within a
Teamworks process. |
|
SalesforceOpportunity
|
View Object
|
Variable Type
|
A variable type that resides within the View
layer within a layered Teamworks architecture. These may be defined to
present data in a specific way. |
|
|
Integration Object
|
Variable Type
|
A variable type that resides within the
Integration layer within a layered Teamworks architecture. These may be
used directly with SQL and Web Service connectors that load data
directly into Teamworks variables. |
It may be useful to include the system being integrated with in the title of the variable.
|
SalesforceSalesOpportunity
|
Example Library
Reserved Verbs
These verbs can be used at the beginning of artifact names in order to more clearly specify the action of the service.
Verb
|
Use
|
Example
|
Retrieve
|
Pulling data from a system of record |
Retrieve Product Details from Salesforce |
Write
|
Creating a new record in a system of record |
Write Customer Details to Salesforce |
Update
|
Updating an existing record in a system of record |
Update Customer Details in Salesforce |
Delete
|
Removing a record from a system of record |
Delete Customer from Salesforce |
Send
|
Sending a message event/email to another system/participant |
Send Email to Customer |
Receive
|
Receiving a message event to and from a participant |
Receive message from Salesforce |
Validate
|
Validating a coach using the coach validation framework |
Validate Product Details Coach |
Test
|
Testing a service |
Test Delete Product Details from Salesforce |
Construct
|
Initializing a variable type |
Construct ProductDetails |
Implement
|
Implementing a UCA |
Implement Batch Timer |
Higher Level Artifacts
Snapshot Names
Snapshot names should do at least 1 of 2 things:
- Provide a date stamp of the snapshot (e.g. v15March2010 or 14June2010Release)
- Describe change/enhancement (e.g. RouteAroundExecutiveApprovals)
Here is an example of a more detailed naming convention around Snapshots
Special Note for BPM Advanced
Not all the recommendations apply to BPM Advanced. For example, refer to this
infocenter reference in situations where you want to use more than 3 digit numeric snapshots.
- (Prior Release/Production).(Playback/Maintenance Release).(Snapshot per Current Playback/Maintenance Release).(Workspace branch)
- Examples:
- Snapshot for Release 1 development prior to installation to
Production, during playback 3 development, the 6th snapshot during this
time = 0.3.6
- Snapshot for Release 1 development post installation to Production,
during development for the 2nd maintenance release, the 4th snapshot
during this time = 1.2.4
- Snapshot for Release 1 development post installation to Production,
in a workspace taken from a branch at 1.2.4, 1st snapshot in this
branch= 1.2.4.1
- Once there are multiple releases and multiple workspaces, this might
need to be expanded to incorporate that. A possible approach would be
going to other snapshots for subsequent releases (normally with a major
scope change) or starting over from a snapshot of choice from a prior
release.
Environment Variables
Environment Variables Naming Pattern: Coming Soon
Process App Names
- Name your Process Application after the main process in the PA or the business term/purpose for the PA
- Don’t use words “Process Application” in PA’s name
Toolkit Names
- Name the toolkit after what utility/services it provides
- Add “Toolkit” or “Framework” word to the name, so the export of it can be differentiated from process applications.
Process App & Toolkit Names
- Don’t use very long names try to keep it less than 64 characters
- Use white space between words to improve readability
- Avoid using abbreviation (this is what acronym is meant for) except common words to make the name shorter
- Put additional information in Description field
- Don’t use version number in the name (this is what snapshot should
be used for), unless want to bring attention to the major change in the
solution (like Axis2 vs Axis)
Diagram
The names of model artifacts should be shortened to be readable on
the diagram, but they must still provide an explanation of what the
attached artifact does.
Specific Conventions
Logging. For most logging-related library items, the words “Log” or “Logging” should appear in the name.
Layouts. Layout names will generally include the name of the
specific type of layout, e.g. a coach layout will have the word
“Coach” in it. Again, this is not necessary, but it is useful.
Variable Types. Variable types must be all one word, no
spaces and a limited selection of special characters (0..9 and _ are
allowed). Also, variable types should always begin with a capital
letter. Usually new types are defined to be complex objects
(structures), and the standard for capitalization for such types is to
be capitalized.
UCAs. UCAs that will be used as Events in a BPD should be
named with the word “Event” in the name. For example, “New Order
Event”. The services which implement these UCAs should be labeled as
“Implement New Order Event” for example. UCAs which are not tied to a
BPD implementation should not include the word “Event” in the name.
UCAs require attached Services – and it’s best to follow a convention
where the name of the Service is “the same” as the name of the UCA.
While it’s true that multiple UCAs can be attached to the same Service,
it’s generally easier to think of them in terms of a paired Service and
UCA.
Decision Points. Decision points, whether in BPDs or
Services, should be in the form of a question. All of the lines coming
out of the decision should be answers to the question.
Lines coming out of Decision points should have labels that indicate
the condition under which the path is taken. Labels such as “yes” and
“no” require the reader to trace back to the Decision Gateway, so they
should be generally avoided in favor of something more descriptive like
“loan exceeds $100″.
3. Reuse
Design Pattern
Reuse is recognized as a fundamental best practice within the IT
industry and has been practiced from the earliest days of programming.
This basic principle is the basis of many other best practices including
modularity, loose coupling, high cohesion, information hiding and
separation of concerns.
The idea is that a solution should be comprised of reusable modules
instead of replicating complete sections of the solution no matter how
large or small. Each module is written once and maintained in one place.
If another aspect of the solution needs the same functionality then it
can simply delegate to the module that provides that functionality. This
avoids redundancy within the solution, improves maintenance time, and
promotes consistency.
Within IBM BPM resue is achieved by wrapping reuseable aspects of the
solution within a service. A library of reuseable services may be
developed that can simply be dragged onto other service or BPD diagrams
as many times as required. Many other design patterns are based upon
this idea. For example, the task service design pattern illustartes a
specific example of a reusable service.
Services may be used to wrap other model artifacts, such as coaches
and server script, that cannot be reused directly without introducing
redundancy. The coach service design pattern and data access service
design pattern provide good examples of this.
Generally it is a good idea to avoid exposing java script to business
users wherever possible. Wrapping server script within a reuseable
service hides the complexity of the Java Script and provides a simple
component which the business user is more familiar with.
4. Constructor Design Pattern
Use the constructor design pattern to create and initialise the data
in your business objects in a consistent fashion and in one single place
with a reusable component model within a Process Application or
Toolkit. Adopt this design approach, instead of having multiple process
code locations for initialising and setting default values for Business
Objects. Typically, Business Object initialisation is done using local
private JavaScript blocks which make the code difficult to manage,
update and leads to errors/defects that difficult to trace and fix.
This pattern is a specialisation of the standard Singleton Design pattern.
The main parts of this pattern are:
Define a Business Object variable
Create a general system service to be used as the singleton constructor
Declare the target Business object as an input, output and private variable.
Model the General System Service
Create an initialisation wrapper service that calls the constructor
The example below creates a constructor for a list of Job Business Object.
Define a Business Object variable
In this case, I’m using a complex variable called Job
The Business object consists of three parameters – JobDescription, JobStatus, and JobCompleted
Create a general system service to be used as the singleton constructor
Create a service of type “General System Service” that will be used
to instantiate the Business Object and set default values, if required.
I’ve used the prefix underscore (_) in the name to indicate this
service is a helper or utility service that should only be used within
other services and never directly in a human service or BPD activity.
This makes it easy to spot misuse and ensure process developers are
using agreed design guidelines. Also make it easier to unit test
services based on different implementation and usage types.
Created _constructorListOfJobs
Declare the target Business object as an input, output and private variable.
If your variable is a list also declare as an input an integer for
the size of the list to be created and populated with default values.
The input and output variable should be the same Business Object type and have a descriptive name.
The private variable should be the same Business Object type as the
input and output variables, called something like “_constructor”, using a
naming convention to indicate this is only ever to be a private
variable.
Select the “Has Defaults” check box for the private variable to
auto-generate the script to create and initialise the Business object.
See screenshots below for details.
Model the General System Service
Create a script block that contains the default values for this type of Business Object.
In addition, you should add error handling and logging to catch any
errors. Typical errors would be initialisation script errors occurring
after the modification of the Business Object, for example renaming a
parameter.
Usually, the “Has Defaults” auto generated script should update in synch
with any changes in the Business object. If it does not for whatever
reason, just uncheck and recheck the check box to correct the “Has
Defaults” auto generated script.
If required, make the necessary changes to the default values
initialisation script block. Now any referencing BPD or Service that
requires a variable of this Business Object type to be created,
initialised and possibly have default values set will automatically have
the benefit of these changes.
Always nullify private variables for efficient memory management.
I’ve used two exits as this is consistent with the developer
guidelines agreed on the project for modelling utility and helper
services. This simplifies the models in parent services and makes the
flow logic clear when a system error, as opposed to business exception,
has occurred.
Create an initialisation wrapper service that calls the constructor
Create a wrapper service that encapsulates and calls the constructor.
This also has the benefit of being able to use the “Where Used” feature
on the modular wrapper service to clearly see references to other
services and BPDs using this particular Business Object initialisation
logic, instead of trawling through individual private JavaScript blocks.
5. Loop Design Pattern
There are two ways to implement loops within services. One method is
to write it entirely within Javascript, the other is to do it
diagrammatically.
The preceding image illustrates a loop implemented diagrammatically.
Some of these steps actually use small snippets of Javascript, but these
are very simple constructs that business users can easily understand.
The loop requires a counter to indicate the number of times the loop has
been iterated. An Integer may be used for this purpose and is set to
zero during the initialisation of the loop. Any other variable
initialisation may also be performed during this step. For example:
tw.local.count = 0;
tw.local.policyDebt = 0;
Loops are typically used to iterate over a list variable. The list may be empty, so the loop exit criteria must be checked before looping commences. The decision gateway Yes path will require a condition to be specified. For example:
tw.local.count < tw.local.claims.listLength
Some action will be performed each time round the loop. Typically, this may be a Service, a Server Script or a combination. The list variable and counter may be used together to identify the next item within the list. This may be mapped to either an input or an output parameter of a service, or directly within a Server Script. For example:
tw.local.policyDebt += tw.local.claims[tw.local.count].debt;
Before re-entering the decision gateway the counter is incremented. This either locates the next item within the list or triggers the exit condition. For example:
tw.local.count++;
The following code segment illustrates a loop implemented entirely with Javascript:
tw.local.policyDebt = 0;
for(varcount = 0; count
tw.local.policyDebt += tw.local.claims[count.debt];
}
The advantages of using the Javascript approach are:
- Performance improvement. There is a minimal run-time performance overhead when using the diagrammatic approach.
- The speed of development. An experienced Javascript programmer may prefer this approach as it is quicker to implement.
The advantages of using the diagrammatic approach are:
- Easy for business users to understand. i.e. They don't have to become a skilled Javascript programmer.
- Easy to debug. The process inspector allows BPM developers to step through each step within the loop and examine variables. Conversely, Server Scripts are executed atomically, so it is not possible to step through each step within a loop written entirely within Javascript.
- Avoids infinite loops. It is possible to define a loop either using Javascript or diagrammatically where the exit criteria is never satisfied. i.e. it loops forever. IBM BPM provides a facility to detect infinite loops. With diagrammatic loops it is possible for IBM BPM to stop services running infinite loops by using the admin console, whereas the only way to stop infinite loops written entirely in Javascript is to restart the process server.
- Allows nested services to be used within the loop. This is also technically possible within Javascript but it has its drawbacks - the syntax it is not business user friendly and services invoked using Javascript cannot contain coaches.
Additional Notes
If you run a simple test you may see exponential performance impact as you increase the number of loops. However, this is likely due to the structure of your test.
When you add even a small operation, say a 20ms unit of work to be performed inside the illustrated test with a single loop of size 100, the results are no longer different between scripting and diagramming your loop. You'd have 210s (canvas) vs. 200.055s (script). For larger units of work, the difference approaches zero and becomes negligible.
Unless the unit of work inside the loop is insignificant (less than 10ms) and the size of the loop is significant (larger than 100) the performance difference between diagrammatic and script is negligible. On the other hand, there will always be the JS sync issue in anything prior to TW7.
The only time a script loop makes any sense is for very small loop size and/or very small unit of work contained inside the loop.
6. Constants Pattern
Overview
Teamworks does not provide a model artefact specifically designed to
maintain constants used within the Solution. Constants are used to
promote consistency, improve maintenance and reduce typographical
errors. Exposed Process Values (EPVs) are intended to be used to allow
business users modify the parameters affecting business rules within the
solution. However, EPVs may also be used to maintain constants.
For each EPV variable the External Name, Variable Name, External
Description and Default Value should all be identical, as illustrated in
Figure 1. Constants should not be directly exposed within the user
interfaces, use localization resources instead.
Source : IBM
