Skip to main content

TeamForge CLI Cookbook

This page collects sample Digital.ai TeamForge command line interface (CLI) report scripts. Each one can be saved to a file and passed to the CLI as a command line argument, which makes the reports easy to run as many times as needed.

For the commands used in these scripts, see the Command Reference and Working with Lists.

General Guidelines​

This section covers how to save a report script and the two lines worth adding to the start of every script.

Creating a Report Script​

Open an editor of your choice. On Windows, WordPad is a better choice than Notepad. Copy the report script from this page into a new document and save it as a text file. Then, at a command line, run your report using the following syntax.

Linux

ctf --script /pathto/yourfile.txt

Windows

ctf.exe --script c:\directory\myfile.txt

Extra Attributes​

When these reports run, they often generate additional information that you may not want to see while the report runs. To hide that output, put the following line at the start of your report script.

silent

The version check makes sure that your script runs on the right version of the CLI.

versioncheck 1.1

Project Reports​

This section contains a report that runs across every project on the site.

Get a List of All Project Members​

api CollabNet->getProjectList 1
foreach
do
  copy as project
  ctf api CollabNet->getProjectMemberList $project.id
  foreach
  do
    print "$project.title",username,email
  done
done

Tracker Reports​

This section contains reports that summarize tracker artifacts by priority and by modification date.

Open Artifact Summary in My Projects by Priority​

my projects foreach
do
  print title
  ctf api TrackerApp->getTrackerList `print id`
    foreach
    do
      print as "  %s" title
      items
      for ITEM function -row distinct priority
      do
        where priority == "$ITEM"
        echo as "    Priority $ITEM: %3.0f" `function count`
      done
    done
done

Open Artifacts Modified This Week​

For this report you need to create a tracker filter and set two rules.

The CLI lets you set relative dates for date fields. In this example the phrase last sunday is changed to the actual date at the time the filter is used. This way you can leave the filter alone, reuse it every week, and get results that are appropriate for that week.

In this report, an API call gets all artifacts site-wide that match the rules of the tmpfilter. The undef argument tells the API to leave the first argument (containerId) as undefined, which stops the call from being limited to any tracker or project.

tmpfilter init tracker
tmpfilter set statusClass Open
tmpfilter set modifiedAfter last sunday

set FORMAT %-11.11s %-35.35s %-15.15s %s
echo Artifacts Modified This Week.  Report Date `date`
echo
echo as "  $FORMAT" Artifact ID, Title, Status, Assigned To
api TrackerApp->getArtifactList undef
  foreach -row
  do
    print as "  $FORMAT" id,title,status,assignedToFullname
  done

SCM Reports​

This section contains a report that lists source code repositories across your projects.

List All of the Repositories in Each of My Projects​

my projects foreach
do
  ctf set TITLE `print id,title`
  ctf api ScmApp->getRepositoryList `print id`
  foreach
  do
    print $TITLE,repositoryDirectory
  done
done

Using Templates​

This section shows how the CLI populates an HTML template with data collected from TeamForge and posts the result back to a page component.

Creating a Line Graph​

This example creates a line graph mashup using a Google line graph widget. The CLI collects data from TeamForge, populates an HTML template with the results, and then posts that template to a text page component in a TeamForge project.

Copy the following HTML snippet to a file called graph.html.

<div id="chart_div" style="width: 700px; height: 240px;"></div>

<script type="text/javascript" src="https://www.google.com/jsapi"></script>
<script type="text/javascript"><!--
  google.load('visualization', '1', {'packages':['annotatedtimeline']});
  // google.setOnLoadCallback(drawChart);
  function drawChart() {
    var data = new google.visualization.DataTable();
    data.addColumn('date', 'Date');
    data.addColumn('number', 'Closure Rate in Days');
    data.addColumn('string', 'title1');
    data.addColumn('string', 'text1');
    data.addRows([
[:START ROW:]    [new Date([:var:YEAR:], [:var:MONTH:], [:var:DOM:]), [:var:DAYS:], undefined, undefined],
[:END ROW:]
    ]);

    var chart = new google.visualization.AnnotatedTimeLine(document.getElementById('chart_div'));
    chart.draw(data, {displayAnnotations: true});
  }
// --></script>
<script type="text/javascript"><!--
  drawChart();
// --></script>

In the template above, ROW is replaced with the lines generated by the CLI representing each point on the line graph.

The following CLI script collects the data from a specified tracker and places the resulting HTML graph into a TeamForge page component.

To use this script you need to create an HTML or text page component to save the chart on. Toward the end of the script is a sample component id, pagec2580. Replace that id with the one you created. About halfway through the script is where it connects to a tracker. The sample id there is tracker1305. Replace that id with the one for the tracker you want the report for.

# check the CLI version and run silent.
versioncheck 1.1
silent

# Open a temporary file and load the graph.html template
output -tmp
template load graph.html
template header

# Make a tmpfilter and set the needed filter values
tmpfilter init tracker
tmpfilter set statusClass Close

for WEEK in 12-0
do

  ctf set TOTAL   0
  ctf set COUNTER 0

  ctf tmpfilter set modifiedAfter  sunday `expr $WEEK + 1 ` weeks ago
  ctf tmpfilter set modifiedBefore saturday $WEEK weeks ago

  ctf api TrackerApp->getArtifactList tracker1305
  foreach -row
  do
    # Get the date in seconds to make the math easier.
    ctf set -e END     date as "%s" `print closeDate`
    ctf set -e START   date as "%s" `print submittedDate`
    ctf set -e TOTAL   expr $TOTAL + ( $END - $START )
    ctf set -e COUNTER expr $COUNTER + 1
  done

  # Calculate the rate
  ctf set -e RATE  expr $TOTAL / $COUNTER
  ctf set -e HOURS expr int( $RATE  / 3600 )
  ctf set -e DAYS  expr int( $HOURS / 24 )

  # Get the separate date bits
  ctf set -e YEAR  date as "%Y" saturday $WEEK weeks ago
  ctf set -e DOM   date as "%e" saturday $WEEK weeks ago
  ctf set -e MONTH date as "%f" saturday $WEEK weeks ago

  # The google chart expects the month to be base 0 ( 0 = January )
  ctf set -e MONTH expr $MONTH - 1

  template row

done

template footer
output

# Load the content into TeamForge
load DATA $TMPFILE
api PageApp->setTextComponentContent pagec2580, $DATA