Powered by Zoomin Software. For more details please contactZoomin

Semaphore 5.13 Knowledge Service

Upgrading from Concepts Server

  • Last Updated: November 20, 2026
  • 4 minute read
    • Semaphore
    • Version 5.13
    • Documentation

In Semaphore 5.13, Knowledge Service replaces Concepts Server. The installers programs migrate the existing installation, but some MarkLogic settings must be reviewed before you start the new service.

Install the replacement

Before upgrading, stop Concepts Server and back up its configuration and local data. Use MarkLogic backup tools to protect the configured content, schema, and modules databases and relevant security configuration. Do not run the old and new services simultaneously against the same deployment during migration.

On Linux, install the Knowledge Service RPM with a package manager so that it replaces Semaphore-Concepts. For example:

dnf install Semaphore-KnowledgeService-<version>.noarch.rpm

You can also use yum install or rpm -U. Do not use rpm -i for this upgrade.

On Windows, run Semaphore-<version>-KnowledgeService-setup.exe as an administrator. The previous HTTP port and Java selection are used as defaults. Select Java 21 or later.

Important: Do not delete the old configuration before upgrading. The installer stages it before removing the old installation.

The installers migrate active settings from concepts.properties into knowledge-service.properties, changing concepts.* keys to knowledgeService.*. They update logging references, preserve local data and certificate files, and archive old logs under logs/concepts-server in the new log directory.

Review migrated configuration

The installer program copies only the following settings from the earlier marklogic.properties:

Property Preserved value
marklogic.host MarkLogic host
marklogic.admin.user Administrative username
marklogic.admin.password Administrative password or password reference
marklogic.database Existing content database name
marklogic.schema-database Existing schema database name

You can keep the preserved database names and retain access to models that you have already published. Republishing your models after the upgrade is recommended.

If you choose to use new database names instead, previously published models will not be available in the new databases. You must republish your models to make them available in Knowledge Service.

Review the new marklogic.properties against the original before starting the service. Ports and all other old MarkLogic settings are not copied. Reconfigure any non-default TLS/authentication, permissions, REST/modules names, gateway, forest/replica, or vault settings that you need. Retaining a keystore file does not restore its omitted vault settings.

If using a non-admin MarkLogic account, update its roles and privileges before startup as described in Reduced-permission provisioning account.

Important: The old marklogic.port=8000 normally referred to App-Services. In Knowledge Service, marklogic.port is the dedicated REST data port, defaulting to 8040. App-Services uses marklogic.app-services.port, defaulting to 8000; the Manage API uses marklogic.monitoring.port, defaulting to 8002. Review custom ports explicitly and remove the unsupported marklogic.forest and marklogic.schema-database-forest settings. See Configuring the Knowledge Service.

Update external scripts, environment overrides, and custom service launchers to use the new installation paths and names:

Previous name New name
concepts.properties knowledge-service.properties
concepts.* knowledgeService.*
CONCEPTS_CONFIG_PATH KNOWLEDGE_SERVICE_CONFIG_PATH
CONCEPTS_LOG_LEVEL KNOWLEDGE_SERVICE_LOG_LEVEL
semaphore-concepts Linux service semaphore-knowledge-service
SEM-CON Windows service SEM-KS

The installers do not rewrite external scripts or orchestration configuration.

Start and verify the service

After reviewing the configuration:

  1. Start semaphore-knowledge-service on Linux or SEM-KS on Windows. Initial startup might update document permissions and reindex the content database; allow time for this work to complete.

  2. Check Status at <knowledge_service_base_uri>/application/status. A successful response should include statusCode: 0 and connected: true.

  3. Check the models list at <knowledge_service_base_uri>/models:

    • If you retained the existing database names, verify that the previously published models appear in the response.
    • If you configured new databases, an empty list ([]) is expected until you republish your models.
  4. Republish your Semaphore models. This step is recommended when retaining existing databases and required when using new databases.

  5. Verify that the expected models are available and run a representative query to confirm that it succeeds.

After successful republishing and verification, have your MarkLogic administrator review obsolete Knowledge Service-owned modules and TDE templates in the formerly used databases. Do not delete shared Modules or Schemas databases, or templates still needed by a preserved schema-database configuration.

Migration recovery

The installers do not automatically merge independently configured Concepts Server and Knowledge Service installations. Back up both installations and resolve the conflict before retrying.

If migration fails, inspect the installer logs to identify the cause. Correct the reported issue, such as a file access or permissions problem, and rerun the installer.

The installer can reuse the preserved recovery files to resume the migration, even if the previous Concepts Server installation has already been uninstalled.

On Linux, recovery files remain under /var/opt/semaphore/.concepts-to-knowledge-service; the new service is disabled and blocked from starting until migration succeeds. On Windows, recovery files remain under C:\ProgramData\Smartlogic\knowledge-service-migration, and the installer does not automatically start the new service.

If the underlying issue cannot be resolved and the migration cannot be completed, use the backups created before the upgrade to recover the previous environment.

After successful migration, the original configuration is retained under /var/opt/semaphore/knowledgeService/migration-backup/concepts-config on Linux, or <install_dir>\migration-backup\concepts-config on Windows.

Container upgrades

Switching from the Concepts Server image to semaphore-knowledge-service does not run installer migration. The container startup script copies or compares defaults but does not translate old settings or move existing mount points.

Back up and migrate your configuration and local data to the new mount paths, apply the name changes above, and review MarkLogic settings before starting the container. Republish your models, as it's recommended. See Run individual Progress-supplied Docker images for the current image configuration.

Alert