Document Factory Commands

Document Factory uses a set of special commands referred to as $Commands to populate and format the document. The $Commands do not appear in the completed document. Some commands, like $BEGIN_LIST/$END_LIST, are used in pursuant process lists, such as a list of traceability links or a list of users responsible for a requirement. $COMMANDS alone do not place data in the document. You must use them in conjunction with keywords.

There are 4 types of commands:

Note: $COMMANDS are not case sensitive, and uppercase letters are not required for proper operation. However, adopting a formatting style and using it consistently adds to the readability of your templates.

It is important to mark commands in the consistent outlines. For example, $BEGIN_SECTION and its corresponding $END_SECTION must be on the same outline.

If $END_SECTION is not in the same outline as its $BEGIN_SECTION, a problem during the document generation occurs.

Use viewing mode to “outline.” Choose View > Outline in Word. In this mode, the outline of the entire template is clear.

Note: In order for global commands to use Multiple Project command, use (project name,baseline) with no space between ex: $BEGIN_SIGNATURES(Address Book,Current Baseline) .

Commands

The following is a list of commands:
$SORT{ }
(Optional) Specifies the order requirements are sorted.

The following keywords can be used in a sort command: Type, Command, ID_Number, Version, Status, Priority, Hierarchy, Name.

$BEGIN_SECTION
$SORT{hierarchy}
$END_SECTION

The $SORT command determines the order in which requirements appear in a section. By default, the sorting is by ascending order. Keywords used as arguments in the $Sort command can be labeled as ASC for ascending order or DESC for descending order. Ascending is assumed if neither is specified.

If multiple arguments are used in the sort list, requirements are sorted first by the first argument in the list. If there are multiple requirements meeting that criteria, they are then sorted by the second argument, and so on.

$MULTIPLE_PROJECT

$PROJECT{Address Book}
$BASELINE{Current Baseline}

<<Project>>
<<Baseline>

Sort by ID number

$BEGIN SECTION

$SORT{<keyword>}
<<Hierarchy>>, <<Name>>, 
<<ID Number>>

$END_SECTION
$BEGIN_SECTION
$FILTER{Type = ‘1. Business Requirements’}
$SORT{Hierarchy}
$END_SECTION
$SORT{project, <keyword>}

Sorts according to <keyword> gathered from various projects and are listed alphabetically in the order of project names when used Multiple Project Template.

$MULTIPLE_PROJECT

$PROJECT{Company Standards}
$BASELINE{Current Baseline}

<<Project>>
<<Baseline>
$BEGIN_SECTION
$SORT{Project, ID_Number}
<<Hierarchy>>, <<Name>>, 
<<ID_Number>>

$END_SECTION
$SORT_TRACES {<keyword>}
(Optional) specifies in which order the traces should be printed. The command can only appear in the section area and should be used before the $BEGIN_TRACES/$END_TRACES command loop.
You can use the following keywords in a $SORT_TRACES command:
  • Trace_ReqTag
  • Trace_Name
  • Trace_Suspect
  • Trace_TestStatus
  • Trace_DirectImplied
  • Trace_Direction
  • Trace_Project
  • Trace_type
  • Trace_tag
  • Trace_status
  • Trace_priority
  • Trace_version
  • Trace_owner
  • Trace_created_on
  • Trace_created_by
  • Delivery_StoryID
  • Delivery_StoryName
  • Delivery_Status
  • Delivery_Owner
  • Delivery_Project
  • Delivery_Iteration
  • Delivery_IterationEndDate
  • Delivery_Blocked
  • Delivery_PlanEst
  • Delivery_TaskEst
  • Delivery_ToDo
  • Delivery_Rank

The $SORT_TRACES command determines the order in which traces appear for a requirement section. By default, the sorting is by ascending order. Keywords used as arguments in the $SORT_TRACES command can be labeled as ASC for ascending order or DESC for descending order. Ascending is assumed if neither is specified.

If multiple arguments are used with $SORT_TRACES, traces are sorted first by the first argument in the list. If there are multiple traces meeting that criteria, they are then sorted by the second argument, and so on.

The <<Trace_ReqTag>> returns the requirement ID and tag.

Example 1 (single key, ascending order)

$BEGIN_SECTION
$FILTER{Filter: BusinessRequirementsOnly}
$SORT{Hierarchy}
<<Hierarchy>>, <<Name>>
$SORT_TRACES{Trace_ReqTag}
$BEGIN_TRACES(To_Traces,From_Traces,Direct_Traces,Requirement_Objects)
<<Trace_ReqTag>>
$END_TRACES
$END_SECTION

Example 2 (single key, descending order)

$BEGIN_SECTION
$FILTER{Filter: BusinessRequirementsOnly}
$SORT {Hierarchy}
<<Hierarchy>>, <<Name>>
$SORT_TRACES{Trace_Name Desc}
$BEGIN_TRACES(To_Traces,From_Traces,Direct_Traces,Requirement_Objects)
<<Trace_Name>>
$END_TRACES
$END_SECTION

Example 3 (multiple keys, mixed orders)

$BEGIN_SECTION
$FILTER{Filter: BusinessRequirementsOnly}
$SORT{Hierarchy}
<<Hierarchy>>, <<Name>>
$SORT_TRACES{Trace_Direction Desc,Trace_ReqTag}
$BEGIN_TRACES(To_Traces,From_Traces,Direct_Traces,Requirement_Objects)
<<Trace_Direction>>, <<Trace_ReqTag>>
$END_TRACES
$END_SECTION
$INDENTION_LEVEL{ }

(Optional) Specifies the maximum number of levels a section will be indented in the output document.

$BEGIN_SECTION
$SORT{hierarchy}
$INDENTION_LEVEL{3}
$INDENTION_SIZE{.5}
$END_SECTION
$INDENTION_SIZE{ }

(Optional) Specifies how far, in inches, each level is indented.

See the example above

$PROJECT{ }

(Optional) Specifies the project name for the document. Only use $PROJECT once in a template.

$PROJECT{Order Processing}
$BASELINE{ }

(Optional) Specifies the baseline to use for the document.

$BASELINE{Version 1.}
$BEGIN_SECTION

(Required) Marks the beginning of a section. Most commands must be enclosed in a $BEGIN_SECTION/$END_SECTION command.

Rules about a section:
  • A template can contain many sections; however, you cannot have a section within a section.
  • All $Commands except $PROJECT, $BASELINE, and $BEGIN_SIGNATURES/ $END_SIGNATURES, $BEGIN_PROJECT_DISCUSSIONS/$END_PROJECT_DISCUSSIONS, $BEGIN_GLOSSARY/$END_GLOSSARY, $BEGIN_ROW/$END_ROW, $BEGIN_SIGN_ROW/$END_SIGN_ROW, $BEGIN_GLOSSARY_ROW/$END_GLOSSARY_ROW must be used within a $BEGIN_SECTION/$END_SECTION command.
  • There can be only one instance of each type of command in a section.
$BEGIN_SECTION
$SORT{Hierarchy}
$INDENTION_LEVEL{3}
$INDENTION_SIZE{.5}
$BEGIN_LIST
<<References>>
$END_LIST
$BEGIN_LIST
<<responsibilities>>
$END_LIST

<<Name>>
(<<Tag>><<ID_Number>>)
<<Description>>
<<History>>
$END_SECTION

Example 1

In Example 1, all data will be retrieved from the project “Order Processing”.

$PROJECT{Order Processing}
User name: <<Userid>>
Project name: <<Project>>
Project description: 
<<Project_Description>>

$BEGIN_SECTION 

$SORT{Hierarchy} 
$INDENTION_LEVEL{3} 
$INDENTION_SIZE{.5} 

$BEGIN_LIST
<<References>>  
$END_LIST
$BEGIN_LIST
<<responsibilities>>
$END_LIST 

<<Name>> (<<Tag>> <<ID_Number>>) 
<<Description>> 
<<History>> 
$END_SECTION

Example 2, when there are multiple projects, the syntax would be:

In Example 2, when used with multiple projects, all data from the project “Address Book” is retrieved and thereafter all data from project “ATM” is retrieved.

$MULTIPLE_PROJECT

$BEGIN_SECTION(Address Book)   
$SORT{Hierarchy}  
$INDENTION_LEVEL{3}  
$INDENTION_SIZE{.5}
$BEGIN_LIST 
<<References>>  
$END_LIST
$CALCULATE{keyword1 * keyword2 as Result}
Result: <<Result>>
$END_SECTION

$BEGIN_SECTION(Automated Teller Machine) 

$SORT{Hierarchy}  
$INDENTION_LEVEL{3}  
$INDENTION_SIZE{.5}   
$BEGIN_LIST
<<References>>    
$END_LIST   
$CALCULATE{keyword1 * keyword2 as Result2}
Result: <<Result2>>  
$END_SECTION

For representing global keywords, see the above section on “Multiple project reports”.

$END_SECTION

(Required) Marks the end of a section. Must be used with $BEGIN_SECTION.

See the example above.

$BEGIN_ROW/$END_ROW
(Optional) A command loop used to include requirement information in a table. Use with $SECTION Keywords. History, discussions, lists, and traces commands can be embedded in the $BEGIN_ROW/$END_ROW command. For more information, see Creating Tables in Document Factory section. When using the $MULTIPLE_PROJECT command, follow the $BEGIN_ROW command with input parameters, such as project and baseline names, inside a pair of parenthesis.
Note: The $BEGIN_ROW/$END_ROW command should not be used within a $BEGIN_SECTION/$END_SECTION.
Note: $END_ROW must be in the last line of the bottom-right most cell.
Example 1 shows the syntax in a table
Name Type Description
$BEGIN_ROW
$FILTER{Filter:JustCreatedFilter}
$SORT{Hierarchy}
<<Name>>
<<Type>>
<<Description>>
$END_ROW

Example 2 uses the following syntax to print requirement information from multiple projects in a table

$MULTIPLE_PROJECT
Name Type Description
$BEGIN_ROW(Address Book,Current Baseline)
$FILTER{Filter:JustCreatedFilter}
$SORT{Hierarchy}
<<Name>>
<<Type>>
<<Description>>
 $END_ROW
$REQIDS

(Optional) Specifies which requirements to retrieve using ID numbers. $REQIDS is used in conjunction with $PROJECT and $BASELINE keywords.

$PROJECT{Order Processing} 
$BASELINE{Version 1.0} 
$REQIDS{123, 345}

When used with multiple project template, the requirements will be filtered based on the first specified $REQIDS in the template. Example: $REQIDS{2, 3}

$MULTIPLE_PROJECT

$REQIDS{2, 3}
$BEGIN_SECTION(Automated Teller Machine,Current Baseline)
.................
...........
$REQIDS{4, 7}
$BEGIN_SECTION(Order Processing, Current Baseline)
<<ID_Number>>
 
$MULTIPLE_PROJECT
$REQIDS{118, 75, 225, 226}

$BEGIN_SECTION(Order Processing,Version 1.0)
<<Hierarchy>> <<Name>> <<Tag>> <<ID_Number>> <<Description>>

$END_SECTION

$BEGIN_SECTION(X100 Droid,Current Baseline)
<<Hierarchy>> <<Name>> <<Tag>> <<ID_Number>> <<Description>>

$END_SECTION

In the example shown, $REQIDS{118, 75} and $REQIDS{225, 226} will extract requirements {118, 75} on project Order Processing,Version 1.0 and {225, 226} on (X100 Droid,Current Baseline)

$REQTREE

(Optional) An alternative to the $REQIDS command. This command allows you to report on a group of requirements by simply specifying the parent requirement ID number. $REQIDS takes priority over $REQTREE and only the first occurrence of $REQTREE command specified in a template is used.

$REQTREE{214}
$BEGIN_SIGNATURES/ $END_SIGNATURES

(Optional) A command loop used to include baseline signature information. Used with signature keywords.

In Example 1, signature data will be retrieved from the project “Order Processing”.

Example 1

$PROJECT{Order Processing}
$BASELINE{Initial Requirements}
User name: <<Userid>>
Project name: <<Project>>
Project description: 
<<Project_Description>>
$BEGIN_SIGNATURES
<<First_Name>> <<Last_Name>>, <<Title>>
<<Signature_Date>> <<Meaning>> <<Comment>> $END_SIGNATURES

In Example 2, when used with multiple projects, the signature data will be retrieved from the project “Proj1” and thereafter from project “Proj2”.

Example 2, when there are multiple projects, the syntax would be:

$MULTIPLE_PROJECT

$BEGIN_SIGNATURES(Automated Teller Machine,Current Baseline)

<<First_Name>>
<<Last_Name>>,
<<Title>>
<<Signature_Date>>
<<Meaning>>
<<Comment>> 

$END_SIGNATURES


$BEGIN_SIGNATURES(Order Processing,Current Baseline) 

<<First_Name>> 
<<Last_Name>>, 
<<Title>>
<<Signature_Date>> 
<<Meaning>> 
<<Comment>>  

$END_SIGNATURES

For representing global keywords, see the above section on “Multiple project reports”.

$BEGIN_SIGN_ROW/END_SIGN_ROW

(optional) This command is used in the table. For more information, see section on “Creating eSignatures in Document Factory”.

$BEGIN_SIGN_ROW
<<Signature_Date>>
<<Signature_Time>>
<<First_Name>>
<<Last_Name>>

<<Title>>
<<Meaning>>

$END_SIGN_ROW
$FILTER{ }

(Optional ) Specifies that only data that meets the criteria specified by its arguments is included in the section.

When using a filter created from, for example, the Requirements Grid, filtering happens on the server. Filtering reduces the amount of data sent to the client machine, resulting in a faster performance for the user. Here is the step by step procedure to create and save the filter on the server and use it from within Document Factory template.

The syntax is:

$BEGIN_SECTION
$FILTER{Filter:JustCreatedFilter}
$END_SECTION

The ‘JustCreatedFilter’ can be created either using Traceability Matrix or Requirement Grid.

Start Doc Factory and specify the above filter command in the template.

An example for the JustCreatedFilter is as follows:

AND
Project Equals "Automated Teller Machine"
ID Greater Than 89

Note that criteria_name can be used instead of filter when defining the parameter so that templates prior to Caliber 11.1 are still valid.

In line filtering

When filtering requirements types by a specific user-defined attribute, use the following syntax: $FILTER{type = ‘Requirement Type’ AND (UDA LIKE ‘%KeyWord%’)}

For example:

$FILTER{Type = ‘1. Business Requirements’ AND (Owner Priority LIKE ‘%Even%’)} 

$FILTER commands are expressed as:

Expression1 compare operator Expression2 where:

Expression1 is one of the following keywords: tag, type, id_number, version, status, priority, hierarchy, or any user-defined attribute.

See the list of compare operators in the Operators section below for details

Expression2 is a keyword value expressed as: text string (expressed as ‘1. Business Requirements’), numbers (integers or float expressed as number of days = 50), dates (expressed as date = #11-22-01#), boolean (expressed as yes or no, true or false, or no quotes)

You can use wild cards in searches that use the like operator. The wild card characters are as follows: % or * (a string of characters of any length, or possibly no characters; also used to represent multiple characters), _ (one character), # (one digit), [a-g] (range of characters), [!a-g] (outside a range of characters); [%] or [ _ ] (placing a special character in brackets means to take it literally rather than giving it a special meaning)

You can combine search conditions by using the following logical operators: and (both expressions must be true to return a value), or (either condition must be true to return a value).

$BEGIN_LIST

(Optional) A command loop used with keywords to produce lists of data. It displays a comma separated sequence for <<Responsibilities>>, <<References>>, and Multiple Selection User-Defined Attributes. Data is pre-formatted. Must be used with $END_LIST.

Responsibilities:
$BEGIN_LIST
<<Responsibilities>>
$END_LIST

Note: You can format the information with bolding, underlining, etc.

$END_LIST

(Optional) Marks the end of a list. Must be used with $BEGIN_LIST.

See the example above.

$BEGIN_HISTORY

(Optional) A command loop used with history revision keywords. Allows you to format the data. Must be used with $END_HISTORY.

$BEGIN_SECTION
$SORT{Hierarchy}
$BEGIN_HISTORY
Rev#:<<Major_Version>>
	    <<Minor_Version>>
User:<<Userid>>
Name:<<User_Name>>
<<Comment>>
$BEGIN_CHANGES

Changed Field:

<<Field_Changed>>
From:<<From_Value>>
To:<<To_Value>>
$END_CHANGES
$END_HISTORY
$END_SECTION
$END_HISTORY

(Optional) Marks the end of the history revision loop. Must be used with $BEGIN_HISTORY

See the example above.

$BEGIN_CHANGES

Valid only if $BEGIN_ HISTORY/ $END_ HISTORY is used

A command loop used with history changes keywords. Allows you to format the data. Must be used with $END_CHANGES

See the example above.

$END_CHANGES

Valid only if $BEGIN_ HISTORY/ $END_ HISTORY is used.

Marks the end of the history changes loop. Must be used with $BEGIN_CHANGES.

See the example above.

$EXCLUDE_TRACES
Specifies the Project and Requirement Type sets from which traced Caliber requirements should be excluded for reporting.
Note: $EXCLUDE_TRACES can only appear in the section area and should be used before the $BEGIN_TRACES/$END_TRACES command loop.

A colon (:) is the separator between a Project name and a Requirement name. A comma (,) is the separator between projName:rtName pairs. The Project and Requirement Type names are case sensitive.

$EXCLUDE_TRACES{projName_1 : rtName_1, … projName_i : rtName_i, …}

The word ALLTYPES is reserved for all Requirement Types from a specific project. For example, $EXCLUDE_TRACES{Automated Teller Machine : ALLTYPES} is used to exclude all traced Caliber requirements from the Automated Teller Machine project.

$BEGIN_SECTION
$EXCLUDE_TRACES{Automated Teller Machine:
2. User Requirements, 
Company Standards:Human Resources}
Requirement info: <<hierarchy>> <<name>> <<tag>> <<id_number>>
$Begin_Traces(To_Traces,From_Traces,
Direct_Traces,
Requirement_Objects)
Trace Project: <<Trace_Project>>
Trace Type: <<Trace_Type>>
Trace: <<Trace_Name>> <<Trace_ReqTag>>
Direction: <<Trace_Direction>>
$END_TRACES
$END_SECTION
$BEGIN_TRACES( )

(Optional) A command loop used with the traceability and section keywords. Allows you to format the data. Must be used with $END_TRACES.

$BEGIN_TRACES/$END_TRACES takes a string of identifiers that specify the trace and object types you want to be include in the document. There are three categories of identifiers: trace direction (to or from traces), trace type (direct or implied), object type (requirements, delivery objects, Quality Center (to traces only) and SCM objects)

The option string can contain a combination of identifiers. The identifiers can be in any order and separated by any type of separator.

The trace identifiers are as follows: TO_TRACES, FROM_TRACES, DIRECT_TRACES, IMPLIED_TRACES, REQUIREMENT_OBJECTS, DELIVERY_OBJECTS, SCM_OBJECTS, ALL_OBJECTS

If no option string is supplied, Document Factory assumes the following default:

$BEGIN_TRACES (To_Traces,From_Traces, Direct_Traces, All_Objects)

The data extracted for each object is determined by the keywords used within the command.

$BEGIN_SECTION
$BEGIN_TRACES
(TO_TRACES,
FROM_TRACES,
DIRECT_TRACES, 
ALL_OBJECTS)
<<Trace_Name>>
<<Trace_Direction>>
<<Trace_Suspect>>
$END_TRACES
$END_SECTION
$END_TRACES

(Optional) Marks the end of the traceability loop. Must be used with $BEGIN_TRACES.

See the example above.

$BEGIN_DISCUSSIONS

(Optional) A command loop used to format requirement discussion data. Used with discussion keywords. Must be used with $END_DISCUSSIONS.

$BEGIN_SECTION
<<Hierarchy>><<Name>>
(<<Tag>><<ID_Number>>)
Requirement Discussions:
$BEGIN_DISCUSSIONS
Tag: <<Discussion_Req_Tag>>
Subject:<<Subject>>
From:<<From>>
Is Read: <<Is_Read>>
Date: <<Discussion_Date>>
Body: <<Body>>
$END_DISCUSSIONS
$END_SECTION
$END_DISCUSSIONS
(Optional) Marks the end of the requirement discussion loop. Must be used with $BEGIN_DISCUSSIONS.

See the example above.

$BEGIN_PROJECT_ DISCUSSIONS

(Optional) A command loop used to format project discussion data. Used with discussion keywords. Must be used with $END_PROJECT_DISCUSSIONS.

Note: The $BEGIN_PROJECT_DISCUSSIONS/$END_PROJECT_DISCUSSIONS command does not have to be used in a $BEGIN_SECTION/$END_SECTION.

In Example 1, all data will be retrieved from the project “Order Processing”.

Example 1:

$PROJECT{Order Processing}
Project Name:<<Project>>
Project Description: 
<<Project_Description>>
Project Discussions:
$BEGIN_PROJECT_DISCUSSIONS
Subject: <<Subject>>
From: <<From>>
Is Read: <<Is_Read>>
Date: <<Discussion_Date>>
Body: <<Body>>
$END_PROJECT_DISCUSSIONS

In Example 2, when used with multiple projects, all data from the project “Order Processing” is retrieved and thereafter all data from project “Automated Teller Machine” is retrieved.

Example 2, when there are multiple projects, the syntax is:

$MULTIPLE_PROJECT

$BEGIN_PROJECT_DISCUSSIONS(Order Processing,Current Baseline)
Subject: <<Subject>> 
From: <<From>> 
Is Read: <<Is_Read>>
Date: <<Discussion_Date>> 
Body: <<Body>>

$END_PROJECT_DISCUSSIONS

$BEGIN_PROJECT_DISCUSSIONS(Automated Teller Machine,Current Baseline) 
Subject: <<Subject>>  
From: <<From>>
Is Read: <<Is_Read>> 
Date: <<Discussion_Date>>  
Body: <<Body>>

$END_PROJECT_DISCUSSIONS

For representing global keywords, see the above section on “Multiple project reports”.

$END_PROJECT_ DISCUSSIONS

(Optional) Marks the end of the project discussion loop. Must be used with $BEGIN_PROJECT_DISCUSSIONS.

See the example above.

$DIFF

(Optional) Compares two baselines within a project.

$DIFF{Current Baseline-Version 1.0}
$BEGIN_GLOSSARY

(Optional) A command loop used to include glossary information. Used with glossary keywords. Must be used with $END_GLOSSARY.

Note: The $BEGIN_GLOSSARY/$END_GLOSSARY command does not have to be used in a $BEGIN_SECTION/$END_SECTION.

In Example 1, all glossary data will be retrieved from the project “Order Processing”.

Example 1

$PROJECT{Order Processing}
User name: <<Userid>>
Project name: <<Project>>
Project description: 
<<Project_Description>>
$BEGIN_GLOSSARY
Term: <<Term>>
Definition: <<Definition>>
$END_GLOSSARY

In Example 2, when used with multiple projects, all glossary data will be retrieved from the project “Order Processing” and thereafter from project “Automated Teller Machine”.

Example 2, when there are multiple projects, the syntax would be:

$MULTIPLE_PROJECT

$BEGIN_GLOSSARY(Order Processing)
Term: <<Term>> 
Definition: <<Definition>>

$END_GLOSSARY


$BEGIN_GLOSSARY(Automated Teller Machine) 
Term: <<Term>> 
Definition: <<Definition>>>

$END_GLOSSARY

For representing global keywords, see the above section on “Multiple project reports”.

$END_GLOSSARY

(Optional) Marks the end of the glossary loop. Must be used with $BEGIN_GLOSSARY.

See the example above.

$BEGIN_GLOSSARY_ROW/$END_GLOSSARY_ROW
(Optional) A command loop used to include glossary information in a table. Use with glossary keywords. When using the $MULTIPLE_PROJECT command, follow the $BEGIN_GLOSSARY_ROW command with input parameters, such as project and baseline names, inside a pair of parenthesis. For more information, see Printing Glossary Terms in the Table section.
Note: The $BEGIN_GLOSSARY_ROW/$END_GLOSSARY_ROW command should not be used within a $BEGIN_SECTION/$END_SECTION.
Note: $END_ GLOSSARY_ROW must be used in the last line of the bottom-right most cell.
$CALCULATE{ }

(Optional) Performs calculations on specified keywords.

The $CALCULATE command instructs Document Factory to perform a mathematical calculation on the specified keywords. You must format the arguments to $CALCULATE as keyword1 [*+-/] keyword2 as result. Keyword1 and keyword2 are separated by an operator (multiply [*], add [+], subtract [-], divide[/]), then the word “as” followed by the result. Result is any name that you want to use. It can then be used elsewhere in the document like a keyword to display the results of the calculation.

With multiple projects, $CALCULATE command can be used many times.

$BEGIN_SECTION
$CALCULATE{Days + Overtime 
Hours as Total_Time}
Number of Hours: <<Total_Time>>
$END_SECTION