This chapter describes the system management scripts available within Squiz Matrix. These scripts perform various tasks to manage and maintain your system.

add_user_own_access.php

The add_user_own_access.php script ensures that each user in the system has permissions to access their Squiz Matrix user asset and is provided as a fail safe measure in case the permissions have become corrupted. Primarily, this script is used during upgrade procedures.

This script is located in the /scripts directory of your Squiz Matrix system and takes the following parameter:

• The system root directory.

Example

$ php add_user_own_access.php [system_root]

WARNING: You are running this integrity checker on the whole system.
This is fine but:
  it may take a long time; and
  it will acquire locks on many of your assets (meaning you wont be able to 
  edit content for a while)
  
Root User [ # 5 ]            [ OK ] 

asset_listing_change_metadata_sort_option.php

The asset_listing_change_metadata_sort_option.php script will generate the SQL queries needed to change the metadata sorting options from raw to presentation or vice versa for an Asset Listing page. It does not run this SQL on the system but rather allows you to run it using a client of your choice.

This script is located in the /scripts directory of your Squiz Matrix system and takes the following parameter:

• The system root directory.

check_requirements.php

The check_requirements.php script is a requirements checking script that will verify the program requirements of a Squiz Matrix installation against your server configuration. Notification will be made for any required third-party applications, PHP extensions and PEAR packages. Utilities providing optional functionality within Squiz Matrix will also be suggested.

This script is located in the /install directory of your Squiz Matrix system and takes the following parameter:

• The system root directory.

clean_old_shadow_links.php

The clean_old_shadow_links.php script cleans links to shadow assets within Squiz Matrix that are no longer valid. This is usually due to the assets having since been removed from the data source (e.g. an LDAP backend user is linked under a User Group but is later removed from the LDAP directory).

When this script is first run, it will return a list of shadow links for review. These links can then be saved to a specified file (as either SQL statements or a PHP array) and passed back into the script for deletion.

This script is located in the /scripts/dev directory of your Squiz Matrix system and takes the following parameters:

• -m: The system root directory.
• -s: The file path to save SQL statements to delete old shadow links (optional).

  Tip: You will need to use an SQL client, such as psql, to excute the SQL statements generated on this parameter.

• -p: The file path to save a PHP array of old shadow links (optional).
• -d: The path of a PHP file, generated by this script's -p option, to delete old shadow links from the database (optional).

Example

In the following example, the clean_old_shadow_links.php script is run three times.

On the first run, the script returns a list of old shadow links in the system:

$ php clean_old_shadow_links.php -m [system_root]

List of old shadow links:

  linkid | type | majorid | minorid
-------+------+---------+--------------------------------------------------------
 11583 |    1 |    6    | 7094:uid=Manager,ou=Staff,o=Squiz,c=au,dc=demo,dc=squiz,dc=net
 11599 |    1 |    3091 | 3038:3

(Number of links: 2)

You will need to run this script with -s or -p option to save the shadow links to files
and -d option to delete the shadow links stored in the output file generated by -p option.
(You have to use an SQL client like psql to execute the SQL statements generated by -s option)

 --------------------------------------------------------------------------------------------------------

On the second run, the PHP array to deleted the old shadow links is saved to the old_links.php file, as specified in the -p parameter.

$ php clean_old_shadow_links.php -m [system_root] -p old_shadow_links.php

List of old shadow links:

linkid | type | majorid | minorid
--------+------+---------+--------------------------------------------------------
 11583 |    1 |    6    | 7094:uid=Manager,ou=Staff,o=Squiz,c=au,dc=demo,dc=squiz,dc=net
 11599 |    1 |    3091 | 3038:3
(Number of links: 2)

The PHP array to delete the old shadow links are saved to old_links.php

---------------------------------------------------------------------------------------------------------

On the final run, the old_links.php file is passed into the script (through the -d parameter) and the old shadow links are deleted from the database.

$ php clean_old_shadow_links.php -m [system_root] -d old_shadow_links.php

2 old shadow link(s) from old_links.php were deleted successfully.

clear_cron_deadlock.php

Clears the deadlock on the Scheduled Jobs Manager (Cron Manager).

The script takes the following parameters:

• [system_root]: The system root directory.
• --clear: Tell the script that you want to manually clear the deadlock. If this is not passed, the script will simply just tell you if there is a deadlock or not.
• --force: Force the clearing of the deadlock. If this is not passed, the script will only clear the deadlock if the cron is meant to be running and has tried to run more times than the maximum warning limit.

Example

$ php scripts/clear_cron_deadlock.php . --clear --force 
Cron Running: No, Run Checks: 0/3
Manual Clear Complete

Prior to version 5.4.1.0, the --clear parameter was called --reset. For any system prior to this version, you need to use --reset instead of --clear.

$ php scripts/generate_ssh_key.php <system_root> --generate --info

Generating public/private rsa key pair ...
Generating public/private rsa key pair ...

Your identification has been saved in ~/data/private/system/.ssh/matrix_ssh_key.
Your public key has been saved in ~/data/private/system/.ssh/matrix_ssh_key.pub.

The key fingerprint is:

The key's randomart image is:


RSA SSH keys pair generated successfully.

get_design_area_setable_attrs.php

The get_design_area_setable_attrs.php script is a diagnostic script that prints out the names of all the settable attributes of all the design areas in the Squiz Matrix system, along with their descriptions.

This script is located in the /scripts directory of your Squiz Matrix system and takes the following parameter:

• The system root directory.

hipo_management.php

The hipo_management.php script displays any HIPO Jobs currently running on the system, allowing you to manage jobs that may have stalled.

While this script is running, you will be prompted to select a HIPO Job to manage and then provided with the options of either resuming or killing the job.

This script is located in the /scripts directory of your Squiz Matrix system and takes the following parameter:

• The system root directory.
• -remove_all_jobs: kills all HIPO Jobs currently running on the system.

Example

$ php hipo_management.php [system_root]

1: HIPO Job Acquire Locks( 7% ) Last Updated: 1 minute and 3 seconds ago
2: HIPO Job Create Links( 27% ) Last Updated: 38 seconds ago
Enter the number of the job to change: (Press q to quit) 2   

Options
        r - resume
        k - kill
        q - quit
Choice:r

Resuming HIPO Job HIPO Job Create Links [  OK  ]   

$ php hipo_management.php [system_root] -remove_all_jobs

Found 4 jobs.
Make sure no HIPO jobs are running currently. Selecting 'yes' will remove
those HIPO jobs too.
Are you sure you want to continue removing all HIPO jobs? (y/n) y

Now truncating Hipo job table   [  OK  ] 

indent_list_to_xml.php

The indent_list_to_xml.php script takes a text file containing a list of indented items, and converts it into a Thesaurus XML import file. It is set up so that the relationships defined in the XML match the indenting in the text file.

This script is located in the /scripts directory of your Squiz Matrix system and takes the following parameter:

• The text file to convert.

Example

For example, create a file with the following content called thesaurus.txt:

    Fruit
        Apple
        Banana
    Vegetables
        Cabbage
            White
            Purple
        Daikon
        Eggplant

Passing the above file to the script will result in the following output:

$ php indent_list_to_xml.php thesaurus.txt

    <thesaurus>
        <term name="Fruit">
            <relation name="Category">
                <term name="Apple"></term>
                <term name="Banana"></term>
            </relation>
        </term>
        <term name="Vegetables">
            <relation name="Category">
                <term name="Cabbage">
                    <relation name="Category">
                        <term name="White"></term>
                        <term name="Purple"></term>
                    </relation>
                </term>
                <term name="Daikon"></term>
                <term name="Eggplant"></term>
            </relation>
        </term>
    </thesaurus>   

locale_backup.php

The locale_backup.php script gathers all of the locale information stored in locale/<language>/* underneath each asset and package, to assist with the process of translating the interface and error messages to different languages.

This script is located in the /scripts/locale directory of your Squiz Matrix system and takes the following parameters:

• The system root directory.

• --locale=<language_code> where <language_code> is a two-letter ISO 3166 country code. Can be used multiple times to export different languages (eg. --locale=en --locale=fr) or only specific types of localisation (specifically errors, internal_messages, screens and strings, eg. --locale=en-screens,errors will backup all the screens and errors in English).
• --output=<output_directory> where <output_directory> is the directory to write the compiled locale files to; if none is specified, they will be written to  <system_root>/data/temp/locale_backup/.

As of 5.0.0.0 this script has been removed from the official Matrix releases. This script is for development use only.

locale_restore.php

The locale_restore.php script takes all the locale string data generated by locale_backup.php and reintegrates it with your installation.

This script is located in the /scripts/locale directory of your Squiz Matrix system and takes the following parameters:

• The system root directory.

• -d: specifies the directory of the backed up files. If omitted, defaults to <system_root>/data/temp/locale_backup (optional).
• -r: recurse subdirectories (recommended if using the output from locale_backup.php) (optional).
• -f: force overwriting of language files. If not set, this script will ask you to confirm overwriting of each file that already exists (optional).

migrate_metadata_text_to_multiple_text.php

This script has been deprecated and was removed from Matrix in version 5.5.0.0.

The migrate_metadata_text_to_multiple_text.php script converts metadata content on a group of specified assets from metadata text fields to multiple text fields, splitting single entries by the specified delimiter.

This script is located in the /scripts directory of your Squiz Matrix system and takes the following parameters:

• The system root directory.
• --from=<from asset ID> where <from asset ID> is the asset ID of the Metadata Text Field to migrate from.
• --to=<to asset ID> where <to asset ID> is the asset ID of the Metadata Multiple Text Field to migrate to.
• --delimited=<delimiter> where <delimiter> is the delimiter between items (defaults to a single space) (optional).

Example

$ php migrate_metadata_text_to_multiple_text.php 

Usage: migrate_metadata_text_to_multiple_text.php -s <system root> --from=<from asset ID> --to=<to asset ID> --delimiter=<delimiter>

   -s          : the Matrix system root path
   --from      : the asset ID of the Metadata Text Field to migrate from
   --to        : the asset ID of the Metadata Multiple Text Field to migrate to
   --delimiter : delimiter between items (default is a single space) - multiple
          characters are allowed

NOTES:
* If your delimiter contains a space, you may need to place your delimiter
  string in quotation marks - eg. --delimiter=", "
* It is recommended to use the fully qualified path to your Matrix root to
  avoid warnings relating to file versioning in some assets (ie. Not ".").  

morph_assets.php

$ php scripts/morph_assets.php [system_root] 100 user backend_user
 
There are 1 user assets to morph, are you sure you want to continue? Type 'yes' to continue: yes
Morphing assets...
Morph Asset #202
Finished morphing assets. 1 of 1 user assets were morphed to backend_user assets.

permission_change.php

This script is deprecated because it has memory issues when used on a large amount of assets. Use system_apply_permission.php instead.

The permission_change.php script changes the Permissions of an asset with the option to cascade the permission change to child assets.

This script is located in the /scripts directory of your Squiz Matrix system and takes the following parameters:

• The system root directory.
• The asset ID of the asset to change the permissions of.
• The asset ID of the user to apply the permission to.
• The permission to apply (either read, write or admin).
• Whether to grant (indicated as y) or deny (indicated as n) the permission.
• Whether or not to cascade the status change to child assets (indicated as y) or not (indicated as n).

Example

$ php permission_change.php [system_root] 100 7 write y y

 START PERMISSION CHANGE

 FINISHED

In the above usage, the Public User has been granted Write Permission on the asset and its children.

recreate_rollback_triggers.php

The recreate_rollback_triggers.php script regenerates the Rollback triggers in the database and may be required during upgrades.

This script is located in the /scripts directory of your Squiz Matrix system and takes the following parameter:

• The system root directory.

regen_metadata_by_root_nodes.php

The regen_metadata_by_root_nodes.php script will take an argument of a list of root nodes separated by commas and regenerate the metadata for the child assets of each root node.

This script is located in the /scripts directory of your Squiz Matrix system and takes the following parameters:

• The system root directory.
• A comma-separated list of the asset ids for the root nodes to regenerate the metadata for.
• The maximum thread count. This parameter is optional and by default, it is set to 3.
• The number of assets to process per batch. This parameter is optional and by default it is set to 50.
• --skip-asset-update : prevent the metadata regeneration process from firing an Asset Updated event on regenerated assets. The Updated Date of these assets will also remain unchanged when this parameter is used. Optional
• --direct-children-only : will make the script only affect direct child assets (1 level down) from the selected root nodes. Optional

If you want to use the --skip-asset-update or --direct-children-only parameters, you must use the first 2 parameters in order for the script to work properly.

regen_metadata_schemas.php

The regen_metadata_schemas.php script regenerates the Metadata Schemas from the command line.

This script is located in the /scripts directory of your Squiz Matrix system and takes the following parameters:

• The system root directory.
• The ID of the Metadata Schema to regenerate. This is optional. If no ID is specified, all Metadata Schemas in the system will be regenerated.

regen_system_assets_config.php

The regen_system_assets_config.php script  generates the system assets config for installed systems. This script is provided for use if your system becomes fully corrupted. For example, if your system starts giving System asset not found errors.

This script is located in the /scripts directory of your Squiz Matrix system and takes the following parameter:

• The system root directory.

regenerate_file_system.php

regenerate_treeids_for_triggers.php

The regenerate_treeids_for_triggers.php script regenerates the IDs in the database for all triggers. This script should be run in conjunction with the recreate_link_tree.php script when regenerating the link tree in a database that includes triggers. For more information, refer to the Recreate Link Tree Script chapter.

This script is located in the /scripts directory of your Squiz Matrix system and takes the following parameter:

• The system root directory.

remove_old_cron_jobs.php

The remove_old_cron_jobs.php script removes any Cron jobs that were scheduled to run more than a week ago.

This script is located in the /scripts directory of your Squiz Matrix system and takes the following parameter:

• The system root directory.

remove_permissions.php

$ php remove_permissions.php --system=[system_root] --rootnode=100,130,205 --excludeuser=65 --type=2

This script is about to remove ALL permissions for assets under root node:100,130,205 excluding user:65 with permission type:2
39 assets to check
Are you sure you want to proceed (Y/N)? Y
32 permission rows have been deleted 

rename_thesaurus_term.php

$ php scripts/rename_thesaurus_term.php [system_root] 100 Apple Orange

Renaming Thesaurus Term.                        [ Done ]
Finding Metadata Schemas to regenerate.         [ Done ]
Updating Thesaurus Term on Assets.              [ Done ]
Total Asset found to regenerate schema on :     7

rename_type_code.php

The rename_type_code.php script updates the data directories and asset type entries in the database. This script should be run when renaming an asset type, after the asset type's directory and definition files have been renamed.

This script is located in the /scripts/dev directory of your Squiz Matrix system and takes the following parameters:

• The system root directory.

• The old asset type code.
• The new asset type code to rename it to.

As of 5.0.0.0 this script has been removed from the official Matrix releases. This script is for development use only.

replace_text.php

The replace_text.php script runs the WYSIWYG Editor's Replace Text plugin on all editable content under a specified set of root URLs.

For more information on the Replace Text plugin, refer to the WYSIWYG Editor chapter in the Content Types manual.

This script is located in the /scripts directory of your Squiz Matrix system and takes the following parameters:

• The system root directory.
• The root nodes to include when running this script.
• The root nodes to exclude when running this script (optional).

This script includes a number of editable configuration options that can be set on the script (1 to enabled, 0 to disable).

$options = Array ( 
        //non-extreme options 
        'Remove <font> tags' => 1, 
         'Remove double spaces' => 1, 
        'Remove non-HTML tags' => 1, 
        'Change Microsoft Words bullets' => 1, 
        'Remove soft hyphens' => 1, 
        //extreme options 
        'Remove style attribute' => 0, 
        'Remove class attribute' => 0, 
        'Remove <table> tags' => 0, 
        'Remove <span> tags' => 0, 
        'Remove all empty tags' => 0, 
        'Remove all tags attributes (except HREF and SRC)' => 0, 
    ); 

Example

$ php replace_text.php [system_root] 100 150

Examining wysiwyg content type of Asset ID: 105
Examining wysiwyg content type of Asset ID: 465
Examining wysiwyg content type of Asset ID: 469
Examining wysiwyg content type of Asset ID: 476
...

rewrite_assetid_links.php

run_cron_job.php

This script is for development use only.

The run_cron_job.php script runs a specified Cron job once, regardless of whether or not the cron job should be run at the time.

This script is located in the /scripts/dev directory of your Squiz Matrix system and takes the following parameters:

• The system root directory.

• The asset ID of the Cron job to execute.

search_replace_attribute_content.php

As of 5.0.0.0 this script has been removed from the official Matrix releases. This script is for development use only.

The search_replace_attribute_content.php script searches for instances of text within a specified attribute, and replaces it with other specified text, on a group of assets. To use this script, open it in a text editor and replace the strings assigned to $search_for and $replace_with with what you want to search for and replace:

• In the attributes, change $to_process from "Array()" to "Array(assets_to_change)", where "assets_to_change" is a comma-separated list of asset IDs (eg. "Array(30, 31, 35)" ).
• Change the contents of $attribute_name to the attribute you want to search for, and then comment out the first three lines of code (two "echo"s and one "exit;").

This script is located in the /scripts/dev directory of your Squiz Matrix system and takes the following parameter:

• The system root directory.

set_files_unrestricted.php

The set_files_unrestricted.php script sets all files underneath a certain root node to either restricted or unrestricted. Files that are marked unrestricted, have a Status of Live or higher and have public read permissions are directed through the web server using the __data alias instead of being passed through Squiz Matrix.

This script is located in the /scripts directory of your Squiz Matrix system and takes the following parameters:

• The system root directory.

• The asset ID of the root node to change from.
• Either 1 for unrestricted or 0 for restricted.

$ php shrink_matrix_file_assets.php [system_root] 100

Processing 2364 file assets under root node #100

done

There are 2364 files assets that have redundant copies removed!

status_change.php

The status_change.php script changes the status of an asset with the option to cascade the status change to child assets.

This script is located in the /scripts directory of your Squiz Matrix system and takes the following parameters:

• The system root directory.
• The asset ID of the asset to change the status of.
• The Status code of the status to change the asset to. The Status codes that you can use are shown in the table below.
  

  Status	Code	Status	Code
  Archived	1	Up for Review	32
  Under Construction	2	Safe Editing	64
  Pending Approval	4	Safe Editing Pending Approval	128
  Approved to go Live	8	Safe Editing Approved to go Live	256
  Live	16

  Use comma-separated statuses to step through multiple steps.

• Whether or not to cascade the status change to child assets (indicated as y). This parameter is optional.

Example

In the following example, the asset has been set to Safe Editing Approved to go Live then Live, with the change cascaded to all its children.

$ php status_change.php [system_root] 100 256,16 y

 START STATUS CHANGE

 FINISHED  

system_apply_metadata_schema.php

The system_apply_metadata_schema.php script applies a Metadata Schema to a set of specified assets and their children. It will also generate the metadata for these assets.

This script is located in the /scripts directory of your Squiz Matrix system and takes the following parameters:

• The system root directory. This parameter is mandatory.
• A comma-separated list of asset IDs to apply the Metadata Schema to. This parameter is mandatory.
• The asset ID of the Metadata Schema to apply. This parameter is mandatory.
• The asset type to restrict the Metadata Schema application to.
• --access: the access to set when applying the Metadata Schema to the specified assets (either granted or denied). By default, this option is set to granted.
• -nc: no cascade. The applied Metadata Schema will not be inherited by newly created assets under the specified parent.
• -d: deletes the Metadata Schema from the specified assets.
• -f: forces the application of the Metadata Schema, ignoring any existing conflicting applications (granted or denied).
• -u: notifies each asset that it has been updated.
• --max-threads: maximum concurrent processes (maximum of 5).
• --batch-size: the number of asset to process at once. By default, this is set to 50.

Example

In the following example, we are applying our Metadata Schema (#300) to assets #150, #160 and #170, restricting it to Standard Page assets only, and with access denied.

$ php system_apply_metadata_schema.php [system_root] 150,160,170 300 page_standard --access denied -nc -u --max-threads 5 --batch-size 25  
 
Will attempt to set schema 300 to asset(s) 150,160,170.

  Access: denied
  Cascade:
  Force: 
  Update assets: 1 
  Max threads: 5
  Batch size: 25

-- Remaining: 5
-- Remaining: 4
-- Remaining: 3
-- Remaining: 2
-- Remaining: 1
-- Remaining: 0   

system_apply_permissions.php

The system_apply_permissions.php script applies permissions to a set of specified assets and their children.

This script is located in the /scripts directory of your Squiz Matrix system and takes the following parameters:

• The system root directory. This parameter is mandatory.
• A comma-separated list of asset IDs to apply the permissions on. This parameter is mandatory.
• The permission string representing the permissions to change. In this string, r, w and a represent Read, Write and Admin permissions, respectively. The access applied on these permissions is specified as + (grant), - (deny) and / (remove).
  
  For example, the string r+101;w-102;a/103 will grant Read permission for user #101, deny Write permission for user #102 and remove (whether currently granted or denied) Admin permission for user #103. This parameter is mandatory.
• -nc: no cascade. The applied permissions will not be inherited by newly created assets under the specified parent.
• -f: forces the application of the permissions, ignoring any existing conflicting applications (granted or denied).
• --max-threads: maximum concurrent processes (maximum of 5).
• --batch-size: the number of asset to process at once. By default, this is set to 50.

Example

In the following example, we are applying applying permissions to assets #100 and #200. We are granting Read permission to these assets for user #150 and granting Admin permission for user #250.

$ php system_apply_permissions.php [system_root] 100,200 "r+150;a+250" --max-threads 4 --batch-size 40

Will attempt to set permissions to asset(s) 100,200.

  Max threads: 4
  Batch size: 40

-- Remaining: 10
-- Remaining: 9
-- Remaining: 8
-- Remaining: 7
-- Remaining: 6
-- Remaining: 5
-- Remaining: 4
-- Remaining: 3
-- Remaining: 2
-- Remaining: 1
-- Remaining: 0  

system_update_lookups.php

The system_update_lookups.php script refreshes the lookups (Web Paths and Designs) on all the Sites in the system (and their children).

This script is located in the /scripts directory of your Squiz Matrix system and takes the following parameters:

• The system root directory.

• A comma-separated list of asset IDs to restrict refreshing to a list of root nodes (optional).
• --verbose: Display errors that may occur as a result of using this script to update lookups (optional).
• --batch-size: The number of assets to process at once.

Example

php scripts/system_update_lookups.php $(pwd) 612 --verbose

Updating lookups from asset(s): 612.
Batch size: 1000

Determining assets to process...
Updating lookups for 10 assets...
-- Remaining: 10
-- Remaining: 9
-- Remaining: 8
-- Remaining: 7
-- Remaining: 6
-- Remaining: 5
-- Remaining: 4 
-- Remaining: 3
-- Remaining: 2
-- Remaining: 1
-- Remaining: 0
Done 

system_virus_scan.php

The system_virus_scan.php script runs the Virus Checker against the system's data directory, removing any found viruses.

Please note that in order to use this script, your system must have a configured Virus Checker that is enabled on the External Tools Configuration screen. For more information, refer to the External Tools Configuration chapter in the System Configuration manual.

This script is located in the /scripts directory of your Squiz Matrix system and takes the following parameter:

• The system root directory.

webpath_search_and_replace.php