All examples given here are based on Linux commands. For Windows, the output is the same, however, you need to start cmemc as cmemc.exe  .

cmemc can be configured with environment variables and configuration files. cmemc looks for a default configuration file on a reasonable place depending on your operating system:

  • For Linux, this is $HOME/.config/cmemc/config.ini  .
  • For Windows, this is %APPDATA%\cmemc\config.ini  .

If you need to change this location and use another config file, you have two options:

  • you can always run cmemc with the --config-file path/to/your/config.ini  option, or
  • you can set a new config file with the environment variable CMEMC_CONFIG_FILE  .

However, once you start cmemc the first time and without any command or option, it will create an empty config file at this location and will output a general introduction.

user@ubuntu:/home/user/$ cmemc
Empty config created: /home/user/.config/cmemc/config.ini
Usage: cmemc [OPTIONS] COMMAND [ARGS]...

eccenca Corporate Memory Control (cmemc).

cmemc is the eccenca Corporate Memory Command Line Interface (CLI).

Available commands are grouped by resource type (e.g. graph, project).
Every command has a separate --help option to get command specific
documentation. Some commands such as list, import and export can be used
on most resources. In order to get a list of commands of a group, simply
execute the group command without further parameter (e.g. cmemc project).

If you are using cmemc the first time and need help on configuration, just
run "cmemc config" and have a look at the example config.

Options:
-d, --debug Output debug messages and stack traces after errors.
-q, --quiet Suppress any non-error info messages.
--config-file FILE Use this config file instead of the default one.
[default: /home/user/.config/cmemc/config.ini]
-c, --connection TEXT Use a specific connection from the config file.
--version Show the version and exit.
--help Show this message and exit.

Commands:
config List, edit and check configurations.
graph List, import, export, delete and open graphs.
project List, import, export, create and delete projects.
query List and execute local and remote SPARQL queries.
workflow List, execute, open or inspect workflows.
workspace Import and export the workspace.
BASH

You can now edit your config file and add credentials and URL parameter for your Corporate Memory deployment. You either search the config manually in your home directory or you can use the config edit command, which opens the config file in your default text editor.

user@ubuntu:/home/user/$ cmemc config edit
Open editor for config file /home/user/.config/cmemc/config.ini
BASH

The rules for the config file are similar to a Windows INI file and are explained in detail at docs.python.org.

Basic Example

Here is an basic example:

[my-local]
CMEM_BASE_URI=http://localhost/
OAUTH_GRANT_TYPE=client_credentials
OAUTH_CLIENT_ID=cmem-service-account
OAUTH_CLIENT_SECRET=c9c12831-000c-464b-9b1d-2d8b7e20df6a
TEXT

This creates a named section my-local  which is a connection to a Corporate Memory deployment on http://localhost/ . The authorization will be done with a system account cmem-service-account  and the given client secret. Using this combination of config parameter is based on a typical installation where, all components are available under the some hostname.

Reference

The above example provides access to an installation where all components including keycloak are deployed with the default URL scheme.

However, if you need to fine tune all locations, the following config file parameter can be used in addition to this example:

VariableDescriptionDefault Value
CMEM_BASE_URIBase URL of your Corporate Memoryhttp://docker.local
DI_API_ENDPOINTData Integration API endpointCMEM_BASE_URI/dataintegration
DP_API_ENDPOINTData Platform API endpointCMEM_BASE_URI/dataplatform
OAUTH_TOKEN_URIOAuth 2.0 Token endpointCMEM_BASE_URI/auth/realms/cmem/protocol/openid-connect/token
OAUTH_GRANT_TYPEOAuth 2.0 grant type (password or client_credentials)client_credentials
OAUTH_USERUsername to retrieve the tokenadmin
OAUTH_PASSWORDPassword to retrieve the tokenadmin
OAUTH_CLIENT_IDOAuth 2.0 client idcmem-service-account
OAUTH_CLIENT_SECRETOAuth 2.0 client secretsecret
SSL_VERIFYVerify SSL certs for API requestsTrue
REQUESTS_CA_BUNDLEPath to the CA Bundle file (.pem)Internal path to included CA bundle

Especially for passwords, you may have long values with a lot of special characters. Be aware of the following points:

  • The cmemc config file should be UTF8 encoded.
  • The character % (percent) has a special meaning to the underlaying python ConfigParser module so that you need to use two percents (%%) instead of one. Without proper handling, you will see an error like this: "configparser.InterpolationSyntaxError: '%' must be followed by '%' or '(', found: '%'"


Validation

In order to verify your configuration, you should try to get a list of graphs:

user@ubuntu:/home/user/$ cmemc -c my-local graph list
https://vocab.eccenca.com/dsm/
https://ns.eccenca.com/example/data/dataset/
https://vocab.eccenca.com/sketch/
https://ns.eccenca.com/example/data/vocabs/
https://vocab.eccenca.com/shacl/
urn:elds-backend-access-conditions-graph
https://ns.eccenca.com/data/queries/
http://di.eccenca.com/project/cmem
BASH

If you get a similar list of graphs, you successfully configured cmemc to access your deployment (smile)

You can also validate your config by using the `config check` command:

user@ubuntu:/home/user/$ cmemc config check my-local
[my-local]
DataPlatform v20.03 ... UP
DataIntegration v20.03 ... UP
BASH

This will validate your given URL connection, your access credentials as well as your Corporate Memory deployment (by utilising the /health endpoints).