Mobi User Manual

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

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:

or for Linux/OSX:

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

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

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, any user who has created a record, and all possible user keywords. The selected options in each filter group can be reset and all selected filter options will appear beneath the search bar. 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, last modified date, 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, a button to Open that Record in its respective module (ontologies in the Ontology Editor, etc.) and a button to View the Record card in 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 Record View displays metadata, including the publisher’s username, the creation and modification dates, and associated keywords. The view includes a Statistics section that highlights key metrics relevant to the Record, providing a quick overview of its complexity. Each statistic is accompanied by a tooltip explaining its meaning, making it easier to understand the data. The statistics displayed are specifically tailored to the type of Record you are viewing. If no statistics are available for the Record type, the section will display the message "No statistics available.". Underneath all this is 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. The Activity tab will show a list of activities associated with the Record.

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.

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.

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.

To create a new ontology, click the New button in the records dropdown. 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.

The Ontology IRI is the unique identifier for the new ontology. The editor pre-populates this field with a configurable 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. When the dialog is submitted, the new ontology will automatically be opened into the editor.

To upload an existing ontology, click the Upload button in the records dropdown. This will bring up the browser’s native file browser to select one or more files containing initial ontology data.

Once the file(s) are selected, a dialog 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 editor will set the Title to the file name. Metadata for each ontology file can be entered and submitted separately, or default metadata can be entered for all records using the Submit All button. 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 status of each upload is recorded in the Upload Log which can be opened by clicking the button next to the records dropdown. Any errors will be detailed for each file. 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.

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

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

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.

Just like the shapes graphs, each ontology in Mobi is versioned similarly to the Git Version Control System, whereby all changes to an ontology are collected into a chain of "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 exist 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.

To create a shapes graph, click the New button in the records dropdown. The creation dialog requires a title for the record and an IRI for the shapes graph. You can also optionally a description and keywords which will be used to describe the Shapes Graph Record in the local catalog.

Shapes graphs in Mobi will always include an OWL ontology object to capture high level information about the shapes graph, following best practices from the SHACL W3C specification (see this section as an example).

The Shapes Graph IRI is the unique identifier for the new shapes graph. 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 Shapes Graph Record and the ontology object within the new record. The Description field populates the dcterms:description annotations of both the new Shapes Graph Record and the ontology object within the new record. The Keywords field will attach the entered values as keywords to the new Shapes Graph Record. When the dialog is submitted, the new shapes graph will automatically be opened into the editor.

To upload an existing shapes graph, click the Upload button in the records dropdown. This will bring up the browser’s native file browser to select one or more files containing initial shapes graph data (accepts all standard RDF formats).

Once the file(s) are selected, a dialog will prompt you for metadata entry for the Shapes Graph Record (title, description, keywords). This metadata is used to describe the shapes graph in the local catalog. By default, the editor will set the Title to the file name. Metadata for each shapes graph file can be entered and submitted separately, or default metadata can be entered for all records using the Submit All button. The Title field populates the dcterms:title annotation of the new Shapes Graph Record. The Description field populates the dcterms:description annotation of the new Shapes Graph Record. The Keywords field will attach the entered values as keywords to the new Shapes Graph Record.

The status of each upload is recorded in the Upload Log which can be opened by clicking the button next to the records dropdown. Any errors will be detailed for each file. 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.

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

Just like ontologies, 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.

Mobi Enterprise comes with a publish service for pushing ontologies, vocabularies, and shapes graphs to an external GraphDB instance. This publish service will publish the HEAD of the MASTER branch of the selected Ontology or Shapes Graph Record into a remote GraphDB repository. The service allows you to specify which configured GraphDB instance to publish to. By default, the service will put the data into named graph of the ontology/shapes graph IRI unless a different named graph is specified. The service provides a toggle for overwriting the existing published data in the named graph if it exists in GraphDB or appending the published data to a graph with pre-existing data.

After selecting the target GraphDB instance and repository (and optionally a target named graph), click Submit, and Mobi Enterprise will publish the data to the external system.

Mobi Enterprise comes with three publish services for pushing ontologies, vocabularies, and shapes graphs to an external Anzo instance’s Catalog. All of these publish service will allow you to specify which configured Anzo instance to publish to.

The "Publish to Anzo as SKOS Concepts" service allows Mobi users to select whether to publish the concept hierarchy, the class hierarchy or both as SKOS vocabulary concepts.

The "Publish to Anzo as OWL Dataset/Model" service allows Mobi users to publish the entire contents of an Ontology Record to either an Anzo model or dataset.

The "Publish Shapes Graph to Anzo" service allows Mobi users to create an Anzo dataset containing their shapes graph data for use in validation logic within Graphmarts.

After selecting either the entity types or target location, click Submit, and Mobi Enterprise will push the ontology/vocabulary/shapes graph data to Anzo.

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 to attached to the new request by searching within the displayed paginated list of records. All types of Versioned RDF Records are supported by the tool. This currently includes: Ontology Records, Shapes Graph Records, Mapping Records, and Workflow Records. Once you have selected a record, click Next.

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.

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.

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 Record Permissions). 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 and Shapes Editor, except that the resolution will become a commit on the source branch.

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 and governance tracking.

A merge request can be closed so that the history of the proposed changes and the discussion can be kept, but the merge will not be performed. Users can still make comments on a closed merge request, but it cannot be edited. A closed merge request can be reopened as long as the source and target branches on the request still exist.

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.

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

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

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. The list of properties from the imports closure is determined by searching for properties that meet the following criteria.

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. If a property has more than one rdfs:range value, the datatype override box will be displayed and you must select which type the generated values must be. 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 field appears containing the titles of all class mappings of the appropriate type along with an option to create a new class mapping. The list of class mappings displayed is determined by the rdfs:range that is set on the selected property and its super-properties. If no range has been set on the property or there is a range of owl:Thing a full list of class mappings becomes available alongside the ability to create a new class mapping with all classes within the imports closure being an option.

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.

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 and giving you the option to continue and have the tool automatically remove incompatible mappings. If you continue or the check 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.

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 and giving you the option to continue and have the tool automatically remove incompatible mappings. If you continue or the check 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.

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 and giving you the option to continue and have the tool automatically remove incompatible mappings. If you continue or the check 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 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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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

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.

To create a new workflow, click the New button above the table. The creation dialog requires a title for the record and an IRI for the Workflow object itself. You can also optionally provide a description and keywords which will be used to describe the workflow record in the local catalog.

The Workflow IRI is the unique identifier for the new workflow. 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 workflow record and the workflow object within the new workflow. The Description field populates the dcterms:description annotations of both the new workflow record and the workflow object within the new workflow. The Keywords field will attach the entered values as keywords to the new workflow record. When the dialog is submitted, the new workflow will automatically be opened into the Individual Workflow Page. New workflows are always initialized with no trigger and a single Test Action with a templated message.

In addition to creating a new workflow from scratch, you can upload an existing conformant workflow definition (see the Workflows Appendix for a valid structure). To do so, click the Upload button above the table. This will bring up the browser’s native file browser ot select a file containing a workflow definition (accepts all standard RDF formats).

Once the file is selected, a dialog will prompt you for metadata entry for the workflow record (title, description, keywords). This metadata is used to describe the workflow in the local catalog. By default, the editor will set the Title to the file name. The Title field populates the dcterms:title annotation of the new workflow record. The Description field populates the dcterms:description annotation of the new workflow record. The Keywords field will attach the entered values as keywords to the new workflow record.

The Individual Workflow page will display all metadata about the workflow record along with the full execution history, the commit history, and a visualization of the workflow components that can be expanded to fill the entire screen. The page also includes the same active status toggle and buttons to run, delete, and download the workflow as on the Workflows landing page. If the page is in edit mode (see Editing Workflows), the download button will include any in progress changes made to the workflow.

The graphical display of the Workflow will display the Trigger, if set, as a yellow square and all configured Actions as green circles. Every workflow can have at most one Trigger and must have at least one Action. If a Trigger has not been configured for the workflow, "Default Trigger" will be displayed on the Trigger node. The nodes will display the configured title or type of the Trigger/Action and clicking on a node will bring up a summary of the configuration for the component.

The Workflow Execution History is presented in a filterable, paginated table with the latest executions displayed at the beginning. Each execution is displayed with its status, user who started the execution, start time, and running time and each row can be expanded to provide further details about each Action that was executed during the run. Each execution also has a button to open a page to view the detailed logs output by that run. The page will display metadata about the execution you are viewing along with a dropdown selector to load the overall execution logs or the logs output from an individual action. Each log file can also be downloaded for further investigation.

To update the configuration of an individual workflow, open the Individual Workflow Page and click on the pencil icon in the top right corner of the graphical display as long as the workflow is not currently running. This sets the Individual Workflow Page into edit mode where the execution history and overall metadata is still visible, but the workflow active status cannot be toggled and the workflow cannot be run or deleted. In edit mode, the graphical display will contain buttons to upload a new version of the workflow as a file and have the system determine the changes and a button to save all changes made so far. If changes have been made, the graphical display will also contain an info message stating as such.

In edit mode, the nodes and edges in the graphical display will have a menu that can be opened with a right click and hold so that each component can edited individually. The Trigger node menu will provide the options to remove any existing Trigger configuration (trash icon), to add/edit the Trigger configuration (pencil icon), or to add a new entry Action (plus icon). The Action node menu will provide the options to remove the Action configuration, edit the Action configuration, or add a new child Action. The edge menu will provide the option to remove the edge between nodes. To draw a new edge between nodes, click and drag from one node to another.

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.

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.

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.

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

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

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.

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

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.

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 dropdown selector of all the users in Mobi that have not already been selected. Selecting a user in this dropdown 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 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 dropdown 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.

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.

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

The Publish Configuration tab available in Enterprise only allows you to manage connections to external systems to be utilized within the Publishing Tool. This view is based on an extensible framework for introducing new types of external systems with their own unique requirements and supports multiples connections for each type. By default, Mobi Enterprise supports connections to Anzo and GraphDB systems. The left side of the tab displays the list of all configurations grouped by the type of external systems along with a button to create a new configuration. Every publish configuration is uniquely identified by its type and ID.

The modal to create a new publish configuration will first display a select field with all registered types of publish configurations. Once an external system is selected, the modal will populate with all configuration options for that type of external system along with a button to test the connection to the external system before the configuration is saved.

Clicking on a configuration in the left hand list will display all settings on the right side of the tab in an editable form. Each field is displayed with an information tooltip describing the purpose of the value. Any sensitive fields will be masked with dots and to update the value, the existing value must be cleared. Buttons to test the connection to the external system, save the updated form, and delete the configuration are at the bottom of the form.

The Licensing tab available in Enterprise only allows you to view and update the current license of the server (see the section on adding a license file). The values displayed are pulled from the current license file contents on the installation server and any updates made will be persisted back to that file. The page displays the unique Server ID of the installation, the Owner of the license, the expiration date of the license, the policy attached to the license metadata (older licenses may not have this set), and the full license string that is stored within the license file. To update the license contents, click the pencil button shown on hover, replace the field contents with the complete new license string, and click the save icon.

The "LDAP/SSO" tab available in Enterprise only provides a clear view of your current LDAP/SSO configurations, allowing you to easily review the settings used by the application for authentication. The values displayed are pulled from the configuration file contents on the installation server and any updates made will be persisted back to those files. If a configuration is not set, the left hand link will be italicized.

If an LDAP configuration is set using the associated form, users can log into the application with the Users/Groups defined in your organization’s directory. The form also allows you to remove the configuration. The changes will immediately go into effect once the form is saved/cleared.

The LDAP form is separated into two sections. The "Connection" section contains the following fields:

The "Data Retrieval" section contains the following fields:

In addition, 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 SSO is configured with LDAP, it is recommended to disable direct authentication against the LDAP directory by checking the "Disable Authentication" box in the LDAP form. Mobi supports SAML, OAuth 2.0, and OpenID SSO providers.

The SAML form provides options to customize the connection from Mobi, acting as a Service Provider (SP), to a SAML Identity Property (IdP) and how to pull various user details out of the SAML responses. The form also allows you to remove the configuration. The changes will immediately go into effect once the form is saved/cleared.

The SAML form contains the following fields:

The OAuth/OpenID form provides options to customize the connection from Mobi to either a generic OAuth 2.0 Provider or an OpenID provider. The form also allows you to remove the configuration. The changes will immediately go into effect once the form is saved/cleared. Certain fields are the same between both OAuth and OpenID configurations and others that are unique to one vs. the other. The form contains a radio button to allow you to specify which type of provider is configured.

The OAuth/OpenID form contains the following fields for both types of providers:

If the form is set to OAuth, the following fields are displayed:

If the form is set to OpenID, the following fields are displayed:

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

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.

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.

The table below provides a summary of the software requirements.

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

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

All Mobi prepackaged bundles, services, and required artifacts and dependencies will be automatically deployed by the runtime once started. The Mobi web application should now be accessible at https://localhost:8443/avm/index.html (or substitute localhost with the hostname/IP address of the machine running the process dependant on firewall configurations). The default login credentials are admin:admin.

To stop the Mobi server, run the following command:

In addition to the steps below, Mobi supports a number of configurations to customize your installation and users' experience. See the Mobi Configurations section for more details.

Mobi 4.0 introduced a number of breaking changes from prior versions that also include a few notable configuration changes. The basic steps for upgrading must still be followed, but the following items should be taken note:

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:

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

The wf:ToggleInput type will create a Material Design toggle input. This is meant to be used for boolean property values. Below are the supported SHACL constraints.

An example sh:PropertyShape for this input type is shown below.

The wf:TextInput type will create a standard text input. This is meant to be used for short textual or numeric property values. Below are the supported SHACL constraints.

An example sh:PropertyShape for this input type is shown below.

The wf:TextareaInput type will create a standard textarea input. This is meant to be used for long textual property values. Below are the supported SHACL constraints.

An example sh:PropertyShape for this input type is shown below.

The wf:CheckboxInput type will create a collection of checkboxes with assigned values. This is meant to be used for selecting one or more values for a property based a configured list of valid values. Below are the supported SHACL constraints.

An example sh:PropertyShape for this input type is shown below.

The wf:RadioInput type will create a collection of radio buttons with assigned values. This is meant to be used for selecting one value from a configured list of valid values. Below are the supported SHACL constraints.

An example sh:PropertyShape for this input type is shown below.

The wf:DropdownInput type will create a select field with a specified list of values. This is meant to be used for selecting one value from a configured list of valid values, especially a long list of values. Below are the supported SHACL constraints.

An example sh:PropertyShape for this input type is shown below.

The wf:AutocompleteInput type will create a Material Design autocomplete field. This is meant to be used for selecting one value from a variable list of valid values that is dynamically retrieved from the system repository. Below are the supported SHACL constraints.

An example sh:PropertyShape for this input type is shown below.

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.

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.

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.

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.

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.

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.

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.

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:

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.

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.

Example:

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:

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

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.

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:

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.

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.

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

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

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

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

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:

The most common patterns utilized within the rules of the policy templates are described below. Pay close attention to the values on the AttributeDesignator element as they will change for each case.

Every Workflow RDF definition must have exactly one w:Workflow object with a unique subject IRI. This object is used to hold top level metadata about the Workflow’s execution as well as links to the optional w:Trigger used to initiate executions and the list of w:Action definitions to conduct when the Workflow executes. It can have a max of 1 value for w:hasTrigger and must have a minimum of one value for w:hasAction.

Instances of w:Trigger specify configuration details for how an execution of the Workflow can be initiated by the system outside of manual user interaction. If a workflow execution should be initiated based off an event occurring elsewhere in the platform, there is a specific subtype of w:Trigger called w:EventTrigger which provides additional functionality in the Java OSGi services side. This is one of the areas of extensibility of the framework where custom subtypes of w:Trigger can be loaded into the platform and made available to the core framework.

The "out of the box" supported w:Trigger types are described below.

Instances of w:Action describe what a Workflow should do when it is executed. These are sequentially executed. Logs are stored from the execution of each individual action in addition to the overall workflow logs. This is one of the areas of extensibility of the framework where custom subtypes of w:Action can be loaded into the platform and made available to the core framework. The exact implementation of each of these Actions is dependant on the chosen underlying Workflow Engine.

The "out of the box" supported w:Action types are described below.

To create a workflow, follow the steps below.

When a Workflow Record is first created, it is inactive to start, meaning that even manually initiating an execution will not succeed. This is done to ensure that all required edits to the Workflow can be performed without fear of it executing before the changes are complete. To activate a Workflow and enable it to run, you will need to update the Workflow Record metadata following the steps below.

Workflows are managed by Workflow Records, which are types of Versioned RDF Records. This means that all changes to the definition of the Workflow must go through the standard graph-versioning flow in order for the changes to be recognized by the system. Thus, to update the definition of a Workflow, you will need to first create an In Progress Commit with the changes and then commit those changes to the MASTER branch. This can be done by either uploading a new version of the workflow as a file or manually creating an in progress commit with the added and deleted triples. Regardless of which option you choose, you will need to follow steps similar to those below.

Workflows can be configured with automated triggers that will initiate executions, but a Workflow can always be triggered manually following the steps below.

As Workflows are executed, provenance is tracked for each execution along with logs with more details about the complete workflow execution and each individual action. The RDF structure of this data can be summarized in the image below, with the key classes described underneath.

This can all be retrieved via various REST endpoints provided by the platform. Common scenarios are described below with the appropriate REST endpoints.

In order to introduce a new w:Trigger or w:Action to Mobi, a developer must create an RDF representation of the Trigger/Action they want to add. The Workflows framework is built on top of the SHACL Web Forms Framework so that new trigger and action types will generate appropriate forms within the Workflows module.

A full example of a w:Trigger and w:Action definition is shown below.

In order to load a new Trigger or Action into Mobi, there are four steps: