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