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:
|
To use the Matrix component, the Matrix asset management API must be enabled under System configuration: 
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 Integrations 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 Integrations 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.
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.
Get asset links
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']
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.
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
-
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
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 {page-product-name}"
},
"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 <a href=\"https://marketplace.squiz.net\">Squiz Marketplace.</a> Select the Recipe, add to Squiz Integrations 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
}
]
}
]
}
]
}
}
}