Import/Export Scripts

Last Updated: 25 Feb 2019

This chapter describes the import and export scripts available within Squiz Matrix. These scripts are used to perform import and creation tasks as well as to export asset information from the system.

Bookmarks

create_pages.php

This script allows you to mass create assets, using a .csv file containing your page data.

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

  • The system root directory.
  • The path to the CSV import file.

Example

Its usage is given below:

$ php create_pages.php [system_root] path.to.csv.file 

The format of the .csv file is given below:

asset_name, type_code, parent_assetid, link_type  

For example, using the CSV file below:

Products, page_standard, 23, 1
About Us, page_standard, 23, 1
Contact Us, page_standard, 23, 1
Privacy, page_standard, 23, 1

creates four Standard Page assets name Products, About Us, Contact Us and Privacy, under the asset with the asset id of 23. They will be TYPE_1 linked assets.

csv_to_html_tree.php

This script takes a Comma-Separated Values file (CSV) and converts it to a tree represented by html headings.

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

  • The path to the CSV file to convert.

Example

For example, using the CSV file below:

Fred,John
Fred,John,Mary
Fred,Jack
Fred,Jack,Peter,Jill
Arnie
Arnie,Connor  

The script will output:

<h1>Fred</h1>
  <h2>John</h2>
    <h3>Mary</h3>
  <h2>Jack</h2>
    <h3>Peter</h3>
      <h4>Jill</h4>
<h1>Arnie</h1>
  <h2>Connor</h2>   

csv_to_xml_actions.php

This script creates an import XML file from a Comma-Separated Values file (CSV) and an XML metadata mapping file, allowing you to script the creation of, and setting of metadata to assets of a specified type.

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

  • The system root directory.
  • The path to the CSV file.
  • The path mapping XML file.
  • The ID of the asset to link the new assets under.
  • The type asset to create.

Optionally you can also pass in two flags:

  • unique, which will skip duplicate lines.
  • -ignore_blank, which will ignore fields composed of spaces or dashes.

Example

The mapping XML must follow the following format (items in parentheses ("()") are optional):

<?xml version="1.0" encoding="iso-8859-1" ?>
<!-- template only, usage given below -->
<schema id="[metadata schema asset ID]" name_field="[alias of name field]" (group_by_field_id="[group by field asset ID]" OR group_by_asset_field="[place assets under the asset ID specified in the named column]")>
  <field id="[field 1 asset ID]" alias="[corresponding column name from CSV]" (ignore="1") />
  <field id="[field n asset ID]" alias="[corresponding column name from CSV]" />
</schema> 

For example, an example CSV file is shown below. The first line is the header only.

first_name, address, phone, colour
Page Name 1, Address 1, Phone 1, Red
Page Name 2, Address 2, Phone 2, Green
Page Name 3, Address 3, Phone 3, Blue 

Some examples of the mapping XML files are shown below.

<!-- possible usage, direct ungrouped asset import -->
<schema id="1234" name_field="first_name">
  <field id="1236" alias="address" />
  <field id="1237" alias="phone" />
  <field id="1238" alias="colour" />
</schema>

<!-- OR automatic folder creation and grouping by a specified field... -->
<schema id="1234" group_by_field="1236" name_field="first_name">
  <field id="1235" alias="first_name" />
  <field id="1236" alias="address" />
  <field id="1237" alias="phone" />
  <field id="1238" alias="colour" ignore="1" />
</schema>

<!-- OR to place assets under an associated parent asset with the asset ID
specified in the named column... -->
<schema id="1234" group_by_asset_field="parent_asset_id" name_field="first_name">
  <field id="1235" alias="first_name" />
  <field id="1236" alias="address" />
  <field id="1237" alias="phone" />
  <field id="1238" alias="colour" ignore="1" />
  <field id="1239" alias="parent_asset_id" ignore="1" />
</schema> 

The script will then output:

$ php csv_to_xml_actions.php [system_root] import.csv import.xml 30 folder
- Initialising Matrix...
- Exporting XML...

<?xml version="1.0" encoding="iso-8859-1" ?>
<actions>
-- Creating asset Page Name 1
<action>
  <action_id>page_name_1</action_id>
  <action_type>create_asset</action_type>
  <type_code>folder</type_code>
  <link_type>1</link_type>
  <parentid>30</parentid>
</action>
<action>
  <action_id>set_page_name_1_name</action_id>
  <action_type>set_attribute_value</action_type>
  <asset>[[output://page_name_1.assetid]]</asset>
  <attribute>name</attribute>
  <value>Page Name 1</value>
</action>
<action>
  <action_id>set_page_name_1_path</action_id>
  <action_type>add_web_path</action_type>
  <asset>[[output://page_name_1.assetid]]</asset>
  <path>page_name_1</path>
</action>
<action>
  <action_id>set_page_name_1_metadata_schema</action_id>
  <action_type>set_metadata_schema</action_type>
  <asset>[[output://page_name_1.assetid]]</asset>
  <schemaid>75</schemaid>
  <granted>1</granted>
</action>
<action>
  <action_id>set_page_name_1_metadata_value_80</action_id>
  <action_type>set_metadata_value</action_type>
  <asset>[[output://page_name_1.assetid]]</asset>
  <fieldid>80</fieldid>
  <value>Page Name 1</value>
</action>
<action>
  <action_id>set_page_name_1_metadata_value_81</action_id>
  <action_type>set_metadata_value</action_type>
  <asset>[[output://page_name_1.assetid]]</asset>
  <fieldid>81</fieldid>
  <value>Address 1</value>
</action>
<action>
  <action_id>set_page_name_1_metadata_value_82</action_id>
  <action_type>set_metadata_value</action_type>
  <asset>[[output://page_name_1.assetid]]</asset>
  <fieldid>82</fieldid>
  <value>Phone 1</value>
</action>
<action>
  <action_id>set_page_name_1_metadata_value_83</action_id>
  <action_type>set_metadata_value</action_type>
  <asset>[[output://page_name_1.assetid]]</asset>
  <fieldid>83</fieldid>
  <value>Red</value>
</action>
-- Creating asset Page Name 2
<action>
  <action_id>page_name_2</action_id>
  <action_type>create_asset</action_type>
  <type_code>folder</type_code>
  <link_type>1</link_type>
  <parentid>74</parentid>
</action>
... 

export_to_xml.php

This script takes an asset and all its children, and exports its details to an XML file, able to be used with the import_from_xml.php script. This script will also attempt to preserve attributes and links, such as applied designs, permissions, metadata and nested assets for relevant assets.

The import/export process is not guaranteed across different versions of Squiz Matrix. Caution should be taken when using this script.

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

  • The system root directory.
  • The ID of the asset to export and the ID of the parent asset that the exported asset will be created underneath when being imported. For example, if you want to export asset #3 and store it under asset #35 when it is imported, enter 3:35. You may also export multiple assets, separated by a comma. For example, 30:216,41:311,52:311,80:22. Any linked assets or attributes outside the root node(s)—such as nested assets or users required for permissions—will not be automatically exported, and must be explicitly included.
  • The type of link to create to the new parent (1 for TYPE_1, 2 for TYPE_2, and 4 for TYPE_3).
  • Self contained relations only (optional). This setting allows you to specify the behaviour of exporting notice links, permissions, metadata and workflow settings. By default this is set to 1, which means these settings will only be included if the target assets are also being exported. If this value is set to 0, these settings will be exported regardless and is only recommended if you plan on importing the same data to the same instance of Matrix.

You need to run this script from somewhere where the Apache user is be able to write to $PWD/export, if it can't, the export of the files will fail.

Example

The following example command will export asset #30 (which is a Standard Page) and its children, and create an XML import file (import_page_asset.xml), ready to be imported and linked with a TYPE_1 link underneath asset #100 in another system, with self contained links only:

$ php export_to_xml.php [system_root] 30:100 1 1 > import_page_asset.xml

--------------------------------------
CREATING ASSET: Example Standard Page
--------------------------------------
--------------------------------------
CREATING ASSET: Page Contents
--------------------------------------
--------------------------------------
CREATING ASSET: Content DIV 32
--------------------------------------
--------------------------------------
CREATING ASSET: DIV Content
-------------------------------------- 

import_asset_csv_to_matrix.php

This script can be used to import a CSV file containing asset attributes and metadata values into Squiz Matrix to add, edit or delete an asset.

This script can only be used with assets that can be created without interaction between other asset types. For example, creating a Standard Page with separate Bodycopy DIVs is not supported. However, you can create user accounts and Single Calendar Events assets. No validation is performed on any attributes or metadata fields, so it is assumed that the input provided to this script is correctly formatted.

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

  • The system root directory.
  • The type code of the asset.
  • A CSV file containing the records to import into the assets. An example file structure is as follows:
    Title,First Name,Last Name,Pass,Mail,User
    Mr,John,Smith,matr123,jsmith@email.com,jsmith Mrs,Jane,Doe,matr456,jdoe@email.com,jdoe
  • The ID of the parent asset.
  • The ID of the Metadata Schema to apply to each asset.
  • A CSV file containing attributes name-to-metadata field ID associations. This needs to be in the format metadata field asset ID, supplied field name (e.g. 1234,Title). An example file structure is as follows:
    1234,User
    1235,Title
    1236,First Name
    1237,Last Name
    1238,Mail
  • A CSV file containing attributes name-to-asset attribute field associations. This needs to be in the format supplied field name, asset attribute name, (eg. USER_FIRST_NAME,first_name). An example file structure is as follows:
    User,username
    First Name,first_name
    Last Name,last_name
    Pass,password
    Mail,email 

This script can also optionally take the following:

  • The asset status evaluator of the asset to create. This needs to be either 0 (the asset is not live) or 1 (the asset is live).
  • The unique field name identifier, determining if the asset to be created already exists on the system. Add requests to an asset that already exists on the system will become an edit request. Edit requests to an asset that does not exist on the system will become an add request. Delete requests to an asset that does not exist on the system will be ignored.
  • The operation field name, indicating if the asset is to be added, edited or deleted. This needs to be either A (the asset will be added), E (the asset will be edited) or D (the asset will be deleted). Please note that deletions performed by this script are permanent, by passing the trash.
  • A CSV file containing the items to ignore when performing an edit operation. This needs to be formatted as a single column list.

Example

The usage statement for this script is shown below.

import_asset_csv_to_matrix [system_root] [type_code] [csv import file] [parent id] [schema id] [meta map file] [attr map file] (new assets live) (unique field name) (add edit delete field name) (ignore csv file)  

import_files.php

This script can be used to upload files sitting on the server. These files can be MS Word documents, MS Excel documents, MS PowerPoint documents, PDF's, images, RTF and Text files. You will need to create a directory for each parent asset you will be uploaded file to.

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

  • The system root directory.
  • Path to the import directory.
  • The ID of the parent asset.
  • Restrict file access.

Example

In the import directory specified, create a subdirectory and place the files to be imported in it. The name of the sub directory is the id of the parent asset, which it will be linked to with a TYPE_1 link. For example, with the following import directory:

|- 20
    |- Company Report.doc
    |- Head Office.png
    |- Product.jpg
|- 52
    |- Product Listing.doc
    |- Manual.pdf 

The script will import five file assets. It links Company Report.doc, Head Office.png, and Product.jpg under the asset with the id of 20, and links Product Listing.doc and Manual.pdf under asset with the id of 52.

If a third parameter is provided, the whole folder (including child files and sub folders) will be imported into the system and linked under the asset with the same id as the one that is supplied.

The fourth parameter allows you to specify whether or not to restrict access to the file. By default, unrestricted access will be set to false. To set it to true, pass in a value of 1.

Some examples of its usage is shown below.

$ php import_files.php [system_root] folders_to_import
$ php import_files.php [system_root] folders_to_import 66
$ php import_files.php [system_root] folders_to_import 66 1 

import_folder_structure.php

This script will create Folders in a Squiz Matrix system based on directories in the file system. You can then rename these directories to the asset IDs of the new Folder assets so that you can use the import_file.php script to populate the relevant Folder assets with files.

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

  • The system root directory.
  • Path to the directory containing the folders to be created.
  • The ID of the parent asset under which to create the Folder assets.

A final confirmation will be displayed informing you that the directory names will be modified on the file system. The renaming of directories on the file system is optional. However, if you do not rename the directories, you will not be able to import the files in these directories using the import_file.php script.

This script assumes that all directories are in the specified folders directory and that there are no sub directories.

import_from_xml.php

This script performs actions passed to it in the form of an import script (this can include the creation of assets, setting metadata, or any other action that are available when creating a trigger). An example of an import file can be found at /home/websites/squiz_matrix/scripts/import/xml_example.xml.

This tool is provided as is to help the Matrix community and encourage information sharing. Its use is not covered by a Squiz Service Level Agreement.

The import/export process is not guaranteed across different versions of Squiz Matrix. Caution should be taken when using this script.

Disable Rollback Mode before running this script to improve the performance of your system when processing larger import files. For more information on how to disable rollback, refer to the Rollback Management Script chapter in this manual.

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

  • The system root directory.
  • The import file.
  • --root-node to set a root node and the asset ID of the root to import the assets under. These arguments are optional.
  • --force-create-dependants to tell this script to force create the dependants of imported assest (e.g. Bodycopies on a Standard Page). This is useful if these dependants are not defined in the XML import file. This argument is optional.

This script must be executed from the same directory as the XML import file, in order to read relative file paths.

Example

An example of its usage is shown below.

$ php import_from_xml.php [system_root] xml_example.xml [--root-node 123] [--force-create-dependants]

top_level_user_group                                                  [ OK ]
set_top_level_name                                                    [ OK ]
fred_user                                                             [ OK ]
set_fred_user_name                                                    [ OK ]
sam_user                                                              [ OK ]
set_sam_user_name                                                     [ OK ]
julie_user                                                            [ OK ]
set_julie_user_name                                                   [ OK ] 

import_quiz_from_xml.php

This script is used to import Online Quiz Multiple Choice Questions and Question Groups from an XML file. An example format of the XML file is as follows:

<exportquestions>
<pool Name="Question Group Name">
<question>
<QuestionText>Question Text</QuestionText>
<Option_A points="0">
<Option_Text>Yes</Option_Text>
<Response_Supplement />
</Option_A>
<Option_B points="0">
<Option_Text>No</Option_Text>
<Response_Supplement />
</Option_B>
<Option_C points="1">
<Option_Text>Correct Option</Option_Text>
<Response_Supplement>Sample Response Text</Response_Supplement>
</Option_C>
</question>
</pool>
</exportquestions> 

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

  • The system root directory.
  • The asset ID of the root to import the assets under, e.g. the asset ID of your Online Quiz asset or a questions Folder.
  • The import XML file.

Example

An example usage of this script is shown below.

$ php scripts/import/import_quiz_from_xml.php [system_root] 100 xml_example.xml

*** Import Complete *** 
Questions Created : 20
Groups Created : 3
*** Import Complete ***

update_asset_titles.php

This script is used to change the title attribute on a group of assets (for example file assets), specified in a headerless Comma-Separated Values (CSV) file.

For example:

123, My First File Title
124, My Second File Title
125, My Third File Title

Please note, if an asset specified does not have a title attribute, or the title cannot be set, you will be presented with the option of ignoring the asset, or cancelling the script. Cancelling the script will not revert any changes made thus far.

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

  • The system root directory.
  • The path to the CSV file.

Example

An example of its usage is shown below.

$ php update_asset_titles.php [system_root] path.to.csv.file
PLEASE NOTE: The titles of assets in the "The System" system will be modified by 
this script.
(C)ancel or (O)k? o

- Assigning titles from CSV file...

-- Asset #123: My First File Title
-- Asset #124: Not a file
+-------------------------------------------------------------------------------+
| MySource Warning                                                              |
|-------------------------------------------------------------------------------|
| File : [SYSTEM_ROOT]/core/include/asset.inc                                   |
| Line : 3010                                                                   |
|-------------------------------------------------------------------------------|
| Attribute "title" not found for Asset "Not A File Asset" (#124) [SYS0092]     |
+-------------------------------------------------------------------------------+
* Asset ID 124 does not have a title field, so one cannot be assigned.

User Options ------------
(I)gnore this asset and continue with modification of titles
(C)ancel modification script
i
-- Asset #125: My Third File Title

- All done, stats below:
Asset titles modified : 2
Asset records in file : 3 

tool_export_form_submission_logs.php

This script exports the form submissions of a Custom Form asset to a CSV file. An example format of the exported CSV file is as follows:

Submission Time,User Submitting Form,IP Address,Question 1,Assetid
2011-04-19 09:37:16,12,192.138.2.27,response,509
2011-04-19 09:37:57,12,192.138.2.87,response,512
2011-05-18 13:50:21,12,192.138.14.113,response,633

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

  • The system root directory.
  • The Form Contents asset ID of the Custom Form to export the submissions of.
  • A date range of submissions to export - you must specify both a from and to time. For example, yesterday 23:14:30.
  • The path of the CSV file to export submissions to.

Example

An example of its usage is shown below.

$ php tool_export_form_submission_logs.php [system_root] 1234 "yesterday 0:00:00" "yesterday 23:59:59" path.to.csv.file

Previous Chapter Next Chapter