Skip to main content

How to use configs in QSC Admin

With configs in QSC Admin you have a central point of managing the configuration of your software and processes. Configs can be written and read via API, so you can remotely set up processes and scale them with ease.

In the following examples we will use:

  • tenant: demo
  • config code: my-conf

Creating a config​

You can create a config in QSC Admin UI

  • Enter a name, in our example my-conf
  • Click into the "Code" field
  • The code gets filled automatically, change if necessary
    • The code serves as the identifier for this config
  • Click "Create"

Writing a config in QSC Admin​

You can edit configs directly in QSC Admin UI.

  1. Click on the name of the config you created, in our example "my-conf"
  2. Edit the config
    1. The default config is null
    2. You can write or paste any valid JSON
  3. Save the config by Clicking "Save"

Creating a ui for a config​

In QSC Admin it is possible to create a ui for the config.

  • tabs: define a list of tabs
    • name: the name of the tab
    • inputs: a list of input elements
      • label: the label of the input element
      • path: a json path reference to the value in the json config
      • type: the type of the input
        • input: input field
        • textarea: a textarea filed
        • select: a dropdown box
          • options: the options for the dropdown obx
{
  "uiConfig": {
    "tabs": [
      {
        "name": "General",
        "inputs": [
          {
            "label": "foo",
            "path": "foo",
            "type": "input"
          },
          {
            "label": "type",
            "path": "type",
            "type": "select",
            "options": [
              "opt1",
              "opt2",
              "opt3"
            ]
          },
          {
            "label": "notice",
            "path": "notice",
            "type": "textarea"
          }
        ]
      },
      {
        "name": "Nested",
        "inputs": [
          {
            "label": "nested",
            "path": "nested.bar",
            "type": "input"
          }
        ]
      }
    ]
  }

}

Bulk config API​

With the bulk config API it is possible to read and write configs from and to QSC Admin.

Writing configs via API is useful if your configs change with automatic processes taking place. Reading configs from API is useful if an instance of a software should be set up remotely.

Requirement: API Token​

To access the config API for read/write your config, you have to Create an API Token TODO with config read/write permission

Data Structure​

A config in the bulk config API consists of "name", "code", "type", "config" and "tenant".

{
    "name": "my-conf",
    "code": "my-conf",
    "type": "config",
    "config": {
        "my-setting": "active"
    },
    "tenant": {
        "code": "demo",
        "name": "Demo User"
    },
    "grants": [
        {
          "service": "search",
          "codes": [
            "search-config-code-1",
            "search-config-code-2"
          ]
        } 
    ]
}
  • "name": name of the config
  • "code": machine-readable identifier of the config
  • "type": config
  • "config": the actual config JSON String
  • "tenant": machine-readable tenant code and name
  • "grants": grants to make a config Variables holder. Default value is null

Writing a config via config API​

In order to get the config from API you have to perform an HTTP PUT

  • URL
    • Structure:https://qsc.quasiris.de/api/v1/admin/config/[tenant-code]/[config-code]
    • In our example: https://qsc.quasiris.de/api/v1/admin/config/demo/my-conf
  • Headers:
    • X-QSC-Token: your API token e.g. 2f02fb52-8abc-48d5-8080-58f4eac74f52
    • Content-type: application/json
  • Payload:
    • The payload is the JSON data structure described above
    • In our example the actual config in the payload is "my-setting": "active"

Reading a config via config API​

In order to get the config from API you have to perform an HTTP GET

  • URL:
    • Structure:https://qsc.quasiris.de/api/v1/admin/config/[tenant-code]/[config-code]
    • In our example: https://qsc.quasiris.de/api/v1/admin/config/demo/my-conf
  • Headers:
    • X-QSC-Token: your API token e.g. 2f02fb52-8abc-48d5-8080-58f4eac74f52

To get the config JSON from the data structure, parse the HTTP response as JSON and filter the "config" field from it

Variables Holder​

In order to use the values from your config in other configs (search, feeding) you can enable variables-holder feature.

To open your config for this feature create the config like in the example:

{
    "name": "my-conf",
    "code": "my-conf",
    "type": "config",
    "config": {
        "variable1": "active",
        "variable2": "example string"
    },
    "tenant": {
        "code": "demo",
        "name": "Demo User"
    },
  "grants": [
    {
      "service": "search",
      "codes": [
        "search-config-code-1",
        "search-config-code-2"
      ]
    }
  ]
}

You should not use complex structure in config json, just key-value pairs:

DO THIS:

{
  "config": {
    "configuration.app.username": "myusername",
    "configuration.app.price": 25
  }  
}

INSTEAD OF THIS:

{
  "config": {
    "configuration": {
      "app": {
        "username": "myusername",
        "price": 25
      }
    }
  }  
}

Options:

{
  "grants": [
    {
      "service": "search",
      "codes": [
        "search-config-code-1",
        "search-config-code-2"
      ]
    }
  ]
}
  1. grants - if grants are not null, then the config is treated like variables-holder
  2. service - type of config, were you want to use variables from the config
  3. codes - list of codes of specified service where you want to use the config. If codes property is null or not listed, then you open the access for every search config in your tenant

Mapping variables from variables-holder configs​

At that moment you can use this feature to access your variables in:

  • search configs inside variables property
  • feeding configs inside variables property

Using variables in search

  1. Create search config (resolvable-search)
  2. Go to Variables, click o plus button and set
    • key: resolvedVariable1 value: $.my-conf.variable1
    • key: resolvedVariable2 value: $.my-conf.variable2
  3. Generate api key with search WRITE permission and config READ permission Create an API Token TODO. For example f_jYOEilnLLx6QCwzG9R36.mI8JrN9RBgSmc
  4. Use resolve endpoint to check if variables are resolved:
GET /api/v1/admin/search/resolve/{tenantCode}/resolvable-search
HEADERS:
- X-QSC-Token: f_jYOEilnLLx6QCwzG9R36.mI8JrN9RBgSmc

Using variables in feeding

  1. Create a config
  2. Create feeding config (my-feeding)
  3. Go Raw tab to Variables and configure the variable assetEndpoint 
     {
       "variables": {
         "assetEndpoint": "$.settings.feeding.asset.endpoint"
      }
    }
  4. Use the variable in the pipeline
- name: "com.quasiris.qsc.filter.AssetFilter"
  clazz: "com.quasiris.qsc.filter.AssetFilter"
  disabled: false
  property:
    endpoint: "{{{ feeding.variables.assetEndpoint }}}"
    idField: "docId"
    assetMetaDataField: "assetMetaData"
    isAssetField: "isAsset"
    #apiKeyHeader: "not used"