Kwxsync

The kwxsync command synchronizes issue status updates and comments, along with the ID of the user who made the changes, among projects that you specify. All of the updates are merged, so that identical issues in multiple projects have an identical history.

This is useful when projects share source code, as in the case of branches. Developers need to cite detected issues only once for each source file; kwxsync can then apply their changes to other projects that contain the same source file. You can also use the --storage option to run kwxsync incrementally; for more information, see the example below.

Note: We do not recommend using the --storage and --last-sync options together, as it may result in citing not synchronizing as expected.

The projects can be in different projects_root directories, as well as on different servers. A server is defined as a distinct combination of a machine name and a port number.

If you are using Working with streams, you can run kwxsync between an individual project and a base project in order to sync your defect citing, which syncs all the defects of the base project's streams as well.

Prerequisites

If an access control method has been configured (Basic, LDAP or NIS), the user performing cross-project synchronization (or 'xsync') needs to ensure the following:
  • Each server needs a user with the 'Perform cross-project synchronization' permission. By default, Project root admins and project admins are given this permission. This is a project root level permission; therefore, it is not assignable on the project level.
  • For every server to which kwxsync connects and that has an access control method enabled, an entry that specifes a 'machine:port:user:token' combination, (for example, jsmith2.klocwork.com;8080;jsmith;e46db6b8582a), is required in the 'ltoken' file on the machine that is running kwxsync. To generate an entry in this file for a given machine or machines, the user must run kwauth for each relevant server and log in with the account that contains the proper permission; kwauth then stores and updates a token in the user's home directory.
  • The user that connects is the user whose role memberships, under certain conditions, will be tested. We recommend that you configure a special role that contains the 'Perform cross-project synchronization' permission only.

When you attempt to perform the synchronization, kwxsync proceeds only if the user has the permissions to do so on each of the specified machines. If the user does not have the proper permissions, the system will log a list of each of the machines on which it did not pass along with the user name that did not have the proper permissions, and the kwxsync process will exit.

When connecting to a machine that does not have an access control method in place, and where there is no entry for the target machine in the ltoken file, the name of the user that is logged into the machine that is running kwxsync will be used. Each project referenced in the kwxsync command-line has either an explicit URL (http://jsmith:8080/project_A) or an implicit URL (project_B). If a project has an implicit URL, its server and port are assumed to be the same server and port specified by the value of the --url parameter.

See Synchronizing status changes and comments across projects for how-to information.

Resolving status conflicts by using a status priority file

Between synchronizations, it is possible for multiple users to set different statuses on a single defect. This is more common in organizations that synchronize many projects and have a large number of users, but it can occur in any organization. Klocwork enables organizations to elegantly resolve status conflicts during synchronization by referencing a status priority file. Normally, during synchronization, the system uses the timestamps of each comment and status change to create a shared chronological history among the projects. The status with the most recent timestamp is the status applied across all projects. When you use the status priority option, if an issue has had multiple statuses set since the last synchronization, the system compares each of the statuses with the priorities specified in the file and if needed, applies the highest priority to the issue. Here's how it works:

  1. A system administrator creates a status priority file that defines a numbered, or ranked, list of all issue statuses. This is the file that the system will use to resolve conflicts.
  2. The build process or a system administrator runs the kwxsync command and includes the --status-priority file option. This command points to the location of the status priority file.
  3. On a per-project basis, the system merges the status histories into a common history. If multiple statuses were applied to an issue after the last synchronization, the system logs each status and any associated comments based on their timestamps.
  4. The system validates whether the last status applied has the highest priority as defined in the status priority file.
  5. If the last status applied has the highest priority, the system does nothing. If the last status applied is lower than one of the other statuses it is resolving, the system changes the status of the issue so that the issue is tagged with the highest priority. The system then generates another entry and inserts it into the timeline. The timestamp of the system-generated entry is the timestamp of the previous status plus one second.
  6. The system merges subsequent projects in the same manner until all projects are synchronized.
Format of the status priority file

Within the status priority file, the lowest priority issue status has the lowest number and the highest priority issue status has the highest number. The status priority file must be a UTF-8 text file that

  • contains no spaces or comments
  • contains the name of the status in all-caps, followed by the equals sign and then the number, one status on each line
  • assigns a unique number to each issue status, from 1 to 8

For example, if you create a file that contains the following syntax, the system will apply Fix as the final status when resolving a conflict with any other status:

FIX=8
FIX_IN_LATER_RELEASE=7
FIX_IN_NEXT_RELEASE=6
DEFER=5
FILTER=4
IGNORE=3
NOT_A_PROBLEM=2
ANALYZE=1

The following image shows the status history of an issue that was updated from "Defer" to "Fix" by kwxsync. Each time the system changes an issue status, it adds an entry to the history that includes "<kwxsync>" so that it is clear that the system changed the status during synchronization.

Image:kwxsync-priorityfile.png

Usage

kwxsync [<options>] <project_name_1>|<project_URL_1> <project_name_2>|<project_URL_2> [...]

where <options> are any of the options from the table below

Specify a space-separated list of projects that you want to synchronize. All of the updates in all of the projects you specify will be merged, so that identical issues in all projects will have an identical history.

You can specify project names or project URLs. The project URL has the following format: http(s)://<klocwork_server_host>:<klocwork_server_port>/<project>

Use https:// if a secure Klocwork Server connection has been configured.

Example 1: Synchronizing projects on the same server

kwxsync Project1 Project2 --last-sync "03-04-2015 18:31:00"

In this example, only two projects are specified. The projects share a Klocwork Server that is running on the default host and port (localhost:8080), so we only need to specify the project names. kwxsync will find all issue status updates and comments applied since April 3, 2015 at 6:31 p.m. in Project1, and copy them to Project2; it will also do the same from Project 2 to Project 1.

Example 2: Synchronizing projects on multiple servers

kwxsync http://server01.acme.com:8080/Project1 http://server01.acme.com:8080/Project2 http://serverxyz.acme.com:8080/Project3 

In this example, we want to synchronize three projects, located on two Klocwork Servers. The easiest way to specify these projects is with the project URL, which clearly identifies the host, port and project name for each. kwxsync synchronizes the three projects, so that all identical issues in the projects share the same history. To perform the synchronization when authentication is enabled, the user running the command must be authenticated on all affected servers and must have the 'Perform cross-project synchronization' permission. The person executing the kwxsync command must have a local ltoken file which contains the authentication data for each affected server. To gain proper authentication, the user must run kwauth for each relevant server; kwauth then stores a token in the user's home directory.

Example 3: Using the --storage option to synchronize projects incrementally

kwxsync --storage my_storage_file http://host:8080/zlib http://host:8080/zlib2 http://host2:8082/zlib

In this example, you specify a file in which to persistently store synchronization information as well as synchronizing three projects. The first time you run the command, the system will synchronize the history of all issue status updates and comments, along with the ID of the user who made the changes. When you run the command subsequently, only the most recent set of status updates and comments are synchronized, which saves a substantial amount of time. By using the --storage option, you can run the tool frequently and ensure that each developer sees an up-to-date list of issues.

Example 4: Using the --status-priority option to resolve status conflicts during synchronization

kwxsync --status-priority status-priority-file http://host:8080/zlib http://host:8080/zlib2 http://host2:8082/zlib

In this example, you point to a status priority file that enables the system to resolve status conflicts during synchronization by referring to a ranked list of statuses.

Options

Name Short name Description
--copy -c Copy citations from a single source project to one or more destination projects. The source project is the first project specified on the command line. One or more destination project(s) are specified to the right of the source project, separated by a space. For example:
--copy "srcproj" "destproj1" ["destproj2" ...]
--dry   Perform a "dry run"; the changes will be printed to the console, but will not be applied. See also the --output option. See Performing a "dry run" synchronization for how-to information.
--full -f Force a full synchronization. By default, kwxsync works in incremental mode.
--help   Display this help.
--jobs <int> -j Specify number of jobs to use. The default is 5.
--last-sync <string>   Last synchronization time, of the form "dd-MM-yyyy hh:mm:ss". Use this option when you want to copy all status updates and comments after a particular date and time. This helps improve performance by reducing the amount of information extracted from the database.
--max-retry   Specify the maximum number of times that kwxsync will retry communications with the server. The default is 3.
--output <file> -o Specify an output file for the "dry run" report. When this option is used with --dry, kwxsync outputs a record of all changes that will be made to the specified file, in HTML format. kwxsync will create an HTML report for each project, with the project name as part of the output file name. Note that the HTML file extension is not added if you do not specify it.
--quiet -q Suppress console messages.
--report <file>   Export a synchronization report to text file. See Generating a synchronization report for information on the synchronization report.
--statuses <string>   Specify a comma-separated list of statuses to be synchronized. When you specify the --statuses option, only updates to the specified statuses will be synchronized. For example, if you specify --statuses "not a problem",ignore, a status update to any of the other statuses, such as "Defer", will not be synchronized. See Issue statuses for the list of available statuses.

When synchronizing issue statuses across projects, the current issue status is always the status with the latest timestamp. All prior statuses for a given issue (in other words, statuses with earlier timestamps) are added to the issue citing history.

--status-priority <filename> -sp Specify a status priority file for the system to use to resolve issue status conflicts. This option can be used in combination with other options.
--storage   Specify a file location in which to persistently store synchronization information, for example:
kwxsync --storage my_storage http://host:8080/zlib
 http://host:8080/zlib2 http://host2:8082/zlib  
This option can be used in any combination with existing properties.

After you upgrade to a new version of Klocwork, for example, from 10.4 to 11.0, do not use old storage files. Instead, create a new storage file to use with the upgraded version of the product. Klocwork migrates data properly so the new storage file will contain the history of all issue status updates and comments, along with the ID of the user who made the changes.

If you move a project to another server, you can update the URL of the project so that you don't need to rebuild the storage file. See Renaming a project URL in a kwxsync storage file.

--tag   Tag copied comments with a prefix containing the following information: the name of the project in which the issue's status was first changed, the ID of the matching issue in that project, and the date (dd-mm-yyyy) and time (24h:mm) the issue's status was changed.
--url http(s)://<klocwork_server_host>:<klocwork_server_port>/   URL for the Klocwork Server. Use https:// if a secure Klocwork Server connection has been configured.
--version   Display version information.

Exit codes

When you run the kwxsync command, the system generates an exit code. In release 11.0, the exit codes changed. See the table below for more information.

Exit code Description
0 Success.
1 Catastrophic failure; for example, the server was down when starting the job.
2 Partial success; there was a problem synchronizing one or more projects but the rest of the projects continued synchronizing.