Focus on Documents

---

Updated : 21 November 2024

Working with Document Identifiers (DocumentId)

Each document is distinguished by an identifier whose type is DocumentId The identifier can be empty and its IsEmpty property will therefore return true. Moreover, the document being edited is returned by the EditedDocument property and can be empty.

Thus it is possible to retrieve the document being edited and check that it is not empty before starting any modifications.

Document identifiers correspond to specific minor revisions of PDM objects It is possible to find a DocumentId from PDM objects and vice versa as described in the diagram below:

• To open a document, simply call the TopSolidHost.Documents.Open method and inform it of the DocumentId.
• To save a document, the TopSolidHost.Documents.Save method must be used and the DocumentId must be filled in.
• To close a document, use the TopSolidHost.Documents.Close method which takes as argument the DocumentId, and two booleans to respectively ask the user to confirm the closure and if the document should be saved.

Here is a piece of code that allows you to open, save and close the document filled in by any DocumentId "docId" :

TopSolidHost.Documents.Open(ref docId);
TopSolidHost.Documents.Save(docId);
TopSolidHost.Documents.Close(docId,false,false);

---

Modification of documents : StartModification and EndModification

Your application can interface with TopSolid to both extract information and modify its data. If modifications are required, the application must notify TopSolid beforehand. This is done by calling TopSolidHost.Application.StartModification before making changes and TopSolidHost.Application.EndModification after the modifications are complete.

Note

StartModification may fail if TopSolid is in an inaccessible state. For instance, this can happen if the user is actively editing a menu function. Your application must handle this scenario appropriately.

If StartModification is successful, TopSolid will become unavailable to the user until EndModification is called. Failing to call EndModification will leave TopSolid in a blocked state, requiring the user to terminate the process and potentially lose all unsaved modifications. To avoid this, it is critical to always call EndModification.

To safeguard against issues with StartModification and EndModification, we recommend implementing a try/catch block. Place the StartModification and modification logic within the try block and ensure EndModification is called in both the try and catch blocks. This ensures that if an error occurs, control is properly returned to the user. The recommended structure is as follows:

try
{
	//Start modification
    TopSolidHost.Application.StartModification("My Action", false);
    
    // Your modification code here
    
	//End modification (if success)
    TopSolidHost.Application.EndModification(true, true);
}
catch (Exception ex)
{
    // Handle exception here
    TopSolidHost.Application.EndModification(false, false);
}

---

Focus on EnsureIsDirty

To ensure that a document is editable, you must use the TopSolidHost.Documents.EnsureIsDirty method, which references the DocumentId of the document to be modified. If this method returns true, the document is editable, allowing you to proceed with modifications while minimizing the risk of errors.

However, be aware that this method can fail in specific scenarios, such as when a user exits the document vault. In such cases, a new revision is created, causing the DocumentId to change. This highlights the importance of validating the document's state and handling potential errors when working with document revisions.

Warning

Beginners often overlook the EnsureIsDirty method. If you encounter an issue and end up in the catch block, make sure to check whether you forgot to call EnsureIsDirty. This simple step can help prevent errors and ensure the document was properly validated for edits before attempting modifications.