Troubleshooting During Multiple-Row Editing
During multiple-row editing, it is possible for various errors to occur.
File Open Errors
Attempting to open a second instance of a document that you already have open for multiple-row editing causes an error message to display. The message indicates that a document cannot be open in both multiple-row editing mode and single-row editing mode at the same time. This same message is shown if you attempt to use the CLI to open a document that is already open. It is also shown if two of the same documents are open in single-edit views and you attempt to turn on multiple-row editing from the Editing tab in the Options window.
Backup Recovery Errors
Backup files apply only to multiple-row editing. Because backup files are dependent on the file system, a change to the file system can prevent writing unsaved changes to backup files. In such cases, a red banner displays, indicating the type of error that has occurred. The banner displays three buttons:
• View Error Details—Clicking this button opens the Backup Error window, which displays information about the error. Following these button descriptions is additional information about why backup errors occur.
• Turn Off Multiple-Row Editing—Clicking this button turns off multiple-row editing and turns on single-row editing. The document is then opened for single-row editing. Because backup files are specific to multiple-row editing, this option allows you to work without backup files. It also prevents accumulating too many changes by forcing more frequent saves.
Backup errors occur when attempts are made to create, write to, or read from the backup file. Several variations of the red banner for backup errors exist.
• The “backup failed” banner indicates that an error was encountered while trying to back up changes. This banner appears if permissions for the backup file were suddenly set to read-only while you are editing the document. Clicking View Error Details shows details of the error encountered while trying to write to the backup file. Once the underlying problem is corrected, you must close the document and reopen it so that future changes are backed up. This banner also gives you the option to turn off multiple-row editing to prevent further backup attempts. However, if unsaved changes exist, the button for turning off multiple-row editing is unavailable. In this case, you must either save or discard changes before you can switch to single-row editing. Saving the document always results in the creation of a new backup file.
• The “recovery failed” banner indicates that the backup file is corrupted and that no changes can be recovered. This banner appears when a client shuts down unexpectedly and, on restart, an attempt is made to recover the document from a corrupted backup file. This is a rare scenario in which all unsaved changes to your document are lost. Clicking View Error Details shows details of the error encountered while trying to read the backup file. You can dismiss the banner and continue working on the document because a new backup file gets created.
• The “backup failed to initialize” banner indicates that a backup file cannot be created. This banner appears if the backup folder is not writable. Clicking View Error Details shows details of the error encountered while trying to create the backup file. Once you have corrected the underlying problem, you must close the document and reopen it so that future changes are backed up.
Additional information about backup files follows.
• Backup files are created for top-level context only. For a document with subdocuments, unsaved changes made to subdocuments are recovered after an unexpected shutdown only if you open the parent document, not the subdocument.
For example, document A includes document B. When multiple-row editing is turned on, opening document A creates a backup file for top-level document A. This backup file includes unsaved changes made to both document A and included document B. Assume that an unexpected shutdown occurs.
◦ If you open document A, unsaved changes in document A and included document B are recovered.
◦ If you open document B, any unsaved changes in document B, made within document A, are not recovered.
• Time entries entered on the time entries panel cannot be restored because they are not fields.
Save Errors
Save errors can occur when you are working in documents that have other documents included in them and another user branches an included document in which you have made changes to one or more nodes. When a save error occurs, a banner with two buttons displays.
• View Errors—Clicking this button opens the Save Errors window, which displays changes that could not be made. The information shown for each content item follows the button descriptions.
• Learn More—Clicking this button opens this Integrity Lifecycle Manager Help Center topic.
Here is the scenario in which a save error occurs:
1. You open document A for multiple-row editing and make a change to one or more nodes under included document B.
2. Another user opens document A for either single-row or multiple-row editing and selects > on document B so that document B is branched.
3. You save your changes to document A.
A save error occurs, indicating changes to included document B cannot be made because it was deleted after you began your edit. The newly branched document B replaces the included document B in which you made your changes.
Resynchronize Errors
Resynchronize errors can occur if editability rules for fields have changed to make then uneditable. Resynchronize errors can also occur if the scenario described for save errors exists when you resynchronize. When a resynchronize error occurs, a banner with two buttons displays.
• View Errors—Clicking this button opens the Resynchronize Errors window, which displays changes that could not be made. The information shown for each content item follows the button descriptions.
• Learn More—Clicking this button opens this Integrity Lifecycle Manager Help Center topic.
For each content item with changes that could not be made, you are given information about the affected field, error cause, and your change.
Errors reported when resynchronizing include time entry changes if time entries are no longer editable. For such errors, the values saved on the server are accepted.
Document Locking Errors
During multiple-row editing, you can lock and unlock a document. When saving or resynchronizing, Integrity Lifecycle Manager checks fields for lock attributes and displays an error message if a locking problem exists. The error message also describes how to resolve the problem.
The following table describes scenarios where locking problems are possible. When a document locking error occurs, the document retains all edits that existed before the save or resynchronization started. If you are in situation where you need a lock, you can potentially acquire one.
|
Scenario
|
Modifications Allowed
|
Modifications Made
|
Save
|
Resynchronize
|
|
Document locking is not required, and document is opened without a lock.
|
All fields can be modified.
|
Lock edit and non-lock edit fields
|
Allowed
|
Allowed
|
|
Document locking is required, and document is opened without a lock.
|
Only the fields that are not lock edit fields can be edited. Because the view knows about the locking requirement when opening the document, it knows what fields can be edited.
|
Non-lock edit fields
|
Allowed
|
Allowed
|
|
Document locking is not required, and a document is opened without a lock. However, an administrator makes locking required after the document was opened.
|
All fields can be modified. Because the view does not know about the locking requirement when opening the document, it thinks all fields can be edited.
|
Only non-lock edit fields
|
Allowed
|
Allowed
|
|
Fields that include lock edit fields
|
Not allowed
|
Not allowed
|
|
Document is locked by someone else before the document is opened.
|
Only non-lock edit fields can be modified unless the user is part of the lock group. Because the view knows about the lock when opening the document, it knows what fields can be edited.
|
Non-lock edit fields (and lock edit fields if user is part of lock group)
|
Allowed
|
Allowed
|
|
Document is not locked when opened, and locking is not required. However, a second user locks the document after the first user opens its.
|
All fields can be modified, regardless of whether the first user is in the lock group. This is because the view does not know that a second user has locked the document.
|
Lock edit fields
|
Not allowed unless the first user is part of the lock group
|
Not allowed unless the first user is part of the lock group
|
|
Document is locked, and user is not in the lock group. However, the lock is released during the session, and locking is not required.
|
Only non-lock edit fields can be modified. This is based on the information that the view had when opening the document.
|
Non-lock edit fields
|
Allowed
|
Allowed
|
Behaviors Unique to Multiple-Row Editing
QBR (Query Backed Relationship) fields always display the most recent values returned from the Integrity Lifecycle Manager server. During multiple-row editing, these values are not necessarily consistent with other data on an item.
Pending Import Errors
The next topic describes how you can use pending imports to review and modify requirements before saving them to the server. A pending import always opens for multiple-row editing, regardless of your Document view settings. If a problem is encountered when loading a pending import, a red or yellow banner displays, indicating the type of error that has occurred. These banners display two buttons:
• View Errors—Clicking this button opens the Pending Import Errors window, which displays information about the error. Following these button descriptions is additional information about why pending import errors occur.
Two variations of the banners for pending import errors exist. You can dismiss either of these banners and review and modify the document if desired.
• The red “pending import failed” banner indicates that the pending import of the document has failed and that no changes are loaded in the Document view. This banner appears when the pending import is somehow corrupted or modified outside of Integrity Lifecycle Manager. Clicking View Errors shows the errors encountered while trying to load the pending import.
• The yellow “pending import with errors” banner indicates that the pending import file has opened but that some changes could not be loaded. It then advises that you review and make required changes before saving. Clicking View Errors shows the changes that could not be made for specified item IDs. For example, perhaps a field is not editable or is not visible on the item type or an attachment cannot be loaded.
|
|
It is possible for banners to display simultaneously for both a pending import error and a backup error. For example, both the yellow “pending import with errors” banner and red “backup failed” banner can display. Similarly, both the red “pending import failed” and red “backup failed to initialize” banner can display.
|
If the
Integrity Lifecycle Manager client shut downs unexpectedly when a pending import is open, your unsaved changes are recovered when you next open this pending import. A yellow banner indicates if all unsaved changes were restored in the recovered document. If any changes cannot be restored, the yellow banner displays
View Errors and
Learn More buttons. Because pending imports always open for multiple-row editing, backup files always exist for recovering unsaved changes in pending imports. For more information, see
Recovering Unsaved Changes Made During Multiple-Row Editing.
