24 Waterside

44–48 Wharf Road

London

N1 7UX

T +44 20 7832 5850

F +44 20 7832 5870

E office@adelard.com

W www.adelard.com

18 April 2018 Page 1/14

From: ASCE Support Team

To: ASCE Users

Title: User guide for the eCassandra plugin for ASCE

Contents

1 Introduction ......................................................................................................................................... 1

2 Requirements ...................................................................................................................................... 2 2.1 ASCE requirements .................................................................................................................. 2 2.2 eCassandra requirements ........................................................................................................ 2

3 Installation ........................................................................................................................................... 2

4 Usage ................................................................................................................................................... 3 4.1 Inserting the ASCE DNRs ......................................................................................................... 4 4.2 Examples in use ........................................................................................................................ 8 4.3 Connecting to exported XLS files ........................................................................................... 10

4.3.1 Exporting XLS content from eCassandra .................................................................. 10 4.3.2 Importing eCassandra XLS content into ASCE ......................................................... 11 4.3.3 Performance limitations of XLS import .................................................................... 11

5 Troubleshooting ................................................................................................................................ 11

6 Technical support .............................................................................................................................. 12

Appendix A Risk matrix file for exported XLS hazard logs ...................................................................... 13 A.1 Structure of the riskmatrix.xml file ....................................................................................... 13 A.2 Using Windows Notepad to create the risk matrix file ......................................................... 14

1 Introduction

This document is a user guide for the ASCE eCassandra plugin.

Version of plugin covered by this user guide: 0.1.7

The plugin provides a DNR (Dynamic Narrative Region) facility that allows the safety case in ASCE to

summarise and report on information held in eCassandra Hazard logs. The plugin works with all ASCE

Schemas (e.g. Claims, Arguments, Evidence, Goal Structuring notation etc).

The plugin provides two core reporting services:

1. Summary of an individual hazard, accident, control, cause or reference from eCassandra.

Optionally, this can include a list of linked items

2. Summary of a hazard log as a whole, showing a populated risk matrix that indicates the current

risk status for accidents managed in the hazard log

The plugin can connect to the following data services:

1. Exported XLS hazard logs from eCassandra.

18 April 2018 Page 2/14

2 Requirements

2.1 ASCE requirements

The plugin requires ASCE v4.1 or later.

This plugin requires a proper 32 bit driver installed on the system in order to read MS Office files. If you are

using a 64 bit version of Microsoft Office you have to install the Microsoft Access Database Engine 2010

Redistributable (x86 - 32bit version).

This component is included in the ASCE zip package inside the prerequisites folder or can be downloaded

freely from the Microsoft website.

2.2 eCassandra requirements

To connect to hazard logs in eCassandra, you will need to have:

• Access to the eCassandra webservice

• One or more hazard logs hosted on eCassandra

To connect to hazard logs exported from desktop eCassandra, you will need to create an accompanying risk

matrix XML file – see Appendix A for details.

3 Installation

Use the ASCE plugin manager to install the *.bundle file, choosing the “just me” option when asked where

to install the plugin.

18 April 2018 Page 3/14

Figure 1: ASCE plugin manager

4 Usage

The general process is that in the safety case, a claim would be made that hazards are being adequately

managed. Evidence for this would typically be held in the hazard log.

18 April 2018 Page 4/14

Figure 2: Safety case in ASCE with Hazard log evidence

4.1 Inserting the ASCE DNRs

To insert the eCassandra DNR, open the node editor and then from the Plugin DNR menu, insert the DNR

from the Insert->Plugin (DNR element).

Select one of the two options from the Adelard eCassandra plugin:

18 April 2018 Page 5/14

Figure 3: Menu options for ASCE eCassandra plugin in node editor

This will insert an unconfigured DNR element, to configure it, click on it

18 April 2018 Page 6/14

Figure 4: Inserted DNR for eCassandra hazard log

18 April 2018 Page 7/14

Figure 5: Configuring the DNR options

18 April 2018 Page 8/14

The following DNRs are available:

DNR menu option Purpose Required parameters

1. Insert specific item(s) from

XLS

Allows summarizing a specific item

(Hazard, Accident, Control, Cause,

Reference) from an exported XLS file

from eCassandra. A summary of a

specific item will include:

• all fields for that item,

• (optionally) a summary of

linked items (e.g. hazards

linked to some accident)

Allows summarizing all items of a

specific type. In this case, summary

fields (title id, description) will be

shown.

Path to the XLS file,

exported from

eCassandra

Selection of the item type

to be summarized

2. Insert Hazard log summary

from XLS

Provides a populated risk matrix

showing either:

• Identifier of each

accident, grouped by the

various risk categories

• Lifecycle status for each

risk class

Path to XLS file, exported

from eCassandra

Summary type required

4.2 Examples in use

The following screenshots provides examples that show how the plugin will summarise and report

information from eCassandra hazard logs.

18 April 2018 Page 9/14

Figure 6: Hazard log summary – showing populated risk matrix

18 April 2018 Page 10/14

Figure 7: Example showing summary of a particular accident held in eCassandra

4.3 Connecting to exported XLS files

4.3.1 Exporting XLS content from eCassandra

The ASCE eCassandra plugin can summarise hazard logs exported from eCassandra. To export the XLS file

you can use the following steps:

• Tools/"Import/Export Hazard Log"/Export to Microsoft Office.

• A form appears.

18 April 2018 Page 11/14

• Select Excel as the export format (Access is also available - you get one table for each Excel

worksheet, but nothing else)

o Click Select all for Entities to export and Links to export.

• Then click Export at the top of the form.

• After a pause, a dialog appears with "Do you want to open or save ExportProject.xls from

<servername>?" with Open and Save buttons.

o The latter has drop-down options that allow you to change the filename and select a folder

to save to.

• The dialog disappears, and you can close the form manually.

4.3.2 Importing eCassandra XLS content into ASCE

Use the relevant DNR from within the node editor, then edit the DNR and select your exported hazard log

spreadsheet. Make sure you have a risk matrix file as described in Appendix A.

4.3.3 Performance limitations of XLS import

The Microsoft Data Access Driver for Excel can be quite slow if you have the file open at the same time in

Microsoft Excel.

If you are experiencing performance problems, you should close the file in Excel before updating or

querying any ASCE DNRs using this plugin.

5 Troubleshooting

The following table contains advice covering various issues that may arise when using the plugin

Issue Solution

Exported eCassandra XLS files

The information in the hazard log report does not

reflect the state of the hazard log

Re-export the XLS file from eCassandra (see

Section 4.3)

It is recommended that the XLS file is re-exported

whenever a significant change is made to the

eCassandra file.

I get an error message about a missing risk

matrix

Create a manual risk matrix XML file – see

Appendix A for details

Performance is slow when connecting to or

updating a DNR that queries an exported XLS file

from eCassandra

Check the XLS file is not already open in Excel.

Close the file in Excel and the performance will be

significantly improved.

18 April 2018 Page 12/14

6 Technical support

For technical support on this plugin, email ASCE technical support on:

• asce_support@adelard.com

18 April 2018 Page 13/14

Appendix A Risk matrix file for exported XLS hazard logs

At the time of writing (spring 2018), the XLS export from eCassandra does not include all information being

maintained in eCassandra. In particular, the risk matrix is not exported.

In order for the ASCE plugin for eCassandra to correctly classify the risks, it needs to know which

combination of severities and probabilities constitute the chosen risk levels. The workaround is to re-create

this risk matrix as an XML file that replicates the risk matrix table held in eCassandra. This needs to be

done only once for each hazard log.

Creating this risk matrix file is a more advanced task and so you should be confident in editing XML files

using a plain text editor.

The risk matrix file must be saved in the same folder as the exported XLS file as follows:

\path\to\exported\xls\file\<exported_filename>.riskmatrix.xml

Where <exported_filename> is the name of the XLS file.

For example, if the example “Glider” example was exported as:

d:\desktop\hazard_log\Glider_export.xls

The associated risk matrix would have to be saved to a file called

d:\desktop\hazard_log\Glider_export.xls.riskmatrix.xml

This is shown in the following screenshot:

Figure 8: Risk matrix XML file saved to export folder

A.1 Structure of the riskmatrix.xml file

The structure of the riskmatrix file should be the same as that used in the exported eCassandra file. It

should have a list of severities and probabilities defining the columns and rows of the risk matrix.

18 April 2018 Page 14/14

The <matrix> section of the file should replicate exactly the same risk matrix structure used in hazard log.

An example of the required structure of the XML file is as follows:

<?xml version="1.0"?> <!--

A simple specification of a risk matrix.

Severities are the columns, Probabilities are the rows

and the risk matrix specifies the assigned risk classes

for the various pairs.

-->

<risk-matrix>

<severities>Catastrophic,Critical,Marginal,Negligible</severities>

<probabilities>Frequent,Probable,Occasional,Remote,Improbable,Incredible</probabilities>

<matrix>

<row>A,A,A,B</row>

<row>A,A,B,C</row>

<row>A,B,C,D</row>

<row>B,C,D,D</row>

<row>C,D,D,D</row>

<row>D,D,D,D</row>

</matrix>

</risk-matrix>

Figure 9: Example content required for a risk matrix XML file

A.2 Using Windows Notepad to create the risk matrix file

Windows Notepad can be used to create the risk matrix file, as it is a plain text file.

The main point of note is when you save the file, you should save the full filename, including the full

filename extension – e.g. “Project.xls.riskmatrix.xml”.

If you do not include the full filename and extension, Notepad will save the file with the .TXT file extension.

Other plain text editors can be used as an alternative to Windows Notepad and do not have this limitation.