TeamForge CLI-Working with Lists

Most TeamForge command line interface (CLI) commands return a list. This page covers the data types the CLI works with and the commands that filter, display, search, order, summarize, and iterate over those lists.

For general navigation, see Introduction and Basic Navigation. For individual command syntax, see the Command Reference.

CLI Concepts-Lists, Rows, and DOs​

The TeamForge APIs are consistent in the way they are implemented. The API returns three primary data types, Lists, Rows, and DOs. For example, the command that returns all open artifacts in a tracker returns a List object, and so does the command that returns the documents in a folder, the pages in a wiki, or the releases in a package.

When you ask for my artifacts, the CLI returns a List object, and that List object contains all the artifacts as Row objects.

A Row and a DO (data object) hold much of the same data and look similar. The difference is that a Row is a subset of what a DO contains, and a Row is read-only while a DO can be edited. When you use go to move to an object, the CLI takes you to the DO version of that object.

ctf> filter
  1) tracker : none
  2) tracker : allOpen
ctf/list(2)> 2
go filter102
tracker : allOpen
ctf/list/filter102> det
  1. _name                  == allOpen
  2. _type                  == tracker
  3. assignedTo             =>
  4. category               =>
  5. customer               =>
  6. group                  =>
  7. id                     == filter102
  8. modifiedAfter          =>
  9. modifiedBefore         =>
 10. priority               =>
 11. reportedInReleaseTitle =>
 12. resolvedInReleaseTitle =>
 13. status                 =>
 14. statusClass            => Open
 15. submittedAfter         =>
 16. submittedBefore        =>
 17. submittedBy            =>
 18. title                  =>
ctf/list/filter102> select
Saving...

Filtering​

The CLI supports saved and temporary filters. Filters in the CLI work in a similar way to the web interface.

A filter is a set of rules sent to TeamForge with requests such as getArtifactList. Filters limit the data returned to only the records that match the filter criteria. Filters support only AND operators.

For example, when you use the my artifacts command, the CLI creates a tracker filter specifying that only artifacts that are open and assigned to the current user should be returned.

Creating a Filter​

To create a filter, go to the list of filters and use the add command. This command takes two arguments, the filter type and a name you define.

ctf> filter add tracker allOpen

As of CLI 1.2, you can create the following filter types.

When an API method calls for a filter, the CLI automatically uses the currently selected filter of that type. Check the relevant methods with the describe command for details.

Once the filter is created, the CLI displays the list of filters. Select your new filter to edit it.

Editing a Filter​

The edit screen lists all the fields you can filter on. To edit a field, use the set command followed by the field name and the value you want to set.

ctf/list/filter102> set modifiedAfter last sunday at noon

Some fields, such as modifiedAfter, are relative date fields. These accept date phrases such as last sunday at noon. For example, you can specify a filter that shows artifacts that were modified after last Sunday at noon AND that have a statusClass of Open.

Filter rules are additive. They support only AND type rules, so a record must match rule 1 AND rule 2 and so on. There is no OR in a filter, and only the fields named After or Before provide relative search criteria. For more complex queries, use the CLI where command.

Using a Filter​

To use a filter, tell the CLI which filter is the currently selected filter. Use the select command in the filter edit screen.

ctf> filter allOpen select

Once selected, any call to a get List method of the same type always uses that filter. If you do not want to use a filter, make sure you have one defined with no values. By default the CLI provides a none tracker filter.

ctf> filter none select

Deleting a Filter​

To delete any object in the CLI, use the delete command at the main ctf prompt. The same command deletes anything in the CLI, including TeamForge objects.

To delete a filter you need to know its id number.

ctf> filter allOpen print id
filter112
ctf> delete filter112 YES
delete succeeded

Temporary Filters​

A tmpfilter lasts only for the duration of the current CLI session, or until the unset argument is used.

ctf> tmpfilter init tracker
ctf> tmpfilter set priority 1
ctf> go tracker1234 items

The following arguments are available.

tmpfilter init type
tmpfilter init type SoapType
tmpfilter set field value
tmpfilter unset
tmpfilter show

The CLI supports the tracker, task, user, and commit filter types.

The init command takes an optional SOAP data type. Some API methods that use filters have extended filter features. For example, TrackerApp->getArtifactList3 can use an Artifact3SoapDO based filter.

Show-Display Rows in a List​

Whenever the CLI returns a list, a number of commands and controls are available to manage the display. The show command takes arguments that limit which rows are displayed. With no arguments it defaults to the first n lines.

ctf/list(10)> show 1,5

ctf/list(10)> show +5

ctf/list(10)> show -10

When you first navigate to a list, the CLI shows the first n lines from the list as defined by pagerLines in the CLI options, and only if the showSummary option is set to 1.

ctf> options
CLI Options
ctf/cli001> details
  8. pagerLines   => 15
 11. showSummary  => 1

Use an External Pager​

For long lists you can use an external pager. Set the PAGER environment variable to the name of your preferred external pager program, and the show command sends results to that program when the list exceeds the pagerLines option value.

ctf> set PAGER more

Where-Finding Something in a List​

The where command searches list results and provides flexible search criteria. Many operators are available, including regular expressions.

ctf> my artifacts where status eq "Open"
  1) artf23456 [Open   ]: Add new filtering support
  2) artf23457 [Open   ]: enable list paging
ctf/list/list/(2)>

Because where operates on a list and returns a list, you can perform more than one where operation.

Regular Expressions​

The regular expression operator lets you create simple or complex pattern matching.

where title =~ /(Bugs|Requests)/i

In this example the title matches Bugs OR Requests. The i flag at the end performs a case insensitive match.

For more details on what you can do with regular expressions, see the Perl Regular Expressions page.

Ordering​

Change the order of any list with the order by command. It supports multi column ordering and lets you set alpha and numeric ordering types.

my artifacts
order by status, title

my artifacts
order by title asc, priority numdesc

When viewing a list, use the fields command to see which fields are available to the order by command. The following ordering types are available.

Separate field names with commas. Each column can have the order type after its name, and the types and fields can be mixed as needed.

order by title desc, priority numasc

To see the updated order, use the show command. To see other fields, use the print command.

foreach -row print id,title,status

Special Functions-sum, min, max, count, and distinct​

The function command provides basic statistics in a similar way to a spreadsheet. Each function operates on the current result list and returns the appropriate value.

ctf> my artifacts function sum actualHours
123

ctf> my artifacts function distinct status
Open
Pending
Fixing

The CLI functions for lists include the following.

To get more granular results out of the list, use the function command with the where command.

The function command takes an optional -row argument that tells it to use the data in the list instead of fetching each object from TeamForge. This is generally faster, but it does not have access to as many fields. Use the fields command in the list and in a record to see which fields are available.

A distinct list can be used with the for command. For example, you can get a distinct list of status values and, for each status, find the count of open artifacts. If this list was generated from a filter that had a submittedAfter value of last sunday, the report shows a status breakdown of all artifacts created since last Sunday.

ctf> batch
$ do
$   my artifacts
$   for STATUS function distinct status
$   do
$     where status eq "$STATUS"
$     echo "$STATUS" : `function count`
$   done
$ done
Open: 40
Pending: 12
Fixing: 3

For and Foreach-Iterating over Lists​

The for and foreach commands iterate over lists of data. The key difference is that foreach operates on lists of data returned from TeamForge, and for operates on user defined lists.

Foreach​

The foreach command runs a set of commands for each item in a list. For most lists this means it loads the full data object for the item in the row and runs the commands in the object context.

In the following example, the CLI iterates over each item in the list and runs the commands between do and done. In this case it prints a list of id numbers.

ctf/list(10)> foreach
do
  print id
done

If you only need to perform one action, use the shorter form of the command.

ctf/list(10)> foreach print id

For most lists, foreach runs a go command on each object. A list contains a number of fields but does not typically have access to the entire data object, which is why go is called. This can be expensive in time because an API call is made to fetch the data object.

If you know that the data you need exists in the list itself, foreach takes a -row argument that tells it to use the list data instead of making the extra API call.

ctf/list(10)> foreach -row print id

While -row is faster, the fields and values can differ from the actual object. When writing reports, examine the differences to see whether you can use -row or whether you need the full data object.

ctf> go tracker1234 items foreach -row print id,status,title

ctf> my artifacts
ctf/list(91)> row 1 export -header
ctf/list(91)> foreach -row export

For​

The for command operates on a user defined list. In the following examples the values are hard coded.

ctf> for ITEM in 1,2,3,4
do
  echo
done

ctf> for ITEM in 1-20
do
  echo
done

You can also use CLI variables and iterate over the results of other CLI commands. The -e argument tells the for command to run the following code as CLI commands and process the results.

ctf> for FILE in -e shell ls
do
  go rel1234 upload
done

The above example gets a list of files from the local file system and uploads each one to a file release. For example, the distinct argument to the function command returns a list of values.

ctf> go tracker1234 items
ctf/list(20)> for STATUS in -e function distinct status
do
  where status eq "$STATUS"
  echo "$STATUS", `function count`
done

In this example, for iterates over the list of all status values in the artifact list and generates a count of the number of artifacts in each status.