(r7) WorkitemAttachmentMigrationUtility < Deployment

~~EditAttach~~Printable
r7 - 2021-09-11 - 00:46:57 - Main.WebsmithYou are here: TWiki >
Deployment Web > DeploymentAdminstering > WorkitemAttachmentMigrationUtility
<div id="header-title" style="padding: 10px 15px; border-width:1px; border-style:solid; border-color:#FFD28C; background-image: url(<nop>https://jazz.net/wiki/pub/Deployment/WebPreferences/TLASE.jpg); background-size: cover; font-size:120%">
---+!! Workitem Attachment Migration Utility
%DKGRAY% Authors: Main.SharoonShettykuriyala, Main.TimFeeney <br>
Build basis: 6.0.4, 6.0.5, 6.0.6, 6.0.6.1, 7.0, 7.0.1.
For 7.0.2 a support case must be opened to download the utility.
%ENDCOLOR%</div></sticky>

<!-- Page contents top of page on right hand side in box -->
<sticky><div style="float:right; border-width:1px; border-style:solid; border-color:#DFDFDF; background-color:#F6F6F6; margin:0 0 15px 15px; padding: 0 15px 0 15px;">
%TOC{title="Page contents"}%
</div></sticky>

<sticky><div style="margin:15px;"></sticky>
*%RED%Disclaimer: The Attachment Migration Utility is provided as-is, with no support. You should not use Attachment Migration Utility in production systems without first trying it on a (near) clone of your production Engineering Workflow Management (EWM) repository in a test environment first, unless specifically directed to do so by IBM support.%ENDCOLOR%*


---++ Overview
In release 7.0, EWM updated the default access control context for attachments to be the same as the work item access control to which it is uploaded.  The Attachments Migration Utility is a stand-alone Java application used to analyze and update attachments in a repository. 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.


The utility should be run first in a test environment with a clone of the production EWM repository.  This will allow you to gauge the time it would take to run the utility in production and to verify that the commands yield expected results. The utility was developed mainly with the intent to run as part of an upgrade to 7.x, however, it can also be run on a 7.x system after upgrade as well.


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.

---++ 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.

---++ Examples
---+++ Help
<verbatim>
$ <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>
</verbatim>

---+++ Analyze attachments
<verbatim>
$ <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.
</verbatim>

---+++ Delete attachments that have no associated work item
<verbatim>
$ <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.
</verbatim>

---+++ Update the access context of attachments that are project owned
This will change the access context of the work item that are project owned to that of the work item; it will update the project of the attachment if different than the work item.
<verbatim>
$ <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.
</verbatim>

---+++ Remove multiple work links from the attachment
<verbatim>
$ <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.
</verbatim>

---+++ Associate attachments with no work item association to a specific work item
<verbatim>
$ <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.
</verbatim>

---++Downloads by supported version
The utility is built with the SDK of the following versions of EWM
   * [[%ATTACHURL%/readme7.0.txt][readme file for all supported versions]]
   * [[%ATTACHURL%/AttachmentMigrationUtility604.jar][6.0.4]]
   * [[%ATTACHURL%/AttachmentMigrationUtility605.jar][6.0.5]]
   * [[%ATTACHURL%/AttachmentMigrationUtility606.jar][6.0.6]]
   * [[%ATTACHURL%/AttachmentMigrationUtility.jar][6.0.6.1 / 7.0 / 7.0.1]]

For Version 7.0.2 and later, a support case must be opened to access the utility.
---++!! Related topics:
See this [[https://trfeeney.wordpress.com/2019/10/08/follow-up-to-help-my-rtc-database-is-getting-big][blog]] to learn more on how database space can be reclaimed once the unwanted attachments are deleted from the system.
Attachments
Topic attachments
I	Attachment	Action	Size	Date	Who	Comment
jar	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
jar	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
jar	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
jar	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
txt	readme7.0.txt	manage	2.3 K	2020-04-03 - 17:15	TimFeeney	readme for the Attachment Migration Utility (applicable to all versions)
Deployment
Community information and contribution guidelines
Status icon key:
To do
Under construction
New
Updated
Constant change
None - stable page
Smaller versions of status icons for inline text:
Copyright © 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.