Posting Reports on an Intranet

From Seapine Labs

This article includes information for how Surround SCM reports can be automated and posted on an intranet for employees to view the detailed history of files and also changes to files within the last 30 days.

This is a simple example that could be expanded with more complex reports and a more complex script file.

Contents 1 Background 2 About the Environment 3 About the Reports 4 About the Batch File 4.1 The RunReport CLI Command 5 Creating a Dashboard/Interface 6 Enhancements/Extensions

[edit] Background

The Surround SCM CLI allows you to run any of the reports created using the client under Tools > Reports.

The reports are created in HTML format and you can specify the location of where to save the file. This allows you to post these files anywhere on your network, including a folder mapped on your intranet web server (provided the process has access to that folder).

This example shows how you can create a batch file using the CLI to run these reports. You can then use the Operating System's scheduling tools to run the batch file during off-hours. It is important that this is run at a time where there is minimal or no usage of the Surround SCM database. Depending on the detail and scope of the report, the database may be momentarily locked with a read cache lock, which would prevent any write action to the database.

This example also includes a basic index file that has links to the various reports created by the batch file.

[edit] About the Environment

This example uses a database that is also used for the online demonstrationof Surround SCM. This database uses the branch-by-purpose model. In this branching model, all new feature development takes place on the mainline branch, while maintenance development for existing releases takes place on the child baseline branches.

A repository is created for each software product on the mainline branch. Each maintenance branch is branched off the repository for the specific product. For a detailed explanation of this and other branch models, review the Surround SCM Branching Strategies article on this wiki.

For this example, I created reports for the WysiCM product.

Figure 1 illustrates the repository structure under the mainline branch:

Figure 2 illustrates the branch structure used:

This example runs reports on the mainline branch and on the maintenance branch for WysiCM version 1.

[edit] About the Reports

The reports must first be created using the Surround SCM native GUI client. I have four reports:

1) Mainline Branch (WysiCorp, Inc.): Detailed history report, Changes in last 30 days report

2) Maintenance Branch (WysiCM 1.x): Detailed history report, Changes in last 30 days report

• To create the detailed history report, select the branch and repository, select the recursive check box, and then select all actions performed by all users. The report summary for the mainline branch is as follows:

Report on files [Administrator, cremerf, jbarber] have performed [Add, Add to branch, Add from branch, Check in, Rebase, Rebase with merge, Label, Attach to TestTrack, Remove, Restore, Promote to, Promote from with merge, Promote from, Share created, Share broken, Rename, Destroy, Rollback Rebase, Rollback Promote, Rollback File, Change custom field, Change state] where date [is] [all dates] and in branch [WysiCorp, Inc.] and repository [WysiCorp, Inc./WysiCM] [recursively]

• To create a report that shows changes in the last 30 days, select the branch and repository, select the recursive check box, then select change actions performed by all users. Also filter by dates "in the last 30 days". The report summary for the mainline branch is as follows:

Report on files [Administrator, cremerf, jbarber] have performed [Add, Check in, Rebase, Rebase with merge, Remove, Promote from with merge, Promote from, Rollback Rebase, Rollback Promote, Rollback File] where date [is] in the last [30] [days] and in branch [WysiCorp, Inc.] and repository [WysiCorp, Inc./WysiCM] [recursively]

[edit] About the Batch File

Now that the report are defined, you need to create the batch file to run the reports.

[edit] The RunReport CLI Command

First, let's take a look at the command that will be used by the batch file. By typing "sscm rr -h" on a terminal window (command prompt), we get the help on the command, which should look something like this:

Syntax:
sscm runreport ReportID [-oOutputFile] [-bBranch] [-pRepository] [-h]
 [-y[Username:Password|+]] [-zSCMServerAddr:PortNum] [+u]

Shortcut command: rr

Description:
Run a report.

ReportID:   The ID of the saved report.
-b:   Branch to report on.
      If not specified, the default working directory branch is used.
-p:   Full path to the repository to report on.
      If not specified, the default working directory repository is used.
-o:   File to send output to.
      All output is written to this file instead of displayed on the screen.
-h:   Display online help for this command.
-y:   Surround SCM username and password. Use + to use single sign-on.
-z:   Surround SCM server address and port number.
+u:   Display output in Unicode (Windows only). The output cannot be sent to
      a file. If output is enabled for all commands, enter +u- to
      disable for this command.

To get the ID of the report, you have to run another CLI command, lsreport. Running the lsreport command lists the four reports that were created (report output was reformatted for display purposes):

 ID      Report Name                       Type         Branch                Repository                Public?      Owner  

---      ------------                      -------      ----------------      --------------------      -------      -------

  1 WysiCM detailed history                History      WysiCorp, Inc.       WysiCorp, Inc./WysiCM       public  Administrator

  2 Wysi CM Changes in Last 30 days        History      WysiCorp, Inc.       WysiCorp, Inc./WysiCM       public  Administrator

  3 WysiCM 1.x detailed history            History      WysiCM 1.x           WysiCorp, Inc./WysiCM       public  Administrator

  4 WysiCM 1.x Changes in Last 30 Days     History      WysiCM 1.x           WysiCorp, Inc./WysiCM       public  Administrator

Because I have already indicated which branch and repository to report on for each report, the RunReport command does not need this information (-b and -p switches).

The command will not overwrite a file if it exists. This means some logic needs to be added to account for this. DOS offers a way to check if a file exists, and the GOTO command allows us to indicate what to do.

Following is the entire batch file that generates four reports:

REM wysiCM New Feature Development detailed history report section-------------------------------------------------

IF NOT EXIST "C:\Inetpub\wwwroot\scmreports\wysicmnewscmdetailreport.htm" GOTO RUNwYSICMNEWDETREPORT

DEL "C:\Inetpub\wwwroot\wysicmnewscmdetailreport.htm"
GOTO RUNwYSICMNEWDETREPORT

:RUNwYSICMNEWDETREPORT
sscm rr 1 -o"C:\Inetpub\wwwroot\scmreports\wysicmnewscmdetailreport.htm" -yAdministrator: -z127.0.0.1:4900


REM WysiCM New Feature Development changes in 30 days report---------------------------------------

IF NOT EXIST "C:\Inetpub\wwwroot\scmreports\wysicm30newscmchangereport.htm" GOTO RUNWYSICM30NEWCHNGREPORT

DEL "C:\Inetpub\wwwroot\wysicm30newscmchangereport.htm"
GOTO RUNWYSICM30NEWCHNGREPORT

:RUNWYSICM30NEWCHNGREPORT

sscm rr 2 -o"C:\Inetpub\wwwroot\scmreports\wysicm30newscmchangereport.htm" -yAdministrator: -z127.0.0.1:4900


REM wysiCM 1.x detail history report section-------------------------------------------------

IF NOT EXIST "C:\Inetpub\wwwroot\scmreports\wysicm1xscmdetailreport.htm" GOTO RUNwYSICM1XDETREPORT

DEL "C:\Inetpub\wwwroot\wysicm1xscmdetailreport.htm"
RUNwYSICM1XDETREPORT

:RUNwYSICM1XDETREPORT
sscm rr 3 -o"C:\Inetpub\wwwroot\scmreports\wysicm1xscmdetailreport.htm" -yAdministrator: -z127.0.0.1:4900


REM WysiCM 1.x Development changes in 30 days report---------------------------------------

IF NOT EXIST "C:\Inetpub\wwwroot\scmreports\wysicm301xscmchangereport.htm" GOTO RUNWYSICM30NEWCHNGREPORT

DEL "C:\Inetpub\wwwroot\scmchangereport.htm"
RUNWYSICM30NEWCHNGREPORT

:RUNWYSICM30NEWCHNGREPORT

sscm rr 4 -o"C:\Inetpub\wwwroot\scmreports\wysicm301xscmchangereport.htm" -yAdministrator: -z127.0.0.1:4900

Note that in the batch file, the reports are published to the 'wwwroot' folder on my local computer. You could easily change that to a network share that points to the 'wwwroot' or 'htdocs' folder on your intranet web server. Remember you need to make sure the process that runs the batch file has access and permissions to delete and create a new file on this share. One way to check this is by the user account that the process will use. With Windows scheduling, for example, you must indicate which user account will be used to run the task. Make sure this account has the nescessary access and permissions.

[edit] Creating a Dashboard/Interface

In order for users not to have to keep track of various links, you should create a Web page that includes links to the reports.

Figure 3 illustrates a simple dashboard created to access the four reports:

As you can see, the HTML code is minimal:

<?xml version=“1.0” charset=“iso-8859-1” ?>
<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN'
'http://www.w3.org/TR/xhtml1/DTD/strict.dtd' >

<html>
   <head>
      <title>Surround SCM Reports Dashboard</title>
   </head>
   <body>
        <div align ="center"><img src='Logo.JPG' height= '100' width= '324' class="img" alt="logo"/></div>
        <div align ="center">



== Enhancements/Extensions ==

In this example, the HTML pages for the reports can not be modified.  The current reporting engine does not offer a way to change the title, style, etc... of the page.

However, a simple program could be written instead of the above batch file.  After it runs the runreport command, it could conceivably open the html file and make modifications automatically.

This would avoid the need of having someone manually edit the HTML pages every time a new report is generated and it would make the report match the company's branding.

Another option is to change the output of the report to a comma delimited or tab delimited text file.  An application could then read in the contents and dynamically create the reports with custom format.
[[Category:Surround SCM]]

<h1>WYSICM 1.x Reports</h1></div>
        <div align ="center"><a href='wysicm1xscmdetailreport.htm'>Detailed History Report</a></div><br/>
        <div align ="center"><a href='wysicm301xscmchangereport.htm'>Change in Last 30 Days</a></div>

   </body>
</html>

[edit] Enhancements/Extensions

In this example, the HTML pages for the reports can not be modified. The current reporting engine does not offer a way to change the title, style, etc... of the page.

However, a simple program could be written instead of the above batch file. After it runs the runreport command, it could conceivably open the html file and make modifications automatically.

This would avoid the need of having someone manually edit the HTML pages every time a new report is generated and it would make the report match the company's branding.