{"id":23122590,"url":"https://github.com/folio-org/mod-lists","last_synced_at":"2026-01-17T00:47:33.742Z","repository":{"id":191210829,"uuid":"683039123","full_name":"folio-org/mod-lists","owner":"folio-org","description":"Lists back-end module","archived":false,"fork":false,"pushed_at":"2026-01-14T17:52:45.000Z","size":752,"stargazers_count":1,"open_issues_count":5,"forks_count":3,"subscribers_count":7,"default_branch":"master","last_synced_at":"2026-01-14T21:21:49.390Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":false,"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/folio-org.png","metadata":{"files":{"readme":"README.md","changelog":"NEWS.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-08-25T13:00:49.000Z","updated_at":"2026-01-13T21:29:59.000Z","dependencies_parsed_at":"2023-10-19T15:44:10.563Z","dependency_job_id":"12fdf91c-42bd-42a0-bc66-f0f058a5e657","html_url":"https://github.com/folio-org/mod-lists","commit_stats":null,"previous_names":["folio-org/mod-lists"],"tags_count":32,"template":false,"template_full_name":null,"purl":"pkg:github/folio-org/mod-lists","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folio-org%2Fmod-lists","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folio-org%2Fmod-lists/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folio-org%2Fmod-lists/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folio-org%2Fmod-lists/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/folio-org","download_url":"https://codeload.github.com/folio-org/mod-lists/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folio-org%2Fmod-lists/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28490571,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T23:55:29.509Z","status":"ssl_error","status_checked_at":"2026-01-16T23:55:29.108Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-17T07:28:21.096Z","updated_at":"2026-01-17T00:47:33.721Z","avatar_url":"https://github.com/folio-org.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mod-lists\nCopyright (C) 2023 The Open Library Foundation\n\nThis software is distributed under the terms of the Apache License,\nVersion 2.0. See the file \"[LICENSE](LICENSE)\" for more information.\n\n- [Introduction](#introduction)\n- [Architecture](#architecture)\n- [Compiling](#compiling)\n- [Environment Variables](#environment-variables)\n- [Installing the module](#installing-the-module)\n  - [System user](#system-user)\n  - [Resource requirements](#resource-requirements)\n  - [Installation](#installation)\n- [Deploying the module](#deploying-the-module)\n- [Interacting with list-app](#interacting-with-list-app)\n  - [Create a new list](#create-a-new-list)\n  - [Get all the available lists](#get-all-the-available-lists)\n  - [Get comprehensive details about a particular list](#get-comprehensive-details-about-a-particular-list)\n  - [Update list](#update-list)\n  - [Delete list](#delete-list)\n  - [Refresh List](#refresh-list)\n  - [Contents of a list](#contents-of-a-list)\n  - [Exporting List](#exporting-list)\n  - [Export Status](#export-status)\n  - [Download export](#download-export)\n- [Additional information](#additional-information)\n  - [Issue tracker](#issue-tracker)\n  - [Code of Conduct](#code-of-conduct)\n  - [ModuleDescriptor](#moduledescriptor)\n  - [API documentation](#api-documentation)\n  - [Code analysis](#code-analysis)\n  - [Download and configuration](#download-and-configuration)\n\n## Introduction\nmod-lists is responsible for persisting the metadata and the contents (IDs) of lists.\n\n## Architecture\nThe \"mod-lists\" module is responsible for handling lists within the system. It provides a set of REST endpoints that enable users to perform CRUD (Create, Read, Update, Delete) operations on lists. To efficiently query the data, the module leverages the \"lib-fqm-query-processor\" library, which streamlines the process of querying the underlying data storage, such as a database or file system.\n## Compiling\n```bash\nmvn clean install\n```\n## Environment Variables\n\n| Name                                           | Default Value            | Description                                                                                                 |\n|------------------------------------------------|--------------------------|-------------------------------------------------------------------------------------------------------------|\n| DB_HOST                                        | localhost                | Postgres hostname                                                                                           |\n| DB_PORT                                        | 5432                     | Postgres port                                                                                               |\n| DB_USERNAME                                    | postgres                 | Postgres username                                                                                           |\n| DB_PASSWORD                                    | postgres                 | Postgres password                                                                                           |\n| DB_DATABASE                                    | postgres                 | Postgres database name                                                                                      |\n| server.port                                    | 8081                     | Server port                                                                                                 |\n| MAX_LIST_SIZE                                  | 1250000                  | max size of each list                                                                                       |\n| LIST_EXPORT_BATCH_SIZE                         | 1000                     | batch size for exports                                                                                      |\n| S3_BUCKET                                      | -                        | Name of the S3 bucket for exports                                                                           |\n| S3_REGION                                      | us-west-2                | region of the S3 bucket                                                                                     |\n| S3_URL                                         | https://s3.amazonaws.com | end point for the S3 bucket                                                                                 |\n| S3_IS_AWS                                      | false                    | Use the AWS SDK for S3 access                                                                               |\n| S3_ACCESS_KEY_ID                               | -                        | access key for the S3 bucket                                                                                |\n| S3_SECRET_ACCESS_KEY                           | -                        | secret key for the S3 bucket                                                                                |\n| S3_SUB_PATH                                    | mod-lists                | S3 subpath for file storage                                                                                 |\n| OKAPI_URL                                      | http://okapi:9130        | Okapi URL, used for system user authentication/management                                                   |\n| SYSTEM_USER_PASSWORD                           | -                        | Password for the system user; **must be set**                                                               |\n| SYSTEM_USER_ENABLED                            | true                     | Defines if system user must be created at service tenant initialization or used for egress service requests |\n| SYSTEM_USER_RETRY_WAIT_MINUTES                 | 10                       | Max time to wait for the system user to be created, which is used in the Tenant API                         |\n| mod-lists.list-export.s3-startup-check.enabled | true                     | Verify that S3/MinIO is accessible on startup                                                               |\n| spring.task.execution.pool.max-size            | 10                       | refresh/export/migrate thread pool's max size                                                               |\n| REFRESH_QUERY_TIMEOUT_MINUTES                  | 90                       | Max time to wait for an FQL query to run during a list refresh                                              |\n| REFRESH_BATCH_SIZE                             | 10000                    | Number of results to retrieve at a time from FQM when refreshing lists                                      |\n\n\u003e **Note on CSV storage**: MinIO remote storage or Amazon S3 can be used as storage for generated CSV files.\nThe storage is selected by specifying the url of S3-compatible storage by using ENV variable `S3_URL`.\n`S3_IS_AWS` is used to specify client to communicate with storage.\nIt requires `true` in case if S3 usage or `false` in case if MinIO usage. By default it equals to `false`.\nIn addition, the following ENV variables can be\nspecified: `S3_REGION`, `S3_BUCKET`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_SUB_PATH`.\nBy default, the module will attempt to uploaded and delete a small file to S3/MinIO on startup, to verify that the\nservice is reachable. This check can be disabled by setting `mod-lists.list-export.s3-startup-check.enabled` to `false`.\n\n## Installing the module\n\nFollow the guide of Deploying Modules sections of the [Okapi Guide](https://github.com/folio-org/okapi/blob/master/doc/guide.md#example-1-deploying-and-using-a-simple-module) and Reference, which describe the process in detail.\n\n### System user\n\nAs part of installation, this module creates a system user with the username `mod-lists`, password as the environment\nvariable `SYSTEM_USER_PASSWORD`, and permissions to interact with `mod-fqm-manager`\n(as specified [here](src/main/resources/system-user-permissions.txt)).\n\n### Resource requirements\n\n#### Short version\n- Small/medium institutions: Allocate 2 gigabytes of memory for the heap (`-Xmx2g`)\n- Large institutions: Allocate 5.5 gigabytes of memory for the heap (`-Xmx5500m`)\n\n#### Long version\nMost operations in mod-lists use very little memory, however more memory is required when serving up list exports to\nusers. Additionally, sufficient memory is required for good and consistent performance.\nWith the default settings, you should provide mod-lists with at least 1 gigabyte of heap space. This will allow it to\nperform well and export any list up to the default maximum list size. For larger instances, where mod-lists is used\nheavily, give it at least 2 gigabytes. In the most extreme case (still assuming the default max list size and concurrent\ntask limit), where the application is fully saturated with non-stop export requests of extremely large lists that happen\nto all require a lot of memory at the same instant, 5.5 gigabytes of heap space should be sufficient to maintain\nperformance and stability.\n\nIn addition, at least 200 megabytes of free storage space should be available on the server for mod-lists to use for\nstaging temporary files during the list export process.\n\nNote: \"memory\" here refers to heap space memory (set with the `-Xmx` parameter on the JVM), not total system memory.\n\n### Installation\n\nFirst of all you need a running Okapi instance. (Note that specifying an explicit 'okapiurl' might be needed.)\n```bash\n   cd .../okapi\n   java -jar okapi-core/target/okapi-core-fat.jar dev\n```\nWe need to declare the module to Okapi:\n```bash\n  curl -w '\\n' -X POST -D -   \\\n   -H \"Content-type: application/json\"   \\\n   -d @target/ModuleDescriptor.json \\\n   http://localhost:9130/_/proxy/modules\n```\nThat ModuleDescriptor tells Okapi what the module is called, what services it provides, and how to deploy it.\n\n## Deploying the module\nNext we need to deploy the module. There is a deployment descriptor in target/DeploymentDescriptor.json. It tells Okapi to start the module on 'localhost'.\n\nDeploy it via Okapi discovery:\n\n```bash\n   curl -w '\\n' -D - -s \\\n  -X POST \\\n  -H \"Content-type: application/json\" \\\n  -d @target/DeploymentDescriptor.json  \\\n  http://localhost:9130/_/discovery/modules\n```\nThen we need to enable the module for the tenant:\n\n```bash\n  curl -w '\\n' -X POST -D -   \\\n    -H \"Content-type: application/json\"   \\\n    -d @target/TenantModuleDescriptor.json \\\n    http://localhost:9130/_/proxy/tenants/\u003ctenant_name\u003e/modules\n```\n## Interacting with list-app\n\u003e **Note:** This may become outdated and that the source of record for the API is src/main/resources/swagger.api/list.yaml\n\n### Create a new list\nThis API endpoint allows you to create a new list.\n```bash\ncurl \\\n  -H 'Accept: application/json' \\\n  -H 'x-okapi-tenant: {{ tenant identifier }}' \\\n  -H 'x-okapi-token: {{ token }}' \\\n  -X POST {{ base-uri }}/lists\n```\nRequest Body\n```bash\n{\n\"name\": \"Example List\",\n\"description\": \" Creating an example list\",\n\"entityTypeId\": \"xxxxxxxxxxxxxxxxxxxxxxxxx\",\n\"isActive\": false,\n\"isPrivate\": false,\n\"fqlQuery\": \"{\\\"item_status\\\": {\\\"$eq\\\": \\\"missing\\\"}}\"\n}\n```\nResponse\n* Status Code : 201 Created\n* Content Type: application/json.\n\nThe response from the API will contain the ID of the new list (uuid).\n\n### Get all the available lists\nReturns all the available lists.\n```bash\ncurl \\\n  -H 'Accept: application/json' \\\n  -H 'x-okapi-tenant: {{ tenant identifier }}' \\\n  -H 'x-okapi-token: {{ token }}' \\\n  -X GET {{ base-uri }}/lists\n```\nResponse\n\n* Status Code: 200 OK\n* Content Type: application/json.\n\nThe response will be a JSON object containing the information about all the available lists.\n\n### Get comprehensive details about a particular list\n\nReturns the information of a specific list.\n```bash\ncurl \\\n-H 'Accept: application/json' \\\n-H 'x-okapi-tenant: {{ tenant identifier }}' \\\n-H 'x-okapi-token: {{ token }}' \\\n-X GET {{ base-uri }}/lists/{{ id }}\n```\nResponse\n* Status Code: 200 OK\n* Content Type: application/json.\n\nThe response will be a JSON object containing the information about the specified list.\n\n### Update list\nThis API endpoint allows the user to update the list\n```bash\ncurl \\\n-H 'Accept: application/json' \\\n-H 'x-okapi-tenant: {{ tenant identifier }}' \\\n-H 'x-okapi-token: {{ token }}' \\\n-X PUT {{ base-uri }}/lists/{{ id }}\n```\nRequest Body\n\nThe request body should be a JSON object with the following parameters:\n* name (string)\n* fqlQuery (optional - string)\n* isActive (boolean)\n* isPrivate (boolean)\n* version\n* query_id (Optional. If passed, the query results will be copied to the updated list)\n\nResponse\n* Status Code: 200 OK\n* Content Type: application/json.\n\nThe response will contain a JSON object with the updated details of the list.\n\n### Delete list\nThis API endpoint allows the user to delete a list.\n```bash\ncurl \\\n-H 'Accept: application/json' \\\n-H 'x-okapi-tenant: {{ tenant identifier }}' \\\n-H 'x-okapi-token: {{ token }}' \\\n-X DELETE {{ base-uri }}/lists/{{ id }}\n```\nResponse\n* Status Code : 204 No Content\n\n### Refresh List\nThis API endpoint allows the user to refresh a list.\n```bash\ncurl \\\n-H 'Accept: application/json' \\\n-H 'x-okapi-tenant: {{ tenant identifier }}' \\\n-H 'x-okapi-token: {{ token }}' \\\n-X POST {{ base-uri }}/lists/{{ id }}/refresh\n```\nResponse\n* Status Code : 200 OK\n\nThe response will be UUID of the refresh request.\n\n### Contents of a list\nGet contents of a report\n```bash\ncurl \\\n-H 'Accept: application/json' \\\n-H 'x-okapi-tenant: {{ tenant identifier }}' \\\n-H 'x-okapi-token: {{ token }}' \\\n-X GET {{ base-uri }}/lists/{{ id }}/contents?offset={{ offset }}\u0026size={{ size }}\n```\n\n\u003e **Note:** To paginate through the results, you can utilize the optional `offset` and `size` query parameters. It's important to\n\u003e note that the offset parameter follows a zero-based index.\n\nResponse\n* Status Code : 200 OK\n\nThe response will be page of JSON records.\n\n### Exporting List\nStart an asynchronous list export.\n\n```bash\ncurl \\\n-H 'Accept: application/json' \\\n-H 'x-okapi-tenant: {{ tenant identifier }}' \\\n-H 'x-okapi-token: {{ token }}' \\\n-X POST {{ base-uri }}/lists/{{ id }}/export\n```\nResponse\n* Status Code: 201\n* Content type: application/json\n\nThe response will contain a JSON object which will contain the UUID of the export and other details.\n\n### Export Status\nGet status of an export request.\n\n```bash\ncurl \\\n-H 'Accept: application/json' \\\n-H 'x-okapi-tenant: {{ tenant identifier }}' \\\n-H 'x-okapi-token: {{ token }}' \\\n-X GET{{ base-uri }}/lists/{{ id }}/export/{{ export-id }}\n```\nResponse\n* Status Code: 200 OK\n* Content Type: application/json\n\nThe response contains the `status` of the export `SUCCESS`, `INPROGRESS` OR `FAILED`.\n\n### Download export\nDownload contents (CSV) of an export\n\n```bash\ncurl \\\n-H 'Accept: application/json' \\\n-H 'x-okapi-tenant: {{ tenant identifier }}' \\\n-H 'x-okapi-token: {{ token }}' \\\n-X GET{{ base-uri }}/lists/{{ id }}/export/{{ export-id }}/download\n```\nResponse\n\n* Status Code: 200 OK\n* Content Type: text/csv\n\nThe response the csv of the downloaded list.\n\n## Additional information\n\n### Issue tracker\n\nSee project [MODLISTS](https://issues.folio.org/browse/MODLISTS)\nat the [FOLIO issue tracker](https://dev.folio.org/guidelines/issue-tracker).\n\n### Code of Conduct\n\nRefer to the Wiki\n[FOLIO Code of Conduct](https://wiki.folio.org/display/COMMUNITY/FOLIO+Code+of+Conduct).\n\n### ModuleDescriptor\n\nSee the [ModuleDescriptor](descriptors/ModuleDescriptor-template.json)\nfor the interfaces that this module requires and provides, the permissions,\nand the additional module metadata.\n\n### API documentation\n\nAPI descriptions:\n\n* [OpenAPI](src/main/resources/swagger.api/list.yaml)\n* [Schemas](src/main/resources/swagger.api/schemas/)\n\nGenerated [API documentation](https://dev.folio.org/reference/api/#mod-lists)\n\n### Code analysis\n\n[SonarQube analysis](https://sonarcloud.io/project/overview?id=org.folio%3Amod-lists).\n\n### Download and configuration\n\nThe built artifacts for this module are available.\nSee [configuration](https://dev.folio.org/download/artifacts) for repository access,\nand the Docker images for [released versions](https://hub.docker.com/r/folioorg/mod-lists/)\nand for [snapshot versions](https://hub.docker.com/r/folioci/mod-lists/).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffolio-org%2Fmod-lists","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffolio-org%2Fmod-lists","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffolio-org%2Fmod-lists/lists"}