Skip to main content

Migration Steps for UnifiedViews

24/04/2026

The UnifiedViews migration process requires manual action — specifically, copying the necessary files and folders from a native installation of UnifiedViews to a dockerized version. Starting with version 10.2.0, UnifiedViews is released with Docker files and Helm charts for deployment against Kubernetes.

Migration steps

  1. Stop the old UnifiedViews service. See step (3) above of the requirements.

    Stop the new UnifiedViews (both rdf4j and unified-views services). Example:

    docker compose -f docker-compose.yaml -f addons.yaml down rdf4j unified-views

  2. The old UnifiedViews properties file cannot be directly used with the new UnifiedViews. It must be adapted with several new variables.

    As a reference we have a previous backup of the new UnifiedViews properties file at step (2) of the requirements (see above).

  3. Adapt your old unifiedviews.properties file with variables values as follows:

    module.path = /unified-views/dependencies
general.workingdir = /unified-views/data/backend/working
frontend.log.directory = /unified-views/logs/frontend
backend.log.directory = /unified-views/logs/backend

  4. Map the unifiedviews.properties file to be used by UnifiedViews docker service. This should be done inside the addons.yaml file in the volume section of unified-views service. Example:

    volumes:
      -./unifiedviews.properties:/unified-views/configs/uv.properties

  5. During the first RDF4J-Workbench service startup, two volumes were created, defined in addons.yaml file for the rdf4j service:

    volumes:
      - rdf4j_data:/var/rdf4j
      - rdf4j_logs:/usr/local/${APP_SERVER:-tomcat}/logs

    We will use rdf4j_data as a target volume for old UnifiedViews RDF4J data folder content.

  6. Delete the existing default content of the rdf4j_data volume. Example:

    docker run --rm \
      -v pp10_rdf4j_data:/data \
      alpine sh -lc 'rm -rf /data/* /data/.[!.]* /data/..?* || true; ls -la /data'   

  7. Inspect the volume rdf4j_data and get the value of its configured user. Example output (User=tomcat)

    >docker inspect pp10-rdf4j-1 --format 'User={{.Config.User}}'

  8. Inspect the RDF4J-Workbench image and get the value of user identity: Example output (uid=101(tomcat) gid=65534(nogroup) groups=65534(nogroup))

    docker run --rm --entrypoint sh eclipse/rdf4j-workbench:4.3.15 -lc 'id; echo "---"; id tomcat || true'

  9. Copy the old RDF4J folder content from previous backup done at step (6) of the requirements (see above) to the rdf4j_data volume and set the ownership and permissions retrieved from steps (7) and (8). Example (tomcat. Nogroup, 750)

    docker run --rm \
      -v pp10_rdf4j_data:/data \
      -v "$PWD/uv_rdf4j":/src:ro \
      alpine sh -lc \
      'cp -a /src/. /data/ && \
      chown -R 101:65534 /data/server && \
      chmod -R 750 /data/server'

  10. Start both the rdf4j and unified-views services. Example:

    docker compose -f docker-compose.yaml -f addons.yaml up -d rdf4j unified-views

  11. Log in to UnifiedViews with the following URL to verify that old data is present. URL:

    	    http(s)://<server-name>/UnifiedViews

    Credentials: credentials for the admin user from the old UnifiedViews installation. All old data should be present in the UI:

    1. Pipelines tab 

      They should be editable and executable, with the same old user ownership and visibility settings.

    2. DPUs tab 

      Default DPUs, old clones of default DPUs, and visibility settings.

    3. Monitor tab 

      Old executions should be listed.

    4. Scheduler tab 

      Old scheduling rules should be listed.

    5. Settings menu 

      1. Account and notifications settings are the same as before.

      2. Run-time properties are the same as before.

      3. Debug and working data settings are the same as before.

      4. Users (all old users are present, login should be possible).

Remarks

  1. Other DPUs, particularly those customized in the legacy UnifiedViews environment, must be manually imported via the user interface. It is also a prerequisite that these DPUs are compatible with the new UnifiedViews installation version.

  2. Your new UnifiedViews installation will still use the working folder that the old one did, and you may want to map it to the external one.. If needed you can use it for old working folder content from the previous backup done in step (7) of the requirements (see above). UnifiedViews container location:

    /unified-views/data/backend/working

  3. After this, it is again possible to enable OIDC if needed and use external non-local UnifiedViews users to login.

  4. Pipelines can be exported and imported via API, and DPUs can be imported via API. These API calls support both Basic authentication and OAuth when OIDC is enabled.

    More details of API usage can be found on the Swagger openAPI documentation page. This page is not enabled by default, so you need to add the flag master.api.doc.enabled = true in the UnifiedViews properties file and restart the service. URL:

      http(s)://<server-name>/master/swagger-ui/

    If a client will need to retrieve default DPUs (loaded during the first start of the new UnifiedViews), they can find them inside the UnifiedViews container. Source:

      /unified-views/dependencies/defaultdpus

    Used DPUs in pipelines can be exported together with the pipeline(s) export (see below).

Examples of API calls

Export of all pipelines (pipelines + all DPUs used in pipelines):

          curl --location 'https://<server-name>/master/api/1/pipelines/export?asUser=admin' \
          --header 'Content-Type: application/json' \
          --header 'Accept: application/zip' \
          --header 'Authorization: Basic YWRtaW46dW5pZmllZHZpZXdz' \
          --data '{
          "exportDPUUserData": true,
          "exportJars": true,
          "chbExportSchedule": true
          }' \
          -o pipelines.zip

Export of a single pipeline (pipeline + all DPUs used in the pipeline):

          BASE_URL="https://<server-name>/master/api/1"
          PIPELINE_ID="ef385338-f370-402b-9b40-4c6b9a68645b"
          AUTH_B64="YWRtaW46dW5pZmllZHZpZXdz"
          curl --location "$BASE_URL/pipelines/$PIPELINE_ID/export" \
          --header 'Content-Type: application/json' \
          --header 'Accept: application/zip' \
          --header "Authorization: Basic $AUTH_B64" \
          --data '{
          "exportDPUUserData": true,
          "exportJars": true,
          "chbExportSchedule": true
          }' \
          -o "pipeline-$PIPELINE_ID.zip" \
	  -w "\nPIPELINE_ID: $PIPELINE_ID\nHTTP status: %{http_code}\n"

Export of a single pipeline import:

          curl --location 'https://<server-name>/master/api/1/pipelines/import' \
          --header 'Authorization: Basic YWRtaW46dW5pZmllZHZpZXdz' \
          --form 'file=@pipeline.zip' \
          --form 'asUser=admin' \
          --form 'importUserData=true' \
          --form 'importSchedule=true' \
	  -w '\nHTTP status: %{http_code}\n'
Rollback procedures

Stop the Docker container and start your previous UnifiedViews installation.

In this section: