Workitem Attachment Migration Utility (DRAFT) todo.png

Authors: SharoonShettykuriyala, TimFeeney
Build basis: 6.0.6.1, 7.0, 7.0.1.

Disclaimer: The AttachmentMigrationUtility is provided as-is, with no support. You should not use AttachmentMigrationUtility in production systems without first trying it out on a clone of your production EWM repository in a test environment first unless specifically directed to do so by IBM support.

Download AttachmentMigrationUtility

To download the utility, go to the Attachments section at the bottom of this page. Download the 'readme.txt' file and the .jar file related to the version of your ELM system.

Attachments Migrator Utility

The Attachments Migrator Utility is a stand-alone Java application used to analyze and update attachments in a repository.

Motivation

In release 7.0, Engineering Workflow Management updated the default access control context for attachments to be the same as the work item access control to which it is uploaded. The utility is provided to help customers migrate existing attachments to the new access control model. It will find all work items that do not have the same access control as the work item linked and update the access context accordingly.

Features

The utility lists all the attachments in the repository that are : ⁃ linked to multiple work items, with an option to remove multiple links (so that an attachment would be owned by one work item only) ⁃ linked to a work item but are project owned, with an option to update the context to that of the work item ⁃ not linked to any work item, with an option to link to a specified work item ⁃ linked to a deleted work item, with an option to remove the link to the deleted work item

The analysis can be scoped to a specific project or all attachments in the repository.

Using the argument -h or -help provides a detailed help message on the various supported arguments and commands the utility supports.

The utility displays the size of individual orphaned attachments (not linked to any work item) as well as the total size for all orphaned attachments. This information can be used to remove these orphaned attachments since attachments (especially large ones) are often a large contributor to EWM repository size.

Example:

1) Help
$ <java.home>/bin/java.exe -jar AttachmentMigrationUtility.jar -uri=<https://<server name>:<port number>/<context root>> -u=<user> -pw=<password> -c=analyzeAndUpdateAttachments -h

Attachments Migrator 1.0
================================
The Attachments Migrator Utility is a stand-alone Java application used to analyze attachments in a repository and allow to change the access context of the attachments to that of the work item it is linked to. It supports the following commands:
      
Command: analyzeAndUpdateAttachments
Description: Fetch all attachments in a repository and update based on arguments. List all the attachments:
- which are linked to multiple work items, option to remove the multiple links.
- linked to a work item but are project owned, option to update the context to that of the work item.
- not linked to any work item, option to link to the specified work item.
- have any attachments linked to a deleted work item, option to remove the link to the deleted work item.

Argument Reference
==================

Note: Argument values containing whitespace must be enclosed in double quote characters.

-h, -help
    Prints this help message.

-uri, -serverUri=<URL>
    The fully qualified URL of IBM Engineering Workflow Management in the following format:
    https://<server>:<port>/<context root>
    Note: The fully qualified URL is case sensitive.
   
-u, -userName=<userName>
   The username for a valid user for the server.

-pw, -password=<password>
   The password for the username for the server.

-update
   Update the access context of attachments that are project owned with the access context of the work item it is associated with, update the project of the attachment if different than the work item.

-rmDelWILink
   Remove link to deleted work items from the attachments.

-rmMultiWILinks
   Remove multiple work links from the attachment.

-addWorkItemId
   The work item id to associate attachments that are not associated with any work item.

-deleteAttachmentsNoWI, delAttachmentsNoWI
   Deletes the attachments which has no work item associated with it.

-l, -log=<file>
    [Optional] Logs information to the specified log file (relative file name or absolute file path).
    Note: The log file is rotated (deleted) on every execution of the tool.
 
-p, -project=<project item id>
   [Optional] Analysis is done only for the specified project

Example usage:
 <java.home>/bin/java.exe -jar AttachmentMigrationUtility.jar -uri=<https://hostname:9443/ccm> -u=<user> -pw=<password> -c=analyzeAndUpdateAttachments -l=<c:/temp/migration.log>

2) Analyze attachments
$ <java.home>/bin/java.exe -jar AttachmentMigrationUtility.jar -uri=<https://<server name>:<port number>/<context root>> -u=<user> -pw=<password> -c=analyzeAndUpdateAttachments
Requested commands are: [analyzeAndUpdateAttachments].
analyzeAndUpdateAttachments started.
Contacting https://<server name>:<port number>/<context root>/…
User <user> has logged in to https://<server name>:<port number>/<context root>/
0 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - -----------------------------------------------------------------------
1 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Attachments linked to multiple work items: 1
1 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - -----------------------------------------------------------------------
1 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Attachment 1 - license_en.html linked to work item 2253 in project BH Scrum
1 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Attachment 1 - license_en.html linked to work item 2254 in project BH Scrum
1 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - -----------------------------------------------------------------------
analyzeAndUpdateAttachments completed.

$ <java.home>/bin/java.exe -jar AttachmentMigrationUtility.jar -uri=<https://<server name>:<port number>/<context root>> -u=<user> -pw=<password> -c=analyzeAndUpdateAttachments
Requested commands are: [analyzeAndUpdateAttachments].
analyzeAndUpdateAttachments started.
Contacting https://<server name>:<port number>/<context root>/...
User <user> has logged in to https://<server name>:<port number>/<context root>/

0 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - -----------------------------------------------------------------------
1 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Attachments with out the same access context as the work item: 1
1 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - -----------------------------------------------------------------------
1 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Attachment 4 - capture-20200309-1114 (1).png linked to work item 98 in project JKE Banking (Change Management)
1 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - -----------------------------------------------------------------------
1 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - -----------------------------------------------------------------------
1 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Attachments linked to no work items: 3
1 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - -----------------------------------------------------------------------
1 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Attachment 5 - Screen Shot 2020-04-15 at 3.02.57 PM.png in project All_Presentation with size 475.4 KB
2 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Attachment 6 - Screen Shot 2020-04-10 at 3.08.50 PM.png in project BH Scrum with size 95.1 KB
2 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Attachment 8 - Screen Shot 2020-04-15 at 3.02.57 PM.png in project BH Scrum with size 475.4 KB
2 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Total attachments size: 1.0 MB
2 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - -----------------------------------------------------------------------
analyzeAndUpdateAttachments completed.

$ <java.home>/bin/java.exe -jar AttachmentMigrationUtility.jar -uri=<https://<server name>:<port number>/<context root>> -u=<user> -pw=<password> -c=analyzeAndUpdateAttachments
Requested commands are: [analyzeAndUpdateAttachments].
analyzeAndUpdateAttachments started.
Contacting https://<server name>:<port number>/<context root>/...
User <user> has logged in to https://<server name>:<port number>/<context root>/
0 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - -----------------------------------------------------------------------
1 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Attachments linked to no work items: 2
1 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - -----------------------------------------------------------------------
1 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Attachment 3 - landscape-2090495_960_720.jpg in project dbp-scrum with size 99.7 KB
1 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Attachment 4 - Screen Shot 2018-08-07 at 5.25.53 PM.png in project Sai Scrum with size 64.6 KB
1 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Total attachments size: 164.4 KB
1 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - -----------------------------------------------------------------------
analyzeAndUpdateAttachments completed.

3) Delete the attachments which have no work item associated with it.
$ <java.home>/bin/java.exe -jar AttachmentMigrationUtility.jar -uri=<https://<server name>:<port number>/<context root>> -u=<user> -pw=<password> -c=analyzeAndUpdateAttachments -deleteAttachmentsNoWI
Requested commands are: [analyzeAndUpdateAttachments].
analyzeAndUpdateAttachments started.
Contacting https://<server name>:<port number>/<context root>/...
User <user> has logged in to https://<server name>:<port number>/<context root>/

0 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Deleting attachment 3 - landscape-2090495_960_720.jpg
Delete Attachments
1291 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Deleting attachment 4 - Screen Shot 2018-08-07 at 5.25.53 PM.png
Delete Attachments
Exception: CRJAZ6053E To complete the 'Save Attachment' task, you need these permissions: 'You don't have permission to perform the following actions:
  Delete attachment (delete)'
analyzeAndUpdateAttachments completed.

If the user does not have permissions to delete the attachment for that project then the appropriate error is thrown.

4) Update the access context of attachments that are project owned with the access context of the work item it is associated with, update the project of the attachment if different than the work item.

$ <java.home>/bin/java.exe -jar AttachmentMigrationUtility.jar -uri=<https://<server name>:<port number>/<context root>> -u=<user> -pw=<password> -c=analyzeAndUpdateAttachments -update
Requested commands are: [analyzeAndUpdateAttachments].
analyzeAndUpdateAttachments started.
Contacting https://<server name>:<port number>/<context root>/...
User <user> has logged in to https://<server name>:<port number>/<context root>/
0 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Updating context for attachment 4 - capture-20200309-1114 (1).png to context of work item 98.
2925 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - -----------------------------------------------------------------------
2925 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Attachments linked to no work items: 3
2925 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - -----------------------------------------------------------------------
2926 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Attachment 5 - Screen Shot 2020-04-15 at 3.02.57 PM.png in project All_Presentation with size 475.4 KB
2926 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Attachment 6 - Screen Shot 2020-04-10 at 3.08.50 PM.png in project BH Scrum with size 95.1 KB
2926 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Attachment 8 - Screen Shot 2020-04-15 at 3.02.57 PM.png in project BH Scrum with size 475.4 KB
2926 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Total attachments size: 1.0 MB
2927 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - -----------------------------------------------------------------------
analyzeAndUpdateAttachments completed.

5) Remove multiple work links from the attachment.
$ <java.home>/bin/java.exe -jar AttachmentMigrationUtility.jar -uri=<https://<server name>:<port number>/<context root>> -u=<user> -pw=<password> -c=analyzeAndUpdateAttachments -rmMultiWILinks
Requested commands are: [analyzeAndUpdateAttachments].
analyzeAndUpdateAttachments started.
Contacting https://<server name>:<port number>/<context root>/...
User <user> has logged in to https://<server name>:<port number>/<context root>/
0 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Multiple work item links to attachment 1 - license_en.html ... retaining link to work item 2253.
1039 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Deleting link: sourceRef 2254: Formal item for CR 92269 - Project A targetRef: 1: license_en.html.
analyzeAndUpdateAttachments completed.

6) Associate attachments that are not associated with any work item to a specific work item.
$ <java.home>/bin/java.exe -jar AttachmentMigrationUtility.jar -uri=<https://<server name>:<port number>/<context root>> -u=<user> -pw=<password> -c=analyzeAndUpdateAttachments -addWorkItemId=<work item id>
Requested commands are: [analyzeAndUpdateAttachments].
analyzeAndUpdateAttachments started.
Contacting https://<server name>:<port number>/<context root>/...
User <user> has logged in to https://<server name>:<port number>/<context root>/
0 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Linking attachment 5 - Screen Shot 2020-04-15 at 3.02.57 PM.png to work item 17571.
351 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Linking attachment 6 - Screen Shot 2020-04-10 at 3.08.50 PM.png to work item 17571.
841 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Linking attachment 8 - Screen Shot 2020-04-15 at 3.02.57 PM.png to work item 17571.
1594 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - -----------------------------------------------------------------------
1594 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Attachments with out the same access context as the work item: 2
1594 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - -----------------------------------------------------------------------
1594 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Attachment 6 - Screen Shot 2020-04-10 at 3.08.50 PM.png linked to work item 17571 in project BH Scrum
1594 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Attachment 8 - Screen Shot 2020-04-15 at 3.02.57 PM.png linked to work item 17571 in project BH Scrum
1594 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - -----------------------------------------------------------------------
1594 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - -----------------------------------------------------------------------
1594 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Attachments in different project than the work item: 2
1595 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - ----------------------------------------------------------------------
1595 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Attachment 6 - Screen Shot 2020-04-10 at 3.08.50 PM.png linked to work item 17571 in project BH Scrum
1595 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - Attachment 8 - Screen Shot 2020-04-15 at 3.02.57 PM.png linked to work item 17571 in project BH Scrum
1595 [main] INFO com.ibm.team.tap.tools.attachmentsMigrator.AttachmentMigrationUtility  - -----------------------------------------------------------------------
analyzeAndUpdateAttachments completed.

It is recommended to run the tool in a test environment (a near clone to production system) to gauge the time it would take to run and to verify that the commands yield expected results. The migration support of the tool was developed mainly with the intent to migrate to 7.0 system. It could be run on a 7.0 system after upgrade as well.

Versions supported:

The tool is built with the SDK of the following version of EWM
  • 604
  • 605
  • 606
  • 6061 / 7.0 / 7.0.1

Reference:
See, https://trfeeney.wordpress.com/2019/10/08/follow-up-to-help-my-rtc-database-is-getting-big/, to learn more on how database space is reclaimed once the unwanted attachments are deleted from the system.

Topic attachments
I Attachment Action SizeSorted ascending Date Who Comment
Txttxt readme7.0.txt manage 2.3 K 2020-04-03 - 17:15 TimFeeney readme for the AttachmentMigrationUtility (applicable to all versions)
Jarjar AttachmentMigrationUtility605.jar manage 13319.6 K 2020-05-28 - 22:24 UnknownUser The version of the tool that can be run against 6.0.5 server
Jarjar AttachmentMigrationUtility606.jar manage 13720.9 K 2020-05-28 - 22:25 UnknownUser The version of the tool that can be run against 6.0.6 server
Jarjar AttachmentMigrationUtility.jar manage 13786.0 K 2020-05-28 - 22:26 UnknownUser The version of the tool that can be run against 6.0.6.1, 7.0 or 7.0.1 servers
Jarjar AttachmentMigrationUtility604.jar manage 14025.5 K 2020-05-28 - 22:23 UnknownUser The version of the tool that can be run against 6.0.4 server
This topic: Deployment > WebHome > DeploymentAdminstering > WorkitemAttachmentMigrationUtility
History: r3 - 2020-05-28 - 22:27:15 - Main.sharoons
 
This site is powered by the TWiki collaboration platformCopyright © by IBM and non-IBM contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our Terms of Use. Please read the following disclaimer.
Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more here.