Explorer Configuration

Deployment guidelines

nFlow Explorer is a single page web application, so it can be deployed to any web server.

Typically nFlow Explorer is embedded as a library (through Maven dependency) in the application that uses nFlow backend components (engine and REST API). See examples for unpacking the library inside the application using Maven or Gradle.

Regardless of where the library is deployed, you need override some properties in config.js. At minimum, you need to configure the endpoint for your nFlow REST API.

In Spring Boot -application you can just copy & paste the default config.js to src/main/resources/static/explorer/config.js file under your application, and make your custom configuration there. This file will override the default config.js that is unpacked from the library dependency.

Configuration options (config.js)

Property name	Description	Required	Example value
nflowUrl	nFlow REST API endpoint. Applicable if you have only one nFlow REST API. Deprecated, prefer using nflowEndpoints instead. Hint: Use relative path (e.g. /rest/nflow) instead of absolute path (e.g. https://server.com/rest/nflow) for environment agnostic path, if nFlow Explorer and REST API are deployed in the same application.		http://localhost:7500/nflow/api
nflowApiDocs	nFlow Swagger UI endpoint. Applicable if you have only one nFlow REST API. Deprecated, prefer using nflowEndpoints instead.		http://localhost:7500/nflow/ui/doc/
withCredentials	When true (defaults to false), the credentials used for loading nFlow Explorer are used for nFlow REST API calls. Applicable if you have only one nFlow REST API. Deprecated, prefer using nflowEndpoints instead.		true
nflowEndpoints-array	The preferred way of definition nFlow REST API endpoints. Each endpoint is assigned apiUrl (see nflowUrl), docUrl (see nflowApiDocs), withCredentials, id (any unique string) and title (human readable label for nFlow deployment behind the apiUrl). If there's more than 1 elements in the array, an endpoint selection-box is shown in the Explorer top navigation bar.	X	[ { id: 'localhost', title: 'local nflow instance', apiUrl: 'http://localhost:7500/nflow/api', docUrl: 'http://localhost:7500/nflow/ui/doc/' }, { id: 'nbank', title: 'nBank at nflow.io', apiUrl: 'https://bank.nflow.io/nflow/api', docUrl: 'https://bank.nflow.io/nflow/ui/doc/' }, ]
adal	Configuration for Azure AD authentication. See azure-activedirectory-library-for-js-repository for more details. Note that you also need to equip your nFlow REST API endpoints with Azure AD authentication filter. The properties are documented here)		{ requireADLogin: false, instance: 'https://login.microsoftonline.com/', tenant: 'Enter_your_tenant_name_here_e.g._contoso.onmicrosoft.com', clientId: 'Enter_your_client_ID_here_e.g._e9a5a8b6-8af7-4719-9821-0deef255f68e', popUp: false }

Environment specific configuration

If your nFlow Explorer configuration contains environment (e.g. development, test, production) specific values, you need a different config.js file for each environment. The method for achieving this depends on your environment.

If you're embedding nFlow as a library in your application as described earlier, you can threat config.js as a template that is read and modified by a Java Servlet with environment specific properties. The code examples below enable configuring environment specific Azure AD client IDs, but the same approach works for any other properties as well.

YourConfiguration.java

@Bean
public ServletRegistrationBean<NflowExplorerConfigServlet> nflowExplorerConfig() {
  return new ServletRegistrationBean<NflowExplorerConfigServlet>(new NflowExplorerConfigServlet(env), "/explorer/config.js");
}

public static class NflowExplorerConfigServlet extends HttpServlet {
  private static final long serialVersionUID = 1L;
  private final boolean securityDisabled;
  private final String aadClientId;

  public NflowExplorerConfigServlet(Environment env) {
    securityDisabled = env.getProperty("security.disable", Boolean.class, false);
    aadClientId = env.getRequiredProperty("azure.activedirectory.client-id");
  }

  @Override
  public void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException {
    ClassPathResource cpr = new ClassPathResource("static/explorer/config.js");
    String config = IOUtils.toString(cpr.getInputStream(), StandardCharsets.UTF_8.name());
    if (securityDisabled) {
      config = config.replace("REQUIRE-AAD-LOGIN", "false");
    } else {
      config = config
        .replace("REQUIRE-AAD-LOGIN", "true")
        .replace("AAD-CLIENT-ID", aadClientId);
    }
    IOUtils.write(config, response.getOutputStream(), response.getCharacterEncoding());
  }
}

config.js

var Config = function () {
  this.nflowEndpoints = [
    {
      id: 'yourApi',
      title: 'Your API',
      apiUrl: '/rest'
    }
  ];

  this.adal = {
    requireADLogin: REQUIRE-AAD-LOGIN,
    instance: 'https://login.microsoftonline.com/',
    tenant: 'a123abca-1ab2-1234-1ab0-1abc13abc323',
    clientId: 'AAD-CLIENT-ID',
      popUp: false,
      anonymousEndpoints: ['html']
  };

  this.radiator = {
    // poll period in seconds
    pollPeriod: 15,
    // max number of items to keep in memory
    maxHistorySize: 10000
  };
};