. . .

Service Configuration parameters

In the previous tutorial, we set a default value for newly created objects (which in this case were groceries). This default value was hardcoded into the service implementation.
Now, suppose you want to let every customer that uses your service set this default value from the Dashboard without having to download the service code and change it there. This can be done by using so called configuration parameters.

A configuration parameter is a tuple of definition (key) and value. The definition for a configuration parameter needs to be created in your service. The value can be set through the Dashboard or programmatically and is stored in the configuration server Gearhead.

In this tutorial, we will see where and how the definitions for your configuration parameters should be set, and how you can interact with them.

Note that for this part of the tutorial, Gearhead must be started and registered to Consul.

Setting a configuration parameter

  1. First, you have to create a configuration definition for your parameter. This can be achieved by adding an enumeration value to your specific service configuration definition class. You can find this class in the 'config' package (under com.apiomat.microservice.tutorialservice), it is named TutorialServiceConfigDefinition.java for this example.

  2. Have a look at the commented out generated example that helps you to create your first configuration definition:Java

    // Sample for a service configuration
    // DEFAULT_CONFIG( "DEFAULT_CONFIG", "Hint values", Type.TEXT, "Example", "Title", "Info", "Default", 0 )

    The parameters of the enum are the following (in this exact order):

    1. key - The case-insensitive identifier of this parameter, the name of the java enumeration entry must be equal to it.

    2. values - In an enumeration-type parameter where only certain values are possible (e.g. a "size" parameter that can only be "small", "medium" or "large"), this can be used to display the possible values. Can be left blank in other cases.

    3. dataType - The ApiOmat data type of this parameter, will affect which UI component is used in the Dashboard to select the value of this parameter. It's also used to handle the object type of the value when saving or retrieving it programmatically from the configuration server.

    4. example - An example value that will be shown in the Dashboard, next to the parameter's field in a tooltip.

    5. title - The name of the parameter which will be shown in the Dashboard.

    6. info - Informational text that will be shown in the same tooltip as the example.

    7. defaultValue - The default value set for this configuration parameter, will be returned when querying the configuration server if no value exists.

    8. order - Set the order in which your configuration parameters are shown in the dashboard, if you have more than one.

    You can now define your own configuration definition with the help of the example:Java

    DEFAULT_PRICE( "DEFAULT_PRICE", "", Type.NUMBER, "0.8", "Default Price", "This is the default price of every new grocery", 0.5, 1 );

  3. Now that you have created your first configuration parameter, deploy your service so that your changes are synchronized and (re)start it. Note that you may have to refresh the service page by clicking on the 'refresh' button in 'Market (1) > Services (2)':

    images/download/attachments/68177129/Screen-Shot-2020-02-21-at-09.24.20.png



  4. You should now have access to your configuration parameter through the Dashboard:

    images/download/attachments/68177129/Screen-Shot-2020-02-21-at-09.24.39.png



  5. Open the configuration panel and you can set the value:

    images/download/attachments/68177129/Screen-Shot-2020-02-21-at-09.25.05.png

Now that you have set a value (e.g. 0.7) for your configuration parameter, you can use it in your service logic.

Programmatically retrieve configuration parameter value

In the previous tutorial, we set a default value for every new grocery that is created inside the GroceryApiServiceImpl class. We will add our custom logic to the save method of GroceryApiServiceImpl, so that the DEFAULT_PRICE value will be set as the default price of any created Grocery object:

  1. The value of a configuration parameter is retrieved by the method readValue([applicationName], [usedSystem], [configurationDefinition]) of the ServiceConfigRequester class, provided by the apiomat-service-config library. In the context of Spring Boot services, the library apiomat-service-config-starter autoconfigures the components required to retrieve configuration parameter values into your Spring context .

  2. In GroceryApiServiceImpl, you can directly autowire the ServiceConfigRequester instance, and override the save method to add logic to read the value previously set for your DEFAULT_PRICE:Java

    @Autowired
    com.apiomat.service.config.api.ServiceConfigRequester requester;
    @Autowired
    javax.servlet.http.HttpServletRequest request;
     
    ...
    @Override
    public String save( final String appName, final Grocery model )
    {
    /* extract ApiOmat system header value */
    final String aomSystemHeaderValue = this.request.getHeader( "x-apiomat-system" );
    final ApiomatSystem requestedSystem = ApiomatSystem.valueOf( aomSystemHeaderValue );
     
    /* retrieve the default price from configuration service Gearhead, use type "Number" to avoid ClassCastExceptions */
    final Number defaultPrice = this.requester.readValue( appName, requestedSystem, "TutorialService", TutorialServiceConfigDefinition.DEFAULT_PRICE );
    /* set the default price to the grocery object and save it */
    model.setPrice( defaultPrice.doubleValue() );
     
    return super.save( appName, model );
    }
    ...

    Configuration parameter values are stored in Gearhead per application, service and system. The example above demonstrates how you can retrieve the current request from the Spring context and extract the ApiOmat system header value.

  3. Deploy and restart your service. Now, every time you create a new grocery via a REST call or through the Dashboard data panel, it should automatically have the price that has been set in the configuration dialog!
    If you are creating data via the Dashboard, be aware that you may have to refresh the services again from the 'Market > Services' view for the change to take effect.

    images/download/attachments/68177129/Screen-Shot-2020-02-21-at-10.07.31.png


Congratulations! Now you know how to define and set configuration parameters for your ApiOmat service.

Next steps