Unclassified
From: Luke Emmet
To:
ASCE plugin developers
Ref:
W/2082/12201/45
Title: ASCE development documentation
Contents
1
Introduction to ASCE Plugins ................................................................................................ 2
1.1 Example plugin features ......................................................................................... 3
2
Plugin file definition ............................................................................................................... 3
2.1 ASCE plugin file format ......................................................................................... 3
2.2 Plugin installation locations .................................................................................... 3
3
ASCE Plugin XML structure ................................................................................................. 4
3.1 <plugin>.................................................................................................................. 4
3.1.1 <general-info> ......................................................................................... 4
3.1.2 <applicable-schemas> ............................................................................. 4
3.1.3 <user-interfaces> ..................................................................................... 5
3.1.4 <script> .................................................................................................... 6
4
Plugin user interface forms ..................................................................................................... 6
4.1.1 Loading a plugin form ............................................................................. 6
4.1.2 Handling events ....................................................................................... 6
4.1.3 Unloading a form ..................................................................................... 6
4.1.4 Other ASCE Events ................................................................................. 7
5
Dynamic Narrative Regions (DNRs) ...................................................................................... 7
5.1.1 Introduction ............................................................................................. 7
5.1.2 DNR specification ................................................................................... 7
5.1.3 Reserved attributes .................................................................................. 8
5.1.4 DNR lifecycle .......................................................................................... 8
5.1.5 Persisting state in a DNR element ........................................................... 9
5.1.6 refresh-method ......................................................................................... 9
5.1.7 Content "flattening" ............................................................................... 11
6
ASCE Schemas ..................................................................................................................... 11
7
References............................................................................................................................. 12
Adelard
265332806
Unclassified
13 July 2017
Unclassified
Page 2 of 12
1 Introduction to ASCE Plugins
This document explains how to develop plugins for ASCE 4.2 Enterprise, covering the
following aspects
●
File format for ASCE plugins, and required structure – see Section 2 and Section 3.
●
User interface forms in ASCE plugins – see Section 4.
●
An overview of the DNR facilities available to plugin developers – see Section 5.
This document should be read in conjunction with the ASCE object model API documentation
[1], available from the ASCE support team <[email protected]> .
ASCE is a flexible and extensible graphical hypertext system for developing managing and
reviewing structured documentation such as safety and assurance documents.
A typical end user application of ASCE is to develop some kind of "Assurance" case in which a
structured argument of claims or goals are backed up by argumentation and supporting
evidence, including multiple internal and external cross-references. This approach can be
applied to problem domains such as:
●
safety cases and safety assurance reports
●
compliance cases
●
assurance cases
●
system/software reliability cases
●
environment cases
●
project plans
An ASCE network is a directed graph of ASCE objects with the visual design and some
properties defined by the applicable ASCE Schema (see Section 6).
Each node within the ASCE network has the following properties:
●
Node type
●
User editable Title and Id properties
●
HTML Annotation – where users edit the narrative content or insert DNRs (see
Section 5)
●
Node properties (also known as Status fields) which are schema-specific (see Section
6)
●
In-Links and out-links collections, referencing linked nodes that define the graph
structure.
●
Layout information in a number of views (size, position).
Further details of the available properties and methods of the ASCE object model can be found
in [1].
13 July 2017
265332806
Unclassified
Adelard
Unclassified
Page 3 of 12
1.1 Example plugin features
Writing plugins for ASCE is a primary way in which you can add value to the core ASCE
product. An ASCE Plugin can significantly extend the behaviour of ASCE. For example, a
plugin can provide the following functionality:
●
Popup windows to present and collect information from the user
●
Analysis of the structure of a network
●
Propagation of data values over the network
●
Connection to third party tools and file formats
●
Exporting data
2 Plugin file definition
2.1 ASCE plugin file format
An ASCE plugin is an XML file that extends the functionality of ASCE with macros and
additional user interface windows. The structure and contents of an ASCE plugin is described in
Section 3.
Plugins that need additional resources can be distributed as a .bundle file, which is simply a .zip
file that satisfies the following:
●
The bundle file must follow the naming convention that it has the same name as the
plugin file within it, but with a .bundle file extension.
●
The bundle file must contain the plugin xml file at the top level of the zip container.
●
The bundle file may contain other resources or sub folders.
Bundle files can be installed by the end user by means of the plugin manager feature within
ASCE. Installing a bundle plugin will result in a sub folder being created within the plugins
folder with the name of the plugin.
Bundle files can be created by zipping up the relevant files and renaming the .zip file to
.bundle.
Each plugin should have a filename that uniquely identifies the plugin. The base of the filename
is used in all DNR elements (see 2.5) that are inserted by the user in his or her network.
It is recommended that the name of the organisation that developed the plugin is included in the
file name to reduce potential file name clashes (e.g. adelard arrangement macros.xml)
2.2 Plugin installation locations
ASCE plugins that are shipped with ASCE are stored in the "plugins/" folder beneath the ASCE
program folder. This is typically:
c:\program files\ASCE-v42\plugins\
(or similar depending on your operating system and version of ASCE).
Additionally, ASCE plugins can be manually placed within the following location within the
user profile:
Adelard
265332806
Unclassified
13 July 2017
Unclassified
Page 4 of 12
%APPDATA%/Adelard/ASCE/4.2/plugins
End users should use the plugin manager feature of ASCE provides an “install” function to load
new plugins provided to them.
When an ASCE network is loaded in ASCE Enterprise, ASCE determines which plugins are
applicable for the schema of the network that is being loaded (described below).
3 ASCE Plugin XML structure
3.1 <plugin>
The root element for the plugin provides basic information about the plugin. This item must
contain the following attributes:
●
plugin-engine-version - this indicates the version of the plugin engine used and
expected. Currently the value of this attribute must be "3.0" to be loaded by ASCE
4.0 or 4.1 (other values reserved for future use)
●
name – the user friendly name of the plugin, which is determines the entry for that
plugin in the plugin manager.
For example:
<plugin plugin-engine-version="3.0" name="My plugin name">
3.1.1
<general-info>
This element contains general information about the plugin and its author, including contact
information. The following tags should be included:
●
<author> - the author of the plugin
●
<email> email contact information for the plugin author
●
<organisation> - organisation that developed the plugin
●
<homepage> - home page for the organisation or a home page for the plugin
●
<documentation> - a description (Text or escaped HTML) of the plugin and what it
does. Can include links to further information if required
●
<version> - the version of the plugin
3.1.2
<applicable-schemas>
This section contains a list of <schema-match> tags which contain an expression which matches
one or more ASCE schemas.
When ASCE loads a network, it checks the schema for the network, and then loads only those
plugins that contain a <schema-match> item that matches the schema for the current network.
3.1.2.1
<schema-match>
The schema-match item is a simple regular expression, so therefore it is possible to include
expressions to match a range of schemas.
13 July 2017
265332806
Unclassified
Adelard
Unclassified
Page 5 of 12
●
* matches any sequence of characters (zero or more)
●
? matches any character
●
# matches any single digit (0–9).
Some examples:
schema-match text
Would match schemas called
ASCAD*
ASCAD
ASCAD 2.9.3a
ASCAD based new schema 0.1a
etc
ASCAD 1.?
ASCAD 1.0
ASCAD 1.A
etc
ASCAD #.#
ASCAD 1.1
ASCAD 2.1
etc
*
[All schemas]
3.1.3
<user-interfaces>
Each plugin should provide some user interface information so that the end user can interact
with it. This consists of:
●
forms (which can be loaded into a pop-up window) at the appropriate moment, and
●
menus (which are inserted into ASCE's menu structure)
3.1.3.1
<form name="frmMyForm">
Optionally, there can be a number of forms in an ASCE plugin. Each form contains a <layout>
tag which contains a chunk of HTML which provides the user interface for that form.
The name of the form must be provided, and is case-insensitive. The form name must not
contain hyphens or start with a number. Suitable form names include:
●
frmMyForm
●
frmAnotherForm
●
frmYetanotherform2
●
frmContentPlugin
●
AnotherForm
<layout>
This contains a block of escaped HTML that provides the user interface for the form when it is
loaded. The HTML must be escaped as a <![CDATA[...]]> section or by escaping the markup
entries (otherwise the plugin will not be valid XML). Further information on user interface
forms see 4 and 4.1.4
Adelard
265332806
Unclassified
13 July 2017
Unclassified
Page 6 of 12
3.1.4
<script>
This tag contains the script of your plugin which is used to handle the various events. The script
should be written as VBScript.
When the plugin is loaded, the script is loaded into its own self-contained module. Plugins
cannot have direct access to any data or code in any other plugin at run time.
It is usually helpful to specify this section as a <![CDATA[...]]> element to ensure mark-up
characters in your script do not cause problems in loading the XML content.
Further information on scripting ASCE is described in [1].
Optional attributes:
●
timeout=”0” – to prevent ASCE’s plugin engine from aborting long operations your
plugin may perform
●
language=”javascript” – plugin code may also be developed using javascript,
although no formal support for this is provided by Adelard.
4 Plugin user interface forms
User interface forms in ASCE plugins are specified as HTML.
4.1.1
Loading a plugin form
The sequence of steps followed on loading is as follows:
1. The ASCE plugin window is loaded (either explicitly when a script calls the
Plugin.LoadForm method, or implicitly when a user clicks on a DNR element in the
narrative field of a loaded Node Editor window).
2. The "innerHTML" property of the body element of the HTML document of the
plugin form is set to be the HTML supplied in the plugin.
3. The [formname]_onLoad() event is fired if it is defined. This enables the plugin
script to populate any fields in the plugin form with the appropriate values.
4.1.2
Handling events
After the form is loaded, a script may handle user interface events in the HTML. Further details
are provided in [1]
4.1.3
Unloading a form
Any form that is loaded using the LoadForm methods can be unloaded using the CloseForm
method.
Forms loaded by the user clicking on a DNR element cannot however be unloaded in this way.
These forms are only unloaded when the user clicks the "validate plugin", "update plugin
region" or the [x] button on the plugin window.
13 July 2017
265332806
Unclassified
Adelard
Unclassified
Page 7 of 12
4.1.4
Other ASCE Events
Other ASCE events that can be scripted by plugin developers are documented in [1].
5 Dynamic Narrative Regions (DNRs)
5.1.1
Introduction
One area of functionality that your plugin may provide is that of providing dynamic narrative
content in the narrative field of an ASCE node. Each such region in an ASCE node narrative
field is known as a Dynamic Narrative Region (DNR) element.
Dynamic Narrative Regions are blocks of HTML that are inserted into the narrative of a node.
There can be a number of DNR elements in any node in an ASCE network.
●
When a user clicks on a DNR in an ASCE node, ASCE will load the form specified
in the "plugin-form" attribute of the DNR HTML element.
●
When a user validates or updates a DNR (individually or globally), ASCE will run
the function specified in the "refresh-method" attribute of the DNR HTML Element.
DNR elements are very powerful and allow the plugin developer to build enhanced "content
plugins" which dynamically summarise or link to information held in other files or applications.
Applications of this technology can be used as follows:
●
Linking to Hazard log tools
●
Summarising other ASCE networks (including the inclusion of a selected node from
another ASCE network)
●
Linking to a summary query in a database (e.g. all records matching some criteria)
●
Providing a detailed summary of a particular record in a database
●
Connecting to a "web-service"
●
etc
If your plugin aims to provide DNR functionality, by convention it should add one or
more menu items to the "Insert-Plugin" menu in the node editor. When the user clicks on these
menus, the appropriate DNR content should be inserted at the selection point in the current node
editor document (Context.EditorDOM).
5.1.2
DNR specification
A DNR element is a standard HTML element with the following HTML attributes:
●
the class of the element is "ASCE-Plugin"
●
●
Adelard
e.g. class="ASCE-Plugin"
the tagname of the element must be table or a
●
e.g. <table
●
table tags are preferred to a tags as they are easier for the user to select and
move/cut/copy/paste to another position.
class="ASCE-Plugin"...>
or <a
265332806
Unclassified
class="ASCE-Plugin" ...>
13 July 2017
Unclassified
Page 8 of 12
●
the element must provide a plugin-name attribute to indicate which plugin will
handle its content. This should correspond to the filename of the plugin XML file
without the .xml extension.
●
●
the element must provide a plugin-form attribute to indicate which form is in the
plugin should be activated when the user clicks on the DNR element
●
●
e.g. plugin-form="frmPopupForm1"
the element must provide a refresh-method attribute which specifies the name of a
function (which takes no arguments and returns a string) which will be used to
validate and if necessary update the DNR element when required
●
5.1.3
e.g. plugin-name="my plugin v0.1a" (would be handled by the plugin with the
filename my-plugin v0.1a.xml)
e.g. refresh-method="GetCurrentContent"
Reserved attributes
The following attributes are reserved by ASCE.
5.1.4
●
class="ASCE-Plugin"
●
plugin-name="[chosen plugin]"
●
plugin-form="[chosen popup form to be displayed when user clicks on DNR]"
●
refresh-method="[chosen refresh function in the plugin to handle the DNR]"
●
last-author="[updated automatically by ASCE]"
●
last-edited="[updated automatically by ASCE]"
●
content-text-hash="[updated automatically by ASCE]"
●
plugin-checksum="[updated automatically by ASCE]"
DNR lifecycle
The lifecycle of a DNR element is typically as follows:
4. A network is opened, and a plugin containing one or more DNR elements is loaded
5. A DNR element is inserted by the user clicking on a menu item in the Node Editor
(under "Insert Plugin") - at which point the plugin would insert a block of HTML into
the current selection (an "empty" DNR element containing information for it to be
"fired-up")
6. A user clicks on the DNR element, at which point the appropriate plugin form is
loaded (the particular form used is specified as an attribute of the DNR element)
7. The user interacts with the user interface provided by the plugin form (e.g. by
choosing a file or selecting items from a drop down list etc)
8. The user "updates" the plugin:
●
13 July 2017
At this point ASCE runs the "refresh-method" function of the DNR element,
which provides the current content for the DNR element, and the DNR is updated
with this new content (see also 5.1.7 below).
265332806
Unclassified
Adelard
Unclassified
Page 9 of 12
●
●
In addition, ASCE then adds a number of additional attributes to the DNR
element:
●
a checksum of the textual content of the DNR element
●
a checksum of the source of the plugin
●
the current date (last updated date)
●
the username of the currently logged in user (Windows username)
The ASCE node narrative now contains an updated DNR element with up-to-date
information. If a user clicks on the DNR element again, the sequence from item 3
in this list is followed again.
9. The user "validates" the plugin:
1. At this point ASCE runs the "refresh-method" function of the DNR element,
which provides the current content for the DNR element. ASCE compares:
1. the stored DNR element text checksum is compared with a checksum of the
current DNR element text (this is to determine if the DNR element has been
manually edited or otherwise changed since it was updated)
2. the checksum of the new content is compared with the stored DNR element
text checksum (this is to determine if the content has changed since the DNR
element was last updated)
3. the checksum of the source of the plugin is compared with the stored
checksum of the plugin (this is to determine if the plugin has been edited
since it was last used (a security check))
2. If all of these checks pass, then ASCE reports that the content is currently valid.
10. At some later point the user may globally validate or update all plugins - at which
point ASCE runs step 5 or 6 above for all plugins in the current network.
5.1.5
Persisting state in a DNR element
Plugin developers can persist DNR state in the attributes or text of the DNR element. When
used in conjunction with the appropriate code in the plugin form’s onLoad() event, this enables
each DNR element to successfully "round-trip" the data and present a user interface that is prepopulated with the data of that plugin.
Base64Encode and Base64Decode functions are provided (see [1]) which can be used to
encode data in this attribute. The advantage of using Base64 encoding is that all data is
converted to alphanumeric characters (together with "=" character) only.
5.1.6
refresh-method
The value of the "refresh-method" of a DNR element is the name of a function that is used to
update a particular DNR element. For example:
<table class="ASCE-Plugin" refresh-method="GetCurrentContent" ...
In this example the "refresh-method" attribute specifies that the function GetCurrentContent
should be used to update this DNR element (N.B. it is not necessary for the function to be called
GetCurrentContent, other function names can be used as required).
The specification of the function used in "refresh-method" is as follows:
Adelard
265332806
Unclassified
13 July 2017
Unclassified
Page 10 of 12
Function RefreshMethodFunctionName()
'your code goes here
End Function
This function must take no arguments, and must return a string.
A simple example - which returns the an HTML table containing the current date - is given
below:
Function GetCurrentContent()
Dim s
'A simple DNR that returns today's date...
s = "<table class=""ASCE-Plugin" border=1 border-color=#a0a0a0 " & _
"plugin-name=""very simple plugin"" " & vbnewline & _
"plugin-form=""frmContentPlugin"" " & vbnewline & _
"refresh-method=""GetCurrentContent"" " & vbnewline & _
"><tr><td>Today's date is [" & Cstr(Date()) & "]</td></tr>" & _
"</table>"
GetCurrentContent = s
End Function
To access the attributes of the DNR element, you can use the ActiveDNRELement object. The
return value of the function is used to update the DNR element.
The format of the response string must be one of the following:
11. Usually a block of HTML "markup" is returned which will update the plugin region.
This markup should contain sufficient attributes for the DNR element to be refreshed
and ready for next use (e.g. all required attributes should be supplied). It can return
one of the following:
1. <table class="ASCE-Plugin" ...> or
2. <a class="ASCE-Plugin" ...>
12. An error-response XML fragment to indicate if there was a problem in getting the
current content. This is described below.
5.1.6.1
Specification of <table> and <a> responses
As described above, a "refresh-method" function usually returns a block of HTML markup. This
should have sufficient information for it to be reloaded if the user chooses to update or validate
the plugin.
The response of the example function above to update the current DNR element would be the
following block of HTML:
<table class="ASCE-Plugin" border=1 bordercolor="#a0a0a0"
plugin-name="very simple plugin"
plugin-form="frmContentPLugin"
refresh-method="GetCurrentContent"
><tr><td>Today's date is [22-Oct-2004]</td></tr>
</table>
13 July 2017
265332806
Unclassified
Adelard
Unclassified
Page 11 of 12
5.1.6.2
Specificaton of <response> responses
To indicate an error response you can use on of the following error codes to provide rich
feedback to the end user. If the function returns an error response it must be a wellformed XML
fragment of the following structure:
●
<response status="[error code]">Your error response message</response>
These error codes are adapted from the standard HTTP error codes.
Error code Interpretation
400
"Bad request"
403
"Forbidden"
404
"Not found"
405
"Method not allowed"
406
"Not acceptable"
408
"Timeout"
410
"Gone"
500
"Internal server error"
501
"Not implemented"
503
"Service unavailable"
For example a DNR element might not be able to update due to a lack of authentication, and
might return the following response tag:
<response code="403">Incorrect username and password supplied for the
MyDatabase.mdb database</response>
5.1.7
Content "flattening"
To ensure that plugins do not introduce invalid links into embedded content by supplying DNR
content that itself contains other references that may not be valid in the current context, content
that is inserted into a DNR element is "flattened" by ASCE as follows:
●
any table or span tags that are of class "ASCE-Plugin" (e.g. are themselves DNR
elements) are updated with the class attribute removed (to prevent them generating
error messages etc)
●
any embedded links (internal links within an ASCE network, class="ASCEEmbedded") are removed, where they reference nodes that do not exist in the current
network. This prevents the inadvertent inclusion of links that would not be valid in
the node that contains the DNR element. File links and URL links are not altered
6 ASCE Schemas
A key feature of ASCE is that it is extensible through the use of "schemas". A schema is a set of
definitions of properties that define a notation for use in ASCE. ASCE schemas are the means
by which the notations used by ASCE are defined. An ASCE Schema specifies the following:
Adelard
265332806
Unclassified
13 July 2017
Unclassified
Page 12 of 12
●
Node types (including name, shape, color, aspect ratio etc)
●
Status fields (user-editable attributes for each node)
●
Link types (name, colour)
●
Display rules (how the nodes are displayed based on status field values)
●
Check rules (structural properties that are considered desirable or anomalous for the
schema)
ASCE comes with some notations pre-supplied, but other notations can be developed by editing
the ASCE schema files (XML).
Further details about developing ASCE schemas can be found in the ASCE Schema
documentation [2].
7 References
Additional ASCE v4 API documentation is available from Adelard on request. Contact
[email protected] for details
[1]
ASCE Object Model API for ASCE 4.2, W/1873/3017/62
[2]
ASCE Schema developer documentation for ASCE 4.2, W/2083/12201/46
13 July 2017
265332806
Unclassified
Adelard