KSH API configuration – data model and rules

Overview

The screen manages settings for external data APIs, mainly the KSH open data API: code, name, base URL, API key, an advanced JSON setting and the scope (global, company group, company). The KSH calls are made by the ksh library.

Data model

Table names carry the installation's own prefix in the database.

Known keys of config_json: raw_datasets (raw datasets to download) and stat_indicators (indicators of the statistics import).

Process

1. Form defaults: code ksh, base URL of the office's data portal. For code ksh the KSH dataset list is shown with tick boxes; the ticked ones go into raw_datasets.
2. On saving, config_json is entity-decoded and stored as valid JSON; api_code is required.
3. The scope is derived from the company and company group fields: company: plus ID, group: plus ID, or global.
4. For a new record the response returns the new ID, so the next save is an edit.
5. The connection test fetches the KSH dataset list with the given base URL and reports the count or the error.

Consumers (statistics import, dataset download) resolve the configuration in the order company → company group → global, using active rows only.

Permissions

• List: list; form and test: edit; save: canSave() (add for a new record, edit for an existing one); the Add button is also shown on the edit permission.
• Activate, deactivate: status; delete: delete, single or bulk.
• The company group picker shows the companies allowed by the content scope.

Known limitations

• Deletion is physical, without a reference check.
• The statusdelete key is in the permission catalogue, but there is no endpoint for it.