Managing external data sources

Important

The external data sources interface for DMN data objects is available for your On Premise installation on request. In case you want to activate the interface, please contact the Signavio Support Team by email at support@signavio.com.

In the Signavio Decision Manager, you can use to define the data types of input columns in DMN model decision tables.

For the data types string lists (enumerations) and hierarchies, you can set up external services to retrieve corresponding data objects.

This section explains the implementation and configuration of such a service.

Architecture

The following diagram shows the system architecture of the external data source interface:

The architecture of the external data source integration service

The architecture of the external data source integration service

The component on the left represents the Signavio system. The right part of the diagram represents a third-party service with access to the to-be transferred data. It may contain a bridging application that reformats third party data so the Signavio Decision Manager can read it.

There are two options to set up a service so that third party data can be accessed by the Signavio Decision Manager.

The options are represented by the two outgoing request/response channels in the diagram.

  • Direct access: For this, the service URL defined in the Signavio Decision Manager has to be accessible via HTTP(S) GET requests. The service response needs to match the Signavio data format. See how to match the format below.
  • The Range Accessor Service: Signavio offers a reference web application that can either be used as an adapter to map data from existing services or to build up an entirely independent data service. To use this web app provided by Signavio, you need to calibrate Signavio accordingly. Read more at how to implement the Range Accessor Service.

Direct Third Party Access: Data Format

The Signavio system needs the response of an external service request to comply to the following JSON structure:

<response> := <enumResponse> | <hierarchyResponse> | [<enumItem>*]

<enumResponse> := { type: "enumeration", enumItems: [<enumItem>*] }
<enumItem> := { id:<String>, title:<String> }

<hierarchyResponse> := { type: "hierarchy", hierarchyItems: [<hierarchyItem>*] }
<hierarchyItem> := {id:<String>, title:<String>, children: [<hierarchyItem>*] }

The response is either declared as an enumeration or hierarchy and contains a type definition and items.

The following examples serve as references for the data structures necessary.

Example enumeration:

{ type: "enumeration",
   enumItems:  [
      {id:"firstPlace", title:"Gold medal"},
      {id:"secondPlace", title:"Silver medal"},
      {id:"thirdPlace", title:"Bronze medal"}
   ]
}

The enumeration response is a JSON object with a type declaration and a JSON array of enumeration items. Each item is a JSON object with the mandatory attributes id and title. Any other attributes will be ignored.

Example hierarchy:

{
  type: "hierarchy",
  hierarchyItems: [{
    id: "am",
    title: "America"
  }, {
    id: "eu",
    title: "Europe",
    children: [{
      id: "uk",
      title: "United Kingdom"
    }, {
      id: "de",
      title: "Germany",
      children: [{
        id: "berlin",
        title: "Berlin"
      }]
    }, {
      id: "fr",
      title: "France"
    }]
  }, {
    id: "as",
    title: "Asia"
  }]
}

The hierarchy response is a JSON object with a type declaration and an array of hierarchy items. Each item is an object with the mandatory attributes id and title attribute and the optional attribute children. children is an array having the same format as hierarchy items. Any other attributes will be ignored.

Important

The id value must not contain any whitespace characters and the value of the title attribute has to start with an alphabet letter.

Range Accessor Service

Signavio offers a reference web application that can either be used as an adapter to map data from existing services or to build up an entirely independent data service.

To use this service, extend the AbstactExternalValueRange class (using a non-abstract class) and dispatch the RangeServingServlet. This can facilitate the reuse of an existing service. The service can be called and the data can be mapped to the specified data format.

In either way, the output has to comply with the data format as specified above. The sample web app Signavio Range Accessor Service contains (among others) the following files and folders (packages) of interest:

RangeServingServlet.java (com/signavio/rangeservice/servlet)

AbstractExternalValueRange.java (com/signavio/rangeservice/conversion/)

public byte[] getValues(HttpServletRequest req) throws JsonProcessingException {...}.

The subclasses in the example subpackage serve as simple examples of service implementations for enumeration and hierarchy providers.

AbstractRangeExchange.java (com/signavio/rangeservice/util/exchange/)

Important

No other files, folders and jar files should be changed, deleted or moved to ensure proper functionality. Some of them are only of interest at compile time, some at runtime

Creating external data sources

To make use of an external service, it has to be registered in the corresponding Signavio workspace. Open the Signavion Explorer and click Setup - Define notations/attributes in thethe Signavio Explorer and choose the Dictionary configuration tab, then click the link in the explanatory header text:

Click the link to open the management dialog for external data sources.

Click the link to open the management dialog for external data sources.

Now, click Add:

Click 'Add' to register a new service.

Click ‘Add’ to register a new service.

A service consists of a name, a unique URL and a caching configuration:

  • Name

    The name is used as the identifier in the Signavio dictionary.

  • URL

    This is the service URL accessible by an HTTP GET request responding with data in the Signavio data format as specified above.

  • Cache

    It is possible to cache the data temporarily. If activated and configured, the referenced service will not be queried for the caching period, as the system will use the cached values.

    It is highly recommended to activate caching. Otherwise, the service data will be newly requested each time the dictionary entry is loaded. Without caching, if the service is temporarily unavailable, the request the Signavio Decision Manager is making to the service will timeout and the data will be unavailable until the request is answered.

Click Add to register the service:

../../_images/addservice2_en_zoom46.png

To learn how to reference external services when modeling data objects in the Dictionary, read more at Referencing external data sources.