Workbench

The Workbench is the web-based administration interface to the Ontotext Platform. Its layout consists of two main areas. The navigation area on the left-hand side of the screen contains a menu with its main functionalities: Schemas, Playground, Monitoring, GraphQL, Search, and Documentation. The work area shows the tasks associated with the selected functionality.

../_images/platform_workbench1.png

Quick Start

This docker-compose.yaml can be used to start the Workbench application.

To deploy the docker-compose.yaml, execute the following shell command:

docker-compose up -d

After deploying, to access the Workbench application, open http://localhost:9993 in your browser.

Note

Update SOAAS_ENDPOINT to point to your Semantic Objects Service address. Add or update SEARCH_ENDPOINT to point to your Platform Search Service address.

Home Screen Widgets

The home screen contains widgets with information about the active schema, a list of all available schemas, as well as the Platform license details.

Active Schema Widget

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

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

Set Up License

The Ontotext Platform is available under a commercial time-based license, so you need to first set one up. To purchase a license or obtain a copy for evaluation, please contact our sales or marketing teams.

You can upload the .license file stored on your local machine via the respective buttons in the home screen, as well as from any screen by using the button in the top right.

../_images/workbench-set-license.png

A dialog box will ask you to confirm the following license details:

  • Licensed to
  • Valid until
  • Maintenance date
  • License purpose

If you cancel the upload, you will remain in the home screen.

Schemas

Schema Registry

The Schemas tab in the main menu enables you to view and manage all schemas that are uploaded or created in the Platform. 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
../_images/workbench-schema-registry.png

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:

../_images/workbench-manage-schema.png

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)
../_images/workbench-data-validation-widget.png

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 Platform 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.
../_images/workbench-upload-ontology.png

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

../_images/workbench-generate-schema.png

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 Platform 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 Platform 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 Platform Search Service is deployed and the endpoint is configured in the Workbench, then SOML validation will be executed in the SOaaS and the Search Service. 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.

../_images/workbench-save-schema.png

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

../_images/workbench-activate-schema.png

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

../_images/workbench-complete-create-wizard.png

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.

../_images/workbench-create-schema.png

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

Select Schema

Another way to generate a schema in the Platform is to upload one that you already have.

This can be done in several ways:

  • from the home page –> Upload Schema
  • from Schema Registry ‣ Upload Schema
  • from the Schema Registry where in the Actions column, there is an Upload button for each schema in the list
  • from Manage Schema ‣ Upload Schema

As always, the progress of process will be shown in the bar at the top of the page.

Select the schema file you want to upload (as above, .yaml and .yml formats are supported). You will be notified if the upload has been successful, or there is an issue with it.

If you try to upload a schema whose ID already exists on the server, the Workbench will notify you that if you proceed, the upload will override that schema.

To Proceed to the next step, create/update the schema (depending on whether you are uploading a new schema, or updating an already existing one).

You can also reject the upload, which will take you back to the starting screen of the process.

If you want to Delete the schema, you will be asked to replace it with a new one.

As always, if you want to navigate away from this screen, a message will warn you that leaving the page will cause the Upload Schema Wizard progress will be lost.

Save Schema

You can also Edit the uploaded schema – pressing this button will open it in the Playground. There, you can execute all of the already described actions supported by the Playground, such as syntax check, validation, and error detection.

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

Warning

If you want to go one step back in the wizard, all the changes that you have made in the schema will be lost as well.

Once you are finished with the modifications of the schema, you can now save it in the Platform. If you have uploaded a new schema, the button for it will be Create, and if you have uploaded a new version of an already existing schema, the button will be Update.

If a schema with the same ID is currently active, a notification message will ask you whether you want to overwrite it or cancel the operation.

Activate Schema

Now that your schema has been saved, you can preview its details and proceed with the activation.

If the newly created/updated schema is not active, you can Activate it or Skip the activation and proceed to the completion of the process.

If the schema is already active, you will be able to directly proceed to finalizing the process. (the activation button will be inactive)

You can also Edit the currently saved schema by pressing the button that will open it in the Playground.

Complete Upload Schema Wizard

Completing the activation step will take you to the Schema Registry where the newly created/updated schema is now visible in the schema list.

As indicated in the progress bar, this completes our Schema Upload process.

Playground

The Platform Playground is the web-based code editor enabling you to edit/update, validate, and download your schema. You can open it from the main menu.

../_images/workbench-playground.png

Select the schema you want to work with from the drop-down menu with all available schemas.

You can use the following shortcuts when editing the schema:

  • Ctrl / Cmd+F: search the schema content
  • Ctrl+Shift+F / Cmd+Option+F: replace
  • Ctrl / Cmd+Z: undo
  • Ctrl / Cmd+Y: redo

Besides editing, here you can also perform a syntax check of the schema in order to validate it. 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 the editor. For example, if we misspell specialPrefixes as specialprefixes, the Schema validation errors field will display the following:

../_images/workbench-schema-validation-error.png

You will be able to validate the schema only if its syntax is correct (otherwise the Validate button will be inactive).

Warning

If you have made changes to the schema content and want to navigate away from this screen, the Playground will ask you to confirm first, as this would cause the changes to be lost.

Once you have finished all edits and modifications to your schema, you can save it and proceed to the next step (if this is a part of a create/generate schema workflow).

Warning

Proceed with caution when saving an active schema, as this will automatically update the GraphQL endpoint. Depending on the changes, queries and mutations from applications may start to malfunction.

GraphQL

The Workbench integrates the GraphiQL in-browser tool for writing, validating, and testing GraphQL queries. In it, you can:

  • perform GraphQL queries and mutations for the currently active in SOaaS or Search Service SOML schema
  • switch between available GraphQL endpoints: SOaaS or Search Service if configured
  • see the query response or errors
  • see previously executed queries
  • explore the active GraphQL SDL (schema definition language)

Type your query in the left side of the screen, and you will see intelligent typeaheads aware of the current GraphQL type schema and live syntax and validation errors highlighted within the text.

The GraphiQL Explorer plugin, which is integrated in the tool, enables you to construct correct GraphQL queries and mutations faster and more easily. Clicking the Explorer button will open a panel on the left where you can explore and construct queries/mutations.

See more about it in the official GraphiQL Explorer documentation, as well as in this OneGraph blog post on the subject.

../_images/workbench-graphql.png

RBAC permissions are as follows:

Permission Action
read execute queries
write execute mutations
delete execute delete mutations
no permissions only view the Documentation section in GraphiQL

Security

Login

When the security of the Platform 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 Platform 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:

Action Description
"*/*" Read/write/delete/bind access to all schemas
"*/read" Read access to all schemas
"*/write" Write access to all schemas
"*/delete" Delete access to all schemas
"*/bind" Activate all schemas
“swapi*/read" Read access to all schemas starting with SWAPI

Possible notActions are:

notAction Description
"*/*" No read/write/delete/bind access to any schema
"*/read" No read access to any schema
"*/write" No write access to any schema
"*/delete" No delete access to any schema
"*/bind" No activate access to any schema
“swapi*/read" No read access to any schema starting with SWAPI

Warning

NotActions take precedence over Actions.

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.

Monitoring

SOaaS Health Status

The Monitoring section of the Workbench menu provides an overview of the current health status of the Semantic Objects Service. 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 SOaaS 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

Administration

The Workbench application reads the following configurations from the environment:

  • EXPRESS_PORT: port of the Express server that is serving the Workbench application. Default value is 3001.
  • SOAAS_ENDPOINT: URL to the Semantic Objects Service. Default value is http://localhost:9995.
  • SEARCH_ENDPOINT: URL to the Search Service. This should be configured only if the service is deployed. When the Search Service is configured, the Workbench will execute SOML validation in that service too. Default value is undefined.
  • GRAPHQL_ENDPOINT: URL to the /graphql endpoint to use for querying. Used when it differs from SOAAS_ENDPOINT, for example when the federation is enabled and requests should go through Apollo Gateway. Default value is undefined.
  • CONTEXT_PATH: Configures the Workbench to be accessible behind a sub-path, i.e., /workbench. Used when deployed behind a reverse proxy. Default value is /, meaning it is not behind a sub-path.
  • SECURITY_ENABLED: Configures the Workbench to be secured. Default value is false.
  • OAUTH_PUBLIC_ENDPOINT: public URL to an OAuth provider. Used when security is enabled. Default value is http://localhost:9011/oauth2.
  • OAUTH_ENDPOINT: URL to an OAuth provider services. Used when the authentication should not go via public URLs. Used when security is enabled. Default value is the one configured by OAUTH_PUBLIC_ENDPOINT.
  • OAUTH_REDIRECT: URL to which the OAuth provider will redirect back to the Workbench application. This should be a URL accessible by the provider. Used when security is enabled. Default value is http://localhost:3000/.
  • CLIENT_ID: UUID of the OAuth application client. Used when security is enabled.
  • CLIENT_SECRET: a secret used during OAuth authentication with refresh token grant. Used when security is enabled.
  • TENANT_ID: UUID of the OAuth application tenant. Used when security is enabled.