Book a Demo

Author Topic: documentation automation interface syntax  (Read 4116 times)

ggandhi

  • EA User
  • **
  • Posts: 28
  • Karma: +0/-0
    • View Profile
documentation automation interface syntax
« on: December 25, 2013, 02:08:27 am »
I have had some success with the documentation automation interface. Because scripting is NOT something Sparx provide direct assistance with, I need to know where I can find the answers. This forum is useful, but it is not a published API guide. I need to know where the object model is described. I need to know he corect syntax. I have provided My Pseudocode Example below which outlines what I am trying to achieve. The pseudocode demonstrates that I have yet to learn the correct syntax.
 
In my company, for each Sparx project package, we need to print the package name, package notes, package-linked document, then iterate over all diagrams, print the diagram, then (if (currentDiagram.Type == 'Deployment')) within each diagram, print a tabulated list of diagram elements. I have already successfully built this reporting process (without using the documentation automation interface) using a Virtual Document with a «master document» containing 3 «model document»s. This is provided as a template to my customers. The customer simply drops project packages into the middle «model document» and runs their report, rooted in the «master document».  There is one hole in the process. Currently, regardless of diagram.type, the process prints a print a tabulated list of diagram elements. The documentation automation interface may be the solution.  
  
(My Pseudocode Example)
currentPackage = Repository.GetTreeSelectedPackage();
generationSuccess = docGenerator.DocumentPkgNotes( currentPackage.PkgID, 0, SECTION_HEADER_AND_NOTES_TEMPLATE );
generationSuccess = docGenerator.DocumentLinkedDocument( currentPackage.LinkedDocID, 0, LINKED_DOC_TEMPLATE );
// Iterate over all diagrams under the currently selected package
   var packageDiagrams as EA.Collection;
   packageDiagrams = currentPackage.Diagrams;
   for ( var i = 0 ; i < packageDiagrams.Count ; i++ )
    {
     // Get the current diagram
     var currentDiagram as EA.Diagram;
     currentDiagram = packageDiagrams.GetAt( i );
     generationSuccess = docGenerator.DocumentDiagram( currentDiagram.DiagramID, 0, PACKAGE_DIAGRAM_IMAGE_TEMPLATE );
     if (currentDiagram == 'Deployment')
     {
        generationSuccess = docGenerator.DocumentDiagramElements( currentDiagram.DiagramID, 0, PACKAGE_DIAGRAM_ELEMENTS_TABLE_TEMPLATE );
     }
   }

Please can someone show the correct syntax for the above documentation automation interface JScript.

ggandhi

  • EA User
  • **
  • Posts: 28
  • Karma: +0/-0
    • View Profile
Re: documentation automation interface syntax
« Reply #1 on: December 27, 2013, 10:04:44 pm »
Since I started this discussion, I have devised the correct syntax for the above documentation automation interface JScript.  I am successfully choosing between one RTFTemplate or another RTFTemplate according to the diagram type.  I need to make a further enhancement. I need to apply an element filter on the tabulated list of elements.  If I apply this element filter to the RTFTemplate, nothing is printed.  Dermot (Sparx Support) has explained "with the automation scripting the filters are not applied. It is up to the coder to set code condition statements as to what objects/diagrams etc. are printed or not printed.".  I have prepared element-level code so that I will be able to set condition statements around the stereotype of each element. Before I code condition statements, I need to know how to print element-level data. Currently my code is failing to print diagram element information.  I guess there are errors in the following declaration.
var diagramElements as EA.Collection;
diagramElements = currentDiagram.Elements;

Any ideas?
 

ggandhi

  • EA User
  • **
  • Posts: 28
  • Karma: +0/-0
    • View Profile
Re: documentation automation interface syntax
« Reply #2 on: December 30, 2013, 09:01:23 pm »
Since my last post, I have found the correct myObjects declaration as shown below.
I know that the myObjects declaration is correct because diagramObjects.Count matches the number of elements (23) in the diagram.
Function ReportInfo tells me that currentObject.ElementID is properly defined, because function ReportInfo returns currentObject.ElementID as a unique ID for each element.

var myObjects as EA.Collection;
myObjects = currentDiagram.DiagramObjects;
for ( var i = 0 ; i < myObjects.Count ; i++ )
{
var currentObject as EA.DiagramObject;
currentObject = myObjects.GetAt( i );
ReportInfo( " ElementID:" + currentObject.ElementID);

I believe I am passing the correct parameter currentObject.ElementID to docGenerator.DocumentElement.
generationSuccess = docGenerator.DocumentElement(currentObject.ElementID,0,DIAG_TABLE_ROW_TEMPLATE);
So this time the problem could be related to DIAG_TABLE_ROW_TEMPLATE, the RTFTemplate VEIAD_doc_auto_int_02_Diag_Table_Row, which look like this:
package>
diagram>
element>
{Element.Name}
<element
<diagram
<package

I get no error message, but nothing is being printed, even though no filter is applied.

ggandhi

  • EA User
  • **
  • Posts: 28
  • Karma: +0/-0
    • View Profile
Re: documentation automation interface syntax
« Reply #3 on: December 31, 2013, 09:42:58 pm »
As usual, Nizam Mohamed (Enterprise Architect Sparx Systems User Group) has inspired me and I have made a breakthrough. I tested the USECASE_TEMPLATE.  It worked OK, so I compared the positioning of containers with my RTFTemplate Fragment. I fixed my table-row-printing fragment VEIAD_ELEM_TABLE_ROW (specified in my DocumentGenerator API Jscript).
 
The problem was caused by the positioning of the table row inside the diagram element containers as follows:
package>
diagram>element> "my table row" <element<diagram.
<package
 
I fixed the problem by moving the position of the table row outside of the diagram containers as follows:
package>
diagram><diagram
element>"my table row"<element
<package
 
RTFTemplate Fragment VEIAD_ELEM_TABLE_ROW is now producing a table row for each eligible diagram element.  
 
I still have one problem with one of the RTFTemplate Fragment sub-queries, even though the same sub-query works perfectly in my Virtual Document model. I am not using the Virtual Document model because it does not allow me to programmatically choose between diagrams with tables and diagrams without tables.  This is why I have developed this JScript to use the DocumentGenerator API.
 
The current problem lies in {Template - VEIAD_ELEM_TABLE_SQL_01_RUNTIME}
 
RTFTemplate Fragment VEIAD_ELEM_TABLE_ROW contains a table with one row and 7 columns as follows:
Column 1: {Element.Name}
Column 2: {Element.Stereotype}:{Element.valueOf(04-Hostname)}
Column 3: {Template - VEIAD_ELEM_TABLE_SQL_02_OS}
Column 4: {Element.valueOf(01-CPU)}
Column 5: {Element.valueOf(02-Mem)}
Column 6: {Template - VEIAD_ELEM_TABLE_SQL_01_RUNTIME}
Column 7: {Element.valueOf(06-Total Storage/Tier)}
 
All columns are successful except for column 6. Columns 3 (successful) and 6 (unsuccessful) are described below.
 
RTFTemplate Fragment VEIAD_ELEM_TABLE_SQL_02_OS contains the following code
custom>
{OS}
<custom
 
RTFTemplate Fragment VEIAD_ELEM_TABLE_SQL_02_OS contains the following Custom SQL Custom Query
select distinct t_objectproperties.Value as OS from t_objectproperties where t_objectproperties.Property in ('02-OS') and t_objectproperties.Object_ID in (select t_connector.End_Object_ID from t_connector where t_connector.Connector_Type in ('Generalization', 'Realisation') and t_connector.Start_Object_ID=#OBJECTID#)
 
 
RTFTemplate Fragment VEIAD_ELEM_TABLE_SQL_01_RUNTIME contains the following code
custom>
{RuntimeEnv}
<custom
 
RTFTemplate Fragment VEIAD_ELEM_TABLE_SQL_01_RUNTIME contains the following Custom SQL Custom Query
select distinct t_objectproperties.Value as RuntimeEnv from t_objectproperties where t_objectproperties.Property in ('01-Runtime Env') and t_objectproperties.Object_ID in (select t_connector.End_Object_ID from t_connector where t_connector.Connector_Type in ('Generalization', 'Realisation') and t_connector.Start_Object_ID=#OBJECTID#)
 
Question
 
Even though
1. VEIAD_ELEM_TABLE_SQL_02 succeeds in retrieving {OS} in this DocumentGenerator API context
2. VEIAD_ELEM_TABLE_SQL_01_RUNTIME and VEIAD_ELEM_TABLE_SQL_02 both succeed perfectly in my Virtual Document model wherein the table row is inside the diagram element containers
 
why does VEIAD_ELEM_TABLE_SQL_01_RUNTIME fail to retrieve {RuntimeEnv} in this DocumentGenerator API context?

ggandhi

  • EA User
  • **
  • Posts: 28
  • Karma: +0/-0
    • View Profile
Re: documentation automation interface syntax
« Reply #4 on: January 04, 2014, 03:34:08 am »
I have fixed the issue with {RuntimeEnv} by deleting and re-inserting the code {Template - VEIAD_ELEM_TABLE_SQL_01_RUNTIME} into column 6 of RTFTemplate Fragment VEIAD_ELEM_TABLE_ROW. I noticed that the appearance of the above code was different to the appearance of code {Template - VEIAD_ELEM_TABLE_SQL_02_OS}, suggesting that something was impacting the DocGenAPI interpretation of {Template - VEIAD_ELEM_TABLE_SQL_01_RUNTIME}. The RTF Editor font box and style box did not show any style difference, but the red code appearance suggested there was a difference. Now that both codes have the same appearance, {RuntimeEnv} is being populated into RTFTemplate Fragment VEIAD_ELEM_TABLE_ROW.

I can close this discussion now, but I have found a Sparx bug in the DocGenApi Table of Contents.  The page numbers are printing as '1_' instead if '10' etc.  :-X