Adding a Tool

To add a tool to the Education Platform there are two steps that must be completed:

Create and deploy the backend tool services
Create and make available the static configuration file and resources

The following sections document each step.

Tool Service

Tool service components provide the functionality that would typically be provided by a developer's local machine environment for executing MDE programs. The education platform's tool services are stateless FaaS and implement the ITool interface that is an asynchronous http json request and response.

All JSON must conform to ECMA-404 be UTF-8 encoded and appropriately escaped. Most languages have standard libraries to support this for example javascript JSON.stringify().

Any technology that supports these protocols can be use to implement a tool function for the education platform provided they comply with the following request and response specifications.

Request Specification

Key	Value	Multiplicity
[function parameter name]	File contents required for the action	0..*
language	Tool language id	1..1

Function Parameter Name

The total number of function parameter name attribute(s) and their key names are defined by the tool function. They are the file contents encoded as UTF-8 strings that are the inputs required to generate the function's output. The values of each file will be the contents of a panel mapped by the playground activity configuration and their names are defined by tool configuration file.

To improve file type compatibility with tool services, the education platform has in-built support for file type conversion. When an action function has been triggered, the platform compares the input activity panel file types (specified in the activity configuration file) with the types of the tool service function parameters (specified in the tool configuration file). For any input file types that do not match, conversion functions are first invoked to convert the file type to the corresponding type of the action function's input. This means that tool providers can select and fix the most suitable file types for their tool and only conversion functions need be added to support additional file types.

Language

The language attribute is the language identifier of the source panel initiating the tool function. It can be used by the tool function to to handle multiple languages as single service.

Request Example

The OCL toolfunction has four attributes metamodel, constraints, model, and language. The first three attributes metamodel, constraints, and model are the contents of the platform panels in emfatic, ocl, and flexmi formats respectively. The fourth language attribute specifies that the constraints should be processed as complete OCL.

{
	"metamodel":"@\"http://www.eclipse.org/OCL/Import\"(ecore=\"http://www.eclipse.org/
			emf/2002/Ecore\")\n@namespace(uri=\"http://www.eclipse.org/mdt/ocl/oclinecore/
			tutorial\", prefix=\"tut\")\npackage tutorial;\n\nclass Library {\n\tattr String[1] 
			name;\n\n\t@\"http://www.eclipse.org/OCL/Collection\"(nullFree=\"false\")\n\t!ordered 
			val Book[*]#library books;\n\n\t@\"http://www.eclipse.org/OCL/
			Collection\"(nullFree=\"false\")\n\t!ordered val Loan[*] loans;\n\n\t@\"http://
			www.eclipse.org/OCL/Collection\"(nullFree=\"false\")\n\t!ordered val Member[*]#library 
			members;\n}\n\nclass Book {\n\tattr String[1] name;\n\tattr EBigInteger[1] copies;
			\n\tref Library#books library;\n}\n\nclass Member {\n\tattr String[1] name;\n\tref 
			Library#members library;\n}\n\nclass Loan {\n\tref Book[1] book;\n\tref Member[1] 
			member;\n\tattr EDate date;\n}\n\n",

	"constraints":" import 'http://www.eclipse.org/mdt/ocl/oclinecore/tutorial'\n \n 
			package tutorial\n \n context Book\n \n inv SufficientCopies : library.loans-
			>select(book=self)->size() <= copies\n \n \n \n endpackage",
	
	"model":"<?xml version=\"1.0\" encoding=\"ASCII\"?>\n<tut:Library xmi:version=\"2.0\" 
			xmlns:xmi=\"http://www.omg.org/XMI\" xmlns:tut=\"http://www.eclipse.org/mdt/ocl/
			oclinecore/tutorial\" name=\"lib\">\n  <books name=\"b1\" copies=\"1\"/>\n  <books 
			name=\"b2\" copies=\"2\"/>\n  <books name=\"b3\" copies=\"3\"/>\n  <loans book=\"//
			@books.0\" member=\"//@members.2\"/>\n  <loans book=\"//@books.0\" member=\"//
			@members.2\"/>\n  <loans book=\"//@books.1\" member=\"//@members.1\"/>\n  <loans 
			book=\"//@books.2\" member=\"//@members.0\"/>\n  <members name=\"m1\"/>\n  <members 
			name=\"m2\"/>\n <members name=\"m3\"/>\n</tut:Library>\n",
	
	"language":"oclcomplete"
}

Response Specification

Key	Value	Multiplicity
output	String	1..1
[diagram]	SVG image	0..1
generatedText	Output file text	0..1
generatedFiles	GeneratedFile	0..*
error	Error log text	0..1

Note - The four response options are mutually exclusive.

Output

Textual output from the execution of the tool function, for example, the console output.

Diagram

Any attribute that contains the diagram keyword will be recognised and processed as a diagram by the platform. The expected diagram image format is SVG.

Generated Text

The output file contents generated by the tool function as a string.

Generated File

The generated file contents and path.

Key	Value	Multiplicity
path	String	1..1	The file path
content	String	1..1	The file text

Error

Textual log of any errors that occur during execution of the function.

Response Example

Response with textual output:

{
    "output": "\n2 - org.eclipse.emf.ecore: Diagnosis of 1 objects.\n\t2 - org.eclipse.emf.ecore: 
    		The 'Book::SufficientCopies' constraint is violated for 'Library lib::Book b1'"
}

Response with svg diagram:

{
    "targetModelDiagram": "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?><svg>
					...svg contents...
  				</svg>",
    "output": ""
}

the SVG contents have been removed for clarity

Response with multiple generated file output:

{
    "generatedFiles": [
        {
            "path": "../src/file1.java",
            "content": "..."
        },
        {
            "path": "../src/file2.java",
            "content": "..."
        }
    ],
    "output": ""
}

Note - To display multiple files the tool should use a panel definition of type OutputPanel with the language value set to multi see paneldef for details.

Java Based Implementation

Existing examples of tool services can be found in the platformtools repository. The examples are implemented using Java and use the google cloud functions for the http handling and gcloud deployment.

The following diagram shows the main packages and classes of a tool service. Each package should have its own maven module. As a tool provider you are responsible for implementing everything in the [toolname]function package. There is a maven archetype for setting up this project structure and quickly getting setup to develop your tool service here.

The core package provides the abstract class MdeNetToolFunction that needs to be implemented by your tool's Run[toolname]Function class.

A tool function's Run[toolname]Function must implement the expected tool functionality using the parameters from the request to generate the response.

Eclipse Based Tool Support

For tools that have complex dependency requirements and are not available in main maven repositories adding an additional package and corresponding maven module may be necessary. The following class diagram shows the structure with the added tool package.

The tool package [toolname] provides a run function that the run package invokes to generate the response.

This package structure separates the dependencies required during a tool's execution from the tool service http functions and enables the tool specific dependencies to be separately built and bundled together for the tool service. For eclipse this means using the tycho maven plugin to resolve dependencies from eclipse p2 repositories specified in a *.target file.

Maven Archetype

Template [ToolName]function and [ToolName] packages can be generated using the MDENet maven archetypes to use as a starting point for your tool service.

Checkout the mdenet/platformtools repository.
Build the tool services which include the archetypes using the following command from the ./platformtools/services directory.

mvn -Pall clean install

Generate a tool function package using the following command replacing TOOL_NAME with the name of your tool.

mvn archetype:generate \
        -DtoolName=TOOL_NAME \
        -DarchetypeGroupId=com.mde-network.ep.toolfunctions \
        -DarchetypeArtifactId=com.mde-network.ep.toolfunctions.archetypes.toolfunction

If you are creating a tool service that is Eclipse based or has complex dependency requirements, generate a tool package using the following command.

mvn archetype:generate \
        -DtoolName=TOOL_NAME \
        -DarchetypeGroupId=com.mde-network.ep.toolfunctions \
        -DarchetypeArtifactId=com.mde-network.ep.toolfunctions.archetypes.tool

Implement your tool's run functions.

Configuration File and Resources

An important user interface component of the education platform is the Panel. They are comparable to the editor windows of a desktop Integrated Development Environment (IDE) and display content to the user specified by an activity. The following diagram shows the main features of a Panel.

There are three main areas of a panel that are customisable title and icon, buttons, and content. The title and icon identify the panel to the user. The icon is specified by the tool and the title is specified by the activity. The buttons are interaction points that can perform actions on the panel contents or display supplementary information such as documentation. The default set of buttons displayed on a panel are specified by the tool. Finally, panel contents displays files from the activity for editing or displays the results of a completed action. The tool specifies the appearance of the presented panel contents by defining the highlighting rules for its language.

The configuration file and resources are what define the three panel areas of an education platform tool service. The configuration file defines the tool functions and the panels that are available for a platform activity to use. The tool's resource files include highlighting rules for its languages and icon images used for its panels.

The platform expects the layout of the static tool files of an activity to be as follows.

├── icons
|   └── *.png
├──config.json
├──highlighting.js
└──icons.css

Configuration File

Note that a VSCode extension is now available to support creation of the configuration file.

tool
- id
- name
- functions
  - id
  - name
  - parameters
    - name
    - type
    - instanceof
  - returntype
  - path
- paneldefs
  - id
  - name
  - panelclass
  - icon
  - language
  - buttons
    - id
    - icon
    - hint

Tool

Top-level configuration file object

Key	Value	Multiplicity
id	String	1..1	A unique string used for identification.
name	String	1..1	The text used for display.
functions	Function	0..*	Array of Function objects.
paneldefs	PanelDef	0..*	Array of PanelDef objects.

Function

The function object describes a tool service's function, including its file type information. The platform uses the function object to validate requests when invoking a tool function and determine if any type conversions are required prior to to its invocation.

The parameters of a function object should directly correspond to a tool function's request specification parameters.

Key	Value	Multiplicity
id	String	1..1	A unique string used for identification.
name	String	1..1	The text used for display.
parameters	Parameter	0..*	Array of Parameter objects.
returntype	String	1..1	The type of the function's return value.
path	String	1..1	The function's endpoint url.

Parameter

The parameter object describes a tool service's function parameter by its name, type, and metamodel parameter reference.

Key	Value	Multiplicity
name	String	1..1	Name of the parameter.
type	String	1..1	The parameter's type.
instanceof	String	0..1	Reference to the parameter's metamodel by parameter name.

PanelDef

The panel definition object specifies a panel defining each of the customisable areas. There are four classes of panel that determine a panel's primary behaviour: program, console, output, or composite.

Program panels provide an ace editor with syntax highlighting for a file of an activity.

Console panels display textual output from a tool that would usually be displayed by a terminal.

Output panels display the results of an action function. The output panel can display multiple outputs when the language value is set to multi and the tool contains generatedFiles see the response spec for details.

Composite panels enable the hierarchical structuring of panels. They contain child panels which can include other composite panels. Child panels' visibility can be toggled using ToggleButtons with the visible panels filling the available space.

Key	Value	Multiplicity
id	String	1..1	A unique string used for identification.
name	String	1..1	The text used for the panels title.
panelclass	String	1..1	The type of panel: ProgramPanel, ConsolePanel, OutputPanel, or CompositePanel.
icon	String	1..1	Reference to the name of the icon to use. See Icons for details of where icon files should be located.
language	String	0..1	Reference to a set of language highlighting rule. See Highlighting Rules for details on language highlighting rules.
buttons	Button	0..*	Array of button objects.

Button

The button object describes a button to be displayed on the panel. There are two classes action and help. Action buttons when clicked triggers a tool service's backend function with the parameter to panel mapping given by the activity. Help buttons when clicked display a webpage.

Key	Value	Multiplicity
id	String	1..1	A unique string used for identification.
icon	String	1..1	Reference to the name of the icon to use. See Icons for details of where icon files should be located.
hint	String	1..1	The tooltip text to display.

Plus any required keys from one of the button concrete classes ActionButton or HelpButton.

ActionButton

Key	Value	Multiplicity
actionfunction	String	1..1	Reference to a function id from the functions defined in tool.functions.

HelpButton

Key	Value	Multiplicity
url	String	1..1	The web address to display.

ToggleButton

Key	Value	Multiplicity
internal	String	1..1	The internal action to perform: toggle.
targetPanel	String	1..1	Reference to the id of a panel.

Resources

Icons

Icon image files 16x16 pixels in size as gif, png or svg format should be placed in a directory named icons.

In the icon.css file an entry for each icon image should be added as follows where NAME is the icon's filename and EXT is the three letter file extension e.g. png.

.mif-NAME::before {
    content: url("./icons/NAME.EXT");
}

Highlighting Rules

The highlighting.js is a bundled javascript file of all the ace editor highlighting rules for the languages defined by the tool.

Refer to the ace documentation for the highlighting rule format.

See the platformtools static.* e.g. static.epsilon for examples of tool highlighting rules.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly