Matrix

This component is currently in the Beta phase of development. We encourage users to submit feedback, and we will be prioritizing fixes should any issues be encountered.

Choose the right component

Use the flowchart below to assist in choosing the appropriate component for your use case:

Component decision tree

To use the Matrix component, the Matrix asset management API must be enabled under System configuration:

Enable the Matrix asset management API

For more information, documentation is available at https://YOUR-MATRIX-INSTANCE/__management_api/v1/docs.

The Matrix Component provides actions that offer functionality in line with the Matrix Asset Management API’s functionality. API documentation can be found at https://<your.matrix.instance>/\_\_management_api/v1/docs.

To ensure smooth operation in your workflows, it is advisable to employ the same version of the Matrix connector across multiple steps. This helps prevent any potential incompatibility issues.

Credentials

The following credentials are required to authenticate the Squiz Connect Matrix component with your Matrix instance.

Title

The title of your credential.

API endpoint

The endpoint to which the component makes API calls. For example, if your site URL was example.com`, the API endpoint is https://example.com.

Auth token

The API token you use in requests for this content API integration. The token is a unique value and can not be changed.

Generic actions

Create asset

This action allows integrators to directly access the Create asset request of the asset management API.

API documentation is available at https://YOUR-MATRIX-INSTANCE/__management_api/v1/docs#/paths/~1assets/post.

Input fields

Don’t throw error on failed calls

If this option is selected, the action emits any errors as a message rather than throwing a flow error. Select this option to allow the flow to continue when errors occur and deal with the errors within the flow. If this is unselected, the flow halts and invokes its error handler if any error occurs during this action’s execution.

Parent ID

The ID of the parent asset under which the new asset is created.

Asset type

The type of the asset to be created.

Link type

The type of link to the parent which is created when creating the asset. This must be one of the following types:

  • Menu

  • Hidden

  • Invisible

  • Reference

Attributes

Specify any attributes as an object. Read the Input examples section for a sample value.

Metadata values

Specify any metadata schemas as an object. Read the Input examples section for a sample value.

Metadata schemas

Specify any metadata schemas as an array of objects. Read the Input examples section for a sample value.

Although Metadata values and Attributes are not mandatory on the Connect UI, the component will throw an error if both fields are empty.

Get asset

API documentation is available at https://YOUR-MATRIX-INSTANCE/__management_api/v1/docs#/paths/_(1assets)1{assetId}/get.

Input fields

Don’t throw error on failed calls

If this option is selected, the action emits any errors as a message rather than throwing a flow error. Select this option to allow the flow to continue when errors occur and deal with the errors within the flow. If this is unselected, the flow halts and invokes its error handler if any error occurs during this action’s execution.

Asset ID

The ID of the asset to be retrieved.

Output

This action emits a result object containing the body of the response received from the asset management API.

Update asset

This action allows integrators to directly access the Update an asset request of the asset management API.

API documentation is available at https://YOUR-MATRIX-INSTANCE/__management_api/v1/docs#/paths/_(1assets)1{assetId}~1links/get.

Input fields

Don’t throw error on failed calls

If this option is selected, the action emits any errors as a message rather than throwing a flow error. Select this option to allow the flow to continue when errors occur and deal with the errors within the flow. If this is unselected, the flow halts and invokes its error handler if any error occurs during this action’s execution.

Asset ID

The ID of the asset to be updated.

Context ID

Specifying Context ID will set the attributes and metadata in the provided context. If the metadata or attributes are not already contextualized for the provided context ID, then they will be contextualized as part of this operation.

Attributes

Specify any attributes as an object. Read the Input examples section for a sample value.

Metadata values

Specify any metadata schemas as an object. Read the Input examples section for a sample value.

Metadata schemas

Specify any metadata schemas as an array of objects. Read the Input examples section for a sample value.

Output

This action emits a result object containing the body of the response received from the asset management API.

This operation returns a list of links the asset has. By default, it only includes child links. Parents can be included with a parameter.

API documentation is available at https://YOUR-MATRIX-INSTANCE/__management_api/v1/docs#/paths/_(1assets)1{assetId}/patch.

Input fields

Don’t throw error on failed calls

If this option is selected, the action emits any errors as a message rather than throwing a flow error. Select this option to allow the flow to continue when errors occur and deal with the errors within the flow. If this is unselected, the flow halts and invokes its error handler if any error occurs during this action’s execution.

Split result if it’s an array

If this option is selected and, after making the request, the result body is an array, the action emits one message for each element of the array.

Asset ID

The ID of the asset for which links are retrieved.

Direction

Specify direction when iterating the asset tree; down displays children links, and up displays parent links. Defaults to children links.

Asset type codes

Specify an array of one or more asset type codes to filter the links based on the type of the linked asset. Example value: ['content_type_raw_html', 'content_type_wysiwyg']

Output

The action emits a result object containing the body of the response received from the asset management API. If the Split result if it’s an array option is selected and the result body is an array, the action emits one message for each element of the array.

Delete asset

This action allows integrators to directly access the 'Delete asset by id' request of the Asset Management API.

API documentation is available at https://YOUR-MATRIX-INSTANCE/__management_api/v1/docs#/paths/~1assets~1{assetId}/delete

Input fields

Don’t throw error on failed calls

If this option is selected, the action will emit any errors as a message rather than throwing a flow error. Select this option to allow the flow to continue when errors occur and can deal with the errors within the flow. Leave unselected; the flow will halt and invoke its error handler if any error occurs during this action’s execution.

Asset ID

The ID of the asset to be deleted.

Output

The action will emit a result object containing the asset ID, and success fields.

Set status of single asset

This action allows integrators to directly access the 'Set the asset status' request of the Asset Management API.

API documentation is available at https://YOUR-MATRIX-INSTANCE/__management_api/v1/docs#/paths/~1assets~1{assetId}~1status/post.

Input fields

Don’t throw error on failed calls

If this option is selected, the action will emit any errors as a message rather than throwing a flow error. Select this option to allow the flow to continue when errors occur and can deal with the errors within the flow. Leave unselected; the flow will halt and invoke its error handler if any error occurs during this action’s execution.

Asset ID

The ID of the asset which will be used to update that asset’s status.

Status

Specify a status value from the list below in the Enum:

  • archived

  • under_construction

  • pending_approval

  • approved_to_go_live

  • live

  • up_for_review

  • safe_editing

  • safe_editing_pending_approval

  • safe_edit_approved_to_go_live

Output

The action will emit a result object containing the asset ID, new status, and success fields.

Set status of an asset and its children

Using the Get asset links requests cascadingly, this action will traverse the asset tree treating the supplied asset ID as the starting node, fetch all the child assets, and build up an array of all the asset Ids from that asset tree. Furthermore, it traverses this asset IDs - array and updates the status of all the assets in that tree by utilizing the 'Set the asset status' request

API documentation is available at https://YOUR-MATRIX-INSTANCE/__management_api/v1/docs#/paths/~1assets~1{assetId}~1status/post

Input fields

Don’t throw error on failed calls

If this option is selected, the action will emit any errors as a message rather than throwing a flow error. Select this option to allow the flow to continue when errors occur and can deal with the errors within the flow. Leave unselected; the flow will halt and invoke its error handler if any error occurs during this action’s execution.

Split result if it’s an array

If this option is selected and, after making the request, the result body is an array, the action emits one message for each element of the array.

Asset ID

The ID of the asset which will be used to update that asset’s status and all its children.

Status

Specify a status value from the list below in the Enum:

  • archived

  • under_construction

  • pending_approval

  • approved_to_go_live

  • live

  • up_for_review

  • safe_editing

  • safe_editing_pending_approval

  • safe_edit_approved_to_go_live

Output

The action will emit a result object, an array of objects, where each object contains the asset ID, new status, and success fields corresponding to each asset. If the Split result if it’s an array option is checked and the result body is an array, the action will emit one message for each array element.

Use case-specific actions

Get standard page with children

Using the Get asset and Get asset links requests, this action traverses the asset tree of the specified standard page. It builds a JSON object containing the top-level standard page and sub-objects representing the children of the standard page.

An example of how this works is available at https://marketplace.squiz.net/recipes/google-translation-for-matrix.

Input fields

Don’t throw error on failed calls

If this option is selected, the action emits any errors as a message rather than throwing a flow error. Select this option to allow the flow to continue when errors occur and deal with the errors within the flow. If this is unselected, the flow halts and invoke its error handler if any error occurs during this action’s execution.

Asset ID

ID of the standard page asset, which is used as the starting point to build a JSON object of the standard page and its children.

Output

An example of the action’s output is shown in Standard page JSON object.

Create standard page with children from a JSON object

Takes a JSON object that represents a standard page and its children. It iterates through all pages, using the Create asset request to create a standard page under the specified parent asset with a link type of the specified link type. Then it creates each subsequent child specified in the standard page JSON value under this standard page.

An example of how this works is available at https://marketplace.squiz.net/recipes/google-translation-for-matrix.

Read the Input examples section for a sample input value.

Input fields:

Don’t throw error on failed calls

If this option is selected, the action continues if any errors are returned in the response to any calls made to the API. Errors are added to an array in the result output. Select this option to allow the flow to continue when errors occur and deal with the errors within the flow. If this is unselected, the flow halts and invoke its error handler if any error occurs during this action’s execution.

This component does not clean up after any errors. If the action was expected to create four assets, and one call fails, three assets are still created.
Parent ID

The ID of the parent asset under which the new asset is created.

Link type

The type of link to the parent which is created when creating the asset. Must be one of the following types:

  • Menu

  • Hidden

  • Invisible

  • Reference

Standard page JSON

A JSON representation of a standard page to be created. The Get standard page with children action documentation shows more examples of how this object should be structured.

Output

This action emits a result object containing sub-objects denoting all assets created by running the action.

For example:

{
  "result": {
    "errors": [],
    "standard_page": {
      "id": "3067",
      "page_contents": [
        {
          "id": "3068",
          "components": [
            {
              "id": "3069",
              "component_contents": [
                {
                  "id": "3070"
                }
              ]
            },
            {
              "id": "3071",
              "component_contents": [
                {
                  "id": "3072"
                }
              ]
            },
            {
              "id": "3073",
              "component_contents": [
                {
                  "id": "3074"
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

Input examples

Attributes

{
    "name": "Testing Name",
    "short_name": "Test"
}

Metadata values

{
    "target_language_code": {
        "value": "pl"
    }
}

Metadata schemas

[
    {
    "id": "19444",
    "granted": true,
    "cascades": true
    }
]

Standard page JSON object

Example of result from Get standard page with children. The result object can be used as input for Create standard page with children from JSON object:

{
    "result": {
    "standard_page": {
        "id": "20451",
        "type": "page_standard",
        "attributes": {
        "name": "connect test",
        "short_name": "connect test html"
        },
        "status": 16,
        "version": "0.0.40",
        "created": {
        "date_time_unix": 1620869500,
        "user_id": "19204"
        },
        "updated": {
        "date_time_unix": 1635722359,
        "user_id": "19207"
        },
        "published": {
        "date_time_unix": 1620869501,
        "user_id": "19204"
        },
        "status_changed": {
        "date_time_unix": 1620869501,
        "user_id": "19204"
        },
        "metadata_schemas": [
        {
            "id": "19444",
            "granted": true,
            "cascades": true
        }
        ],
        "metadata_values": {
        "seo.robots": {
            "type": "metadata_field_select",
            "value": ""
        },
        "seo.sitemap": {
            "type": "metadata_field_select",
            "value": ""
        },
        "html.title.disable.site": {
            "type": "metadata_field_select",
            "value": []
        },
        "html.title": {
            "type": "metadata_field_text",
            "value": "%asset_name%"
        },
        "canonical.url": {
            "type": "metadata_field_text",
            "value": "%asset_url%"
        },
        "description": {
            "type": "metadata_field_text",
            "value": ""
        },
        "author": {
            "type": "metadata_field_text",
            "value": "Squiz Connect"
        },
        "short.title": {
            "type": "metadata_field_text",
            "value": "%asset_short_name%"
        },
        "top.header.background.image": {
            "type": "metadata_field_related_asset",
            "value": "1494"
        },
        "top.header.title": {
            "type": "metadata_field_text",
            "value": "%asset_name%"
        },
        "top.header.subtitle": {
            "type": "metadata_field_text",
            "value": ""
        },
        "top.header.override": {
            "type": "metadata_field_related_asset",
            "value": ""
        },
        "top.header.hide": {
            "type": "metadata_field_select",
            "value": []
        },
        "page.type": {
            "type": "metadata_field_select",
            "value": ""
        },
        "l.bottom.banner": {
            "type": "metadata_field_select",
            "value": ""
        },
        "dtm.code": {
            "type": "metadata_field_select",
            "value": "true"
        },
        "twitter.card": {
            "type": "metadata_field_text",
            "value": "summary_large_image"
        },
        "og.image": {
            "type": "metadata_field_related_asset",
            "value": "2078"
        },
        "source_language_code": null,
        "target_language_code": {
            "type": "metadata_field_select",
            "value": "zh"
        },
        "status": {
            "type": "metadata_field_select",
            "value": "job_pending"
        }
        },
        "links": [
        {
            "link_id": "26841",
            "major_id": "20451",
            "minor_id": "20452",
            "link_type": "hidden",
            "value": "",
            "sort_order": 0,
            "is_dependent": false,
            "is_exclusive": true
        }
        ],
        "page_contents": [
        {
            "id": "20452",
            "type": "bodycopy",
            "attributes": {
            "name": "Page Contents"
            },
            "status": 16,
            "version": "0.0.12",
            "created": {
            "date_time_unix": 1620869500,
            "user_id": "19204"
            },
            "updated": {
            "date_time_unix": 1635722359,
            "user_id": "19207"
            },
            "published": {
            "date_time_unix": 1620869501,
            "user_id": "19204"
            },
            "status_changed": {
            "date_time_unix": 1620869501,
            "user_id": "19204"
            },
            "metadata_schemas": [],
            "metadata_values": null,
            "links": [
            {
                "link_id": "26842",
                "major_id": "20452",
                "minor_id": "20453",
                "link_type": "hidden",
                "value": "",
                "sort_order": 0,
                "is_dependent": false,
                "is_exclusive": false
            },
            {
                "link_id": "31418",
                "major_id": "20452",
                "minor_id": "23879",
                "link_type": "hidden",
                "value": "",
                "sort_order": 1,
                "is_dependent": false,
                "is_exclusive": false
            },
            {
                "link_id": "31869",
                "major_id": "20452",
                "minor_id": "24255",
                "link_type": "hidden",
                "value": "",
                "sort_order": 2,
                "is_dependent": false,
                "is_exclusive": false
            }
            ],
            "components": [
            {
                "id": "20453",
                "type": "bodycopy_div",
                "attributes": {
                "template_applied": false,
                "comments": "",
                "name": "Component",
                "description": "",
                "attributes": {
                    "content_type": "content_type_wysiwyg",
                    "layout_type": "none",
                    "container_id": "component_20453"
                },
                "persona_evaluation": "any"
                },
                "status": 16,
                "version": "0.0.8",
                "created": {
                "date_time_unix": 1620869501,
                "user_id": "19204"
                },
                "updated": {
                "date_time_unix": 1635722331,
                "user_id": "19207"
                },
                "published": {
                "date_time_unix": 1620869501,
                "user_id": "19204"
                },
                "status_changed": {
                "date_time_unix": 1620869501,
                "user_id": "19204"
                },
                "metadata_schemas": [],
                "metadata_values": null,
                "links": [
                {
                    "link_id": "26843",
                    "major_id": "20453",
                    "minor_id": "20454",
                    "link_type": "hidden",
                    "value": "div_contents",
                    "sort_order": 0,
                    "is_dependent": false,
                    "is_exclusive": true
                }
                ],
                "component_contents": [
                {
                    "id": "20454",
                    "type": "content_type_wysiwyg",
                    "attributes": {
                    "name": "Component Content",
                    "html": "<p>Build websites, portals, mobile apps and more with scalable technology that puts you in the driving seat to connect with customers and innovate at speed.</p><p><img src=\"./?a=41913\" alt=\"logo\" width=\"800\" height=\"800\" /></p>",
                    "htmltidy_status": "wait",
                    "htmltidy_errors": "No error found"
                    },
                    "status": 16,
                    "version": "0.0.8",
                    "created": {
                    "date_time_unix": 1620869501,
                    "user_id": "19204"
                    },
                    "updated": {
                    "date_time_unix": 1635722331,
                    "user_id": "19207"
                    },
                    "published": {
                    "date_time_unix": 1620869501,
                    "user_id": "19204"
                    },
                    "status_changed": {
                    "date_time_unix": 1620869501,
                    "user_id": "19204"
                    },
                    "metadata_schemas": [],
                    "metadata_values": null
                }
                ]
            },
            {
                "id": "23879",
                "type": "bodycopy_div",
                "attributes": {
                "template_applied": false,
                "comments": "",
                "name": "Component",
                "description": "",
                "attributes": {
                    "content_type": "content_type_wysiwyg",
                    "layout_type": "div",
                    "template": "",
                    "container_id": "component_23879"
                },
                "persona_evaluation": "any"
                },
                "status": 16,
                "version": "0.0.2",
                "created": {
                "date_time_unix": 1623723078,
                "user_id": "2233:chan"
                },
                "updated": {
                "date_time_unix": 1623723095,
                "user_id": "2233:chan"
                },
                "published": null,
                "status_changed": {
                "date_time_unix": 1623723078,
                "user_id": "2233:chan"
                },
                "metadata_schemas": [],
                "metadata_values": null,
                "links": [
                {
                    "link_id": "31419",
                    "major_id": "23879",
                    "minor_id": "23880",
                    "link_type": "hidden",
                    "value": "div_contents",
                    "sort_order": 0,
                    "is_dependent": false,
                    "is_exclusive": true
                }
                ],
                "component_contents": [
                {
                    "id": "23880",
                    "type": "content_type_wysiwyg",
                    "attributes": {
                    "name": "Component Content",
                    "html": "<h2>Recipes</h2><div><p>Pre-packaged templates for non-technical users can be downloaded from&nbsp;<a href=\"https://marketplace.squiz.net\">Squiz Marketplace.</a> Simply select the Recipe, add to Squiz Connect and they're ready to go.
Like any recipe, you can add your flavor by customizing them if you need them to work in a specific way before or after deployment.</p></div>",
                    "htmltidy_status": "wait",
                    "htmltidy_errors": "No error found"
                    },
                    "status": 16,
                    "version": "0.0.2",
                    "created": {
                    "date_time_unix": 1623723078,
                    "user_id": "2233:chan"
                    },
                    "updated": {
                    "date_time_unix": 1623723095,
                    "user_id": "2233:chan"
                    },
                    "published": null,
                    "status_changed": {
                    "date_time_unix": 1623723078,
                    "user_id": "2233:chan"
                    },
                    "metadata_schemas": [],
                    "metadata_values": null
                }
                ]
            },
            {
                "id": "24255",
                "type": "bodycopy_div",
                "attributes": {
                "template_applied": false,
                "comments": "",
                "name": "API",
                "description": "",
                "attributes": {
                    "content_type": "content_type_wysiwyg",
                    "layout_type": "none",
                    "container_id": "api_24255"
                },
                "persona_evaluation": "any"
                },
                "status": 16,
                "version": "0.0.4",
                "created": {
                "date_time_unix": 1623992894,
                "user_id": "19204"
                },
                "updated": {
                "date_time_unix": 1635722359,
                "user_id": "19207"
                },
                "published": null,
                "status_changed": {
                "date_time_unix": 1623992894,
                "user_id": "19204"
                },
                "metadata_schemas": [],
                "metadata_values": null,
                "links": [
                {
                    "link_id": "31870",
                    "major_id": "24255",
                    "minor_id": "24256",
                    "link_type": "hidden",
                    "value": "div_contents",
                    "sort_order": 0,
                    "is_dependent": false,
                    "is_exclusive": true
                }
                ],
                "component_contents": [
                {
                    "id": "24256",
                    "type": "content_type_wysiwyg",
                    "attributes": {
                    "name": "Component Content",
                    "html": "<div id=\"component_24162\"><p>3rd container content</p></div>",
                    "htmltidy_status": "wait",
                    "htmltidy_errors": "No error found"
                    },
                    "status": 16,
                    "version": "0.0.4",
                    "created": {
                    "date_time_unix": 1623992895,
                    "user_id": "19204"
                    },
                    "updated": {
                    "date_time_unix": 1635722359,
                    "user_id": "19207"
                    },
                    "published": null,
                    "status_changed": {
                    "date_time_unix": 1623992895,
                    "user_id": "19204"
                    },
                    "metadata_schemas": [],
                    "metadata_values": null
                }
                ]
            }
            ]
        }
        ]
    }
    }
}