Workbench¶

Active Schema Widget¶

This widget provides the following information about the currently active schema in the Semantic Objects:

• metadata: the schema ID, label, creator, date of creation, date of last update, and version information
• information: the schema objects, properties, and roles
• dataset statistics: the elements in the schema dataset
• data validation status (displayed only if the schema has been validated against the dataset): status of the data validation report, its dates of creation/completion, and number of validation tasks found

The Open button will open the schema in the Workbench Playground where you can edit it.

Schemas Widget¶

Here, you can see all created schemas listed with their name, status (active or not), and the date of their most recent update.

From the home screen, you can also execute the following actions:

• create a schema
• generate a schema
• upload a schema

Schema Registry¶

The Schemas tab in the main menu enables you to view and manage all schemas that are uploaded or created in the Semantic Objects. They are listed in a table with the following information about each of them:

• ID: the ID of the schema

• label: the schema label (if one exists)

• active: a flag that shows if the schema is activated

• updated: last update of the schema

• created: date of schema creation

• creator: creator of the schema

• objects: the number of objects defined in the schema

• properties: the number of properties defined in the schema

• actions: a list of actions that can be executed directly from here:

  • edit: opens the schema in the Playground
  • upload: starts the Upload Schema Wizard
  • download: downloads the schema in .yaml format
  • delete: deletes the schema after prompting you to confirm the deletion
  • activate: binds the schema to the service

If you want to view more details about a schema and manage it, click on the schema ID in the list. This will open it in the Manage Schema view.

In this screen, you can also Create, Generate, or Upload a schema with the buttons below the list.

Manage Schema¶

As mentioned above, you can preview and manage a schema by clicking on its ID in the Schemas list. You will be taken here:

In this view, you can:

• Open the schema: this will take you to the Playground where you can edit and update it
• Upload a new version of the schema: this will start the Upload Schema Wizard
• Download the schema: this will download a .yaml file of it
• Validate the schema against the data (described below)
• Activate the schema (if it is not active)
• Delete the schema: you can only delete an inactive schema, and will be asked to confirm the action.

In the displayed widgets, you can view the following details about the schema:

• Schema metadata

  • id
  • label
  • creator
  • created
  • updated
  • versionInfo

• Schema information

  • the number of the defined objects grouped by:

    • total number of objects
    • concrete object types
    • interfaces

  • the number of the defined properties grouped by:

    • total number of properties
    • data properties
    • object properties

If the schema is activated, you will also see a third widget displaying the schema statistics. It lists the top object types in the schema with the most instances in descending order.

You can also validate the schema against the dataset that you are working with. Clicking Validate schema against data will open a fourth widget containing information about the data validation status:

• Status of the validation report (can be Running, Done, Canceled, Failed)
• Created on (date)
• Completed on/Canceled on (date)
• The total number of tasks
• The number of info tasks (if found)
• The number of warning tasks (if found)
• The number of failed tasks (if found)

The validation process can be stopped while still in progress via the same button, which during validation is displayed as Stop data validation. Once the validation has been completed, a View report button will be visible at the bottom of the widget. Clicking it will open the schema in the Playground. Below the schema editor, you will find a detailed data validation report with three possible error types found - INFO, WARNING, and FAILED, where FAILED would mean that an error has occurred during the data validation process.

Generate Schema Wizard¶

The Semantic Objects Workbench enables you to generate a schema without the need for an external tool, so that you can expose an existing RDF dataset as a GraphQL endpoint.

Another way to do that is with the OWL2SOML tool.

You can Generate a schema from the Workbench home page or Schemas page using the respective button. This will start the Generate Schema workflow, the progress of which you can see in the progress bar at the top of the screen.

Upload Ontology¶

You can upload an ontology from a local file. To do so:

1. In the home screen, click Generate Schema. This will start the Generate Schema Wizard that will display the progress in the bar at the top of the page.
2. In the next screen, click Upload RDF files and select the file on your computer that you want to use. Any RDF format is supported.

The Workbench will notify you if the ontology has been successfully uploaded, or there is an issue with it. You can upload multiple ontologies, as well as delete them if you wish so.

You need to have at least one uploaded ontology in order to be able to Proceed to the next step.

If you want to navigate away from this screen, the Workbench will again ask you to confirm first, as this would cause the Generate Schema Wizard progress to be lost.

Generate Schema¶

After having uploaded your ontologies into the Semantic Objects, you can now proceed to the schema generation.

Select the ontology/ies that you want to use from the list on the left side of the Select Ontologies section and transfer them to the right. They can also be de-selected.

Note

The first ontology that you select from the list will be the “main” ontology, from which the schema will obtain the voc prefix.

The right section of the screen shows the Parameters that can be configured for the schema being generated. Hovering over the info icon next to each of them will show you a tooltip with the parameter’s description. The parameters are as follows:

• Vocabulary prefix: specifies a vocPfx for the SOML. The namespace for this prefix needs to be declared in one of the ontology files. If not specified explicitly, one will be extracted automatically. Setting it to NONE will set a default namespace http://example.com/. Use this option if there is no main ontology defined.

• Schema ID: specifies an ID for the SOML. Optional unless vocPfx is set to NONE.

• Label: specifies a label for the SOML. To be used only with the Schema ID parameter. Otherwise, the label will be automatically extracted from the main ontology.

• String mode: controls the way of emitting string-related datatypes as follows:

  Datatype	stringOrLangString (default)	langString	string
  rdf:LangString	langString	langString	string
  rdf:PlainLiteral, rdfs:Literal, schema:Text, undefined	stringOrLangString	langString	string
  xsd:String	string	string	string

• Default langString configurations: group contains parameters that generate default values for the langString configuration used in the schema. It is optional and can be skipped, or the values can also be added later in the config section of the schema. When the String mode is set to String, configuration for this parameter is disabled.

  Supported formats:

  • Set fetch/validate/implicit using key value format, e.g.: fetch: en~,de,ANY, validate: en~,de~,fr~, implicit: en-GB

  Configurations meaning:

  • Fetch: restricts the returned languages in the preferred order. Obtains the first value according to the order, or all matching values.
  • Validate: validates values during create/update (mutation) to restrict certain languages or ensure uniqueness per language.
  • Implicit: allows to omit the language tag on mutation.

Once you are done with this configuration, you are ready to generate the schema that will be based on it. (Note that if no ontology is selected, the Generate button will be inactive.)

From here, it is also possible to return to the previous step and upload new ontologies.

If you want to navigate away from this screen, the Workbench will again ask you to confirm first, as this would cause the Generate Schema Wizard progress to be lost.

Save Schema¶

Once you are done with the configuration of the schema, press Generate to go to the next screen. The progress will be shown in the bar at the top where the previous steps will be marked as done.

The newly generated schema will be opened in the Semantic Objects Playground. Here, you can edit its content, as well as perform a syntax check in order to validate the schema. The Playground will execute a dry run generation of a GraphQL schema, and display any errors and warnings that it detects in the collapsible section below.

If the Ontotext Semantic Search is deployed and the endpoint is configured in the Workbench, then SOML validation will be executed in the Semantic Objects and the Semantic Search. If there are validation errors or warnings in any of the services, they will be merged and displayed. You will be able to validate the schema only if its syntax is correct.

If you want to re-generate the schema, you can do so by going back to the previous step.

Note

Keep in mind that this will cause the Generate Schema Wizard progress to be lost, so the Workbench will ask you to confirm the action first. The same applies for navigating away from this screen in general.

After finalizing the editing and validation of the schema, you can now Save it and continue to the next step.

If a schema with the same ID already exists on the server, the Workbench will prompt you to choose whether to overwrite the current schema or cancel the save operation.

Activate Schema¶

In the progress bar, you can see that the schema has been generated and saved, and is now ready for activation. You can preview its details, activate it, and proceed to the next step. It is also possible to skip the activation and proceed nonetheless.

Note

You can also Edit the current saved schema. This will open it in the Playground, but you will be asked to confirm first, as that would cause the Generate Schema Wizard progress to be lost.

This concludes the Generate Schema process.

Complete Generate Schema Wizard¶

After activating the schema, you will be taken to the final step of the wizard – the Schema Registry where you can now see the newly generated schema, as well as all other available schemas in the Semantic Objects.

As displayed in the progress bar, this completes our schema generation stage.

Create Schema¶

You can also create a new schema from the Create button in the home screen, as well as from that in the Schema Registry view. It will open a new schema template in the Playground.

Here, you can:

• add, edit, and delete values
• validate the new schema: errors and warnings will be displayed in the Errors field below
• paste a schema and replace the existing one

If you try to navigate away from the screen, a message will warn you that the changes you have made will be lost.

After the editing, you can save the schema to the server. Saving also starts the validation process, and the schema will only be saved if it has been validated successfully. If there is an issue with it, errors and warnings will be displayed in the Errors field.

The Semantic Objects will also validate that a schema with the same ID does not exist. In case one exists, a message will warn you that if you proceed, the schema will be updated.

Once you have saved your schema, you will be taken to the Manage Schema page where you can view and manage it.

Upload Schema Wizard¶

Login¶

When the security of the Semantic Objects is ON, you will need to log in to the Workbench with your username and password credentials.

If you attempt to log out and have unsaved work, the Workbench will notify you of it.

Apply Security¶

The functionalities of the Workbench can be accessed depending on the user role actions defined in the soml-rbac schema.

If you log in as a user with no defined role in the soml-rbac schema (also called default role), a message will inform you that you do not have sufficient rights to use the Workbench.

If you log in as a user with read-only rights (actions: ["/read"]), you will be able to view the content of all sections of the Workbench, but will not be able to create/edit schemas (the respective buttons will be inactive).

If you log in as a user with write-only rights (actions: ["/write"]), a message will inform you that your access to the Workbench is limited due to the assigned roles.

In all three options, you can set up a license, and access the Documentation section.

All users with roles defined in the soml-rbac schema have access to the schemas based on their role’s actions.

The possible actions are:

Possible notActions are:

The various access options will allow you the following:

• If you are logged in as a user with a defined role in the soml-rbac schema but without read permissions, you will have the same limited access as users with no defined role. The Workbench will notify you of this.

• If you are logged in as a user with read access only to specific schema(s) (e.g., “swapi*/read"), only they will be visible in the Schema Registry list, in the home screen widgets, and the drop-down menu with available schemas in the Playground.

• If you are logged in as a user with read access:

  • You will be able to: see all schemas in the Schema Registry list, in the home screen widgets, and the drop-down menu with available schemas in the Playground.
  • You will not be able to: create/generate/edit/upload/delete/activate a schema. You can still edit and validate a schema in the Playground, but will not be able to save it.

• If you are logged in as a user with write and/or bind and/or delete permissions, but without read access, you will not be able to see the schema in the Schema Registry list, in the home screen widgets, and the drop-down menu with available schemas in the Playground.

• If you are logged in as a user with read and write access, you will be able to execute all actions except for activate and delete a schema.

• If you are logged in as a user with write access and try to create/upload a schema, a notification message at the Save Schema step will inform you that you will not be able to see the schema due to restricted permissions.

• If you are logged in as a user with filtered (“swapi*/*") permissions and try to create/generate/upload a schema with an ID different from the one to which you have access, a notification message at the Save Schema step will inform you that you will not be able to see the schema due to restricted permissions.

• If you are logged in as a user with read and bind access, you will be able to execute all read actions and also activate the schema.

• If you are logged in as a user with read and delete access, you will be able to execute all read actions and also delete the schema.

Semantic Objects Health Status¶

The Monitoring section of the Workbench menu provides an overview of the current health status of the Semantic Objects. On top of it, you can see the overall health status with three possible states: OK, WARNING, and ERROR. Displayed separately below are the default Semantic Objects health checks, independently of the overall status:

• MongoDB checks
• SPARQL checks
• SOML checks
• SOML RBAC checks
• Query service
• Mutation service
• Elastic service

Each health check contains the following information:

• Name: name of the health check
• Status: OK, WARNING, ERROR
• Severity: LOW, MEDIUM, HIGH
• Impact: the health check’s impact on the system health
• Message: short information message on the health check status
• ID: unique health check identifier
• Type: type of the health check
• Description: more details about the health check
• Troubleshooting: a link to a web page providing insight on the health check status