API Reference

The IMS API allows third party developers to access core IMS functionality without the need to use the web interface. The API exposes a wide variety of methods for both reporting on the system, and performing actions. The documentation provided here provides a complete command reference.

The API methods are broken down into modules listed on the left. Each module has a list of methods; each method includes details of its parameters and outputs.

For usage notes and examples, please see the full documentation on the Third Light wiki.

ACL top

Contents

Details

top

Creates a new ACL for a given folder and member.

ACL.Create ( int folderId, int memberGuid, FOLDER_ACL_RIGHTS rights )

FOLDER_ACL_DETAILS

Type and Name Description

int folderId

The container for which to create the ACL.

int memberGuid

The GUID of the user, group or role that this ACL is for,

FOLDER_ACL_RIGHTS rights

The rights for the ACL.

Returns

FOLDER_ACL_DETAILS

The details of the created ACL.

top

Delete one or more ACLs.

ACL.Delete ( int[] aclIds )

void

Type and Name Description

int[] aclIds

The ACLs to delete.

Returns

void

top

Get the details of the ACLs in the supplied folder.

Variant Information: This method has 2 variants.
Variant 1

ACL.GetAll ( int folderId[, ACL_GET_ALL_OPTIONS options = NULL] )

FOLDER_ACL_DETAILS[]

Type and Name Description

int folderId

ID or GUID of folder to query

ACL_GET_ALL_OPTIONS options

Options to configure what ACLs are returned by this method.

Returns

FOLDER_ACL_DETAILS[]

The ACLs for the supplied folderId.

Variant 2

ACL.GetAll ( int[] folderIds[, ACL_GET_ALL_OPTIONS options = NULL] )

FOLDER_ACL_DETAILS[][]

Type and Name Description

int[] folderIds

ID or GUID of folder to query

ACL_GET_ALL_OPTIONS options

Options to configure what ACLs are returned by this method.

Returns

FOLDER_ACL_DETAILS[][]

The ACLs for the supplied folderId.

top

Get the GUIDs of the ACLs in the supplied folder.

Variant Information: This method has 2 variants.
Variant 1

ACL.GetAllGUIDs ( int folderId[, ACL_GET_ALL_OPTIONS options = NULL] )

string[]

Type and Name Description

int folderId

ID or GUID of folder to query

ACL_GET_ALL_OPTIONS options

Options to configure what ACLs are returned by this method.

Returns

string[]

The ACLs for the supplied folderId.

Variant 2

ACL.GetAllGUIDs ( int[] folderIds[, ACL_GET_ALL_OPTIONS options = NULL] )

string[][]

Type and Name Description

int[] folderIds

ID or GUID of folder to query

ACL_GET_ALL_OPTIONS options

Options to configure what ACLs are returned by this method.

Returns

string[][]

The ACLs for the supplied folderId.

top

Get the IDs of the ACLs in the supplied folder.

Variant Information: This method has 2 variants.
Variant 1

ACL.GetAllIDs ( int folderId[, ACL_GET_ALL_OPTIONS options = NULL] )

int[]

Type and Name Description

int folderId

ID or GUID of folder to query

ACL_GET_ALL_OPTIONS options

Options to configure what ACLs are returned by this method.

Returns

int[]

The ACLs for the supplied folderId.

Variant 2

ACL.GetAllIDs ( int[] folderIds[, ACL_GET_ALL_OPTIONS options = NULL] )

int[][]

Type and Name Description

int[] folderIds

ID or GUID of folder to query

ACL_GET_ALL_OPTIONS options

Options to configure what ACLs are returned by this method.

Returns

int[][]

The ACLs for the supplied folderId.

top

Retrieve information for a particular ACL.

Variant Information: This method has 2 variants.
Variant 1

ACL.GetDetails ( int aclId )

FOLDER_ACL_DETAILS

Type and Name Description

int aclId

the ACL(s) to query

Returns

FOLDER_ACL_DETAILS

A hash of details about the ACL

Variant 2

ACL.GetDetails ( int[] aclIds )

FOLDER_ACL_DETAILS[]

Type and Name Description

int[] aclIds

the ACL(s) to query

Returns

FOLDER_ACL_DETAILS[]

A hash of details about the ACL

top

Modify the details of an ACL.

ACL.SetDetails ( int aclId, ACL_SET_DETAILS details )

FOLDER_ACL_DETAILS

Type and Name Description

int aclId

ID or GUID of the ACL to update

ACL_SET_DETAILS details

updated details for the ACL.

Returns

FOLDER_ACL_DETAILS

The updated hash of the ACL.

APIKey top

Contents

Details

top

Create a new API key with the specified label

APIKey.CreateKey ( string label[, int context = 'dom0'] )

Type and Name Description

string label

The label for the new key

int context

The context for which to create the API key.

Returns

The new API key

top

Delete the specified API key

APIKey.DeleteKey ( int[] apiKeyId )

void

Type and Name Description

int[] apiKeyId

The API Key to delete

Returns

void

top

Retrieve a list of all API Keys configured.

APIKey.GetAllKeyGUIDs ( [int context = 'dom0'] )

string[]

Type and Name Description

int context

The context for which to get the current API keys.

Returns

string[]

An array of the GUIDs of all of the API Keys.

top

Retrieve a list of all API Keys configured.

APIKey.GetAllKeyIDs ( [int context = 'dom0'] )

int[]

Type and Name Description

int context

The context for which to get the current API keys.

Returns

int[]

An array of the IDs of all of the API Keys.

top

Retrieve a list of all API Keys configured.

APIKey.GetAllKeys ( [int context = 'dom0'] )

Type and Name Description

int context

The context for which to get the current API keys.

Returns

An array of hashes containing apikey and label for each API Key

top

Returns details of the API Keys.

Variant Information: This method has 2 variants.
Variant 1

APIKey.GetApiKeyDetails ( int apiKeyId )

Type and Name Description

int apiKeyId

IDs of the API key to get the detials for.

Returns

Variant 2

APIKey.GetApiKeyDetails ( int[] apiKeyId )

Type and Name Description

int[] apiKeyId

IDs of the API key to get the detials for.

Returns

AuditLogs top

Contents

Details

top

Get a pickup URL to download audit logs with a specified set of search criteria

AuditLogs.Export ( [AUDIT_LOG_FILTER filter = NULL] )

string

Type and Name Description

AUDIT_LOG_FILTER filter

Only include logs matching the specified criteria

Returns

string

A URL, at which the CSV may be collected

top

Get audit log records matching the specified criteria

Variant Information: This method has 2 variants.
Variant 1

AuditLogs.Get ( int auditLog )

Type and Name Description

int auditLog

Logs to get details

Returns

Variant 2

AuditLogs.Get ( int[] auditLog )

Type and Name Description

int[] auditLog

Logs to get details

Returns

top

This method can be used to retrieve details about how audited actions are categorised, it is useful to provide context for other log retrieval methods, and to provide a filter interface to request just a particular category in requests

In the returned hashes, key is the token to use with the API and description is a human-readable description of it

AuditLogs.GetAvailableCategories ( )

Type and Name Description

Returns

top

Get audit logs for specified objects (files/folders/users etc).

hashes.

Variant Information: This method has 2 variants.
Variant 1

AuditLogs.GetForGUIDs ( string guids[, AUDIT_LOG_FILTER filter = NULL] )

Type and Name Description

string guids

An array of GUIDs

AUDIT_LOG_FILTER filter

Optional filter to apply per item

Returns

The GUID mapped to a an array of audit logs

Variant 2

AuditLogs.GetForGUIDs ( string[] guids[, AUDIT_LOG_FILTER filter = NULL] )

Type and Name Description

string[] guids

An array of GUIDs

AUDIT_LOG_FILTER filter

Optional filter to apply per item

Returns

The GUID mapped to a an array of audit logs

top

Catalogue top

Contents

Details

top

Add a panel to the local catalogue

The purpose is to add a panel that is shared or is available from another context, note that locally created panels will always be added to the catalogue

Catalogue.AddLocalCategory ( int catalogue, int category )

void

Type and Name Description

int catalogue

The catalogue to modify

int category

The category to add

Returns

void

top

Add a panel to the local catalogue

The purpose is to add a panel that is shared or is available from another context, note that locally created panels will always be added to the catalogue

Catalogue.AddLocalPanel ( int catalogue, int panel )

void

Type and Name Description

int catalogue

The catalogue to modify

int panel

The panel to add

Returns

void

top

Add an external user to the contact list for a group. Returns a hash containing details of the new user.

The external user hash contains keys as follows:

id - The ID of the external user type - 'external' - This is provided for consistency name - The display name for the external user email - The external user's e-mail address company - An extra descriptive field, intended to specify the company with which the external user is associated

Catalogue.AddToContactList ( string email[, int catalogue = 'me'][, string name = NULL][, string company = NULL][, string message = NULL] )

USER_DETAILS

Type and Name Description

string email

The e-mail address for the new contact

int catalogue

An optional Group or User ID, specifying the context for the contact list

string name

An optional name for the contact

string company

An optional company name for the contact

string message

An optional message to include in the welcome e-mail sent to the contact

Returns

USER_DETAILS

A hash containing details about the added contact

top

Get the GUIDs of all the categories available for use in a given catalogue

Catalogue.GetAvailableCategoriesForCatalogue ( int catalogue )

string[][]

Type and Name Description

int catalogue

The catalogue to modify

Returns

string[][]

GUIDs of usable categories, nested by the context in which they are found

top

Get the GUIDs of all the panels available for use in a given catalogue

Catalogue.GetAvailablePanelGUIDsForCatalogue ( int catalogue )

string[][]

Type and Name Description

int catalogue

The catalogue to modify

Returns

string[][]

GUIDs of usable panels, nested by the context in which they are found

top

Get all the panels available for use in a given catalogue

Returns panel details nested by the context in which they are found

Catalogue.GetAvailablePanelsForCatalogue ( int catalogue )

Type and Name Description

int catalogue

The catalogue to modify

Returns

top

This gets the resultant download categories for this catalogue, after resolving any parent configuration

Catalogue.GetCategories ( int catalogue )

string[]

Type and Name Description

int catalogue

The catalogue to modify

Returns

string[]

An ordered list of GUIDs of the categories in the catalogue

top

Get the contact list for this context, having resolved parent inclusions and ordering

The external user GUIDs returned are suitable for use in sharing

Catalogue.GetContactList ( [int catalogue = 'me'] )

Type and Name Description

int catalogue

The catalogue to query

Returns

An ordered list of GUIDs of the external users in the contact list, grouped by the context from which they are inherited

top

Get the settings for a catalogue. The catalogue can be specified by ID, GUID or context string

This provides info such as whether entries are inherited from the parent

Catalogue.GetDetails ( [int catalogue = 'me'] )

Type and Name Description

int catalogue

The catalogue to look up

Returns

top

Get the local categories in a catalogue, in order

The position attribute is supplied to allow a single one to be moved by re-sending it with a modified value.

Catalogue.GetLocalCategories ( int catalogue )

Type and Name Description

int catalogue

The catalogue to modify

Returns

top

Get the local panels in a catalogue, in order

The position attribute is supplied to allow a single panel to be moved by re-sending it with a modified value.

Catalogue.GetLocalPanels ( int catalogue )

Type and Name Description

int catalogue

The catalogue to modify

Returns

top

Get the local shortlisted download sizes in a catalogue, in order

The position attribute is supplied to allow a single one to be moved by re-sending it with a modified value.

Catalogue.GetLocalShortlist ( int catalogue )

Type and Name Description

int catalogue

The catalogue to modify

Returns

top

Gets the IDs of panels that are attached to the context root specified

Catalogue.GetPanelGUIDsOnContext ( int catalogue )

string[]

Type and Name Description

int catalogue

The context to query

Returns

string[]

The GUIDs of the metadata panels that match

top

Gets the IDs of panels that are attached to the context root specified

Catalogue.GetPanelIDsOnContext ( int catalogue )

int[]

Type and Name Description

int catalogue

The context to query

Returns

int[]

The ID of the metadata panels that match

top

This gets the resultant panels for this catalogue, after resolving any parent configuration

Catalogue.GetPanels ( int catalogue )

string[]

Type and Name Description

int catalogue

The catalogue to modify

Returns

string[]

An ordered list of GUIDs of the panels in the catalogue

top

Get the parent categories associated with a catalogue, in order

Catalogue.GetParentCategories ( int catalogue )

Type and Name Description

int catalogue

The catalogue to modify

Returns

top

Get the parent panels associated with a catalogue, in order

The position attribute is supplied to allow a single panel to be moved by re-sending it with a modified value.

Catalogue.GetParentPanels ( int catalogue )

Type and Name Description

int catalogue

The catalogue to modify

Returns

top

Get the parent sizes associated with a catalogue, in order

Catalogue.GetParentShortlist ( int catalogue )

Type and Name Description

int catalogue

The catalogue to modify

Returns

top

This gets the resultant shortlisted download sizes for this catalogue, after resolving any parent configuration

Catalogue.GetShortList ( int catalogue )

string[]

Type and Name Description

int catalogue

The catalogue to modify

Returns

string[]

An ordered list of GUIDs of the shortlisted sizes in the catalogue

top

Remove an external user from the contact list for a group

Catalogue.RemoveFromContactList ( int externalUserId[, int catalogue = 'me'] )

void

Type and Name Description

int externalUserId

The external user to remove

int catalogue

An optional Group or User ID, specifying the context for the contact list

Returns

void

top

Remove a panel from the local catalogue

This can only be done for shared panels that had been added; locally created panels cannot be removed but must be deleted

Catalogue.RemoveLocalCategory ( int catalogue, int category )

void

Type and Name Description

int catalogue

The catalogue to modify

int category

The category to remove

Returns

void

top

Remove a panel from the local catalogue

This can only be done for shared panels that had been added; locally created panels cannot be removed but must be deleted

Catalogue.RemoveLocalPanel ( int catalogue, int panel )

void

Type and Name Description

int catalogue

The catalogue to modify

int panel

The panel to remove

Returns

void

top

Amend the settings for a catalogue, returning the new values

Catalogue.SetDetails ( int catalogue, CATALOGUE_DETAILS details )

Type and Name Description

int catalogue

The catalogue to modify

CATALOGUE_DETAILS details

The amended details to set

Returns

top

Set local categories, in order

This will add categories as required, and will remove categories that are not mentioned if they come from a different catalogue. Locally defined categories that are not mentioned will be preserved but moved to the bottom of the list

Catalogue.SetLocalCategories ( int catalogue, CATALOGUE_CATEGORY_DETAILS[] categories )

void

Type and Name Description

int catalogue

The catalogue to modify

CATALOGUE_CATEGORY_DETAILS[] categories

The updated details for each category

Returns

void

top

Set details on a local panel

This can be used to modify position

It will attempt to add the specified panel to the local catalogue if required

Catalogue.SetLocalCategoryDetails ( int catalogue, CATALOGUE_CATEGORY_DETAILS category )

void

Type and Name Description

int catalogue

The catalogue to modify

CATALOGUE_CATEGORY_DETAILS category

The updated details for a category

Returns

void

top

Set details on a local panel

This can be used to modify isAttachedToRoot and position

It will attempt to add the specified panel to the local catalogue if required

Catalogue.SetLocalPanelDetails ( int catalogue, CATALOGUE_PANEL_DETAILS panel )

void

Type and Name Description

int catalogue

The catalogue to modify

CATALOGUE_PANEL_DETAILS panel

The updated details for a panel

Returns

void

top

Set details on local panels

This can be used to modify isAttachedToRoot, add the specified panel to the local catalogue if required and specify the order of the panels

Panels that are not mentioned will be removed if they came from an external catalogue. Otherwise they will be preserved but moved to the bottom of the list

Catalogue.SetLocalPanels ( int catalogue, CATALOGUE_PANEL_DETAILS[] panels )

void

Type and Name Description

int catalogue

The catalogue to modify

CATALOGUE_PANEL_DETAILS[] panels

The updated details for a panel

Returns

void

top

Configure whether sizes in the (local) catalogue are included in the shortlist

Any sizes not mentioned will be left unchanged

Catalogue.SetLocalShortlist ( int catalogue, CATALOGUE_SHORTLIST_DETAILS[] sizes )

void

Type and Name Description

int catalogue

The catalogue to modify

CATALOGUE_SHORTLIST_DETAILS[] sizes

The entries

Returns

void

top

Configure whether a size in the (local) catalogue is included in the shortlist

Catalogue.SetLocalShortlistDetails ( int catalogue, CATALOGUE_SHORTLIST_DETAILS size )

void

Type and Name Description

int catalogue

The catalogue to modify

CATALOGUE_SHORTLIST_DETAILS size

The entry

Returns

void

top

Set details on parent Categories

This can be used to modify showInList

Categories not mentioned will not be changed

Catalogue.SetParentCategories ( int catalogue, PARENT_CATALOGUE_CATEGORY_DETAILS[] categories )

void

Type and Name Description

int catalogue

The catalogue to modify

PARENT_CATALOGUE_CATEGORY_DETAILS[] categories

The updated details for each panel

Returns

void

top

Set details on a parent panel

This can be used to modify showInList

Catalogue.SetParentCategoryDetails ( int catalogue, PARENT_CATALOGUE_CATEGORY_DETAILS category )

void

Type and Name Description

int catalogue

The catalogue to modify

PARENT_CATALOGUE_CATEGORY_DETAILS category

The updated details for a panel

Returns

void

top

Set details on a parent panel

This can be used to modify isAttachedToRoot and showInList

Catalogue.SetParentPanelDetails ( int catalogue, PARENT_CATALOGUE_PANEL_DETAILS[] panels )

void

Type and Name Description

int catalogue

The catalogue to modify

PARENT_CATALOGUE_PANEL_DETAILS[] panels

The updated details for a panel

Returns

void

top

Configure whether sizes in the (parent) catalogue are included in the shortlist

Any sizes not mentioned will be left unchanged

This method can only be called if the catalogue is not set to inherit the parent shortlist

Catalogue.SetParentShortlist ( int catalogue, CATALOGUE_SHORTLIST_DETAILS[] sizes )

void

Type and Name Description

int catalogue

The catalogue to modify

CATALOGUE_SHORTLIST_DETAILS[] sizes

The entries

Returns

void

top

Set details on a parent panel

This can be used to modify isAttachedToRoot and showInList

Catalogue.SetParentShortlistDetails ( int catalogue, CATALOGUE_SHORTLIST_DETAILS size )

void

Type and Name Description

int catalogue

The catalogue to modify

CATALOGUE_SHORTLIST_DETAILS size

The updated details for a panel

Returns

void

Config top

Contents

Details

top

Checks to see if a feature is available in the IMS site.

Supported feature keys are:

  • SECURE_FILE_FETCH - true if IMS site is configured for creation of either temporary or permanent secure file fetch URLs
  • SECURE_FILE_FETCH_PERMANENT - true if IMS site is configured for creation of permanent secure file fetch URLs
  • REVISIONS - true if IMS site is configured asset version control

Config.CheckFeatureAvailable ( string featureKey )

bool

Type and Name Description

string featureKey

A string key representing the feature that you want to check is available in the IMS site.

Returns

bool

true if the feature is available

top

Get the structured settings data for site configuration.

This is used in building the settings/properties pages

Config.GetConfigSettings ( string settingKey )

Type and Name Description

string settingKey

One of configuration, passwordpolicy, saml2, openid, ldap, groupmappings all

Returns

An array of hashes describing configuration sections

top

Gets details of the default password policy.

Config.GetDefaultPasswordPolicy ( )

Type and Name Description

Returns

The default password policy.

top

Gets a structured hash of the available metadata fields

The returned hash is keyed by panel name, values are hashes of metadata keyfield name

Config.GetMetadataFields ( )

string[][]

Type and Name Description

Returns

string[][]

A hash of field labels by panel then tag ID

top

Gets details of the password policy in effect

The returned hash contains keys as follows:

  • minlength - int The minimum number of characters in the password
  • mincountreuse - int The minimum number of password changes before an old password can be reused
  • mindaysreuse - int The minimum number of days before an old password can be reused
  • requireupper - bool Whether passwords must contain an upper-case letter
  • requirelower - bool Whether passwords must contain a lower-case letter
  • requirenumber - bool Whether passwords must contain a number
  • requiresymbol - bool Whether passwords must contain a non-alphanumeric character
  • maxage - int Number of days after which the password must be changed
  • lockouttime - int Number of minutes to lock an account when lockouttries failed login attempts occur
  • lockouttries - int Number of tries after which an account is locked
  • desc - string A textual description of the password policy

Config.GetPasswordPolicy ( )

Type and Name Description

Returns

A hash containing keys referring to aspects of the password policy, as above

top

Get the options for an enum with non-hardcoded options.

Config.GetSettingOptions ( hash settings )

string[][]

Type and Name Description

hash settings

A list of the setting names to return the current options for

Returns

string[][]

The current options keyed by the setting name

top

Get the current setting values for the requested setting names.

Config.GetSettingValues ( string|string[] settings )

string[]

Type and Name Description

string|string[] settings

A list of the setting names to return the current values for

Returns

string[]

The current setting value keyed by the setting name

top

Sets the supplied settings for the IMS site. The returned hash contains for following keys:

  • success - true if the settings were successfully applied.
  • updatedSettings - if the settings were successfully applied. Same structure as GetSettingValues returns.
  • validateResponse - if the settings were not successfully applied. Same structure as ValidateSettingValues.

Config.SetSettingValues ( hash settings )

Type and Name Description

hash settings

The setting values to set. keyed by the setting name.

Returns

top

Test the configured IDP Metadata URL. The contents are returned in the response, abbreviated if they exceed 10,000 characters, together with a boolean to indicate success, or not. If not, the message will contain the error.

Config.TestIdpMetadataURL ( string url )

Type and Name Description

string url

The URL to test

Returns

The test response containing a success flag and a message.

top

Test the configured LDAP connection. The response contains a boolean to indicate success or failure, and a corresponding message.

Config.TestLDAPConnection ( )

Type and Name Description

Returns

The test response containing a success flag and a message.

top

Validate the supplied setting values. Returned hash contains the following keyed by the setting name.

  • valid - whether the supplied value is valid
  • reasons - if the value is invalid, a list of the reasons why the validation failed

Config.ValidateSettingValues ( hash settings )

Type and Name Description

hash settings

The setting values to validate, keyed by the setting name

Returns

A hash with a key for each supplied setting (see below), also invalidCount which contains the count of invalid settings.

Contexts top

Contents

Details

top

Get the logical areas visible to the current user This will return site-wide "domain" contexts, the user's own home directory ("me"), the home directories of any groups to which the user belongs, and the public folders of any other users or groups in the site.

The context IDs returned are suitable for use with Folders.GetTopLevelFolders and suchlike

Contexts.GetChildren ( [int scope = 'me'] )

string[]

Type and Name Description

int scope

The parent context for which to get children

Returns

string[]

An array of contextIDs

top

Get details about one or more contexts, by context ID, Group ID or group GUID

Each returned hash contains keys as follows:

  • id string The context identifier, for use in other API requests
  • type string One of domain, me and group, according to the nature of the context
  • domain string The parent domain of the context (this will normally be dom0)
  • name string A user-facing identifier for the context
  • avatar string A URL to the appropriate avatar for the user or group that is the origin of the context

*/

Variant Information: This method has 2 variants.
Variant 1

Contexts.GetDetails ( int context )

Type and Name Description

int context

An array of contexts for which details should be returned.

Returns

Details of the requested contexts

Variant 2

Contexts.GetDetails ( int[] context )

Type and Name Description

int[] context

An array of contexts for which details should be returned.

Returns

Details of the requested contexts

top

Get the path of contexts leading to a given user/group in the hierarchy. Normally this will go to the top, unless a parent group in not visible to the caller, in which case the highest visible group will be treated as a root

Contexts.GetVisiblePath ( [int context = 'me'] )

string[]

Type and Name Description

int context

The group for which to find a path

Returns

string[]

The list of groups/users in the visible hierarchy to the subject.

Core top

Contents

Details

top

Check if a list of GUIDs can be deleted

This supports files, file links, folders and folder links

Variant Information: This method has 2 variants.
Variant 1

Core.CheckDelete ( int guids )

bool

Type and Name Description

int guids

An array of GUIDs of objects to test for deletion

Returns

bool

Whether the respective object can be deleted

Variant 2

Core.CheckDelete ( array guids )

bool[]

Type and Name Description

array guids

An array of GUIDs of objects to test for deletion

Returns

bool[]

Whether the respective object can be deleted

top

Check if a list of GUIDs can be moved to a specified destination

This supports files, file links, folders and folder links

Core.CheckMove ( array guids, string destination )

Type and Name Description

array guids

An array of GUIDs of objects to test for move

string destination

A GUID or folder ID for the destination of the move

Returns

Whether the respective object can be moved to the requested destination

top

Drops user impersonation back to original actor

This method cannot be used if the impersonation was performed by an API key

Core.DeImpersonate ( )

Type and Name Description

Returns

top

Delete a list of GUIDs

This supports files, file links, folders and folder links

Variant Information: This method has 2 variants.
Variant 1

Core.Delete ( int guids )

Type and Name Description

int guids

An array of GUIDs of objects to delete

Returns

Variant 2

Core.Delete ( array guids )

void

Type and Name Description

array guids

An array of GUIDs of objects to delete

Returns

void

top

Drop any administrative privileges for the session

Core.DropPrivileges ( )

Type and Name Description

Returns

top

Elevates the current session to gain available administrative privileges.

Core.Elevate ( string password[, int timeLimit = '1800'] )

Type and Name Description

string password

The user account's password

int timeLimit

Number of seconds to hold elevated privileges. Specify 0 for unlimited.

Returns

top

Retrieve detailed information about available API methods and their usage.

The returned hash contains information structured as follows:

  • module name - e.g. "Core"
    • method name - e.g. "GetAPIListing"
      • description - an explanation of the method's behaviour
      • parameters - a hash containing a lowercased key for each parameter
        • parameter id - this is the parameter name converted to lowercase
          • name - name of the parameter
          • type - the parameter's data type. e.g. int, bool
          • description - an explanation of the parameter's purpose
          • required - boolean, is the parameter required or optional
          • default - if this is an optional parameter, this is the default value
        • ... further parameters ...
      • return - a hash detailing any data returned by the method
        • type - the returned value's data type. e.g. int, bool
        • description - an explanation of the returned value
    • ... further methods ...
  • ... further modules ...

Core.GetAPIListing ( )

Type and Name Description

Returns

Keyed by module name and method name

top

We use this for IMS7

Core.GetAPIListingForIMS7 ( )

Type and Name Description

Returns

Keyed by module name and method name

top

Gets summary information for each available API module.

Core.GetAPIModuleInformation ( )

string[]

Type and Name Description

Returns

string[]

A hash containing a key for each module which references a text description describing the module.

top

Get an accessible path to one or more objects (of type FILE, FOLDER, FILE_LINK, FOLDER_LINK)

This is equivalent to calling the type-specific version (e.g. Files.GetAccessiblePathForFile)

Variant Information: This method has 2 variants.
Variant 1

Core.GetAccessiblePath ( int guids )

Type and Name Description

int guids

An array of GUIDs of objects for which to retrieve paths

Returns

An array describing the objects in the hierarchy

Variant 2

Core.GetAccessiblePath ( array guids )

Type and Name Description

array guids

An array of GUIDs of objects for which to retrieve paths

Returns

An array describing the objects in the hierarchy

top

Gets a pre-authenticated URL for the requested user This method may only be called if the session was created via Core.LoginWithKey

Core.GetAuthorisedURL ( string userRef[, string lookupType = '"id"'][, string destination = NULL] )

string

Type and Name Description

string userRef

The user account's username, e-mail address or ID

string lookupType

The type of userRef - supported values are "email" "username" "id" or "userprincipal" (LDAP users only)

string destination

An optional destination page. Will default to the main home page (home.tlx)

Returns

string

A URL to direct the user to

top

Get details for one or more objects of any type that supports GUID identification

Each located object will return the standard details hash, keyed by GUID

Variant Information: This method has 2 variants.
Variant 1

Core.GetDetails ( string guids[, CORE_DETAILS_OPTIONS options = NULL] )

API_KEY|CATALOGUE_DETAILS|DOWNLOAD_CATEGORY_DETAILS|DOWNLOAD_SIZE_DETAILS|FILE_DETAILS|FILE_LINK_DETAILS|FOLDER_DETAILS|FOLDER_LINK_DETAILS|GROUP_DETAILS|METADATA_PANEL_DETAILS|METADATA_TAG_DETAILS|PUBLISH_LINK_DETAILS|THEME_DETAILS|USER_DETAILS|WORKFLOW_PANEL|WORKFLOW_SCRIPT|FOLDER_ACL_DETAILS|INBOX_ITEM_DETAILS
API_KEY|CATALOGUE_DETAILS|DOWNLOAD_CATEGORY_DETAILS|DOWNLOAD_SIZE_DETAILS|FILE_DETAILS|FILE_LINK_DETAILS|FOLDER_DETAILS|FOLDER_LINK_DETAILS|GROUP_DETAILS|METADATA_PANEL_DETAILS|METADATA_TAG_DETAILS|PUBLISH_LINK_DETAILS|THEME_DETAILS|USER_DETAILS|WORKFLOW_PANEL|WORKFLOW_SCRIPT|FOLDER_ACL_DETAILS|INBOX_ITEM_DETAILS
API_KEY|CATALOGUE_DETAILS|DOWNLOAD_CATEGORY_DETAILS|DOWNLOAD_SIZE_DETAILS|FILE_DETAILS|FILE_LINK_DETAILS|FOLDER_DETAILS|FOLDER_LINK_DETAILS|GROUP_DETAILS|METADATA_PANEL_DETAILS|METADATA_TAG_DETAILS|PUBLISH_LINK_DETAILS|THEME_DETAILS|USER_DETAILS|WORKFLOW_PANEL|WORKFLOW_SCRIPT|FOLDER_ACL_DETAILS|INBOX_ITEM_DETAILS
API_KEY|CATALOGUE_DETAILS|DOWNLOAD_CATEGORY_DETAILS|DOWNLOAD_SIZE_DETAILS|FILE_DETAILS|FILE_LINK_DETAILS|FOLDER_DETAILS|FOLDER_LINK_DETAILS|GROUP_DETAILS|METADATA_PANEL_DETAILS|METADATA_TAG_DETAILS|PUBLISH_LINK_DETAILS|THEME_DETAILS|USER_DETAILS|WORKFLOW_PANEL|WORKFLOW_SCRIPT|FOLDER_ACL_DETAILS|INBOX_ITEM_DETAILS

Type and Name Description

string guids

An array of GUIDs of objects for which to retrieve details

CORE_DETAILS_OPTIONS options

An optional hash of settings to pass through to type-specific detail getters.

Returns

API_KEY|CATALOGUE_DETAILS|DOWNLOAD_CATEGORY_DETAILS|DOWNLOAD_SIZE_DETAILS|FILE_DETAILS|FILE_LINK_DETAILS|FOLDER_DETAILS|FOLDER_LINK_DETAILS|GROUP_DETAILS|METADATA_PANEL_DETAILS|METADATA_TAG_DETAILS|PUBLISH_LINK_DETAILS|THEME_DETAILS|USER_DETAILS|WORKFLOW_PANEL|WORKFLOW_SCRIPT|FOLDER_ACL_DETAILS|INBOX_ITEM_DETAILS
API_KEY|CATALOGUE_DETAILS|DOWNLOAD_CATEGORY_DETAILS|DOWNLOAD_SIZE_DETAILS|FILE_DETAILS|FILE_LINK_DETAILS|FOLDER_DETAILS|FOLDER_LINK_DETAILS|GROUP_DETAILS|METADATA_PANEL_DETAILS|METADATA_TAG_DETAILS|PUBLISH_LINK_DETAILS|THEME_DETAILS|USER_DETAILS|WORKFLOW_PANEL|WORKFLOW_SCRIPT|FOLDER_ACL_DETAILS|INBOX_ITEM_DETAILS
API_KEY|CATALOGUE_DETAILS|DOWNLOAD_CATEGORY_DETAILS|DOWNLOAD_SIZE_DETAILS|FILE_DETAILS|FILE_LINK_DETAILS|FOLDER_DETAILS|FOLDER_LINK_DETAILS|GROUP_DETAILS|METADATA_PANEL_DETAILS|METADATA_TAG_DETAILS|PUBLISH_LINK_DETAILS|THEME_DETAILS|USER_DETAILS|WORKFLOW_PANEL|WORKFLOW_SCRIPT|FOLDER_ACL_DETAILS|INBOX_ITEM_DETAILS
API_KEY|CATALOGUE_DETAILS|DOWNLOAD_CATEGORY_DETAILS|DOWNLOAD_SIZE_DETAILS|FILE_DETAILS|FILE_LINK_DETAILS|FOLDER_DETAILS|FOLDER_LINK_DETAILS|GROUP_DETAILS|METADATA_PANEL_DETAILS|METADATA_TAG_DETAILS|PUBLISH_LINK_DETAILS|THEME_DETAILS|USER_DETAILS|WORKFLOW_PANEL|WORKFLOW_SCRIPT|FOLDER_ACL_DETAILS|INBOX_ITEM_DETAILS

Variant 2

Core.GetDetails ( string[] guids[, CORE_DETAILS_OPTIONS options = NULL] )

API_KEY[]|CATALOGUE_DETAILS[]|DOWNLOAD_CATEGORY_DETAILS[]|DOWNLOAD_SIZE_DETAILS[]|FILE_DETAILS[]|FILE_LINK_DETAILS[]|FOLDER_DETAILS[]|FOLDER_LINK_DETAILS[]|GROUP_DETAILS[]|METADATA_PANEL_DETAILS[]|METADATA_TAG_DETAILS[]|PUBLISH_LINK_DETAILS[]|THEME_DETAILS[]|USER_DETAILS[]|WORKFLOW_PANEL[]|WORKFLOW_SCRIPT[]|FOLDER_ACL_DETAILS[]|INBOX_ITEM_DETAILS[]
API_KEY[]|CATALOGUE_DETAILS[]|DOWNLOAD_CATEGORY_DETAILS[]|DOWNLOAD_SIZE_DETAILS[]|FILE_DETAILS[]|FILE_LINK_DETAILS[]|FOLDER_DETAILS[]|FOLDER_LINK_DETAILS[]|GROUP_DETAILS[]|METADATA_PANEL_DETAILS[]|METADATA_TAG_DETAILS[]|PUBLISH_LINK_DETAILS[]|THEME_DETAILS[]|USER_DETAILS[]|WORKFLOW_PANEL[]|WORKFLOW_SCRIPT[]|FOLDER_ACL_DETAILS[]|INBOX_ITEM_DETAILS[]
API_KEY[]|CATALOGUE_DETAILS[]|DOWNLOAD_CATEGORY_DETAILS[]|DOWNLOAD_SIZE_DETAILS[]|FILE_DETAILS[]|FILE_LINK_DETAILS[]|FOLDER_DETAILS[]|FOLDER_LINK_DETAILS[]|GROUP_DETAILS[]|METADATA_PANEL_DETAILS[]|METADATA_TAG_DETAILS[]|PUBLISH_LINK_DETAILS[]|THEME_DETAILS[]|USER_DETAILS[]|WORKFLOW_PANEL[]|WORKFLOW_SCRIPT[]|FOLDER_ACL_DETAILS[]|INBOX_ITEM_DETAILS[]
API_KEY[]|CATALOGUE_DETAILS[]|DOWNLOAD_CATEGORY_DETAILS[]|DOWNLOAD_SIZE_DETAILS[]|FILE_DETAILS[]|FILE_LINK_DETAILS[]|FOLDER_DETAILS[]|FOLDER_LINK_DETAILS[]|GROUP_DETAILS[]|METADATA_PANEL_DETAILS[]|METADATA_TAG_DETAILS[]|PUBLISH_LINK_DETAILS[]|THEME_DETAILS[]|USER_DETAILS[]|WORKFLOW_PANEL[]|WORKFLOW_SCRIPT[]|FOLDER_ACL_DETAILS[]|INBOX_ITEM_DETAILS[]

Type and Name Description

string[] guids

An array of GUIDs of objects for which to retrieve details

CORE_DETAILS_OPTIONS options

An optional hash of settings to pass through to type-specific detail getters.

Returns

API_KEY[]|CATALOGUE_DETAILS[]|DOWNLOAD_CATEGORY_DETAILS[]|DOWNLOAD_SIZE_DETAILS[]|FILE_DETAILS[]|FILE_LINK_DETAILS[]|FOLDER_DETAILS[]|FOLDER_LINK_DETAILS[]|GROUP_DETAILS[]|METADATA_PANEL_DETAILS[]|METADATA_TAG_DETAILS[]|PUBLISH_LINK_DETAILS[]|THEME_DETAILS[]|USER_DETAILS[]|WORKFLOW_PANEL[]|WORKFLOW_SCRIPT[]|FOLDER_ACL_DETAILS[]|INBOX_ITEM_DETAILS[]
API_KEY[]|CATALOGUE_DETAILS[]|DOWNLOAD_CATEGORY_DETAILS[]|DOWNLOAD_SIZE_DETAILS[]|FILE_DETAILS[]|FILE_LINK_DETAILS[]|FOLDER_DETAILS[]|FOLDER_LINK_DETAILS[]|GROUP_DETAILS[]|METADATA_PANEL_DETAILS[]|METADATA_TAG_DETAILS[]|PUBLISH_LINK_DETAILS[]|THEME_DETAILS[]|USER_DETAILS[]|WORKFLOW_PANEL[]|WORKFLOW_SCRIPT[]|FOLDER_ACL_DETAILS[]|INBOX_ITEM_DETAILS[]
API_KEY[]|CATALOGUE_DETAILS[]|DOWNLOAD_CATEGORY_DETAILS[]|DOWNLOAD_SIZE_DETAILS[]|FILE_DETAILS[]|FILE_LINK_DETAILS[]|FOLDER_DETAILS[]|FOLDER_LINK_DETAILS[]|GROUP_DETAILS[]|METADATA_PANEL_DETAILS[]|METADATA_TAG_DETAILS[]|PUBLISH_LINK_DETAILS[]|THEME_DETAILS[]|USER_DETAILS[]|WORKFLOW_PANEL[]|WORKFLOW_SCRIPT[]|FOLDER_ACL_DETAILS[]|INBOX_ITEM_DETAILS[]
API_KEY[]|CATALOGUE_DETAILS[]|DOWNLOAD_CATEGORY_DETAILS[]|DOWNLOAD_SIZE_DETAILS[]|FILE_DETAILS[]|FILE_LINK_DETAILS[]|FOLDER_DETAILS[]|FOLDER_LINK_DETAILS[]|GROUP_DETAILS[]|METADATA_PANEL_DETAILS[]|METADATA_TAG_DETAILS[]|PUBLISH_LINK_DETAILS[]|THEME_DETAILS[]|USER_DETAILS[]|WORKFLOW_PANEL[]|WORKFLOW_SCRIPT[]|FOLDER_ACL_DETAILS[]|INBOX_ITEM_DETAILS[]

top

Returns the environment settings for the current user; useful for initial configuration of a UI or API based application.

The following keys are included in the returned hash: - lang - the current language in use. - title - the title string used to set the title element in an html UI. - themepath - an absolute path to the theme files. - theme - the current theme variant in use. - timeZone - the system timeZone - timeZones - array of possible timeZones - authModes - array of possible authentication mechanisms.

Core.GetEnvironment ( )

Type and Name Description

Returns

top

Retrieves the total number of files in the library. If the user doesn't have access to the whole library then this method will return an ACTION_NOT_PERMITTED error.

Core.GetFileCount ( )

int

Type and Name Description

Returns

int

The number of files in the library

top

Retrieves the total number of files in the library. If the user doesn't have access to the whole library then this method will return an ACTIONNOTPERMITTED error.

Core.GetPictureCount ( )

int

Type and Name Description

Returns

int

The number of files in the library

top

Get details of time remaining until the current session expires.

Unless the X-Ims-Session-No-Touch HTTP Header is set when making this request, calling this method will extend the current session.

Core.GetSessionExpiry ( )

Type and Name Description

Returns

Details of time remaining until the current session expires.

top

Returns details about the currently active user.

Core.GetUserDetails ( )

USER_DETAILS

Type and Name Description

Returns

USER_DETAILS

top

It is useful for the websocket server, which has access to Rabbit

Core.Handshake ( )

Type and Name Description

Returns

top

Changes the active user for the current session to that specified.

The options hash supports keys as follows

  • elevated - new user has all available administrative permissions (default prior to API v2.0)
  • restricted - new user session has no administrative permissions (default since API v2.0)

The returned hash will contain keys as follows:

  • sessionId - a session identifier which should be used in all further communication
  • userDetails - a hash contianin user information
    • type - the type of entity logged into the system. Normally this will be 1, indicating a conventional user
    • username - the login username
    • description - name or description
    • email - email address

Core.ImpersonateUser ( string userRef[, string lookupType = '"id"'][, hash options = NULL] )

Type and Name Description

string userRef

The user account's username, e-mail address or ID

string lookupType

The type of userRef - supported values are "email" "username" "id" "context" or "userprincipal" (LDAP users only)

hash options

Options that control elevation status of new session

Returns

top

Tests whether a given IMS Module is enabled

Core.IsModuleEnabled ( string moduleName )

bool

Type and Name Description

string moduleName

The name of the module to test

Returns

bool

Whether the module is enabled

top

Starts an IMS user session. After a successful login, this function returns a session identifier. Depending on the communication method being used to access the API, this identifier can be sent as a cookie with name "IMSSESSID", or sent within the body of the normal request. For further information please see the general usage notes for the API.

The options hash supports keys as follows

  • persistent - allow the session to endure beyond the normal limit
  • elevated - log in with all available administrative permissions (default prior to API v2.0)
  • restricted - log in without administrative permissions (default since API v2.0)

The returned hash will contain keys as follows:

  • sessionId - a session identifier which should be used in all further communication
  • userDetails - a hash containing user information
    • type - the type of entity logged into the system. Normally this will be 1, indicating a conventional user
    • username - the login username
    • description - name or description
    • email - email address

Core.Login ( string username, string password[, hash options = NULL] )

Type and Name Description

string username

The user account's username

string password

The user account's password

hash options

A hash of options, detailed below

Returns

top

Starts an IMS session. After a successful login, this function returns a session identifier. Depending on the communication method being used to access the API, this identifier can be sent as a cookie with name "IMSSESSID", or sent within the body of the normal request. For further information please see the general usage notes for the API.

The options has supports keys as follows:

  • persistent - allow the session to endure beyond the normal limit
  • elevated - log in with all available administrative permissions (default prior to API v2.0)
  • restricted - log in without administrative permissions (default since API v2.0)

The returned hash will contain keys as follows:

  • sessionId - a session identifier which should be used in all further communication

Core.LoginWithKey ( string apikey[, hash options = NULL] )

Type and Name Description

string apikey

An API key configured in IMS

hash options

A hash of options, detailed below

Returns

top

Ends the IMS user session.

Core.Logout ( )

void

Type and Name Description

Returns

void

top

Move a list of GUIDs to a specified destination

This supports files, file links, folders and folder links

Variant Information: This method has 2 variants.
Variant 1

Core.Move ( int guids, string destination[, bool upgradeFunctionalLevels = false] )

Type and Name Description

int guids

An array of GUIDs of objects to move

string destination

A GUID or folder ID for the destination of the move

bool upgradeFunctionalLevels

If a Collection or Smart Folder with a non-Publish Functional Level is encountered then upgrade the Functional Level to SHARE.

Returns

Variant 2

Core.Move ( array guids, string destination[, bool upgradeFunctionalLevels = false] )

void

Type and Name Description

array guids

An array of GUIDs of objects to move

string destination

A GUID or folder ID for the destination of the move

bool upgradeFunctionalLevels

If a Collection or Smart Folder with a non-Publish Functional Level is encountered then upgrade the Functional Level to SHARE.

Returns

void

DownloadCategories top

Contents

Details

top

Create a new download category.

DownloadCategories.AddDownloadCategory ( DOWNLOAD_CATEGORY_DETAILS downloadCategoryDetails[, int catalogue = 'dom0'] )

int

Type and Name Description

DOWNLOAD_CATEGORY_DETAILS downloadCategoryDetails

The details for the new category

int catalogue

The catalogue in which to create the category

Returns

int

The ID of the new download category

top

Add a new download size to a download category.

DownloadCategories.AddDownloadSize ( int downloadCategoryId, DOWNLOAD_SIZE_DETAILS downloadSizeDetails )

int

Type and Name Description

int downloadCategoryId

The ID of the download category where the new download size will be added

DOWNLOAD_SIZE_DETAILS downloadSizeDetails

The details for the new Download Size

Returns

int

The ID of the new download size

top

Create a new download category.

DownloadCategories.CreateDownloadCategory ( DOWNLOAD_CATEGORY_DETAILS downloadCategoryDetails[, int catalogue = 'dom0'] )

Type and Name Description

DOWNLOAD_CATEGORY_DETAILS downloadCategoryDetails

The details for the new category

int catalogue

The catalogue in which to create the category

Returns

The details of the new download category

top

Create a new download size to a download category.

DownloadCategories.CreateDownloadSize ( int downloadCategoryId, DOWNLOAD_SIZE_DETAILS downloadSizeDetails )

Type and Name Description

int downloadCategoryId

The ID of the download category where the new download size will be added

DOWNLOAD_SIZE_DETAILS downloadSizeDetails

The details for the new Download Size

Returns

The details of the new download size.

top

Remove a download category from the system.

DownloadCategories.DeleteDownloadCategory ( int downloadCategoryId )

int

Type and Name Description

int downloadCategoryId

The ID of the download category to remove

Returns

int

The ID of the download category that has been deleted

top

Remove a download size from the system.

DownloadCategories.DeleteDownloadSize ( int downloadSizeId )

int

Type and Name Description

int downloadSizeId

The ID of the download size to remove

Returns

int

The ID of the download size that has been deleted

top

Update a download category.

DownloadCategories.EditDownloadCategory ( int downloadCategoryId, DOWNLOAD_CATEGORY_DETAILS downloadCategoryDetails )

int

Type and Name Description

int downloadCategoryId

The ID of the download category to update

DOWNLOAD_CATEGORY_DETAILS downloadCategoryDetails

The details for the new category

Returns

int

The ID of the download category that has been updated

top

Update an existing download size.

DownloadCategories.EditDownloadSize ( int downloadSizeId, DOWNLOAD_SIZE_DETAILS downloadSizeDetails )

void

Type and Name Description

int downloadSizeId

The ID of the download size to update

DOWNLOAD_SIZE_DETAILS downloadSizeDetails

The fields to update in the Download Size

Returns

void

top

Retrieve an array of all the available download categories. The returned array is a list of hashes, each with the following keys:

  • id - the category's ID.
  • name - the category's name.
  • type - the category's associated file type - "image", "video", "audio" or "other".
  • description - the categories description.

DownloadCategories.GetAvailableDownloadCategories ( [int catalogue = 'me'] )

Type and Name Description

int catalogue

The catalogue for which to get categories

Returns

An array of hashes detailing the available Download Categories

top

Retrieve an array of all the available download sizes for an asset. The returned array is a list of hashes, each with the following keys:

  • id - the download size's ID
  • type - the asset type of the download size. Will be one of image,video,audio,other
  • description - the description of the download size
  • width - the width in pixels of the download size (image/video)
  • height - the height in pixels of the download size (image/video)
  • format - the format identifier for the download size
  • vbr - Bitrate for video
  • abr - Bitrate for audio (audio/video)
  • asr - Sample rate for audio (audio/video)
  • duration - Cutoff time in seconds for audio/video
  • dpi - DPI for image
  • colourspace - Colour space for image
  • downloadCategoryId - the ID of the parent download category. See DownloadCategories.GetAvailableDownloadCategories
  • downloadCategoryName - the name of the parent download category. See DownloadCategories.GetAvailableDownloadCategories
  • dims - brief format and dimensions of the category
  • `isOriginal' - true/false, indicating whether or not the variant corresponds to downloading an original file
Variant Information: This method has 2 variants.
Variant 1

DownloadCategories.GetAvailableDownloadSizes ( [int[] categoryId = NULL], int assetId )

Type and Name Description

int[] categoryId

A category ID or array of such. If supplied, edits will be restricted to these categories

int assetId

The asset Id for which the download sizes will be found

Returns

An array of hashes detailing the available Download Sizes

Variant 2

DownloadCategories.GetAvailableDownloadSizes ( [int[] categoryId = NULL], int catalogue )

Type and Name Description

int[] categoryId

A category ID or array of such. If supplied, edits will be restricted to these categories

int catalogue

The catalogue for which to get sizes

Returns

An array of hashes detailing the available Download Sizes

top

Returns the details for the download category with the supplied id.

Variant Information: This method has 2 variants.
Variant 1

DownloadCategories.GetDownloadCategoryDetails ( int categoryId )

Type and Name Description

int categoryId

The id of the download category.becaus

Returns

The details of the download category.

Variant 2

DownloadCategories.GetDownloadCategoryDetails ( int[] categoryId )

Type and Name Description

int[] categoryId

The id of the download category.becaus

Returns

The details of the download category.

top

Returns the details for the download size with the supplied id.

Variant Information: This method has 2 variants.
Variant 1

DownloadCategories.GetDownloadSizeDetails ( int sizeId )

Type and Name Description

int sizeId

The id of the download size,

Returns

The details of the download size.

Variant 2

DownloadCategories.GetDownloadSizeDetails ( int[] sizeId )

Type and Name Description

int[] sizeId

The id of the download size,

Returns

The details of the download size.

top

Retrieve an array of of all the download sizes for an asset.

DownloadCategories.GetDownloadSizeInfo ( int assetId )

Type and Name Description

int assetId

The asset Id for which the download sizes will be found

Returns

top

Retrieve an array of all the locally defined (thus editable) download categories. The returned array is a list of hashes, each with the following keys:

  • id - the category's ID.
  • name - the category's name.
  • type - the category's associated file type - "image", "video", "audio" or "other".
  • description - the categories description.

DownloadCategories.GetEditableDownloadCategories ( [int catalogue = 'me'] )

Type and Name Description

int catalogue

The catalogue for which to get categories

Returns

An array of hashes detailing the available Download Categories

top

Set download categories as an ordered array. Each hash within the array should contain the following keys:

  • id - the category's ID, or NULL for a new category
  • name - the category's name.
  • description - the category's description.
  • type - the category's associated file type - "audio","video","image" or "other". N.B. Changing this for existing categories is not supported.

Hashes containing just the id key may be squashed to the ID. This permits reordering by passing a straightforward array of IDs.

IMPORTANT: any existing categories whose ID is not provided to this function will be removed.

DownloadCategories.SetAvailableDownloadCategories ( DOWNLOAD_CATEGORY_DETAILS[] arrCategories[, int catalogue = 'dom0'] )

Type and Name Description

DOWNLOAD_CATEGORY_DETAILS[] arrCategories

An array of hashes detailing the desired Download Category configuration

int catalogue

The catalogue to modify

Returns

An array of hashes detailing the new Download Category configuration

top

Set all the available download sizes for the site. Each item in the array is a list of hashes, accepting the following keys:

  • id - the download size's ID, or NULL for a new size. This key is mandatory
  • type - for compatibility with Get only; if provided this must match the type of the parent category
  • description - the description of the download size
  • width - the width in pixels of the download size
  • height - the height in pixels of the download size
  • format - the format identifier for the download size
  • vbr - Bitrate for video
  • abr - Bitrate for audio
  • asr - Sample rate for audio
  • duration - Cutoff time in seconds for audio/video
  • dpi - DPI for image
  • colourspace - Colour space for image
  • downloadCategoryId - the ID of the parent download category. See DownloadCategories.GetAvailableDownloadCategories
  • downloadCategoryName - for compatibility with Get only; this key will be ignored
  • dims - for compatibility with Get only; this key will be ignored
  • `isOriginal' - for compatibility with Get only; this key will be ignored

Hashes containing just the id key may be squashed to the ID. This permits reordering by passing a straightforward array of IDs.

For existing sizes, any keys may be omitted, in which case the corresponding property will be unchanged

IMPORTANT: any existing sizes whose ID is not provided to this function will be removed. It may be desirable to pass the optional categoryId parameter to restrict the scope of the changes.

DownloadCategories.SetAvailableDownloadSizes ( DOWNLOAD_SIZE_DETAILS[] sizes[, int[] categoryId = NULL][, int catalogue = 'dom0'] )

Type and Name Description

DOWNLOAD_SIZE_DETAILS[] sizes

An array of hashes describing the download sizes to set

int[] categoryId

A category ID or array of such. If supplied, edits will be restricted to these categories

int catalogue

The catalogue to modify

Returns

An array of hashes detailing the available Download Sizes

top

Updates the given download category with the provided details.

DownloadCategories.SetDownloadCategoryDetails ( int categoryId, DOWNLOAD_CATEGORY_DETAILS details )

Type and Name Description

int categoryId

The ID of the category to update.

DOWNLOAD_CATEGORY_DETAILS details

The details with which to update the download category.

Returns

The details of the updated download category.

top

Updates the given download size with the provided details.

DownloadCategories.SetDownloadSizeDetails ( int sizeId, DOWNLOAD_SIZE_DETAILS details )

Type and Name Description

int sizeId

The ID of the size to update.

DOWNLOAD_SIZE_DETAILS details

The details of which to update the download size.

Returns

The details of the updated download size.

Downloads top

Contents

Details

top

Adds a new History Note to a download

Depending on the site configuration, a history note may be required to perform a download. This method can be used to supply the requisite history note.

This action is only valid if the download is currently blocked by the absence of a note.

Downloads.AddHistoryNote ( int downloadId, string note )

Type and Name Description

int downloadId

The ID of the download to update

string note

The new history note

Returns

A [[Download Status]] hash

top

Deletes a download.

Downloads.DeleteDownload ( int downloadId )

void

Type and Name Description

int downloadId

The ID of the download to delete

Returns

void

top

Download one or more files, either as an original or using a predefined download size.

At least one of assetId and folderId must be specified.

This method will return a hash of details about the requested download

The options parameter supports keys as follows:

  • nothing - Currently not implemented
Variant Information: This method has 2 variants.
Variant 1

Downloads.Download ( int[] fileId[, int downloadSize = NULL][, string noteText = NULL][, hash options = array ( )] )

Type and Name Description

int[] fileId

An integer or array of [IMS File References] to download

int downloadSize

A download size to use for this download. If not specified, download the original file(s).

string noteText

An optional history note to attach to the download.

hash options

A hash containing details of the requested output. Supported keys detailed below.

Returns

Variant 2

Downloads.Download ( int[] folderId[, int downloadSize = NULL][, string noteText = NULL][, hash options = array ( )] )

Type and Name Description

int[] folderId

An integer or array of [[Folder References]] to download

int downloadSize

A download size to use for this download. If not specified, download the original file(s).

string noteText

An optional history note to attach to the download.

hash options

A hash containing details of the requested output. Supported keys detailed below.

Returns

top

Get the current status of a download task

Variant Information: This method has 2 variants.
Variant 1

Downloads.GetDownloadDetails ( mixed downloadId )

Type and Name Description

mixed downloadId

The ID or an array of IDs of the download to query

Returns

A Download Details hash

Variant 2

Downloads.GetDownloadDetails ( mixed downloadId )

Type and Name Description

mixed downloadId

The ID or an array of IDs of the download to query

Returns

A Download Details hash

top

Get all of the current user's download ids

Downloads.GetDownloadList ( )

int[]

Type and Name Description

Returns

int[]

The current download ids.

top

Get the details of the current user's download queue

Downloads.GetDownloadQueueDetails ( )

Type and Name Description

Returns

The download queue details.

top

top

top

Retrieve a list of all downloads that the user has yet to retrieve.

Downloads.GetUncollectedDownloads ( )

int[]

Type and Name Description

Returns

int[]

An array of download IDs

top

Validates each of the supplied crop settings for the supplied asset. Checks that a crop can be generated by the current user. The returned hash contains a key for each supplied crop, with the following details:

  • valid bool - true if the crop is valid
  • reason string - if not valid, why
  • constraintWidth int - the most zoomed in the crop can be to respect the user's settings
  • constraintHeight int - see above.

Downloads.GetUsersCropLimitsForAsset ( int assetId, hash crops[, int revision = NULL] )

Type and Name Description

int assetId

An IMS File Reference

hash crops

A list of crop settings, containing the following items: key, cropWidth and cropHeight

int revision

Optionally the asset's revision to use

Returns

A hash containing details for each crop, detailed above.

top

Validates each of the supplied crop settings for the supplied list of assets. Checks that a crop can be generated by the current user. The returned hash contains a key for each valid asset id, which contains a key for each supplied crop, with the following details:

  • valid bool - true if the crop is valid
  • reason string - if not valid, why
  • constraintWidth int - the most zoomed in the crop can be to respect the user's settings
  • constraintHeight int - see above.

Downloads.GetUsersCropLimitsForAssets ( array assetIds, hash crops )

Type and Name Description

array assetIds

An array of IMS File References to test

hash crops

A list of crop settings, containing the following items: key, cropWidth and cropHeight

Returns

A hash containing details for each crop for each asset, detailed above.

top

Get information pertinent to launching an advanced download tool on the requested files.

This method will return a hash of details indicating available download options for the selection.

Variant Information: This method has 2 variants.
Variant 1

Downloads.PrepareDownload ( int[] fileId )

Type and Name Description

int[] fileId

An integer or array of [IMS File References] to download

Returns

A hash of details containing keys as below

Variant 2

Downloads.PrepareDownload ( int[] folderId )

Type and Name Description

int[] folderId

An integer or array of [[Folder References]] to download

Returns

A hash of details containing keys as below

ExternalUsers top

Contents

Details

top

Get details about external users

Variant Information: This method has 2 variants.
Variant 1

ExternalUsers.Get ( int euId )

USER_DETAILS

Type and Name Description

int euId

The external users to get

Returns

USER_DETAILS

The updated details

Variant 2

ExternalUsers.Get ( int[] euIds )

USER_DETAILS[]

Type and Name Description

int[] euIds

The external users to get

Returns

USER_DETAILS[]

The updated details

top

Update details on an external user

ExternalUsers.SetDetails ( int euId, EXTERNAL_USER_SETTINGS details )

USER_DETAILS