When you build your service, SOAJS adds its functionality and properties to the request and response of that service. These features empower the developer to have all the tools needed to develop the API quickly and offer common ground between team members.

This space will show you:

  1. What the SOAJS Request is
  2. How to you use the SOAJS Request
  3. Some examples on its usage

SOAJS Request

req.soajs.inputmaskDatasoajs makes it easy by consolidating all the api params from multiple source(post, get, cookie, headers, session, provisioning, …) under one object after formatting and validation.
req.soajs.registrysoajs gives you easy access to the specified environment configuration.
req.soajs.uracsoajs gives you easy access to the logged in user record in case urac is set to true 
req.soajs.logsoajs gives you the ability to have unified and standardized api logging (error, debug, info, …). With the power of soajs.agent, the unified logging will be fed into elastic search and the soajs.dashboard.ui to give you amazing analytic information.
req.soajs.buildResponsethis function builds the standardized json response returned by the api.
req.soajs.validatorsoajs makes it easy for you to validate json schemas.
req.soajs.metamultitenancy meta configuration.
req.soajs.servicesConfigsoajs gives the power to configure each service differently from one tenant to the other as well as empowers you to even have it configured differently down to the user. This configuration is provided by this entry.
req.soajs.tenantcontains the tenant information.
req.soajs.sessionobject to read/write data from the multi-tenant session.
req.soajs.awarenesssoajs allows services on the same cloud to get connected internally
//SOAJS adds to the req the following
req.soajs = {
    // object containing all the input specified in the schema of inputmask mw
    "inputmaskData": {},

    // the registry
    "registry" : {},

	// This is added in case urac property is set to true, it contains the logged in record
	"urac" : {},

    // the logger object
    "log" : {"error" : function(){}},

    // build a response and returns it
    "buildResponse": function (error, data) {},

    // the validator object
    "validator" : {},

    // the meta object
    "meta" : {},

    // the services config from key or URAC
    "servicesConfig": {},

    //tenant info
    "tenant": {
        //tenant id
        "id": '',

        //tenant code
        "code": '',

        //tenant internal and external keys
        "key": {},

        //application info
        "application": {

            //application id
            "appId": '',

            //product code
            "product": '',

            //package code
            "package": '',

            //application acl
            "acl": '',

            //package acl
            "package_acl": ''


    // Access to the session data
    "session": {
        // to set service data into the session
        "setSERVICE": function (obj, cb) {},

        // to get the service data from the session
        "getSERVICE": function () {},
	"awareness": {
		"getHost": function(serviceName, cb) {}


req.soajs can be invoked from any API at runtime to fetch the running configuration and use SOAJS's core methods.

Active Configuration

You can use req.soajs to:

  • Read the current registry information: req.soajs.registry 

    service.get("/hello", function(req, res) {
  • Read the IMFV inputs: req.soajs.inputmaskData 

    service.get("/hello", function(req, res) {
  • Read the service configuration: req.soajs.servicesConfig

    service.get("/hello", function(req, res) {
  • Read the current tenant information: req.soajs.tenant 

    service.get("/hello", function(req, res) {
  • Get the host of a service

    service.get("/hello", function(req, res) {
        req.soajs.awareness.getHost('controller', (host) => {
    		let uri = 'http://' + host + ':' + + req.soajs.inputmaskData.config.route;
    		// hit the new route

SOAJS functionality

You can use req.soajs to:

  • use the logger to output logs on the console based on log type: req.soajs.log

    service.get("/hello", function(req, res) {
        req.soajs.log.error("any message, object, array .... ");"any message, object, array .... ");
        req.soajs.log.warn("any message, object, array .... ");
        req.soajs.log.debug("any message, object, array .... ");
  • use buildResponse to construct a unified and valid REST response: req.soajs.buildResponse

    service.get("/hello", function(req, res) {
        var response1 = req.soajs.buildResponse(new Error("Something went wrong...");
        var response2 = req.soajs.buildResponse({"code": 401, "msg": "Something went wrong..." });
        var response3 = req.soajs.buildResponse(null, { "a": "b" });
  • use the meta to fetch a multitenant database configuration based on the current tenant: req.soajs.meta

    service.get("/hello", function(req, res) {
        var config = req.soajs.meta.tenantDB(req.soajs.registry.tenantMetaDB, "myMTdbName", req.soajs.tenant.code);
        var mongo = new soajs.mongo(config);
  • use the validator to perform JSON schema validation: req.soajs.validator

    service.get("/hello", function(req, res) {
        var data = 4;
        var schema = {"type": "number"};
        var x = new req.soajs.validator.Validator();
        x.validate(data, schema);