Ibm-appconfiguration-node-feature NPM

IBM Cloud App Configuration Node Feature SDK

IBM Cloud App Configuration Feature SDK is used to perform feature evaluation based on the configuration on IBM Cloud App Configuration service.

Overview
Installation
Module Inclusion
Initialize Client
APIs
Feature Evaluation
License

Overview

IBM Cloud App Configuration is a centralized feature management and configuration service on IBM Cloud for use with web and mobile applications, microservices, and distributed environments.

Instrument your applications with App Configuration Node SDKs, and use the App Configuration dashboard or API to define features flags, organized into collections and targeted to segments. Change feature flag states in the cloud to activate or deactivate features in your application or environment, often without re-starting.

Installation

Installation is done using the npm install command.

The Feature SDK uses ibm-appconfiguration-node-core as one of the base dependency.

$ npm install ibm-appconfiguration-node-core
$ npm install ibm-appconfiguration-node-feature

Include Module

To import the module

const { AppConfigurationCore } = require ('ibm-appconfiguration-node-core');

const {
  AppConfigurationFeature
} = require('ibm-appconfiguration-node-feature');

Initialize Client

Initialize the Core SDK to connect with your App Configuration service instance.

const client = AppConfigurationCore.getInstance({
  region: 'us-south',
  guid: 'xxxxx-5f61-xxxx-9f97-xxxx',
  apikey: 'abcd-1234xyz',
})

region : Region name where the App Configuration service instance is created. Use us-south for Dallas and eu-gb for London.
guid : Instance Id of the App Configuration service. Get it from the service credentials section of the dashboard.
apikey : ApiKey of the App Configuration service. Get it from the service credentials section of the dashboard.

Note: The AppConfigurationCore client can be null if any of the configurations are missing or invalid.

Initialize the feature flag sdk to connect with your App Configuration service instance.

const featureClient = AppConfigurationFeature.getInstance({
  collectionId: "collection_id",
  liveFeatureUpdateEnabled: true,
  featureFile: 'custom/userJson.json'
})

where,

collectionId: Id of the collection created in App Configuration service instance.
liveFeatureUpdateEnabled: Optional. Set this value to false if the new feature values shouldn't be fetched from the server. Make sure to provide a proper JSON file in the featureFile path. By default, this value is enabled.
featureFile: Optional. Path to the JSON file, which contains feature details and segment details. Defaults to null.

Note: The AppConfigurationFeature client can be null if any of the configurations are invalid. In this case SDK shows the error message. To avoid errors in the app, check for null AppConfigurationFeature object.

APIs

Set attributes

You can set the attributes values that define the segments using setClientAttributes method. This value is used as the default attributes to evaluate the feature rules.

var attributes = {
    "city":"Bengaluru",
    "country": "India"
}
featureClient.setClientAttributes(attributes)

The feature evaluation can also be done by using the request object in the APIs. Pass the values in query or headers or body to evaluate the feature rules. All these values are used during the getCurrentValue of the feature object.

For example, You can pass the attributes as part of the headers in the request to your API as below:

curl --request GET 'https://customerapiserver.com/api/v2/getAppData' --header 'city: Bengaluru' --header 'country: India'

Get all features

var features = featureClient.getFeatures();

var feature = features["feature_Id"];

if(feature) {
    console.log(`Feature Name ${feature.getFeatureName()} `);
    console.log(`Feature ShortName ${feature.getFeatureId()} `);
    console.log(`Feature Type ${feature.getFeatureDataType()} `);
    console.log(`Feature is enabled ${feature.isEnabled()} `);
    console.log(`Feature currentValue ${feature.getCurrentValue()} `);
}

Get single feature

const feature = featureClient.getFeature('feature_Id')

if(feature) {

    if(feature.isEnabled()) {
        // enable feature
    } else {
        // disable the feature
    }
    console.log('data', feature);
    console.log(`Feature Name ${feature.getFeatureName()} `);
    console.log(`Feature ShortName ${feature.getFeatureId()} `);
    console.log(`Feature Type ${feature.getFeatureDataType()} `);
    console.log(`Feature is enabled ${feature.isEnabled()} `);
    console.log(`Feature currentValue ${feature.getCurrentValue()} `);
}

Listen to the feature changes

To listen to the data changes add the following code in your application

  featureClient.emitter.on('featuresUpdate', () => {
      // add your code
  })

Note: The AppConfigurationFeature getFeature can be null if the featureId is invalid. In this case SDK shows the error message. To avoid errors in the app, check for null AppConfigurationFeature getFeature.

Feature evaluation

You can use the feature.getCurrentValue() method to evaluate the value of the feature flag. If the feature flag is configured with segments in the App Configuration service, you can set the attributes values used for evaluation using one of the below methods :

Feature evaluation using the attributes set in Client Attributes. Refer to Set Attributes for more details.

console.log(`Feature currentValue ${feature.getCurrentValue()} `);

Feature evaluation using the Request object. Pass the request object, to use the attributes set in request headers, body and query parameters for feature evaluation.

app.get('/', function (req, res) {

  ........
  console.log(`Feature currentValue with req object :  ${feature.getCurrentValue(req)}`)
  ........

})