HowToIntegrateWithSVN

Plandora, SVN and rastreability matrix

Each Plandora entity (task, requirement, risk, etc) could contain a relationship with a configuration item of the project repository. This kind of link is very usefull to obtain information such as, which itens of repository were affected by which task or requirement.

Plandora addresses this feature through the Relationship Grid. There are two ways to make the link with a repository item:

(a) in active mode, the user with "project resource" profile, uses the Navigation Popup and chooses the repository items that make sense to him. Important: only the project leaders are able to define which resources will receive permission to perform this action. Users with "customer" profile are not allowed to perform this action at all.

(b) in passive mode, the link between a repository item and a Plandora entity will show up after the "commit" event by the repository.

Passive mode

The Plandora tool exposes a servlet that could be requested by repositories engines for integration purposes.

This servlet must be accessed by the URI:

    http://[my_server]:[my_port]/pandora/do/connectorListener

Each post that is sent to Plandora will be interpretated such as a "commit permission" and must be dispatched by repository during the "pre-commit" event:

Plandora expects a request message similar to the example bellow.

   <?xml version='1.0' encoding='UTF-8'?>
   <MSG PROJ_ID='my_plandora_project_id'>
      <REPOS>
         <![CDATA[12345]]>
      </REPOS>"
      <FILES>
         <![CDATA[ commit files list in svn format ]]>
      </FILES>
      <LOG>
         <![CDATA[commit message written by commiter]]>
      </LOG>
      <AUTHOR>
         <![CDATA[commiter author username]]>
      </AUTHOR>
   </MSG>

After the request, Plandora will check if the body of message is according to the policies defined by project leader into the Project Form.

In the end, Plandora replies with content successfully like the example bellow:

    <RESPONSE STATUS="0" MSG="OK" \>

...or with a error message like the example bellow:

    <MSG RESPONSE="1010" CONTENT="The commit description is mandatory."/>

SVN Configuration

At passive mode, the repository server must send a message to Plandora requesting permission to commit. Then, it is necessary to perform some setup arrangements at SVN.

Each SVN project contain a folder called hooks/. This folder contain a number of script files that corresponding to an event of SVN. For Plandora integration purposes, only pre-commit file must be changed.

The example bellow, describes the content of pre-commit file that was used by Plandora team during the tests of SVN integration. Maybe, you prefer to change something. It's up to you. ;-)

Before using the script, replace the strings: MY_PLANDORA_PROJ_ID, MY_SVN_PATH, MY_SERVER, MY_PORT with values that make sense to you.

    #!/bin/sh
    # PRE-COMMIT HOOK
    #
    # The pre-commit hook is invoked before a Subversion txn is
    # committed.  Subversion runs this hook by invoking a program
    # (script, executable, binary, etc.) named 'pre-commit' (for which
    # this file is a template), with the following ordered arguments:
    #
    #   [1] REPOS-PATH   (the path to this repository)
    #   [2] TXN-NAME     (the name of the txn about to be committed)
    #
    #   [STDIN] LOCK-TOKENS ** the lock tokens are passed via STDIN.
    #
    #   If STDIN contains the line "LOCK-TOKENS:\n" (the "\n" denotes a
    #   single newline), the lines following it are the lock tokens for
    #   this commit.  The end of the list is marked by a line containing
    #   only a newline character.
    #
    #   Each lock token line consists of a URI-escaped path, followed
    #   by the separator character '|', followed by the lock token string,
    #   followed by a newline.
    #
    # The default working directory for the invocation is undefined, so
    # the program should set one explicitly if it cares.
    #
    # If the hook program exits with success, the txn is committed; but
    # if it exits with failure (non-zero), the txn is aborted, no commit
    # takes place, and STDERR is returned to the client.   The hook
    # program can use the 'svnlook' utility to help it examine the txn.
    #
    # On a Unix system, the normal procedure is to have 'pre-commit'
    # invoke other programs to do the real work, though it may do the
    # work itself too.
    #
    #   ***  NOTE: THE HOOK PROGRAM MUST NOT MODIFY THE TXN, EXCEPT  ***
    #   ***  FOR REVISION PROPERTIES (like svn:log or svn:author).   ***
    #
    #   This is why we recommend using the read-only 'svnlook' utility.
    #   In the future, Subversion may enforce the rule that pre-commit
    #   hooks should not modify the versioned data in txns, or else come
    #   up with a mechanism to make it safe to do so (by informing the
    #   committing client of the changes).  However, right now neither
    #   mechanism is implemented, so hook writers just have to be careful.
    #
    # Note that 'pre-commit' must be executable by the user(s) who will
    # invoke it (typically the user httpd runs as), and that user must
    # have filesystem-level permission to access the repository.
    #
    # On a Windows system, you should name the hook program
    # 'pre-commit.bat' or 'pre-commit.exe',
    # but the basic idea is the same.
    #
    # The hook program typically does not inherit the environment of
    # its parent process.  For example, a common problem is for the
    # PATH environment variable to not be set to its usual value, so
    # that subprograms fail to launch unless invoked via absolute path.
    # If you're having unexpected problems with a hook program, the
    # culprit may be unusual (or missing) environment variables.
    # 
    # Here is an example hook script, for a Unix /bin/sh interpreter.
    # For more examples and pre-written hooks, see those in
    # the Subversion repository at
    # http://svn.collab.net/repos/svn/trunk/tools/hook-scripts/ and
    # http://svn.collab.net/repos/svn/trunk/contrib/hook-scripts/
    REPOS="$1"
    TXN="$2"
    respStatus=1
    # Make sure that the log message contains some text.
    SVNLOOK=/usr/local/bin/svnlook
    # generate the request xml message
    sn1="<?xml version='1.0' encoding='UTF-8'?><MSG PROJ_ID='MY_PLANDORA_PROJ_ID'>";
    sn2="<![CDATA["
    sn3="]]>"
    sn4="<REPOS>"
    sn5="</REPOS>"
    sn6="<FILES>"
    sn7="</FILES>"
    sn8="<LOG>"
    sn9="</LOG>"
    sn10="<AUTHOR>"
    sn11="</AUTHOR></MSG>"
    # get some information from SVN commit session
    filelst=`$SVNLOOK changed -t "$TXN" "$REPOS"`
    msglog=`$SVNLOOK log -t "$TXN" "$REPOS"`
    AUTHOR=`"$SVNLOOK" author -t "$TXN" "$REPOS"`
    respfile="/MY_SVN_PATH/hooks/resp_plandora.txt"
    # send the post to Plandora server
    curl -X POST -H 'Content-type: text/xml' -s -d \
       "$sn1$sn4$sn2$REPOS$sn3$sn5$sn6$sn2$filelst$sn3$sn7 \
        $sn8$sn2$msglog$sn3$sn9$sn10$sn2$AUTHOR$sn3$sn11" \
       http://MY_SERVER:MY_PORT/pandora/do/connectorListener >&1 >$respfile
    # checks if commit must be allowed.
    respExists=0
    [ -f $respfile ] && respExists=1 || respExists=0
    if [ $respExists = 1 ]
    then
      respFileContent=`cat $respfile`
      expectedContent="<RESPONSE STATUS=\"0\" MSG=\"OK\"></RESPONSE>";
      if [ "$respFileContent" == "$expectedContent" ]
      then
         respStatus=0
      else
         respStatus=2
      fi
    else
      respStatus=3
    fi
    # display the response from Plandora server
    cat $respfile >&2
    echo $respStatus >&2
    rm $respfile
    exit $respStatus