Credits: Mark Dobbie, Matthew Oatts, Sergiy Tsymbal, Fahad Osmani

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


Process Apps

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


Service Types

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


Example Tags and Names

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