Link to external references - ECP-3.1

[jonathan.carter]

ECP 3 is split into two parts - ECP 3.1 and ECP 3.2 - and introduces the capability to capture references to external documentation for any element in the repository. Additionally, links to those references will be made available in Essential Viewer reports.

ECP 3.1 Covers the required extensions to the meta model.

Proposed changes:

• Add a slot to the EA_Class meta class to hold a string for a URL to the external documentation/reference
• Using either the URLWidget or a TextWidget on the Form for each class, introduce the field above the External Repository References attribute on each EA_Class form.

These extensions will be provided by a meta model Protege script.

[jonathan.carter]

To further develop the requirements for the ability to capture references to external (to Essential) items, e.g. documentation, it should be possible for any element in the Essential model to have multiple references to external things, via a URL.

Therefore, this extension is revised to perform the following changes to the meta model:

• Create a new meta class to manage each reference to an external item reference
• Create a new multi-instance slot on each EA_Class to hold these external item references

Jonathan

[jonathan.carter]

Here is the proposed meta model extension for ECP-3.1

This adds a new class, External_Reference_Link and a new slot to EA_Class (and therefore all subclasses of EA_Class), external_reference_links that is a multi-instance slot to manage instances of External_Reference_Link. An inverse slot from External_Reference_Link to the EA_Class instances is also included.



Jonathan

[jonathan.carter]

A candidate release for this meta model extension is ready to be downloaded and evaluated.

Download the meta model extension and the sample repository (with this extension applied) from the Share area.

Meta Model

Sample repository

The meta model extension is a Protege Script Tab script that you should download and save to your workstation. Then, open Protege and open your Essential repository project.
Go to the Script Console Tab.
type the following at the prompt:

execfile("<full file path>/linkToExternalSource.txt")

Note: the Unix-style '/' even on Windows.
Once the script has completed, you will see a success message, which means that the meta model extension has been applied.
This script updates all classes in the EA_Class hierarchy and may take many seconds to run.

Jonathan

[Kevin Campbell]

Is it possible to configure this extension to be aware of proxy servers? I can see that it's attempting to render the page after entry of the URL, but never succeeds because I'm behind a proxy server. I can close the window but subsequent performance of Protege suggests that perhaps a thread is still out there attempting to connect.

Kevin

[jonathan.carter]

Hi Kevin,

I've had a look into this but I'm not sure I've got a perfect answer for this one.

Within the modelling side, in Protege, we've set the Form for the External Reference Link instances to use the URLWidget, which is out of the box from the Protege team.
I've checked all the options on this widget and had a look at the source code and documentation for it but there's nowhere with this widget to set it up to use a Proxy.

You could add some properties to your Protege Preferences that should get Protege as a whole to use the proxy, as follows:

Property ---- Value
http.proxyHost ---- <Your proxy server hostname>
http.proxyPort ---- <Your proxy server port number>
http.proxyUser ---- <Your user ID>
http.proxyPassword ---- <Your password>

To take effect, you will have to re-start Protege once you've set these up.

However, I'm not sure what impact this will have on the Essential Architecture Reporting tab, which also uses HTTP to communicate with Essential Viewer. Probably worth trying but if the Reporting tab can no longer see Viewer, you'll need to remove these properties.
Note also, that if your proxy server requires any form of authentication, the above, properties approach isn't very secure etc. and may not handle more complex authentication such as Windows NT challenge-response.

Of course, as Protege is open-source, it's possible to create an updated version of the URL widget that DOES provide support for proxy servers that can handle the authentication etc.

Initially, we had considered just using a String widget for the URL of the external link but realised that if we used the URL widget you would at least get some confirmation that the URL you'd specified was correct. The main idea behind this meta class, though, was to provide these links within Viewer. As it's a relatively recent addition, most of the views that are provided don't yet make use of this but it's a simple extension of any of the views to check for an External Instance Link on the instance you're rendering, and if there is one, provide a simple hyperlink to the external reference. As you're already in your browser, any proxy settings are already defined and you will be able to navigate to the referenced external content.

So, in summary, this was originally designed as a Viewer-side capability with the URL widget as a nice-to-have confirmation thing. However, you've raised a great scenario that makes sense to add to the requirements for this ECP.

I'm not sure to what extent this helps but let me know what you think, or if you'd like some help with the query to add the External References to you views.

Jonathan

[Kevin Campbell]

Hi Jonathan

There's no simple answer I don't think. In practice we configure our browsers to bypass the proxy for internal addresses, but that's probably going beyond what can be expected of the URL widget. We use the external reference in two scenarios: a genuinely external reference to information related to a technology product or application provider, and also for internal links to scanned documents supporting software contracts.

I think we'll live with it the way it is; the biggest value is from within Viewer and the browser settings will take care of that.

Thanks

Kevin