{"id":19243220,"url":"https://github.com/odpi/egeria-samples-api","last_synced_at":"2025-04-21T09:32:54.011Z","repository":{"id":50889606,"uuid":"504446408","full_name":"odpi/egeria-samples-api","owner":"odpi","description":"A collection of samples illustrating the different APIs of Egeria.","archived":true,"fork":false,"pushed_at":"2025-03-01T09:10:13.000Z","size":56415,"stargazers_count":12,"open_issues_count":5,"forks_count":8,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-04-01T12:04:25.565Z","etag":null,"topics":["egeria"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/odpi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":"governance-program/README.md","roadmap":null,"authors":null,"dei":null}},"created_at":"2022-06-17T08:04:59.000Z","updated_at":"2025-03-18T13:46:23.000Z","dependencies_parsed_at":"2024-04-22T02:28:11.979Z","dependency_job_id":"ea024ad1-7dcc-4fcb-bf05-58832a312003","html_url":"https://github.com/odpi/egeria-samples-api","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/odpi%2Fegeria-samples-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/odpi%2Fegeria-samples-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/odpi%2Fegeria-samples-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/odpi%2Fegeria-samples-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/odpi","download_url":"https://codeload.github.com/odpi/egeria-samples-api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250032241,"owners_count":21363801,"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","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":["egeria"],"created_at":"2024-11-09T17:17:07.433Z","updated_at":"2025-04-21T09:32:48.968Z","avatar_url":"https://github.com/odpi.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- SPDX-License-Identifier: CC-BY-4.0 --\u003e\n\u003c!-- Copyright Contributors to the ODPi Egeria project. --\u003e\n\n# Egeria API Samples (egeria-samples-api)\n\nThis repository is a collection of samples that show how to use Egeria's metadata\nmanagement and governance APIs to set up and run a sustainability initiative at\nthe fictitious company\n[Coco Pharmaceuticals](https://egeria-project.org/practices/coco-pharmaceuticals/).\n\nSustainability reporting is increasingly required by governments and financial institutions. \nCompanies are encouraged to set targets to reduce their emissions \nand to report on their progress towards these targets. \nThe [Greenhouse Gas Protocol](https://ghgprotocol.org/) defines the foundational methods for this process.\n\nImproving the sustainability of an organization is a continuous process of:\n\n* reviewing its operations\n* measuring the impact of these operations\n* aggregating these impacts across locations and divisions of an organization\n* reviewing, certifying and reporting on sustainability\n* setting targets to improve sustainability\n* taking action to achieve these targets\n* measuring the change\n* *repeat*\n\nAll parts of the organization need to be involved.\nInvestment in automation around this process is also important\nto ensure ongoing improvements to data collection and remediation actions that\nimprove the sustainability of their operations becomes embedded in the business,\nnot something they focus on from time-to-time.\n\nThe samples are divided into the following groups:\n\n* [Extending the governance program](#extending-the-governance-program) to include a sustainability focus.\n* [Creating an inventory](#creating-the-operations-inventory) of Coco Pharmaceuticals operations.\n* [Finding and cataloguing the data](#finding-and-cataloguing-data) that describes the impact of their operations.\n* [Validating and publishing sustainability report](#building-the-sustainability-dashboard) to continuously monitor the sustainability status of Coco Pharmaceuticals. \n* [Assessing and improving IT operations](#assessing-and-improving-it-systems).\n* [Sustainability Webpages](#sustainability-webpages)\n\n## Bringing the samples onto your local machine\n\n### Just want to build and run\n\nIf you want to just build and run the samples, all you need to do is clone this\ngit repository.  Create a new directory (folder) on your machine, open a terminal (command) window; change into your new directory and enter:\n\n```\ngit clone https://github.com/odpi/egeria-samples-api.git\n```\n\non the command line and press *return*. The code is copied into your new directory, and you're ready to build or load it into an IDE.\n\n### Wanting to contribute new code and documentation\n\nNew contributions are added to the git repository using a *Pull Request* from a personal *Fork*.  If you want to contribute to this git repository, then you need to create a fork of the repository and then create a clone of the repository from your fork.\n\n* If this is the first git project you have setup, you need to configure the email address and name using the commands below. The email address should match the email you use for github so that your contributions are recognized.\n```\ngit config --global user.name 'My Name'\ngit config --global user.email 'myuser@myemail.org'\n\n```\n* Go the repository's page on Github at https://github.com/odpi/egeria-samples-api and click on 'Fork' towards the top right of the page. This creates your own copy of the repository which is where you'll keep your work in progress.\n* Next, clone the repository (this copies it down to your local environment):\n    ```\n    git clone https://github.com/\u003cyourGitUserId\u003e/egeria-samples-api.git\n    ```\n* Finally add an additional 'remote' - this makes it easier to retrieve updates other people may have made to the repository - which you'll need to do before pushing a PR.\n    ```\n    git remote add upstream https://github.com/odpi/egeria-samples-api\n    ```\n\n## Building the samples\n\nMost of the samples are written in Java, although there are a couple that are in python.\n\n### Working with Java\n\nEgeria requires version 11 of Java, but also supports version 17, which is the latest Long Term Service release (LTS).\n\nYou will need a Java Development Kit (JDK) installed on your machine in order to build the Java samples. (A JDK will include a JRE.)\n\nThere are various JREs/JDKs available, and you may even have one pre-installed on your system. You can check if java is already installed by running the command `java --version` from the command-line.\n\nJava can be installed by:\n\n* Downloading the OpenJDK 11 (LTS) HotSpot JVM from [Adoptium](https://adoptium.net/en-GB/installation/).\n* Running the installer that is downloaded.\n\nAlternatively you may wish to install from your package manager such as homebrew on MacOS.\n\nThe java samples are built using gradle.  This will start to run automatically when you load the project into an IDE such as IntelliJ.  Alternatively, gradle will run from the root directory of the downloaded project using the following command:\n\nFor Linux, macOS:\n```\n./gradlew build\n```\n\nOr for Windows:\n```\n./gradle.bat build\n```\n\nSamples that need some work on are described in the [GitHub Issues](https://github.com/odpi/egeria-samples-api/issues) for this repository.\n\n### Working with Python\n\nEgeria uses version 3 of python.  There are various mechanisms for acquiring python for your machine.  You will need the following packages to be installed.\n\n* csv\n* time\n* os\n* urllib3\n* requests\n* pprint\n* json\n\n## Running the samples\n\nEach sample is located in its own directory.   The [samples-ensemble](https://github.com/odpi/egeria-samples-api/tree/main/samples-ensemble) module will run all the Java samples.\n\nThe samples are all client applications that call a [Metadata Access Server](https://egeria-project.org/concepts/metadata-access-server/) running on the [Egeria OMAG Server Platform](https://egeria-project.org/concepts/omag-server-platform/).  The metadata repository is preloaded with an [open metadata archive](https://egeria-project.org/concepts/open-metadata-archive/) that contains sample metadata from Coco Pharmaceuticals.  This archive is called [CocoComboArchive.json](https://github.com/odpi/egeria-samples/blob/master/content-packs/CocoComboArchive.json) and [can be loaded](https://egeria-project.org/features/metadata-archiving/overview/#loading-open-metadata-archives) as part of the metadata access server's startup configuration, or later, once the server is running.\n\n![running samples](docs/running-egeria-samples.png)\n\nWhether you choose to run a sample individually or through *samples-ensemble*, you need to supply three pieces of information:\n\n* The *serverURLRoot* of the OMAG server platform.\n* The *serverName* of the metadata access server\n* The *userId* to use on the calls.\n\nThis information is provided from the Egeria deployment environment.\n\n## Structure of the samples\n\nThe java samples call an Egeria client, which in turn calls the REST API of Egeria.  The Javadoc for the clients is published here: [https://odpi.github.io/egeria/index.html](https://odpi.github.io/egeria/index.html).\n\nThe python samples call the REST APIs directly because Egeria does not have any python client libraries (yet :).  Details of the REST API for Egeria can be found by linking to the Swagger UI at *serverURLRoot*/swagger-ui.html.\n\n![Inside the samples](docs/different-client-samples.png)\n\n## Understanding Sustainability Reporting\n\nThe GHG Protocol defines strategies, processes and techniques for collecting and calculating carbon emissions. Three classes of emissions are defined:\n\n* Scope 1 - Direct Emissions from Operations\n* Scope 2 - Indirect Emissions from Utility Consumption\n* Scope 3 - Other indirect emissions\n\nMost reporting is focused on Scope 1 and Scope 2; for Scope 3 there is often a limited focus on business travel.\n\nCalculations for each kind of emission is specified in the GHG Protocol. Reference data supporting these calculations varies over time, location, and sometimes industry - so we need to perform the calculations on a location by location basis and then aggregate this information. This is also useful since we can more easily compare locations and identify the different challenges they face. As we perform these calculations it is important that we record how the results are computed, including which reference data were used.\n\n## More information on the samples\n\nThe samples are divided into related groups ...\n\n### Extending the governance program\n\nCoco Pharmaceuticals has an existing governance program that helps them manage their operations.\nThis governance program is divided into multiple governance domains that each focus on a specific aspect of their\noperations.  For example, they have a domain for data governance, a domain for security and a domain for privacy.\n\nThe samples for extending the governance program show how to add a new governance domain for sustainability.\n\n[Go to code ...](governance-program)\n\n### Creating the operations inventory\n\nCoco Pharmaceuticals need to report on all aspects of their operation.  \nTo ensure they have not missed anything, and to identify where improvements can be made,\nthey need lists of their locations and the equipment and activity at each location.  This is called the operations\ninventory and provides a context for the data they collect.  \n\nFor example, they have utility bills for each of the sites they operate.  \nThe operations inventory will tell them what type of activities - such as office work, \nmanufacturing, research, ...) are occurring at each site, what types of equipment runs there and\nwhich part of the business is responsible for each aspect. With the inventory they can apportion the power or\nwater use to these aspects and then review the data from different perspectives:\n\n* Business area (and hence associated revenue)\n* Types of activity\n* Types of facilities (such as offices, data centres, )\n* Types of equipment (such as IT systems, refrigeration units, robots, vehicles, ...)\n\nThis way they can pick the most important things to change first.\n\nThe samples for building the operations inventory show how to define new types of equipment, catalog the\nlocations, facilities, equipments and activities at each location and issue queries to show different \nparts of the inventory.\n\n[Go to code ...](operations-inventory)\n\n### Finding and cataloguing data\n\nUnderstanding the impact of operations takes more than utility bills.  It is important to understand\nimpact of travel, loss of coolants (such as CFCs), fuel for manufacturing equipment, ...\n\nData about these impacts need to be catalogued so the teams analysing the data and making choices on actions\nto take can find the data. \n\nThe catalog entries for this data need to link to the appropriate parts of the operations inventory to provide\ncontext to the data.  Different locations will often have different sources of data. Often data from different sources uses different units, terminology and reference values.\nThe process of cataloguing data must capture this type of detail to make it consumable by the analysis processes. \n\nThe samples for cataloguing data show how to catalog data and link/tag it, so it is ready for analysis.\n\n[Go to code ...](cataloguing-data)\n\n### Building the sustainability dashboard\n\nIn order to keep sustainability in people's minds (and to provide data to the different stakeholders),\nCoco Pharmaceuticals want to have a set of dashboards and reports that shows their current status and how it is changing\n(better or worse) over time.\n\nData pipelines take the raw data they have, and normalize the data so that the CO2 equivalent emissions can be calculated using standard techniques. transform and combine it into a sustainability database that supplies\ndata to these new dashboards and reports.\n\nThe samples for the sustainability dashboard includes building the data pipelines, cataloguing them\nand recording lineage to show the origin of the data in the reports/dashboards. Lineage is especially important in certifying the accuracy of reported metrics.\n\n[Go to code ...](sustainability-dashboard)\n\n### Assessing and improving IT systems\n\nIT systems (computers) use a lot of electricity.\n\nCoco Pharmaceuticals use many IT systems to run their business, automate their factories, depots, and labs.\nThe research work in particular requires powerful machines running calculations and other analytics to identify,\ndevelop and validate their treatments.\n\nThe number of IT systems continues to grow since new systems are often added and old systems are rarely removed.\nOne surefire way to reduce the impact of their operations is to remove obsolete IT systems and streamline/consolidate their\nprocessing onto a smaller number of more power efficient computers.\n\n[Go to code ...](it-systems)\n\n## Sustainability webpages\n\nDifferent personas need different information to help them understand the sustainability of their area of responsibility,\nand the impact of the changes they are making on the situation.  The sustainability webpages show different views of\nthe Egeria information targeted for different personas.\n\n[Go to code ...](sustainability-webpages)\n\n\n----\nLicense: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/),\nCopyright Contributors to the ODPi Egeria project.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fodpi%2Fegeria-samples-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fodpi%2Fegeria-samples-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fodpi%2Fegeria-samples-api/lists"}