Getting Started with Perspective

Hard coded settings, we've all had to deal with them. Nothing is worse than an emergency deployment to replace a hard coded variable because it changed. Even worse are those pesky sensitive keys stored in plain text right in the code. Anyone with the code base now has access to that system's credentials.

As a result, the first system we built for any application was a proper settings management tool. Over the decades, it got more complex and sophisticated and thus Perspective was born.

The Perspective feature management tool is designed to store and provide the correct settings to the correct application in the correct environment. Beyond that, it was designed to be implemented in the easiest way possible (currently in Java and Node). Lastly, it has recursive lookups to include settings within settings for powerful setting management. Simply add the Maven, Gradle or NPM package to get started. For Maven projects:

<dependency>
 <groupId>com.tamaton.util</groupId>
 <artifactId>perspective-client</artifactId>
 <version>1.0.3</version>
</dependency>

For NPM projects:

"dependencies": {
 "perspective-npm-client": "^1.0.0"
},

Next, log into Tamaton Portal and go to the Perspective section. Once there, you can begin creating application settings. Create a few settings to test your application. Use the following guidelines for adding new settings:

• App: The application name calling the API. Settings for a specific app should match the app name. Settings for all applications should use * here.
• Env: The environment the application is running in. For environment agnostic variables, use * here.
• Name: The key/name of the setting. This is the lookup key that will be used in the application to pull this setting.
• Value: The value of the setting for this app and environment.
• Secret: Is this a sensitive value? (masks from logging in the application and in this portal).
• Type: Fine grained controls over the allowable options for the setting.
• Values: Limits the value of the setting to these comma separated items.

Some things to note about the settings are wildcards (*) and nested variables (${key}). Wildcards can be used to share the same setting across all environments and/or applications. These can be overriden by a non-wilcard value. As an example, a setting for a domain, like tamaton.com, can be set with a wildcard environment. Then we can add the same setting with the environment set to DEV and value set to localhost. Then all environments but DEV will pull tamaton.com and DEV will pull localhost.

Nested variables are a great way to simplify settings management. For example, we can create a wildcard environment setting like database${environment-url}.tamaton.com and endpoint${environment-url}.tamaton.com. Then we create the environment-url setting for each environment like PRD="", TST="-tst", UST="-uat". The end result would add the correct environment slug into the required URL for requests. Running any application in the TST environment would automatically connect to the TST database and other TST endpoint services. These could then be overwritten per application/environment if there was need for cross environment communication.

Next step to implement Perspective, create the Configuration object in your code. For Java, create a singleton like so:

@Bean
public com.tamaton.util.conf.Configuration configuration() {
 return ConfigurationBuilder
  .initialize()
   .setApplication(<application name/identifier defined by you>)
   .setCacheTime(<how long in ms to store cache>)
   .setEmail(<your login email>)
   .setEnvironment(<environment defined by you>)
   .setAccountId(<your account id>)
   .setSubscription(<your api key>)
   .build();
}

For Node.js, create an object like so:

const persConfig =
{
 accountKey: {
  accountId: "<your account id>",
  email: "<your login email>"
 },
 apiKey: "<your api key>",
 application: "<application name/identifier defined by you>",
 environment: "<environment defined by you>"
};

To use Perspective settings within your application, autowire the singleton into your class and simply pass the key/name of the setting you would like to retrieve.

@Autowired
private Configuration configuration;


public void someMethod() {
 ...

 String setting = configuration.getProperty("<setting key/name>")

 ...
}

In java, you can provide a Translator to the configuration.getProperty method to autoconvert the setting into the needed obect type like so:

Integer number = configuration.getProperty("some-number", Translator.translateInteger());

We have prebuilt translators for Integers, longs, doubles, BigDecimals, Patterns, and comma delimited Arrays. You can, however, create your own implementation of the Translator class to handle other types of Objects. The translated object type will be cached in the settings layer.