TIP Doc Generator UserGuide

Owned by Craig Gallen [Administrator] (Unlicensed)
Last updated: Feb 12, 2013Version comment

JOSIF Main Page | JOSIF Framework | TIP Doc Generator | TIP Doc Generator UserGuide

Installation

For software prerequisites and installation process, please refer to Getting Started

Use TIP Documentation Generator in a TIP Model project

Note: we may take the documents generated from TIP SPM Model and TIP Test Models as examples. Please note that the examples only reflect status of the models and the generator at the time the wiki page is compiled.

Resources Checklist

The authors of TIP model prjects should prepare some resources which are part of inputs to the documentation generator. Some resources are optional.

1. Introduction and Summary

We create two HTML files in the 'docs' folder of a TIP model project. The files must be named to intro.html and summary.html seperately. They will be contents for chapter 1 and chapter 2 of generated document, respectively. For the structure of the document to be generated, please refer to TIP Doc Generator DocStructure

Note: if a TIP Model project is created with TIP project creator, the 'docs' folder and two HTML files with default contents will be automatically created. Otherwise, the authors need to create them manually.

Following are recommended structure of these two HTML files:

Introduction

This file gives an introduction to TIP interfaces. Its structure can be (we take example from TIP SPM model):

<html>
  <body>
<p>The TM Forum has given much attention to the evolution of next generation networks and the business and operational support systems needed to manage them. 
As a result, the TIP Framework was developed to provide a toolkit of industry-agreed specifications and guidelines that cover key business and technical areas.
</p> 
<p>
There are potential gaps or weaknesses for service problem management, especially for newer, more advanced information and content services. 
To date, most service assurance activities have focused on a set of network-facing processes aimed at determining and resolving network and service issues and events.
With the increased range of services now being offered and the increasingly competitive market-driven environment, new demands are being placed on the service assurance systems to deliver even higher levels of service to customers. 
</p>
<p>
The TM Forum recognizes the service assurance platforms need to evolve at the same rate of speed as the networks used to deliver services. </p>
<p>
The Service Problem Management interface is filling this gap and defining an interface to manage Service Problems that is following the SID Model and using the newly developed TIP Framework tooling. 
</p>

<h2>Document Structure</h2>
<p>The following sections are contained in this document:
<ul>
	<li>Section 1 is the document introduction</li>
	<li>Section 2 provides a summary description of the interface</li>
	<li>Section 3 describes all the Service Interfaces contained in this interface</li>
	<li>Section 4 describes the Information Model used by this interface</li>
</ul>
</p>
  </body>
</html>

The generated doc is:

Note that the sub-section about convention is appended by the generator automatically. The model author don't need to provide it

Summary

This file gives summary of TIP interfaces. Following is a sample (from TIP SPM model):

<h1>Interface Summary</h1>

The Service Problem Management interface is covering 2 new SID ABEs:



<ul>
  <li>Problem or Trouble ABE, part of the Common Business Entities Domain. This 
  ABE contains all shared definitions, like statuses and the definition of the 
  Problem entity as it is shared between Service Problem and Customer Problem. 
  Problem has been defined as abstract. </li>
  <li>Service Problem ABE, part of the Service Domain. This ABE contains the 
  Service Problem. </li>
</ul>
<p>The Service Problem Management interface is an entity-centric interface, so 
all the operations are related to either the Problem or the Service Problem 
entities. All operations defined can be shared and therefore have been defined 
on the Problem entity and the corresponding service interface, defined as an 
abstract interface, is part of the Trouble or Problem ABE. The 
service interface associated to the Service Problem simply inherits from the 
Problem service interface.</p>
<p>The 2 Service Interfaces will be described first, then the implementation 
packages that correspond to the 2 ABEs will be described.</p>
<img src="./../../TIP_SPM_Model.jpg" width="465px" height="465px"/>

Please note that at the last line is we give a link to an image. This image is the overall picture of the model, you can refer to next section for more details. Note that the relative path './../../' starts from the gen folder 'target\tigerstripe.gen' which is automatically generated at the fist phase of the generation. If you want to use this HTML template, you can just change the picture name according to your enviroment.

The generated doc is:

2. Pictures

The pictures are optional.

We can prepare following pictures.

a) A picture about TIP service

b) Pictures about interfaces

c) Pictures about entities

Note: The generator can put pictures into adequate place of generated document. These pictures are not necessary for the generator to run, but is nice to have for a TIP doc.

Picture about TIP service

The picture should be named as '%project name%.jpg'. We can find project name in tigerstripe.xml of the project. Please put this picture in the root of the model project.

For example, if the project name is 'TIP_SPM_Model', picture name should be 'TIP_SPM_Model.jpg'.

Picture about interfaces

The pictures should be named as '%short name of interface%.jpg'. Take interface org.tmforum.tip.cbe.problem.ProblemInterface (in TIP SPM Model) as example, the picture name should be ProblemInterface.jpg', and we must put it in the same folder with java file of the interface.

Picture about interfaces or entities

The pictures should be named as '%short name of entity%.jpg'. Take entity org.tmforum.tip.cbe.problem.Problem (in TIP SPM Model) as example, the picture name should be 'Problem.jpg', and we must put it in the same folder with java file of the entity.

3. Service Name and File Name

Please refer to Variables

Run the Generator

1. Enable the generator

2. Click the button 'G' in menu:

3. When the generation is successfully completed, find the generated document

For example, for SPM project, the generated doc is TMF_SPM_IA.pdf, in which we can find output of prepared resources: service introduction, service summary, pictures. This file is located at: