All versions of this manual
X

 Linkurious administration manual

Welcome to the Linkurious administrator documentation. This documentation will help you install, run and customize Linkurious.

Architecture overview

Linkurious is a three-tier application. The presentation layer is a Web application. It uses our graph visualization library, called Ogma, to allow rich interactions with the graph. It also provides a user interface to enable collaboration among end users and data administration.

The presentation layer communicates with the logic layer via a JSON-based REST API. Custom presentation layer application can be developed on top of the logic layer.

The logic layer is a NodeJS-based server. It provides a unified REST API to read, write and search into graph databases from multiple vendors (Neo4j, DataStax, and AllegroGraph). It implements also a security layer with modular authentication that enables role-based access control policies. It can be connected to multiple graph databases at the same time and offers high-level APIs for collaborative exploration of graphs: users can create, share and publish graph visualizations, and multiple users can edit graph data.

Administrators can control it from its REST API for easy automation and deployment. Multiple external authentication providers are supported (LDAP, Active Directory, Windows Azure Active Directory, Google Suite).

The data layer supports several graph databases, as well as indexation engines.

architecture overview

 Getting started: Technical requirements

Linkurious is a Web-application server, it needs to be installed on a server and can then be accessed by multiple users using their Web browser.

Linkurious Server

Technical requirements for the machine used to install the Linkurious Web-application server.

Hardware

For a standard installation of Linkurious, the recommended hardware is:

Please keep in mind that these technical requirements are for Linkurious server only. For hardware requirements regarding your graph database, please refer to these guides:

Elasticsearch

Linkurious includes an embedded Elasticsearch instance for search capabilities. Please keep in mind that this embedded instance will only work for smaller graphs (less than 50M nodes + edges). For larger graphs, you will need to deploy an Elasticsearch cluster. Please refer to Elasticsearch's hardware requirements guide for details.

Operating System

Linkurious server can be deployed on the following platforms:

Java

Linkurious' embedded Elasticsearch engine requires Java JRE (or JDK) 7+.

You can download the latest JRE from Oracle's website.

Installation instructions:

The JAVA_HOME environment variable should be set.

SQLite and GLIBC 2.14

Linkurious uses an embedded SQLite store for user-data persistence. This database requires GLIBC >= 2.14. Some older Linux distributions don't have this version of GLIBC available. You can check the version available on your system on http://distrowatch.com.

If SQLite does not work on your system, please refer to the user-data store documentation section to learn how to use alternative databases.

Linkurious Client

Technical requirements for users who want to access Linkurious with their Web browser.

Hardware

Hardware requirements of the Linkurious Web client vary with the size of the visualized graphs. For up to 500 nodes and edges in a single visualization, we recommend to use a machine with 4 GB RAM, and 2 CPU cores @ 1.6 Ghz.

The minimal screen resolution is 1024 x 768.

Web Browser

End-users will access Linkurious through a Web browser. All modern browsers are supported:

 Getting started: Downloading

Where to download from

The latest version of Linkurious can be downloaded from at https://linkurio.us/my-account/.

Log in with the username and password created during the purchase process. You will then see the downloadable files:

Archive content

The ZIP file contains:

Staying up-to-date

Please see our documentation on how to update Linkurious.

 Getting started: Installing

Linux systems

  1. Unzip Linkurious' archive: >unzip linkurious-linux-v1.8.4.zip
  2. Enter the Linkurious folder: >cd linkurious-linux
  3. Check the configuration file at linkurious-linux/data/config/production.json (see how to configure a data-source)
  4. Make Java JRE 7+ is installed (type java -version in a terminal), if needed, install Java.

See how to start Linkurious on Linux.

Windows systems

  1. Unzip Linkurious' archive (right-click on the file, then "Extract all")
  2. Enter the linkurious-windows folder
  3. Check the configuration file at linkurious-windows/data/config/production.json (see how to configure a data-source)
  4. Make sure that you have Java JRE 7+ installed (see Java JDK requirements)

See how to start Linkurious on Windows.

Mac OS X systems

  1. Unzip Linkurious' archive: >unzip linkurious-osx-v1.8.4.zip
  2. Enter the Linkurious folder: >cd linkurious-osx
  3. Check the configuration file at linkurious-osx/data/config/production.json (see how to configure a data-source)
  4. Make Java JRE 7+ is installed (type java -version in a terminal), if needed, install Java.

See how to start Linkurious on Mac OS X.

Installing as a service.

In order to run Linkurious automatically when the operating system starts, it is possible to install Linkurious as a system service on Linux, Mac OS X and Windows.

Linux systems

  1. Open the administration menu by running menu.sh in the linkurious-linux folder.
  2. Check if Linkurious is already installed as a service (displayed at the top of the menu).
  3. Select Install Linkurious as a service.
  4. Linkurious will install itself as a service of your operating system.

Windows systems

  1. Open the administration menu by running menu.bat in the linkurious-windows folder.
  2. Check if Linkurious is already installed as a service (displayed at the top of the menu).
  3. Select Install Linkurious as a service.
  4. Linkurious will install itself as a service of your operating system.

Mac OS X systems

  1. Open the administration menu by running menu.sh.command in the linkurious-osx folder.
  2. Check if Linkurious is already installed as a service (displayed at the top of the menu).
  3. Select Install Linkurious as a service.
  4. Linkurious will install itself as a service of your operating system.

 Getting started: Starting Linkurious

Linux systems

To start Linkurious, run the start.sh script in the linkurious-linux directory.

Alternatively, run the menu.sh script and select Start Linkurious processes from the console.

By default, Linkurious server will listen for connection on port 3000. However, some firewalls block network traffic ports other than 80 (HTTP). See the Web server configuration documentation to learn how to make Linkurious listen on port 80.

Windows systems

To start Linkurious, run the start.bat script in the linkurious-windows directory.

Alternatively, run the menu.bat script and select Start Linkurious from the console.

The firewall of Windows might ask you to authorize connections with Linkurious.

If so, click on Authorize access.

Content of the linkurious-windows directory: Content of the linkurious-windows directory

Linkurious starting up on Windows: startup window

Mac OS X systems

To start Linkurious, run the start.sh.command script in the linkurious-osx directory.

Alternatively, run the menu.sh.command script and select Start Linkurious processes from the console.

 Getting started: Stopping Linkurious

Linux systems

Run the stop.sh script in the linkurious-linux directory.

Alternately, run menu.sh and select Stop Linkurious processes from the console.

Windows systems

Run the stop.bat script in the linkurious-windows directory.

Alternately, run menu.bat and select Stop Linkurious from the console.

Mac OS X systems

Run the stop.sh.command script in the linkurious-osx directory.

Alternately, run menu.sh.command and select Stop Linkurious processes from the console.

 Troubleshooting: Checking Linkurious' status

Process monitoring

Linkurious starts 3 separate processes when launched:

Check if these processes are alive by opening the menu from the Linkurious directory (see how on each operating system below).

The menu looks like this: Linkurious manager menu

Linux systems

Run menu.sh (the status is above the menu). Alternately, run menu.sh status.

Windows systems

Run menu.bat (the status is above the menu). Alternately, run menu.bat status.

Mac OS X systems

Run menu.sh.command (the status is above the menu). Alternately, run menu.sh.command status.

API status

The status of the API can be retrieved using a browser or a command line HTTP client like cURL.

To retrieve the API status, send a GET request to http://127.0.0.1:3000/api/status (replace 127.0.0.1 and 3000 with the actual host and port of your server).

// example response 
{"status":{"code":200,"name":"initialized","message":"Linkurious ready to go :)","uptime":8633}}

API version

The version of the API can be retrieved using a browser or a command line HTTP client like cURL.

To retrieve the API status, send a GET request to http://127.0.0.1:3000/api/version (replace 127.0.0.1 and 3000 with the actual host and port of your server).

// example response 
{"tag_name":"1.8.4","name":"Xenodochial Xenoposeidon","prerelease":false,"enterprise":true}

 Troubleshooting: Reading the logs

The logs of the application are located in linkurious/data/manager/logs folder:

For a structured version of the Linkurious server logs in JSONL format, see the linkurious/data/logs folder:

 Troubleshooting: Getting support

If you need to get support regarding a issue or a question, please contact use at support@linkurio.us.

 Importing graph data

Before starting to explore the content of your graph database using Linkurious, you need to import data in your graph database.

The following sections will help you import data into your graph:

  1. Neo4j
  2. DataStax Enterprise Graph
  3. AllegroGraph
  4. Titan DB

If already have data in your graph database or you don't need to import anything, see how to configure your graph database with Linkurious.

 Importing graph data: Neo4j

Linkurious relies on Neo4j to store the data. The data importation is thus not handled by our solution. Many options exist to import data into Neo4j:

Finally, if you want to quickly try Linkurious with an example dataset, you can download a Neo4j-compatible example dataset.

 Importing graph data: DataStax Enterprise Graph

Please refer to the DataStax online documentation about DSE Graph Loader for details on how to load data into DSE Graph.

 Importing graph data: AllegroGraph

Please refer to the AllegroGraph online documentation about AllegroGraph Loader for details on how to load data into AllegroGraph.

 Importing graph data: Titan DB

Please refer to the Titan online documentation about Bulk Loading for details on how to load data into Titan DB.

 Updating Linkurious

We release a new version of Linkurious every couple of month on average. New releases include new features, improvements, and bug fixes.

The following pages will help you check for updates, back-up Linkurious before updating, and update Linkurious.

 Updating Linkurious: Checking for updates

About menu

Administrators can manually check if updates of Linkurious are available by opening the "about" menu from Dashboard > account menu > about.

Example "about" menu: about page example

Public version API

Another options is to open http://linkurio.us/version/linkurious-enterprise.json

// example output: 
{
  "tag_name": "v1.8.4", // latest version of Linkurious 
  "message": null,
  "url": "https://linkurio.us/my-account/" // where to download the latest version from 
}

 Updating Linkurious: Backing up your data

Follow these steps to perform a backup of your Linkurious data:

  1. Stop Linkurious
  2. Back-up of the linkurious/data folder.
  3. Back-up the user-data store
  4. Start Linkurious

Please note that this procedure does not back-up your graph data, but only your Linkurious configuration and user-data (visualizations, users, etc.).

 Updating Linkurious: Update procedure

If you follow this procedure, you will be able to update Linkurious to a newer version without loosing your configuration and user-data store. You data will be automatically migrated to the never version.

Before updating, make sure that you have backed-up your data in case something unexpected happens.

During the update procedure, if Linkurious is running, it will be stopped. You will need to re-start Linkurious after the update procedure.

  1. Download the newer version you wish to install (see how to download Linkurious)
  2. Copy linkurious-xxx-v1.8.4.zip in your current Linkurious directory (along the start stop and update scripts)
  3. Run the update script (Linux: update.sh, OSX: update.sh.command, Windows: update.bat)
  4. Done! You can restart Linkurious.

Troubleshooting

If the update script fails, please check the update log located at linkurious/data/update.log for details.

 Configuring data-sources

By default, Linkurious is configured to connect to a Neo4j database at 127.0.0.1:7474.

There are several ways to edit data-source configuration if you need to change the default configuration, or if you want to add an additional data-source.

Supported vendors

Linkurious can connect to some of the the most popular graph databases:

Multi-database support

Linkurious is able to connect to several graph databases at the same time and lets you switch from one database to another seamlessly.

Edit the data-source configuration

Using the Web user interface

Using an administrator account, access the Admin > Data menu to edit the current data-source configuration: admin-data menu

Edit the data-source configuration to match your graph database edit data-source configuration form

Submit the changes by hitting the Save configuration button save data-source configuration

Using the configuration file

Edit the configuration file located at linkurious/data/config/production.json.

See details for each supported graph database vendor:

 Configuring data-sources: Neo4j

Neo4j is supported from version 2.0.

Configuration file

To edit the Neo4j data-source configuration, you can either use the Web user-interface or edit the configuration file located at linkurious/data/config/production.json.

Example Neo4j configuration:

{
  "dataSources": [
    {
      "graphdb": {
        "vendor": "neo4j",
        "url": "http://127.0.0.1:7474/",
        "user": "MY_NEO4J_USER",
        "password": "MY_NEO4J_PASSWORD"
      },
      "index": {
        "vendor": "elasticSearch",
        "host": "127.0.0.1",
        "port": 9201
      }
    }
  ]
}

Supported graphdb options with Neo4j:

Search with Neo4j

For supported index options, see our documentation about search with Neo4j.

Neo4j credentials

Since Neo4j v2.2, you need to create credentials for Neo4j before using it. If you just installed Neo4j, these steps will help you create credentials:

  1. Launch the Neo4j server
  2. Open your Web browser at http://127.0.0.1:7474
  3. Follow the instructions to create a new username and password

Alternatively, you can disable credentials in Neo4j by editing the Neo4j configuration at neo4j/conf/neo4j.conf and uncommenting the following line:

dbms.security.auth_enabled=false

 Configuring data-sources: DataStax Enterprise Graph

DataStax Enterprise Graph is supported from version 5.0.4.

Prerequisites

In order to use DSE Graph with Linkurious is necessary that the option graph.tx_autostart is set to true on your current database.

Enable it via the DSE gremlin console by typing:

:remote config alias g <graphName>.g
graph.schema().config().option('graph.tx_autostart').set('true')

Depending on the search connector you will use, it may be necessary to set to true also the option graph.allow_scan.

:remote config alias g <graphName>.g
graph.schema().config().option('graph.allow_scan').set('true')

Configuration file

To edit the DSE Graph data-source configuration, you can either use the Web user-interface or edit the configuration file located at linkurious/data/config/production.json.

Example DSE Graph configuration:

{
  "dataSources": [
    {
      "graphdb": {
        "vendor": "dse",
        "url": "ws://127.0.0.1:8182/",
        "graphName": "MY_GRAPH"
      },
      "index": {
        "vendor": "elasticSearch",
        "host": "127.0.0.1",
        "port": 9201
      }
    }
  ]
}

Supported graphdb options for DSE Graph:

Search with DSE Graph

For supported index options, see our documentation about search with DSE Graph.

 Configuring data-sources: AllegroGraph

AllegroGraph is supported from versions 5.0.

Configuration file

To edit the AllegroGraph data-source configuration, you can either use the Web user-interface or edit the configuration file located at linkurious/data/config/production.json.

Example AllegroGraph configuration:

{
  "dataSources": [
    {
      "graphdb": {
        "vendor": "allegroGraph",
        "url": "http://127.0.0.1:10035/",
        "repository": "MY_REPOSITORY"
      },
      "index": {
        "vendor": "elasticSearch",
        "host": "127.0.0.1",
        "port": 9201
      }
    }
  ]
}

Supported graphdb options for AllegroGraph:

Search with AllegroGraph

For supported index options, see our documentation about search with AllegroGraph.

 Configuring data-sources: Titan DB

Titan DB is supported from version 1.0.

Configuration file

To edit the Titan DB data-source configuration, you can either use the Web user-interface or edit the configuration file located at linkurious/data/config/production.json.

Example Titan DB configuration:

{
  "dataSources": [
    {
      "graphdb": {
        "vendor": "titan",
        "url": "ws://127.0.0.1:8182/",
        "configurationPath": "/usr/local/titan/config/titan-cassandra-es.properties"
      },
      "index": {
        "vendor": "elasticSearch",
        "host": "127.0.0.1",
        "port": 9201
      }
    }
  ]
}

Supported graphdb options for Titan DB:

Search with Titan DB

For supported index options, see our documentation about search with Titan DB.

 Configuring data-sources: Alternative IDs

When you save a visualization in Linkurious, only the node and edge identifier are persisted in the user-data store, along with position and style information. When a visualization is loaded, the node and edge identifiers are used to reload the actual node and edge data from the graph database.

If you need to re-generate your graph database from scratch, the graph database will probably generate new identifiers for all nodes and edges, breaking all references to nodes and edges in existing visualizations.

Using a property as a stable identifier

You can configure Linkurious to use a node or edge property as stable identifiers. Once set-up, Linkurious will use the given property as identifier instead of using the identifiers generated by the database.

Thank to this strategy, visualizations will be robust to graph re-generation.

Notice that the properties used as identifier should be indexed by the database to allow for a fast lookup by value.

Alternative identifiers configuration

To use alternative node and edge identifiers, edit your data-source database configuration in the configuration file (linkurious/data/config/production.json):

Example of alternative identifier configuration with Neo4j:

{
  "dataSources": [
    {
      "graphdb": {
        "vendor": "neo4j",
        "url": "http://127.0.0.1:7474/",
        "alternativeNodeId": "STABLE_NODE_PROPETY_NAME",
        "alternativeEdgeId": "STABLE_EDGE_PROPETY_NAME"
      }
      // [...] 
    }
  ]
}

Stable sourceKey in Neo4j

Linkurious generates a unique identifier for data-source, based on internal information from the data-source. This data-source identifiers (called the sourceKey) is used identify all user-data (visualizations etc.) that belongs to a data-source.

When re-generating a Neo4j graph database, the sourceKey will change. In order to avoid breaking all references to existing visualisations, it is possible to manually the sourceKey of a data-source.

Before re-generating the graph database, go to the Admin > Sources menu: sources admin menu

In the sources administration panel, find the Key value for your data-source (e.g. 1c3490bd) and copy it.

Then, edit the configuration file (production.json) and set manualSourceKey for yur data-source:

{
  "dataSources": [
    {
      "manualSourceKey": "1c3490bd",
      "graphdb": {
        "vendor": "neo4j",
        "url": "http://127.0.0.1:7474/"
      }
      // [...] 
    }
  ]
}

 Configuring data-sources: Advanced settings

The following are advanced data-source settings that apply to all data-sources. They can be changed in the configuration file (linkurious/data/config/production.json) under the advanced key.

General settings

Search engine settings

Graph exploration settings

Additional Certificate Authorities

Password obfuscation

 Search index

Linkurious allow you to search your graph using natural full-text search.

In order to offer the search feature out-of-the-box, Linkurious ships with an embedded Elasticsearch server. The option allow for zero-configuration deployment in many cases.

Indexing your graph data

By default, Linkurious uses Elasticsearch for search. This options requires Linkurious to index your graph database, which technically means that Linkurious will feed the whole content of the graph database to Elasticsearch to make it searchable. The time required to index the graph database increases with the size of the graph and this solution has limits in its scalability.

Indexation typically happens at speeds between 2000 and 20000 nodes or edges per second, depending on the number of properties for nodes and edges, and hardware performances.

Embedded Elasticsearch

By default, Linkurious ships with an embedded Elasticsearch server (version 1.4.5). This server only listens for local connections on a non-default port (it binds to 127.0.0.1:9201), for security reasons and to avoid collisions with existing servers.

Use your own Elasticsearch

It is possible to use your own Elasticsearch cluster for performances reasons. Linkurious supports Elasticsearch v1.x as well as v2.x. See details about Elasticsearch configuration options.

Search scalability and alternatives to Elasticsearch

Using Elasticsearch is convenient but may not fit cases where the graph database is big (more a a couple million nodes and edges) and is regularly modified from outside Linkurious, which required to re-index the whole database.

In order to offer a scalable search feature on big graphs, Linkurious offers alternatives search solution:

Edit the search configuration

Using the Web user interface

The index configuration can be changed from the administration interface.

Using an administrator account, access the Admin > Data menu to edit the current data-source configuration: admin-data menu

Edit the data-source index configuration: edit data-source configuration form

Submit the changes by hitting the Save configuration button save data-source configuration

Using the configuration file

Edit the configuration file located at linkurious/data/config/production.json.

See details for each supported search connector:

 Search index: Neo4j

Neo4j supports search with the elasticSearch, elasticSearch2 and neo2es connectors.

See details on how to configure ElasticSearch with Linkurious.

Neo4j-to-elasticsearch integration

Neo4j-to-elasticsearch is a Neo4j plugin that allows for automatic synchronization between Neo4j and Elasticsearch. This means that all changes to Neo4j are automatically propagated to Elasticsearch.

Resources for supported versions of neo4j-to-elasticsearch:

Install neo4j-to-elasticsearch

Follow these steps to use install this Neo4j plugin:

  1. Download the GraphAware framework JAR
    • Choose a version A.B.C.x where A.B.C matches your Neo4j version and x is 44 or later.
  2. Download the neo4j-to-elasticsearch JAR
    • Choose a version A.B.C.x.y where A.B.C matches your Neo4j version and x.y is 44.8 or later.
  3. Copy graphaware-server-community-all-A.B.C.x.jar and graphaware-neo4j-to-elasticsearch-A.B.C.x.y.jar to your neo4j/plugins directory
  4. Edit the Neo4 configuration at neo4j/conf/neo4j.conf and add the following lines at the beginning of the file:
    com.graphaware.runtime.enabled=true
    com.graphaware.module.ES.1=com.graphaware.module.es.ElasticSearchModuleBootstrapper
    com.graphaware.module.ES.uri=HOST_OF_YOUR_ELASTICSEARCH_SERVER
    com.graphaware.module.ES.port=PORT_OF_YOUR_ELASTICSEARCH_SERVER
    com.graphaware.module.ES.relationship=(true)
    com.graphaware.module.ES.mapping=AdvancedMapping
    com.graphaware.module.ES.keyProperty=ID()
  5. Restart Neo4j

Integrate with Linkurious

Once the neo4j-to-elasticsearch plugin is installed, you need to change the data-source configuration to use the neo2es vendor.

Set the dataSources.index.vendor key to neo2es in the configuration (linkurious/data/config/production.json):

{
  "dataSources": [
    {
      "graph": {
        "vendor": "neo4j"
        "url": "http://127.0.0.1:7474"
      },
      "index": {
        "vendor": "neo2es"
      }
    }
  ]
}

Restart Linkurious after saving the configuration.

 Search index: DataStax Enterprise Graph

DataStax Enterprise Graph supports search with the elasticSearch, elasticSearch2 and dseSearch connectors. See details on how to configure ElasticSearch with Linkurious.

The dseSearch connector is strongly recommended for graphs with more than 100'000 nodes and edges.

DSE Search integration

DSE Search in DataStax Enterprise's built-in search engine. You can learn more about DSE Search from DataStax' documentation.

Index with DSE Search

Please refer to DataStax' documentation on how to create new indices, including search indices. Follow these steps to use DSE Search and integrate it with Linkurious:

  1. Connect via gremlin to DSE Graph
  2. For each node label execute this command:
    schema.vertexLabel("MY_NODE_LABEL").index("search").search()
      .by("MY_NODE_PROPERTY_1").asText()
      .by("MY_NODE_PROPERTY_2").asText()
      .by("MY_NODE_PROPERTY_3").asText()
      .by("MY_NODE_PROPERTY_N").asText()
      .add();
    Every property key that you want to index has to appear in this command. You can add as many properties as you want.

We recommend to create asText() search indices instead of asString() ones. Both types of indices are supported by Linkurious, but the latter doesn't support OR search queries. If you don't need this feature, asString() indices will actually compute search queries faster. It's also possible to mix asText() and asString() indices to find a balance of features and performances.

Integrate with Linkurious

Set the dataSources.index.vendor key to dseSearch in the configuration (linkurious/data/config/production.json):

{
  "dataSources": [
    {
      "graph": {
        "vendor": "dse",
        "url": "ws://127.0.0.1:8182/",
        "graphName": "MY_GRAPH"
      },
      "index": {
        "vendor": "dseSearch"
      }
    }
  ]
}

Restart Linkurious after saving the configuration.

 Search index: AllegroGraph

AllegroGraph supports search with the elasticSearch, elasticSearch2 and allegroGraphSearch connectors.

See details on how to configure ElasticSearch with Linkurious.

The allegroGraphSearch connector is strongly recommended for graphs with more than 1'000'000 triples.

AllegroGraph search integration

Linkurious can search for nodes directly on the free-text indices managed by AllegroGraph itself. To do so, you have to configure the vendor property under index to the value "allegroGraphSearch" and configure AllegroGraph accordingly to have a free-text index.

If you already have a free-text index, skip the next step.

Create a free-text index in AllegroGraph

  1. Go to the repository page on AllegroGraph WebView (by default at http://127.0.0.1:10035)
  2. Press Manage free-text indices
  3. Create a new free-text index, the name is irrelevant
  4. The default options for the newly created index should be enough. You must ensure that "Objects" under Fields to index is highlighted.

Integrate with Linkurious

Set the dataSources.index.vendor key to allegroGraphSearch in the configuration (linkurious/data/config/production.json):

{
  "dataSources": [
    {
      "graph": {
        "vendor": "allegroGraph",
        "url": "http://127.0.0.1:10035/",
        "repository": "MY_REPOSITORY"
      },
      "index": {
        "vendor": "allegroGraphSearch"
      }
    }
  ]
}

Restart Linkurious after saving the configuration.

 Search index: Titan DB

Titan DB supports search with the elasticSearch and elasticSearch2 connectors.

See details on how to configure ElasticSearch with Linkurious.

 Search index: Properties disclosure

By default, all node and edge properties are available to users of Linkurious. You can make some properties unavailable. Unavailable properties will no longer be accessible or searchable.

Open the Admin > Data menu, and scroll down to the Node properties section. All properties are marked as available in the following example.

node properties disclosure

 Search index: Configuring ElasticSearch

ElasticSearch is supported from 1.4+ (for elasticSearch connector) and from version 2.0 (for elasticSearch2 connector).

Embedded Elasticsearch

Linkurious ships with an embedded Elasticsearch server (version 1.4.5).

To use Linkurious' embedded Elasticsearch instance, simply set the following index configurations keys:

Example configuration:

{
  "dataSources": [
    {
      "graph": {
        "vendor": "neo4j"
        "url": "http://127.0.0.1:7474"
      },
      "index": {
        "vendor": "elasticSearch",
        "host": "127.0.0.1",
        "port": 9201
      }
    }
  ]
}

Configuring Elasticsearch v1.x

Search connector elasticSearch supports the following options:

Example configuration:

{
  "dataSources": [
    {
      "graph": {
        "vendor": "neo4j"
        "url": "http://127.0.0.1:7474"
      },
      "index": {
        "vendor": "elasticSearch",
        "host": "192.168.1.80",
        "port": 9200,
        "dynamicMapping": false
      }
    }
  ]
}

Configuring Elasticsearch v2.x

Search connector elasticSearch2 supports the following options:

Example configuration:

{
  "dataSources": [
    {
      "graph": {
        "vendor": "neo4j"
        "url": "http://127.0.0.1:7474"
      },
      "index": {
        "vendor": "elasticSearch2",
        "host": "192.168.1.122",
        "port": 9200,
        "skipEdgeIndexation": true
      }
    }
  ]
}

 Search index: Using ElasticSearch on AWS

By default, Linkurious ships with an embedded Elasticsearch instance which works out-of-the-box by default. The embedded Elasticsearch instance will work well for average to large database sizes, but for search-heavy use-cases or very large databases, configuring your own ElasticSearch cluster might be necessary.

An easy way to deploy an easy-to-scale Elasticsearch cluster yourself is to use Amazon Web Services (AWS).

Please follow these steps to create a configure your AWS Elasticsearch cluster with Linkurious:

Create your AWS account

Visit the Amazon Web Services website and create your account (or log in if you already have one).

Create a new cluster

Visit the Amazon Elasticsearch Service page, log-in and follow the steps to create an Elasticsearch cluster:

  1. Select "services" > "Elasticsearch Service"
  2. Hit "get started"
  3. Name your cluster (1) and select the Elasticsearch version 2.x (2), hit "Next"
  4. Select the instance type, number of instances and number of dedicated masters in your cluster (3), depending on your database's size.
  5. Configure the access policy for your cluster. Use "access from specific IP" (4) and enter the public IP address of your Linkurious server (5)
  6. Review your configuration and confirm the creation of the cluster.
  7. Wait until the cluster is deployed (usually less than an hour).
  8. When your cluster is deployed, copy the "Endpoint" host name
  9. Stop the Linkurious server
  10. Open the configuration file (linkurious/data/config/production.json) and edit the following fields:
    {
      // [...] 
      "dataSources": [{
        "name": "My Graph DB",
        "graphdb": {
          // configuration or you graph database 
        },
        "index": {
          "vendor": "elasticSearch2",
          // "Endpoint" value copied in step (8.) 
          "host": "search-linkurious-es-ty7pcetbrp6eylauybpqv3dwwa.us-west-2.es.amazonaws.com",
          // AWS Elasticsearch instances listen to port 80 by default 
          "port": 80,
          // other optional index configuration options 
          "dynamicMapping": false,
          "skipEdgeIndexation": false
        }
      }]
      // [...] 
    }
  11. Restart Linkurious

 User-data store

Linkurious uses an SQL database to store user-data. The database contains:

By default, the user-data store is a SQLite file-based database. This makes Linkurious easy to deploy.

For deployment at scale (more than a couple users), we recommend switching to one of the supported server-based databases:

Configure with SQLite

SQLite if the default user-data store of Linkurious.

"db": {
    "name": "linkurious",
    "options": {
      "dialect": "sqlite"
      "storage": "server/database.sqlite"
    }
}

Configure with MySQL

"db": {
    "name": "linkurious",
    "username": "MYSQL_USER_NAME",
    "password": "MYSQL_PASSWORD",
    "options": {
      "dialect": "mysql",
      "host": "MYSQL_HOST",
      "port": 3306
    }
}

Configure with Microsoft SQL Server

"db": {
    "name": "linkurious",
    "username": "MSSQL_USER_NAME",
    "password": "MSSQL_PASSWORD",
    "options": {
      "dialect": "mssql",
      "host": "MSSQL_HOST",
      "port": 1433
    }
}

Configure with MariaDB

"db": {
    "name": "linkurious",
    "username": "MARIADB_USER_NAME",
    "password": "MARIADB_PASSWORD",
    "options": {
      "dialect": "mariadb",
      "host": "MARIADB_HOST",
      "port": 3306
    }
}

 User-data store: Migrating to MySQL

The default storage system for Linkurious' user-data store is SQLite.

This is the procedure to migrate from SQLite to MySQL.

  1. Export the SQLite database to a file:
    sqlite3 ./linkurious/data/server/database.sqlite .dump > export.sql
  2. Load the exported database into MySQL:
    mysql -u MY_MYSQL_USER -p -h 127.0.0.1 linkurious < export.sql
  3. Update Linkurious configuration to connect to MySQL

 User-data store: Backing-up your store

If you are using the SQLite database (by default), you only need to follow the standard Linkurious backup procedure.

If you are using another database to store the Linkurious user-data, please refer to one of the following guides:

 Web server

The web server of Linkurious delivers the application to end users through HTTP/S. It is configured within the server configuration key within the configuration file (linkurious/data/config/production.json):

General

Within the server key:

Some firewalls block network traffic ports other than 80 (HTTP). Since only root users can listen on ports lower than 1024, you may want reroute traffic from 80 to 3000 as follows:

sudo iptables -t nat -A PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 3000

If you use SSL, you can add a second rule to redirect 3443 to 443:

sudo iptables -t nat -A PREROUTING -p tcp --dport 443 -j REDIRECT --to-port 3443

Link generation

Within the server key:

In some cases, Linkurious needs to generate links to itself (for example when generating links to the widget). For that, the server needs to know its public domain and port to generate those links.

The public port can be different from the actual port if you use traffic rerouting (using a firewall or a reverse-proxy). In the example above (traffic rerouting), the actual HTTP port (listenPort) is 3000, but the public HTTP port (publicPortHttp) is 80.

Cookies

Within the server key:

Cross-origin resource sharing (CORS)

Within the server key:

Image cross-origin (client-side)

Within the sigma key:

SSL

Within the server key:

External communications with the Linkurious server can be secured using SSL without installing third-party software.

If the Linkurious server, graph database, and the search index are installed on different machines, we recommend to encrypting communication between them. Please refer to the data-source documentation and search index documentation to learn how to enable HTTPS.

 Web server: Client analytics

The Linkurious client can log user actions by sending events to your Google Analytics account. They provide information of the way the application is used, which features are the most useful, etc. This feature is disabled by default and no external script is injected in this case. It is configured within the clientAnalytics key:

 Access control

Configuring access

The user-access system is configured within the access configuration key in the configuration file (linkurious/data/config/production.json):

Local vs. external authentication

To access Linkurious when authRequired is true, users need accounts in Linkurious. Administrators can create accounts directly in Linkurious (see how to create users) or rely on an external authentication service. Linkurious supports the following external authentication services:

If your company uses an authentication service that Linkurious does not support yet, please get in touch.

 Access control: Enabling authentication

We strongly advise you to enable user authentication to secure the access to your data once Linkurious is deployed on a server. This will allow you to enforce the limit of authenticated users with regards to your license terms.

By default, user authentication is disabled and all actions are performed under the special account named "Unique User". The unique user has unrestricted access and does not require a password, so anyone can access the platform.

Before enabling user authentication we must create an administrator account.

You need to create an administrator account before enabling authentication, otherwise you will not be able to log in.

Let's create an administrator account. Select the Users from the Admin menu of the navigation bar. Once the user management dashboard is displayed, click on the Add button next to "No Users".

The user creation form appears: user creation form

Fill in all the fields and especially add the admin group in the groups field to grant administration rights to the new user. When done, click Save.

Once you have create the first administrator, you can enable user authentication. Edit the configuration file (linkurious/data/config/production.json) and set the authRequired key to true (see how to configure access). Restart Linkurious. User authentication is now enabled. Reload the user interface of the Web application to display the login screen.

login screen

 Access control: Users, groups and rights

Linkurious relies on a role-based access control model based on node-categories and edge-types:

When users belong to several user-groups, it can happen that many access-rights are defined for a node-category (or edge-type). In this case, the more permissive access-right is granted.

Example

Creating users, groups and rights

To create users, user-groups and access-rights, administrators can use the Web user interface via the Admin > Users menu: admin-users menu

Password hashing

Passwords are hashed with the PBKDF2 algorithm and the following parameters:

External users

When using an external source for authentication (LDAP, Active Directory, OpenID Connect etc.), users are automatically created in Linkurious when they first connect.

These shadow-users allow to store Linkurious specific data such as user preferences, user-groups and other objects (visualizations, etc.). Passwords of external users are never stored inside Linkurious.

The user-group that will be attributed to these users is the default user-group (with read-all access), unless you specify a group ID in access.externalUserDefaultGroupId or you configure a group mapping. (see details on how to configure access).

Group mapping

If an external source already organizes users in groups, it's possible to use this information to map automatically external groups to Linkurious groups. To do so, you have to set the access.externalUsersGroupMapping configuration key to be an object with the external group IDs as keys and the internal group IDs as values.

For example, if we want to provide group mapping for Microsoft Active Directory:

{ // under the access configuration key 
  // ... 
  "externalUsersGroupMapping": {
    "Administrators": 2 // any Active Directory admin is a Linkurious admin 
  }
  // ... 
}

Note that for some identity providers the external group IDs is the actual group name, for others is an ID:

To exclude some groups of users from logging in into Linkurious, set up a list of authorized groups in the configuration key access.externalUsersAllowedGroups.

 Access control: LDAP

In Linkurious, administrators manage other user accounts. User accounts are identified by either a login or an e-mail address.

If Linkurious is connected to an LDAP service (preferably OpenLDAP or Active Directory), users are authenticated using the external service at each log-in.

If you have a LDAP service running in your network, you can use it to authenticate users in Linkurious.

OpenLDAP

For OpenLDAP compatible providers, add an ldap section inside the access section.

Allowed options in access.ldap:

The bindDN and bindPassword are optional. If specified they will be used to bind to the LDAP server.

Example LDAP configuration:

"access": {
  // [...] 
  "ldap": {
    "enabled": true,
    "url": "ldap://ldap.forumsys.com:389",
    "bindDN": "cn=read-only-admin,dc=example,dc=com",
    "bindPassword": "password",
    "baseDN": ["dc=example,dc=com"],
    "usernameField": "uid",
    "emailField": "mail",
    "groupField": "group",
    "authorizedGroups": ["group1", "group2"]
  }
}

Contact your network administrator to ensure that the machine where Linkurious is installed can connect to the LDAP service.

Active Directory

For Microsoft Active Directory, add a msActiveDirectory section inside the access section.

Allowed options in access.msActiveDirectory:

Example Active Directory configuration:

"access": {
  // [...] 
  "msActiveDirectory": {
    "enabled": true,
    "url": "ldap://ldap.lks.com",
    "baseDN": "dc=ldap,dc=lks,dc=com",
    "domain": "ldap.lks.com"
  }
}

In alternative is possible to use your on premises Active Directory in conjunction with Azure Active Directory to provide SSO to your users. Please refer to Prerequisites for Azure AD Connect for more information and to SSO with Azure AD to know how to setup Azure AD as an authentication provider.

 Access control: SSO with Azure AD

Linkurious supports Microsoft Azure Active Directory an external authentication provider.

To set up Linkurious authentication with Microsoft Azure Active Directory, follow these steps:

  1. Create a new app called Linkurious in Azure Active Directory on Azure Portal
  2. From the Azure Portal, obtain the following parameters:
    • authorizationURL, e.g. https://login.microsoftonline.com/60d78xxx-xxxx-xxxx-xxxx-xxxxxx9ca39b/oauth2/authorize
    • tokenURL, e.g. https://login.microsoftonline.com/60d78xxx-xxxx-xxxx-xxxx-xxxxxx9ca39b/oauth2/token
    • clientID, e.g. 91d426e2-xxx-xxxx-xxxx-989f89b6b2a2
    • clientSecret, e.g. gt7BHSnoIffbxxxxxxxxxxxxxxxxxxtyAG5xDotC8I=
    • tenantID, (optional, required only for group mapping) e.g. 60d78xxx-xxxx-xxxx-xxxx-xxxxxx9ca39b
  3. Add an oauth2 section inside the access section in Linkurious' configuration (linkurious/data/config/production.json)

Example access.oauth2 configuration with Microsoft Azure Active Directory:

"access": {
  // [...] 
  "oauth2": {
    "enabled": true,
    "provider": "azure",
    "authorizationURL": "https://login.microsoftonline.com/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/oauth2/authorize",
    "tokenURL": "https://login.microsoftonline.com/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/oauth2/token",
    "clientID": "XXXXXXXX-XXX-XXXX-XXXX-XXXXXXXXXXXX",
    "clientSecret": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "azure": {
      "tenantID": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
    }
  }
}

 Access control: SSO with Google

Linkurious supports Google Suite (a.k.a. Google Apps) as an external authentication provider (with Single Sign-On).

Since Google Suite implements the OpenID Connect standard, this can be configured using Linkurious' OpenID Connect provider.

To set up Linkurious authentication with Google Suite, follow these steps:

  1. Create the credentials on your Google Developers console.
  2. From the portal, obtain the following parameters:
    • authorizationURL, e.g. https://accounts.google.com/o/oauth2/v2/auth
    • tokenURL, e.g. https://www.googleapis.com/oauth2/v4/token
    • clientID, e.g. 1718xxxxxx-xxxxxxxxxxxxxxxx.apps.googleusercontent.com
    • clientSecret, e.g. E09dQxxxxxxxxxxxxxxxxSN

To limit the access to the Google accounts from your Google Suite domain, remember to add the hd query parameter to the authorizationURL with your domain as value.

Example access.oauth2 configuration with Google Suite:

"access": {
  // [...] 
  "oauth2": {
    "enabled": true,
    "provider": "openidconnect",
    "authorizationURL": "https://accounts.google.com/o/oauth2/v2/auth?hd=YOUR_GSUITE_DOMAIN.COM",
    "tokenURL": "https://www.googleapis.com/oauth2/v4/token",
    "clientID": "XXXXXXXXXX-XXXXXXXXXXXXXXXX.apps.googleusercontent.com",
    "clientSecret": "XXXXXXXXXXXXXXXXXXXXXXX"
  }
}

 Access control: SSO with OpenID Connect

Linkurious supports any OpenID Connect compatible provider as external authentication providers.

What is OpenID Connect?

OpenID Connect is an identity layer on top of the OAuth2 protocol. It allows applications (like Linkurious) to verify the identity of End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable manner.

Configuration

To set up Linkurious authentication with an OpenID Connect provider, you need to obtain the following parameters from the provider:

Example access.oauth2 configuration with an OpenID Connect provider:

"access": {
  // [...] 
  "oauth2": {
    "enabled": true,
    "provider": "openidconnect",
    "authorizationURL": "https://accounts.google.com/o/oauth2/v2/auth",
    "tokenURL": "https://www.googleapis.com/oauth2/v4/token",
    "clientID": "XXXXXXXXXX-XXXXXXXXXXXXXXXX.apps.googleusercontent.com",
    "clientSecret": "XXXXXXXXXXXXXXXXXXXXXXX"
  }
}

Group mapping in OIDC

To set up group mapping in OpenID Connect is necessary to specify additional configuration keys:

For example if you want to set up OIDC with Okta:

"access": {
  // [...] 
  "oauth2": {
    "enabled": true,
    "provider": "openidconnect",
    "authorizationURL": "https://XXXXXXXXXX.oktapreview.com/oauth2/v1/authorize",
    "tokenURL": "https://XXXXXXXXXX.oktapreview.com/oauth2/v1/token",
    "clientID": "XXXXXXXXXXXXXXXXXXXXXXX",
    "clientSecret": "XXXXXXXXXXXXXXXXXXXXXXX",
    "openidconnect": {
      "userinfoURL": "https://XXXXXXXXXX.oktapreview.com/oauth2/v1/userinfo",
      "scope": "openid profile email groups",
      "groupClaim": "groups"
    }
}

 Access control: SSO with SAML2 / ADFS

Linkurious supports SAML2 compatible providers as external authentication providers.

Configuration

To set up Linkurious authentication with a SAML2 provider, you need to obtain the following parameters from the provider:

groupAttribute is the attribute of the SAML response containing the array of groups a user belongs to.

Example access.saml2 configuration with a SAML2 provider:

"access": {
  // [...] 
  "saml2": {
    "enabled": true,
    "url": "https://example.com/adfs/ls",
    "identityProviderCertificate": "/Users/example/linkurious/saml.cert",
    "groupAttribute": "Groups"
  },
}

ADFS Configuration

In particular, ADFS (Active Directory Federation Services) is a SAML 2 provider that offers Single-Sign-On towards an Active Directory service.

To set up Linkurious authentication with ADFS, Linkurious has to be configured as a Relying Party Trust in ADFS.

 Alerts

Alerts are a way to watch your graph database for specific pattens and be notified when such a pattern appears in the data. A simple classification interface lets users navigate through pattern matches and flag them as confirmed or dismissed.

How alerts work

To create an alert, an administrator needs to:

After that, users will have access to all matches to this alert in the Alerts panel of Linkurious: alert list

Opening an alerts lists all recent matches sorted by score: alert matches

Clinking on a match opens it in graph view for details: match details

 Alerts: Configuration

The default values for Match TTL, Maximum match and Maximum runtime can be set in the configuration file (linkurious/data/config/production.json) under the alert key:

alert: {
  maxMatchTTL: 30,
  maxMatchesLimit: 5000,
  maxRuntimeLimit: 600000,
  maxConcurrency: 1
}

The maxConcurrency key indicates how many alert queries can be run concurrently. This is useful when you configure multiple alerts and want to prevent them from running at the same time to limit load on the graph database server.

 Alerts: Managing alerts

Alerts are currently only supported on Neo4j databases.

Creating a new alert

To create an Alert, open the Admin > Alerts menu and click add: create an alert

Alert settings are:

When done, click Save and enable to run the query right away.

Disabling an alert

If you want to prevent an alert from running and hide it from users, you can disabled it from the administrator user interface (Disable button on each alert).

Keep in mind that deleting an alert will delete all it existing matches.

 Visualizations appearance: Default styles

You can configure Linkurious to customize the default visual aspect of nodes and edges in new visualizations, so that your users will jump head first into the exploration of data.

Nodes and edges are grey and have the same size by default. The defined styles will be applied to all data-sources.

Open the configuration file (linkurious/data/config/production.json). Visualization styles are defined within the sigma key by the defaultStyles and color palette. Styles are mapping between visual variables such as colors or size, and data properties on nodes and edges.

Visual variables can be used in a single style at a time. For instance we can set nodes.color and nodes.icons, but we cannot set nodes.color twice. We can set nodes.color and edges.color.

Palettes may contain color schemes for both quantitative and qualitative properties, as well as schemes for icons. Schemes for qualitative properties bind property values to colors. Schemes for quantitative properties bind the number of property values to lists of sequential colors. Schemes may be nested and be referenced in dot notation by the styles.

Available defaultStyles.nodes.by values:

Available defaultStyles.edges.by values:

Color mapping

In the following example, nodes are colored by categories "COMPANY", "CITY", "MARKET", "INVESTOR", and edge are colored by type "HAS_CITY", "HAS_MARKED", "INVESTED_IN". Notice how each color palettes is referenced in schemes.

Example for qualitative properties:

"defaultStyles": {
  "nodes": {
    "color": {
      "by": "data.categories",
      "scheme": "nodes.qualitative.MyColorPalette1"
    }
  },
  "edges": {
    "color": {
      "by": "data.type",
      "scheme": "edges.qualitative.MyColorPalette2"
    }
  }
},
"palette": {
  "nodes": {
    "qualitative": {
      "MyColorPalette1": {
        "INVESTOR": "#5FDAA2",
        "COMPANY": "#DE6FBC",
        "MARKET": "#4EA4D4",
        "CITY": "#D4742C"
      }
    }
  },
  "edges": {
    "qualitative": {
      "MyColorPalette2": {
        "INVESTED_IN": "#5FDAA2",
        "HAS_CITY": "#DE6FBC",
        "HAS_MARKET": "#4EA4D4"
      }
    }
  }
}

Coloring by quantitative property follows the same logic. In the following example the nodes are colored by a numeric property. Values will be linearly grouped into 7 bins, ordered from small to large values (see an example below).

color-scale

Example for quantitative properties:

"defaultStyles": {
  "nodes": {
    "color": {
      "by": "data.properties.my_score",
      "scheme": "nodes.quantitative"
    }
  }
},
"palette": {
  "nodes": {
    "quantitative": {
      "7": ["#161344","#3f1c4c","#632654","#86315b","#a93c63","#cd476a","#f35371"]
    }
  }
}

Color palette

Linkurious will always use 7 colors for quantitative properties of the nodes, and 3 colors only for edges. The human eye can distinguish a few colors only, so you should craft your palette carefully.

If you do not set styles for qualitative properties, Linkurious will assign colors from a randomly -but carefully- generated set of colors. This set can be modified at palette.nodes.qualitative.linkurious_def (edges respectively).

Be careful to never delete linkurious_def or sequential because they are used by Linkurious.

We recommend to pick colors from the ColorBrewer palette, which provides highly distinctive sets of colors (see below).

color-brewer

You can also generate consistent color scales for qualitative data on http://gka.github.io/palettes/.

Node icons

Linkurious provides more than 500 icons from the FontAwesome project. You can assign icons using their unicode characters such has "\uf219". Get the complete character map at http://fortawesome.github.io/Font-Awesome/icons/ (select an icon to display the unicode).

The following example set icons to node categories "COMPANY", "CITY", "MARKET", "INVESTOR".

Example;

"defaultStyles": {
  "nodes": {
    "icon": {
      "by": "data.categories",
      "scheme": "nodes.icons.MyIconPalette"
    }
  }
},
"palette": {
  "nodes": {
    "icons": {
      "MyIconPalette": {
        "INVESTOR": {"font": "FontAwesome", "scale": 1, "color": "#fff", "content": "\uf19c"},
        "CITY": {"font": "FontAwesome", "scale": 1, "color": "#fff", "content": "\uf015"},
        "COMPANY": {"font": "FontAwesome", "scale": 1, "color": "#fff", "content": "\uf135"},
        "MARKET": {"font": "FontAwesome", "scale": 1, "color": "#fff", "content": "\uf219"}
      }
    }
  }
}

Node images

This feature is experimental and not yet available from the user interface.

Nodes can be filled with an image if one of their property is an URL to an image. Available image formats are PNG, JPG, GIF, or TIFF. The following example set images to node categories "COMPANY", "CITY", "MARKET".

Example:

"defaultStyles": {
  "nodes": {
    "image": {
      "by": "data.categories",
      "scheme": "nodes.images.MyImagePalette"
    }
  }
},
"palette": {
  "nodes": {
    "images": {
      "MyImagePalette": {
        "COMPANY": {
          "url": "http://example.com/img/company.png", "scale": 1.3, "clip": 0.85
        },
        "CITY": {
          "url": "http://example.com/img/city.png", "scale": 1.3, "clip": 0.85
        },
        "MARKET": {
          "url": "http://example.com/img/market.png", "scale": 1.3, "clip": 0.85
        }
      }
    }
  }
}

Note that you can host your custom images in Linkurious itself by storing them in the folder located at linkurious/data/server/customFiles/. For example you can create a folder at customFiles/my-icons/ and store your images there (e.g. company.png and city.png). Then, your palette configuration would be:

"palette": {
  "nodes": {
    "images": {
      "MyImagePalette": {
        "COMPANY": {"url": "/my-icons/company.png", "scale": 1.3, "clip": 0.85},
        "CITY": {"url": "/my-icons/city.png", "scale": 1.3, "clip": 0.85}
      }
    }
  }
}

Applying the styles configuration to existing users

Editing the styles and palettes in the configuration file does not automatically changes the styles for existing users.

Technically, the styles and palette configuration is only used when a user opens a new visualization for a given data-source for the first time. Existing visualizations are never affected by style and palette changes in the configuration.

If you want to apply the style and palette configuration to all new visualizations created by all users for a given data-source, you need to:

  1. Connect to Linkurious as an administrator
  2. Select the data-source you want to apply the default styles to
  3. Open the Admin > Data menu and scroll to the bottom of the page
  4. Click the "Reset default visualization styles" button.

reset styles

 Visualizations appearance: Default captions

In Linkurious, node and edge captions are the texts display next to a node or an edge.

Captions can be configured individually by each user using the design menu, but default values they can be configured for all users by an administrator.

To set default captions, you need to edit the defaultCaptions key in configuration file (linkurious/data/config/production.json). Inside defaultCaptions, the defaultCaptions.nodes and defaultCaptions.edges sections define the default captions for nodes and edges respectively.

Each of these two sections is an object where the keys must be node categories or edge types and values are objects with the following keys:

Example:

"defaultCaptions": {
  "nodes": {
    "CITY": {
      "active": true,
      "displayName": true,
      "properties": ["name"]
    },
    "COMPANY": {
      "active": true,
      "displayName": false,
      "properties": ["name", "country"]
    }
  },
  "edges": {
    "INVESTED_IN": {
      "active": true,
      "displayName": true,
      "properties": ["funded_month"]
    }
  }
}

Applying the previous example definition:

Applying default captions

Editing the default captions in the configuration file does not automatically change captions for existing users.

Technically, the default captions configuration is only used when a user opens a new visualization for a given data-source for the first time. Existing visualizations are never affected by default captions changes in the configuration.

If you want to apply the default captions configuration to all new visualizations created by all users for a given data-source, you need to:

  1. Connect to Linkurious as an administrator
  2. Select the data-source you want to apply the default styles to
  3. Open the Admin > Data menu and scroll to the bottom of the page
  4. Click the "Reset default captions styles" button.

reset default captions

 Visualizations appearance: Geographic tiles

Linkurious supports displaying nodes with geographic coordinates (latitude and longitude) on a map.

Users are able to switch a visualization to geo mode when geographic coordinates are available on at least one nodes of the visualization. The map tiles layer used in geo mode can be customized by users.

By default, Linkurious comes pre-configured with several geographical tile layers. Administrators change the available geographical tile layers by editing the leaflet section in the configuration file (linkurious/data/config/production.json). The leaflet key is an array of geographical tile layer configurations. Each entry has the following attributes:

Geographical tile layers and overlay layers can be found at https://leaflet-extras.github.io/leaflet-providers/preview/.

Example configuration:

"leaflet": [
  {
    "overlay": true,
    "name": "Stamen Toner Lines",
    "thumbnail": "",
    "urlTemplate": "http://stamen-tiles-{s}.a.ssl.fastly.net/toner-lines/{z}/{x}/{y}.png",
    "attribution": "Map tiles by <a href="http://stamen.com">Stamen Design</a>, <a href="http://creativecommons.org/licenses/by/3.0">CC BY 3.0</a> &mdash; Map data &copy; <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a>", 
    "subdomains": "abcd",
    "id": null,
    "accessToken": null,
    "minZoom": 2,
    "maxZoom": 20
  },
  {
    "name": "MapBox Streets",
    "thumbnail": "/assets/img/MapBox_Streets.png",
    "urlTemplate": "https://api.tiles.mapbox.com/v4/{id}/{z}/{x}/{y}.png?access_token={accessToken}",
    "attribution": "Map data &copy; <a href="http://openstreetmap.org">OpenStreetMap</a>, <a href="http://creativecommons.org/licenses/by-sa/2.0/">CC-BY-SA</a>, Imagery &copy <a href="http://mapbox.com">Mapbox</a>", 
    "subdomains": null,
    "id": "mapbox.streets",
    "accessToken": "pk.eyJ1Ijoic2hleW1hbm4iLCJhIjoiY2lqNGZmanhpMDAxaHc4bTNhZGFrcHZleiJ9.VliJNQs7QBK5e5ZmYl9RTw",
    "minZoom": 2,
    "maxZoom": 20
  }
]

 Audit trail

Audit trails allows you to record detailed logs about the operations performed on your graph database by Linkurious users. This feature is disabled by default.

The following settings are available in the configuration file (linkurious/data/config/production.json) within the auditTrail key:

 Audit trail: Log format

The audit trail log files contain JSON lines in JSONL format.

You can easily bind a log management system like Logstash to interpret them.

Each log line contains:

Log content example:

{"mode":"WRITE","date":"2017-01-09T17:34:07.446Z","user":"simpleUser@example.com","sourceKey":"e8890b53","action":"createEdge","params":{"createInfo":{"source":4328,"target":4332,"type":"ACTED_IN","data":{"tata":"toto"}}},"result":{"edge":{"id":5958,"data":{"tata":"toto"},"type":"ACTED_IN","source":4328,"target":4332}}}
{"mode":"READ","date":"2017-01-09T17:34:07.478Z","user":"simpleUser@example.com","sourceKey":"e8890b53","action":"getNode","params":{"id":4330},"result":{"node":{"id":4330,"data":{"tagline":"Welcome to the Real World","title":"The Matrix","released":1999,"nodeNoIndexProp":"foo"},"categories":["Movie","TheMatrix"]}}}
{"mode":"READ","date":"2017-01-09T17:34:07.507Z","user":"simpleUser@example.com","sourceKey":"e8890b53","action":"getEdge","params":{"edgeId":5950},"result":{"edge":{"id":5950,"data":{"edgeNoIndexProp":"bar","roles":["Neo"]},"type":"ACTED_IN","source":4313,"target":4330}}}
{"mode":"READ WRITE","date":"2017-01-09T17:34:12.253Z","user":"user@linkurio.us","sourceKey":"e8890b53","action":"rawQuery","params":{"query":"MATCH (n:Person) RETURN n","dialect":"cypher"},"result":{"nodes":[{"id":4357,"data":{"born":1967,"name":"Andy Wachowski"},"categories":["Person"],"edges":[]},{"id":4359,"data":{"born":1967,"name":"Carrie-Anne Moss"},"categories":["Person"],"edges":[]},{"id":4360,"data":{"born":1954,"name":"James Cameron"},"categories":["Person"],"edges":[]},{"id":4361,"data":{"born":1964,"name":"Keanu Reeves"},"categories":["Person"],"edges":[]},{"id":4362,"data":{"born":1965,"name":"Lana Wachowski"},"categories":["Person"],"edges":[]},{"id":4364,"data":{"born":1901,"name":"Phillip Cameron"},"categories":["Person"],"edges":[]},{"id":4365,"data":{"born":1976,"name":"Sam Worthington"},"categories":["Person"],"edges":[]}]}}
{"mode":"READ WRITE","date":"2017-01-09T17:34:12.289Z","user":"user@linkurio.us","sourceKey":"e8890b53","action":"rawQuery","params":{"query":"MATCH (n1)-[r:DIRECTED]->(n2) RETURN n1, r","dialect":"cypher"},"result":{"nodes":[{"id":4357,"data":{"born":1967,"name":"Andy Wachowski"},"categories":["Person"],"edges":[{"id":6009,"data":{},"type":"DIRECTED","source":4357,"target":4366},{"id":6010,"data":{},"type":"DIRECTED","source":4357,"target":4367},{"id":6011,"data":{},"type":"DIRECTED","source":4357,"target":4368}]},{"id":4358,"data":{"tagline":"Return to Pandora","title":"Avatar","released":1999},"categories":["Avatar","Movie"],"edges":[{"id":6034,"data":{},"type":"DIRECTED","source":4360,"target":4358}]},{"id":4360,"data":{"born":1954,"name":"James Cameron"},"categories":["Person"],"edges":[{"id":6034,"data":{},"type":"DIRECTED","source":4360,"target":4358}]},{"id":4362,"data":{"born":1965,"name":"Lana Wachowski"},"categories":["Person"],"edges":[{"id":6020,"data":{},"type":"DIRECTED","source":4362,"target":4366},{"id":6021,"data":{},"type":"DIRECTED","source":4362,"target":4367},{"id":6022,"data":{},"type":"DIRECTED","source":4362,"target":4368}]},{"id":4366,"data":{"tagline":"Welcome to the Real World","title":"The Matrix","released":1999,"nodeNoIndexProp":"foo"},"categories":["Movie","TheMatrix"],"edges":[{"id":6020,"data":{},"type":"DIRECTED","source":4362,"target":4366},{"id":6009,"data":{},"type":"DIRECTED","source":4357,"target":4366}]},{"id":4367,"data":{"tagline":"Free your mind","title":"The Matrix Reloaded","released":2003},"categories":["Movie","TheMatrixReloaded"],"edges":[{"id":6021,"data":{},"type":"DIRECTED","source":4362,"target":4367},{"id":6010,"data":{},"type":"DIRECTED","source":4357,"target":4367}]},{"id":4368,"data":{"tagline":"Everything that has a beginning has an end","title":"The Matrix Revolutions","released":2003},"categories":["Movie","TheMatrixRevolutions"],"edges":[{"id":6022,"data":{},"type":"DIRECTED","source":4362,"target":4368},{"id":6011,"data":{},"type":"DIRECTED","source":4357,"target":4368}]}]}}

Details of a log entry:

{
  "mode": "WRITE",
  "date": "2017-01-09T17:34:07.446Z",
  "user": "simpleUser@example.com",
  "sourceKey": "e8890b53",
  "action": "createEdge",
  "params": {"createInfo":{"source":4328,"target":4332,"type":"ACTED_IN","data":{"tata":"toto"}}},
  "result": {"edge":{"id":5958,"data":{"foo":"bar"},"type":"BAZ","source":4328,"target":4332}}
}