Using the KMM-Client tool to carry out administrative functions

Save PDF

Last Updated: May 13, 2026
12 minute read

Semaphore
Documentation

The “kmm-client” tool is a Java command-line application for accessing the Knowledge Model Management REST API. It can be downloaded from the standard “Software Downloads” section of the Smartlogic Customer Portal.

Note: When using the “kmm-client” to access a Knowledge Model Management instance, the kmm-client should be of the same version as that Knowledge Model Management instance.

Note: The “kmm-client” tool is Java based so requires that Java be installed.

Usage

The general syntax for running the tool is as follows:

java -jar <kmm-client jar file> [-hV] [--connect-timeout=<connectTimeoutMs>] [--socket-timeout=<socketTimeoutMs>] [-a=<cloudApiKey>] [-c=<cloudApiTokenGenerationUrl>] [-d=<requestData>] [-D=<requestDataFile>]
                     [-f=<tokenFile>] [-i=<action>] [-m=<maxAsyncWaitMin>] [-n=<username>] [-o=<outputFile>] [-p=<password>] [-s=<performInAsyncMode>] [-t=<token>] [-T=<uploadFile>] -u=<webappUrl> 
                     [-U=<uploadFileContentType>] [-v=<shouldVerifyChecksum>] [-X=<requestMethod>] [-F=<name=content>]... [-H=<requestHeader>]... [<parameter>...]

Options

Options are passed to kmm-client using either that option‘s long name (--<option name>) or its shortcut (-<option shortcut>).The option’s name and value can either be separated by a space or an equals sign. For example, 4 ways of passing the application URL option shown below are equivalent:

--url http://localhost:5080/kmm
--url=http://localhost:5080/kmm
-u http://localhost:5080/kmm
-u=http://localhost:5080/kmm

The available options are as follows.

Note: The “--url” option (“-u” shortcut) is a required option. The application URL is passed as its value.

Note: When using with Knowledge Model Management with authentication enabled, will need to generate a token and pass it as the “--token” option’s value or to pass the username and password (see “--user” option). To generate the token, using your browser, log into Knowledge Model Management then access the URL <<KMM-URL>>/api/special/generateToken?lifetime=[number of seconds] The number of seconds should be enough for the task for which you will be using it - if you are setting up a backup script to run into the future, then a large value should be specified.

Note: When using with Semaphore Cloud the “--cloud-api-key” option is required to authenticate (see Generation of a Semaphore Cloud API key). Optionally, you can also pass the “--cloud-api-token-generation-url” option (or use the default value).

Note: If an option’s value contains quotation marks, they have to be escaped with “\”.

Note: If an option’s value contains spaces, it has to be put into quotation marks.

Option	Description	Value	Example	Comments	Release notes
--connect-timeout	The time in milliseconds to establish the connection with the remote host. A timeout value of zero is interpreted as an infinite timeout. A negative value is interpreted as undefined (system default).	Integer	--connect-timeout 3000	The default value is -1.	Option introduced in version 4.2.9.
--socket-timeout	The time in milliseconds waiting for data after the connection was established. Maximum time of inactivity between two data packets. A timeout value of zero is interpreted as an infinite timeout. A negative value is interpreted as undefined (system default).	Integer	--socket-timeout 1000	The default value is -1.	Option introduced in version 4.2.9.
-a --cloud-api-key	Api Key required to authenticate in Smartlogic Cloud.	String	-a vyd1X3G2h4P+cumzkmFq0A==	The --cloud-api-token-generation-url option also may be given, otherwise the default URL used to generate API token for Smartlogic Cloud will be used.
-c --cloud-api-token-generation-url	URL used to generate API Token for Smartlogic Cloud.	URL	-c https://cloud.smartlogic.com/token	Used if the “--cloud-api-key” option is given. The default value is “https://cloud.smartlogic.com/token”.
-d --data	Data to send in POST/PATCH request. This option overrides option “--data-file”.	String	-d “{\"@type\": \"sys:Model\", \"rdfs:label\": \"Example\"}”	A header defining the content type should also be passed as an option. Otherwise the “text/plain” content type is passed.
-D --data-file	Name of the file with data to send in POST/PATCH request.	Path	-D C:\Examples\example.json
-f --tokenFile	Name of a file with generated API token.	Path	-f C:\Examples\token.txt
-F --form	Create a POST request using Content-Type multipart/form-data. The required format is <name>=<content>, where the name is name of the form-field. If the option‘s value contains special characters such as space, ’<’ or semicolon, it must be put into quotation marks. Because kmm-client uses semicolons for its own option handling, if the value contains a semicolon, it must be presented using escaped double quotation marks, e.g. -F “name=\”John; Wick\“”. The content can be either the textual data (e.g. -F “name=John Wick”) or the file to upload if prefaced by an @ character (e.g. -F bundlefile=@plugin.jar). To post the contents of a file rather than the file itself, prefix the file name with the symbol ‘<’ (e.g. -F “name=<name.txt”). This will generate a text field with a value equal to the contents of the file. It is also possible to set the Content-Type of a field by using “type=” and separating it from the data using a semicolon (e.g. -F “name=John Wick;type=\”text/plain; charset=UTF-8\“” or -F “zip=@file.zip;type=application/zip”). By default, the content type is set to “text/plain; charset=ISO-8859-1” for text content and “application/octet-stream” for a file content. The name field of a file upload part can be specified using “filename=” (e.g. -F “file=@image.jpg;filename=example.jpg;type=image/jpeg”). This option overrides options “--request”, “--data” and “--data-file”	String		Multiple “--form” options can be used.	Option introduced in version 4.2.8.
-h --help	Display help message.	-	-h		Option introduced in version 4.2.6.
-H --header	Request header.	String	-H Content-Type:application/ld+json	Multiple “--header” options can be used.	The shortcut for this option was changed in version 4.2.6. Previously it was “-h”
-i --action	Perform predefined action. This option overrides option “--request”.	String (one of the predefined actions: backup, restore)	-i backup
-m --max-async-wait	The maximum time (in minutes) for which kmm-client will send requests to check the status of the asynchronous job while waiting for it to finish. If the job is not finished after this time, kmm-client will end with an error, but the asynchronous task will continue to run in Knowledge Model Management.	Integer	-m 60	The default value is 600.	The name for the option was changed in version 4.2.7. Previously it was “--max_async_wait”
-n --user	Username to authenticate in Studio.	String	-n exampleUser	If you pass only username (without “--password” option), you’ll be asked to pass the password from the console.	Option introduced in version 4.2.3.
-o --output	Output file name	Path	-o C:\Examples\backup.zip
-p --password	Password to authenticate in Studio.	String	-p examplePassword	It is not recommended to pass the password in that way. If you pass only “--user” option, you’ll be asked to pass the password from the console. It is ignored if “--user” option is not provided.	Option introduced in version 4.2.3.
-s --async	Perform in async mode.	Boolean	-s true
-t --token	Generated API token. This option overrided option “--tokenFile”.	String	-t WyJzdXBlcmFkbWluIiwxNTM7MjI4O
-T --upload-file	File to upload. Use this option only when doing restore. It creates multipart-form entity with name “file” and specified file. This option overrides options “--form”, “--data” and “--data_file”.	Path	-T C:\Examples\backup.zip
-u --url	Servlet URL with context path.	URL	-u http://localhost:5080/kmm	Required option.
-U --upload-file-content-type	Content type of uploaded file.	String	-U application/ld+json	Used only if the “--upload-file” option is given. By default it is “application/octet-stream” content type.
-v --verify-checksum	Verify checksum of the response body.	Boolean	-v false	The MD5 checksum of the response body will be verified. By default it’s true if the “--output” option is given. Can be used only if the “--output” option is given.
-V --version	Display version of the tool.	-	-V		Option introduced in version 4.2.6.
-X --request	Request method.	String (GET\|PATCH\|POST\|DELETE)	-X GET

Parameters

When no action is selected (“--action” option), then the first parameter is interpreted as a request path relative to the Knowledge Model Management API endpoint. The following parameters are interpreted as request query parameters. When action is selected, then all parameters are interpreted as request query parameters.

Query parameters should be added using the following syntax:

<parameter name>=<parameter value>

For example,

properties=meta:displayName

Parameters to be set to “true” value can be passed using the above syntax or just by putting their name and the “true” value will be added implicitly. For example, passing

overwrite

is equivalent to passing

overwrite=true

For example, the below example should return all changes for the “myExample” model with basic summary info and sorted by the “dcterms:created” field.

java -jar kmm-client.jar --url http://localhost:5080/kmm --token WyJ4eHgiLDE1MzYzMjk0MzEsIk1DQUNEak1LY2xOdkdXRzdhbTBsOXBFdkFnNDhSUDFTcGxsd3krV2dtS0U5eVE9PSJd --request GET api/sys/model:myExample/teamwork:Change/rdf:instance properties=sem:about/meta:displayName,dcterms:created sort=dcterms:created

And using Semaphore Cloud:

java -jar kmm-client.jar --url https://cloud.smartlogic.com/sw/client/67a8b704-42df-4b53-9a83-0a138c12a16d --cloud-api-key vyd1X3G2h4P+cumzkmFq0A== --cloud-api-token-generation-url https://cloud.smartlogic.com/token --request GET api/sys/model:myExample/teamwork:Change/rdf:instance properties=sem:about/meta:displayName,dcterms:created sort=dcterms:created

Reading command line arguments from a file

You can save command line arguments in a file and then pass a path to this file as a tool execution argument, prepending it with the ‘@’ character. For example, you can save the following arguments to a “cmd.txt” file

--url http://localhost:5080/kmm --token WyJ4eHgiLDE1MzYzMjk0MzEsIk1DQUNEak1LY2xOdkdXRzdhbTBsOXBFdkFnNDhSUDFTcGxsd3krV2dtS0U5eVE9PSJd --request GET api/sys/model:myExample/teamwork:Change/rdf:instance properties=sem:about/meta:displayName,dcterms:created sort=dcterms:created

and then run the kmm-client as follows:

  java -jar <kmm-client jar file> @cmd.txt

This applies to version 4.2.6 and later.

Accessing the KMM API

There are two ways of accessing the KMM API:

-Directly passing the request method as the ''%%--%%request'' option and a ''path'' as the first parameter.
-Using one of the ''predefined actions''.

Passing request method and a path

The general syntax for running the tool passing request method and a path is as follows:

java -jar <kmm-client jar file> --url <application URL> --request <request method> [ADDITIONAL OPTIONS] <path> [PARAMETERS]

For example, to retrieve a list of models from the Knowledge Model Management, execute the tool as below:

java -jar kmm-client.jar --url http://localhost:5080/kmm --token WyJ4eHgiLDF1MzYzMjk0MzEsIk1DQUNEak1LY2xOdkdXRzdhbTBsOXBFdkFnNDhSUDFTcGxsd3krV2dtS0U5eVE9PSJd --request GET api/sys/sys:Model/rdf:instance

and using Semaphore Cloud:

java -jar kmm-client.jar --url https://cloud.smartlogic.com/sw/client/67a8b704-42df-4b53-9a83-0a138c12a16d --cloud-api-key vyd1X3G2h4P+cumzkmFq0A== --cloud-api-token-generation-url https://cloud.smartlogic.com/token --request GET api/sys/sys:Model/rdf:instance

As the response, on the console you should see:

{
                    
  "@graph" : [ {
    "@id" : "model:modelName1.tch"
  }, {
    "@id" : "model:modelName2.tch"
  } ]
}

Predefined actions

There are two predefined actions: backup which does the full backup and restore which does the full import.

The general syntax for running the tool using predefined action is as follows:

java -jar <kmm-client jar file> --url <application URL> --action <action name> [ADDITIONAL OPTIONS] [PARAMETERS]

Backup action

To do the full backup using Knowledge Model Management, you should run the application as in the example:

java -jar kmm-client.jar --url http://localhost:5080/kmm --token WyJ4eHgiLDE1NzYzMjk0MzEsIk1DQUNEak1LY2xOdkdXRzdhbTBsOXBFdkFnNDhSUDFTcGxsd3krV2dtS0U5eVE9PSJd --action backup --output backup.zip

and using Smartlogic Cloud:

java -jar kmm-client.jar --url https://cloud.smartlogic.com/sw/client/67a8b704-42df-4b53-9a83-0a138c12a16d --cloud-api-key vyd1X3G2h4P+cumzkmFq0A== --cloud-api-token-generation-url https://cloud.smartlogic.com/token --action backup --output backup.zip

The console output should be empty and the backup files should be present in the “backup.zip” file (under the same path as the jar file). Additionally, an MD5 checksum should be saved to the “backup.zip.md5” file.

Restore action

To do the full restore using Knowledge Model Management, you should run the application as in the example:

java -jar kmm-client.jar --url http://localhost:5080/kmm --token WyJ4eHgiLDE1MzYzMjk0MzEsIk1DQUNEak1LY2xOdkdXRzdhbTBsOXBFdkFnNDhSUDFTcGxsd3krV2dtS0U5eVE9PSJd --action restore --upload-file backup.zip

and using Smartlogic Cloud:

java -jar kmm-client.jar --url https://cloud.smartlogic.com/sw/client/67a8b704-42df-4b53-9a83-0a138c12a16d --cloud-api-key vyd1X3G2h4P+cumzkmFq0A== --cloud-api-token-generation-url https://cloud.smartlogic.com/token --action restore --upload-file backup.zip

You need to pass the zip file containing backup files under the --upload-file option. As the response, on the console we should see:

{
  "message": "Imported 3 models"
}

You can also pass the recreate, overwrite and checkVersion parameters. The recreate parameter set to “true” says that conflicting models will be deleted and re-imported and set to “false” means that conflicting models will remain unchanged. The overwrite parameter applies to configuration files and determines whether the conflicting files will be overwritten from the backup file or remain unchanged. The checkVersion parameter set to true indicates that a restore should confirm that the backup was taken from the same version of KMM into which you are restoring. Setting checkVersion to false indicates to skip this check and perform the restore even if the KMM versions are not the same. Examples below, using Knowledge Model Management and Semaphore Cloud respectively, show how to do the full import with recreating all conflicting models and overwriting all conflicting configuration files.

java -jar kmm-client.jar --url http://localhost:5080/kmm --token WyJ4eHgiLDE1MzYzMjk0MzEsIk1DQUNEak1LY2xOdkdXRzdhbTBsOXBFdkFnNDhSUDFTcGxsd3krV2dtS0U5eVE9PSJd --action restore --upload-file backup.zip recreate=true overwrite=true checkVersion=true

java -jar kmm-client.jar --url https://cloud.smartlogic.com/sw/client/67a8b704-42df-4b53-9a83-0a138c12a16d --cloud-api-key vyd1X3G2h4P+cumzkmFq0A== --cloud-api-token-generation-url https://cloud.smartlogic.com/token --action restore --upload-file backup.zip recreate=true overwrite=true checkVersion=true

If you use version 4.2.5 or previous of the kmm-client, you need to pass also the --async true option (it is passed by default when executing “restore” action in version 4.2.6 and later):

java -jar kmm-client.jar --url http://localhost:5080/kmm --token WyJ4eHgiLDE1MzYzMjk0MzEsIk1DQUNEak1LY2xOdkdXRzdhbTBsOXBFdkFnNDhSUDFTcGxsd3krV2dtS0U5eVE9PSJd --action restore --upload-file backup.zip --async true

java -jar kmm-client.jar --url https://cloud.smartlogic.com/sw/client/67a8b704-42df-4b53-9a83-0a138c12a16d --cloud-api-key vyd1X3G2h4P+cumzkmFq0A== --cloud-api-token-generation-url https://cloud.smartlogic.com/token --action restore --upload-file backup.zip --async true

Notes

Getting JSON-LD context in KMM responses

To improve the readability of the console outputs, the header “X-JsonLd-Exclude-Context:true” is added to all requests by default (in version 4.2.7 and later). This prevents the return of the “@context” in the JSON-LD responses. To get the JSON-LD context along with the response, add “--header X-JsonLd-Exclude-Context:false” to the command line.

Examples

Backup up selected models

Selected models can be backuped up using the following syntax:

java -jar <kmm-client jar file> --url <application URL> --request GET [ADDITIONAL OPTIONS] api/backup/<models to be backuped separated by commas> [PARAMETERS]

For example, using Knowledge Model Management

java -jar kmm-client.jar --url http://localhost:5080/kmm --token WyJ4eHgiLDE1MzYzMjk0MzEsIk1DQUNEak1LY2xOdkdXRzdhbTBsOXBFdkFnNDhSUDFTcGxsd3krV2dtS0U5eVE9PSJd --output backup.zip --request GET api/backup/model:ExampleModelA,model:ExampleModelB

And using Semaphore Cloud:

java -jar kmm-client.jar --url https://cloud.smartlogic.com/sw/client/67a8b704-42df-4b53-9a83-0a138c12a16d --cloud-api-key vyd1X3G2h4P+cumzkmFq0A== --cloud-api-token-generation-url https://cloud.smartlogic.com/token --output backup.zip --request GET api/backup/model:ExampleModelA,model:ExampleModelB

Restore selected models

Selected models can be restored using the following syntax:

java -jar <kmm-client jar file> --url <application URL> --async true --upload-file <file with models to be restored> --request POST [ADDITIONAL OPTIONS] api/backup/import/model [recreate=true] [overwrite=true] [ADDITIONAL PARAMETERS]

For example, using Knowledge Model Management

java -jar kmm-client.jar --url http://localhost:5080/kmm --token WyJ4eHgiLDE1MzYzMjk0MzEsIk1DQUNEak1LY2xOdkdXRzdhbTBsOXBFdkFnNDhSUDFTcGxsd3krV2dtS0U5eVE9PSJd --async true --upload-file backup.zip --request POST api/backup/import/model recreate=true overwrite=true

And using Semaphore Cloud:

java -jar kmm-client.jar --url https://cloud.smartlogic.com/sw/client/67a8b704-42df-4b53-9a83-0a138c12a16d --cloud-api-key vyd1X3G2h4P+cumzkmFq0A== --cloud-api-token-generation-url https://cloud.smartlogic.com/token --async true --upload-file backup.zip --request POST api/backup/import/model recreate=true overwrite=true

Create a new model

A model can be created using the following syntax:

java -jar <kmm-client jar file> --url <application URL> --request POST --data "{\"@type\": \"sys:Model\", \"rdfs:label\": \"<model label>\"}" --header Content-Type:application/ld+json [ADDITIONAL OPTIONS] api/sys/sys:Model/rdf:instance [PARAMETERS]

For example, using Knowledge Model Management

java -jar kmm-client.jar --url http://localhost:5080/kmm --token WyJ4eHgiLDE1MzYzMjk0MzEsIk1DQUNEak1LY2xOdkdXRzdhbTBsOXBFdkFnNDhSUDFTcGxsd3krV2dtS0U5eVE9PSJd --request POST --data "{\"@type\": \"sys:Model\", \"rdfs:label\": \"ExampleModel\"}" --header Content-Type:application/ld+json api/sys/sys:Model/rdf:instance

And using Semaphore Cloud:

java -jar kmm-client.jar --url https://cloud.smartlogic.com/sw/client/67a8b704-42df-4b53-9a83-0a138c12a16d --cloud-api-key vyd1X3G2h4P+cumzkmFq0A== --cloud-api-token-generation-url https://cloud.smartlogic.com/token --request POST --data "{\"@type\": \"sys:Model\", \"rdfs:label\": \"ExampleModel\"}" --header Content-Type:application/ld+json api/sys/sys:Model/rdf:instance

You can also save the request body to the file (without escaping ” characters) and use the --data-file option instead of the --data option.

Delete a model

A model can be deleted using the following syntax:

java -jar <kmm-client jar file> --url <application URL> --request DELETE [ADDITIONAL OPTIONS] api/sys/model:<model name> [PARAMETERS]

For example, using Knowledge Model Management

java -jar kmm-client.jar --url http://localhost:5080/kmm --token WyJ4eHgiLDE1MzYzMjk0MzEsIk1DQUNEak1LY2xOdkdXRzdhbTBsOXBFdkFnNDhSUDFTcGxsd3krV2dtS0U5eVE9PSJd --request DELETE api/sys/model:ExampleModel

And using Semaphore Cloud:

java -jar kmm-client.jar --url https://cloud.smartlogic.com/sw/client/67a8b704-42df-4b53-9a83-0a138c12a16d --cloud-api-key vyd1X3G2h4P+cumzkmFq0A== --cloud-api-token-generation-url https://cloud.smartlogic.com/token --request DELETE api/sys/model:ExampleModel

Install a plugin

A plugin can be installed using the following syntax:

java -jar <kmm-client jar file> --url <application URL> --form bundlefile=@<path to a plugin file> [ADDITIONAL OPTIONS] api/plugin [PARAMETERS]

For example, using Knowledge Model Management :

java -jar kmm-client.jar --url http://localhost:5080/kmm --token WyJ4eHgiLDE1MzYzMjk0MzEsIk1DQUNEak1LY2xOdkdXRzdhbTBsOXBFdkFnNDhSUDFTcGxsd3krV2dtS0U5eVE9PSJd --form bundlefile=@plugin.jar api/plugin

And using Semaphore Cloud:

java -jar kmm-client.jar --url https://cloud.smartlogic.com/sw/client/67a8b704-42df-4b53-9a83-0a138c12a16d --cloud-api-key vyd1X3G2h4P+cumzkmFq0A== --cloud-api-token-generation-url https://cloud.smartlogic.com/token --form bundlefile=@plugin.jar api/plugin

Import a TTL file

A TTL file can be imported using the following syntax:

java -jar <kmm-client jar file> --url <application URL> --form file=@<path to a TTL file> [ADDITIONAL OPTIONS] api/backup/model:<model name>/import [PARAMETERS]

For example, using Knowledge Model Management:

java -jar kmm-client.jar --url http://localhost:5080/kmm --token WyJ4eHgiLDE1MzYzMjk0MzEsIk1DQUNEak1LY2xOdkdXRzdhbTBsOXBFdkFnNDhSUDFTcGxsd3krV2dtS0U5eVE9PSJd --form file=@model.ttl api/backup/model:ExampleModel/import

And using Semaphore Cloud:

java -jar kmm-client.jar --url https://cloud.smartlogic.com/sw/client/67a8b704-42df-4b53-9a83-0a138c12a16d --cloud-api-key vyd1X3G2h4P+cumzkmFq0A== --cloud-api-token-generation-url https://cloud.smartlogic.com/token --form file=@model.ttl api/backup/model:ExampleModel/import

Export a TTL file

A TTL file can be exported using the following syntax:

java -jar <kmm-client jar file> --url <application URL> -H Accept:text/turtle api/backup/model:<model name>/export -o mymodel.ttl [PARAMETERS]

For example, using Knowledge Model Management:

java -jar kmm-client.jar -H Accept:text/turtle -f=token --url http://localhost:5080/kmm -o mymodel.ttl api/backup/model:MyModel/export

And using Semaphore Cloud:

java -jar kmm-client.jar --url https://cloud.smartlogic.com/sw/client/67a8b704-42df-4b53-9a83-0a138c12a16d --cloud-api-key vyd1X3G2h4P+cumzkmFq0A== --cloud-api-token-generation-url https://cloud.smartlogic.com/token -H Accept:text/turtle -o mymodel.ttl api/backup/model:ExampleModel/export

Publish a Model

To externally trigger a publish of a model within KMM , you can use a command like:

java -jar "C:\Releases\Semaphore 5.2.1\Software\Components\Platform Independent\Semaphore-KMMClient-5.2.1.jar" ^
  --url=http://192.168.0.14:5080/kmm ^
  --tokenFile=token.txt ^
  --request POST ^
  api/publisher/model:Subjects/publish ^
  environment=http://www.smartlogic.com/2019/08/studio#environment_2cd6388e-c6d3-4770-a47d-01e1ab1244a7 ^
  language=en ^
  config=Subjects/Semaphore-Publisher.xml

In this case the security token is stored in a file called “token.txt”. The model URI appears in the api/publisher/<<Model URI>>/line.

To get the environment, you will need to, as a Semaphore Super Administrator, lookup the environment URI using the graphql interface, access the URL Machine http://Machine Name:5080/graphql, then enter the query

{
  environments {
    name
    uri
  }
}

(This is actually the default query.) When the run button is pressed the environment URI is displated.

The config is the path to the Publisher configuration file. Note, the model name is required here.

For versions before 5.2.1, the token method of authentication does not work for this call, you will need to supply username and password.

You can submit the publish call directly (e.g. using cURL) as, for example,

curl -v ^
     -X POST ^
     --header X-Api-Key:WyJHb2QiLDE2Mj...dU5DMnR4YkEwPSJd ^
    "http://localhost:5080/kmm/api?path=publisher/model:SESTestModel/publish&config=SESTestModel/Semaphore-Publisher.xml&environment=urn:uuid:a8586443-60a2-81b5-fd37-ab2446cf31c9&language=en"

Note, that in this case the response will wait for the Publish to complete which may well cause a connection timeout. To handle this, add the parameter “async=true” to the request. This will give an immediate response of the form:

{
    "status": "ACCEPTED",
    "jobId": "4e6e699d-650f-4f27-8374-29643de247ab-44",
    "resultLifetimeMs": 1800000,
    "creationTimeMs": 1684932902892,
    "nextStatusCheckMs": 1000
}

with a Location header defined.

You can request the status of the publishing by querying the URL in that Location header, e.g.

GET http://localhost:5080/kmm/api/async/jobs/4e6e699d-650f-4f27-8374-29643de247ab-44

This will return with a status FINISHED when the publish has completed.

You can then get the results from the publish by accessing the URL

GET http://localhost:5080/kmm/api/async/jobs/4e6e699d-650f-4f27-8374-29643de247ab-44/result

This will give an overview of the publish, e.g.

{
    "id": "4e6e699d-650f-4f27-8374-29643de247ab-44",
    "state": "SUCCESS",
    "started": "2023-05-24T12:55:02.894794100Z",
    "finished": "2023-05-24T12:55:04.963395500Z",
    "graphLabel": "master",
    "user": "UserName",
    "config": "SESTestModel/Semaphore-Publisher.xml",
    "environment": {
        "name": "Non-Production"
    }
}

If you use the kmm-client then this asynchronous handling is done for you.

Known issues

Backup does not work in asynchronous mode

Executing either full backup (using predefined action or directly passing the path) or backup of selected models does not work in asynchronous mode. Please do not run a backup with --async option.

Full restore does not work in Semaphore Cloud

There is a known issue that can prevent a full restore of all backup data when used with Semaphore Cloud (those backups including configuration files). If you have problems restoring a full backup, try restoring specific models instead.

Semaphore Knowledge Model Management (KMM) Administration