CIM Service

This is a server which provides an OpenAPI REST API for CIMpy. This can be used to upload and process grid data specified by the IEC61970 standard.

The server is based on connexion which itself builds upon flask. The API is specified in the openapi.yaml.

Requirements

• Python 3.5.2+
• CIMpy python packages and dependencies specified by requirements.txt. Install them with pip3 install -r requirements.txt

Usage

To run the server directly, please execute the following from the root directory:

python3 server.py

To run in docker:

docker run --name=redis-master redis
docker build -t cim-service .
docker run cim-service

To run in Kubernetes:

This will become easier when we have uploaded the docker containers to docker hub.

Install redis

helm repo add bitnami https://charts.bitnami.com/bitnami
helm install redis bitnami/redis --values=helm/redis/values.yaml

Install docker registry

docker run -d -p 5000:5000 --restart=always --name registry registry:2

Install cim-service

docker build -t cim-service .
docker tag cim-service:latest localhost:5000/cim-service:latest
docker push localhost:5000/cim-service
helm install cim-service helm/ --values helm/values.yaml

For manual interaction and a rendered specification open http://localhost:8080/ui/ in your Browser.

Development:

Notes for developers:

• The repository contains set of vscode configurations at (.vscode)[.vscode/]

Code Structure

The server.py invokes the connexion server with the openapi.yaml as argument. The connexion server then parses the yaml and provides the general server functionality. The developer then has to provide the callbacks to the service which should be called by the API. The name of the callback function is specified in the openapi.yaml as operationID (example: operationId: cimadapter.get_models). The basic job is then to provide these callbacks.

The convention for the ANM4L server is to put the callbacks into the project root with a name like XYZadapter.py.

The openapi-generator also generates a set of classes which correspond to the schema from the openapi.yaml. These can be used to ease the parsing of requests and the generation of responses. All of these classes are located at models.

Code Generation/API Changes

The fundamental code structure is generated with the OpenAPITool openapi-generator. If the openapi.yaml has changed, you can run the generate_api_code.sh script to generate these files again.

However, these files must be adapted manually! The quality of the generated code is not sufficient. Examples of what must be adapted:

• openapi-generator puts all the server files into a folder openapi, which is this an unnecessary hierarchy. You need to copy the generated files to the corresponding folder in the repository and fix the import lines in the python code.
• openapi-generator generates some useless files. Not all "models" are needed for the implementation
• openapi-generator creates sometimes unnecessary imports. Characteristic examples: connexion, six, json. Also sometimes files are imported twice.

Recommended approach:

Generate the files and then use a diff editor such as meld to selectively import the changed code. Example:

meld generated/openapi_server/models models

Testing

This project uses pytest for integration tests. All integration test can be found in test. To invoke it manually call:

pytest  -cov test/

(pytest should easily integrate into your IDE...)