Naming Conventions - ActiveVOS

Challenge

When building an ActiveVOS project many objects of different types have to be created. These objects will be used as resources by business users and exposed to partner services via an API. It is  important that a naming convention is chosen, documented and used throughout the project. This will avoid misunderstandings, facilitate code sharing, add to the clarity of the project and also lend itself to compliance where standards are required.

Description

In this document we will describe Informatica’s best practice for naming conventions for ActiveVOS projects. The following are objects that can have standardized naming conventions.

• Project Names
• Bpel Names
  • Variable Names
  • Partner Names
  • Activity names
• Wsdl names
  • Port type names
  • Partner Link Names
  • Part names 
  • Operation Names
• Schema names
  • Schema element names
  • Schema type names
  • Schema attributes names
• Html File Names
• Pdd names
  • Service Names
• Folder names
• Targetnamespaces
  • prefixes

What is a Naming Convention?

When we choose a naming convention we choose how we are going to name different objects. Naming conventions can be strict or loose. Sometimes there are technical restrictions on names. These restrictions need to be included in your naming convention (e.g., CamelCase.bpel for bpel files since all bpel files have to end in the .bpel extension).

Naming Convention Examples

We will use something that is called My New Object and show an example of the naming conventions listed.

Choosing a Naming Convention

When choosing a naming convention for ActiveVOS, check for the following standards that may already exist: 

• Company Standards
• Application Standards
• Project Standards
• Once you have a list of business restrictions /standards determine the list of object types within your scope that you have control over naming For each object type determine the technical restrictions. For example, some names can have spaces others cannot or, some objects need an extension while others do not. List the object types and restrictions.
• For each object discuss the options and determine a naming convention.
• Choose a naming convention.
• Document the naming convention.
• Put a check in place for the naming convention. Code reviews are usually good place to enforce naming conventions.

Naming Convention Rules

Every Object Type does not have to have the same naming convention

For example bpels can be CamelCase and wsdls can be camelcase.

Every Object does not have to have the same naming convention

Some service names can be <BpelName>Service; another could be <Function>AutomatedStep so long as the naming convention states the rules are.

You can have exceptions

Sometimes you have to have exceptions these just need to be documented.

Technical restrictions with ActiveVOS objects

Below are the technical restrictions that apply to the most common ActiveVOS objects. In the case where the object is a file the restriction is whatever the file system restriction is. Different file systems impose different restrictions on filename lengths and the allowed characters within filenames. For example a file called myFile.txt and myfile.txt can co-exist in the same folder Linux but on in windows.

Best Practice ActiveVOS Objects

Avoid Spaces in File Names

Even though spaces are allowed in the file name objects, because spaces are non-visible they may represent double byte characters that cause problems when copying bpels and creating indexed properties. It is therefore better to exclude spaces from bpel, wsdl, schema and project names.

Have Different Names for Types and Elements in Schemas

Since a schema type is a different object to a schema element, it is technically possible to give a type the same name as an element. This can cause confusion. It is better for the names to distinguish between the elements and the types. The most commonly used standard is to have the word Type at the end or the beginning of a type name for example, element = Address, type = AddressType.

Service Names

The service name is set in the pdd. Unless the service name is changed the service name is the same as the Port Type name. If this is not changed it means that you cannot have two processes based on the same Port Type running on the same server.

1. Rename the Service  so it does not have the same name as the Port Type
2. Choose a naming convention for services that indicates that they are service names 

The most common naming convention used are <Function>Service or <BpelName>Service>. So if a process called GetCustomer.bpel is created, under this naming convention, the service name would be GetCustomerService.

You may also have a callback service name that has to be added to a partner service. The most common naming convention for this is <Partner Service Name>Callback.

Participant Names

A new Process Service Consumer created in ActiveVOS designer is named Process_Consumer by default. If the default name is not changed, many processes will be named process consumer. Sometimes the convention used by the Process Developers is to use Process File Name for a Process Service Consumer Name. This is not possible when a process bpel file name contains spaces. Therefore, it is better to avoid spaces in the process file names.  As an example, the Bpel Process is called GetCustomer.bpel. The process consumer participant name is GetCustomer.

When Defining Partner Service Provider, ActiveVOS designer will generate name “Partner” for the first provider. The second one will be Provider1 and so on. Leaving the default names creates confusion.  Best practice is to provide a naming convention for partners and use those names. It is also recommended to use the same name for the same logical Partner Service Provider in all processes that use that service.

Informatica recommends creating a list of partner services port types and the partner name that should be used as the participant name. Then every time a partner service is used in different bpels is used with the same name.

Sometimes the suffix PL or PLT is used in names of Process Participants (e.g., GetCustomerPL. Informatica recommends that suffixes are a matter of individual preference).

Project Names

Usually a project name is assigned before the project starts. ActiveVOS may have more than one physical project relating to a logical project. The name should reflect the reason for the project. A common project can be named <Logical Project Name>Common. . If a set of projects are being created, use a logical naming convention. An abbreviation for the project may be needed so that project names do not get to long. For example a logical project name could be: My Really Really Important Project. Using the abbreviation of MMRIP could result in the following physical project names.

• MRRIPCommon
• MRRIPUtilities
• MRRIPHumanTasks

Bpel Names

Although spaces are allowed in Bpel names it is best practice not to use spaces.

You may have one naming convention – CamelCase, camelCase…Or you may have a set of naming conventions such as: 

• Automated Step Bpels : <Function>Step.bpel
• Rest Bpels <Function>REST.bpel
• IDD Task Workflow bpels <Function>Workflow.bpel
• OtherBpels <Function>.bpel

Pdd Names

When a Pdd is created it has the same name as the Bpel it is generated for as there is a 1-1 relationship between bpels and pdds the best practice is to keep these objects with the same root names.

Activity Names

An activity is represented in a Bpel as either a box or a structure. Each activity has an activity name. The names should be a short description of what the activity does.

After you create an Activity in ActiveVOS, change the name to something meaningful.

Target Namespaces

In ActiveVOS Schemas, WSDLs and Bpels have targetnamespaces

• Choose a targetnamespace preamble for your schema, wsdl and bpel files.
• Determine wither version number should be included in the targetnamespace.
• Determine whether the object type should be included in the targetnamespace.
• Decide between urn values and url values.
• Decide whether uppercase is allowed.
• Document the decisions.
• Set the workspace preferences to use the preamble for new bpel processes.

From ActiveVOS designer menu choose Window > Preferences >ActiveVOS. Click on the ActiveVOS tab to see the Target Namespace Preamble field.

Optional:

Normally schema and wsdl targetnamespaces are edited in the actual objects. Many times these objects are created outside of a wizard so the default is not applied. Many schemas and wsdls are started with a copy.

Set the default for the new schemas.

Set the Default for the new Wsdl files.

Examples:

http://www.informatica.com/training/RoadRepairEstimator

http://schemas.xmlsoap.org/wsdl/

urn:siperian.api

http://wsdl.informatica.com/sample/roads/2013/08/roadProblem

Target Namespace Prefixes.

ActiveVOS automatically assigns a prefix for any new targetnamespace that are used in your bpel process. It starts with ns then ns1, ns2 etc. When xml  generates the types indicated by the targetnamespace it is not clear which type is being used. It is best practice to use the same prefix for the same target namespace in all your bpels. This makes the resulting xml easier to read. It also allows xQuery statements to be copied from one bpel to another without having to make changes. Having a prefix that is relates to the targetnamespace it represents makes the code clearer as well and errors can be prevented in XPath and XQuery statements.

Standardize the targetnamespaces with the following steps:

1. List all the targetnamespaces used in your project
2. Determine a prefix for each targetnamespace
3. Document which prefix goes with which targetnamespace
4. Make sure the bpels are updated with the correct prefixes

Other possible and optional common approaches to naming  are: -

• Add the suffix w to wsdls.
• An s is added for schemas
• When there is both a request schema and response schema q is added for request and r is added for response

A get customer example looks like:

or

Prefixes should not to be too long. On the following example xml is generated with a long prefix.

<roadRepairScheduleEstimation:ScheduleRepair xmlns:roadRepairScheduleEstimation="http://www.informatica.com/training/schema/road>
     <roadRepairScheduleEstimation:ReportIdentifier>string</roadRepairScheduleEstimation:ReportIdentifier>
     <roadRepairScheduleEstimation:ProblemReport>
     <roadRepairScheduleEstimation:Location>string</roadRepairScheduleEstimation:Location>
     <roadRepairScheduleEstimation:RoadProblem>pothole</roadRepairScheduleEstimation:RoadProblem>
     <roadRepairScheduleEstimation:ReportedBy>string</roadRepairScheduleEstimation:ReportedBy>
     <roadRepairScheduleEstimation:AdditionalInfo/>
   </roadRepairScheduleEstimation:ProblemReport>
   <roadRepairScheduleEstimation:DateRequested>2014-06-11</roadRepairScheduleEstimation:DateRequested>
   <roadRepairScheduleEstimation:AdditionalInfo/>
</roadRepairScheduleEstimation:ScheduleRepair>

The long prefix roadRepairScheduleEstimation makes the xml difficult to read and much larger than it could be. A good naming convention allows the reader to quickly distinguish between different objects and types.

Documentation

Any naming convention in you project should be documented. Specify whether it is a Company standard, Application standard, or project standard, what the standard is, what it applies to and what the exceptions are.

Exceptions

In some cases resources are provided by external systems and there is no control given over the naming conventions. Many sure any names that do not use the standard are documented in an exceptions section.

Summary

Best Practice in naming conventions for ActiveVOS can be summarized as follows:

• Choose a naming Convention for all objects even if it is a loose naming convention.
• Document the Naming convention.
• Document the exceptions. Make sure it covers objects that will be created with default names and numbers to avoid confusion during maintenance cycles.