JavaScript API

The JavaScript API (JS API) asset is used to enable the execution of core-level Matrix functions using JavaScript, allowing users to create, modify and retrieve content within the system.

These functions are handled on the Details screen of the JavaScript API asset.

Due to cross-domain Ajax requests and session restrictions, the JavaScript API should not be used if your configuration requires cross-domain calls.

Once you have added a JavaScript API asset, you can configure its settings on its associated asset screens. The majority of these screens are similar to those for a standard page. They are described in the Asset screens documentation. This documentation will describe the Details screen, which is different for the JavaScript API.

Details screen

The Details screen allows you to configure the operation parameters and restrictions of the JavaScript API. Read the Asset screens documentation for more information about the Status, Future status, Thumbnail, and Details sections.

Restrictions

This section allows you to set restrictions for the JavaScript API operations.

The fields available are as follows:

Root node: Select a root node to which to restrict the JavaScript API. This will limit the API’s functions to that specific root node. For example, if your system contains two sites, Site 1 and Site 2, selecting Site 1 in this field will only allow the JavaScript API to access the content of that specific site. To select additional root nodes, select more…. To delete a root node from the list, select clear. This field is mandatory.
Asset types to create: Select asset types to restrict the assets created by the createAsset operation. For example, selecting Cart in this field will mean that the createAsset operation will only create cart assets. To select more than one asset type, click on the more… button. An additional list will appear on the screen. To remove an asset type from the list, then select clear and then select Save.
Parent types: Select asset types to restrict the assets that can act as parents when using creation, linking, and moving operations. For example, selecting Site in this field will mean that an operation involving a parent asset, such as createAsset or createLink, will only allow the JavaScript API to use site assets as the parent asset.
Allow attributes on create: Select whether additional attributes can be added when creating assets using the createAsset operation. If this field is set to Yes, the attribute parameter of the createAsset operation can be used to define attributes to be added. For example, a news item asset can be created with the attribute parameter as contact_name=john&contact_phone=01234. This will set the contact name attribute of the news item to john and the contact phone attribute to 01234. By default, this field is set to No.
Return JSON: Select whether to return result codes through JSON in response to the JavaScript API’s operations. You may choose to disable the return of JSON to prevent users from being able to view information, such as asset ids and attribute values, from certain operations. By default, this field is set to Yes.
Ignore permissions: Select whether to ignore permissions when creating assets using the createAsset, cloneAsset, and createFileAsset operations. If this field is set to Yes, permissions will not be checked when performing these functions. This means that a user without the appropriate write access would still create an asset within the system. By default, this field is set to No.
Force simple edit: By default, the function calls of the JavaScript API will act as if made on the administration interface of Matrix. This means that any generated URLs, for example, in a workflow email, will contain the _admin suffix. This field allows you to force function calls to act as if made in the inline edit mode, meaning that any URLs generated by these calls would use the _edit suffix instead of the _admin suffix. By default, this field is set to No.
Use enhanced JS API: Leave this as Yes. Setting it to No will use the standard mode on the JS API, which has been deprecated as of version 5.1.0.0 and is a much inferior version.
Allow batching requests: This operation allows you to group multiple functions on the JS API into a single request. By default, this field is set to No. For more information, refer to the batching requests section in this documentation.

API settings

This section contains the API key used for the JavaScript API asset. The squiz_matrix_api construct defined on the API uses this key to allow the JavaScript API assets to function.

For more information, refer to the [Basic JavaScript API implementation] documentation in this documentation.

Operation Paramters

Core

createAsset

The createAsset operation will create an asset in the system.

Table 1. Request
Parameter	Comment	Type
parent_id	Parentid of the new parent.	integer
type_code	Type code of the new asset.	string
asset_name	Name for the new asset.	string
link_type	Type of link to create (See Note 1 below).	string/integer
link_value	Value of the link.	string
sort_order	Order in the tree.	integer
is_dependant	Dependant to parent.	integer
is_exclusive	Exclusive to parent.	integer
extra_attributes	Allows additional attributes.	integer
attributes	String of additional query string containing key/pair values (See Note 2 below).	string
dataCallback	Custom callback function.	function

Note 1

The link_type parameter can accept the value as a string or its integer value:

String	Integer
"SQ_LINK_TYPE_1"	1
"SQ_LINK_TYPE_2"	2
"SQ_LINK_TYPE_3"	4
"SQ_LINK_NOTICE"	8

Note 2

This parameter requires the Allow Attributes on Create field enabled. For more information, refer to the Restrictions section of this chapter.

Table 2. Response
Response
name
id
link_id

Example 1. Example

js_api.createAsset({
   "parent_id":100,
   "type_code":"comment",
   "asset_name":"blog comment",
   "link_type":"SQ_LINK_TYPE_1",
   "link_value":"link value",
   "sort_order":1,
   "is_dependant":0,
   "is_exclusive":0,
   "extra_attributes":1,
   "attributes":"comment=comment goes here&rating=5.0",
   "dataCallback":customDataCallbackFunc
})

createFileAsset

The createFileAsset operation will create a blank File type asset (PDF file, MP3, etc.) to which users will upload their file.

Table 3. Request
Parameter	Comment	Type
parentID	Parentid of the new parent.	string
type_code	Type code of the new asset (defaults to 'File').	string
friendly_name	Name of the asset being created.	string
link_type	Type of link to create for File asset (See Note 1 below).	string/integer
link_value	Value of the link to create to parent for this new asset.	string
dataCallback	Custom callback function.	function

Note 1

The link_type parameter can accept the value as a string or its integer value:

String	Integer
"SQ_LINK_TYPE_1"	1
"SQ_LINK_TYPE_2"	2
"SQ_LINK_TYPE_3"	4
"SQ_LINK_NOTICE"	8

Table 4. Response
Response
`{"123":"New File Asset (#123) 'File' of type_code 'pdf_file' created successfully"}`

Example 2. Example

js_api.createFileAsset({
   "parentID":"100",
   "type_code":"pdf_file",
   "friendly_name":"my-file",
   "link_type":"SQ_LINK_TYPE_1",
   "link_value":"link value",
   "dataCallback":customDataCallbackFunc
})

cloneAsset

This operation will clone an asset under a specified parent.

Table 5. Request
Parameter	Comment	Type
asset_id	Asset ID of the asset to clone.	string
new_parent	Asset ID of the parent under which to clone.	string
clone_name	Name for the new clone asset.	string
clone_num	Number of clones to create.	integer
new_position	Position to place newly created assets under the parent.	integer
link_type	Link type of the cloned asset: SQ_LINK_TYPE_1 SQ_LINK_TYPE_2 SQ_LINK_TYPE_3 SQ_LINK_NOTICE	string
link_value	Link value of the cloned asset.	string
dataCallback	Custom callback function.	function

Response

Table 6. Response
Response
`success => Home Page (#100) has been successfully cloned to #200, #204 assetid => 100 newParent => 200 clonedAssets => [object Object],[object Object] 0 => [object Object] id => 200 link_id => 8463 name => Home Page 1 => [object Object] id => 204 link_id => 8467 name => Home Page`

success => Home Page (#100) has been successfully cloned to #200, #204
assetid => 100
newParent => 200
clonedAssets => [object Object],[object Object]
0 => [object Object]
id => 200
link_id => 8463
name => Home Page
1 => [object Object]
id => 204
link_id => 8467
name => Home Page

Example 3. Example

js_api.cloneAsset({
   "asset_id":"100",
   "new_parent":"240",
   "clone_name":"name",
   "clone_num":2,
   "new_position":1,
   "link_type":"SQ_LINK_TYPE_2",
   "link_value":"new value",
   "dataCallback":customDataCallbackFunc
})

getGeneral

The getGeneral operation will return the general information of an asset.

Table 7. Request
Parameter	Comment	Type
asset_id	ID of the asset for which to get information.	string
get_attributes	If we are getting non standard attribute values of the assets (FALSE by default).	boolean
dataCallback	Custom callback function.	function

Table 8. Response
Response
name
short_name
id
type_code
type
icon_path
data_path
web_path
status
created
created_userid
created_username
updated
updated_userid
updated_username
published
published_userid
published_username
status_changed
status_changed_userid
status_changed_username

Example 4. Example

js_api.getGeneral({
   "asset_id":"100",
   "get_attributes":1,
   "dataCallback":customDataCallbackFunc
})

getChildCount

The getChildCount operation will return a count of the number of direct children or dependants of an asset.

Table 9. Request
Parameter	Comment	Type
asset_id	ID of the asset of which to get children.	string
level	Number of levels to return, default all.	number
dataCallback	Custom callback function.	function

Table 10. Response
Response
child_count

Example 5. Example

js_api.getChildCount({
   "asset_id":"100",
   "level":5,
   "dataCallback":customDataCallbackFunc
})

getAssetTypes

This operation will return the asset type codes of assets within the system.

Table 11. Request
Parameter	Comment	Type
dataCallback	Custom callback function.	function

Table 12. Response
Response
[source] ---- "asset_type" { type_code version name instantiable allowed_access parent_type dir customisation description lvl }, … ----

Example 6. Example

js_api.getAssetTypes({
   "dataCallback":customDataCallbackFunc
})

getAttributes

This operation will return the attributes of an asset.

Table 13. Request
Parameter	Comment	Type
asset_id	ID of the asset for which to get information.	string
dataCallback	Custom callback function.	function

Table 14. Response
Response
`{"name":"Home Page","short_name":"Home"}`

Example 7. Example

js_api.getAttributes({
   "asset_id":"100",
   "dataCallback":customDataCallbackFunc
})

setAttribute

The setAttribute operation will set a single attribute value.

Table 15. Request
Parameter	Comment	Type
asset_id	ID of the asset for which to get information.	string
attr_name	Name of the attribute to change.	string
attr_val	Value to change the attribute to.	string
dataCallback	Custom callback function.	function

Table 16. Response
Response
`["Attribute "short_name" has been successfully set to "Home" for Asset "Home Page" (#1234)"]`

Example 8. Example

js_api.setAttribute({
   "asset_id":"100",
   "attr_name":"name",
   "attr_val":"new title",
   "dataCallback":customDataCallbackFunc
})

js_api.setAttribute({
   "asset_id":"100",
   "attr_name":"html",
   "attr_val":"content",
   "dataCallback":customDataCallbackFunc
})

setMultipleAttributes

The setMultipleAttributes operation will set multiple attribute values.

Table 17. Request
Parameter	Comment	Type
asset_id	ID of the asset for which to get information.	string
field_info (attr_name, attr_val)	Attribute name and their respect value.	array
dataCallback	Custom callback function.	function

Table 18. Response
Response
`["Attribute "short_name" has been successfully set to "Home" for Asset "Home Page"(#1234)","Attribute … ]`

Example 9. Example

js_api.setMultipleAttributes({
   "asset_id":"100",
   "field_info":{
      "name":"New Name",
      "short_name":"New Short Name"
   },
   "dataCallback":customDataCallbackFunc
})

getLocksInfo

The getLocksInfo operation will return the general information of locks on an asset.

Table 19. Request
Parameter	Comment	Type
asset_id	ID of the asset for which to get locks.	string
screen_name	The screen lock type for which to get locks.	string
dataCallback	Custom callback function.	function

Table 20. Response
Response
`[""settings" locks are held by User "Root User" (#12) for Asset "Home" (#1234). This is due to expire in 3 minutes and 25 seconds"]`

Available screen name (lock types) that you can get lock info for are:

String	Integer
"settings"	1
"attributes"	2
"permissions"	4
"links"	8
"workflow"	16
"metadata"	32
"lookups"	64
"roles"	256

Example 10. Example

js_api.getLocksInfo({
   "asset_id":"100",
   "screen_name":"settings",
   "dataCallback":customDataCallbackFunc
})

acquireLock

The acquireLock operation will acquire the lock of an asset screen (or update the lock if it has already been acquired by the user).

Table 21. Request
Parameter	Comment	Type
asset_id	ID of the asset for which to get locks.	string
screen_name	The screen for which to get locks.	string
dependants_only	Whether dependants only or all children. Defaults to true.	boolean
force_acquire	Whether to attempt to forcibly acquire the lock. Defaults to false.	boolean
dataCallback	Custom callback function.	function

Table 22. Response
Response
`[""settings" locks are now acquired for Asset "Home" (#1234)"]`

Example 11. Example

js_api.acquireLock({
   "asset_id":"100",
   "screen_name":"metadata",
   "dependants_only":0,
   "force_acquire":1,
   "dataCallback":customDataCallbackFunc
})

The Details Screen of an Asset consists of both the Attributes and Links locks.

releaseLock

The releaseLock operation will release the lock of an asset screen.

Table 23. Request
Parameter	Comment	Type
asset_id	ID of the asset for which to release locks.	string
screen_name	The screen for which to release locks.	string
dataCallback	Custom callback function.	function

Table 24. Response
Response
`[""settings" locks are now released for Asset "Home" (#1234)"]`

Example 12. Example

js_api.releaseLock({
   "asset_id":"100",
   "screen_name":"links",
   "dataCallback":customDataCallbackFunc
})

trashAsset

The trashAsset operation will send an asset to the Trash.

Table 25. Request
Parameter	Comment	Type
asset_ids	ID of the asset(s) to delete.	array / string
dataCallback	Custom callback function.	function

Table 26. Response
Response
`["Asset "Home" (#1234) successfully moved to Trash"] `

Example 13. Example

js_api.trashAsset({
   "asset_ids":[
      "100",
      "101",
      "102"
   ],
   "dataCallback":customDataCallbackFunc
})

getKeywordsReplacements

The getKeywordsReplacements operation will return the standard and global keyword replacements of an asset.

Table 27. Request
Parameter	Comment	Type
asset_id	Id of the asset for which to get replacements.	string
keywords_array	Array of keywords for which to get replacements.	array
null_if_empty	Whether to return null for non-replaced keywords.	boolean
dataCallback	Custom callback function.	function

Table 28. Response
Response
keyword (for example; `"asset_assetid":"1234"`)

Example 14. Example

js_api.getKeywordsReplacements({
   "asset_id":"100",
   "keywords_array":[
      "%asset_name%",
      "%asset_assetid%"
   ],   "null_if_empty":true,
   "dataCallback":customDataCallbackFunc
})

setAssetStatus

The setAssetStatus operation will set the status of an asset and its dependants (with the option of cascading the status to child assets).

Table 29. Request
Parameter	Comment	Type
asset_id	ID of the asset for which to set the status.	string
status	The status to which the asset is to be set.	integer
cascade	Whether to cascade the status to non-dependant children (false by default)	boolean
workflow_stream	Workflow stream to be passed.	string
userlog	The user workflow log message	string
dataCallback	Custom callback function.	function

Table 30. Response
Response
`["Status for Asset "Home" (#1234) has been changed successfully to Live"]`

You can view the status numbers for the status parameter in the Concepts documentation.

Example 15. Example

js_api.setAssetStatus({
   "asset_id":"100",
   "status":32,
   "cascade":1,
   "workflow_stream":"altstream",
   "userlog":"log message",   "dataCallback":customDataCallbackFunc
})

getWebPath

The getWebPath operation will return the web path(s) of an asset.

Table 31. Request
Parameter	Comment	Type
asset_id	ID of the asset for which to get web paths.	string
dataCallback	Custom callback function.	function

Table 32. Response
Response
webpath

Example 16. Example

js_api.getWebPath({
   "asset_id":"100",
   "dataCallback":customDataCallbackFunc
})

setWebPath

The setWebPath operation will set the web path of an asset.

Table 33. Request
Parameter	Comment	Type
asset_id	ID of the asset for which to get web paths.	string
paths	New web paths to be assigned to asset.	array
auto_remap	Whether to auto-remap (default to True).	boolean
dataCallback	Custom callback function.	function

Table 34. Response
Response
webpath

Example 17. Example

js_api.setWebPath({
   "asset_id":"100",
   "paths":[
      "about-us",
      "about",
      "info"
   ],
   "auto_remap":1,
   "dataCallback":customDataCallbackFunc
})

getRoles

The getRoles operation will return the roles of an asset.

Table 35. Request
Parameter	Comment	Type
asset_id	The AssetID of the asset to which the role is applied.	integer
role_id	The AssetID of the roles that are applied.	integer
user_id	The AssetID of the user performing the role.	integer
include_assetid	Whether to include the AssetID in the returned array.	boolean
include_globals	Whether to query the role view which includes expanded Global roles as individual users.	boolean
expand_groups	When TRUE, any groups defined within a role will be replaced with the UserIDs in that group. If FALSE, return the GroupIDs.	boolean
inc_dependants	If FALSE, filter out dependant assets.	boolean
include_parents	When UserID is specified; this will return role information for roles that a user has inherited from its parent groups, as well as those directly applied on the user.	boolean
type_codes	When `include_assetid` is TRUE; filter the returned asset IDs by a specified type code.	array
strict_type_code	Whether to use strict type code for type code filter, i.e. type codes not inherited.	boolean
dataCallback	Custom callback function.	function

Table 36. Response
Response
roleid =⇒ userid

Example 18. Example

js_api.getRoles({
   "asset_id":100,
   "role_id":150,
   "user_id":70,
   "include_assetid":1,
   "include_globals":1,
   "expand_groups":1,
   "inc_dependants":0,
   "include_parents":0,   "type_codes":"page",   "strict_type_code":0,   "dataCallback":customDataCallbackFunc
})

setContentOfEditableFileAsset

The setContentOfEditableFileAsset operation will set the content of an editable File type asset (CSS File, XML File, Text File, XSL File, JS File).

Locks need to be acquired on the asset before setting content.

Table 37. Request
Parameter	Comment	Type
asset_id	ID of the asset for which to update content.	string
content	New content of the asset.	string
dataCallback	Custom callback function.	function

Table 38. Response
Response
`["Content of Asset "File" (#1234) successfully updated"]`

Example 19. Example

js_api.setContentOfEditableFileAsset({
   "asset_id":"100",
   "content":"content of file",
   "dataCallback":customDataCallbackFunc
})

updateFileAssetContent

The updateFileAssetContent operation is automatically enabled on the JS API Details screen together with the Set File Content function will update the contents of a File type asset by passing the data in a Base64 encoded string.

Locks need to be acquired on the asset before setting content.

Table 39. Request
Parameter	Comment	Type
asset_id	ID of the File asset for which to update content.	string
content	Base64 encoded string of content for the File asset.	string
dataCallback	Custom callback function.	function

Table 40. Response
Response
`{success: "Content of the file asset file.jpg(#100) successfully updated", assetid: "100"}`

Example 20. Example

js_api.updateFileAssetContent({
   "asset_id":"100",
   "content":"/9j/4QDGRXhpZgAASUkqAAgAA...",
   "dataCallback":customDataCallbackFunc
})

importAssetsFromXML

The importAssetsFromXML operation will import assets under a specified root node from a structured XML file.

Table 41. Request
Parameter	Comment	Type
asset_id	Asset under which the assets are to be imported.	string
filePath	Path to file on the file system.	string
dataCallback	Custom callback function.	function

Table 42. Response
Response

Example 21. Example

js_api.importAssetsFromXML({
   "asset_id":"100",
   "filePath":"/path/to/our/xml/file/import_from_this_file.xml",
   "dataCallback":customDataCallbackFunc
})

executeHTMLTidy

The executeHTMLTidy operation will execute HTML Tidy on the content of a passed string.

Table 43. Request
Parameter	Comment	Type
content	String content to be cleaned up.	string
dataCallback	Custom callback function.	function

Table 44. Response
Response

Example 22. Example

js_api.executeHTMLTidy({
   "content":"<h1>heading</h2>",
   "dataCallback":customDataCallbackFunc
})

showDifference

The showDifference operation will compare the content of two different assets.

Table 45. Request
Parameter	Comment	Type
assetid_1	Asset ID of the first asset to compare.	string
assetid_2	Asset ID of the second asse to compare.	string
paint_layout_1	Asset ID of the Paint Layout to apply to Asset 1.	string
paint_layout_2	Asset ID of the Paint Layout to apply to Asset 2.	string
dataCallback	Custom callback function.	function

Table 46. Response
Response
`{"success": Show Diff Content… }`

Example 23. Example

js_api.showDifference({
   "assetid_1":"100",
   "assetid_2":"200",
   "paint_layout_1":"340",
   "paint_layout_2":"350",
   "dataCallback":customDataCallbackFunc
})

validateActiveUser

The validateActiveUser operation will validate a specified user and can optionally return the asset IDs of user groups to which the user belongs.

Table 47. Request
Parameter	Comment	Type
username	The user to validate.	string
get_groups	Whether to return the user groups to which the user belongs.	boolean
dataCallback	Custom callback function.	function

Table 48. Response
Response
`{User: "Found"}` OR `['100,'101,'11']`

Example 24. Example

js_api.validateActiveUser({
   "username":"User",
   "get_groups":1,   "dataCallback":customDataCallbackFunc
})

getFileIndexingComponents

The getFileIndexingComponents operation will fetch indexing contents for file assets that would normally be served by Apache.] The returned data includes details about metadata values, file properties and permission details.

Table 49. Request
Parameter	Comment	Type
asset_urls	The URL of the file for which to return indexing content.	string
dataCallback	Custom callback function.	function

Table 50. Response

Response

	{
        metadata => {
            date => 2015-10-2410:53:13,
        }
        security_locks => '7',
        SQUIZASSETYPE => thumbnail,
        last_modified => 2015-04-27T13:38:05,
        file_title => thumbnail_for_user,
        file_name => img.jpg,
        author_name => Root User,
        author_id => 12,
        created => 2015-04-23T10:44:34,
}

Example 25. Example

js_api.getFileIndexingComponents({
   "asset_urls":"http://www.example.com/__data/assets/thumbnail/0019/955/img.jpg",
   "dataCallback":customDataCallbackFunc
})

sortAssetChildren

The sortAssetChildren operation will sort child assets of a particular asset in a specific order and sorted by a specific value.

Table 51. Request
Parameter	Comment	Type
parent_id	Asset ID you want to sort the child assets for.	string / int
sort_by	Standard asset fields or keywords by which to sort.	string
sort_direction	Direction in which to sort; either ascending or descending	string
sort_type	The sorting type to use.	integer
dataCallback	Custom callback function.	function

The sort_type options are based on the PHP sort() function’s sort_flags parameter and are passed in as integer values representing the type.

The values are as follows:

Type	Value
Regular	0
Numeric	1
String	2
Natural	6

Example 26. Example

js_api.sortAssetChildren({
   "parent_id":     "100",
   "sort_by":       "type_code",
   "sort_direction: "ascending",
   "sort_type":     0,
   "dataCallback":  customDataCallbackFunc
})

Linking

createLink

The createLink operation will create a link in the system.

Table 52. Request
Parameter	Comment	Type
parent_id	Major asset ID being linked.	integer
child_id	Minor asset ID being linked.	integer
link_type	Type of link to create (See Note below).	string/integer
link_value	Value of the link.	string
sort_order	Order in the tree.	integer
is_dependant	Dependant to parent	integer
is_exclusive	Exclusive to parent	integer
dataCallback	Custom callback function.	function

The link_type parameter can accept the value as a string or its integer value:

String	Integer
"SQ_LINK_TYPE_1"	1
"SQ_LINK_TYPE_2"	2
"SQ_LINK_TYPE_3"	4
"SQ_LINK_NOTICE"	8

Example 27. Example

js_api.createLink({
   "parent_id":100,
   "child_id":120,
   "link_type":"SQ_LINK_TYPE_2",
   "link_value":"link_value",
   "sort_order":1,
   "is_dependant":1,
   "is_exclusive":0,
   "dataCallback":customDataCallbackFunc
})

removeLink

The removeLink operations will remove a single link between a parent and child asset.

Table 53. Request
Parameter	Comment	Type
parent_id	ID of the parent.	string
child_id	ID of the child.	string
link_type	Type of link being looked for SQ_LINK_TYPE_1 SQ_LINK_TYPE_2 SQ_LINK_TYPE_3 SQ_LINK_NOTICE	string
link_value	Value of link we are looking for ('' by default).	string
dataCallback	Custom callback function.	function

Example 28. Example

js_api.removeLink({
   "parent_id":"100",
   "child_id":"120",
   "link_type":"SQ_LINK_TYPE_1",
   "link_value":"link value",
   "dataCallback":customDataCallbackFunc
})

removeMultipleLinks

The removeMultipleLinks operations will remove a multiple links between a parent and child asset.

Table 54. Request
Parameter	Comment	Type
link_info (parent, child, link_type, link_value).	Array of `link_info`.	json object
dataCallback	Custom callback function.	function

Table 55. Response
Response

Example 29. Example

js_api.removeMultipleLinks({
   "link_info":{
      "links":[
         {
            "parent":"100",
            "child":"120",
            "link_type":"SQ_LINK_TYPE_1",
            "link_value":"link value"
         },
         {
            "parent":"200",
            "child":"220",
            "link_type":"SQ_LINK_TYPE_1",
            "link_value":"link value"
         }
      ]
   },
   "dataCallback":customDataCallbackFunc
})

moveLink

The moveLink operation will move a link from one parent to another.

Table 56. Request
Parameter	Comment	Type
old_parent_id	ID of the old parent.	string
child_id	ID of the child.	string
old_link_type	Type of link we are search for between given assets SQ_LINK_TYPE_1 SQ_LINK_TYPE_2 SQ_LINK_TYPE_3 SQ_LINK_NOTICE	string
old_link_value	Value of link we are searching for between given assets ('' by default).	string
new_parent_id	ID of the new parent.	string
new_link_type	Type of link to use SQ_LINK_TYPE_1 SQ_LINK_TYPE_2 SQ_LINK_TYPE_3 SQ_LINK_NOTICE	string
new_link_value	Value of link to use ('' by default).	string
new_position	The new position.	string
dataCallback	Custom callback function.	function

Table 57. Response
Response
link_id

Example 30. Example

js_api.moveLink({
   "old_parent_id":"100",
   "child_id":"120",
   "old_link_type":"SQ_LINK_TYPE_1",
   "old_link_value":"old link value",
   "new_parent_id":"200",
   "new_link_type":"SQ_LINK_TYPE_1",
   "new_link_value":"new link value",
   "new_position":"1",
   "dataCallback":customDataCallbackFunc
})

updateLink

The updateLink operation will update a single link in the system.

Table 58. Request
Parameter	Comment	Type
parent_id	ID of the parent.	string
child_id	ID of the child.	string
existing_link_type	Existing link type between the assets SQ_LINK_TYPE_1 SQ_LINK_TYPE_2 SQ_LINK_TYPE_3 SQ_LINK_NOTICE	string
existing_link_value	Existing link value between the assets ('' by default).	string
link_type	Link type to be updated to SQ_LINK_TYPE_1 SQ_LINK_TYPE_2 SQ_LINK_TYPE_3 SQ_LINK_NOTICE	string
link_value	Link value to be updated to ('' by default).	string
sort_order	The new position.	string
locked	The asset link lock status (locked by default).	string
dataCallback	Custom callback function.	function

Table 59. Response
Response
`["success":"Link #"500 " between Asset "Home" (#123) and Asset "Contact" (#456) has been updated"]`

Example 31. Example

js_api.updateLink({
   "parent_id":"100",
   "child_id":"120",
   "existing_link_type":"SQ_LINK_TYPE_1",
   "existing_link_value":"current link value",
   "link_type":"SQ_LINK_TYPE_2",
   "link_value":"new link value",
   "sort_order":"10",
   "locked":"1",
   "dataCallback":customDataCallbackFunc
})

updateMultipleLinks

The updateMultipleLinks operation will update multiple links in the system.

Table 60. Request
Parameter	Comment	Type
link_info (parent, child, existing_link_type, existing_link_value, link_type, link_value, sort_order, link_lock)	Array of link_info	json object
dataCallback	Custom callback function.	function

Table 61. Response
Response
`[{"success":"Link #"500 " between Asset "Home" (#123) and Asset "Contact" (#456) has been updated"},{"success":"Link … ]`

Example 32. Example

js_api.updateMultipleLinks({
   "link_info":{
      "links":[
         {
            "parent":"100",
            "child":"120",
            "existing_link_type":"SQ_LINK_TYPE_1",
            "existing_link_value":"old link value",
            "link_type":"SQ_LINK_TYPE_2",
            "link_value":"new link value",
            "sort_order":"5",
            "link_lock":"1"
         },
         {
            "parent":"200",
            "child":"220",
            "existing_link_type":"SQ_LINK_TYPE_2",
            "existing_link_value":"old link value",
            "link_type":"SQ_LINK_TYPE_1",
            "link_value":"new link value",
            "sort_order":"2",
            "link_lock":"0"
         }
      ]
   },
   "dataCallback":customDataCallbackFunc
})

getLinkId

The getLinkId operation will return the link id between a parent and child asset.

Table 62. Request
Parameter	Comment	Type
parent_id	ID of the parent.	string
child_id	ID of the child.	string
link_type	Type of link we are looking for SQ_LINK_TYPE_1 SQ_LINK_TYPE_2 SQ_LINK_TYPE_3 SQ_LINK_NOTICE	string
link_value	Value of link we are looking for ('' by default).	string
all_info	If we want all the link information or just linkid.	string
dataCallback	Custom callback function.	function

Table 63. Response
Response
link_id

Example 33. Example

js_api.getLinkId({
   "asset_id":"100",
   "child_id":"120",
   "link_type":"SQ_LINK_TYPE_!",
   "link_value":"link_value",
   "all_info":1,
   "dataCallback":customDataCallbackFunc
})

Permissions

getPermissions

The getPermissions operation will return the permissions of an asset.

Table 64. Request
Parameter	Comment	Type
asset_id	ID of the asset from which to get permissions.	string
level	Permission level: 1 (READ) 2 (WRITE) 3 (ADMIN)	string
dataCallback	Custom callback function.	function

Table 65. Response
Response
"granted/denied" : { "user_id" : { id name user_name type }, "group_id" : { id name type users { "user_id" : { id name user_name type }, … }, ….

Example 34. Example

js_api.getPermissions({
   "asset_id":"100",
   "level":"3",
   "dataCallback":customDataCallbackFunc
})

setPermission

The setPermission operation will set a user or user group permission on a specified asset.

Table 66. Request
Parameter	Comment	Type
asset_id	The ID of the asset on which to set permissions.	string/integer
user_ids	The ID of the user or user group for which to apply permissions.	string/integer
granted	The permission type to apply: 1 (Grant) 0 (Deny) -1 (Revoke)	integer
level	The permissions level to apply: 1 (Read) 2 (Write) 3 (Admin)	integer
cascades	Whether to automatically cascade permissions to newly created child assets.	boolean
dependants_only	Whether to apply permission changes to dependant assets only.	boolean
dependant_parents	Whether to apply permission changes to dependant parents instead.	boolean
dataCallback	Custom callback function.	function

Table 67. Response
Response
`{"success":"Permission changes made successfully","assetids":["123"],"permission":"3","granted":"1","cascades":true}`

Example 35. Example

js_api.setPermission({
   "asset_id":"123",
   "user_ids":"456",
   "granted":"1",
   "level":"3",
   "cascades":"true",
   "dependants_only":"true",
   "dependants_parents":"false",
   "dataCallback":customDataCallbackFunc
})

Workflow

getWorkflowSchema

The getWorkflowSchema operation will return any applied or denied workflow schemas on an asset.

Table 68. Request
Parameter	Comment	Type
asset_id	ID of the asset for which to get workflow.	string
granted	The status of workflow to get (default to Null). True (granted) False (denied) Null (get all)	boolean
running	If to only get workflows that are running (default to False)	boolean
dataCallback	Custom callback function.	function

Table 69. Response
Response
granted / running

Example 36. Example

js_api.getWorkflowSchema({
   "asset_id":"100",
   "granted":1,
   "running":0,
   "dataCallback":customDataCallbackFunc
})

Traversing

getParents

The getParents operation will return the parents of an asset.

Table 70. Request
Parameter	Comment	Type
asset_id	ID of the asset for which to get parents.	sting
levels	Number of levels to return.	number
type_codes	Asset type code wanted.	array
link_types	Link type of links being looked for: SQ_LINK_TYPE_1 SQ_LINK_TYPE_2 SQ_LINK_TYPE_3 SQ_LINK_NOTICE	array
link_values	Link values allowed on the asset returned.	array
get_attributes	For non-standard attribute values of the assets (FALSE by default).	boolean
dataCallback	Custom callback function.	function

Table 71. Response
Response
`"0" { name short_name id type_code type icon_path data_path web_path status created created_userid created_username updated updated_userid updated_username published published_userid published_username status_changed status_changed_userid status_changed_username link_id link_type is_dependant is_exclusive sort_order link_value locked }, ...`

Example 37. Example

js_api.getParents({
   "asset_id":"100",
   "levels":3,
   "type_codes":[
      "page_standard",
      "site"
   ],
   "link_types":[
      "SQ_LINK_TYPE_1",
      "SQ_LINK_TYPE_2"
   ],
   "link_values":[
      "value1",
      "value2"
   ],
   "get_attributes":1,
   "dataCallback":customDataCallbackFunc
})

getChildren

The getChildren operation will return the dependant, non-dependant and NOTICE linked children of an asset.

Table 72. Request
Parameter	Comment	Type
asset_id	ID of the asset for which to get children.	string
levels	Number of levels to return.	number
type_codes	Asset type code required.	array
link_types	Link type of links being looked for: SQ_LINK_TYPE_1 SQ_LINK_TYPE_2 SQ_LINK_TYPE_3 SQ_LINK_NOTICE	array
link_values	Link values allowed on the asset returned	array
get_attributes	Get non-standard attribute values of the assets (FALSE by default).	boolean
dataCallback	Custom callback function.	function

Table 73. Response

Response

"0" {
     name
     short_name
     id
     type_code
     type
     icon_path
     data_path
     web_path
     status
     created
     created_userid
     created_username
     updated
     updated_userid
     updated_username
     published
     published_userid
     published_username
     status_changed
     status_changed_userid
     status_changed_username
     link_id
     link_type
     is_dependant
     is_exclusive
     sort_order
     link_value
     locked
     direct_dependant_children
     direct_non_dependant_children
     direct_notice_linked_children

  }, ...

Example 38. Example

js_api.getChildren({
   "asset_id":"100",
   "levels":2,
   "type_codes":[
      "page_standard",
      "comment"
   ],
   "link_types":[
      "SQ_LINK_TYPE_1",
      "SQ_LINK_TYPE_2"
   ],
   "link_values":[
      "value1",
      "value2"
   ],
   "get_attributes":1,
   "dataCallback":customDataCallbackFunc
})

getAssetTree

The getAssetTree operation will return tree information for children of an asset.

Table 74. Request
Parameter	Comment	Type
asset_id	ID of the asset of which to get tree information.	string
levels	Number of levels to return.	integer
link_types	The link types to return.	integer
dataCallback	Custom callback function.	function

Table 75. Response
Response
"asset_id":{ "asset_id":{ assetid majorid type_code page_standard status name short_name path sort_order }, ...

Example 39. Example

js_api.getAssetTree({
   "asset_id":"100",
   "levels":2,
"link_types":1,   "dataCallback":customDataCallbackFunc
})

getLineage

The getLineage operation will return the asset lineages of an asset.

Table 76. Request
Parameter	Comment	Type
asset_url	URL or asset ID of the asset for which to get the lineage.	string
significant_link_only	Whether to return significant links only (TYPE 1 and TYPE 2 links).	boolean
dataCallback	Custom callback function.	function

Table 77. Response
Response
"0" { tree_id assetid name type_code link_type link_value linkid parent_assetid parent_type_code }, ...

Example 40. Example

js_api.getLineage({
   "asset_url":"http://www.example.com/site",
   "significant_links_only":1,
   "dataCallback":customDataCallbackFunc
})

Example 41. Example

js_api.getLineage({
   "asset_url":"100",
   "significant_links_only":0,
   "dataCallback":customDataCallbackFunc
})

getLineageFromUrl

The getLineageFromUrl operation will return the asset lineage of a specified URL.

Table 78. Request
Parameter	Comment	Type
asset_url	URL of the asset for which to get the lineage.	string
dataCallback	Custom callback function.	function

Table 79. Response
Response
"0" { url assetid name short_name type_code status protocol link_type }, ...

Example 42. Example

js_api.getLineageFromUrl({
   "asset_url":"http://www.example.com/site",
   "dataCallback":customDataCallbackFunc
})

getUrlFromLineage

The getUrlFromLineage operation will return the URL of an asset lineage.

Table 80. Request
Parameter	Comment	Type
lineage	An array of asset IDs in lineage order. For example; `["80","85","200"]` or `[{"assetid":"80"},{"assetid":"85"}]`	array
root_url	A root URL by which to filter the results.	string
protocol	A protocol by which to filter the results. For example: `HTTP` or `HTTPS`	string
dataCallback	Custom callback function.	function

Table 81. Response
Response
`[ "http://www.example.com" ]`

Example 43. Example

js_api.getUrlFromLineage({
   "lineage":["4206", "4437"],
   "root_url":"http://www.example.com/site ",   "protocol":"https",
   "dataCallback":customDataCallbackFunc
})

Metadata

getMetadata

The getMetadata operation will return the metadata values of an asset.

Table 82. Request
Parameter	Comment	Type
asset_id	ID of the asset for which information is being retrieved.	string
dataCallback	Custom callback function.	function

Table 83. Response
Response
{"Title":"Home","Description":"The home page of the site","Date Created":"14/06/2010 09:43:22"}

Example 44. Example

js_api.getMetadata({
   "asset_id":"100",
   "dataCallback":customDataCallbackFunc
})

setMetadata

The SetMetadata operation will set a metadata value for an asset.

Table 84. Request
Parameter	Comment	Type
asset_id	ID of the asset for which information is being queried.	string
field_id	ID of the metadata field for which information is being queried.	string
field_val	The value set as metadata (See the Note below).	string
dataCallback	Custom callback function.	function

Table 85. Response
Response
`{"success":["Metadata field #456 has been successfully set to "author" for Asset "Home" (#123)"]}`

Note

The formats for setting the various metadata field types are outlined below. You can pass a value of null to use the default metadata value on the specified field.

Text: A simple text string. For example, Squiz Matrix.
Select: The key(s) for the option(s) to select, separated by semicolons. For example,` a; b; c`.
Multiple Text: Simple text strings, separated by semicolons for each item. For example, Squiz; Matrix.
Date: The date and time in the format yyyy-MM-dd hh::mm::ss. For example,` 2012-06-14 09:12:40`.
Thesaurus: The name of the Thesaurus Term. For example, Matrix.
Hierarchy: The key(s) for the option(s) to select, separated by semicolons. For example, a; a1; b2.
WYSIWYG: HTML content. For example, <strong>lorem ipsum…</strong>
Related Asset: The asset ID of the related asset. For example, 123.

Read the Configuring metadata schemas documentation for more information on available metadata field types.

Example 45. Example

js_api.setMetadata({
   "asset_id":100,
   "field_id":900,
   "field_val":"metadata",
   "dataCallback":customDataCallbackFunc
})

Example 46. Example

js_api.setMetadata({
   "asset_id":100,
   "field_id":900,
   "field_val":null,
   "dataCallback":customDataCallbackFunc
})

setMetadataAllFields

The SetMetadataAllFields operation will set the metadata values of multiple fields for an asset.

Table 86. Request
Parameter	Comment	Type
asset_id	ID of the asset for which information is being queried.	string
field_info	Field IDs and their values.	array
dataCallback	Custom callback function.	function

Table 87. Response
Response
`{"success":["Metadatafield #456 has been successfully set to "author" for Asset "Home" (#123)","Metadata field … ]}`

Example 47. Example

js_api.setMetadataAllFields({
   "asset_id":"100",
   "field_info":{
      "900":"Metadata1",
      "901":"Metadata2"
   },
   "dataCallback":customDataCallbackFunc
})

getMetadataSchema

The getMetadataSchema operation will return the details of the metadata schema(s) configured on an asset, including metadata fields and their attributes.

Table 88. Request
Parameter	Comment	Type
assetid	The ID of the asset of which to get the metadata schema information.	string
granted	Whether to return metadata schemas that have been applied (TRUE) or denied (FALSE).	boolean
cascades	Whether to return metadata schemas that cascade to newly created child assets (TRUE) or schemas that do not (FALSE).	boolean
dataCallback	Custom callback function.	function

Example 48. Example

js_api.getMetadataSchema({
   "assetid":"150",
   "granted":1,   "cascades":0,   "dataCallback":customDataCallbackFunc
})

editMetadataSchema

The editMetadataSchema operation will set or unset a metadata schema on a specified asset.

Table 89. Request
Parameter	Comment	Type
assetid	The asset on which to set or unset the metadata schema.	string
schemaid	The metadata schema to be set or unset on the asset.	string
set	Whether the metadata schema is being set (1) or unset (0).	boolean
granted	Whether the metadata schema is being applied (TRUE) or denied (FALSE).	boolean
cascades	Whether the schema should be cascaded to newly created assets.	boolean
dataCallback	Custom callback function.	function

Example 49. Example

js_api.editMetadataSchema({
   "assetid":"612",
   "schemaid":"405",
   "set":1,
   "granted":0,
   "cascades":0,   "dataCallback":customDataCallbackFunc
})

Contexts

Sync Contexts: Enabling this option will allow the Javascript API to correctly synchronize Context changes on both the frontend and backend, facilitating context-aware functionality from the API’s operations.

getAlternateContext

The getAlternateContext operation will return information on the alternate Contexts configured on your system.

Table 90. Request
Parameter	Comment	Type
all_info	Whether to return all information of returned contexts.	boolean
dataCallback	Custom callback function.	function

Example 50. Example

js_api.getAlternateContext({
   "all_info":1,
   "dataCallback":customDataCallbackFunc
})

getCurrentContext

The getCurrentContext operation will return information on the current Contexts configured on your system.

Table 91. Request
Parameter	Comment	Type
all_info	Whether to return all information of returned contexts.	boolean
dataCallback	Custom callback function.	function

Example 51. Example

js_api.getCurrentContext({
   "all_info":1,
   "dataCallback":customDataCallbackFunc
})

getAllContexts

The getAllContexts operation will return information on all the Contexts configured on your system.

Table 92. Request
Parameter	Comment	Type
all_info	Whether to return all information of returned contexts.	boolean
dataCallback	Custom callback function.	function

Example 52. Example

js_api.getAllContexts({
   "all_info":1,
   "dataCallback":customDataCallbackFunc
})

setContext

The setContext operation will set the current Context on the system to a specified context.

Table 93. Request
Parameter	Comment	Type
context_id	ID of the context to activate.	string
dataCallback	Custom callback function.	function

Example 53. Example

js_api.setContext({
   "context_id":"160",
   "dataCallback":customDataCallbackFunc
})

restoreContext

The restoreContext operation will set the current Context on the system to that which was previously set.

Table 94. Request
Parameter	Comment	Type
dataCallback	Custom callback function.	function

Example 54. Example

js_api.restoreContext({
   "dataCallback":customDataCallbackFunc
})

contextualiseAsset

Enables the contextualiseAsset function which lets you contextualize an asset’s attributes or metadata for a specific Context.

Table 95. Request
Parameter	Comment	Type
asset_id	The ID of the asset to contextualise.	string/integer
context_id	The ID of the Context to contextualise.	string/integer
contextualise	Choose either to contextualize or un-contextualize the component for the asset.	boolean
component_type	Asset component to contextualize: Attribute Metadata Null (contextualizes both).	string
dataCallback	Custom callback function.	function

Example 55. Example

js_api.contextualiseAsset({
  "asset_id":"100"
  "context_id":"1"
  "contextualise":true
  "component_type":"metadata"
  "dataCallback":customDataCallbackFunc
})

Google Analytics

getGoogleAnalyticsStatistics

The getGoogleAnalyticsStatistics function will allow you to make a request to a Google Analytics application to retrieve analytics data.

Table 96. Request
Parameter	Comment	Type
assetid	The asset ID of the Google Analytics View asset.	string
end_date	The end date of analytics data to return. Can be specified as a plain date (for example; `2014-11-18`) or as a relative date.	string
start_date	The start date of the analytics data to return.	string
duration	The duration of analytics data to return, worked back from the `end_date`, inclusive. For instance `P1M` indicates one-month duration.	string
dimensions	Specify the dimenstions to use on the request. Visit the Google Analytics site for more information.	array/string
metrics	Specify the dimenstions to use on the request. Visit the Google Analytics site for more information.	array/string
sort_by	Array of fields by which to sort results.	array/string
filter	Filter analytics data according to the filter expressions defined on the Google Analytics site.	array/string
force_cache	Specify whether to query Google Analytics for data if a cached entry is not available. If set to to TRUE, and no content is available, a `noContent` error will be returned.	boolean
dataCallback	Custom callback function.	functionq

Example 56. Example

js_api.getGoogleAnalyticsStatistics({
   "assetid":"100",
   "dimensions":["ga:date"],
   "metrics":["ga:sessions", "ga:pageviews"],
   "duration":"P1M",
   "end_date":"-P1D",
   "sort_by":["-ga:sessions"],   "dataCallback":customDataCallbackFunc
})

System information

This sections displays the system information operations, allowing you to retrieve information on your Matrix system, including user preferences and the maintenance mode status of your system.

Read the Global preferences and the System maintenance documentation for more information.

In this section, select Yes for the functions you want to make available on the API. You can use the Set All field to either enable or disable all the functions in this section.

getSystemInformation

The getSystemInformation function will allow you to retrieve the information on your system.

Table 97. Request
Parameter	Comment	Type
dataCallback	Custom callback function.	function

Example 57. Example

js_api.getSystemInformation({
   "dataCallback":customDataCallbackFunc
})

Form questions

createQuestion

The createQuestion function will allow you to create a new question on a Custom Form.

Table 98. Request
Parameter	Comment	Type
assetid	The asset of the form or form section to add the question asset	string
type_code	The type of question to be added (default: Text)	string
units	The number of questions to add of a certain type (default: 1)	integer
dataCallback	Custom callback function.	function

Example 58. Example

js_api.createQuestion({
    "assetid":"100",
    "type_code":"Country",    "units":2,
    "dataCallback":customDataCallbackFunc
})

updateQuestion

The updateQuestion function will allow you to update the field information of an existing question on a custom form.

Table 99. Request
Parameter	Comment	Type
assetid	The asset of the form or form section to update.	string
question_id	The asset ID of the question to update.	string
field_info	The object containing data that needs to be updated.	json
dataCallback	Custom callback function.	function

Example 59. Example

var field_info = {
    'cust_required_error': 'This is custom Text',                                                     //text type
    'is_required': 1,                                                                                 // boolean type
    'default':  '2014-10-10 10:59:39',                                                                // datetime type
    'name': 'Date Time Question',                                                                     // text type
    'show': show_array,                                                                               // serialise type
    'text': 'a:3:{s:1:"d";s:9:"date text";s:1:"m";s:10:"month text";s:1:"y";s:9:"year text";}'        // also serialise type
};

js_api.updateQuestion({
    "assetid":"100",
    "question_id":"q35",
    "field_info":field_info,
    "dataCallback":customDataCallbackFunc})

removeQuestion

The removeQuestion function will allow you to remove a question from a custom form.

Table 100. Request
Parameter	Comment	Type
assetid	The asset of the form or form section from which to remove a question.	string
question_id	Question that needs to be removed.	string
dataCallback	Custom callback function.	function

Example 60. Example

js_api.removeQuestion({
    "assetid":"100",
    "question_id":"q35",
    "dataCallback":customDataCallbackFunc})

updateQuestionOrder

The updateQuestionOrder function will allow you to update the order of the questions on a custom form.

Table 101. Request
Parameter	Comment	Type
assetid	The asset of the form or form section to update.	string
sort_order	New order of the questions.	array
dataCallback	Custom callback function.	function

Example 61. Example

question_order = ['100:q52', '100:q51', '100:q50', '100:q49''];
js_api.updateQuestionOrder({
    assetid:"100",
    sort_order:question_order,
    dataCallback:customDataCallbackFunc})

Personas

getAvailablePersonas

Table 102. Request
Parameter	Comment	Type
assetid	ID of the asset for which to get available personas.	string
dataCallback	Custom callback function.	function

Table 103. Response
Response
{ "personas":{ "persona_id":{ assetid, name } }, "applied_personas": [persona_id] },...

Example 62. Example

js_api.getAvailablePersonas({
  "asset_id":"100",
  "dataCallback":customDataCallbackFunc<br>
})

assignPersonas

Table 104. Request
Parameter	Comment	Type
assetid	ID of the asset that has the variation.	string
variation_id	ID of the variation asset.	string
persona_ids	IDs of the personas to apply to the variation.	array
dataCallback	Custom callback function.	function

Table 105. Response
Response
null

Example 63. Example

js_api.assignPersona({
  "asset_id":"100",
  "variation_id":"101"
  "persona_ids": ["200"]
  "dataCallback":customDataCallbackFunc
})

Batching requests

The batchRequest operation allows you to group multiple functions on the JS API into a single batched request. The response of this operation will include all the data returned from each executed function.

The output of functions on this operation can be used as the input for subsequent functions using the following keyword replacement format:

%Results_0_<param>%

For example, the keyword replacement %results_0_1_name% would print the value of the name parameter returned on the second element of the first array of the response.

Matrix will attempt to replace this keyword when used within page content, returning a blank value. In such cases, the following format for this keyword can be employed:

"`%" + "Results_0_<param>" + "%`"

A blocking parameter (type: Boolean) is available for use on each operation to stop the execution of subsequent operations if an error is returned.

Usage of this parameter is as follows:

{
    function :"getGeneral",
    args : {
        asset_id : "100",
        get_attributes : 0
    }
"blocking":1
}

Example

The following example uses the batchRequest operation to run the getChildren and setAttribute operations on a single request.

The getChildren operation will retrieve the top-level child assets of our site (#100) that are of type page_standard. The setAttribute operation will use this information to change the short_name of the first returned asset on this response.

To do this, the %results_0_0_id% keyword replacement has been used in the asset_id parameter. This will retrieve the ID value of the first element of the first array of the response (that is, the first returned asset on the data returned on the getChildren operation).

The blocking property has also been used on the getChildren operation. This means that if an error is returned, the following operation (setAttribute) will not be run.

Request (enhanced)

js_api.batchRequest({
   "functions":{
      "0":{
         "function":"getChildren",
         "args":{
         "asset_id":"100",
         "levels":1,
         "type_codes":"page_standard",
         "get_attributes":0
         },
         "blocking":1
      },
      "1":{
         "function":"setAttribute",
         "args":{
         "asset_id":"%results_0_0_id%",
         "attr_name":"short_name",
         "attr_val":"new short name"
         }
      }
   },
   "dataCallback":customDataCallbackFunc
});

Response

[["0" {
        "name" : Home Page
        "short_name" : Home
        "id" : 150
        "type_code" : page_standard
        "type" : Page Standard
        ...

   },

["Attribute "short_name" has been successfully set to "new short name" for asset "home page" (#150)"]]

As shown in the above response, the batchRequest operation has used the returned ID value on getChildren (first element) as the asset ID passed in the setAttribute operation.