Task: Set Up Automated Annotation Mirroring

If you are wish to periodically synchronize warning annotations between different hubs, you may find it useful to automate the mirroring steps.

Overview

Suppose we want to mirror the annotations from the hub at http://sourcehub:7340 to the hub at http://desthub:7340.

There are two steps:

Step A Set up sessions and get bearer tokens.
We will use these bearer tokens for authentication in Step B.
Step B Set up mirroring script.
Create a script to perform the mirroring operations, then arrange for the script to be run automatically.

Preliminaries

Before you start:

  1. Ensure that you have hub user accounts on both hubs, and that both accounts have G_ANNOTATION_IMPORT and G_ANNOTATION_EXPORT permissions.
  2. Choose the machine where you want to set up your mirroring script. The remainder of these instructions will refer to this machine as mirrormach.

Step A: Set up sessions and get bearer tokens

We will use bearer authentication for the hub operations in this task.

If you do not already have a suitable session and bearer token for each hub, generate them now:

  1. Open the CodeSonar web GUI for the source hub: http://sourcehub:7340.
  2. Sign in as a user with G_ANNOTATION_IMPORT and G_ANNOTATION_EXPORT permissions.
  3. Click the Settings icon Settings icon in the page header to view the Settings page.
  4. Click Manage My Sessions in the Account tab.
    Your User Sessions page will open.
  5. Use the Create Session form to create a new session with a suitably long Expires setting.
    When you click Create Session, the page will be reloaded and the Bearer Token for your new session will be displayed at the top of the page.
    IMPORTANT: Make a note of the Bearer Token now. Once you refresh or navigate away from this page there will be no further opportunity to view the token.
  6. Save the source hub bearer token to a file that is visible from mirrormach. The remainder of these instructions will refer to this file as srcbearerfile.
  7. Open the CodeSonar web GUI for the destination hub: http://desthub:7340.
  8. Repeat steps 2-5 to create a suitable session on the destination hub.
  9. Save the destination hub bearer token to a file that is visible from mirrormach. The remainder of these instructions will refer to this file as destbearerfile.

Step B: Set up mirroring script

The process for setting up the mirroring script differs slightly between systems because of different scripting syntax and system tools.

Set up mirroring script: *ix Systems

  1. Determine a suitable working directory on mirrormach. In the next step, we will refer to this directory as /path/to/workingdir.
  2. Create a shell script csonar_push.sh with the following contents.
    # /bin/sh
cd /path/to/workingdir
SRC_TOKEN=$(cat $2)
DST_TOKEN=$(cat $4)
curl -H "Authorization: Bearer ${SRC_TOKEN}" $1/annotations.csv  > anno.csv || exit $?
curl -H "Authorization: Bearer ${DST_TOKEN}" $3/import_annotations/ -F 'file=@anno.csv' > response.html
    By default, any annotation merge conflicts will be resolved by using the existing values on the destination hub.
  3. Test the script by invoking it:
    ./csonar_push.sh http://sourcehub:7340 path/to/srcbearerfile http://desthub:7340 path/to/destbearerfile
    where
    http://sourcehub:7340 is the location of the source hub (the hub we are copying annotations from.
    http://desthub:7340 is the location of the destination hub (the hub we are copying annotations to).
    path/to/srcbearerfile is the path to the file where you saved your bearer token for the source hub.
    path/to/destbearerfile is the path to the file where you saved your bearer token for the destination hub.
  4. Use your system tools to arrange for the script to be run automatically. For example, suppose you want to use mirror annotations between two hubs:
    Hub location Bearer token stored in file
    http://red:7340 /mytokens/redtoken
    https://blue:7340 /mytokens/bluetoken
    If you are using cron, add the following two lines to your crontab to run at 2:05am every day. 
    5 2 * * * /path/to/csonar_push.sh http://red:7340 /mytokens/redtoken https://blue:7340 /mytokens/bluetoken
5 2 * * * /path/to/csonar_push.sh https://blue:7340 /mytokens/bluetoken http://red:7340 /mytokens/redtoken

Set up mirroring script: Windows Systems

  1. Determine a suitable working directory on mirrormach. In the next step, we will refer to this directory as path\to\workingdir
  2. Create a batch file csonar_push.bat with the following contents. 
    set workdir=path\to\workingdir
cd /D %workdir%
set /p SRC_TOKEN=<"%2"
set /p DST_TOKEN=<"%4"
curl -H "Authorization: Bearer %SRC_TOKEN%" %1/annotations.csv > anno.csv || exit $?
curl -H "Authorization: Bearer %DST_TOKEN%" %3/import_annotations/ -F "file=@anno.csv" > response.html
    By default, any annotation merge conflicts will be resolved by using the existing values on the destination hub.
  3. Test the script by invoking it:
    csonar_push.bat http://sourcehub:7340 path/to/srcbearerfile http://desthub:7340 path/to/destbearerfile
    where
    http://sourcehub:7340 is the location of the source hub (the hub we are copying annotations from.
    http://desthub:7340 is the location of the destination hub (the hub we are copying annotations to).
    path/to/srcbearerfile is the path to the file where you saved your bearer token for the source hub.
    path/to/destbearerfile is the path to the file where you saved your bearer token for the destination hub.
  4. Use your system tools to arrange for the script to be run automatically. For example, you may choose to use the Windows Task Scheduler.

Links