Mobi Logo

Mobi is an open and collaborative knowledge graph platform for teams and communities to publish and discover data, data models, and analytics that are instantly consumable.

Introduction

Mobi is a free and open platform which links native data sources into a knowledge graph, creating an environment for teams and communities to accelerate discovery and deployment of advanced data systems. Mobi is built with Apache Karaf and utilizes OWL 2 for authoring ontologies, the SPARQL query language for data lookup, and a pluggable backend system for processing and handling graph data modeled using the Resource Description Framework (RDF). The Mobi platform applies the best practices recommended by the World Wide Web Consortium (W3C) to support organic growth of knowledge in a variety of domains.

Quick Start Guide

Installing from the Distribution

Prerequisites

Mobi requires a Java SE 17 environment to run. Refer to http://www.oracle.com/technetwork/java/javase/ for details on how to download and install Java SE 1.17.

Make sure your JAVA_HOME environment variable correctly points to your Java 17 installation directory. For example on a Mac, this would resemble /Library/Java/JavaVirtualMachines/openjdk-17.jdk. On Windows, this would resemble C:\Program Files\Java\openjdk-17.jdk

Installation

Download the appropriate binary distribution for your system using our download site.

The Mobi distribution comes packaged as a .zip file for Windows and a tar.gz file for Linux/OSX. Extract this file to a new directory on your system. For example, in C:\Mobi - from now on this directory will be referenced as MOBI_HOME.

Open a command line console and change the directory to MOBI_HOME.

To start the Mobi server, run the following command in Windows:

> cd %MOBI_HOME%
> bin\start.bat

or for Linux/OSX:

$ cd $MOBI_HOME
$ ./bin/start

All Mobi prepackaged bundles, services, and required artifacts and dependencies will be automatically deployed by the runtime once started.

Tip
You can check the status of the running server using the bin/status script or access the Mobi shell using the bin/client script (that’s bin\status.bat and bin\client.bat for you Windows users). If you are having problems starting Mobi, check the log files in $MOBI_HOME\data\log.

The Mobi web application should now be accessible at https://localhost:8443/mobi/index.html. The default login credentials are admin:admin.

Installing the Docker Image

The easiest way to get started with Mobi on Docker is to download and install https://docs.docker.com/get-docker/. If you are using Mac or Windows Operating System, Docker Desktop will be available for use which provides a Dashboard GUI to manage docker images. If you are using a Linux operating system, you will interact with Docker via terminal commands.

Mobi is available as a preconfigured Docker image on Docker Hub: https://hub.docker.com/r/inovexis/mobi/. You can find the Mobi image by searching for our organization "inovexis" in the DockerHub search bar.

DockerHub Mobi Page
Figure 1. DockerHub Mobi Page

On this page you will see the docker pull command. Open up a terminal and execute the command to pull the Mobi Docker image.

~ % docker pull inovexis/mobi
Using default tag: latest
latest: Pulling from inovexis/mobi
6d827a3ef358: Pull complete
2726297beaf1: Pull complete
7d27bd3d7fec: Pull complete
e61641c845ed: Pull complete
cce4cca5b76b: Pull complete
6826227500b0: Pull complete
c03b117ffd91: Pull complete
821a1547b435: Pull complete
2bd47f6b1b42: Pull complete
e4cf3e9f705c: Pull complete
3733107c5c01: Pull complete
4a9bdb07bcd2: Pull complete
cb3da7c9fe66: Pull complete
Digest: sha256:f387dd12cc2235150a2dd03b2741f01baf872f771ea8fb7e61ebf8bd4acb2155
Status: Downloaded newer image for inovexis/mobi:latest
docker.io/inovexis/mobi:latest

To verify that the image was pulled correctly, you can run the command below to view all pulled images.

docker images -a
REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
inovexis/mobi       latest              6a5c8e447ec0        3 months ago        795MB

You can then run Mobi using the standard docker run command. We recommend running Mobi on port 8443 rather than the random default value.

% docker run -dp 8443:8443 inovexis/mobi
fb324e907ad8254e587e88e1014291850050ed8d6493463a8dabdd8ac9367430

Once you’ve created a container with the Mobi Docker image, you can go to Docker Dashboard to see image running.

Docker Dashboard
Figure 2. Docker Dashboard

You can also look in the terminal for the Mobi container running.

% docker container list
CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                    NAMES
9abedac96a93        inovexis/mobi       "/usr/local/bin/mvn-…"   4 seconds ago       Up 2 seconds        0.0.0.0:8443->8443/tcp   flamboyant_panini

The Mobi image should now be running with the web application accessible at https://localhost:8443/mobi/index.html. The default login credentials are admin:admin.

You can use the CLI tool to login in karaf. Once you click on the CLI button, it will open up a terminal window where you can login into karaf.

DockerHub Mobi Page
Figure 3. Docker Dashboard CLI
user@machine ~ % docker exec -it fb324e907ad8254e587e88e1014291850050ed8d6493463a8dabdd8ac9367430 /bin/sh; exit
# ls -al # command to list directories
total 24
drwxr-xr-x 1 root root 4096 Jul 23 21:52 .
drwxr-xr-x 1 root root 4096 Jul 23 21:52 ..
drwxr-xr-x 1 root root 4096 Oct 29 15:43 mobi-distribution-1.17.78
# ./mobi-distribution-x.xx.xx/bin/client # command to login into karaf
Logging in as karaf




                       @@@@@
                      @#####@
                      @#####@
                     @@@@@@&
    &@%           @@@@@@@                       _     _
  @/,,,&@@@@@@@@@&   @@         _ __ ___   ___ | |__ (_)
  @,,,,,@@@@@@.     &@         | '_ ` _ \ / _ \| '_ \| |
  @,,,,/@      @@&  @@         | | | | | | (_) | |_) | |
    @*@           @@@@         |_| |_| |_|\___/|_.__/|_|
                   &@@
                    @@@
                    @&//@@
                   @//////@
                   @%////@@
                    @@@@@

  mobi (x.xx.xx).
  Powered by Apache Karaf

Hit '<tab>' for a list of available commands
and '[cmd] --help' for help on a specific command.
Hit '<ctrl-d>' or 'osgi:shutdown' to shutdown mobi.


karaf@mobi()>

To start or stop the container, you could either use the terminal or Docker Dashboard GUI.

docker container start {container id for mobi}
docker container stop {container id for mobi}

User Guide

The Mobi web application currently has seven main modules:

The web application also has a My Account page to configure various settings and preferences of the logged in user and a Administration page for admin users to configure user accounts and groups. The Configuration for the Mobi software itself is set in configuration files. The Mobi Shell also provides several commands for accessing the application data. The home page of Mobi includes some quick action buttons for performing common tasks and a display of the latest key activities performed by users throughout the application. Each activity displays a summary about the action performed, who did it, and when it happened. The list is sorted with the latest activities first and is paginated so you can view earlier actions.

The home page of Mobi
Figure 4. The Home Page

Mobi Enterprise also has a Vocabulary Linking module for discovering relationships between vocabularies for enhanced semantic integration.

Catalog

The Mobi web-based Catalog allows users to publish data, dataset descriptions, analytics and other resources. It allows users to control the way their data is shared.

Note
Federation of catalogs in Mobi is coming soon!

To reach the Catalog click on the link in the left menu.

full catalog initial view
Figure 5. The Catalog

The Local Catalog of Mobi contains all Records contained within your Mobi node. This includes all versioned ontologies created in the Ontology Editor, versioned mappings created in the Mapping Tool, versioned shapes graphs created in the Shapes Editor, and all datasets created in the Datasets Manager.

There are two main views of the Catalog:

Catalog Landing Page

catalog landing page
Figure 6. The Catalog Landing Page

The landing page of the Catalog displays a paginated list of all the Records in the Local Catalog that can be searched, sorted, and filtered. The filters on the left contain all possible types of Records and all possible user keywords. The search bar allows you to perform a text search through all the Record metadata.

Each Record in the list is displayed as a card with the Record title, type with related icon, date last modified, description, and keywords. Clicking on the title of the Record will copy its unique identifier (IRI). The footer of each Record card shows the username of its creator and a button to open that Record in its respective module (ontologies in the Ontology Editor, etc.). Clicking on the Record card will open it in the Record View.

Record View

record view
Figure 7. The Record View

The Record View displays all metadata for the selected Record along with set of tabs that updates based on the type of Record. The top of the Record view shows the Record title, type icon, and its description. The Record description is meant to provide a short summary of the Record. The right side of the view displays the created and modified dates of the Record along with its keywords and a button to open the Record in its associated module (ontologies in the Ontology Editor, etc.).

Every Record type will contain an Overview tab where you can view a Markdown description of the Record that provides more detailed information than the description field. If the Record is a Versioned RDF Record, such as an Ontology Record or Mapping Record, the tabset will also include a tab displaying the list of its Branches. The Branches in the list are expandable to view the description and commit history of the Branch.

If you have the permission to manage the Record, clicking on the title, description, overview, and keywords fields will turn them into editable fields for easy updates. In addition, you will see a Manage button which will navigate you to the Record Permissions page.

Record Permissions

The Record Permissions page enables you to specify which users and groups can perform various actions against a record, such as viewing, deleting, modifying, and managing. Modify refers to the ability to affect the data represented by the record while Manage refers to the ability to edit the Record metadata. Versioned RDF Records like Ontologies and Mappings will also provide the ability to restrict who can modify the MASTER branch. Each type of Record has its own default permissions that get set uploaded or created.

Permissions can be set to allow all authenticated users (the Everyone slider) or limit access to specific users and groups. To set the permission to a user or group, unselect the Everyone permission, find a user or group in the search box underneath the appropriate box, and select it. To remove a user or group from the permission, click the X button next to the username or group title. After you have finished making the changes you want, make sure to click the save button in the bottom right. You can also click on the back button if you want to go back to the Record View.

record view permission
Figure 8. Editing an Record Permission

For Versioned RDF records, If a user is not allowed to modify the branch they are currently viewing, all actions in the editor that would affect the branch are disabled or removed. In addition, if a user is not allowed to edit the target branch of a merge request, they will not be able to accept the request.

Ontology Editor

The Mobi web-based ontology editor provides a Distributed Ontology Management System (DOMS) for local and community development of Web Ontology Language (OWL) ontologies. The DOMS features a customizable user interface, knowledge capture, collaboration, access policy management, ontology reuse, and extensibility.

Note
The community distribution of ontologies in Mobi is coming soon!

To reach the ontology editor, click on the link in the left menu.

The Ontology Editor
Figure 9. The Ontology Editor

The initial view of the Ontology Editor shows the Ontologies page. The center of the page contains a paginated list of all ontologies in the local Mobi repository. Each ontology in the list displays ontology metadata and an action menu. The action menu allows you to delete the ontology. Deleting an ontology from this location will delete the ontology and associated ontology record and change history from the local catalog. Clicking an ontology will open it in the editor.

When opening an ontology, the editor will load the previous branch and commit you were viewing. If you have not previously opened the ontology or the branch you were viewing no longer exists, then the editor will load the HEAD commit of the ontology’s master branch. For an explanation of commits and branches see the section on Ontology Versioning.

From this screen you can also filter the ontology list, create new ontologies, or upload existing ones.

Creating New Ontologies

To create a new ontology, select the New Ontology button on the main ontology editor view. In the creation dialog, you are required to provide an ontology IRI and title. You can also optionally provide a description and keywords. This metadata is used to describe the ontology in the local catalog.

new ontology form
Figure 10. New Ontology Form

The Ontology IRI is the unique identifier for the new ontology. The editor pre-populates this field with a default namespace and a local name generated from the Title field. You can always override this behavior. The Title field populates the dcterms:title annotations of both the new ontology record and the ontology object within the new ontology. The Description field populates the dcterms:description annotations of both the new ontology record and the ontology object within the new ontology. The Keywords field will attach the entered values as keywords to the new ontology record.

Uploading Existing Ontologies

To upload an existing ontology, you can either click the Upload Ontology button and use the browser’s native file browser or drag and drop files onto the main ontologies view.

When uploading a file or files, a dialog box will prompt you for metadata entry for the ontology record (title, description, keywords). This metadata is used to describe the ontology in the local catalog. By default, the application will set the record title using the filename. Metadata for each ontology can be entered and submitted separately, or default metadata can be entered for all records using the Submit All button.

upload metadata form
Figure 11. Ontology upload metadata form.

Once all metadata has been submitted, a panel will be shown in the bottom right of the page which shows the status for each upload. Any errors will be detailed for each file. To refresh the main ontologies list with the new files, close the upload panel.

upload ontology results
Figure 12. Ontology upload results.

Supported ontology file types are .owl, .ttl, .xml, .jsonld, .owx, .json, .n3, .nq, .nt, .rdf, .txt, .json, .ofn, .omn , .owx, and .rdfs. The Title field populates the dcterms:title annotation of the new ontology record. The Description field populates the dcterms:description annotation of the new ontology record. The Keywords field will attach the entered values as keywords to the new ontology record. The file extension is used to guess the appropriate RDF Format to parse the file contents. If a parsing error occurs, the snackbar will display the error message relevant to guessed RDF Format.

Editing an Ontology

The Ontology Editor provides an interface for developing OWL 2 ontologies with additional features directed towards developing Simple Knowledge Organization System (SKOS) vocabularies and extensions thereof, including support for (SKOS-XL)

Tip
To learn more about OWL ontologies, see the W3C Specification. To learn more about SKOS vocabularies, see the W3C Specification

The Ontology Editor contains various tabs supporting activities for ontology development, search, and version control.

full editor ontology view
Figure 13. Ontology Editor

This section will describe the tools related to ontology development activities. These include:

The Schemes Tab and Concepts Tab will appear if the editor detects that the opened ontology contains SKOS classes and properties. The easiest way to have access to these tabs is to import the SKOS ontology (http://www.w3.org/2004/02/skos/core).

For a detailed description of the versioning components, refer to the Ontology Versioning section.

Ontology Project Tab

The Ontology Project Tab displays high-level information about the ontology. This includes the ontology annotations and properties, ontology imports, and a preview of the serialized ontology RDF.

ontology editor tab project
Figure 14. Ontology Editor Project Tab

The top of this tab contains the title of the ontology and its IRI. The IRI shown is the Version IRI, Ontology IRI, or a blank node identifier. The IRI can be copied quickly by clicking on it.

On the upper left side of this tab is a section containing a list of all the applied OWL Ontology Properties and Annotations. There are controls included to add, remove, and edit these properties.

On the lower left side of this tab is a section containing a list of all direct and indirect ontology imports. If an imported ontology could not be resolved, it will appear red. To add a new imported ontology, click on the plus button and either enter the IRI of an ontology available on the web or select an ontology within Mobi. To refresh the cached versions of the imported ontologies and attempt to resolve any unresolved imports, click on the refresh button.

On the right of this tab is a card used to generate a preview of the ontology as RDF. There is a drop down with several different RDF serializations to choose from. Clicking Refresh will generate a preview of the saved state of the ontology in the specified RDF format in the area below. The preview will be limited to the first 5000 results. Additionally, there is a button for downloading the ontology in the selected format.

Tip
The serialized ontology is a representation of data stored in the repository and will not include unsaved changes.
Overview Tab

The Overview Tab provides quick access to classes and their associated properties as compared to the Classes and Properties tabs. Properties are associated to classes through the use of rdfs:domain.

ontology editor tab overview
Figure 15. Ontology Editor Overview Tab

The left side of this tab contains the list of all classes and their associated properties, including imports. Any properties that have no rdfs:domain are grouped into a folder in the hierarchy called "Properties". You can expand a class to view its properties by clicking the "+" icon or double-clicking the class name. Properties are displayed with a symbol representing the data type of the range property. If an entity has been changed and those changes have not been committed, it will appear bold and an indicator will be shown on the right of the entity name. Imported classes and properties will appear grey and italicized. The list also includes a search bar that will filter the list to classes/properties with annotations or local names containing your search query and the ability to apply one or more filters. The Hide unused imports filter will remove all imported entities from the list that are not used by any of the entities defined in the ontology. The Hide deprecated entities filter will remove all entities annotated with the owl:deprecated property. Clicking on an item in the tree will load that entity’s information into the other sections in this tab.

The title of the selected class or property, its IRI, and its type(s) are displayed at the top of the tab along with buttons to delete the entity and view its change history (see Entity History). The IRI can be copied quickly by clicking on it. The middle sections in this tab allow you to add, remove, and edit Annotations and Axioms for the selected class or property. Imported classes and properties cannot be edited.

If you selected a property, a section with checkboxes for adding different characteristics to the selected property is shown in the top right of the Overview Tab.

Tip
See the W3C Specification for the definitions of property characteristics.

The last section on the right displays all the locations where the selected entity is used within the saved state of the ontology. For classes, this is anywhere the selected class is used as the object of a statement. For properties, this is anywhere the selected property is used as the predicate or object of a statement. Usages are grouped by the predicate of the statement and can be collapsed by clicking on the predicate title. Links in the usages section, as with links in various other components of the editor, can be clicked to navigate to that entity. If the number of usages exceeds 100, a button to load the next 100 is shown at the bottom of the section.

Classes Tab

The Classes Tab allows you to view, create, and delete classes in the opened ontology.

ontology editor tab classes
Figure 16. Ontology Editor Classes Tab

The left side of the tab contains a hierarchical view of the classes, including imports, nested according to their rdfs:subClassOf property. That is, a class’s children are classes which are defined as subclasses of the particular class. Since classes can be defined as a subclass of multiple classes, they may appear several times within the hierarchy. If a class has been changed and those changes have not been committed, it will appear bold and an indicator will be shown on the right of the class name. Imported classes will appear grey and italicized. The list also includes a search bar that will filter the list to classes with annotations or local names containing your search query and the ability to apply one or more filters. The Hide unused imports filter will remove all imported classes from the list that are not used by any of the entities defined in the ontology. The Hide deprecated entities filter will remove all classes annotated with the owl:deprecated property. Clicking on an item in the hierarchy will load that class’s information into the other sections in this tab. Double clicking on a class with children will toggle the display of the children.

The title of the selected class, its IRI, and its type(s) are displayed at the top of the tab along with buttons to delete the class and view its change history (see Entity History). The IRI can be copied quickly by clicking on it. The middle sections in this tab allow you to add, remove, and edit Annotations and Axioms for the selected class. Imported classes cannot be edited.

The section on the right of the Classes Tab displays all the locations where the selected class is used within the saved state of the ontology. That is, anywhere the selected class is used as the object of a statement. Usages are grouped by the predicate of the statement and can be collapsed by clicking on the predicate title. Links in the usages section, as with links in various other components of the editor, can be clicked to navigate to that entity. If the number of usages exceeds 100, a button to load the next 100 is shown at the bottom of the section.

Properties Tab

The Properties Tab allows you to view, create, and delete properties in the opened ontology.

ontology editor tab properties
Figure 17. Ontology Editor Properties Tab

The left side of the tab contains a hierarchical view of the data, object, and annotation properties, including imports. The data, object, and annotation properties are grouped into three separate folders within the hierarchy that will open and close when clicked. Properties are nested according to their rdfs:subPropertyOf property. That is, a property’s children are properties which are defined as subproperties of the particular property. Properties are displayed with a symbol representing the data type of the range property. If a property has been changed and those changes have not been committed, it will appear bold and an indicator will be shown on the right of the property name. Imported properties will appear grey and italicized. The list also includes a search bar that will filter the list to properties with annotations or local names containing your search query and the ability to apply one or more filters. The Hide unused imports filter will remove all imported properties from the list that are not used by any of the entities defined in the ontology. The Hide deprecated entities filter will remove all properties annotated with the owl:deprecated property. Clicking on an item in the hierarchy will load that property’s information into the other sections in this tab. Double clicking on a property with children will toggle the display of the children.

The title of the selected property, its IRI, and its type(s) are displayed at the top of the tab along with buttons to delete the property and view its change history (see Entity History). The IRI can be copied quickly by clicking on it. The middle sections in this tab change depending on whether you have selected a data, object, or annotation property. If the selected property is a data or object property, the sections for adding, removing, and editing Annotations and Axioms are shown. If the selected property is an annotation property, only the Annotation sections is shown. Imported properties cannot be edited.

If the selected property is a data or object property, a block with checkboxes for adding different characteristics to the selected property is shown in the top right of the Properties Tab. Imported properties cannot be edited.

object property tab
Figure 18. Object Property View
Tip
See the W3C Specification for the definitions of property characteristics.

The last section on the right of the tab displays all the locations where the selected property is used within the saved state of the ontology. That is, anywhere the selected property is used as the predicate or object of a statement. Usages are grouped by the predicate of the statement and can be collapsed by clicking on the predicate title. Links in the usages section, as with links in various other components of the editor, can be clicked to navigate to that entity. If the number of usages exceeds 100, a button to load the next 100 is shown at the bottom of the section.

Individuals Tab

The Individuals Tab allows you to view, edit, create, and delete individuals in the opened ontology.

ontology editor tab individuals
Figure 19. Ontology Editor Individuals Tab

The left side of the tab contains a view of all individuals, including imports, nested under their classes based on the rdfs:subClassOf property. If an individual has been changed and those changes have not been committed, it will appear bold and an indicator will be shown on the right of the individual name. Imported individuals will appear grey and italicized. The list also includes a search bar that will filter the list to individuals with annotations or local names containing your search query and the ability to apply one or more filters. The Hide unused imports filter will remove all imported individuals from the list that are not used by any of the entities defined in the ontology. The Hide deprecated entities filter will remove all individual annotated with the owl:deprecated property. Clicking on an item in the list will load that individual’s information into the other sections in this tab.

The title of the selected individual, its IRI, and its type(s) are displayed at the top of the tab along with buttons to delete the individual and view its change history (see Entity History). The IRI can be copied quickly by clicking on it. The section to the center and right of the tab allow you to add, remove, and edit Data, Object, and Annotation Properties for the selected individual. The options for Data and Object Properties are populated from the ontology and its imports. The user entered values in both the annotation and datatype property overlays are validated against the type field of the overlay. Imported individuals cannot be edited.

The types of an individual are editable by clicking the pencil icon at the end of the types list. The overlay allows you to add and remove types from the ontology and its imports. The "Named Individual" type is required.

edit individual types
Figure 20. Edit Individual Types Overlay
Schemes Tab

The Schemes Tab will appear if the editor detects the opened ontology is a SKOS vocabulary. It displays information about all the concept schemes and their directly related concepts defined in the opened vocabulary.

ontology editor tab schemes
Figure 21. Ontology Editor Schemes Tab

The left side of the tab contains a hierarchical view of the concept schemes, including imports. The top level items are the concept schemes, or subclasses of skos:ConceptScheme, and their children are all concepts, or subclasses of skos:Concept, within that scheme. This could be defined through the skos:hasTopConcept, skos:topConceptOf, or skos:inScheme properties. If a concept scheme or concept has been changed and those changes have not been committed, it will appear bold and an indicator will be shown on the right of its name. Imported concept schemes and concepts will appear grey and italicized. The list also includes a search bar that will filter the list to concepts/schemes with annotations or local names containing your search query and the ability to apply one or more filters. The Hide unused imports filter will remove all imported schemes from the list that are not used by any of the entities defined in the ontology. The Hide deprecated entities filter will remove all schemes annotated with the owl:deprecated property. Clicking on an item in the hierarchy will load that concept scheme’s or concept’s information in the other sections in this tab. Double clicking on a concept scheme with children will toggle the display of the children.

The title of the selected concept scheme or concept, its IRI, and its type(s) are displayed at the top of the tab along with buttons to delete the entity and view its change history (see Entity History). The IRI can be copied quickly by clicking on it. The middle sections in this tab allow you to add, remove, and edit Annotations, Data Properties, and Object Properties for the selected concept scheme or concept. Imported concept schemes and concepts cannot be edited.

The third section on the right of the Schemes Tab displays all the locations where the selected concept scheme or concept is used within the saved state of the vocabulary. This is anywhere the selected concept scheme or concept is used as the object of a statement. Usages are grouped by the predicate of the statement and can be collapsed by clicking on the predicate title. Links in the usages section, as with links in various other components of the editor, can be clicked to navigate to that entity. If the number of usages exceeds 100, a button to load the next 100 is shown at the bottom of the section.

Concepts Tab

The Concepts Tab will appear if the editor detects the opened ontology is a SKOS vocabulary. The Concepts Tab displays information about all the concepts defined in the opened vocabulary.

ontology editor tab concepts
Figure 22. Ontology Editor Concepts Tab

The left side of the tab contains a hierarchical view of the concepts, including imports. The concept hierarchy is determined using all of the SKOS broader and narrower properties. If a concept scheme or concept has been changed and those changes have not been committed, it will appear bold and an indicator will be shown on the right of its name. Imported concepts will appear grey and italicized. The list also includes a search bar that will filter the list to concepts with annotations or local names containing your search query and the ability to apply one or more filters. The Hide unused imports filter will remove all imported concepts from the list that are not used by any of the entities defined in the ontology. The Hide deprecated entities filter will remove all concepts annotated with the owl:deprecated property. Clicking on an item in the hierarchy will load that concept’s information in the other sections in this tab. Double clicking on a concept with children will toggle the display of the children.

The title of the selected concept, its IRI, and its type(s) are displayed at the top of the tab along with buttons to delete the concept and view its change history (see Entity History). The IRI can be copied quickly by clicking on it. The middle blocks in this tab allow you to add, remove, and edit Annotations, Data Properties, and Object Properties for the selected concept. Imported concepts cannot be edited.

The third section on the right of the Concepts Tab displays all the locations where the selected concept is used within the saved state of the vocabulary. This is anywhere the selected concept is used as the object of a statement. Usages are grouped by the predicate of the statement and can be collapsed by clicking on the predicate title. Links in the usages section, as with links in various other components of the editor, can be clicked to navigate to that entity. If the number of usages exceeds 100, a button to load the next 100 is shown at the bottom of the section.

Search Tab

The Search Tab allows you to perform a keyword search through all the entities within the saved state of the opened ontology and its imports.

ontology editor tab search
Figure 23. Ontology Editor Search Tab

The left side of the tab contains a simple search bar and a list of search results. To perform a search, type a string into the search bar and press the ENTER key. The results are separated by type headers which are collapsible. Each result is displayed with its display name. Properties are displayed with a symbol representing the data type of the range property. Clicking on a result will load that entity’s information into the right section of this tab. The right section displays the entity’s display name, IRI, types, and properties. The parts of the property values that match the search text will be highlighted. The right section also includes a Go To button that will open the entity in the appropriate tab. Double clicking on an entity in the list will also open that entity in the appropriate tab.

Visualization Tab

The Visualization Tab depicts the ontology in a force-directed graph layout. Each node represents a class, with dotted lines symbolizing the relationship between parent class and subclass, and solid lines representing the object properties.

pizza graph
Figure 24. Pizza Ontology Graph

The ontology visualization feature enables users to easily understand data within an Ontology by allowing them to navigate across the classes and their relationships. The feature allows users to zoom, pan, select, drag, hover, and click nodes and links.

The number of classes displayed is limited to 500. Any in progress changes you have will not be rendered until they are committed. After initial graph calculation, the state of the graph will persist while users keep the Ontology open. The graph will only be re-rendered when there is a new commit.

warning commit inprogress
Figure 25. Uncommited changes state
warning over node limit
Figure 26. Over the limit state

The side panel of the Visualization tab displays a searchable list of all the classes in the import closure (i.e. direct and imported) grouped by parent ontology. The checkboxes next to each class indicate whether a class is currently shown in the visualization and can be toggled to customize the displayed graph. Selecting the checkbox next to a class will update the graph by adding a new node with the class name, subclass relationships with other displayed classes, and object properties with other displayed classes. Deselecting the checkbox next to a class will remove these three things. Selecting a class in the side panel will highlight the node in the graph if displayed. Selecting a node in the graph will also highlight in the side panel. The side panel also includes a "Filter" dropdown with three options to help find the classes of interest in the list.

  • “All” which is the default. When selected, the list of classes contains both classes declared in the opened ontology and imported classes

  • “Local” which will filter the list of classes to only those declared in the opened ontology when selected

  • “Imported” which will filter the list of classes to only those from imported ontologies

sidebard imported open
Figure 27. Side Panel: classes grouped by parent ontology

The side panel can be hidden or shown with a button.

sidepanel close button
Figure 28. Side Panel Close Button
sidepanel open button
Figure 29. Side Panel Open Button
Imported Ontologies

The rendered graph will include every ontology within the imports closure. The classes in the graph are rendered with different colors based on which ontology within the imports closure they belong to. If a change to an imported Ontology is made, the changes will not be rendered until a manual refresh is triggered which will reset the Ontology cache or until a new commit is made.

imported ontology
Figure 30. Imported Ontologies
update imports
Figure 31. Refresh import

Ontology Versioning

Each ontology in Mobi is versioned in a manner similar to the Git Version Control System, whereby all changes to an ontology are collected into a chain "commits" which form a commit history called a "branch". Thus, every version in the history of an ontology can be generated by selecting a commit and applying all the changes in the branch back to the initial commit.

Every ontology is initialized with a MASTER branch that contains the initial commit. Work can be done on this MASTER branch or can be split out into separate branches. Work done on these branches occur in isolation until they are merged back into the MASTER branch, joining any other changes committed in the meantime. When merging two branches, the ontology editor does its best to combine any changes made on both branches. If a conflict occurs, the editor allows the user to resolve them manually. More information on merging branches can be found in the section on Merging Branches.

Checking Out Branches/Tags/Commits

The check out select box located underneath the selected ontology in the left display, provides a list of all the available branches and tags on the ontology. To checkout a branch or tag, simply select the branch in the drop-down menu. Checking out a tag will open the ontology at the tagged commit in read-only mode. If you have checked out a commit from the Commits Tab, the commit will be in the dropdown list and show as selected. Note that the select box will be disabled if you have any uncommitted changes on the current branch. To edit a branch name or description, click on the edit icon next to the branch in the drop-down menu. You cannot edit the master branch of an ontology.

check out select

check out select commit

check out tag
Figure 32. Ontology checked out at a tag

To delete a branch or tag, click on the delete icon next to the branch/tag in the drop-down menu. If a branch is deleted, all commits on that branch that are not part of another branch will be removed, as well as the branch itself. If a tag is deleted, the commit is not removed. Note that these actions cannot be undone.

Viewing Saved Changes

Every edit made to an entity within an ontology is automatically saved and an indicator is shown in the top right if the most recent changes have been saved successfully. The Changes Tab displays all saved and uncommitted changes in the opened ontology. Saving changes without committing allows a user to edit an ontology through a number of browser sessions before making any commits to the commit history. These changes are unique to the user, and are available to other users once a commit is performed. They are grouped by individual entity and display the triples on the entity grouped by property. When a “Show Full” toggle is active, the changes display is updated to include all the other triples on that changed entity.

ontology editor tab changes
Figure 33. Ontology Editor Changes Tab

Within each collapsible block in the list are the added and deleted triples for a particular entity IRI. If there are no changes to the ontology, this page will be empty. To commit these changes, select the Commit Changes button in the Button Stack. To remove these changes, click Remove All Changes.

If new commits have been made to the branch by other users while you are editing or viewing an ontology, a warning symbol will be displayed in the section title and a message will be displayed in the section notifying you that there are new commits on the branch. If you have no saved changes, there will be a link to update the current ontology by pulling in the latest changes. If you have saved changes, there will be a message notifying you to either commit your changes or remove them. If you choose to commit your changes, you can still continue working and there will be a link to pull in the latest changes and re-sync with the branch.

pull latest changes
Figure 34. Pull in latest changes message
behind head
Figure 35. Behind the head with saved changes
Merging Branches

The Ontology Editor also supports merging the head commit of the branch you are currently viewing into the head commit of another branch. Two branches can only be merged if there are no conflicts between the head commits of each branch. To perform a merge, select the green Merge Branches button in the button stack.

The merge view displays the name of the current (source) branch, a select box for the branch (target) you want to merge into, and a checkbox for whether or not you want the source branch to be deleted after it is merged. The view also shows an aggregated view of all changes made in the source branch that will be merged into the target branch along with a list of all the commits that will be added to the target branch from the source branch.

merge view
Figure 36. Merge branches view

Clicking Submit will attempt to perform the merge. If there are no conflicts between the changes on both branches, a new commit will be created merging the two branches, and a success message will appear in the top right corner of the screen.

Conflicts arise when the application cannot determine how to automatically merge specific changes to entities between two branches. If conflicts exist between the two branches, the merge process will be halted and the screen will update to notify you of those conflicts and provide you a way to resolve them. Each conflict is listed by entity within the ontology and with a marker indicating whether or not it has been resolved. Click on a conflict in the list to start resolving them.

merge conflicts main
Figure 37. List of all merge conflicts

When resolving a conflict, the tool displays the changes to the entity from both branches. To resolve the conflict, select the version of the entity you wish to keep. You can either click the Back to List button to go back to the list of all the conflicts or the Previous or Next buttons to iterate through the list of conflicts.

Note
Currently the editor only supports accepting entire changes. We are working on improvements to give more flexibility in resolving conflicts during a merge operation.
merge conflicts resolution
Figure 38. Merge conflict resolution view.

Once all conflicts have been resolved, the Submit with Resolutions button will become active and you can complete the merge operation. Completing the merge will create a new commit that incorporates your conflict resolutions into the target branch, and displays a success message in the upper right corner of the screen.

Commits Tab

The Commits Tab provides a table and graph of all the commits made in the history of the branch you are currently viewing. The username of the creator, ID, message, and date for each commit are displayed within the table. The graph displays each commit connected to its parent commits continuing backwards until the initial commit. To view more information about a particular commit in the history, such as the added and deleted statements, click on its id or associated circle in the graph. The table also includes buttons for "checking out" a commit in the history. Clicking a View button will open the ontology at that commit in read-only mode. This is useful for creating tags to indicate versions on the ontology (see Button Stack and Checking Out Branches/Tags/Commits).

commit history table
Figure 39. Commit history table of a branch
Entity History

Clicking on a See History button next to a selected entity in one of the tabs will open a view containing the change history of that specific entity in the ontology. The view is split into two columns. The left side contains a dropdown containing all the commits where that entity was changed and defaults to the latest commit. Any added triples will be green and any deleted triples will be red. The right side contains a table of all the commits where that entity was changed. The table behaves the same as the table in the Commits Tab, just without the graph. To return to the main editor, click the back button in the top left.

entity history
Figure 40. Entity History view

Ontology Editor Reference

Edit IRI Overlay

The Edit IRI overlay provides the user with a simple way to edit and create valid IRIs. The Begins with field (required) is the beginning of the IRI. This is more commonly known as the namespace. When editing the IRI of entities within an ontology, this value is typically the ontology IRI. The Then field (required) is the next character in the IRI. This value can be thought of the separator between the namespace and local name (described below). The provided values for the Then field are "#", "/", and ":". The Ends with field (required) is the last part of the IRI. This value is commonly known as the local name. It is used in the drop down lists in this application as the easiest way to identify what the IRI references. Clicking the refresh button on the left will reset the three fields to their original values. You cannot create/save an edited IRI that already exists within the ontology. Clicking Cancel will close the overlay. Clicking Submit will save the IRI with the entered values for the selected entity and update the ontology.

edit iri overlay
Figure 41. Edit IRI overlay
Axiom Overlay

The Axiom Overlay is how you add new axioms to entities in your ontology. The Axiom dropdown provides a list of common axioms for the type of entity you have selected. Once selected, there are two ways to add a value. The first is choosing from a list of entities within the ontology and its imports. The second is writing out a class expression or restriction in Manchester Syntax in the Editor. Entities are referenced by their local name and must be present in the ontology or its imports.

axiom value editor
Figure 42. Axiom Overlay Editor with an example
Property Value Displays

Property Value Displays are a common way Mobi displays multiple values for a property on an entity. These properties could be data properties, object properties, annotations, axioms, etc. The display consists of the title section and the values section. The title section includes a bold title and the property IRI. The values section lists all the values set for the displayed property along with the type, if the value is a literal, and edit and delete buttons when you hover over the value. The functionality of the edit and delete buttons for values differ depending on where the Property Value Display is being used. If a value of a property is a class restriction or expression, it will be represented in a simplified format or Manchester Syntax if it is supported. These values can be deleted, but not edited.

Tip
See the W3C Specification for information about blank nodes, class/property restrictions, and class/property expressions.
property value display
Figure 43. A property value display with multiple values
Button Stack

The Button Stack is visible in any Ontology tab in the bottom right hand corner of the screen and holds a variety of buttons that are shown when the stack is hovered over.

button stack
Figure 44. Collapsed button stack

To add a new entity to the ontology, click on the main Create Entity button in the stack. This will open an overlay with options for what kind of entity to create and once you have selected an option, an appropriate overlay will be shown for creating that type of entity. After creating the entity, a snackbar will appear at the bottom allowing you to navigate directly to your new entity.

create entity button
Figure 45. Create Entity button
new snackbar
Figure 46. New Entity snackbar

If you have made changes to an ontology, the Commit Changes button will become active. Clicking on this button will bring up the Add Commit overlay.

commit changes button
Figure 47. Commit button

The Add Commit overlay provides a textarea for you to enter in a Comment that will be associated with that commit. This commit usually specifies what changes where made in the commit so that others can read the message and understand what happened at that point in time. You can still commit your changes if you are not currently viewing the head commit of the current branch. Clicking Cancel will close the overlay. Clicking Submit will add all your saved changes to a new commit object whose parent is the commit you were viewing and close the overlay.

add commit overlay
Figure 48. Add commit overlay

See the Merging Branches section for details on how the merging branches works.

merge branch button
Figure 49. Merge Branch button

The Create Branch button allows you to create a new branch from the commit and branch you are viewing, including past commits. This action can be performed even if you have unsaved or saved changes. Clicking on the button will bring up the Create New Branch overlay.

create branch button
Figure 50. Create Branch button

The Create New Branch overlay provides fields for entering information about the branch as a whole. The Title field (required) will set the dcterms:title of the branch. The Description field will set the dcterms:description of the branch. Clicking Cancel will close the overlay. Clicking Submit will create a new branch with the entered information whose head commit was the commit you were viewing and close the overlay.

create branch overlay
Figure 51. Create new branch overlay

The Create Tag button allows you to create a human readable and persistent pointer to the commit you are currently viewing. Clicking this button will bring up an overlay where you can type in the title for the Tag and customize it’s IRI. Once the Tag is created, the ontology will open the ontology in read-only mode at the tagged commit.

create tag button
Figure 52. Create Tag button

The Upload Changes button allows you to upload a new version of your ontology from a file and apply the changes. Clicking this button will bring up an overlay where you can select the file with the changed ontology. Uploaded changes will not be automatically committed, but will allow you to review changes before making a new Commit.

upload changes button
Figure 53. Upload Changes button
Extension Mappings

The table below describes which file extensions are mapped to which RDF Formats when an ontology file is uploaded to Mobi. In the event more than one RDF Format is possible for a single extension, all RDF Formats are attempted.

Table 1. Table Extension to RDF Formats
Extension RDF Format Name

.json

RDF/JSON, JSON-LD

.jsonld

JSON-LD

.ttl

Turtle

.xml

Rio OWL XML, RDF/XML

.ofn

Rio Functional Syntax

.omn

Rio Manchester Syntax

.owx

Rio OWL XML

.rdf

RDF/XML

.rdfs

RDF/XML

.owl

RDF/XML, Rio OWL XML

.trig

TriG

.nt

N-Triples

.nq

N-Quads

.obo

Open Biological and Biomedical Ontologies

Link (ENTERPRISE)

The Mobi Vocabulary Linking Tool is an Enterprise only feature that allows you to create semantic links between terms found in two different vocabularies. The tool uses the Levenshtein algorithm by default to determine the similarity of labels between terms

To reach the Vocabulary Linking tool, click on the link in the left menu.

The Vocabulary Linking Tool
Figure 54. The Vocabulary Linking Tool

The initial view of the Vocabulary Linking Tool shows a form on the left for selecting the vocabularies and a space for matched terms to be displayed. To select a vocabulary, you must select the Ontology Record and a Branch. All selected semantic relations you wish to add will be committed to the selected branches for both vocabularies.

To adjust the configuration for the linking algorithm, click on Advanced and a configuration modal will appear. The modal contains fields for the “Matching Sensitivity”, which controls the range of percentages that matching results must be within to be returned, and the “Matching Properties”, which controls which properties are analyzed for similarity by the linking tool.

The vocabulary linking configuration modal
Figure 55. The vocabulary linking configuration modal

After you have selected 2 different ontologies, click on Analyze and the right section of the view will update with the matched terms in a paginated list.

Example vocabulary linking results
Figure 56. Example vocabulary linking results

The top of the results section shows a checkbox for selecting or deselecting all the results in addition to two dropdowns. One is for filtering the results based on whether terms have already been semantically linked. The other is for sorting the results based on the highest matched percentage of all the labels of each matched term pair.

Each result in the display shows the display name for each term, which semantic relation will be committed, and the highest matched percentage between labels of both the terms. Each result is also expandable to show all the properties for each term in the pair along with a select for which semantic relation to use. If the terms in a matched pair are already semantically linked, they will be marked as such and the checkbox on the row will be disabled.

Example matched vocabulary terms
Figure 57. Example pair of matched vocabulary terms
Previously linked vocabulary matches
Figure 58. Matched vocabulary terms that are already linked

To mark which terms you wish to link, select which relation you wish to use from the select in the expanded section and check the box next to the pair. The options are “Exact Match”, “Close Match”, or “Related”. Use the following as a reference for what each type of relation means:

Exact Match

Used to link two concepts that can always be used interchangeably.

Close Match

Used to link two concepts that can sometimes be used interchangeably depending on the application. Not as strong of a link as “Exact Match”.

Related

Represents associative (non-hierarchical) links.

After you have selected the type of link you would like to make and checked the checkbox for the row, repeat this process for all the terms that you want linked. To commit the links, click on Commit in the top right corner of the page, above the “Sort” dropdown. You should then see a modal open with options for how to commit the selected linking to the ontologies. You have a choice of committing to one ontology or both. Once you have selected which ontology(s) to commit to, click on Submit.

One Way Linking

You should then get a message saying that the Linking Matches were successfully committed for each ontology.

Successful linking
Figure 59. A success message linking vocabularies

Shapes Editor (BETA)

The Mobi web-based shapes graph editor is an experimental feature that provides users with a Distributed Management System for local and community development of (SHACL Shapes). The Shapes Editor features a customizable user interface, constraint capture, collaboration, shapes graph reuse, and extensibility.

To reach the Shapes Editor, click on the link in the left menu.

Shapes Overview Page
Figure 60. Shapes Editor Overview page

The main Shapes Editor page includes a new action-bar where all the action buttons for a shapes graph record are located. From the action-bar, users can create, filter, and open different shapes graph records, branches, and tags.

action bar
Figure 61. Shapes Editor Action Bar

When opening a shapes graph record, the editor will load the previous branch and/or commit you were viewing. If you have not previously opened the record or in the case that the branch you were viewing no longer exists, the editor will load the HEAD commit of the shape graph’s master branch. For an explanation of commits and branches, see the section on Shapes Graph Versioning.

Once a shapes graph record has been opened, The overview page displays a list of high-level information surrounding the shapes graph. This includes a shapes graph’s annotations, properties, imports, and a preview of the shapes graph serialized as RDF in Turtle syntax. Mobi will capture this high level information about a shapes graph with an OWL ontology object, following best practices from the SHACL W3C specification (see this section as an example).

shapes details
Figure 62. Shapes Record Details

Creating New Shapes Graphs

To create a shapes graph, select the Create Shapes Graph button found in the dropdown for selecting a record. In the creation dialog, you are required to provide a title for the record and a file providing the initial shapes graph data (accepts all standard RDF formats). Users can also optionally provide a description and keywords which will be used to describe the shapes graph record in the local catalog.

create shapes
Figure 63. New Shapes Record Form

The Title field populates the dcterms:title annotations of the new shapes graph record and the Description field populates the dcterms:description annotations of the new shapes graph record. The keywords field will attach the entered values as keywords to the new record.

Editing a Shapes Graph

Note
In-app shapes graph editing features are coming soon. In this BETA version, updates can be uploaded using the Upload Changes feature

Shapes Graph Versioning

Each shapes graph in Mobi is versioned similarly to the Git Version Control System, whereby all changes to a shapes graph are collected into a chain of "commits" which form a commit history called a "branch". Thus, every version in the history of a shapes graph can be generated by selecting a commit and applying all the changes in the branch back to the initial commit.

Every shapes graph is also initialized with a MASTER branch that contains the initial commit. Changes to the shapes graph can be uploaded to the MASTER branch or can be uploaded into separate branches. Changes uploaded on these branches exists in isolation until they are merged into the MASTER branch, joining any other changes committed in the meantime. When merging two branches, the Shapes Editor does its best to combine any changes made on both branches. If a conflict occurs, the editor allows the user to resolve them manually. More information on merging branches can be found in the section on Merging Branches.

Branches & Tags

In order to create a branch or tag, click the corresponding button in the action bar.

create branch button

create tag button

Create Branch and Create Tag buttons

The branches dropdown provides a searchable list of branches and tags which can be checked out. To checkout a branch or tag, simply select the branch in the drop-down menu. Checking out a tag will open the ontology at the tagged commit in read-only mode. If you have checked out a commit from the commit history table, the commit will be in the dropdown list and show as selected. Note that the ability to check out a branch or tag will be disabled if you have any uncommitted changes on the current branch.

versioning dropdown
Figure 64. Branches Dropdown

To delete a branch or tag, click on the delete icon next to the branch/tag in the drop-down menu. If a branch is deleted, all commits on that branch that are not part of another branch will be removed, as well as the branch itself. If a tag is deleted, the commit is not removed. Note that these actions cannot be undone.

Viewing Saved Changes on Shapes Graphs

Changes that have been uploaded to a shapes graph record are automatically saved and an indicator is shown in the action-bar. Users are able to reach the changes page by clicking the Show Changes button found in the right-hand side of the action bar.

The changes page displays all saved and uncommitted changes in the opened shape graph. Saving changes without committing allows a user to edit an shape graph through a number of browser sessions before making any commits to the commit history. These changes are unique to the user, and are available to other users once a commit is performed. They are grouped by individual entity and display the triples on the entity grouped by property. When a “Show Full” toggle is active, the changes display is updated to include all the other triples on that changed entity.

changes page
Figure 65. Changes Page

The Changes Page displays all the uncommitted changes and the commit history table for the opened shapes graph record. This provides users the ability to upload changes without committing and allows a user the opportunity to review proposed changes to a shapes graph in a more digestible manner before adding any commits to the commit history. Clicking the Remove All Changes button will clear all the changes uploaded into the shape graph, resetting to the state of the current commit.

Users can also view a shapes graph record at a specific commit in time by clicking the View button next to the corresponding commit in the commit history table.

Merging Branches on Shapes Graphs

Merging branches works much the same as the Ontology Editor. By clicking the Merge Branch button found in the action-bar, users are brought to the merge view of the Shapes Editor.

merge branches button
Figure 66. Merge Branches button

The merge view displays the name of the current (source) branch, a select box for the branch (target) you want to merge into, and a checkbox for whether or not you want the source branch to be deleted after it is merged. The view also shows an aggregated view of all changes made in the source branch that will be merged into the target branch along with a list of all the commits that will be added to the target branch from the source branch.

merge page
Figure 67. Merge View

Clicking Submit will attempt to perform the merge. If there are no conflicts between the changes on both branches, a new commit will be created merging the two branches, and a success message will appear in the top right corner of the screen.

Uploading Changes to Shapes Graphs

The Upload Changes button in the action-bar allows you to upload a new version of your shapes graph from a file and apply the changes. Clicking this button will bring up an overlay where you can select the file with the changed shapes graph. Uploaded changes will not be automatically committed, but will allow you to review changes before making a new Commit.

upload changes button
Figure 68. Upload Changes button

Merge Requests

The Mobi Merge Requests module allows users to create long lived representations of a merge between two branches of a record to provide checks and balances before including changes into the object the record represents. Each merge request is connected to a particular Record in the local Catalog and specifies a "source" and "target" branch. The request represents what would occur if the "source" branch were merged into the "target" branch.

To reach the Merge Requests module, click on the link in the left menu.

full merge requests initial view
Figure 69. The Merge Requests module

The initial view of the Merge Requests module displays a list of all currently open merge requests within the application sorted by created date descending along with a button to create a merge request. To view all accepted merge requests, change the selected filter next to the search bar. Each merge request in the list displays a preview of the request metadata and a button to delete the request. Clicking on a merge request in the list opens a display of the individual merge request.

individual request
Figure 70. An Individual Merge Request

The individual merge request view displays all information regarding the merge request. The top displays more metadata about the request including the request’s description and whether the source branch will be removed once the request is accepted. Below the metadata are a series of tabs containing the discussion on the request, the changes between the source and target branch, and commits that will be added from the source to the target branch. The bottom of the view contains a button to delete the request, a button to accept the request if it not already accepted, and a button to go back to the main list of merge requests.

The discussion tab allows users to comment and discuss the changes within the request to facilitates more collaboration in a distributed environment. You can create new comments to start new threads of communication or you can reply to existing comments and further the discussion. Comments can only be removed by the creators of the comment.

Note
The comment editor supports GitHub flavored Markdown which you can find more information about here.

The Changes tab displays the full difference of the source branch from the target branch. They are grouped by individual entity and display the triples on the entity grouped by property. When a “Show Full” toggle is active, the changes display is updated to include all the other triples on that changed entity.

The metadata of a request can be edited by hovering over the area and clicking the pencil button. In the resulting overlay, you can change the Title, Description, target branch, Assignees, and whether the source branch should be removed on acceptance.

edit merge request
Figure 71. Editing Merge Request Metadata

Create a Merge Request

To create a merge request, click New Request on the initial view of the Merge Requests module. Creating a merge request is a three part process. The first step is to select which record in Mobi that request should be attached to by searching within the displayed paginated list of records. Once you have selected a record, click Next.

Important
If the record a request is attached to is deleted, that request is removed. If the source branch of a request is removed, that request will also be removed.
step1
Figure 72. Creating a Merge Request: Step 1 - Select a Record

The second step of creating a merge request is to pick the "source" and "target" branch from the attached record. The source branch will be the branch in the first select box and the target branch will be in the second select box. Once both are selected, you will see an aggregated view of all changes made in the source branch that will be merged into the target branch along with all the commits from the source branch that will be included in the target branch. Once you have selected the branches you want to merge, click Next.

step2
Figure 73. Creating a Merge Request: Step 2 - Select Branches

The third step of creating a merge request is to provide any metadata you want to include about the request. This includes the required Title, optional Description, any Assignees of the request, and whether the source branch should be removed when the request is accepted. Once you have provided the metadata you wish to include, click Submit and a new Merge Request with your selections will be created.

step3
Figure 74. Creating a Merge Request: Step 3 - Request Metadata

Accepting a Merge Request

A merge request can be accepted only if there are no conflicts between the source and target branch and the user accepting the request has permission to modify the target (see [Ontology Managing]). If there are conflicts between the source and target branches, a notification will be shown with the option to resolve the conflicts from within the Merge Requests module. Resolving conflicts behaves the same as in the Ontology Editor, except that the resolution will become a commit on the source branch.

conflicts
Figure 75. Conflicts on a Merge Request

If a merge request is accepted, the merge will be preformed from the source into the target and the request will be moved into an Accepted state. All accepted merge requests are saved within the application for provenance.

Mapping Tool

The Mobi web-based Mapping Tool allows users to define custom, ontology-driven definitions to control and execute input data transformations to the Resource Description Framework (RDF) semantic data model. User-defined mappings load semantic data into the Mobi store for analysis, sharing and linking.

To reach the Mapping Tool, click on the link in the left menu.

full mapping tool initial view
Figure 76. Mapping Tool button

To use the Mapping Tool to map data, an ontology must be in the Mobi repository, but it does not have to be opened to access it. If there are no available ontologies, you will not be able to map delimited data. To upload an ontology go to the [ontology_editor] and follow the steps for uploading ontologies or creating a new ontology.

The initial view of the Mapping Tool shows the Mapping Select Page which contains a searchable paginated list of the mappings within the local Mobi repository. Each mapping is displayed with a portion of its metadata along with a dropdown menu with buttons to preview, duplicating, editing, running, download, and delete the mapping. The Preview button will bring up a display of the classes and properties it maps along with the title of the source ontology. If the selected source ontology no longer exists in the local Mobi repository, you will not be able to edit, run, or duplicate the mapping. Click New Mapping to create.

Creating a Mapping

To create a new mapping, click Create Mapping on the Mapping Select Page. The creation overlay requires you to enter a Title which will populate the dcterms:title annotation of the new mapping record. The Description field populates the dcterms:description annotation of the new mapping record. The Keywords field will attach the entered values as keywords to the new mapping record.

create mapping overlay
Figure 77. Create Mapping Overlay

Clicking Submit brings you to the File Upload Page to continue the process of creating a mapping. You must upload a delimited file to use as a standard for the mapping. You can also check whether or not the file contains a header row and select the separator character if the file is CSV. The accepted file formats are .csv, .tsv, .xls, and .xlsx. Selecting a file in the form on the left loads a preview of the first 50 rows and columns of the delimited file into the table on the right. Clicking Continue brings you to the Edit Mapping Page.

file upload create
Figure 78. File Upload Page for Creating a Mapping

The Edit Mapping Page contains three tabs: Edit, Preview, and Commits. The Edit tab contains a section for displaying the currently selected source ontology, the list of class mappings, and a list of property mappings for a particular class. For every row in the delimited data, an instance of a mapped class will be made according to each class mapping. Each created class instance will have a set of properties as defined by the property mappings associated with each class mapping. The values of data properties will have assigned datatypes based on the range of the mapped data property unless otherwise specified. The Preview tab allows you to map the first 10 rows of the selected delimited file using the current state of the mapping in a variety of different RDF serializations. Just like ontologies, mappings are versioned with commits which can be viewed in the Commits tab.

Tip
To learn about the structure of a mapping, refer to the Mobi Mappings Appendix.
edit mapping edit
Figure 79. Edit Mapping Page Edit Tab

When creating a mapping, the first thing you will see is the Source Ontology Overlay. This setting can always be changed by clicking the pencil button next to the ontology name in the Edit tab. The Class section contains a select box with all the class mappings, a button to delete a specific class mapping, and a button to create a new class mapping. Clicking Add Class opens an overlay where you can select a class in the imports closure of the source ontology that has not been deprecated.

The IRI Template section displays the template Mobi will use when generating IRIs for the created class instances from the selected class mapping. The value within the ${} indicates what will be used for the local name of each class instance’s IRI. "UUID" means that a unique identifier will be generated for each class instance. An integer means that Mobi will grab the value from the column with that index (zero-based) for each row and use each value with all white space removed as the local name for the class instance. This template can be edited by clicking the pencil button next to the section title and filling in the fields in the IRI Template Overlay.

The Properties section lists all the property mappings for the selected class mapping with a button to add a new property mapping. Object property mappings are displayed with the name of the class mapping whose instances will be used as the range of the property. Data or Annotation property mappings are displayed with the name of the column whose values will be used as the range of the property, a preview of what the first value would be, the datatype for the mapped value, and the language for the values if specified. Each property mapping also provides a button to edit and delete. If a data property mapping is invalid, meaning it points to a column that does not exist in the delimited file, it must be handled before the mapping can be saved or run.

Clicking Add Property opens an overlay where you can select a property in the imports closure of the source ontology that has not been deprecated or a common annotation. The common annotations that can be mapped are rdfs:label, rdfs:comment, dcterms:title, and dcterms:description. If you select a data property or an annotation, a select box appears containing identifiers for each column in the delimited file along with a preview of the first value of the selected column. At this point, you can also specify a manual datatype override which the mapper will use over the range of the property if set. You can also specify the language for the property values by selecting rdfs:langString as the type and then a language select will appear underneath. If you select an object property, a select box appears containing the titles of all class mappings of the appropriate type along with an option to create a new class mapping.

create property mapping overlay data
Figure 80. Create Property Mapping Overlay for a Data/Annotation Property
create property mapping overlay object
Figure 81. Create Property Mapping Overlay for an Object Property
language selection
Figure 82. Language Selection for a Data/Annotation Property

Clicking the main Save button at the bottom of either the Edit or Preview tab saves the current state of the mapping and brings you back to the Mapping Select Page. Clicking on the arrow to the right of the Save button provides you options for running the mapping in addition to saving it. These options are downloading the mapped data, uploading the mapped data into a data within a Mobi repository, or committing the mapped data to a specific branch of an ontology. Each option will bring up an appropriate overlay for choosing a RDF format and file name, a dataset, or an ontology and branch respectively. Clicking Submit in an overlay will save the current state of the mapping and run it.

Tip
To learn about datasets in Mobi, refer to the Datasets Manager.
Note
For more information about running a mapping into an ontology, refer to Mapping into an Ontology.
save run options
Figure 83. Options for saving and running a mapping

Editing a Mapping

To edit a mapping, click Edit on the Mapping Select Page. The application performs a quick check to see if the source ontology or its imported ontologies changed in such a way that the mapping is no longer valid. If this check does not pass, an overlay is displayed informing you of the error. If it passes, you are brought to the File Upload Page where you must upload a delimited file to use as a standard for the mapping. If the delimited file you choose does not contain enough columns for the mapping’s data property mappings, a list of the missing columns are displayed under the file select. However, you can still edit the mapping as long as those data properties are fixed. From there, editing the mapping works the same as creating a mapping.

file upload edit
Figure 84. File Upload Page for Editing a Mapping
file upload edit missing columns
Figure 85. File Upload Page for Editing a Mapping with missing columns

Duplicating a Mapping

To duplicate a mapping, click Duplicate on the Mapping Select Page. The application performs a quick check to see if the source ontology or its imported ontologies changed in such a way that the mapping is no longer valid. If this check does not pass, an overlay is displayed informing you of the error. If it passes, the Create Mapping overlay will appear allowing you to choose new values for the Title, Description, and Keywords. The rest of the process is the same as editing a mapping including how missing columns are handled.

Running a Mapping

To run a mapping against delimited data without editing it, click Run on the Mapping Select Page. The application performs a quick check to see if the source ontology or its imported ontologies changed in such a way that the mapping is no longer valid. If this check does not pass, an overlay is displayed informing you of the error. If it passes, you are brought to the File Upload Page where you must upload a delimited file to be used when generating RDF data. You can also check whether or not the file contains a header row and select the separator character if the file is CSV. The accepted file formats are .csv, .tsv, .xls, and .xlsx. The classes and properties that will be created using the mapping are displayed under the file select. The columns that must be present in the delimited file are highlighted in the table on the right. Selecting a file in the form on the left loads a preview of the first 50 rows and columns of the delimited file into the table. If the delimited file you choose does not contain enough columns for the mapping’s data property mappings, the properties that are missing columns turn red and you will not be able to run the mapping.

Tip
To learn about datasets in Mobi, refer to the Datasets Manager.
file upload run
Figure 86. File Upload Page for Running a Mapping
file upload run missing columns
Figure 87. File Upload Page for Running a Mapping with missing columns

Clicking Run Mapping will provide you with options for downloading the mapped data, uploading the mapped data into a data within a Mobi repository, or committing the mapped data to a specific branch of an ontology. Each option will bring up an appropriate overlay for choosing a RDF format and file name, a dataset, or an ontology and branch respectively.

Note
For more information about running a mapping into an ontology, refer to Mapping into an Ontology.
run options
Figure 88. Options for saving and running a mapping

Mapping Tool Reference

Source Ontology Overlay

The Source Ontology Overlay allows you to select the source ontology for the mapping from all uploaded ontologies in the local Mobi repository.

source ontology overlay
Figure 89. Source Ontology Overlay

The left side of the overlay contains a searchable list of all the ontologies in the local Mobi repository and a select for the version of the ontology to use. For most ontologies, this will only contain the "Latest" value. However, if an ontology was previously selected for a mapping and that ontology has changed since then, there will be an option for the "Saved" version of the ontology. The right side of the overlay displays information about the ontology from its record in the Catalog and a sample of the classes in that ontology. Setting the source ontology will remove any class and property mappings in the mapping that are incompatible. Class mappings and property mappings are incompatible if the class or property that is referenced no longer exists in the imports closure of the source ontology. Property mappings are also incompatible if they are a different type or have a different range.

IRI Template Overlay

The IRI Template overlay provides you a way to edit each portion of the IRI template of a class mapping. The template will be used to generate the IRIs for each instance created by a class mapping.

iri template overlay

The Begins with field (required) is the beginning of the IRI. This is more commonly known as the namespace. The Then field (required) is the next character in the IRI. This value can be thought of the separator between the namespace and local name (described below). The provided values for the Then field are "#", "/", and ":". The Ends with dropdown field (required) is the last part of the IRI. This value is commonly known as the local name. The values in this dropdown are "UUID", which represents generating a unique identifier as the local name for each generated instance of each row, and the title of each column, which represents using the value of that column as the local name for each generated instance of each row. Clicking Cancel will close the overlay. Clicking Submit will save the IRI template.

Mapping into an Ontology

The overlay for mapping into an ontology contains several configurations on how the mapping result data will be committed. First, you must select the Ontology and Branch that will receive the new commit. After that, there are radio buttons that will determine how the mapping result data will be treated when the commit is made. The first option will treat all the mapping result data as new data, meaning no existing data in the ontology branch will be removed. The second option will treat all the mapping result data as changes to the existing data on the ontology branch. This means that if there are entities or properties on entities in the ontology that are not present in the mapping result data, they will be removed.

map into ontology

A sample workflow using this tool would be to create an ontology in the Ontology Editor and create a branch that will received all mapped data commits. Then run your mapping from the Mapping Tool, committing to the new branch as additions. Finally in the Ontology Editor, merge that branch with the mapped data commit into the MASTER branch. Then any subsequent runs of the mapping with updated data would be committed as changes to the mapped data branch and merged into the MASTER branch.

Datasets Manager

The Mobi Datasets Manager allows users to create, edit, clear, and delete datasets within the application to group and store Resource Description Framework (RDF) semantic data into various graphs for enhanced query isolation, data segmentation, and management.

Tip
To learn more about the structure of a dataset, refer to the Mobi Datasets Appendix.

To reach the Datasets Manager, click on the link in the left menu.

full datasets manager initial view
Figure 90. The Datasets Manager

The page displays a searchable paginated list of all the datasets within the local Mobi repository. Each dataset in the list displays a preview of the dataset metadata and a dropdown menu with upload data, edit, clear, and delete buttons. Deleting a dataset deletes the dataset, catalog record, and all associated data graphs. Clearing a dataset removes all associated data graphs except the system default named graph. Clearing a dataset does not remove the dataset or the catalog record. Editing a dataset allows to you to change some information about the dataset. The Upload Data button allows you to upload graph data to the dataset from a file.

To create a new dataset, click New Dataset and fill out the information in the creation overlay.

Create Dataset

new dataset overlay
Figure 91. New Dataset Overlay

The Create New Dataset overlay contains several sections. The Title field populates the dcterms:title annotation of the new dataset record. The Dataset IRI field allows you to specify what the IRI of the new dataset should be. If not provided, the system will create a unique one for you. The Description field populates the dcterms:description annotation of the new dataset record. The Keywords field will attach the entered values as keywords to the new dataset record. The Repository field allows you to specity the identifier of the repository registered within AVM where the dataset and all associated named graphs will be stored. The default option is the system repository and should be used in most cases. Finally, you can select which ontologies should be used as the basis for the data. Select an ontology from the searchable list of ontologies to add it to the dataset. To remove a selected ontology, click the x next to the ontology name. Clicking Cancel will close the overlay. Clicking Submit will create the dataset with the provided metadata.

Note
The ability to create new repositories in Mobi is coming soon!

Edit Dataset

edit dataset overlay
Figure 92. Edit Dataset Overlay

The Edit Dataset overlay allows you to modify information about the dataset. The Title field modifies the value of the dcterms:title annotation of the dataset record. The Description field modifies the value of the dcterms:description annotation of the dataset record. The Keywords field allows you to add/remove keywords attached to the dataset record. The ontologies area allows you to modify the ontologies associated with the dataset record; just as during creation. Clicking Update will update the dataset record with the new metadata.

Caution
Datasets are associated with specific versions (commits) of an ontology record. In order to update a dataset to the latest version of an ontology record, you’ll need to remove the ontology, click Submit, then add that ontology back to the dataset.

Discover

The Mobi web-based Discover module allows users to quickly search and explore their knowledge graphs. The Explore tab provides an intuitive interface for quickly navigating through ontology-defined entities. The Query tab allows users to develop and execute SPARQL queries.

Tip
To learn more about SPARQL queries, see the W3C Specification.
Note
The ability to save, publish, share and reuse SPARQL queries as part of applications or larger workflows is coming soon!

To reach the Discover page, click on the link in the left menu. The first tab shown is the Explore tab.

full discover page initial view
Figure 93. The Discover Page

Explore

The Explore tab of the Discover page allows you to get a high-level overview of the structure of your data within a dataset.

explore classes
Figure 94. Explore tab with classes

The Explore tab opens with a view of all the classes found within the selected dataset and a button to create a new instance. Each card displays the label and a brief description about a class, the number of instances defined as that class, a few of those instances, and a button to explore the instances themselves. Clicking Explore Data opens the instances view.

explore instances
Figure 95. Explore Tab with instances

The instances view contains a paginated list of all the instances defined as a particular class. Each card displays the label, brief description about an instance, a button to explore the instance itself, and a button to delete the instance. The label is determined based on the values of the rdfs:label, dc:title, or dcterms:title properties on the instance. The description is based on the values of the rdfs:comment, dc:description, or dcterms:description properties on the instance. You can navigate back to the classes view using the breadcrumb trail in the top left. Clicking View Class Name opens the single instance view. Clicking Create Class Name opens the single instance editor. If the particular class has been deprecated in the ontology, you will not be able to create a new instance.

explore single instance
Figure 96. Explore Tab with single instance

The single instance view displays the IRI, label, brief description, and list of all properties associated with the selected instance. Each property will only show one value by default; however, you can view more values, if there are any, by clicking the "Show More" link for that property. The instance view can also display any assertions on a reification of a property value statement by clicking on the small downward arrow on the right side of a property value. Clicking Edit opens the single instance editor.

explore single instance editor
Figure 97. Explore Tab with single instance editor

The single instance editor displays the IRI and a list of all properties associated with the selected instance in an editable format. The IRI can be edited by clicking the pencil button next to the IRI which will open the Edit IRI Overlay. If the instance being edited does not have all the required properties set, as described by cardinality restrictions in the ontology, the instance cannot be saved. To add a another property value, type in the provided input and press the ENTER key. To remove a property value, click on the "X" button of the associated chip. To view a complete property value and add assertions to its reification, click on the associated chip.

Caution
Editing the instance IRI might break relationships within the dataset.

To add a new property to the instance, click Add New Property and select the property in the overlay. After all edits have been made, clicking Cancel will discard the current changes and go back to the single instance view. Clicking Save will save the current changes to the repository and then go back to the single instance view.

Query

The Query tab of the Discover page allows you to submit SPARQL query against the Mobi repository and optionally a specific dataset.

discover query editor overview
Figure 98. Query tab

The Query tab provides a SPARQL query editor powered by the YASGUI SPARQL library. The top section of the page contains the query editor (powered by YASQE), a Dataset field and a Submit button. The Dataset field contains a list of all available datasets within the Mobi repository. Selecting a dataset limits the query to search through the data within the selected dataset. Clicking Submit executes the entered query against the Mobi repository, optionally limited by the selected dataset, and updates the bottom section with the results.

The bottom section displays the results of the most recently submitted SPARQL query (powered by YASR). The section has separate tabs for rendering the query result set depending on the type of SPARQL query submitted. SELECT query results are displayed under the Table tab where the headers of the table are the variables specified in the SPARQL query. The Table comes with features such as filtering, page size, sorting and pagination. CONSTRUCT query results can be displayed under the Turtle, JSON-LD and RDF/XML tabs. The query results are limited to 500 triples/rows for rendering, but the entire result set can be downloaded using the button in the upper right corner of the bottom section.

discover construct query
Figure 99. Construct query

My Account

The My Account page of Mobi provides users with a way to configure their own account and customize various aspects of the application to suit their needs.

To reach the My Account page, click on the display of your username in the left menu.

my account link
Figure 100. My Account link

The My Account page contains four main tabs for configuring your account:

Profile

The Profile tab contains a form for viewing and editing your basic profile information. This information includes your First Name, Last Name, and Email address. None of this information is required. Your current settings for these fields will be displayed to start. To edit, simply change the values in one or more of the fields and and click Save in the bottom right. If the change was successful, you will see a success message at the top of the section.

profile tab
Figure 101. Profile Tab

Groups

The Groups tab contains a list of all the groups you belong to. Next to each group title is an indicator of how many users are within that group. If a group has the admin role, an indicator will be next to the group’s title.

groups tab
Figure 102. Groups Tab

Password

The Password tab contains a form for updating your password. To change it, you must first input your Current Password in the first field. Then enter your desired New Password in the second field and click Save in the bottom right. If the change was successful, you will see a success message at the top of the tab.

password tab
Figure 103. Password Tab

Preferences

The Preferences tab will dynamically populate with user preference definitions added to the repository (see documentation here). These preferences are specific to your user.

preferences tab
Figure 104. Preferences Tab
Note
Default preferences coming soon!

Administration

The Administration page provides administrators with a portal to create, edit, and remove users and groups in Mobi. From this module, you can also assign high level access control for common actions within the application.

To reach the Administration page, click on Administration in the left menu. This option is not available to non-administrators.

administration link
Figure 105. Administration link

There are four main tabs of the Administration page:

Users

The Users tab allows you to create, edit, and remove users from the application.

users tab
Figure 106. Users Tab

The left side of the tab contains a list of all the users in Mobi. Each user is displayed using their first and last names, if available, or their username. If a user is an administrator, whether by having the admin role or by being a part of a group with the admin role, an indicator will be next to their username in the list. At the top of the list is a search bar that will filter the list of users based on their first name, last name, or username. Clicking on a user will load that user’s information into the right side of the section.

Note
The default Admin user can not be deleted.

The middle of the Users tab contains the username of the selected user, a block for viewing and editing the user’s profile information, and a block for resetting the user’s password. Resetting a user’s password cannot be undone.

The right side of the tab contains blocks for viewing and editing the selected user’s permissions and viewing the user’s groups. Clicking on the title of a group will open it in the Groups section.

To create a user, click Create User and the Create User overlay will appear. The Username field (required) must be unique within the application. The Password fields (required) allow you to enter in the password for the new user. The First Name, Last Name, and Email fields are not required, but allow you to enter in basic profile information for the new user. The last section contains a checkbox for setting whether the new user is an administrator. Clicking Cancel will close the overlay. Clicking Submit will create a new user with the entered information.

create user overlay
Figure 107. Create User Overlay

Groups

The Groups tab allows you to create, edit, and remove groups from the application. Groups allow you to associate users with one another and apply the same permissions and roles to all members.

groups tab
Figure 108. Groups Tab

The left side of the tab contains a list of all the groups in Mobi. Next to each group title is an indicator of how many users are within that group. At the top of the list is a search bar that will filter the list of groups based on their title. Clicking on a group title will load that group’s information into the right side of the section.

The right side of the tab contains the selected group’s title and two rows of blocks. The top row contains blocks that allow you to edit the group’s description and permissions. If a group has the "Admin" role, all members within that group are considered administrators.

The bottom row contains a block that allows you to view, add, and remove the group’s members. To add another user to the group, click Add Member and that line in the table will transform into a drop down selector of all the users in Mobi that have not already been selected. Selecting a user in this drop down will automatically add them to the group. To remove a user from the table, click on the corresponding delete button at the end of the row. Any changes in this table will immediately be applied. Clicking on a username in this table will open that user’s information in the Users section.

To create a group, click Create Group and the Create Group overlay will appear. The Group Title field (required) allows you to specify a name for the group. The Description field allows you to enter in a description about what the group represents. At the bottom of the overlay is a table for adding users to the group. Your user account will be added automatically. To add others to the group, click Add Member and that line in the table will transform into a drop down selector of all the users in Mobi that have not already been selected. To remove a user from the table, click on the corresponding delete button at the end of the row. Clicking Cancel will close the overlay. Clicking Submit will create a new group with the entered information and add the listed users to it.

create group overlay
Figure 109. Create group overlay

Permissions

The Permissions tab allows you to set high level access control for common actions in the application, such as creating Ontology Records and querying the system repository. Permissions can be set to allow all authenticated users (the Everyone slider) or limit access to specific users and groups. To set the permission to a user or group, unselect the Everyone permission, find a user or group in the search box underneath the appropriate box, and select it. To remove a user or group from the permission, click the X button next to the username or group title. After you have finished making the changes you want, make sure to click the save button in the bottom right.

Note
More permissions coming soon!
permissions tab
Figure 110. Permissions Tab

Application Settings

The Application Settings tab enables you to alter/maintain system-wide settings. Below are descriptions of the settings currently available in the application.

Note
More Application Settings coming soon!
Default Ontology Namespace

The namespace to be used when generating default IRIs for new ontologies/vocabularies in the Ontology Editor.

application settings tab

Configuration

All default configuration files for Apache Karaf and Mobi are located inside the {MOBI_HOME}/etc directory.

Mobi

Service Configuration

The basic Mobi services can be configured using the following files:

Table 2. Mobi Service Configuration Files
Configuration File Description

com.mobi.catalog.config.CatalogConfigProvider.cfg

Configurations for the Mobi Catalog

com.mobi.platform.config.state.StateManager.cfg

Configurations for the Mobi State Manager

com.mobi.service.repository.native-system.cfg

Configurations for the Mobi System Repository

com.mobi.service.repository.native-prov.cfg

Configurations for the Mobi Provenance Repository

By default, all resources besides provenance data are stored in the system repository which is an RDF triplestore located in the data/repos/system directory of the Mobi distribution. The provenance data is stored within the prov repository. Each repository in Mobi is uniquely identified by its id. To change the data location, id, or title of either repository, edit the dataDir, id, and title properties respectively in the appropriate file. Apache Karaf will dynamically reload any changes made to this existing file.

You can create new repositories to be used for storage in Mobi. First, choose either a "native" repository or a "memory" repository. These two types of repositories are defined in the NativeRepositoryConfig and MemoryRepositoryConfig classes in the com.mobi.repository.impl.sesame module. Once you have chosen the type of repository, make a new .cfg file in the {MOBI_HOME}/etc directory with a file name that starts with either "com.mobi.service.repository.native" or "com.mobi.service.repository.memory". In the file, set the id, title, and dataDir properties you wish for the repository. The file should look like this:

id=demo
title=Demonstration
dataDir=path/to/directory

Apache Karaf will automatically recognize the new configuration file and create the new repository.

The repository that all Catalog resources are stored with is controlled within the com.mobi.catalog.config.CatalogConfigProvider.cfg file. The storage repository for all other types of data are controlled individually in other configuration files. To change each of these repository configurations, open the associated .cfg file and change the id of the repository.target property to be the id of the new repository. For example to change the repository for storing Catalog resources to the repository in the example above, you would open the com.mobi.catalog.config.CatalogConfigProvider.cfg file and edit the repository target line to be:

repository.target = (id=demo)

Apache Karaf will automatically detect the changes and reload the new configuration.

Security Configuration

The configuration for user authentication, authorization, and management are stored in the following files in the {MOBI_HOME}/etc directory:

Table 3. Mobi Security Configuration Files
Configuration File Description

com.mobi.jaas.engines.RdfEngine.cfg

Configurations for the Mobi RDF Engine

com.mobi.security.policy.api.xacml.XACMLPolicyManager.cfg

Configurations for the XACML security policy manager

Mobi utilizes JAAS for user authentication and basic authorization. By default, user credentials and information are managed by the RdfEngine service which is configured with the com.mobi.jaas.engines.RdfEngine.cfg file. The file contains an id of the repository to be used for storage, the encryption settings for JAAS which are enabled to start, and the two default roles: "user" and "admin". Apache Karaf will automatically detect any changes and reload the updated configurations.

The default user for Mobi is "admin" with password "admin". To change the credentials of the "admin" user or perform any other user management activities, utilize the Administration page, the My Account page, or the appropriate REST endpoints.

For more advanced authorization functionality, Mobi uses the an Attribute Based Access Control (ABAC) system called XACML. Policies describing the attributes for allowing or denying individual access requests are managed by the XACMLPolicyManager service which is configured with the com.mobi.security.policy.api.xacml.XACMLPolicyManager.cfg file. The file contains an id of the repository to be used for storage, the location the XACML policy files should be stored in, and whether the policy file location should be created if it does not already exist. Apache Karaf will automatically detect any changes and reload the updated configurations.

In addition to the aforementioned files, Enterprise Mobi also supports LDAP and SSO integrations which are explained in Post-Installation Configuration.

Email Service Configuration

The configuration for the Mobi Email Service is stored in the following file in the {MOBI_HOME}/etc directory:

Table 4. Mobi Email Service Configuration Files
Configuration File Description

com.mobi.email.api.EmailService.cfg

Configurations for the Mobi Email Service

The Mobi Email Service is built on the Apache Commons Email API. The Email Service provides the ability to connect to a provided SMTP server and send an email using a configured email account. By default, the service is configured to connect to a Gmail SMTP server in the com.mobi.email.api.EmailService.cfg file. The service has configurations for smtpServer, port, emailAddress, emailPassword, security, and emailTemplate. Please see below for different configurations of popular email services.

Email Template

The Mobi Email Email Service supplies a default email template that works across most email clients. The default file is located in the {MOBI_HOME}/etc directory. If you want to provide your own email template, modify the emailTemplate configuration to the new email template with either a relative or absolute path to the file. The email service will resolve relative file paths for an email template using the {MOBI_HOME}/etc directory as the base directory.

The email service provides a method for doing a simple string replace on the !|$MESSAGE!|$ binding within the template. For more complex HTML inserts, the service provides a method to replace all HTML between the two !|$BODY!|$ bindings. Custom templates must have the aforementioned bindings (!|$MESSAGE!|$ & !|$BODY!|$). The !|$MESSAGE!|$ binding must be between two !|$BODY!|$ bindings. For example:

<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
...
<body>
!|$BODY!|$
<table>
    <tbody>
    <tr>
        <td>
            <p>
                <!-- A simple message to replace -->
                !|$MESSAGE!|$
            </p>
        </td>
    </tr>
    </tbody>
</table>
!|$BODY!|$
...
</body>
</html>
SMTP Configurations
Gmail

To send emails with Gmail, you must also follow the steps here to allow less secure apps to access the gmail account. Gmail also has strict sending limits that can impair functionality as your organization grows. Additionally, Gmail may flag a machine that it does not recognize and prevent access. If this occurs, log in to your gmail and grant the device access.

smtpServer = smtp.gmail.com
emailAddress = my.email@gmail.com
emailPassword = my-password
port = 587
security = STARTTLS
emailTemplate = emailTemplate.html
Outlook
smtpServer = smtp-mail.outlook.com
emailAddress = my.email@outlook.com
emailPassword = my-password
port = 587
security = STARTTLS
emailTemplate = emailTemplate.html
Office 365
smtpServer = smtp.office365.com
emailAddress = my.email@yourdomain.com
emailPassword = my-password
port = 587
security = STARTTLS
emailTemplate = emailTemplate.html
Yahoo
smtpServer = smtp.mail.yahoo.com
emailAddress = my.email@yahoo.com
emailPassword = my-password
port = 465
security = STARTTLS
emailTemplate = emailTemplate.html
Mailgun
smtpServer = smtp.mailgun.org
emailAddress = my.email@mg.gitlab.com
emailPassword = my-password
port = 587
security = STARTTLS
emailTemplate = emailTemplate.html

Apache Karaf

The Karaf instance that runs Mobi can be configured using the configuration files located in the {MOBI_HOME}/etc directory.

Table 5. Relevant Karaf Configuration Files
Configuration File Description

org.ops4j.pax.url.mvn.cfg

Configurations for Maven repositories used for bundle resolution and deployment

org.ops4j.pax.web.cfg

Configurations for HTTPS connections

The org.ops4j.pax.url.mvn.cfg file specifies how Apache Karaf will resolve Maven URLs. This file is set up so that Apache Karaf will use the basic Maven repositories along with your local Maven repository and the public Mobi remote repository to resolve artifacts.

The org.ops4j.pax.web.cfg file configures the web service Apache Karaf uses to run Mobi. By default, Mobi only runs HTTPS on port 8443.

Mobi Shell

The Mobi Shell is a wrapper around the Karaf shell which provides additional commands and tools for working with Mobi data. To access the shell, run the bin/client script in MOBI_HOME (that’s bin\client.bat for you Windows users). The startup screen of the Mobi shell looks like the following.

                 @#@@
                @###@
               @@@@@                   _     _
   @@@       @@@@      _ __ ___   ___ | |__ (_)
  @,,,@@@@@&    @     | '_ ` _ \ / _ \| '_ \| |
  @,,&&     @  @      | | | | | | (_) | |_) | |
              @@      |_| |_| |_|\___/|_.__/|_|
               @@
              @///@
              @////&
               @@@@


  mobi (x.x.x)
  Powered by Apache Karaf (4.0.6)

Hit '<tab>' for a list of available commands
and '[cmd] --help' for help on a specific command.
Hit '<ctrl-d>' or 'osgi:shutdown' to shutdown mobi.

karaf@mobi>

The Mobi specific commands all start with mobi:. To view the list of available commands, type mobi: and hit TAB. To get information about a particular command, type the name of the command and --help afterwards and run it. For example, running mobi:import --help would show you this.

karaf@mobi>mobi:import --help
DESCRIPTION
        mobi:import

	Imports objects to a repository or dataset

SYNTAX
        mobi:import [options] ImportFile

ARGUMENTS
        ImportFile
                The file to be imported into the repository

OPTIONS
        -c, --continueOnError
                If true, continue parsing even if there is an error on a line.
        -d, --dataset
                The id of the DatasetRecord the file will be imported to
        -r, --repository
                The id of the repository the file will be imported to
        --help
                Display this help message
        -b, --batchSize
                The number representing the triple transaction size for importing.
                (defaults to 10000)

You can also run commands in the Mobi shell without opening it by running bin/client "command". For example, to run the mobi:repository-list command, you would run bin/client "mobi:repository-list". If the command you are running involves files with spaces in the name, make sure the spaces are escaped, meaning use "\ " instead of " ". The same goes for commands that include text within quotes, make sure the quotes are escaped as well.

Administration Guide

Mobi is made available as a compressed distribution package available here. Deployment consists of unpacking this distribution to an appropriate location on the filesystem and modifying included configuration files. Mobi comes pre-bundled with an open-source, file-based RDF database. By default, all data, logs, and configurations will be stored in the extracted file location.

Mobi Requirements

Hardware Requirements

We provide recommended hardware requirements as a guideline. These specifications are based on standard deployment environments. Larger production data or user requirements may require more powerful hardware configurations.

The table below provides a summary of the recommended hardware for production servers and the minimum requirements for test servers.

Component Minimum Recommended Guidelines

Available RAM

1 GB

8 GB or more

Mobi needs enough RAM to load large ontology and data files and run Mobi processes. The configurations provided refer to maximum Java heap size.

Disk Space

10 GB

40 GB or more

By default, Mobi stores all data and configurations in the extracted file location.

CPU

1 core

4 cores or more

Multi-core configurations dramatically improve performance of the bundled application server and database.

Software Requirements

The table below provides a summary of the software requirements.

Component Minimum Recommended Guidelines

Operating System

RHEL/CentOS 6
Windows 7
OSX

RHEL/CentOS 8

Mobi runs within standard Java runtimes; however, we recommend RHEL/CentOS operating systems for on-premise or cloud-based server environments.

Java

1.17

1.17 (latest)

The latest versions of Java 17 include security and performance updates.

Web Browser

Chrome
Firefox
Safari
Edge

Chrome

Use the latest versions of web browsers for best compatibility, performance, and security.

Firewall Requirements

The table below lists the TCP ports to open on the Mobi host.

Port Description

8443

Application HTTPS port.

Tip
We recommend running Mobi on the default port 8443 and using firewall configuration or a proxy server for SSL (port 443) termination and redirection. Mobi does not run on non-SSL ports by default.

Installing Mobi

Pre-Installation Configuration

Create Service Account

Before installing Mobi, create a service account on the host server. The account will be used to run Mobi. The service account should meet the following requirements:

  • The service account must have read and write permissions for the Mobi installation directory. On Linux, this is typically /opt/mobi/mobi-distribution-<version>.

On a standard RHEL/CentOS system, this can be created using the following command:

sudo useradd -d /opt/mobi mobi
Install Java 17

Mobi requires the latest version of Java 1.17 to operate. On a standard RHEL/CentOS system, there is no package available via yum to install. So we suggest Downloading the Oracle installer from here and running it manually using the following commands:

wget https://download.oracle.com/java/17/latest/jdk-17_linux-x64_bin.rpm
sudo rpm -Uvh jdk-17_linux-x64_bin.rpm
Note
If you are using a Red Hat system, you can install Java 17 with sudo yum install java-17-openjdk

The JAVA_HOME environment variable must be set for the user running Mobi. On a standard RHEL/CentOS system (after running the rpm above) this can be set using the following commands:

sudo su - mobi
echo 'export JAVA_HOME=/usr/java/jdk-17.0.4.1' >> ~/.bashrc
exit

Install Mobi

Follow the instructions below to install Mobi. These instructions assume that you have copied the Mobi distribution to the server.

Note
These instructions are prepared for a standard RHEL/CentOS deployment server.
  1. Unpack Mobi to the installation parent directory (e.g. /opt/mobi)

    sudo su - mobi
    tar -xf $MOBI_DIST.tar.gz
  2. Create a symlink to the latest distribution

    ln -s $MOBI_DIST latest
  3. Start the Mobi server

    cd latest
    ./bin/start

To stop the Mobi server, run the following command:

./bin/stop

Post-Installation Configuration

Change the Default Java Heap Size

Set the max heap size in $MOBI_DIST/bin/setenv (e.g. JAVA_MAX_MEM=4G). In version 1.21, to include the JAVA_MAX_MEM and JAVA_MIN_MEM variables in the Mobi startup, add the following line beneath them in the setenv file.

Note
All versions from 1.22 onwards have this line already added.
export JAVA_OPTS="-Xms${JAVA_MIN_MEM} -Xmx${JAVA_MAX_MEM}"
Change the Default Web Port

Change the default SSL port in $MOBI_DIST/etc/org.ops4j.pax.web.cfg

org.osgi.service.http.port.secure = <SSL_APPLICATION_PORT>
Tip
We recommend running Mobi on the default port 8443 and using firewall configuration or a proxy server for SSL (port 443) termination and redirection. Mobi does not run on non-SSL ports by default.
Configure Custom SSL Certificates

Mobi comes bundled with default self-signed SSL certificates stored in a Java Keystore file in etc/keystore. To provide your own SSL certificates, simply replace the default keystore file with your own:

cp mycerts.jks $MOBI_DIST/etc/keystore

If there is a keystore password, it can be configured in the $MOBI_DIST/etc/org.ops4j.pax.web.cfg file using the following configuration properties:

Configuration Property Description

org.ops4j.pax.web.ssl.keystore.password

The password used for keystore integrity check

org.ops4j.pax.web.ssl.key.password

The password used for keystore

Installing Mobi as a Service

We recommend that you configure Mobi as a Linux service for starting Mobi automatically as the service user. Follow the instructions below to implement the service on a standard RHEL/CentOS environment.

Note
The below steps should be run as the root user.
Warning
Be sure to correctly configure the file locations and user.
  1. Create a file called mobi.service in the /usr/lib/systemd/system directory. For example:

    [Unit]
    Description=Mobi Service.
    After=network.target
    StartLimitIntervalSec=30
    
    [Service]
    Type=forking
    PIDFile=/install_path/latest/karaf.pid
    User=mobi
    ExecStart=/install_path/latest/bin/start
    ExecStop=/install_path/latest/bin/stop
    ExecReload=/install_path/latest/bin/stop; /install_path/latest/bin/start
    Restart=always
    
    [Install]
    WantedBy=default.target
  2. Save and close the file, and then run the following commands to start and enable the new service:

    systemctl start mobi
    systemctl enable mobi

Once the service is enabled, Mobi should be running. The Mobi process will start and stop automatically with the server. Any time you start and stop Mobi manually, run the following systemctl commands: sudo systemctl stop mobi and sudo systemctl start mobi.

Configure Default Authentication Token (JWT) Duration

To configure the web authentication token duration, you must create a file called com.mobi.jaas.SimpleTokenManager.cfg with the property detailed below and put it in the etc/ directory of your Mobi installation before starting the application, otherwise the token duration will use the default of 24 hours.

Note
In Enterprise deployments, this is only applied to non-SSO based authentication.
Property Name Description Required Default

tokenDurationMins

Token Duration time in minutes

1440

An example file would look like this.

### 1 day token duration
tokenDurationMins = 1440
Note
.p12 and .jks files should both be supported
LDAP Configuration (ENTERPRISE)

In Enterprise deployments only, Mobi can be configured so that users can log into the application with the Users/Groups defined in your organization’s directory, you must create a file called com.mobi.enterprise.ldap.impl.engine.LDAPEngine.cfg with the following properties and put it in the $MOBI_DIST/etc/ directory before starting the application. If a property is not required, you can delete the line from the config file. The list of possible fields for the config file are shown in the table below.

Property Name Description Required Default

repository.target

Should always be (id=system)

ldap.server

The hostname of the ldap server (ex: localhost)

ldap.port

The port of the LDAP server (ex: 10389)

ldap.timeout

The number of seconds it will keep trying to reach the LDAP server before it gives up (ex: 30)

30

ldap.ssl

Whether to connect to the LDAP engine with SSL (ex: false)

false

ldap.disable-auth

Whether direct authentication to the LDAP engine is disabled (ex: false)

false

ldap.expiry

The number of milliseconds before a LDAPUser should be retrieved (ex: 3600000)

3600000

ldap.admin.dn

The admin DN on your LDAP server (ex: uid=admin,ou=system)

ldap.admin.password

The admin password on your LDAP server (ex: secret)

ldap.users.base

The base DN at which to start looking for users on the LDAP server (ex: ou=people,dc=example,dc=com)

ldap.users.filter

An optional LDAP filter for retrieved users. (ex: (businessCategory=Managers) )

ldap.users.id

The field name on users that the Mobi application will use as the username to log in (ex: uid)

`

ldap.users.firstName`

The field name on users whose value is the first name of the user (ex: givenName)

ldap.users.lastName

The field name on users whose value is the last name of the user (ex: sn)

ldap.users.email

The field name on users whose value is the email address of the user (ex: mail)

ldap.users.membership

The field name on users whose values are the groups they are a part of (ex: memberOf)

ldap.users.membership.search

The format of the user membership field. Should be set to the field name on groups that the values of the user membership field uses. If this is not set, assume the values are full group DNs. (ex: cn)

ldap.groups.base

The base DN at which to start looking for groups on the LDAP server (ex: ou=groups,dc=example,dc=com)

ldap.groups.filter

An optional LDAP filter for retrieved groups (ex: (businessCategory=Managers) )

ldap.groups.id

The field name for groups' ids (ex: dn)

ldap.groups.name

The field name for groups' names/titles (ex: title)

ldap.groups.description

The field name on groups whose value is the description of the group (ex: description)

ldap.groups.membership

The field name on groups whose values are the users that are a part of the group (ex: member)

ldap.groups.membership.search

The format of the group membership field. Should be set to the field name on users that the values of the group membership field uses. If this is not set, assume the values are full user DNs. (ex: uid)

An example file would look like this.

repository.target = (id=system)
ldap.server = localhost
ldap.port = 10389
ldap.timeout = 30
ldap.admin.dn = uid=admin,ou=system
ldap.admin.password = secret
ldap.users.base = ou=people,dc=example,dc=com
ldap.users.filter = (businessCategory=Superhero)
ldap.users.id = uid
ldap.users.firstName = givenName
ldap.users.lastName = sn
ldap.users.membership = memberOf
ldap.groups.base = ou=groups,dc=example,dc=com
ldap.groups.id = cn
ldap.groups.name = cn
ldap.groups.description = description
ldap.groups.membership = member
SSO Configuration (ENTERPRISE)

In Enterprise deployments only, Mobi can be configured to integrate with an SSO provider for authentication. LDAP can be configured alongside the SSO provider to retrieve additional user details, but it is not required. If configured, it is recommended to disable direct authentication against the LDAP directory by adding ldap.disable-auth = false to the com.mobi.enterprise.ldap.impl.engine.LDAPEngine.cfg file. Mobi supports SAML, OAuth 2.0, and OpenID SSO providers.

SAML Configuration

In order to configure Mobi to use SAML, you will need to create a file called com.mobi.enterprise.auth.saml.api.SAMLConfigProvider.cfg to the $MOBI_DIST/etc/ directory. The must have the following fields.

Note
${karaf.etc} is a reference to the $MOBI_DIST/etc/ directory that the application will understand and replace
Note
In order for the certFile to ba valid format, it must contain the appropriate -----BEGIN CERTIFICATE----- header and -----END CERTIFICATE----- footer
Property Name Description Required

title

The title for the SSO provider. This title will be used in the UI for triggering the SSO authentication in the format of “Login with title”

entityId

The SP EntityId. The SSO provider must be configured to expect requests with this SP EntityId

certFile

The file path to a file containing the X509 certificate for verifying the signature of SAML responses. Best practice is to put the file in the $MOBI_DIST/etc/ directory and make this value ${karaf.etc}/<INSERT-FILE-NAME>

keyFile

The optional file path to a file containing the PKCS8 key for verifying the signature of SAML responses. Best practice is to put the file in the $MOBI_DIST/etc/ directory and make this value ${karaf.etc}/<INSERT-FILE-NAME>

ssoUrl

The URL for the SingleSignOnService from the IdP. This is where Mobi will redirect to.

idAttribute

The name of the Attribute in the SAML response where the username can be found. Defaults to using the <UserId>.

ssoBinding

The full URN of the binding to be used for the SAML Requests. Defaults to urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect

standalone

Whether the SAML configuration should be considered by itself or with a LDAP backend as well. Defaults to false. If true, the properties below are applied.

firstNameAttribute

An optional property to specify the name of the attribute in the SAML responses that contains the first name of the authenticated user. Only applicable if standalone.

lastNameAttribute

An optional property to specify the name of the attribute in the SAML responses that contains the last name of the authenticated user. Only applicable if standalone.

emailAttribute

An optional property to specify the name of the attribute in the SAML responses that contains the email of the authenticated user. Only applicable if standalone.

groupAttribute

An optional property to specify the name of the attribute in the SAML responses that contains the groups that the authenticated user is a part of. The values of this attribute will be used as the Group’s title in Mobi. Only applicable if standalone.

An example file with an LDAP backend would look like this.

title=Samling
entityId=https://localhost:8443/mobi/#/login
certFile=${karaf.etc}/samling.cert
keyFile=${karaf.etc}/samling_pkcs8.key
ssoUrl=https://capriza.github.io/samling/samling.html
idAttribute=ShortName
ssoBinding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

An example standalone configuration would look like this.

title=Samling
entityId=https://localhost:8443/mobi/#/login
certFile=${karaf.etc}/samling.cert
keyFile=${karaf.etc}/samling_pkcs8.key
ssoUrl=https://capriza.github.io/samling/samling.html
idAttribute=ShortName
ssoBinding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
standalone=true
firstNameAttribute=FirstName
lastNameAttribute=LastName
emailAttribute=MBox
groupAttribute=Groups
Default SAML Token Duration

In order to configure the token duration for SAML logins, you must create a file called com.mobi.enterprise.auth.rest.SAMLRest.cfg with the following properties and put it in the $MOBI_DIST/etc/ directory before starting the application, otherwise the token duration will use the default of one day. There is only one possible field for the config file as shown in the table below that is configurable and not required to set the token duration value.

Property Name Description Required Default

tokenDurationMins

Token Duration time in minutes

1440

An example file would look like this.

### 1 day token duration
tokenDurationMins = 1440
OAuth/OpenID Configuration

In order to configure Mobi to use OAuth or OpenID, you will need to create two files in the $MOBI_DIST/etc directory: com.mobi.enterprise.auth.oauth.api.OAuthConfigProvider.cfg and com.mobi.enterprise.auth.oauth.impl.token.OAuthTokenLoginModuleProvider.cfg. The latter must be an empty file. The former can be used to configure a generic OAuth 2.0 Provider or an OpenID Provider. For either, the file must have the following fields.

Property Name Description Required

title

The title for the SSO provider. This title will be used in the UI for triggering the SSO authentication in the format of “Login with title”

clientId

The ID for the Mobi installation. The OAuth/OpenID provider must be configured to expect requests with this clientId

scope

The OAuth scopes to include in the authentication request

clientSecret

The optional client secret to use in requests to the OAuth/OpenID provider.

userIdentifierClaim

An optional property to specify which claim in the returned JWT contains the user’s username. These values must match what is configured for the LDAP users id. Defaults to using the sub of the JWT

standalone

Whether the OAuth/OpenID configuration should be considered by itself or with a LDAP backend as well. Defaults to false. If true, the property below is applied.

groupClaim

An optional property to specify which claim in the returned JWT contains the groups the user is a part of. The values of this attribute will be used as the Group’s title in Mobi. Only applicable if standalone.

For OAuth 2.0, the file must also contain these fields.

Property Name Description Required

grantType

The OAuth 2.0 grant type to use for authentication. Mobi currently supports the CODE and IMPLICIT flows.

redirectUrl

The URL for the OAuth/OpenID provider. This is where Mobi will redirect to.

tokenUrl

The URL to hit to retrieve the token in the CODE flow.

keyFile

The file path to a file containing the PKCS8 key for verifying the signature of JWT tokens. Best practice is to put the file in the $MOBI_DIST/etc/ directory and make this value ${karaf.etc}/<INSERT-FILE-NAME>

An example file would look like this.

title=Mock OAuth
clientId=mobi
scope=read,openid
grantType=CODE
redirectUrl=http://localhost:8080/authorize
tokenUrl=http://localhost:8080/token
keyFile=${karaf.etc}/NTs4oGbx1A-cROpjgUKdKtzTEkHUhhSwQ7xdhN6FdlQ_pub.pem

For OpenID, the file must also contain these fields.

Property Name Description Required

openidConfigHostname

The hostname of the OpenID provider. The standard /.well-known/openid-configuration path will be appended to this value.

An example file would look like this.

title=Mock OAuth
clientId=mobi
scope=read,openid
openidConfigHostname=http://localhost:8080
Azure AD OpenID Setup

If you want to configure OpenID integration with Azure AD, there are a few extra steps that need to be taken due to the unique structure of the returned JWTs.

The complementary LDAP configuration for an Azure AD OpenID provider must set the userPrincipalName as the ldap.users.id property in the com.mobi.enterprise.ldap.impl.engine.LDAPEngine.cfg as the Azure AD JWTs do not contain the typical samAccountName values.

In addition, v2.0 of Azure AD adds an additional field to the header of the JWT after signing it, thus making the signature incapable of being verified by the algorithms returned from the JWKS endpoint. In order to stop Azure AD from adding this additional field, you can add a new custom scope to the App registration. The steps to do this are described in this article (https://medium.com/@abhinavsonkar/making-azure-ad-oidc-compliant-5734b70c43ff) under “Problem 1”.

Password Encryption Configuration

Mobi provides a way to automatically encrypt plaintext passwords stored within service configurations on startup and subsequent updates. The setup for this is very short. All you have to do is ensure that a file called com.mobi.security.api.EncryptionService.cfg exists in the $MOBI_DIST/etc directory and contains the following fields:

enabled=true
password=ENTER_A_UNIQUE_PASSWORD_HERE
Note
This password is not the password you want to encrypt, rather it is a unique master password used for encrypt and decrypt operations.

This encryption config is present and enabled by default, meaning your passwords will be automatically encrypted. An alternate way of providing an encryption master password is via environment variable. To configure the use of an environment variable, use the following fields:

enabled=true
variable=MY_CHOSEN_ENVIRONMENT_VARIABLE

If you use an environment variable, make sure before you start Mobi that you have stored a unique password as the value for that environment variable.

Warning
If there is a default password in the Encryption Config (i.e. CHANGEME) make sure you change it to a unique password before starting Mobi, otherwise your passwords will be easy to decrypt.

Once the encryption config is added, start Mobi and if a Mobi service configuration includes a plaintext password, it will encrypt the value and update the configuration file. To change an encrypted value, simply replace it with the new plaintext value in the configuration file and after a few seconds it will be automatically re-encrypted and the file will be updated.

Services that use Encryption
Service Config File Field that gets encrypted

Email

com.mobi.email.api.EmailService.cfg

emailPassword

To update the encryption master password, change the password field in the com.mobi.security.api.EncryptionService.cfg file while Mobi is running. After a few seconds have passed, all passwords will be automatically re-encrypted using the new master password.

Note
If the master password is changed while Mobi is not running, all previously encrypted passwords must be re-entered in plain text for the encryption service to re-encrypt.

Developer Guide

Prerequisites

To build the Mobi source code, you must have the following software and tools installed.

Technology Version Download Link

Java

17

http://www.oracle.com/technetwork/java/javase/downloads/index.html

Maven

3.6+

https://maven.apache.org/download.cgi

Node.js

14+

https://nodejs.org/en/download/

Google Chrome

105+

https://www.google.com/chrome/

Build from Source

Clone the Mobi project from GitHub and navigate to that directory on your machine. Run the following command to build the source:

mvn clean install

The build creates the Mobi distribution as both a .tar.gz file and a .zip file in the mobi-distribution/target directory. Extract one of the files and navigate into that directory.

Inside the extracted distribution directory, start up the Mobi Karaf instance. For Unix/Linux:

bin/start

or for Windows:

bin\start.bat

All the Mobi bundles and services and their dependencies will be automatically deployed using OBR.

The Mobi web application should now be accessible at https://localhost:8443/mobi/index.html.

OntologyCache Configuration File

Mobi utilizes the Repository Cache Ontology API implementation to represent Ontologies.

Configuration file for the CacheRepositoryCleanup job:

com.mobi.cache.impl.repository.CleanupRepositoryCache.cfg

This file is responsible for deleting stale ontologies within the repository after a specified period in order to preserve resources and improve processing. The format looks like the following:

repoId = ontologyCache
expiry = 1800
scheduler.expression=0 0 * * * ?

Clearing Pre-existing Configurations in Karaf

If Mobi has been run with the OWLAPI implementation prior to using the Repository Cache implementation, a configuration object will have been stored in Karaf and must be removed.

From the Karaf terminal run:

karaf@mobi()> config:delete com.mobi.ontology.impl.owlapi.OntologyManager

In order to revert back to the OWLAPI implementation after the Repository cache implementation has been launched, run the following:

karaf@mobi()> config:delete com.mobi.ontology.impl.repository.OntologyManager

Load Dataset Data

Data can be manually loaded into an existing Dataset using the Mobi shell. You will need the full path to the data file and the IRI of the target DatasetRecord.

Open the Mobi shell and run the mobi:import command passing the IRI of the DatasetRecord and the path to the data file. For example, if you wanted to load data located at /Users/tester/Documents/testData.trig into the https://mobi.com/records/my-dataset DatasetRecord, you would run the following command:

mobi:import --dataset https://mobi.com/records/my-dataset /Users/tester/Documents/testData.trig

All triples that are not within a named graph will be loaded into the system default named graph. All triples within named graphs will be added and their named graphs associated with the Dataset.

Accessing Swagger REST API Documentation

Every installation of Mobi provides Swagger Documentation for the full suite of Mobi REST APIs. This documentation is provided as a standard Swagger YAML file as well as a fully interactive hosted version. The Swagger YAML file can be downloaded at $MOBI_HOST/swagger-ui/mobi-swagger.yaml. To reach the Swagger Documentation UI, navigate to $MOBI_HOST/swagger-ui/index.html. For example, in a default deployment these URLs would look like https://localhost:8443/swagger-ui/mobi-swagger.yaml and https://localhost:8443/swagger-ui/index.html, respectively.

Swagger REST API Documentation

Translating Documents

Files in the xml, json, or csv formats can be transformed into an ontology and corresponding instance data using Mobi’s document translation tool. This experimental feature can be utilized via REST endpoint, the Mobi shell, or from the Swagger UI, with all methods providing users configuration options to alter the generated files.

Utilizing the Mobi Shell

The tool can be run from the Mobi shell with the mobi:document-translate command. The command accepts the full path to both the input file to translate and output location for the result. Below is an example call to the command:

mobi:document-translate /Users/tester/Documents/example.json /Users/tester/Documents/outputDir

The Document Translate command accepts several additional configuration options to tailor the way the input file is processed. These options currently include the ability to set the default namespace of the generated ontology and instance data, specify the type of file being translated, and set a number of rows in a CSV to be analyzed before identifying a data property range. The command result is a zip file located at the output destination that contains two turtle files: ontology.ttl which will contain an ontology describing the structure of the input file and data.ttl which will contain the data within your input file translated into RDF data conforming to the ontology.

Utilizing the REST endpoints and Swagger UI

Mobi’s REST endpoints & Swagger UI provide additional ways to use the document translation tool. When using either a direct REST call or the Swagger UI, users are able to select an input file from their filesystem and convert it to valid RDF. If successful, output is returned as a downloadable zip file. Similar to the output generated by the Mobi shell, this zip file contains two turtle files containing the generated ontology and conforming instance data respectively. Additionally, these two methods provides users the same configurable options that the Mobi shell does, with one additional option. When using Rest endpoints or the Swagger UI to translate a document, users are able to also specify the name of the output file. If one is not specified, the name of the input file will be used with a timestamp added on to the end.

Document Translation Swagger Documentaion
Document Translation Postman Documentaion

Translating Different File Types

XML

The XML translator uses the hierarchical structure of the XML input file in order to construct classes and object properties.

XML Input File
Figure 111. XML Example File

When generating the ontology, each element is simultaneously treated as a class and object property if it has child elements and is regarded as a datatype property if it does not. The output will resemble a file similar to the one below.

XML Ontology Ouput File
Figure 112. XML Example Ontology File

The generated data file is composed of elements that have been deemed a class and that have literal values attached to it. Each instance is given a unique IRI based on the namespace of the ontology with a trailing UUID attached at the end.

XML Data Output File
Figure 113. XML Example Data File
JSON

Given a JSON file like below, the JSON translator will use the nested structure of JSON objects in order to construct classes and object properties.

JSON Input File
Figure 114. JSON Example File

An output ontology is then generated using the passed in IRI or a UUID as the namespace. Classes and object properties relating these classes are created based on the keys present in the input file.

JSON Ontology Output File
Figure 115. JSON Example Ontology File

The generated data file is created by utilizing the literal values of each key object. For each instance of a JSON object there is in the input file an RDF entity is created with the same namespace as the ontology.

JSON Data Output File
Figure 116. JSON Example Data File
CSV

The CSV translation tool is the only translator that does not create multiple classes or any object properties. A singular class is generated per file, with the name of the file being used as the name of the class.

CSV Input File
Figure 117. CSV Example File

Each column header is treated as a different datatype property, with the translator parsing a certain number of rows to determine the range of the property.

CSV Ontology Ouput File
Figure 118. CSV Example Ontology File

When creating the instance data, each row within the file is treated as an instance of the class with the cell values being the object of the triples generated by the datatype properties.

CSV Data Output File
Figure 119. CSV Example Data File

Appendix A: Mobi Mappings

Mobi mappings are used to convert delimited data into RDF and are made up of instances of classes defined in a custom ontology found in the com.mobi.etl.api/src/main/resources/delimited.ttl file in the source code. These main classes are:

Note

All examples in this Appendix will be in Turtle RDF serialization and use the following prefixes:

Prefix Namespace

example

http://guide.org/

delim

http://mobi.com/ontologies/delimited#

Mapping

The delim:Mapping class represents the mapping itself. Every mapping must have one and only one instance of the Mapping class. Properties associated with this class provide information about the mapping that are needed for the Mapping Tool to have context. These properties are:

sourceRecord

The delim:sourceRecord property specifies the OntologyRecord a mapping uses for its classes and properties. The Mapping Tool requires this property along with sourceBranch and sourceCommit to retrieve a specific version of an ontology saved in Mobi. A mapping will have access to all entities defined in ontologies within the imports closure of the source ontology. The Mapping Tool utilizes all class and property definitions to validate the class and property mappings and apply the correct datatypes to data property values.

Example 1. sourceRecord
example:DocumentExample delim:sourceRecord <http://mobi.com/records/uhtc> .

sourceBranch

The delim:sourceBranch property specifies the Branch of the sourceRecord a mapping uses for its classes and properties. The Mapping Tool requires this property along with sourceRecord and sourceCommit to retrieve a specific version of an ontology saved in Mobi. A mapping will have access to all entities defined in ontologies within the imports closure of the source ontology. The Mapping Tool utilizes all class and property definitions to validate the class and property mappings and apply the correct datatypes to data property values.

Example 2. sourceBranch
example:DocumentExample delim:sourceBranch <http://mobi.com/branches/master> .

sourceCommit

The delim:sourceCommit property specifies the Commit of the sourceBranch a mapping uses for its classes and properties. The Mapping Tool requires this property along with sourceRecord and sourceBranch to retrieve a specific version of an ontology saved in Mobi. A mapping will have access to all entities defined in ontologies within the imports closure of the source ontology. The Mapping Tool utilizes all class and property definitions to validate the class and property mappings and apply the correct datatypes to data property values.

Example 3. sourceCommit
example:DocumentExample delim:sourceCommit <http://mobi.com/commits/0> .

ClassMapping

The delim:ClassMapping class represents a blueprint for creating an instance of a class. Every ClassMapping defined in a mapping will create an instance of the class it maps to for every row in a set of delimited data. Each class instance created will have a generated IRI. Properties associated with this class specify how the class instance it creates should be constructed. These properties are:

mapsTo

The delim:mapsTo property specifies the class a ClassMapping will create. This is a required property for a ClassMapping since otherwise, the Mapping Tool will not know which class to create an instance of. It must point to a class that is defined either within the source ontology of the mapping or one of the ontologies in the source ontology’s imports closure.

Example 4. mapsTo
example:ClassMappingExample delim:mapsTo <http://mobi.com/ontologies/uhtc> .

dataProperty

The delim:dataProperty property specifies a DataMapping that is associated with a ClassMapping. It must point to a DataMapping instance defined within the mapping. A ClassMapping can have one or more of this property. Every instance of a class created from a ClassMapping will have the property specified in the DataMapping specified by dataProperty.

Example 5. dataProperty
example:ClassMappingExample delim:dataProperty example:DataMapping1 ;
    delim:dataProperty example:DataMapping2 .

objectProperty

The delim:objectProperty property specifies an ObjectMapping that is associated with a ClassMapping. It must point to a ObjectMapping instance defined within the mapping. A ClassMapping can have one or more of this property. Every instance of a class created from a ClassMapping will have the property specified in the ObjectMapping specified by objectProperty.

Example 6. objectProperty
example:ClassMappingExample delim:objectProperty example:ObjectMapping1 ;
    delim:objectProperty example:ObjectMapping2 .

hasPrefix

The delim:hasPrefix property specifies the namespace of the IRI for every class instance created by a ClassMapping. This property is required by the Mapping Tool so it knows how to construct the IRI for each class instance created by the ClassMapping. The value of this property is a string and must be a valid namespace.

Example 7. hasPrefix
example:ClassMappingExample delim:hasPrefix "http://guide.org/example/" .

localName

The delim:localName property specifies how the local name of the IRI will be generated for every class instance created by a ClassMapping. This property points to a string literal and must be in the following format. The string must start with a dollar sign ($) and contain either the string "UUID" or a number surrounded by curly braces "{}". The "UUID" string will generate a unique identifier for every class instance created by the ClassMapping. A number will grab the value of the column at that zero-based index in the row being mapped. If the column specified has duplicate values, the Mapping Tool will combine the properties of every class instance with that IRI and combine them into a single instance. If this property is not set on a ClassMapping, the Mapping Tool will default to generating a UUID for every class instance.

Example 8. localName

This means every class instance will have a unique identifier for a local name.

example:ClassMappingExample1 delim:localName "${UUID}" .

This means every class instance will have the value from the third column for a local name.

example:ClassMappingExample2 delim:localName "${2}" .

DataMapping

The delim:DataMapping class represents a blueprint for creating a data property on a class instance. Since data properties in an ontology point to literal values, a DataMapping specifies a column whose value in the row being mapped will be used as the value of the generated data property. Properties associated with this class define how a data property will be created. These properties are:

columnIndex

The delim:columnIndex property specifies which column a DataMapping should pull the value from to set as the value of the generated data property. This property is required for a DataMapping so that the Mapping Tool knows where to get the value of a data property. All column values retrieved by this property are interpreted as strings. The value of this property must be a string and all the column indexes are zero-based.

Example 9. columnIndex

This will retrieve the value from the first column.

example:DataMapping1 delim:columnIndex "0" .

hasProperty

The delim:hasProperty property specifies which data property a DataMapping will create. This property is required for a DataMapping so that the Mapping Tool knows what property to create. It must point to a data property defined either within the source ontology of the mapping or one of the ontologies in the source ontology’s imports closure. This property can be associated with either a DataMapping or a ObjectMapping.

Example 10. hasProperty for DataMapping
example:DataMapping1 delim:hasProperty <http://mobi.com/ontologies/uhtc/aDataProperty> .

datatypeSpec

The delim:datatypeSpec property specifies a manual override for the datatype of generated data property values resulting from a DataMapping. By default, the datatype will be determined from the range of the property if found with a fallback of string. This setting has precedence over the range of the property. This property is optional for a DataMapping. The value of this property must be the IRI of a standard XSD datatype.

Example 11. datatypeSpec

This will set the datatype of all values to xsd:double.

example:DataMapping1 delim:datatypeSpec xsd:double .

languageSpec

The delim:languageSpec property specifies a language for all generated data property values resulting from a DataMapping. If this property is set, the mapper will manually change the datatype of the value to be rdfs:langString. Any datatype specified by the range of the property will be ignored. This property is optional for a DataMapping. The value of this property must be a valid language tag string (found here under the ISO 639-1 column).

Example 12. languageSpec

This will set the language of all values to be English.

example:DataMapping1 delim:languageSpec "en" .

ObjectMapping

The delim:ObjectMapping class represents a blueprint for creating an object property on a class instance. Since object properties in an ontology point to other classes or class expressions, an ObjectMapping specifies a ClassMapping that will be created for the same row and whose generated class instance will be used as the value of the generated object property. Properties associated with this class define how an object property will be created. These properties are:

classMapping

The delim:classMapping property specifies which class instance generated from a ClassMapping will be used as the value of the generated object property. This property is required for an ObjectMapping so that the Mapping Tool knows which class should be the value of the object property. The generated value will be the class instance created by the specified ClassMapping for the row being mapped. The value must be a ClassMapping defined within the mapping.

Example 13. classMapping
example:ObjectMapping1 delim:classMapping delim:ClassMappingExample .

hasProperty

The delim:hasProperty property specifies which object property an ObjectMapping will create. This property is required for an ObjectMapping so that the Mapping Tool knows what property to create. It must point to a object property defined either within the source ontology of the mapping or one of the ontologies in the source ontology’s imports closure. This property can be associated with either a ObjectMapping or a DataMapping.

Example 14. hasProperty for ObjectMapping
example:ObjectMapping1 delim:hasProperty <http://mobi.com/ontologies/uhtc/aObjectProperty> .

Appendix B: Mobi Datasets

Mobi datasets are used to group and store RDF data into various graphs for enhanced query isolation, data segmentation, and management. The Mobi dataset structure is defined in a custom ontology found in the com.mobi.dataset.api/src/main/resources/dataset.ttl file in the source code. This design is loosely based on the W3C Specification for SPARQL Datasets wherein a collection of graphs can be queried as default named graphs or named graphs. The primary class is dataset:Dataset, and the properties associated with this class provide information about all the named graphs within the dataset. These properties are:

Note

All examples in this Appendix will be in TriG RDF serialization and use the following prefixes:

Prefix Namespace

example

http://guide.org/

dataset

http://mobi.com/ontologies/dataset#

systemDefaultNamedGraph

The dataset:systemDefaultNamedGraph property specifies the default named graph that Mobi will use when loading data that does not specify a graph (e.g. data from a Turtle file). For example, this approach is currently used for data created by the Mapping Tool. This named graph will be cleared, but not removed when a dataset is cleared.

Example 15. systemDefaultNamedGraph
GRAPH example:DatasetExample {
    example:DatasetExample a dataset:Dataset ;
        dataset:systemDefaultNamedGraph example:sdng .
}

GRAPH example:sdng {
    example:Subject a example:Object .
}

defaultNamedGraph

The dataset:defaultNamedGraph property specifies a default named graph within the dataset. These graphs are not maintained by the system and can be used when data segmentation is required within a dataset. These graphs are removed when a dataset is cleared.

Example 16. defaultNamedGraph
GRAPH example:DatasetExample {
    example:DatasetExample a dataset:Dataset ;
        dataset:defaultNamedGraph example:dng .
}

GRAPH example:dng {
    example:Subject a example:Object .
}

namedGraph

The dataset:namedGraph property specifies a named graph within the dataset. These graphs are not maintained by the system and can be used when data segmentation is required within a dataset. These graphs are removed when a dataset is cleared.

Example 17. namedGraph
GRAPH example:DatasetExample {
    example:DatasetExample a dataset:Dataset ;
        dataset:namedGraph example:ng .
}

GRAPH example:ng {
    example:Subject a example:Object .
}

Appendix C: Settings Framework

The Settings Framework was designed to allow the tracking and editing of Settings within Mobi. The framework was designed to be easily extensible such that a new setting can be added to the platform with only some RDF and a few code changes.

The Preferences Tab is powered by the User Preference definitions stored within the system which can be tailored to populate different types of forms depending on the type of data to be stored.

Setting RDF Definition

In order to introduce new Settings to Mobi, a developer must create an RDF representation of the Setting they want to add to the application. The Setting Framework uses SHACL to define settings. Setting RDF must consist of exactly one SHACL NodeShape and one SHACL PropertyShape in order to be recognized as a Setting by Mobi. Requirements for the structure of these SHACL shapes is outlined below.

The following prefixes will be used in the rest of this appendix:

Prefix Namespace

owl:

http://www.w3.org/2002/07/owl#

rdfs

http://www.w3.org/2000/01/rdf-schema#

shacl:

http://www.w3.org/ns/shacl#

setting:

http://mobi.com/ontologies/setting#

xsd:

http://www.w3.org/2001/XMLSchema#

For an explanation of what each SHACL class and property represent, read the descriptions given here: https://www.w3.org/TR/shacl/. The following are descriptions of Mobi specific properties.

setting:Preference

The setting:Preference class acts as the parent class of all preferences within Mobi. Mobi preferences always have an rdfs:subClassOf setting:Preference and are also of type sh:NodeShape.

setting:ApplicationSetting

The setting:ApplicationSetting class acts as the parent class of all application settings within Mobi. Mobi application settings always have an rdfs:subClassOf setting:ApplicationSetting and are also of type sh:NodeShape.

Note
From here on, when referring to either setting:Preference or setting:ApplicationSetting the phrase setting subType may be used.

setting:PreferenceGroup

Every Mobi preference must have a setting:inGroup of a instance of setting:PreferenceGroup. These preference groups are meant to group together semantically related preferences.

setting:ApplicationSettingGroup

Every Mobi application setting must have a setting:inGroup of a instance of setting:ApplicationSettingGroup. These application setting groups are meant to group together semantically related application settings.

setting:FormField

Instances of the setting:FormField class are used by Mobi settings to specify the form input that is used by the UI to select setting values.

setting:hasDataValue

The setting:hasDataValue property is used by instances of setting subTypes to point to the current value of that setting. All Settings must point to a Property Shape that has an sh:path of setting:hasDataValue.

setting:usesFormField

The setting:usesFormField property is used by the required sh:PropertyShape of a Mobi Setting to designate the type of form input that will be used by the frontend to accept setting values for that specific setting.

setting:inGroup

The setting:inGroup property specifies either the setting:PreferenceGroup or setting:ApplicationSettingGroup that a Mobi Setting belongs too. It is used to semantically group related Settings in the UI.

Required SHACL NodeShape
  • Must be of type owl:Class as well as type shacl:Nodeshape

  • Must have an rdfs:subClassOf of setting:Preference or setting:ApplicationSetting

  • Must have an shacl:description that will be shown above the Setting in the UI

  • Must have a shacl:property that points to the required SHACL PropertyShape for the setting

  • Must have a setting:inGroup of an IRI in the system of type setting:PreferenceGroup or setting:ApplicationSettingGroup

Required SHACL PropertyShape
  • Must be of type shacl:PropertyShape

  • Must have an shacl:path of setting:hasDataValue

  • A shacl:datatype of one of the following values

    • xsd:boolean

    • xsd:string

    • xsd:integer

  • Must have a setting:usesFormField that has one of the following values that will affect which type of form input is shown in the UI for this preference

    • setting:ToggleInput

    • setting:TextInput

  • Must have a setting:inGroup of a valid instance of the setting:PreferenceGroup or setting:ApplicationSettingGroup class.

  • May have optional shacl:minCount and/or shacl:maxCount fields denoting the min and max number of possible values for the preference which will be enforced in the UI.

  • May have optional shacl:pattern which may have a regex that controls what values may be used and will be enforced by the UI.

Note
Support for more datatypes and form fields coming soon!
Required PreferenceGroup/ApplicationSettingGroup
  • At least one instance of setting:PreferenceGroup or setting:ApplicationSettingGroup must exist which has an rdfs:label.

    • Preference/ApplicationSetting Groups already in the system can be reused.

Note
Predefined Property Groups coming soon

The following diagram illustrates the relationship between the various preference related classes and properties:

preference diagram

Example RDF

@prefix owl: <http://www.w3.org/2002/07/owl#>.
@prefix xsd: <http://www.w3.org/2001/XMLSchema#>.
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix sh: <http://www.w3.org/ns/shacl#>.
@prefix setting: <http://mobi.com/ontologies/setting#>.
@prefix : <http://mobi.com/ontologies/test#>.
@base <http://mobi.com/ontologies/test>.

:MyBooleanPreference a owl:Class, sh:NodeShape;
    rdfs:subClassOf setting:Preference;
    sh:description "What value do you want for your Boolean Preference?" ;
    sh:property :MyBooleanPreferencePropertyShape;
    setting:inGroup :MyTestPreferenceGroup .

:MyBooleanPreferencePropertyShape a sh:PropertyShape;
    sh:path setting:hasDataValue;
    sh:datatype xsd:boolean;
    sh:minCount 1 ;
    sh:maxCount 1 ;
    setting:usesFormField setting:ToggleInput .

:MyTestPreferenceGroup a setting:PreferenceGroup ;
    rdfs:label "My Test Preference Group"@en .

Adding Custom Settings

In order to create new custom settings in Mobi, there are 3 steps:

  1. Create Setting RDF to model the new Setting

  2. Generate Java classes from the Setting RDF using the Mobi rdf-orm-plugin

  3. Load the Setting RDF into the Mobi Repository

Generate Java Classes from Setting RDF

  • Create an RDF file with your custom setting definition in the src/main/resources directory of a Mobi bundle. This can be any valid RDF format, such a Turtle. A list of supported RDF formats can be found here: Uploading Existing Ontologies

  • Create a pom.xml based on the following example pom in the appropriate Mobi bundle.

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>org.example</groupId>
    <artifactId>Testsf</artifactId>
    <version>1.0-SNAPSHOT</version>
    <name>${project.groupId}.${project.artifactId}</name>
    <packaging>bundle</packaging>
    <parent>
        <artifactId>mobi-parent</artifactId>
        <groupId>com.mobi</groupId>
        <version>1.20.0</version>
        <relativePath></relativePath>
    </parent>
    <dependencies>
        <dependency>
            <groupId>com.mobi</groupId>
            <artifactId>rdf.orm</artifactId>
            <version>1.20.0</version>
        </dependency>
        <dependency>
            <groupId>com.mobi</groupId>
            <artifactId>setting.api</artifactId>
            <version>1.20.0</version>
        </dependency>
    </dependencies>
    <repositories>
        <repository>
            <id>inovex</id>
            <url>http://nexus.inovexcorp.com/nexus/content/repositories/public-maven-prod-group/</url>
        </repository>
    </repositories>
    <pluginRepositories>
        <pluginRepository>
            <id>inovex</id>
            <url>http://nexus.inovexcorp.com/nexus/content/repositories/public-maven-prod-group/</url>
        </pluginRepository>
    </pluginRepositories>
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.felix</groupId>
                <artifactId>maven-bundle-plugin</artifactId>
                <version>3.5.1</version>
                <extensions>true</extensions>
                <configuration>
                    <obrRepository>NONE</obrRepository>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-checkstyle-plugin</artifactId>
                <configuration>
                    <skip>true</skip>
                </configuration>
            </plugin>
            <plugin>
                <groupId>com.mobi.orm</groupId>
                <artifactId>rdf-orm-maven-plugin</artifactId>
                <version>1.20.0</version>
                <executions>
                    <execution>
                        <id>generateOrmSources</id>
                        <phase>generate-sources</phase>
                        <goals>
                            <goal>generate-orm</goal>
                        </goals>
                        <inherited>false</inherited>
                        <configuration>
                            <generates>
                                <ontology>
                                    <ontologyFile>${project.basedir}/src/main/resources/myontologyfile.ttl</ontologyFile>
                                    <outputPackage>my.bundle.ontologies</outputPackage>
                                    <ontologyName>MyOntologyName</ontologyName>
                                </ontology>
                            </generates>
                            <references>
                                <ontology>
                                    <ontologyFile>jar:http://nexus.inovexcorp.com/nexus/repository/public-maven-prod-group/com/mobi/rdf.orm.ontologies/1.20.0/rdf.orm.ontologies-1.20.0.jar!shacl.ttl</ontologyFile>
                                    <outputPackage>com.mobi.ontologies.shacl</outputPackage>
                                </ontology>
                                <ontology>
                                    <ontologyFile>jar:http://nexus.inovexcorp.com/nexus/repository/public-maven-prod-group/com/mobi/setting.api/1.20.0/setting.api-1.20.0.jar!setting.ttl</ontologyFile>
                                    <outputPackage>com.mobi.setting.api.ontologies</outputPackage>
                                    <ontologyName>Setting</ontologyName>
                                </ontology>
                            </references>
                            <outputLocation>${project.basedir}/src/main/java</outputLocation>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

Be sure to replace references to "My ontology" and "My bundle" with your actual ontology and bundle. Also make sure to have the <packaging>bundle</packaging> and the com.mobi.rdf.orm dependency. On your next Mobi build, interfaces, implementation classes, and factory classes will be created based on your ontology.

Load Setting RDF into Mobi Repo

In order for Setting RDF to be recognized by Mobi, it must be loaded into the http://mobi.com/setting-management graph. This can be done one of two ways. The first option is to upload the RDF via Mobi Command Line. To do this, create a trig file with a graph of http://mobi.com/setting-management that has the same contents as your setting RDF. The following is an example:

@prefix owl: <http://www.w3.org/2002/07/owl#>.
@prefix xsd: <http://www.w3.org/2001/XMLSchema#>.
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix sh: <http://www.w3.org/ns/shacl#>.
@prefix setting: <http://mobi.com/ontologies/preference#>.
@prefix : <http://mobi.com/ontologies/test#>.
@base <http://mobi.com/ontologies/test>.

<http://mobi.com/setting-management> {
:MyBooleanPreference a owl:Class, sh:NodeShape;
rdfs:subClassOf setting:Preference;
sh:description "What value do you want for your Boolean Preference?" ;
sh:property :MyBooleanPreferencePropertyShape;
setting:inGroup :MyTestPreferenceGroup .

    :MyBooleanPreferencePropertyShape a sh:PropertyShape;
        sh:path setting:hasDataValue;
        sh:datatype xsd:boolean;
        sh:minCount 1 ;
        sh:maxCount 1 ;
        setting:usesFormField setting:ToggleInput .

    :MyTestPreferenceGroup a setting:PreferenceGroup ;
        rdfs:label "My Test Preference Group"@en .
}

Next, start up Mobi, and run the following command in the Mobi Shell: mobi:import -r system /path/to/my/trigfile.trig. At this point, the preference should now be present and editable in the Mobi UI.

Note
This will only work if you have already built using the rdf-orm-plugin described earlier in the documentation to generate Java classes for the setting RDF.

The second option to load your Setting RDF into the Mobi Repository is to add code to the activate method of a service in your corresponding Mobi bundle. The following methods can be used to help add code into the Mobi Repository.

  • The Models.createModel() method to turn an InputStream into a Model.

  • getRepository().getConnection().add(…​) from the CatalogConfigProvider class used to add a model to the repo. Be sure to pass the http://mobi.com/setting-management iri as the context parameter value.

Example:

settingUtilsService.updateRepoWithSettingDefinitions(MY_ONTOLOGY_INPUT_STREAM, MY_ONTOLOGY_NAME);

Using a Stored Setting

In order to use the value of a stored setting, the setting service will be used in conjunction with one or more of the ORM generated classes (classes generated in the Generate Java Classes from Setting RDF section). The following is an example of how to extract the value of a boolean preference that exists in the system:

boolean myBooleanPreferenceValue = false;
Optional<Preference> myPreferenceOptional = preferenceService.getSetting(valueFactory.createIRI(MyPreference.TYPE), user;
if (myPreferenceOptional.isPresent()) {
    MyPreference myPreference = (MyPreference) myPreferenceOptional.get();
    myBooleanPreferenceValue = myPreference.getHasDataValue().orElseThrow(() -> new IllegalStateException("Some message")).booleanValue();
}

Appendix D: Mobi Security Policies

Mobi utilizes XACML standards to support Attribute-Based Access Control (ABAC). See the ABAC section for more detail.

Attribute-Based Access Control

Attribute-Based Access Control is an alternative to the traditional Role-Based Access Control (RBAC) - an authorization model where users are permitted to access resources based on the roles assigned to the user. As the name implies, ABAC evaluates a combination of Attributes to determine the user’s access permissions.

The base Attributes in Mobi’s ABAC model are:

  • Subject: The subject is the user requesting access to a resource in order to perform an action. These are typically gathered from a token or an existing database/HR system.

  • Resource: The resource is an object or asset (e.g., files, records, metadata, application, etc.) that the user wants to access. Resource attributes in Mobi are typically the IRIs of object.

  • Action: The action is what the user wants to do with the resource. The typical actions in Mobi are "Create", "Read", "Update", "Delete", and "Modify".

Attribute-Based Access Control Workflow

As an example, a policy in Mobi may state "Only users who have the admin role may view Ontology Record 1." When a request is made, Mobi’s XACML Engine (discussed below) will evaluate the request and grant view permission if the request has the following attributes:

  • Subject is the IRI of the User making the request

  • Subject hasUserRole of admin

  • Action is the "Read" action

  • Resource is the IRI of Ontology Record 1

XACML

eXtensible Access Control Markup Language (XACML) is an XML based language that enables security policy definitions and request evaluation to determine if a user has access to given resource. It is composed of the following components:

  • Policy Decision Point (PDP): Evaluates requests against authorization policies before issuing access decisions

  • Policy Enforcement Point (PEP): Intercepts user’s access request to a resource, makes a decision request to the PDP to obtain the access decision (i.e. access to the resource is approved or rejected), and acts on the received decision

  • Policy Information Point (PIP): The system entity that acts as a source of attribute values (i.e. a resource, subject, environment)

  • Policy Retrieval Point (PRP): Point where the XACML access authorization policies are stored, typically a database or the filesystem.

XACML Evaluation Engine

The XACML specification supports both Attribute-Based Access Control and Role-Based Access Control. Mobi’s implementation of XACML only supports ABAC. Request make to the PEP are evaluated in the PDP and return whether or not a user can access a Resource based on the ABAC schema defined above.

Mobi’s XACML definitions are structured using combinations of the following top level elements:

  • Policy: contains a set of Rule elements and a specified procedure for combining the results of their evaluation. It is the basic unit of the policy used by the PDP, and so it is intended to form the basis of an authorization decision

  • Rule: contains a Boolean expression that can be evaluated in isolation, but that is not intended to be accessed in isolation by a PDP. A Rule can be comprised of the following sub-elements:

    • Target: defines the set of requests to which the rule is intended to apply in the form of a logical expression on attributes in the request.

    • Effect: indicates the rule-writer’s intended consequence of a "True" evaluation for the rule. Two values are allowed: "Permit" and "Deny".

    • Condition: represents a Boolean expression that refines the applicability of the rule beyond the predicates implied by its target. Therefore, it may be absent.

    • Obligation Expressions: An operation specified in a rule, policy or policy set that should be performed by the PEP in conjunction with the enforcement of an authorization decision. These are currently unused in Mobi policies.

    • Advice Expressions: A supplementary piece of information in a policy or policy set which is provided to the PEP with the decision of the PDP. These are currently unused in Mobi policies.

XACML Example

Here is an example policy that is used in Mobi to control what users may create an Ontology Record:

<Policy xmlns="urn:oasis:names:tc:xacml:3.0:core:schema:wd-17" PolicyId="http://mobi.com/policies/ontology-creation" RuleCombiningAlgId="urn:oasis:names:tc:xacml:3.0:rule-combining-algorithm:deny-unless-permit" Version="1.0">
    <Description>Who can create an OntologyRecord in the Local Catalog?</Description>
    <Target>
        <AnyOf>
            <AllOf>
                <Match MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
                    <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">http://mobi.com/catalog-local</AttributeValue>
                    <AttributeDesignator AttributeId="urn:oasis:names:tc:xacml:1.0:resource:resource-id" Category="urn:oasis:names:tc:xacml:3.0:attribute-category:resource" DataType="http://www.w3.org/2001/XMLSchema#string" MustBePresent="true"/>
                </Match>
                <Match MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
                    <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">http://mobi.com/ontologies/policy#Create</AttributeValue>
                    <AttributeDesignator AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id" Category="urn:oasis:names:tc:xacml:3.0:attribute-category:action" DataType="http://www.w3.org/2001/XMLSchema#string" MustBePresent="true"/>
                </Match>
                <Match MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
                    <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">http://mobi.com/ontologies/ontology-editor#OntologyRecord</AttributeValue>
                    <AttributeDesignator AttributeId="http://www.w3.org/1999/02/22-rdf-syntax-ns#type" Category="urn:oasis:names:tc:xacml:3.0:attribute-category:action" DataType="http://www.w3.org/2001/XMLSchema#string" MustBePresent="true"/>
                </Match>
            </AllOf>
        </AnyOf>
    </Target>
    <Rule RuleId="urn:createOntologyRecord" Effect="Permit">
        <Target>
            <AnyOf>
                <AllOf>
                    <Match MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
                        <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">http://mobi.com/roles/user</AttributeValue>
                        <AttributeDesignator AttributeId="http://mobi.com/ontologies/user/management#hasUserRole" Category="urn:oasis:names:tc:xacml:1.0:subject-category:access-subject" DataType="http://www.w3.org/2001/XMLSchema#string" MustBePresent="true"/>
                    </Match>
                </AllOf>
            </AnyOf>
        </Target>
    </Rule>
    <Rule RuleId="urn:createOntologyRecordAdmin" Effect="Permit">
        <Target>
            <AnyOf>
                <AllOf>
                    <Match MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
                        <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">admin</AttributeValue>
                        <AttributeDesignator Category="urn:oasis:names:tc:xacml:1.0:subject-category:access-subject" AttributeId="http://mobi.com/ontologies/user/management#username" DataType="http://www.w3.org/2001/XMLSchema#string" MustBePresent="true"/>
                    </Match>
                </AllOf>
            </AnyOf>
        </Target>
    </Rule>
</Policy>

The Target of this policy matches requests where:

Any request that have these 3 criteria are evaluated against the rule section. If either rule resolves to be True, then the request’s response is a Permit as defined in the Effect field in each Rule element.

The first Rule states that the user making the request must be a user in Mobi:

The second Rule states that the user must be the admin user:

These match operator is defined by the MatchId field of the Match element. Most Mobi policies use the basic equals operator urn:oasis:names:tc:xacml:1.0:function:string-equal. See the XACML Functions section of the specification to see other possible operations.

XACML Workflow

Let’s modify our previous example to only allow the admin user to create Ontology Records by deleting the Rule with the hasUserRole section. Our new modified policy now looks like this:

<Policy xmlns="urn:oasis:names:tc:xacml:3.0:core:schema:wd-17" PolicyId="http://mobi.com/policies/ontology-creation" RuleCombiningAlgId="urn:oasis:names:tc:xacml:3.0:rule-combining-algorithm:deny-unless-permit" Version="1.0">
    <Description>Who can create an OntologyRecord in the Local Catalog?</Description>
    <Target>
        <AnyOf>
            <AllOf>
                <Match MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
                    <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">http://mobi.com/catalog-local</AttributeValue>
                    <AttributeDesignator AttributeId="urn:oasis:names:tc:xacml:1.0:resource:resource-id" Category="urn:oasis:names:tc:xacml:3.0:attribute-category:resource" DataType="http://www.w3.org/2001/XMLSchema#string" MustBePresent="true"/>
                </Match>
                <Match MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
                    <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">http://mobi.com/ontologies/policy#Create</AttributeValue>
                    <AttributeDesignator AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id" Category="urn:oasis:names:tc:xacml:3.0:attribute-category:action" DataType="http://www.w3.org/2001/XMLSchema#string" MustBePresent="true"/>
                </Match>
                <Match MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
                    <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">http://mobi.com/ontologies/ontology-editor#OntologyRecord</AttributeValue>
                    <AttributeDesignator AttributeId="http://www.w3.org/1999/02/22-rdf-syntax-ns#type" Category="urn:oasis:names:tc:xacml:3.0:attribute-category:action" DataType="http://www.w3.org/2001/XMLSchema#string" MustBePresent="true"/>
                </Match>
            </AllOf>
        </AnyOf>
    </Target>
    <Rule RuleId="urn:createOntologyRecordAdmin" Effect="Permit">
        <Target>
            <AnyOf>
                <AllOf>
                    <Match MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal">
                        <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">admin</AttributeValue>
                        <AttributeDesignator Category="urn:oasis:names:tc:xacml:1.0:subject-category:access-subject" AttributeId="http://mobi.com/ontologies/user/management#username" DataType="http://www.w3.org/2001/XMLSchema#string" MustBePresent="true"/>
                    </Match>
                </AllOf>
            </AnyOf>
        </Target>
    </Rule>
</Policy>

The following request is for a user that is not the admin user and is attempting to create an Ontology Record:

Let’s now go through the typical XACML workflow from request to evaluation to response.

  1. A REST request is made to a Mobi endpoint where the request is intercepted by the Policy Enforcement Point

    • Relevant user information is extracted from the request

    • Action and Resource information is extracted from the targeted endpoint

      • These are defined by Java Annotations on the endpoints in the Mobi source code.

  2. A XACML request is generated from the data extracted from the REST request.

  3. The XACML request is then passed along to the Policy Decision Point

  4. The Policy Decision Point reaches out to the Policy Information Point and Policy Retrieval Point to retrieve additional attributes and relevant policies to evaluate against.

  5. The Policy Decision Point evaluates the request against any relevant policies. In this case it is our policy listed above.

  6. The Policy Decision Point sees that the User making the request is batman and not admin. Using a deny unless permit model the Policy Decision Point returns Deny as the response to the request.

  7. The Policy Enforcement Point propagates this Deny out, never actually entering the code for the REST request, and returns a 401 Unauthorized error to the system making the REST request.

Mobi Policies

Mobi System Policies

Mobi stores default system policies in the ${karaf.etc}/policies/systemPolicies directory. Custom XACML system policies should be added to this directory. On initial startup these policies are loaded into the Repository and Virtual Filesystem.

Warning
Any edits made to these policies after initial system startup will not be applied unless a mobi:reload-system-policy command is run from the Karaf terminal.

Reload System Policy Command

A helper utility exists in the Karaf terminal for reloading manually edited system policies. The command take a path to a system policy.

Note
System policy file names must be a URI Encoding of the Policy IRI.
karaf@mobi()> mobi:reload-system-policy --help
DESCRIPTION
        mobi:reload-system-policy

	Reloads a system policy in Mobi

SYNTAX
        mobi:reload-system-policy [PolicyFilePath]

ARGUMENTS
        PolicyFilePath
                The path to the system policy file

This command will replace existing system policies with the policy file provided as an argument

Mobi Policy Templates

Mobi makes use of policy templates for generating default policies for different Record Types. There are two main record policy template types:

  • Record Policy: A policy for managing the READ/DELETE/MODIFY permissions of a Record

  • Policy Policy: A policy for managing the Record Policy and adjusting who can edit the permissions of a Record Policy

The following policy templates can be found in the ${karaf.etc}/policies/policyTemplates directory with their system defaults:

  • datasetRecordPolicy.xml: Default policy template for Dataset Records

    • Read Permissions: Any user with the User role

    • Delete Permissions: The user who created the Record

    • Update/Manage Permissions: The user who created the Record

    • Modify Permissions: Any user with the User role

  • mappingRecordPolicy.xml: Default policy template for Mapping Records

    • Read Permissions: Any user with the User role

    • Delete Permissions: Any user with the User role

    • Update/Manage Permissions: The user who created the Record

    • Modify Permissions: Any user with the User role

    • Modify Master Branch: Any user with the User role

  • recordPolicy.xml: Default policy template for Versioned RDF Records (Ontology Records and Shapes Graph Records)

    • Read Permissions: Any user with the User role

    • Delete Permissions: The user who created the Record

    • Update/Manage Permissions: The user who created the Record

    • Modify Permissions: Any user with the User role

    • Modify Master Branch: The user who created the Record

  • policyPolicy.xml: The default policy template for managing access control for a Record. This policy is tied to each type of Record and is associated with the Update Permission for the Record. If the User has the Update Permission, then they can also change who else can Read/Delete/Manage/Modify a given Record.

    • Read Permissions: The user who created the Record

    • Update/Manage Permissions: The user who created the Record

These default policy templates for Records can be manually adjusted in the filesystem to reflect any organization specific need for access control for Records. The templates use a few tokens to do string replacement on when processed by the Mobi Record Services on creation. These tokens are:

  • %RECORDIRI%: The IRI of the created Record

  • %USERIRI%: The IRI of the User creating the Record

  • %POLICYIRI%: The IRI of the Record Policy - this is used by the policyPolicy.xml for managing who can adjust permissions for a given Record

  • %MASTER%: The IRI of the Master branch if it is a Versioned RDF Record

Note
Unlike System Policies, these policies do not need to be reloaded after editing. They are picked up by the Mobi Record Services when a user creates a new Record.