Skip to content

Explorer Configuration

Jump to bottom Edit New page
Esa Puttonen edited this page Jun 7, 2022 · 6 revisions

Table of Contents

Deployment guidelines

nFlow Explorer is a single page web application, so it can be deployed to any web server. Starting from nFlow 8.x.x, there are two Explorer implementations:

  1. nflow-explorer-ng: new Explorer that will have the new features. Implemented using maintained Javascript-libraries such as ReactJS.
  2. nflow-explorer: deprecated Explorer that will be removed in nFlow 9. Implemented using legacy Javascript-libraries such as AngularJS.

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 (nflow-explorer | nflow-explorer-ng) 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) for nflow-explorer-ng

Property name Description Required Example value
nflowEndpoints-array Defines nFlow REST API endpoints for the Explorer, see config.js for more details. 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/'
  },
]
refreshSeconds Controls how often data is polled from the selected nFlow REST API, when an automatically refreshing UI element is displayed (e.g. active executors list) X 
60
customInstanceContent Generate custom content for workflow instance details page (between workflow instance properties table and state transition graph). Optional function that returns either a string or a Promise that resolves to a string. The string is added to the page DOM. To create links to external, which contain additional data about the workflow. Example:
function(definition, workflow, parentWorkflow, childWorkflows) {
  return '<a href="https://cms.service.com/content/' + workflow.businessKey + '">Open CMS</a>'
}
Fetch additional data from external systems and display it in the in nFlow Explorer UI. Example: 
function(definition, workflow, parentWorkflow, childWorkflows) {
  return fetch('https://api.service.com/content/' + workflow.businessKey)
    .then(result => {
      return result.json()
        .then(data => data.contentTitle)
    })
}
customDefinitionContent Generate custom content for workflow definition details page. Optional function that returns either a string or a Promise that resolves to a string. The string is added to the page DOM. See customInstanceContent for usage pattern examples, though note that the method signature differs. 
function(definition) {
  return 'mycontent';
};
htmlTitle Replaces HTML page title by given string. My Explorer title in browser
nflowLogoFile Replaces nFlow logo in header by image in given location (URL or relative path) /nflow/imagepath/mylogo.png
searchResultColumns Customizes columns shown in workflow instance search, see config.js for more details. 
[
  {
    field: 'businessKey',
    label: 'Business key'
  },
  {
    field: 'stateVariables.cron',
    label: 'CRON'
  },
  {
    field: 'nextActivation',
    label: 'Next activation',
    type: 'timestamp'
  }
]

Configuration options (config.js) for nflow-explorer

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/'
  },
]
radiator Configuration for polling nFlow REST API for updates. pollPeriod controls how often data is polled (in seconds). maxHistorySize controls how many historical statistics data points are saved in browser memory (used for drawing radiator graphs). X 
{
  pollPeriod: 15,
  maxHistorySize: 10000
}
customInstanceContent Generate custom content for workflow instance details page (between workflow instance properties table and state transition graph). Optional function that returns either a string or a Promise that resolves to a string. The string is added to the page DOM. To create links to external, which contain additional data about the workflow. Example:
function(definition, workflow, parentWorkflow, childWorkflows) {
  return '<a href="https://cms.service.com/content/' + workflow.businessKey + '">Open CMS</a>'
}
Fetch additional data from external systems and display it in the in nFlow Explorer UI. Example: 
function(definition, workflow, parentWorkflow, childWorkflows) {
  return fetch('https://api.service.com/content/' + workflow.businessKey)
    .then(result => {
      return result.json()
        .then(data => data.contentTitle)
    })
}
customDefinitionContent Generate custom content for workflow definition details page. Optional function that returns either a string or a Promise that resolves to a string. The string is added to the page DOM. See customInstanceContent for usage pattern examples, though note that the method signature differs. 
function(definition) {
  return 'mycontent';
};
htmlTitle Replaces HTML page title by given string. My Explorer title in browser
nflowLogoFile Replaces nFlow logo in header by image in given location (URL or relative path) /nflow/imagepath/mylogo.png
hideFooter When true, hides the sticky footer with copyright. true
searchResultColumns Customizes columns shown in workflow instance search. The configuration in example shows workflow id and type (which are always first columns by default) followed by business key, state variable "cron" and next activation. The default column configuration and column names are listed here. As in example, you can refer to values in workflow instance state variables by prefixing the variable name by stateVariables.. 
[
  {
    field: 'businessKey',
    label: 'Business key'
  },
  {
    field: 'stateVariables.cron',
    label: 'CRON'
  },
  {
    field: 'nextActivation',
    label: 'Next activation',
    type: 'timestamp'
  }
]
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
  };
};

Setting return URL

Explorer supports setting return URL back to your web application by default. This is useful, if you e.g. know in your application which workflow is processing your business object and want provide a link from your UI to Explorer and back. The return link is shown in the uppermost right corner of Explorer.

Query parameter returnUrlLabel controls the label shown in the return link and returnUrl the actual return URL. Working example:

https://bank.nflow.io/nflow/ui/explorer/index.html?returnUrlLabel=Return%20to%20application%20X&returnUrl=https://www.yoursite.com#!/workflow/1

Add a custom footer

Home

Getting Started

Configuration

FAQ

JavaDocs

Glossary

Contributing

Clone this wiki locally