Using parameters in task patterns

Processes are defined in xProcess through Patterns - patterns for sets of tasks, for projects, for priority groupings (e.g. Folders) and patterns for artifacts. By constructing sets of patterns, including patterns within patterns (Composite Tasks), a complete definition of the process behind a family of projects can be built up. A key part of pattern definition is the specification the pattern's parameters. This is what this article looks at.
The diagram above shows the editor for a typical pattern from the Simple Process, showing the 4 parameters that this pattern has: Name, Project Home Page, Start Date, Duration. These are the values that the user can supply when creating an instance of the pattern. Parameters always have default values which are used if the user does not change them, but you can add an action to a parameter - a DefaultValueGetter - which will set the default value at run time based on teh context or time at which the pattern is being instantiated. You can see in this case that Start Date has such an action attached which sets the start date to the current date. Parameters also have a type which can be one of: Integer, Floating Point, Boolean, String or Rich Text.

Having set up the parameters of your pattern you can then use these values to set values within the elements that are created by your pattern. Typically these will be projects, tasks and artifacts any or all which can be modified from the state of the prototype elements in the pattern to the real elements made when a user uses the pattern.

Th first way to use a parameter is by string substitution. Any text field in your prototypes, for example the prototype project's name, can include a parameter substitution. Simply enclose the parameter name with 'Simple Project pattern, the name of the prototype project is $Name$, showing that when the pattern is used the name of the project comes from this parameter. It's also used in the case of the Project Home Page parameter, which sets the description field to point to this url.

You can even use string substitution with artifacts, provided that the artifact uses a text-based, rather than binary format (e.g. rtf, xml, csv formats). In this case just put the substitution string, say $Name$ inside the file attached to your pattern. You'll find when you use the pattern that the corresponding artifact has this string substitution applied. Several patterns in the Basic FDD signs in the field, and when the pattern is instantiated the parameter value will appear at this point instead. You can see an example of this type of parameter use in nearly all the pre-defined patterns delivered with xProcess. In our example here, the Simple Project pattern, the name of the prototype project is $Name$, showing that when the pattern is used the name of the project comes from this parameter. It's also used in the case of the Project Home Page parameter, which sets the description field to point to this url.

You can even use string substitution with artifacts, provided that the artifact uses a text-based, rather than binary format (e.g. rtf, xml, csv formats). In this case just put the substitution string, say $Name$, inside the file attached to your pattern. You'll find when you use the pattern that the corresponding artifact has this string substitution applied. Several patterns in the Basic FDD process have artifacts that use this feature.

The second important way that parameters are used is in actions. As well as DefaultValueGetters, patterns have another very useful type of action - InstantiationActions. These actions are called when a pattern is used. When you define InstantiationActions you specify which of the prototype tasks you want to be transformed by the the action, and which particular action you wish to be called. Here's the InstantiationAction used in the Simple Project pattern.It uses the Set project dates action which sets a number of dates (targets and scheduler dates) associated with the project. It is this code which ensures projects you create start on the date provided by the Start Date parameter. One thing to note about parameters appearing in OGNL code is that spaces in parameter names are replaced by underscores and non-alphanumeric codes are ignored. Also following OGNL conventions the parameter is preceded by a hash (#). Note that the Set project dates action uses both the Start Date and Duration parameters.

When you're starting to use parameters in your patterns the best approach is to look at patterns delivered with the pre-configured processes in xProcess and to re-use actions that these patterns use. The Simple Process for example provides the following actions that you can re-use in your own patterns:

• Next timebox date (Project): finds the latest finishing folder/timebox and adds a day to its end date
• Set required role type (Task): finds a RoleType matching the supplied string and sets this as the required role type for the task
• Set target dates (Task): sets targets
• Get today with offset: returns a date relative to the current date
• Set max participants (Task): sets the number of people for a task
• Set project dates (Project): sets target and schedule dates
• Assign to account name (Task): searches for a matching user and assigns to the task
• Get earliest start or end date (Task): returns either today or the task's project's scheduleStart if this is later
• Set target dates and weight (Folder): sets the folder's targets and priority weighting based on that of preceding folders/timeboxes
• Next timebox name (Project): finds the name of the latest finishing folder/timebox with the appropriate name and returns a name with its number incremented
• Set estimates (Task): sets three-point estimates based on Size
• Set importance (Task): categorizes task into High, Medium or Low categories.
  

Note: there are also some UI Actions in the set of actions supplied by the Simple Process. See for example this article: Set size to match effort.