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, Ogma, to allow rich interactions with the graph. It also provides a user interface to enable data administration and collaboration among end users.

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, JanusGraph, DataStax Enterprise Graph, AllegroGraph and Stardog). 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, Microsoft Active Directory, Microsoft Azure Active Directory, Google Suite, OpenID Connect, SAML2 / ADFS).

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

 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-v2.1.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 sure that 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 Java JRE 7+ is installed (see Java JDK requirements)

See how to start Linkurious on Windows.

Mac OS X systems

  1. Unzip Linkurious archive: > unzip linkurious-osx-v2.1.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 sure that Java JRE 7+ is installed (type java -version in a terminal), if needed, install Java

See how to start Linkurious on Mac OS X.

Install 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.

Open the administration menu by running menu.sh, menu.bat or menu.sh.command in the linkurious folder. Click on Install Linkurious as a system service.

 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 click Start Linkurious.

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 click Start Linkurious.

The firewall of Windows might ask you to authorize connections with Linkurious. If so, click on Authorize access.

Content of the linkurious-windows directory:

Linkurious starting up on Windows:

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 click Start Linkurious.

 Getting started: Stopping Linkurious

Linux systems

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

Alternately, run menu.sh and click Stop Linkurious.

Windows systems

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

Alternately, run menu.bat and click Stop Linkurious.

Mac OS X systems

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

Alternately, run menu.sh.command and click Stop Linkurious.

 Getting started: Configure Linkurious

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

Using an administrator account, access the Admin > Configuration menu to edit the Linkurious configuration:

Some configuration keys requires a restart to be applied. Linkurious will notify you about it and offer you to restart from the Web UI only if you made the changes from the Web UI itself. If you modified the production.json file manually, changes won't get applied and you will need to restart Linkurious.

Configuration keys are divided per category. Edit what you need to change and click Save.

Password field will always be hidden from the Web UI, but they can be edited.

 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 to open it on each operating system below):

Linux systems

Run menu.sh. Alternately, run menu.sh status.

Windows systems

Run menu.bat. Alternately, run menu.bat status.

Mac OS X systems

Run menu.sh.command. 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": "2.1.4",
  "name": "Brilliant Burrito",
  "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.

If the issue is technical, send us a report via e-mail.

To download the bug report use the Web user interface via the Admin > Data menu:

At the end of the page, click Download Report:

 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. JanusGraph
  3. AllegroGraph
  4. DataStax Enterprise Graph
  5. Stardog

If you 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: JanusGraph

Please refer to the JanusGraph online documentation for details on how to load data into JanusGraph.

 Importing graph data: AllegroGraph

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

 Importing graph data: DataStax Enterprise Graph

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

 Importing graph data: Stardog

Please refer to the Stardog online documentation for details on how to load data into Stardog.

 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

Using an administrator account, access the Your Username > About menu to open the Linkurious info:

Click Check for updates to see if you are using the latest version.

Public version API

Alternatively, you can check at http://linkurio.us/version/linkurious-enterprise.json

// example response 
{
  "tag_name": "v2.1.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 newer 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-v2.1.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.

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

You can configure your data-sources via the Web user interface or directly on the linkurious/data/config/production.json file.

Using the Web user interface

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

Edit the data-source configuration to connect to your graph database:

Submit the changes by hitting the Save configuration button.

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 since version 2.0.0.

Configuration

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 configuration:

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

Supported graphdb options with Neo4j:

Search with Neo4j

In order to have full-text search, you can choose among the following options:

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 by uncommenting the following line:

dbms.security.auth_enabled=false

 Configuring data-sources: JanusGraph

JanusGraph is supported since version 0.1.1.

Configuration

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

Example configuration:

{
  "dataSources": [
    {
      "graphdb": {
        "vendor": "janusGraph",
        "url": "ws://127.0.0.1:8182/",
        "configuration": {
          "storage.backend": "cassandra",
          "storage.hostname": "127.0.0.1"
        }
      },
      "index": {
        "vendor": "janusGraphSearch"
      }
    }
  ]
}

Supported graphdb options for JanusGraph:

Note that exactly one option among configuration and configurationPath has to be defined.

Search with JanusGraph

In order to have full-text search, you can choose among the following options:

 Configuring data-sources: AllegroGraph

AllegroGraph is supported since version 6.0.0.

Configuration

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 configuration:

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

Supported graphdb options for AllegroGraph:

Search with AllegroGraph

In order to have full-text search, you can choose among the following options:

 Configuring data-sources: DataStax Enterprise Graph

DataStax Enterprise Graph is supported since version 5.1.3.

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')

If you are going to use any search index other than the one provided directly from DataStax Enterprise Graph, it is 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

To edit the DataStax Enterprise 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 configuration:

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

Supported graphdb options for DataStax Enterprise Graph:

Search with DataStax Enterprise Graph

In order to have full-text search, you can choose among the following options:

 Configuring data-sources: Stardog

Stardog is supported since versions 5.0.0.

Configuration

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

Example configuration:

{
  "dataSources": [
    {
      "graphdb": {
        "vendor": "stardog",
        "url": "http://127.0.0.1:10035/",
        "repository": "myGraph"
      },
      "index": {
        "vendor": "stardogSearch"
      }
    }
  ]
}

Supported graphdb options for Stardog:

Search with Stardog

In order to have full-text search, it's required to configure a search index in Stardog.

 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

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 to identify all user-data (visualizations etc.) that belongs to a data-source.

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

Before re-generating the graph database, go to the Admin > Sources 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 (linkurious/data/config/production.json) and set the key manualSourceKey for your data-source:

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

 Configuring data-sources: Advanced settings

The following advanced data-source settings applies to all data-sources.

To change them, see how to configure Linkurious.

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. This 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 and 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 than 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

You can configure your search engines via the Web user interface or directly on the linkurious/data/config/production.json file.

Using the Web user interface

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

Edit the search engine configuration to connect to your graph database:

Submit the changes by hitting the Save configuration button.

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-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()
    com.graphaware.runtime.stats.disabled=true
    com.graphaware.server.stats.disabled=true
  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.

You can either use the Web user-interface or edit the configuration file located at linkurious/data/config/production.json to set the index.vendor property to the value neo2es.

 Search index: JanusGraph

The janusGraphSearch connector is the recommended solution for full-text search for graphs with more than 100,000 nodes and edges.

JanusGraph search integration

Linkurious can use the builtin search indices managed by JanusGraph itself. You can either use the Web user-interface or edit the configuration file located at linkurious/data/config/production.json to set the index.vendor property to the value janusGraphSearch.

See the JanusGraph documentation to learn more.

If you already have a search index in JanusGraph, the following step is not required.

Create a search index in JanusGraph

Please refer to the JanusGraph documentation on how to create mixed indices.

First, ensure that the property keys to index are of the String data type:

> name = mgmt.makePropertyKey('name').dataType(String.class).make()

Follow these steps to use JanusGraph Search and integrate it with Linkurious:

  1. Connect via gremlin to JanusGraph
  2. Execute this command:
mgmt.buildIndex('searchIndexName', Vertex.class)
.addKey(property1, Mapping.TEXTSTRING.asParameter())
.addKey(property2, Mapping.TEXTSTRING.asParameter())
.addKey(property3, Mapping.TEXTSTRING.asParameter())
.buildMixedIndex("search")
mgmt.commit()

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 index only what you actually need to.

 Search index: AllegroGraph

The allegroGraphSearch connector is the recommended solution for full-text search for graphs with more than 1,000,000 triples.

AllegroGraph search integration

Linkurious can use the builtin search indices managed by AllegroGraph itself. You can either use the Web user-interface or edit the configuration file located at linkurious/data/config/production.json to set the index.vendor property to the value allegroGraphSearch.

See the AllegroGraph documentation to learn more.

If you already have a search index in AllegroGraph, the following step is not required.

Create a search 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.

 Search index: DataStax Enterprise Graph

The dseSearch connector is the recommended solution for full-text search for graphs with more than 100,000 nodes and edges.

DataStax Enterprise Graph Search integration

Linkurious can use the builtin search indices managed by DataStax Enterprise Graph itself. You can either use the Web user-interface or edit the configuration file located at linkurious/data/config/production.json to set the index.vendor property to the value dseSearch.

See the DataStax Enterprise Graph documentation to learn more.

If you already have a search index in DataStax Enterprise Graph, the following step is not required.

Create a search index in DataStax Enterprise Graph

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 the DataStax Enterprise Graph 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 you want to index 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 index only what you actually need to.

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.

 Search index: Stardog

The stardogSearch connector is the only solution for full-text search in Stardog.

Stardog search integration

Linkurious can use the builtin search indices managed by Stardog itself. You can either use the Web user-interface or edit the configuration file located at linkurious/data/config/production.json to set the index.vendor property to the value stardogSearch.

See the Stardog documentation to learn more.

If you already have a search index in Stardog, the following step is not required.

Create a search index in Stardog

Under the configuration page of the repository, ensure that search.enabled is ON.

 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.

 Search index: Configuring Elasticsearch

Elasticsearch is supported from 1.4.0 (using the elasticSearch connector) and from version 2.0.0 (using the elasticSearch2 connector).

Elasticsearch 5 is not yet supported in Linkurious 2.1.4.

Embedded Elasticsearch

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

To use the Linkurious embedded Elasticsearch instance, 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. Click get started

  3. Name your cluster (1) and select the Elasticsearch version 2.x (2), click Next

  4. Select the instance type, the number of instances and the 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. Configure Elasticsearch as explained here

 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 in 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 a link to a 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 ogma.settings.render 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 using secure communication channels between these machines (e.g. HTTPS or WSS). Please refer to the data-source documentation and search index documentation to learn how to enable HTTPS.

To use custom Certificate Authorities (CA), please check how to use additional Certificate Authorities in Linkurious.

 Access control

Configuring access control

The access control 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.

If you enable an SSO capable authentication service (OAuth/OpenID Connect or SAML2), your users won't need to login directly in Linkurious but, instead, by clicking the SSO button they will be redirected to the identity provider for authentication.

 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.

To enable authentication use the Web user interface via the Admin > Users menu:

The following screen will be prompted if authentication is disabled. Click Enable Authentication.

Create an admin account and click Save and enable.

 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 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.

Access-right example

Creating users

Only when authentication is enabled, use the Web user interface via the Admin > Users menu:

From this page, you can see all the users in Linkurious (both local and external users) and their groups in the current data-source:

To create a new user, click Create User.

Assigning users to groups

Click edit button next to a user. The following screen will appear:

Any user can belong to at most 1 built-in group, no limitations occurs for custom groups. Click + to add a new group to the user.

Any user can't edit its own groups.

Built-in groups

Linkurious defines several built-in groups. To learn more about them, click the inspect button next to a built-in group.

To create a new group, click Create Group.

Create a custom group

Define a name for the custom group. You can hover on the options to learn more about them.

On the next page, you can select the access-right for any given node-category:

Password hashing

Passwords of local users are hashed with the PBKDF2 algorithm and the following parameters:

External users

When using an external source for authentication, users are automatically created in Linkurious when they connect for the first time.

These shadow-users allow to store Linkurious specific data such as user preferences, groups and visualizations.

Passwords of external users are never stored inside Linkurious.

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": 1 // any Active Directory admin is a Linkurious admin 
  }
  // ... 
}

For some identity providers the external group IDs is an actual 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

If Linkurious is connected to an LDAP service, users will be 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.

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

OpenLDAP

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

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"]
  }
}

Active Directory

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

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 identity provider.

 Access control: SSO with Azure AD

Linkurious supports Microsoft Azure Active Directory as an external authentication provider.

Configuration

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/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, it can be configured as an OpenID Connect provider.

Configuration

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
  3. Add an oauth2 section inside the access section in linkurious/data/config/production.json

To limit the access to the Google accounts from your Google Suite domain, use the hd query parameter in 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 any 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 any SAML2 compatible provider 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 any 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 SAML2 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 patterns and be notified when such pattern appears in the data. A simple triage interface let the users navigate through pattern matches and flag them as confirmed or dismissed.

Alerts are a supported only for Neo4j in Linkurious 2.1.4.

If you are interested in alerts from other graph vendors, please get in touch.

How alerts work

To create an alert, an administrator needs to:

Using the Run query button, you can preview results for the current query:

Additional columns can be configured using explicitly returned values, as done here with n.length.

Clicking Next, a secondary configuration page will ask for the name of the alert and the frequency at which the query will be run.

After configuring and enabling an alert, it can be accessed by users in the Alerts panel:

Opening an alerts lists all recent matches, sortable by any column:

Clicking on a match opens it for details:

 Alerts: Configuration

The maximum number of matches and the maximum execution time can be set in linkurious/data/config/production.json under the alerts key:

alerts: {
  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.

 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 defaultStyles and color palette key. 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).

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).

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.

 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.

 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}}
}