MySource Matrix Resources

Upgrading MySource Matrix from v3.16 to v3.18

Stop Editing

No editing should be taking place during a major version upgrade. Before starting the upgrade, first ensure that all editors are logged out of the system.

Backup

Before starting any upgrade, always backup your MySource Matrix installation. See the MySource Matrix backup management guide for information on how to backup your MySource Matrix system.

Delete Stale HIPO Jobs

During a major version upgrade, stale HIPO jobs should be removed from the system. Log into the MySource Matrix administration interface as root user and go to the HIPO Herder screen. Lock this screen and delete all HIPO jobs that are listed. Note that there may not be any stale HIPO jobs in the system.

Clear the MySource Matrix Cache

There are some changes to the way the MySource Matrix cache is stored. You should clear Matrix's cache from the Cache Manager before starting the upgrade.

Disable Rollback

At this point, you need to ensure that rollback is disabled before continuing. For help with disabling rollback, see the MySource Matrix rollback management guide.

Disable Cron Run script in Crontab

If you use the Cron system, you will have set up an entry in a Crontab file. It is most likely that it would have been set up for the user Apache runs as, however this depends on your system configuration.

As the user the Crontab entry was installed to, run the following command:

$ crontab -e

Find the entry for Matrix, and add a hash ("#") to the front of the entry to comment it out:

# */15 * * * * php /home/websites/mysource_matrix/core/cron/run.php /home/websites/mysource_matrix

Get the New Source Code

Now, you need to update the MySource Matrix source code. You can find out how to download the latest stable version of MySource Matrix on the installation page.

Once you have downloaded the source code, you need to replace the existing code with the newer version. This will not reset any configuration options or remove any content from your system.

$ cd /home/websites
$ mv mysource_matrix mysource_matrix_3-16
$ tar -xzvf new_source.tar.gz
$ cd mysource_matrix
$ cp -r /home/websites/mysource_matrix_3-16/data .

Run Install Step 1

Now, run the step_01.php installation script. This will create a new configuration file, db.inc. This file now contains the database information that was previously held in the main.inc file before this release (in the SQ_CONF_DB*_DSN settings).

$ php install/step_01.php /home/websites/mysource_matrix

Edit Database Information

Now open up the db.inc file (in directory data/private/conf) and add the relevant database information. The format used in this new configuration file is different to that previously used by MySource Matrix. This is due to a change in database layer between that used by Matrix on PHP 4, and on PHP 5.

See the PostgreSQL DB Setup Guide or the Oracle DB Setup Guide - depending on the database type used by your system - to find the correct setup for you.

Run Queries For New Lookup Value System

A new database storage system has been implemented for the Lookup Value system in this version. It is envisaged that this will reduce the time it takes to select the appropriate Design and/or Paint Layouts for an asset.

The queries to use depend on which database system your MySource Matrix installation is using. Open your SQL client of choice, then run ONLY those queries for that database.

PostgreSQL Database

BEGIN;

DELETE FROM sq_ast_lookup_value
    WHERE inhd = '1';

ALTER TABLE sq_ast_lookup_value
    DROP COLUMN inhd;

ALTER TABLE sq_ast_lookup_value
    ADD COLUMN depth INTEGER;

CREATE INDEX sq_ast_lookup_value_depth
    ON sq_ast_lookup_value (depth);

UPDATE sq_ast_lookup_value
    SET
        url = url || '/'
    WHERE
        url IN
        (
            SELECT url
                FROM sq_ast_lookup_value lv
                WHERE
                    lv.url IN 
                    (
                        SELECT url
                            FROM sq_ast_lookup l
                            WHERE 
                                l.assetid IN 
                                (
                                    SELECT majorid
                                        FROM sq_ast_lnk
                                        WHERE
                                            value LIKE 'override::%'
                                )
                    )
        );

UPDATE sq_ast_lookup_value
    SET
        depth = l.depth
    FROM 
    (
        SELECT url, (length(url) - length(replace(url, '/', ''))) AS depth
            FROM sq_ast_lookup_value
    ) AS l
    WHERE sq_ast_lookup_value.url = l.url;

ALTER TABLE sq_ast_lookup_value
    ALTER COLUMN depth SET NOT NULL;

ALTER TABLE sq_rb_ast_lookup_value
    DROP COLUMN inhd;

ALTER table sq_rb_ast_lookup_value
    ADD COLUMN depth integer;

CREATE INDEX sq_rb_ast_lookup_value_depth
    ON sq_rb_ast_lookup_value (depth);

COMMIT;

Oracle Database

DELETE FROM sq_ast_lookup_value
    WHERE inhd = 1;

ALTER TABLE sq_ast_lookup_value
   DROP COLUMN inhd;

ALTER TABLE sq_ast_lookup_value
    ADD depth INTEGER;

CREATE INDEX sq_ast_lookup_value_depth
    ON sq_ast_lookup_value (depth);

UPDATE sq_ast_lookup_value
    SET
        url = url || '/'
    WHERE url IN
    (
        SELECT url
            FROM sq_ast_lookup_value lv
            WHERE lv.url IN 
            (
                SELECT url
                    FROM sq_ast_lookup l
                    WHERE L.assetid IN
                    (
                        SELECT majorid
                            FROM sq_ast_lnk
                            WHERE value LIKE 'override::%'
                    )
            )
    );

UPDATE sq_ast_lookup_value lv
    SET
        lv.depth = 
        (
            SELECT (LENGTH(url) - LENGTH(REPLACE(url,'/',''))) AS depth
                FROM sq_ast_lookup_value L
                WHERE lv.url = l.url
                    AND ROWNUM = 1
        );

ALTER TABLE sq_ast_lookup_value 
    MODIFY depth NOT NULL;

ALTER TABLE sq_rb_ast_lookup_value
    DROP COLUMN inhd;

ALTER TABLE sq_rb_ast_lookup_value 
    ADD depth INTEGER;

CREATE INDEX sq_rb_ast_lookup_value_depth
    ON sq_rb_ast_lookup_value (depth);

COMMIT;

Run Install Step 2

Now, run the step_02.php installation script.

$ php install/step_02.php /home/websites/mysource_matrix

Remove References to Bridge Asset

The "Bridge" (ie. assets that list shadow assets) has been deprecated as a separate asset type in code since version 3.8. Bridges in assets have been implemented in a pseudo-interface style since 3.8 (changed to a PHP 5 interface in 3.18), allowing an asset to both be a parent of another asset type, and still implement the bridge pattern. The deprecated Bridge asset type has been removed in 3.18.

However, some assets still extended the deprecated Bridge asset, and this would make step_03.php refuse to run out of fear for corrupting the asset type tree. Some changes are required at database level in order to fix the asset type hierarchy for these types. Out of the SSV packages, the XML User Bridge (which now inherits directly from Asset) requires this change.

In order, the queries first update the level number of each level of the hierarchy underneath Bridge, then update the overall level of each affected type code, then delete the Bridge entry from the hierarchy.

The queries to use depend on which database system your MySource Matrix installation is using. Open your SQL client of choice, then run ONLY those queries for that database.

PostgreSQL Database

BEGIN;

UPDATE sq_ast_typ_inhd
    SET inhd_type_code_lvl = inhd_type_code_lvl - 1 
    WHERE
        ROW(inhd_type_code, type_code) IN
        (
            SELECT t2.inhd_type_code, t2.type_code
                FROM sq_ast_typ_inhd t1
                    JOIN sq_ast_typ_inhd t2
                    ON t1.type_code = t2.type_code
                WHERE 
                    t1.inhd_type_code = 'bridge'
                    AND t1.type_code <> 'bridge'
                    AND t2.inhd_type_code_lvl > t1.inhd_type_code_lvl
        );

UPDATE sq_ast_typ_inhd
    SET type_code_lvl = type_code_lvl - 1
    WHERE
        type_code IN 
        (
            SELECT t2.type_code
                FROM sq_ast_typ_inhd t1 
                    JOIN sq_ast_typ_inhd t2
                    ON t1.type_code = t2.type_code
            WHERE
                t1.inhd_type_code = 'bridge' 
                AND t1.type_code <> 'bridge'
        );

DELETE FROM sq_ast_typ_inhd 
    WHERE 
        inhd_type_code = 'bridge'
        AND type_code <> 'bridge';

COMMIT;

Oracle Database

UPDATE sq_ast_typ_inhd
    SET inhd_type_code_lvl = inhd_type_code_lvl - 1 
    WHERE
        (inhd_type_code, type_code) IN
        (
            SELECT t2.inhd_type_code, t2.type_code
                FROM sq_ast_typ_inhd t1
                    JOIN sq_ast_typ_inhd t2
                    ON t1.type_code = t2.type_code
                WHERE 
                    t1.inhd_type_code = 'bridge'
                    AND t1.type_code <> 'bridge'
                    AND t2.inhd_type_code_lvl > t1.inhd_type_code_lvl
        );

UPDATE sq_ast_typ_inhd
    SET type_code_lvl = type_code_lvl - 1
    WHERE
        type_code IN 
        (
            SELECT t2.type_code
                FROM sq_ast_typ_inhd t1 
                    JOIN sq_ast_typ_inhd t2
                    ON t1.type_code = t2.type_code
            WHERE
                t1.inhd_type_code = 'bridge' 
                AND t1.type_code <> 'bridge'
        );

DELETE FROM sq_ast_typ_inhd 
    WHERE 
        inhd_type_code = 'bridge'
        AND type_code <> 'bridge';

COMMIT;

Complete System Upgrade

Next, the system's installation scripts should be run to ensure the asset types and language translations are up to date.

$ php install/step_03.php /home/websites/mysource_matrix
$ php install/compile_locale.php /home/websites/mysource_matrix

Review DSNs for Certain Assets

Due to the change in database layer, DSN formats within the system will change to use the format used by PHP's PDO system. This is slightly different to the format used previously.

In particular, this applies to the following assets:

• DB Data Source
• Clear Matrix Cache Trigger Action

In general, if the DSN connection string in earlier versions took this format:

[dbtype]://[username]:[password]@[hostname]/[database]

In version 3.18.0, this connection string must be formatted thus (note that after database type, order does not appear to be important, and semicolons can be replaced by white-space):

[dbtype]:host=[hostname];user=[username];password=[password];dbname=[database]

Reset Rollback

Only run this step if your system has rollback enabled. If your system does not use rollback, you can safely skip this step.

Rollback entries should be reset between major versions. For instructions on how to reset rollback, see the MySource Matrix rollback management guide.

Re-enable Cron Run script in Crontab

You can now re-enable your MySource Matrix system's entry in the Crontab in the reverse manner as you did to disable it: by editing the Crontab file and removing the comment (#) from the front of the entry.

Re-enable Rollback

If you needed to disable rollback at the beginning of this upgrade, you may now re-enable it. For help with enabling rollback, see the MySource Matrix rollback management guide.

Upgrade Complete

The upgrade of your MySource Matrix system from version 3.16 to 3.18 is now complete.