How to use ImportInternalDocumentArtifact()?

[George]

Hello all,
I'm currently trying to import a file as an internal document using the ImportInternalDocumentArtifact() method from the EA automation interface (Enterprise Architect v16.x, 64-bit), but it does not seem to work.

Code: [Select]

var filePath = "C:\\Temp\\sample.json";
var artifact as EA.Element;
artifact = currentPackage.Elements.AddNew("config.json", "Artifact");
artifact.Update();
var result = artifact.ImportInternalDocumentArtifact(filePath);
Session.Output("File imported?: " + result + "; Count of artifact files: " + artifact.Files.Count);

Logged output:

Code: [Select]


[434475711] File imported?: true; Count of artifact files: 0
When I double-click on the created Artifact, no document opens — the file has not been imported.
Are there any preconditions for ImportInternalDocumentArtifact() to work? Any insight would be greatly appreciated.
 Thank you!

[Geert Bellekens]

The strange thing is that is is not even documented.
https://sparxsystems.com/enterprise_architect_user_guide/17.1/add-ins___scripting/element2.html doesn't mention this method at all.
So it might nog have been implemented at all.

I guess we need to hear from Sparx to be sure.

Geert

[Takeshi K]

On my machine (build 1710), the script works fine. I can double-click the generated object in a diagram to show the json file.

FYI, the Element.Files property does not related to the method. The Element.Files are of items for the Resposibilities dockable window.

[George]

Regarding the documentation of ImportInternalDocumentArtifact() method.
Yes, I also found that documentation is missing, but Google found these links:

Mentioned in EA v12(!): Changes and fixes for Build 1212:

• "Element.ImportInternalDocumentArtifact - Imports the specified file as the internal artifact for this element"
• https://sparxsystems.com/products/ea/12/history.html
• So I thought it is an old feature

And also here, it seems to be Japanese version of EA documentation:

• https://www.sparxsystems.jp/help/17.0/element2.html
• Is it possible that it works only in Japan? As also Takeshi K response suggests.

@Takeshi K:
Ok, I checked working with element.Files collection on a manual example.
- It works for external files (attachments) only, i.e. Type = "Local File" for files in file system or Type = "Web Address".
- Internal document stored within EA db seems not to be included into this collection, so the count in my original code fragment is useless.

[Takeshi K]

@George:

I have maintained the help pages of the sparxsystems.jp. I have checked and added the missing methods/attributes so some of them might not be written in the English help.

Anyway, the Automation Interface is the same among all languages of Enterprise Architect, so you can use the method on the original Enterprise Architect.

[George]

I’d like to share my findings after experimenting with ImportInternalDocumentArtifact() for adding internal documents to Artifact elements. Initially, I thought the method was broken, but it turns out I had made a few mistakes — including falling into an undocumented trap.
These methods basically work as expected:

• Element.ImportInternalDocumentArtifact(filePath) – imports the specified file as an internal document of the element
• Element.IsInternalDocArtifact – indicates whether this element is an internal document Artifact
• Element.ExportInternalDocumentArtifact(filePath) – exports the internal document to a file

However, beware of gotchas:
1. Stereotype blocks the file import
If the Artifact element has a Stereotype set, then ImportInternalDocumentArtifact() silently fails and returns false.
Workaround:

Code: [Select]

var origStereotype = artifact.StereotypeEx;
artifact.StereotypeEx = "";
artifact.ImportInternalDocumentArtifact(filePath);
artifact.StereotypeEx = origStereotype;
artifact.Update();

2. Artifact element name is overwritten
Calling ImportInternalDocumentArtifact() will automatically rename the element (element.Name) to match the imported file name. It can be also changed, reverted to the original name, if required.

3. Element.Files have nothing to do with internal documents
They only concern the external ones.

Hope this helps others avoid the same confusion.
Let me know if there are other obstacles or undocumented behaviors.
Thanks!