Contents

1 Introduction

The TopITSM utility is a tool to analyze abstract information streams between ITSM repositories. It consists of an abstract set of repositories (“nodes”) and the information exchanged between them (“edges”). Company specific information can be added in order to:

• Identify technology gaps;
• Identify missing interfaces;
• Verify the consistency of the organizational structure;
• Map repositories to a specific ITSM methodology.

The following dimensions are supported:

• Class (predefined);
• Department;
• Tool;
• Process (ITSM framework).

1.1 Classes

Administration

A repository which is (mostly) updated and maintained manually;

Tool

A repository which is (mostly) updated and maintained automatically;

Cruncher

A repository which is (mostly) derived from other, external sources or repositories. Its main purpose is to process and/or present this information.

2 Requirements

Note a lot of PDF viewers and Office applications are known to work, including Acrobat Reader and Microsoft Office. It’s essential they can be called from the command-line. Note some applications may require to be included in the PATH to work. Consult the manual of your particular Operating System if you’re unfamiliar with this procedure.

TopITSM can be operated without any of these additional programs with the following limitations:

• TopITSM may generate the .dot file without Graphviz, however you won’t be able to convert it to a .pdf file. A warning may be issued;
• You can generate .pdf files, but you won’t be able to show them on the fly without a PDF viewer;
• You can generate .xls and .rtf files, but you won’t be able to show them on the fly without an Office application.

3 Installing TopITSM

• Create a working directory on your local machine;
• Copy all .idx and .dbm files from the /apps/topitsm directory to your working directory.

Finally, an .ini file has to be created. It has the following format:

[applications]

pdf=evince

rtf=lowriter

dot=dot

xls=localc

• The “applications” section is mandatory;
• Add the name of your PDF viewer executable after the “pdf=” entry;
• Add the name of your spreadsheet executable after the “xls=” entry;
• Add the name of your RTF executable after the “rtf=” entry;
• Add the name of your dot executable after the “dot=” entry.

Note you may add switches and/or paths if required. Save the file to your TopITSM directory as topitsm.ini. TopITSM will not function without an .ini file.

4 Using TopITSM

Now navigate to your TopITSM directory and issue:

4th cxq topitsm.4th

If all is well, TopITSM will respond with:

Initializing..

Type ’help’ for help. OK

The “OK” prompt indicates that TopITSM is now ready for your commands.

4.1 Help

Entering “help” will show the online help page.

4.2 Calculator

TopITSM contains a full integer RPN desk-calculator, much like the Unix dc utility or HP calculators. Only multiplication, division, addition and subtraction operations are supported. A ’dot’ will destructively display the Top of the Stack, e.g.:

23 45 + .

Will return:

68 OK

The following stack operators are available:

E.g. this will calculate 16²:

16 dup * .

256 OK

Note the calculator uses the native stack, so if you leave excessive amounts of superfluous values on the stack this may serious impede other operations.

4.3 TopITSM documents

TopITSM can generate three kinds of documents:

1. A Word document, containing the definitions of all repositories;
2. An Excel sheet, containing all attributes (including the definitions) of all the repositories;
3. Graphviz source-code, which can be rendered by Graphviz to a PDF file.

You can select the kind of document you want to generate by issuing the commands DOCUMENT, SHEET or GRAPH. Issuing one of these commands will leave the document type on the stack.

4.4 TopITSM views

The selected view determines how documents will be ordered or clustered. TopITSM will startup in the “normal” view. The following views are available:

CLASS

Will sort or cluster a document on the class of the repository, see section 1.1;

DEPARTMENT

Will sort or cluster a document on the department, which is responsible or accountable for the repository;

TOOL

Will sort or cluster a document on the tool, which hosts the repository;

PROCESS

Will sort or cluster a document on the ITSM process, which is supported by this repository;

NORMAL

Will sort on the name of the repository. No clustering will be applied.

None of these commands has any stack effects.

4.5 Generating documents

The actual generation of these documents will be achieved by issuing one of these commands:

GENERATE

Will generate the document type which is specified by the Top of the Stack;

SHOW

Will generate the document type which is specified by the Top of the Stack and show it by starting the appropriate viewer.

Note that commands can be concatenated. E.g. this will calculate the square of 23, set the view to normal and generate a Word document:

23 dup * . normal document generate

529 OK 

We advise you to cluster commands in a meaningful way, i.e. select a view, document and generation method:

process graph show

OK

Documents are always stored in your TopITSM directory and will be silently overwritten.

4.6 Error handling

Unknown commands are echoed and appended by a question mark. Internal errors will generate an “Oops”, e.g:

blah

blah? OK 

. 

Oops OK 

Note that any messages of supporting programs are not suppressed and will be shown verbatim. Stack frames will be preserved as they were before the offending command was issued.

5 Backup and restore

TopITSM has a built-in DBMS. The database consists of .idx and .dbm files in the archive. If the database is incomplete or corrupt TopITSM will not successfully initialize - and abort. You can dump the contents of the database and reload them. The database is dumped in .csv format with a semi-colon as delimiter. This is usually the default .csv format of Excel.

Note that although the spreadsheet produced by TopITSM shares some of the fields with the nodes backup, it is not equivalent and hence not suited for import.

5.1 Backup

• In order to backup the nodes, issue: export" nodes.csv". Note that the space after EXPORT" is significant. You may use any filename you see fit;
• In order to backup the edges, issue: save" edges.csv". Note that the space after SAVE" is significant. You may use any filename you see fit.

Files are saved in the TopITSM directory unless you explicitly issue another path.

5.2 Restore

• In order to restore the nodes, issue: import" nodes.csv". Note that the space after IMPORT" is significant. You may select any relevant file in any directory or drive;
• In order to restore the edges, issue: load" edges.csv". Note that the space after LOAD" is significant. You may select any relevant file in any directory or drive.

Note that you may seriously damage the database if you do not use a compliant file. If this occurs, we advise you to restore the original database files.

5.3 Changing node properties

• Export the nodes as described in section 5.1;
• Edit the file (e.g. using Notepad or Excel);
• Complete the following fields:
  • Tooling, the tool, which hosts the repository;
  • Department, the department, which is responsible or accountable for the repository. You can also use “roles” or “persons” if required;
  • Process, the ITSM process, which is supported by this repository. The default is ITILv3¹, but the ”Cube” methodology is also available. If this is the same “best practice” used in your organization, you can leave it as it is.
• Do not change the following fields unless you know exactly what you’re doing:
  • Name;
  • Description;
  • Label;
  • Shape;
  • Fillcolor;
  • Abbreviation;
  • Class.
• Save the .csv file and ensure you use the proper delimiter - a semi-colon;
• Import the resulting .csv file as described in section 5.2. The changes are applied immediately and normal operation can be resumed without a restart.

5.4 Changing edge properties

• Export the edges as described in section 5.1;
• Edit the file (e.g. using Notepad or Excel);
• Change the Style field. Possible values are:
  • solid
  • dotted
  • dashed
  • bold
• Do not change the following fields unless you know exactly what you’re doing:
  • Left;
  • Right;
  • Color;
  • Label.
• You have to ensure that the consistency with the ”nodes” table² is preserved;
• Save the .csv file and ensure you use the proper delimiter - a semi-colon;
• Import the resulting .csv file as described in section 5.2. The changes are applied immediately and normal operation can be resumed without a restart.