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

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

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.

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.

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.

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.

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)

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.

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.

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

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

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.

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.

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.

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 [Ontology Managing] though the same permission handling applies to other types of Versioned RDF Records as well). 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.

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

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

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 box appears containing the titles of all class mappings of the appropriate types along with an option to create a new class mapping.

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

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.

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

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

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 Licensing tab available in enterprise installations 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 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.

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

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

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

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

Dagu is a free and open source workflow engine that defines executions as Directed Acrylic Graphs (or DAGs) and supports interaction with Mobi via REST. To utilize Dagu in executing Workflows, you will need to install the software, and then configure Mobi’s connection to Dagu.

Install Dagu according to their installation instructions. Mobi supports interaction with Dagu both locally (i.e., on the same server) or remotely. The following table describes the recommended Dagu installation method based on the OS of the system Mobi is installed on and the desired Dagu location.

To configure Mobi’s connection to Dagu, create a file called com.mobi.workflows.impl.dagu.DaguWorkflowEngine.cfg with the following properties and put it in the $MOBI_HOME/etc/ directory.

An example file would look like this.

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 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 uses SHACL to define constraints on the attributes of the new Triggers/Actions and to describe how these attributes should be set in the UI.

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:

The publish framework has a generic endpoint as the entrypoint for all publish activities. The endpoint is a POST endpoint that takes the ontology/vocabulary recordId and an optional commitId to publish as query params. The body of the request is a JSON-LD model, jsonModel, that defines the inputs for the publish as defined by the publish service configuration.

Below is an example request to publish a record to a configured GraphDB instance:

The body of the request represented in turtle is:

This request is for a publish of the ontology record https://mobi.com/records#607850ec-86fe-4e17-b47c-36765b946fbb at the HEAD commit (since the commitId query param is omitted). The body of the request defines what publish service type to execute and the inputs for the associated publish service. See comments in turtle for explanation of fields.