{"id":23158768,"url":"https://github.com/greendelta/olca-conversion-service","last_synced_at":"2025-09-04T15:34:30.126Z","repository":{"id":18498473,"uuid":"21694539","full_name":"GreenDelta/olca-conversion-service","owner":"GreenDelta","description":"A RESTful web-service for the openLCA data conversion functionalities","archived":false,"fork":false,"pushed_at":"2021-12-14T13:12:48.000Z","size":845,"stargazers_count":7,"open_issues_count":3,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-05T23:11:25.424Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GreenDelta.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-07-10T13:09:03.000Z","updated_at":"2023-12-21T20:07:43.000Z","dependencies_parsed_at":"2022-09-07T19:00:09.261Z","dependency_job_id":null,"html_url":"https://github.com/GreenDelta/olca-conversion-service","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/GreenDelta/olca-conversion-service","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GreenDelta%2Folca-conversion-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GreenDelta%2Folca-conversion-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GreenDelta%2Folca-conversion-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GreenDelta%2Folca-conversion-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GreenDelta","download_url":"https://codeload.github.com/GreenDelta/olca-conversion-service/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GreenDelta%2Folca-conversion-service/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270932556,"owners_count":24670240,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-17T02:00:09.016Z","response_time":129,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-17T22:27:29.968Z","updated_at":"2025-08-18T01:31:02.914Z","avatar_url":"https://github.com/GreenDelta.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# openLCA conversion service\nThis project provides a web-service for converting LCA process data sets. It is\na Java application using the [Grizzly HTTP Server](https://javaee.github.io/grizzly/)\nand the import and export functions of the\n[openLCA core modules](https://github.com/GreenDelta/olca-modules). Currently,\nthe conversion between the following data formats are supported:\n\n* [x] EcoSpold 1\n* [x] [EcoSpold 2](https://www.ecoinvent.org/data-provider/data-provider-toolkit/ecospold2/ecospold2.html)\n* [x] [ILCD](http://eplca.jrc.ec.europa.eu/LCDN/developer.xhtml)\n* [x] [JSON LD](https://github.com/GreenDelta/olca-schema)\n* [x] SimaPro CSV (*currently only as source format of a data conversion)\n\n## Installation\nIn order to install the application a Java Runtime Environment \u003e= 8 needs to be\ninstalled. Then, unzip the distribution package. It contains the application as\na single jar file, a basic web UI, and a configuration file. You can start\nthe application via the following command:\n\n```bash\njava -jar server.jar\n```\n\nOn a Linux server you probably want to start the server as a\n[background process](https://stackoverflow.com/questions/4797050/how-to-run-process-as-background-and-never-die)\nfrom a shell. One solution to do this, is to use `nohup`:\n\n```bash\nnohup java -jar server.jar \u0026\n```\n\nIf your shell does not return the process ID (to kill the process later) you can\nget it via:\n\n```bash\necho $!\n```\n\n### Configuration\nThe default configuration file looks like this (without the comments):\n\n```javascript\n{\n  // the application host\n  \"host\": \"localhost\",\n\n  // the port of the application\n  \"port\": 80,\n\n  // path to a folder which contains the reference data and a file cache \n  \"workspace\": \"./workspace\",\n\n  // an optional path to a folder with the web UI\n  \"ui\": \"./web\",\n}\n```\n\n#### Reference systems\nThe conversion service can be configured to run with different reference\nsystems where a reference system contains a set of reference data like\nelementary flows, quantities, units etc. and mapping files which are used in the\nconversion. The data of the reference systems are stored under the directory\n`refsystems` of the `workspace` folder. Each reference system is stored in a\nsub-folder of the `refsystems` directory and is identified by the name of this\nsub-folder. \n\nThere is at least one `default` reference system which is created automatically\non server startup if it does not exist. When a conversion request does not\nspecify a reference system, the `default` reference system is taken in the\nconversion. The data of a reference system are stored in a file `data.zip` in\nthe folder of the reference system. The content of the `data.zip` file should\nbe provided in the [openLCA JSON-LD format](https://github.com/GreenDelta/olca-schema)\nas produced by the openLCA export. Additionally, a set of mapping files (see\nbelow) can be provided in a sub-folder `mappings` in the data directory of the\nreference system.\n\nOn server startup, a data dump for each reference system is created if it does\nnot exist yet. For each conversion against a reference system the dump of this\nsystem is loaded into memory and used for the conversion. Thus, to update the\ndata of a reference system, just update the `data.zip` and mapping files,\ndelete the `dump` folder and restart the server.\n\n```\n- workspace\n  - refsystems\n     - default\n       + dump\n       + mappings\n       - data.zip\n     - myrefsystem\n       + dump\n       + mappings\n       - data.zip \n```\n\n#### Mapping files\nIn the `mappings` folder of a reference system, mapping files can be specified.\nThe mappings in these files are applied to the flows in the source format of\na conversion and are format specific:\n\n* EcoSpold 1: `ecospold_flow_map.csv`\n* EcoSpold 2: `ecospold_2_flow_map.csv`\n* ILCD: `ilcd_flow_map.csv`\n* SimaPro CSV: `sp_flow_import_map.csv`\n\nThe mappings in these files should map to the data in the `data.zip` that you\nprovide with the reference system (see above). For the EcoSpold 1+2 and ILCD\nformat, the mapping files are simple CSV files with the following columns:\n\n```\n0: UUID of the flow in the source format\n1: UUID of the reference flow in the database\n2: a conversion factor f: \u003camount reference\u003e = f * \u003camount source\u003e\n``` \n\nAs flows in the EcoSpold 1 format have no UUIDs, MD5 based UUIDs are calculated\nfrom flow attributes in this case. The format of the SimaPro CSV mapping file\nis specified [in the olca-modules](https://github.com/GreenDelta/olca-modules/blob/master/olca-io/REF_DATA.md#simapro-csv-flow-import-mapping)\nrepository. The folder [default_mappings](./default_mappings) contains the\nmapping files that the conversion service uses by default.\n\nAdditionally, these mappings can be overwritten in each conversion request by\nproviding a list of flow mappings directly in the conversion request: ...\n\n## How the conversion works\nA client sends a conversion request to the conversion server which includes an\nURL to the respective process data set, the format of this data set, and the\ntarget format to which this data set should be converted. The conversion server\nthen fetches all the required data from the data server using a format specific\nprotocol. The converted data set with all associated resources (e.g. flow data\nsets etc.) are cached on the conversion server and a link to this data set is\nsend back to the client:\n\n![How it works](./conversion-service.png)\n\nNote that the client could be itself the back-end of an HTTP server that sends\nback the link to another client. The following data provider are currently\nsupported:\n\n| Format | Data provider | Example URL |\n|--------| -------------|------------ |\n| EcoSpold 1 | Plain HTTP server providing the data set | [example from the Needs project](http://www.needs-project.org/needswebdb/scripts/download.php?fileid=4\u0026type=xml) |\n| EcoSpold 2 | Plain HTTP server providing the data set | |\n| ILCD | [soda4LCA](https://bitbucket.org/okusche/soda4lca) | [example from the ELCD database](http://eplca.jrc.ec.europa.eu/ELCD3/resource/processes/1a7da06d-e8b7-4ff1-920c-209e9009dbe0) |\n| JSON LD | [openLCA CS](http://www.openlca.org/collaboration-server/) | e.g. http://localhost:8080/ws/public/browse/gdelta/refdata/PROCESS/e33fb2ad-5db5-4ee7-9486-515fce6fd46d |\n\n\n## Building from source\nThis is a standard [Maven](https://maven.apache.org/) project using the Kotlin\ncompiler as Maven plugin. Thus you need to have Maven installed in order to\ncompile the project. Also, it depends on the [openLCA core modules](https://github.com/GreenDelta/olca-modules)\nwhich need to be installed first. For Windows, there is a build script\n`build.bat` which generates the distribution package:\n\n```bash\ncd olca-conversion-service\nbuild\n```\n\nThis will create the distribution package as `olca-conv_\u003cversion+date\u003e.zip` in\nthe `target` folder. To include the user interface, you need to also build it\nfrom source in the `ui` folder. We use [Gulp](https://gulpjs.com/) as build tool\nfor that:\n\n```bash\ncd olca-conversion-service/ui\nnpm install\ngulp\n```\n\nThe build script will package the UI in the distribution package if it can find\nit.\n\n\n## API\n\n### Conversion Request\n\n* **URL**\n\n  `/api/convert`\n\n* **Method**\n\n  `POST`\n\n* **Data Parameters**\n        \n  An JSON object that describes the conversion, e.g.:\n\n```javascript\n  {\n    // the URL to the source data set\n    \"url\": \"http://eplca.jrc.ec.europa.eu/ELCD3/...\",\n    \n    // the format of the source data set\n    // possible values: \"EcoSpold 1\", \"JSON LD\", or \"ILCD\"\n    \"sourceFormat\": \"ILCD\",\n    \n    // the target format into which the data set should be converted\n    \"targetFormat\": \"EcoSpold 1\"\n  }\n```\n\n* **Success Response:**\n\n  * **Code**: 200 \u003cbr /\u003e\n    **Content:** The conversion result as JSON object:\n\n```javscript\n{\n  // the name of the result package for getting all data set resources via\n  // result request; see below\n  \"zipFile\": \"e.g. 123...2434_ECOSPOLD_1.zip\",\n  \n  // the converted process data set\n  \"process\": \"xml or JSON\",\n  \n  // the format of the conversion result; \"EcoSpold 1\", \"JSON LD\", or \"ILCD\"\n  \"format\": \"EcoSpold 1\"\n}\n```\n\n* **Error Response:**\n\n  * **Code**: 501, Not Implemented \u003cbr /\u003e\n    **Content:** Message about unimplemented data conversion or unknown format.\n  \n  * **Code**: 500, Internal Server Error \u003cbr /\u003e\n      **Content:** conversion error\n\n\n### Get Conversion Result\n\n* **URL**\n\n  `/api/result/:file`\n\n* **Method**\n\n  `GET`\n\n* **URL Parameters**\n        \n  The file name of a conversion result, e.g. `\"123...2434_ECOSPOLD_1.zip\"`\n\n* **Success Response:**\n\n  * **Code**: 200 \u003cbr /\u003e\n    **Content:** A zip file.\n\n* **Error Response:**\n\n  * **Code:** 404, Not Found \u003cbr /\u003e\n    **Content:** `\"File \u003cname\u003e does not exist.\"`\n  \n\nLicense\n-------\nUnless stated otherwise, all source code of the openLCA project is licensed \nunder the [Mozilla Public License, v. 2.0](http://www.mozilla.org/MPL/2.0/). \nPlease see the LICENSE.txt file in the root directory of the source code.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgreendelta%2Folca-conversion-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgreendelta%2Folca-conversion-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgreendelta%2Folca-conversion-service/lists"}