Migration Guide¶
What’s in this document?
To migrate breaking changes and deprecations introduced during the various releases of the Ontotext Metadata Studio, please follow the guide below.
Ontotext Metadata Studio 3.4.0 to 3.5.0¶
Migration to GraphDB 10.3.2 is required to run OMDS 3.5.0. The exact steps to migrating your existing GraphDB instance to GraphDB 10.3.2 depend on the your specific setup.
Hint
More details on GraphDB Migration configurations are available in GraphDB 10.3 documentation.
Migration steps¶
Migration when using Docker images:
- Migrate your GraphDB instance.
- Update
sparql.endpoint.address
property in Metadata Studio Service according to your migrated GraphDB instance. - Update Metadata Studio Service and Metadata Studio Web versions to 3.5.0 update the environment.
Hint
Internal GraphDB address could be: http://graphdb-proxy:7200 when deployed in cluster or http://graphdb-node:7200 otherwise.
Migration when using Metadata Studio Helm Chart:
- Migrate your GraphDB instance
- Update Metadata Studio Chart to version 0.3.1
Moving to new Metadata Studio setup:
- Backup all GraphDB repositories data.
- Stop the existing Metadata Studio deployment.
- Deploy Metadata Studio 3.5 with GraphDB 10.3.2.
- Restore GraphDB repositories data.
Ontotext Metadata Studio 3.3.0 to 3.4.0¶
Migration to GraphDB 10.2.3 is required to run OMDS 3.4.0. The exact steps to migrating your existing GraphDB instance to GraphDB 10.2.3 depend on the your specific setup.
Hint
More details on GraphDB Migration configurations are available in GraphDB 10.2 documentation.
Migration steps¶
Migration when using Docker images:
- Migrate your GraphDB instance.
- Update
sparql.endpoint.address
property in Metadata Studio Service according to your migrated GraphDB instance. - Update Metadata Studio Service and Metadata Studio Web versions to 3.4.0 update the environment.
Hint
Internal GraphDB address could be: http://graphdb-proxy:7200 when deployed in cluster or http://graphdb-node:7200 otherwise.
Migration when using Metadata Studio Helm Chart:
- Migrate your GraphDB instance
- Update Metadata Studio Chart to version 0.3.0
Moving to new Metadata Studio setup:
- Backup all GraphDB repositories data.
- Stop the existing Metadata Studio deployment.
- Deploy Metadata Studio 3.4 with GraphDB 10.2.3.
- Restore GraphDB repositories data.
Ontotext Metadata Studio 3.2.1 to 3.3.0¶
One new base class is introduced in th SOML schema - Form. It is used when the use case calls for a form based approach where the annotations that the user should create are predefined in a form.
Another minor change is the default preview configuration for InlineAnnotation
class. The key
property is set as a preview configuration.
Note
The addition of new classes requires updating and reloading the SOML schema after completing the migration process. See how to do it in the Apply changes and reload SOML schema section below.
Migration steps¶
Hint
If you are using the base schema and all changes are applied through GraphQL mutations, it is enough to just reload the base schema as described in the Apply changes and reload SOML schema section.
Update the SOML schema when using a custom schema.
Add the
Form
class:Form: kind: abstract
- Add
metadata
property toInlineAnnotation
class:
InlineAnnotation: kind: abstract inherits: Annotation props: metadata: { meta: { preview: { fields: [ "key" ] } } }
- Add
Reload the schema.
Ontotext Metadata Studio 3.2.0 to 3.2.1¶
The following changes concerning the SOML schema have been introduced:
- A new
sys:label
property is added to all ObjectClass SOML entities.
Note
The new property addition requires updating and reloading the SOML schema after completing the migration process. See how to do it in the Apply changes and reload SOML schema section below.
Migration steps¶
For the new
sys:label
property: If you are using the base schema and all changes are applied through GraphQL mutations, it is enough to just reload the base schema as described in the Apply changes and reload SOML schema section.Update the SOML schema when using a custom schema.
Add the
sys:label
special prefix tosys:ObjectClass
andsys:Property
props section. See the snippet below:sys:ObjectClass: inherits: sys:SomlExtension descr: "Base class for extending SOML with new Objects" pattern: "${sys_id}" props: sys:id: {min: 1, descr: "ID of the Object in the SOML"} sys:kind: {descr: "Abstract or not", valuesIn: ["abstract", "object"]} sys:inherits: {range: iri, descr: "Class to inherit from"} sys:label: {descr: "Label of the Object in the SOML"} sys:descr: {descr: "Description or clarification"} sys:type: {max: inf, descr: "Array of type value IRIs (prefixed, relative, or absolute)"} sys:typeProp: {descr: "Property that determines the business type"} sys:sparqlFederatedService: {descr: "The ID of a SPARQL Federation Service"} sys:meta: { range: sys:Meta, max: inf, descr: "Adds an additional meta directive in the GraphQL schema for the given property" } sys:props: {range: sys:Property, max: inf, descr: "Array of Properties of the Object"} sys:Property: inherits: sys:SomlExtension descr: "Class representing a Property for SOML Extension" props: sys:id: {min: 1, descr: "ID of the Property in the SOML"} sys:label: {descr: "Label of the Property in the SOML"} sys:descr: {descr: "Description or clarification"} sys:rdfProp: {descr: "RDF property name (if not allowed in GraphQL or hard to read) or SPARQL Template"} sys:range: {descr: "Datatype or SOML object type"} sys:min: {range: int, descr: "Minimum number of values, integer (mutations)"} sys:max: {descr: "Maximum number of values, integer. inf means unlimited (mutations)"} sys:restrictive: {range: boolean, descr: "Controls the SPARQL generation. Properties set as true would not generate OPTIONAL"} sys:meta: {range: sys:Meta, max: inf, descr: "Adds an additional meta directive in the GraphQL schema for the given property"}
Update the project.
Reload the schema.
Ontotext Metadata Studio 3.1.0 to 3.2.0¶
The following changes concerning the SOML schema have been introduced:
- A new
vocabIri
special prefix: Used as an IRI prefix when SOML entities are generated and stored in GraphDB. - A new
ObjectClass
class: Used for creating SOML classes.
Note
The vocabIri
special prefix change requires updating and reloading the SOML schema after completing the migration process. See how to do it in the Apply changes and reload SOML schema section below.
Furthermore, GraphQL mutations for creating, updating, and deleting Annotation classes or Document classes have a new syntax.
Note
The GraphQL mutation syntax change requires an update on the mutations that call the Metadata Studio Service directly, if such exist.
Migration steps¶
For the new
vocabIri
special prefix andObjectClass
class: If you are using the base schema and all changes are applied through GraphQL mutations, it is enough to just reload the base schema as described in the Apply changes and reload SOML schema section.Update the SOML schema when using a custom schema.
Add the
vocabIri
special prefix to thespecialPrefixes
section and update thesys:ObjectClass
as shown below:specialPrefixes: vocab_prefix: voc sys:ObjectClass: inherits: sys:SomlExtension descr: "Base class for extending SOML with new Objects" pattern: "${sys_id}" props: sys:id: {min: 1, descr: "ID of the Object in the SOML"} sys:kind: {descr: "Abstract or not", valuesIn: ["abstract", "object"]} sys:inherits: {range: iri, descr: "Class to inherit from"} sys:descr: {descr: "Description or clarification"} sys:type: {max: inf, descr: "Array of type value IRIs (prefixed, relative, or absolute)"} sys:typeProp: {descr: "Property that determines the business type"} sys:sparqlFederatedService: {descr: "The ID of a SPARQL Federation Service"} sys:meta: { range: sys:Meta, max: inf, descr: "Adds an additional meta directive in the GraphQL schema for the given property" } sys:props: {range: sys:Property, max: inf, descr: "Array of Properties of the Object"}
Update the project.
Reload the schema.
For the Annotations and Documents mutation change:
Update your mutations following the examples below:
Create mutation:
mutation create { create_sys_ObjectClass(objects: [ { sys_id: "PersonAnnotation" sys_inherits: "voc:InlineAnnotation" } ]) { sys_ObjectClass { id } } }
Update mutation:
mutation update { update_sys_ObjectClass(where: {ID: ["http://example.com/PersonAnnotation"]}) { sys_ObjectClass { id } } }
Delete mutation:
mutation delete { delete_sys_ObjectClass(where: {ID: ["http://example.com/PersonAnnotation"]}) { sys_ObjectClass { id } } }
Execute the new mutations.
Ontotext Metadata Studio 3.0.0 to 3.1.0¶
An optional setting for default sort field of Document annotations has been introduced to the SOML schema. See here for more details.
A new ExternalService
class has been introduced in the SOML schema. It defines the configured SPARQL federated services in Metadata Studio.
The class is used in the Project
class where a new property externalService
is introduced. See here for more details.
Note
The External service change requires updating and reloading the SOML schema after completing the migration process. See how to do it in the Apply changes and reload SOML schema section below.
Note
During upgrade of the Ontotext Metadata Studio to a newer version (or just a different version in general), the base schema will be automatically updated in case there are any changes to it in the new version.
If you do not want to update the default schema, you need to set the omds.update.default.schema
property in the values.overrides.yaml file to false
like this:
service: configuration: omds.update.default.schema: "false"
After the upgrade, the old schema version will be backed up with ID /soml/mant_<previous-version>
.
Migration steps¶
Hint
If you are using the base schema and all changes are applied through GraphQL mutations, it is enough to just reload the base schema as described in the Apply changes and reload SOML schema section.
Update the SOML schema when using a custom schema.
Add the
ExternalService
class:ExternalService: type: omds:ExternalService props: label: label: "External service name" min: 1 url: label: "External service address" min: 1
Add the
externalService
field to theProject
class:Project: inherits: Timesensitive type: omds:Project props: label: {label: "Label", meta: {search: {visible: true, order: 1}, form: {visible: true}}} status: {label: "Status", meta: {search: {visible: true, order: 2}, form: {visible: true}}} metadata: {meta: {search: {visible: false}, form: {visible: false}}} corpus: {range: Corpus, max: inf, rdfProp: omds:corpus, meta: {search: {visible: false}, form: {visible: false}}} logo: {range: iri, rdfProp: omds:logo, meta: {search: {visible: false}, form: {visible: false}}} externalService: {range: ExternalService, max: inf, meta: {search: {visible: false}, form: {visible: false}}}
Add the
externalService
property to themetadata
fieldmeta
of all Concepts with definedsparqlFederatedService
. The name of the service must matchsparqlFederatedService
.Person: inherits: Concept sparqlFederatedService: wikidata props: metadata: { meta: { externalService: "wikidata"} }
Reload the schema.
Update the project.
Configure the services that are external to the project.
Using the Metadata Studio UI:
Open the Projects View.
Click the Configure project settings icon under Actions.
Add all external services to the project via the Create new button.
Using a mutation:
mutation CreateExternalService( $projectId: [ID!] $externalServiceName: String $externalServiceUrl: String ) { update_Project( where: { ID: $projectId } objects: { externalService: { externalService: { label: $externalServiceName url: $externalServiceUrl } } } ) { project { externalService { id label url } } } }
Update the Concept classes with the corresponding external service.
Using the Metadata Studio UI:
In the Manage schema view, open the Extend class view of the Concept class.
In the
field, select the corresponding external service.
Using a mutation:
For all Concept classes that have
metadata
field, execute the following mutation:mutation createConceptMetadata( $classId: [ID!] $externalServiceName: String ) { update_Concept_Class( where: { ID: $classId } objects: { sys_props: { sys_Property: { sys_id: "metadata" sys_meta: { sys_Meta: { sys_key: "externalService", sys_values: $externalServiceName } } } } } ) { affected_count { kind count } } }
For all Concepts that do NOT have a
metadata
field, execute the following mutation:mutation UpdateConceptMetadata( $classId: [ID!] $externalServiceName: String ) { update_Concept_Class( where: { ID: $classId } objects: { sys_props: { where: { sys_id: { EQ: "metadata" } } sys_Property: { sys_meta: { replace: true sys_Meta: { sys_key: "externalService", sys_values: $externalServiceName } } } } } ) { affected_count { count kind } } }
Apply changes and reload SOML schema¶
Important
This step applies to every migration process regardless of the Metadata Studio version.
If using the base SOML schema and all changes are done through GraphQL mutations:
- Delete the
otp-system
system repository. - Restart Metadata Studio.
- Delete the
If using a custom SOML schema, reload it as follows:
Retrieve the SOML schema from the service:
curl --location -X GET 'http://hostname/service/soml/{schemaName}' \ -H 'X-Request-ID: some-uuid-correlation-id' \ -H 'Accept: text/yaml' \ -H 'Authorization: Bearer {validToken}'
Apply any changes to the SOML schema.
Upload the SOML schema to the service:
curl --location -X PUT 'http://hostname/service/soml/{schemaName}' \ -H 'Content-Type: text/yaml' \ -H 'X-Request-ID: some-uuid-correlation-id' \ -H 'Accept: application/ld+json' \ -H 'Authorization: Bearer {validToken}' \ -T schema.yaml