GroIMP can be started as an HTTP API that provides a generalized set of commands allowing interaction from other software. Currently a Python and a R library are provided but any software capable of HTTP requests could interact with GroIMP. This approach can be used to automatically start a simulation and interact with it during the execution.
Starting with GroIMP 2.1 the API application is included and can be started with the following command:
java -Xverify:none -jar core.jar --headless -a api
This starts a local web server, the default port is 58081, this can be changed either in the preferences panel in the GUI or by adding -Xport=58080 to the command above.
A more in-depth explanation of GroIMP arguments can be found here.
Now the API can be reached at http://localhost:58081/api. This will return an error message since no command was given.
Every command acepted by the API server follows the schema below:
<host>:<port>/api/<ref>/<command>?<key>=<value>
Depending on the command there can be several key value pairs as well as a request body containing decode file. The list of all available commands can be found here.
The GroLink API does not distinguish between different request methods.
The GroLink API can be used to manage multiple files and is started without a specific project. To do so a main workbench is used which can be addressed using the reference (ref) “app” in the HTTP request. This main workbench can create new workbenches, load provided projects or run embedded examples. The main workbench is also able to list all currently opened workbenches.
In any cases it returns a workbench id that can then be used to address the new workbench with the ref wb/<id>. A request send to the sever will be forwarded directly to the referenced workbench, where it is either executed or if the workbench is busy wait. After the completion of the command from the request the request response to the client. In this way the API server has never to wait for any execution to be completed and can run non blocking.
There are two different ways to open a project,either the absolute path on the file system is provided and the server can reach this file or the content of the file (this only works with gsz) is decoded and added to the body of the request. The second way has the advantage that it works without a shared file system, for instance on docker, kubernetes or a remote sever.
After transferring the file both commands work similarly, they open a workbench the same way as in the GUI or the CLI and then return a workbench ID. ( command description)
Creating a new workbench will end in the same result as clicking file > new in the GUI. By default the new workbench will be using the new RGG template, yet it is possible to provide the name of another template that should be used. The templates can be listed with a specific command.
Listing and loading examples works similar to creating a workbench.
Saving the project is a workbench command that has to be addressed to the workbench that is suppose to be saved. If a path is provided the project will be saved at that location, otherwise if no path is provided the decoded gsz file will be returned to the client. This allows to save project that where executed on other file systems. ( command description)
It is possible to send the name of an RGG function to the project and receive the output of the XL console as a result (command). Additionally it is possible to list all RGG functions.
In a similar fashion it is possible to run XL queries, which are then executed in a environment similar to the XL-Console. Only with the limitation that in contrast to the console it is not possible to save variables between two calls. While it is possible to send the XL query as an URL parameter, for more complex queries it would be recommended to use the request body since several characters of the XL syntax are effecting urls.
The API can provide JSON based representation of the project Graph.
The JSON format uses two dictionaries to represent the graph: “projectgraphNodes” and “projectgraphEdges”. The projectgraphNodes list holds the nodes themselves with their node id. This ID is again used in triples of the projectgraphEdges list to define the source (first entry) and the destination (second entry). The third value in the triple represents the edge bits to seperate for example successor and branch. Finally the projectgraphRoot represents the root node of the project graph.
The source files of a project can be listed, read, removed, added or updated.
Adding a file can be done via a path or as a request body, similar to opening a project. Updating a file will replace the content of the given file with the body of the request, meaning to change only one line it would be reasonable to first read the file, change it locally and then send it back.
Importing and exporting can both be done either via path or within the request/response. For the second case the extension is required as an argument.
While data handling through external files for instance for logging, is still possible, this would not be that suitable for a setup where the API server and the client are not running on the same system. In that case a possible way is to just add input data files as source files to the project and read them from RGG.
To receive data from the simulation one possible way is to use datasets, the API has specific commands to list and read datasets.
Due to the generalized approach using registry paths, the HTTP commands are quite long and complex. To ease this and the management of the workbenches, client libraries are provided in R and Python.
The GroPy library provides an object orientated Python3 implementation. It can be installed using the pip installer using the package registered at the repository:
pip install GroPy --index-url https://gitlab.com/api/v4/projects/50527255/packages/pypi/simple
Additionally it is possible to only get the file GroPy.py from the repository and link it directly.
The library is based on three classes: Call, GroLink and WBRef.
A call object represents a possible request to the API server and can be send with the run function and the results can be interpreted with the read function. The run function returns the object itself to enable a short writing form: myCall.run().read(). The read function can return either a file, a json-String or a WBRef object, depending on the command.
The GroLink class holds the connection to the API server and can create different calls for Project Management (e.g. create or open new workbenches), most of these commands return WBRef objects (List of Python commands). It is initialized with the address to the API server.
A WBRef object represents the connection to a workbench, it does not hold any information other than the id of the workbench and the link to the API server. This object provides function to create calls for the Project Interaction.(List of Python commands)
Due to the design of the API server it is possible to send request regarding commands that where not originally part of the GroLink project. To be able to address this command from the python library the function createAppCall(self, command, returnType=Call.JSON_RETURN, parameters=None, content=None) or createWBCall(self, command, returnType=Call.JSON_RETURN, parameters=None, content=None) can be used.
link = GroPy.GroLink("http://localhost:58081/api/") link.createAppCall("/path/to/the/command") WBref1 = link.createWB().run().read() WBref1.createWBCall("/path/to/the/command")
The GroR package is not added to any public repository and must therefore be installed by hand. This can be done in different ways depending on your needs.
It is possible to download the GroR.R file from this repository and link it to your R file with this code:
source(“path/to/GroR.R”)
The releases contain packages that can be installed directly with either the R command:
install.packages(“path/to/GroR_x.x.x.tar.gz”, repos = NULL, type = “source”)
Alternatively, it is possible to install the package with the R Studio package manager by selecting “install from package archive file”.
The library comes with two sets for functions, one set with the prefix “GroLink.” and one with the prefix “WBRef.”. The GroLink.* functions take the address of the API server as first input and provided a implementation for most Project Management requests. Most of them return wb objects which are the first needed parameter for the WBRef.* functions. These functions implement the requests for Project interaction. A list of all avialable commands can be found in the readme of the repository.