Custom Documentation

• Sparx Systems Enterprise Architect has a powerful feature to generate a quick report through the ‘Custom Document’ feature.
• Beneficial among businesses and firms not only because of the ease of generating reports but also because they are usually quite accurate and uniform.
• Helps the business to stay competitive by making the right data available to the right people at the right time.

What’s new in Custom Documentation in Sparx Enterprise Architect 16?

• New custom document templates and sample document contents are available through Model Wizard and can be accessed from a Document Publishing perspective.
• This new document templates allow you to produce high-level design, and functional, and business requirement documents.
• Creating a Custom Document is fairly simple, and you can generate a document with a few clicks by simply dragging and dropping a model content from the Project Browser.
• It Dynamically updates the entire document or a particular section, ensuring that it reflects the latest changes in the Model. So that, you can save time and avoid regenerating a document then copy-paste the changes in the existing word documents.
• Warnings are now displayed when data is lost when updating a dynamic part.
• Ad hoc reporting features allow users to customize to insert their own words, images, logo, and other contents to their own requirements.
• Improved content list, which now includes the element and template for each dynamic part.
• During document generation, a progress indicator will bring better feedback.
• Numerous improvements and usability improvements have been made.

Figure 1: Custom Templates

Further Information
Please contact us or write an email to info@sparxsystems.in to have a live demo about the new EA 16 features and capabilities.

Sparx Systems Enterprise Architect is one of the very few tools that have the capability to generate documents on go from a centralized repository. Enterprise Architect has features to customize document contents using user templates, fragments, style sheets, cover pages and headers, and footers.

• Document Script in fragments is a new option that is introduced in Enterprise Architect 13.
• Used generally for generating complex documents from Enterprise Architect.

Custom Script vs Document Script

• Custom script (Introduced in EA 11): Script returns a value that can be used in the fragment using the ‘custom’ field.
• Document script (Introduced in EA 13): A combination of scripts and templates. The script calls another Template and passes the ID of an object to be reported

How does Document Script work?

Advantages of Document Script:

• Flexibility in reporting desired fields in the desired order
• Loop through or mix and match details in a custom way, as per the requirements.
• Removes the need to write an external add-in to generate custom documents from the model.

Steps to create Document using Document Scripts:

• From the Above business process diagram, we are going to generate all the diagram objects from the parent package.
• Initially have created a Template like the below with package and element section enabled.

• Under the Diagram Objects heading have inserted a new fragment and inside the fragment have enabled the Custom Section as below

• To create a document script Fragment -> Document Options ->Custom Query -> Document Script and in the dropdown select the script which is written for document generation.

• Reference the ID of the element or Package currently being processed by the document template, using the #OBJECTID# or #PACKAGEID#
• Process Package script does the magic of rendering the objects in an order to a document.
• Script which needs to be used in the Document script should always return an RTF

      var docGenerator as EA.DocumentGenerator;

        docGenerator = Repository.CreateDocumentGenerator();

        if ( docGenerator.NewDocument(“”) )

        { 

            docGenerator.DocumentElement(ElementID,Heading Depth,”templateName”); // Used to add the element details in rtf

             var rtf = docGenerator.GetDocumentAsRTF();

            return rtf;

       }

• For more details on attributes and methods of DocumentGenerator class please refer to Sparx Help on Document Generator class
• In the document script, a template should be referred to so that the data will be formatted and printed based on that template.
• For e.g. From the below package structure in Enterprise Architect

• If the documentation is generated at the package level (BP00100) and the script for rendering all the diagram objects of a diagram
• We need to pass the packageID as the parameter in the document script.
• In the script, the main function rtf should be returned

function main(packageID)

{

var docGenerator as EA.DocumentGenerator;

docGenerator = Repository.CreateDocumentGenerator();

if ( docGenerator.NewDocument(“”) )

{

try

{

var package as EA.Package;

package = Repository.GetPackageByID(packageID);

var diagram as EA.Diagram;

diagram = package.Diagrams.GetAt(0);

var diagramObjects as EA.Collection;

diagramObjects = diagram.DiagramObjects;

for ( var i = 0 ; i < diagramObjects.Count ; i++ ) {

var diagramObject as EA.DiagramObject;

diagramObject = diagramObjects.GetAt( i );

var currentElement as EA.Element;

currentElement = Repository.GetElementByID(diagramObject.ElementID);

if(currentElement.Type != “Note” && currentElement.Type != “ActivityPartition” && currentElement.Type != “Pool” && currentElement.Type != “Lane”)

docGenerator.DocumentElement(currentElement.ElementID,1,ACTIVITY_TEMPLATE);

}

}

catch(e)

{

Session.Output(e);

}

var rtf = docGenerator.GetDocumentAsRTF();

return rtf;

}

return “”;

}

• Templates inside the script can be mentioned as below

var ACTIVITY_TEMPLATE = “Activity_Report”;

Conclusion:

• The above described is an example of generating a document using a document script. You can download this entire sample model with document generation scripts and templates from https://sparxsystems.in/Downloads/DocumentScriptTest.eap
• Any complex logic can be used in the script but finally, it should return an RTF. 

Further Information
Please contact us or write an email to info@sparxsystems.in to have a live demo of the new EA 16 features and capabilities.