IDocumentCreator¶
- class IDocumentCreator¶
Bases:
ImpactCOMWrapperBase- Description:
The IDocumentCreator is used to add multiple documents in a single operation.
- Remarks:
The IDocumentCreator allows multiple documents to be added in a single operation. The IDocumentCreator can be used to pre-populate a list of documents to add and display the ‘Add Documents’ dialog to the user (see show_dialog). The IDocumentCreator object can be retrieved from any IDocuments collection. An IDocumentCreator retrieved from an IDocuments collection for an existing Impact object (such as ICustomer) will automatically add an IDocumentCreatorRelationship as appropriate. For an unsaved IDrawing the IDocumentCreator object retrieved from IDrawing.document_creator can be used to add documents to the project before it is saved. When the IDrawing is saved in the database the documents will automatically be added at the same time. Use the add_local_file, add_extracted_files_from_local_file, or add_existing_document methods to add documents, use add_relationship to add one or more document relationships that should be created. Finally use Perform to create all the documents in the document repository. Use the Item property to iterate the documents, and the Relationship property to iterate common document relationships. Introduced in Impact 9.0.0.83.
Wraps a COM object or another wrapper instance. Accepts: - A valid impact_object - An existing impact_com_wrapper_base-derived instance
- property allow_documents_to_be_changed¶
Gets allow_documents_to_be_changed.
- Description:
Prevents a user from adding or removing files while using the ‘Add Documents’ dialog.
- Remarks:
This property only applies when using the show_dialog method.
- Returns:
The value of allow_documents_to_be_changed.
- Return type:
- property auto_relationship¶
Gets auto_relationship.
- Description:
Determines the default relationship that will be created.
- Remarks:
Introduced in Impact 11.0.0.7
- Returns:
The value of auto_relationship.
- Return type:
- property can_add_existing_documents¶
Gets can_add_existing_documents.
- Description:
Determines if the IDocumentCreator supports existing documents being added.
- Remarks:
If the IDocumentCreator was retrieved from an IDocuments collection for an existing Impact object (such as an ICustomer) then existing documents can be added to the object. If the IDocumentCreator was retrieved from an unsaved IDrawing then existing documents can also be added.
- Returns:
The value of can_add_existing_documents.
- Return type:
can_add_existing_documents (bool)
- property comments¶
Gets Comments.
- Description:
Optional comments that will be added to IDocumentHistoryItem.details when each document is added.
- Returns:
The value of Comments.
- Return type:
comments (str)
- property count¶
Gets Count.
- Description:
The number of items in this collection.
- Returns:
The value of Count.
- Return type:
count (int)
- property created_count¶
Gets created_count.
- Description:
The number of documents that were successfully created.
- Remarks:
Using this property before calling Perform will result in an error.
- Returns:
The value of created_count.
- Return type:
created_count (int)
- property existing_count¶
Gets existing_count.
- Description:
The number of existing documents that were successfully modified.
- Remarks:
When adding existing documents using the IDocumentCreator new IDocumentRelationship’s are created between the existing documents and the associated object. Using this property before calling Perform will result in an error.
- Returns:
The value of existing_count.
- Return type:
existing_count (int)
- property relationship_count¶
Gets relationship_count.
- Description:
The number of relationships in this collection.
- Returns:
The value of relationship_count.
- Return type:
relationship_count (int)
- add_existing_document(document)¶
- Description:
Adds an existing IDocument to the IDocumentCreator.
- Remarks:
Check the can_add_existing_documtns property before using this method. When adding an existing document a new IDocumentRelationship is created to link the Impact object (such as ICustomer) to the existing document. This mechanism does not create a duplicate of the IDocument in the document repository. The IDocumentCreatorDocument object returned by this function provides a read-only object that can only be used to display values, with the exception of adding or removing IDocumentCreatorRelationship’s.
- Returns:
Returns a read-only IDocumentCreatorDocument object that references the existing IDocument to add.
- Parameters:
document (IDocument) – The IDocument object to add a relationship for.
- add_extracted_files_from_local_file(file_name)¶
- Description:
Adds the contents of a container file to the IDocumentCreator.
- Remarks:
The files added to the IDocumentCreator are not actually added to the document repository until the Perform method is called. It is important that any local files added to the IDocumentCreator are still in their original locations when the Perform method is called. Use the files_can_be_extracted_from_local_file method to determine if the local file_name contains one or more files. The add_extracted_files_from_local_file method is used to automatically extract files from a zip file and add each file individually. To add a zip file without extracting the contents use the add_local_file method instead. The IDocumentType, IDocumentMIMEType and IDocumentGroup associated with a document are automatically inferred from the file_name parameter based on the file extension. You can use the IDocumentCreatorDocument objects returned by this method to modify the values stored when these documents are created by Perform.
- Returns:
Returns an array of IDocumentCreatorDocument objects that references the extracted files to add.
- Parameters:
file_name (str) – Full path to the file containing multiple files to add.
- add_local_file(file_name)¶
- Description:
Adds a local file to the IDocumentCreator.
- Remarks:
The files added to the IDocumentCreator are not actually added to the document repository until the Perform method is called. It is important that any local files added to the IDocumentCreator are still in their original locations when the Perform method is called. The IDocumentType, IDocumentMIMEType and IDocumentGroup associated with a document are automatically inferred from the file_name parameter based on the file extension. You can use the IDocumentCreatorDocument object returned by this method to modify the values stored when this document is created by Perform.
- Returns:
Returns the IDocumentCreatorDocument that references the local file to add.
- Parameters:
file_name (str) – Full path to the document file to add.
- add_relationship(document_latest_version, relationship, external_type, object_i_d)¶
- Description:
Adds a common document relationship.
- Remarks:
The document relationships are not created until the Perform method is called. Each of the common document relationships added using this method will be created for all documents being created and any existing documents being added. See IDocumentRelationships.add for details of valid object_id values. To add document relationships to individual documents use the IDocumentCreatorDocument.add_relationship method instead.
- Parameters:
document_latest_version (bool) – Links the relationship to the latest document version when true, or the current document version when false.
relationship (ipDocumentRelationship) – The type of relationship to add.
external_type (str) – The external type of relationship for drExternal. It is recommended to use a format such as [domain]:[type] to identify external objects to avoid clashes with other applications. For example ‘webcnx:task’.
object_id (any) – The object that this relationship references.
- clear()¶
- Description:
Clears all documents and relationships from the IDocumentCreator.
- Remarks:
If the IDocumentCreator was retrieved from an IDocuments collection for an existing Impact object (such as an ICustomer) the default IDocumentCreatorRelationship will be automatically re-added after Clear.
- files_can_be_extracted_from_local_file(file_name)¶
- Description:
Determines if files can be extracted from the local file.
- Remarks:
Use this method to determine if the file_name contains multiple files. This method currently only supports ‘zip’ container files.
- Parameters:
file_name (str) – Full path to the file containing multiple files to add.
- item(index)¶
- Description:
Gets an IDocumentCreatorDocument object with the specified index.
- Parameters:
index (any) – Specifies the index of the IDocumentCreatorDocument object to get.
- perform()¶
- Description:
Performs all document adding and modifying operations.
- Remarks:
The Perform method is used to add each IDocumentCreatorDocument and IDocumentCreatorRelationship to the document repository. After calling Perform check the created_count property to determine the number of documents that were added to the document repository or the existing_count property to determine the number of existing documents that were modified. The Perform operation is not a single atomic operation. Even when Perform fails you should check the created_count or existing_count properties as one or more operations may have completed before Perform failed. Once the Perform method has been used you cannot modify the IDocumentCreator object any further. However you can iterate each IDocumentCreatorDocument using the Item property and retrieve the IDocument’s that were added.
- relationship(index)¶
- Description:
Gets an IDocumentCreatorRelationship object with the specified index.
- Parameters:
index (any) – Specifies the index of the IDocumentCreatorRelationship object to get.
- remove(index)¶
- Description:
Removes a specific IDocumentCreatorDocument.
- Remarks:
The Index parameter can be either an integer index or a string GUID (to match IDocumentCreatorDocument.guid).
- Parameters:
index (any) – Specifies the index of the IDocumentCreatorDocument object to remove.
- remove_relationship(index)¶
- Description:
Removes a specific IDocumentCreatorRelationship.
- Parameters:
index (any) – Specifies the index of the IDocumentCreatorRelationship object to remove.
- show_dialog()¶
- Description:
Display the ‘Add Documents’ dialog to the user.
- Remarks:
Use this function to display the ‘Add Documents’ dialog to the user. You can pre-populate the IDocumentCreator object with any local files or existing documents, or you can display an empty dialog. If you don’t want the user to modify the file being added you can set allow_documents_to_be_changed to false. This function will fail if used in an IServer context.