Migration Guide

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:

    1. Migrate your GraphDB instance.
    2. Update sparql.endpoint.address property in Metadata Studio Service according to your migrated GraphDB instance.
    3. 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:

    1. Migrate your GraphDB instance
    2. Update Metadata Studio Chart to version 0.3.1
  • Moving to new Metadata Studio setup:

    1. Backup all GraphDB repositories data.
    2. Stop the existing Metadata Studio deployment.
    3. Deploy Metadata Studio 3.5 with GraphDB 10.3.2.
    4. 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:

    1. Migrate your GraphDB instance.
    2. Update sparql.endpoint.address property in Metadata Studio Service according to your migrated GraphDB instance.
    3. 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:

    1. Migrate your GraphDB instance
    2. Update Metadata Studio Chart to version 0.3.0
  • Moving to new Metadata Studio setup:

    1. Backup all GraphDB repositories data.
    2. Stop the existing Metadata Studio deployment.
    3. Deploy Metadata Studio 3.4 with GraphDB 10.2.3.
    4. 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.

  1. Update the SOML schema when using a custom schema.

    1. Add the Form class:

      Form:
        kind: abstract
      
      1. Add metadata property to InlineAnnotation class:
                InlineAnnotation:
      kind: abstract
      inherits: Annotation
      props:
        metadata: { meta: { preview: { fields: [ "key" ] } } }
      
  2. 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.

    1. Update the SOML schema when using a custom schema.

      1. Add the sys:label special prefix to sys:ObjectClass and sys: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"}
        
      2. Update the project.

    2. 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 and ObjectClass 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.

    1. Update the SOML schema when using a custom schema.

      1. Add the vocabIri special prefix to the specialPrefixes section and update the sys: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"}
        
      2. Update the project.

    2. Reload the schema.

  • For the Annotations and Documents mutation change:

    1. 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
                }
            }
        }
        
    2. 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.

  1. Update the SOML schema when using a custom schema.

    1. Add the ExternalService class:

      ExternalService:
        type: omds:ExternalService
        props:
          label:
            label: "External service name"
            min: 1
          url:
            label: "External service address"
            min: 1
      
    2. Add the externalService field to the Project 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}}}
      
    3. Add the externalService property to the metadata field meta of all Concepts with defined sparqlFederatedService. The name of the service must match sparqlFederatedService.

      Person:
        inherits: Concept
        sparqlFederatedService: wikidata
        props:
          metadata: { meta: { externalService: "wikidata"} }
      
    4. Reload the schema.

  2. Update the project.

    1. Configure the services that are external to the project.

      • Using the Metadata Studio UI:

        1. Open the Projects View.

        2. Click the Configure project settings icon under Actions.

        3. Add all external services to the project via the Create new button.

          _images/add-external-service.png
      • 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
                    }
                }
            }
        }
        
    2. Update the Concept classes with the corresponding external service.

      • Using the Metadata Studio UI:

        1. In the Manage schema view, open the Extend class view of the Concept class.

        2. In the Class details ‣ SPARQL federated service field, select the corresponding external service.

          _images/update-concept-class-with-external-service.png
      • 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:

    1. Delete the otp-system system repository.
    2. Restart Metadata Studio.
  • If using a custom SOML schema, reload it as follows:

    1. 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}'
      
    2. Apply any changes to the SOML schema.

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