Upgrading an existing installation of Studio – Home

Info: The information in this article only applies to the on-premise version of Studio, not to the cloud version.

This article describes the required steps for upgrading an existing Studio installation to a new version of Studio.

Before you start

Before upgrading, please read the Release Notes for any important changes or upgrade instructions. Verify this for all versions that were released after the version that you have currently installed.

Performing a minor upgrade of Studio

This involves the following steps:

Downloading the new files
Reviewing required and optional steps (before upgrading)
Upgrading Studio
Upgrading the Studio plug-in for Studio Server
(Optional) Upgrading the Desktop Application
(Optional) Creating Component Sets and assign them to Digital article templates
Reviewing optional steps (after upgrading)
Testing the installation

Info: Use the filter to only show information for one step.

1. Downloading the new files

Download the new version of Studio and the Studio Server plug-in from the Software Release page (either the latest version or an intermediate version made available in an announcement).

2. Reviewing required and optional steps (before upgrading)

Depending on the version of Studio that you are upgrading from or to, some additional steps may be need to be performed.

Review the following information and implement when necessary.

Upgrading to Studio 11.124 or higher

Studio 11.124 introduces a fix for automatically converting Digital article components. In previous versions, matching was done based on the directive type instead of the id type . This behavior is incorrect as it leads to issues when multiple directives of the same type exist. It also does not match the intent with which the auto conversion rule was designed.

As part of the fix, the conversion rules of the default Component set have been updated, thereby simplifying the process of updating the default Component set.

Before updating to a new version of Studio, all active Component sets need to be updated when you have one or multiple custom Component sets and you make use of the component conversion tools.

Note: When Component sets are not updated, the conversion behavior will change for various components.

Steps for upgrading the default Component set

Note: See also the examples below.

Step 1. Create a new component package by following the instructions in the Read Me file of the Component set.

Step 2. Update the default Component set through the Management Console:

Step 2a. In Studio Server, access the Management Console by clicking Integrations > Studio.

Step 2b. In the menu, choose Component Sets.

Step 2c. Expand the Default Component set and click Choose file to upload the newly created package.

Steps for upgrading custom Component sets

Tip : Speed up the upgrade process by (partly) using the updated conversionRules from the default component set.

Step 1. Open the component-definition.json file of your Component set.

Step 2. Scroll to the conversionRules section.

Step 3. Find the first conversion rule set that is set to auto and check if the directive keys of the templates match.

If they match: no action is required.
If they do not match: change the conversion rule from auto to simple and create a mapping between the directive keys as described in this article.

Step 4. Repeat step 3 for all conversion rules that are configured as auto.

Step 5. Create a package of your Component set and update it through the Management Console:

Step 5a. In Studio Server, access the Management Console by clicking Integrations > Studio.

Step 5b. In the menu, choose Component Sets.

Step 5c. Expand your Component set and click Choose file to upload the newly created package.

Step 6. Create a test article to validate if the updated conversion rules work according to what is configured.

Examples

The following are examples of updating the default Component set.

Example 1: Converting body to subtitle and vice versa

Here, both body and subtitle components have a doc-editable directive. The directive key however does not match as we can see when comparing the templates (text vs title):

body.html:

<p class="text body" doc-editable="text">{{ COMPONENT_BODY_LABEL }}</p>

subtitle.html:

<h2 class="text subtitle" doc-editable="title">{{ COMPONENT_SUBTITLE_LABEL }}</h2>

Old conversion rules configuration:

{
  "conversionRules": {
    "body": {
      "subtitle": "auto"
    },
    "subtitle": {
      "body": "auto"
    }
  }
}

New conversion rules configuration:

{
  "conversionRules": {
    "body": {
      "subtitle": {
        "type": "simple",
        "map": {
          "title": "text"
        }
      }
    },
    "subtitle": {
      "body": {
        "type": "simple",
        "map": {
          "text": "title"
        }
      }
    }
  }
}

Example 2: Converting image to product

Here, both image and product components have a doc-image directive with an identical directive key: image. They differ however when comparing the doc-editable directive: image has a caption and product has a product_title, description, price and link.

image.html:

<figure class="image">
    <div doc-image="image" doc-link="hyperlink"></div>
    <figcaption doc-editable="caption">
        Image caption, sem vel consectetur dignissim, quam felis molestie lorem, eget posuere felis turpis vitae odio.
    </figcaption>
</figure>

product.html:

<div class="product">
    <figure class="product-image-part">
        <img doc-image="image" />
    </figure>
    <div class="product-text-part">
        <h1 doc-editable="product_title">{{ TEMPLATE_PRODUCT_TITLE_PLACEHOLDER }}</h1>
        <p doc-editable="description">{{ TEMPLATE_PRODUCT_DESCRIPTION_PLACEHOLDER }}</p>
        <h2 doc-editable="price">{{ TEMPLATE_PRODUCT_PRICE_PLACEHOLDER }}</h2>
        <h3 doc-editable="link">{{ TEMPLATE_PRODUCT_LINK_PLACEHOLDER }}</h3>
    </div>
</div>

Old conversion rules configuration:

{
  "conversionRules": {
    "image": {
      "product": "auto"
    }
  }
}

New conversion rules configuration:

{
  "conversionRules": {
    "image": {
      "product": {
        "type": "simple",
        "map": {
          "image": "image",
          "product_title": "caption"
        }
      }
    }
  }
}

2. Upgrading Studio

Step 1. For reference purposes, access the configuration settings of your current Studio installation. Do this by opening the following file and copying the content to a temporary text file:

<Studio Server path>/contentstation/config.js

Step 2. Remove Studio by removing the folder named 'contentstation' from the root of your Studio Server installation.

Step 3. Unzip the downloaded version of Studio and place the extracted folder named 'contentstation' in the root of your Studio Server installation.

Step 4. Open the following file and update the settings with the settings from the reference file created earlier:

<Studio Server path>/contentstation/config.js

Caution: Do this by comparing the files to find the differences. You must not just copy your old configuration settings over the new ones as important modifications may have been made.

Step 5. Save the file.

3. Upgrading the Studio plug-in for Studio Server

Tip: To ease the upgrading process of the Studio plug-in, store all modified configuration settings in the config_overrule.php file of Studio Server instead of in the config.php file of the plug-in itself. This way, only the plug-in needs to be replaced without having to update its configuration file.

Step 1. (Optional, only when the settings are not stored in the config_overrule.php file) For reference purposes, access the configuration settings of your current Studio plug-in installation. Do this by opening the following file and copying the content to a temporary text file:

<Studio Server path>/config/plugins/ContentStation/config.php

Step 2. Remove the currently installed Studio Server plug-in by removing the folder named 'ContentStation' from the following folder of your Studio Server installation:

config/plugins

Step 3. Unzip the downloaded version of the Studio Server plug-in and place the extracted folder named 'ContentStation' in the config/plugins folder of your Studio Server installation.

Step 4. (Optional, only when the settings are not stored in the config_overrule.php file) Open the following file, update the settings with the settings from the reference file created earlier.

<Studio Server path>/config/plugins/ContentStation/config.php

Caution: Do this by comparing the files to find the differences. You must not just copy your old configuration settings over the new ones as important modifications may have been made.

Step 5. Log in to Studio Server, access the Server plug-ins page and verify that the plug-in named 'Studio' is enabled (as indicated by a green icon). When a red icon is shown, click it to enable the plug-in.

4. (Optional) Upgrading the Desktop app

The Desktop application is used for setting up the communication between Studio and other applications and for controlling some of the features of the Desktop app itself.

When the Desktop app is already installed and a new version of the Desktop app is made available, the Desktop app can be updated with that new version.

For more information, see Using the Desktop app of Studio.

Note: In Studio 11.90, the Desktop app has been renamed from 'Content Station Desktop app' to 'Studio Desktop app'. When upgrading from Studio 11.89 or lower with a copy of the Content Station Desktop app installed, uninstall / remove the Content Station Desktop app.

5. (Optional) Create Component Sets and assign them to Digital article templates

Component Sets control which components a user can make use of in the article, how these components look and how they work.

Component Sets are made available for a Digital article by assigning them to the template on which a Digital article is based when it is created.

Create as many Component Sets as needed and assign them to the Digital article template in which the set of components need to be available.

Note: When a Digital article is based on a template which does not have a Component Set assigned, the user is asked to choose one when the article is opened. Note that users may not be familiar (enough) with Component Sets to make a correct choice, so it is advised to add a Component Set to each Digital article template.

6. Reviewing optional steps (after upgrading)

Depending on the version of Studio that you are upgrading from or to and the features that you want to make use of, some additional steps may have to be manually performed after Studio has been installed.

Review the below information and implement where applicable.

Upgrading to Studio 11.100 or higher

Using images in SVG format in a Digital article. Images in SVG format can be added to a Digital article as an image or as part of a slideshow. To make this work, the SVG format needs to be added to the file type mapping in the server on which Studio is run. For more information, see Configuration steps for using SVG images in Digital articles in Studio.

Upgrading to Studio 11.105 or higher

Disabling user behavior tracking. WoodWing anonymously tracks user behavior within the application to get an insight into the features of the application that are used and how they are used. Analyzing this information makes it possible for WoodWing to improve the usability and performance of the application. Since Studio 11.105, tracking user behavior is also done through the integration of Mixpanel. The integration of Amplitude used in previous versions is still present but is marked as deprecated and is planned to be removed in a future version.

Tracking analytics via Mixpanel is enabled by default. Should the recording of analytics be disabled (for example because tracking is not allowed in your country for legal reasons), this can be done by disabling the 'Enable analytics' option in the Management Console via Features > General.

For more information, see User behavior tracking in Studio.

Managing the Apps menu via the Management Console. Studio 11.105 has added the option to manage Apps that appear in the Apps menu via the Management Console. These include the default Apps such as the Publication Overview, Issue Manager, and Trash Can. The previous configuration via the config.js file is still available, but managing the configuration via the Management Console is quicker and more user friendly.

Should you have added custom applications to the Apps menu in the version of Studio that you are upgrading from, consider managing them now via the Management Console. Use the settings from the config.js file of the previous installation of Studio to re-configure them. For details, see Adding Custom Applications to Studio.

Note that once managing the Apps menu is done through the Management Console, any configuration settings in the config.js file are ignored.

Upgrading to Studio 11.110 or higher

Enabling the Digital editor through configuration. Since Studio 11.110, it is no longer required to enable the Digital editor by setting the 'CS_DIGITAL_EDITOR_ENABLED' option in the config_overrule.php file of Studio Server to true.

The Digital editor is automatically available for users who log in to Studio 11.110 or higher by using a Multichannel license (required for the use of the Digital editor).

If the 'CS_DIGITAL_EDITOR_ENABLED' option was configured in the config_overrule.php file, the option can now be removed.

Upgrading to Studio 11.162 or higher

Non-breaking spaces in the PSV output of Digital articles. When a Digital article is published, a package of article files and metadata is gathered and sent to the publish channel endpoint: the publish package. One of the files in this package is a rendition of the article in PSV (Prism Source Vocabulary) format.

Within this file, all non-breaking spaces (HTML entity ' ') were replaced by regular space characters in the output. This was done because XML does not support the ' ' entity, and replacing it with a regular space turned out to be the simplest solution at the time.

To create a more accurate export of the content, all ' 'entities are now replaced with '
' Unicode character references.

Any customer who does not like the non-breaking spaces in the XML, can do a transformation to get rid of the non-breaking spaces. This would require a script to change back the '
' to ' '. This does require clean-up on the customer's end.

7. Testing the installation

Step 1. Access the Health Check page in Studio Server.

Step 1a. In the Maintenance menu or on the Home page, click Advanced. A page showing links to advanced Studio Server options appears.

Step 1b. Click Health Check. The Health Check page appears.

Step 2. Click Clear All to deselect all selected tests.

Step 3. Select the following tests:

InDesign Server / CS Editor
Studio

Step 4. Click Test.

The test results are displayed next to the test and should display OK.

Note: If the test fails, an error is displayed together with instructions for how to solve it. Follow the instructions to fix the issue and then run the test once more.

Step 5. Access Studio by entering the following URL in a Web browser:

<Studio Server URL>/contentstation

Example: http://127.0.0.1/StudioServer/contentstation

Step 6. Test the installation by performing tasks that are part of the daily workflow such as creating an article, checking-out a layout or image, and so on.

Step 7. (Optional, only when you are seeing unexpected results) Clear the Web browser cache, close the tab in which Studio is run and access it again.