Please note: The API is in a pre-release state. Methods and parameters may change without notice.

API Reference

The Third Light API allows third party developers to access core Third Light 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

Set ACLs for the provided folders, with the supplied member/rights mappings.

An audit-log entry will be created for this action

ACL.BatchSetForFolders ( int[] folderIds, MEMBER_RIGHTS_MAPPING[] memberRightsMappings )

void

Type and Name Description Required Rights

int[] folderIds

ID or GUID of folders to apply the ACLs for the supplied members/rights mappings. The folders must all be from the same Space.

  • editPermissions

MEMBER_RIGHTS_MAPPING[] memberRightsMappings

The details of the rights to provide for a member on each supplied folder ID or GUID.

Returns

void

top

Set ACLs for the provided member, with the supplied folder/rights mappings.

An audit-log entry will be created for this action

ACL.BatchSetForMember ( int spaceGuid, int memberGuid, FOLDER_RIGHTS_MAPPING[] folderRightsMappings )

void

Type and Name Description Required Rights

int spaceGuid

The Space in which to modify ACLs

  • manage

int memberGuid

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

FOLDER_RIGHTS_MAPPING[] folderRightsMappings

Folder/rights mapping to apply for the supplied member.

Returns

void

top

Creates a new ACL for a given folder and member.

An audit-log entry will be created for this action

ACL.Create ( int folderId, int memberGuid, FOLDER_ACL_RIGHTS rights[, ACL_WORKFLOW_MAPPING[] attachedWorkflows = NULL] )

Type and Name Description Required Rights

int folderId

The container for which to create the ACL.

  • editPermissions

int memberGuid

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

FOLDER_ACL_RIGHTS rights

The rights for the ACL.

ACL_WORKFLOW_MAPPING[] attachedWorkflows

Details of the concrete workflow definitions to attach to this ACL (will be ignored if Workflow Module not enabled).

Returns

The details of the created ACL.

top

Delete one or more ACLs.

An audit-log entry will be created for this action

ACL.Delete ( int[] aclIds )

void

Type and Name Description Required Rights

int[] aclIds

The ACLs to delete.

  • delete

Returns

void

top

Retrieve information for a particular ACL.

Not audit-logged
Variant Information: This method has 2 variants.
Variant 1

ACL.Get ( int aclId )

Type and Name Description Required Rights

int aclId

the ACL(s) to query

Returns

A hash of details about the ACL

Variant 2

ACL.Get ( int[] aclIds )

Type and Name Description Required Rights

int[] aclIds

the ACL(s) to query

Returns

A hash of details about the ACL

top

Get the details of the ACLs in the supplied folder.

Not audit-logged
Variant Information: This method has 2 variants.
Variant 1

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

Type and Name Description Required Rights

int folderId

ID or GUID of folder to query

  • editPermissions

ACL_GET_ALL_OPTIONS options

Options to configure what ACLs are returned by this method.

Returns

The ACLs for the supplied folderId.

Variant 2

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

Type and Name Description Required Rights

int[] folderIds

ID or GUID of folder to query

  • editPermissions

ACL_GET_ALL_OPTIONS options

Options to configure what ACLs are returned by this method.

Returns

The ACLs for the supplied folderId.

top

Get the GUIDs of the ACLs in the supplied folder.

Not audit-logged
Variant Information: This method has 2 variants.
Variant 1

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

string[]

Type and Name Description Required Rights

int folderId

ID or GUID of folder to query

  • editPermissions

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 Required Rights

int[] folderIds

ID or GUID of folder to query

  • editPermissions

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.

Not audit-logged
Variant Information: This method has 2 variants.
Variant 1

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

int[]

Type and Name Description Required Rights

int folderId

ID or GUID of folder to query

  • editPermissions

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 Required Rights

int[] folderIds

ID or GUID of folder to query

  • editPermissions

ACL_GET_ALL_OPTIONS options

Options to configure what ACLs are returned by this method.

Returns

int[][]

The ACLs for the supplied folderId.

top

Modify the details of an ACL.

An audit-log entry will be created for this action

ACL.Set ( int aclId, ACL_SET_DETAILS details )

Type and Name Description Required Rights

int aclId

ID or GUID of the ACL to update

ACL_SET_DETAILS details

updated details for the ACL.

Returns

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 Required Rights

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 Required Rights

int[] apiKeyId

The API Key to delete

  • delete

Returns

void

top

Retrieve a list of all API Keys configured.

Not audit-logged

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

string[]

Type and Name Description Required Rights

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.

Not audit-logged

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

int[]

Type and Name Description Required Rights

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.

Not audit-logged

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

Type and Name Description Required Rights

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.

Not audit-logged
Variant Information: This method has 2 variants.
Variant 1

APIKey.GetApiKeyDetails ( int apiKeyId )

Type and Name Description Required Rights

int apiKeyId

IDs of the API key to get the detials for.

Returns

Variant 2

APIKey.GetApiKeyDetails ( int[] apiKeyId )

Type and Name Description Required Rights

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 Required Rights

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

Not audit-logged
Variant Information: This method has 2 variants.
Variant 1

AuditLogs.Get ( int auditLog )

Type and Name Description Required Rights

int auditLog

Logs to get details

Returns

Variant 2

AuditLogs.Get ( int[] auditLog )

Type and Name Description Required Rights

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

Not audit-logged

AuditLogs.GetAvailableCategories ( )

Type and Name Description Required Rights

Returns

top

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

hashes.

Not audit-logged
Variant Information: This method has 2 variants.
Variant 1

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

Type and Name Description Required Rights

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 Required Rights

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 Required Rights

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 Required Rights

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 description = NULL] )

Type and Name Description Required Rights

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

  • manage

string name

An optional name for the contact

string description

An optional description for the contact

Returns

A hash containing details about the added contact

top

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

Not audit-logged

Catalogue.GetAvailableCategoriesForCatalogue ( int catalogue )

string[][]

Type and Name Description Required Rights

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

Not audit-logged

Catalogue.GetAvailablePanelGUIDsForCatalogue ( int catalogue )

string[][]

Type and Name Description Required Rights

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

Not audit-logged

Catalogue.GetAvailablePanelsForCatalogue ( int catalogue )

Type and Name Description Required Rights

int catalogue

The catalogue to modify

Returns

top

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

Not audit-logged

Catalogue.GetCategories ( int catalogue )

string[]

Type and Name Description Required Rights

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

Not audit-logged

Catalogue.GetContactList ( [int catalogue = 'me'][, string nameFilter = NULL] )

Type and Name Description Required Rights

int catalogue

The catalogue to query

string nameFilter

Optional. The string to filter based on the name of the returned user. This filters based on the string being anywhere in the external user's name.

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

Not audit-logged

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

Type and Name Description Required Rights

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.

Not audit-logged

Catalogue.GetLocalCategories ( int catalogue )

Type and Name Description Required Rights

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.

Not audit-logged

Catalogue.GetLocalPanels ( int catalogue )

Type and Name Description Required Rights

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.

Not audit-logged

Catalogue.GetLocalShortlist ( int catalogue )

Type and Name Description Required Rights

int catalogue

The catalogue to modify

Returns

top

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

Not audit-logged

Catalogue.GetPanelGUIDsOnContext ( int catalogue )

string[]

Type and Name Description Required Rights

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

Not audit-logged

Catalogue.GetPanelIDsOnContext ( int catalogue )

int[]

Type and Name Description Required Rights

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

Not audit-logged

Catalogue.GetPanels ( int catalogue )

string[]

Type and Name Description Required Rights

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

Not audit-logged

Catalogue.GetParentCategories ( int catalogue )

Type and Name Description Required Rights

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.

Not audit-logged

Catalogue.GetParentPanels ( int catalogue )

Type and Name Description Required Rights

int catalogue

The catalogue to modify

Returns

top

Get the parent sizes associated with a catalogue, in order

Not audit-logged

Catalogue.GetParentShortlist ( int catalogue )

Type and Name Description Required Rights

int catalogue

The catalogue to modify

Returns

top

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

Not audit-logged

Catalogue.GetShortList ( int catalogue )

string[]

Type and Name Description Required Rights

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 Required Rights

int externalUserId

The external user to remove

int catalogue

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

  • manage

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 Required Rights

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 Required Rights

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 Required Rights

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 Required Rights

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 Required Rights

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 Required Rights

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 Required Rights

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 Required Rights

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 Required Rights

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 Required Rights

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 Required Rights

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 Required Rights

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 Required Rights

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 Required Rights

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 Required Rights

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

Not audit-logged

Config.GetConfigSettings ( string settingKey )

Type and Name Description Required Rights

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.

Not audit-logged

Config.GetDefaultPasswordPolicy ( )

Type and Name Description Required Rights

Returns

The default password policy.

top

Gets information about the current scope of the LDAP config

Not audit-logged

Config.GetLDAPScope ( )

Type and Name Description Required Rights

Returns

The test response containing a success flag and a message.

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

Not audit-logged

Config.GetMetadataFields ( )

string[][]

Type and Name Description Required Rights

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
Not audit-logged

Config.GetPasswordPolicy ( )

Type and Name Description Required Rights

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.

Not audit-logged

Config.GetSettingOptions ( hash settings )

string[][]

Type and Name Description Required Rights

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.

Not audit-logged

Config.GetSettingValues ( string|string[] settings )

string[]

Type and Name Description Required Rights

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

Join an LDAP domain

This is focussed on Active Directory, but should support other similar DNS-registered domain systems

This is a wizard-based system that will look up the domain in DNS, attempt to identify an appropriate site with it, connect to relevant local DCs and Global Catalogs, and provision a computer binding account

It returns an ENUM that indicates where a possible problem may have occurred - in general you should then re-call this method, adding the relevant optional parameters.

For generic LDAP support, specify settings directly rather than using this.

Config.JoinDomain ( string dnsDomain, string domainAdminUser, string domainAdminPass[, string baseDN = NULL][, bool reuseComputer = NULL][, string computerAccountOU = NULL][, string computerName = NULL][, string[] domainControllers = NULL][, string[] globalCatalogs = NULL] )

Type and Name Description Required Rights

string dnsDomain

The full DNS name of the domain (e.g. contoso.com)

string domainAdminUser

The username of a domain administrator, with permission to create a new bind account. This account is not stored, and is only used to join the domain.

string domainAdminPass

The password for the above user. This account is not stored, and is only used to join the domain.

string baseDN

The base search DN for your domain. This may be required if no Global Catalog servers are available.

bool reuseComputer

True to allow an existing computer account to be reused. You should usually only specify this if you have previously had a COMPUTER_ACCOUNT_FOUND response and checked that it is not otherwise in use.

string computerAccountOU

Specify a full DN to the location to create the computer account. Defaults to the "Computers" container within the base DN.

string computerName

Defaults to the hostname of the running server. May be overridden if, e.g., that is already used elsewhere, or for a cluster where a single node hostname is not appropriate.

string[] domainControllers

A list of domain controllers - this should normally only be specified if you have previously had a NO_DNS error. Each entry should be an LDAP URI, although a bare hostname or hostname:port will be accepted if possible.

string[] globalCatalogs

A list of global catalogs - this should normally be specified if and only if domainControllers is too. Each entry should similarly be an LDAP URL, although a bare hostname or hostname:port will be accepted if possible.

Returns

OK or the type of error encountered

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 Required Rights

hash settings

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

Returns

top

Test the configured IDP Metadata URL. If it works, the contents are returned in the response, abbreviated if they exceed 100,000 characters. If not, the error will be returned instead.

Not audit-logged

Config.TestIdpMetadataURL ( string url )

Type and Name Description Required Rights

string url

The URL to test

Returns

The test response containing a status 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 Required Rights

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 Required Rights

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

Not audit-logged

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

string[]

Type and Name Description Required Rights

int scope

The parent context for which to get children

  • child:view

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

*/

Not audit-logged
Variant Information: This method has 2 variants.
Variant 1

Contexts.GetDetails ( int context )

Type and Name Description Required Rights

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 Required Rights

int[] context

An array of contexts for which details should be returned.

Returns

Details of the requested contexts

top

Get the logical areas for a particular space The caller must be a manager of the space to use this method. The returned contexts will be those of which the space is a member and are visible to the caller.

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

Not audit-logged

Contexts.GetForSpace ( int objContext )

string[]

Type and Name Description Required Rights

int objContext

The parent context for which to get children

  • manage

Returns

string[]

An array of contextIDs

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

Not audit-logged

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

string[]

Type and Name Description Required Rights

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 Required Rights

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 Required Rights

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, int destination )

Type and Name Description Required Rights

array guids

An array of GUIDs of objects to test for move

int 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 Required Rights

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 Required Rights

int guids

An array of GUIDs of objects to delete

Returns

Variant 2

Core.Delete ( array guids )

void

Type and Name Description Required Rights

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 Required Rights

Returns

top

Elevates the current session to gain available administrative privileges.

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

Type and Name Description Required Rights

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 ...
Not audit-logged

Core.GetAPIListing ( )

Type and Name Description Required Rights

Returns

Keyed by module name and method name

top

We use this for IMS7

Not audit-logged

Core.GetAPIListingForIMS7 ( )

Type and Name Description Required Rights

Returns

Keyed by module name and method name

top

Gets summary information for each available API module.

Not audit-logged

Core.GetAPIModuleInformation ( )

string[]

Type and Name Description Required Rights

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)

Not audit-logged
Variant Information: This method has 2 variants.
Variant 1

Core.GetAccessiblePath ( int guids )

Type and Name Description Required Rights

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 Required Rights

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

Not audit-logged

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

string

Type and Name Description Required Rights

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.

Returns

string

A URL to direct the user to

top

Get the GUIDs of the dereferenced file or folder links. If supplied GUID is for a folder or file, it will still be returned in the response.

Not audit-logged
Variant Information: This method has 2 variants.
Variant 1

Core.GetDereferenced ( string guid )

Type and Name Description Required Rights

string guid

GUIDs to look up

Returns

Details of the originals

Variant 2

Core.GetDereferenced ( string[] guids )

Type and Name Description Required Rights

string[] guids

GUIDs to look up

Returns

Details of the originals

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

Not audit-logged
Variant Information: This method has 2 variants.
Variant 1

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

Type and Name Description Required Rights

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

Variant 2

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

Type and Name Description Required Rights

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

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.

Not audit-logged

Core.GetEnvironment ( )

Type and Name Description Required Rights

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.

Not audit-logged

Core.GetFileCount ( )

int

Type and Name Description Required Rights

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.

Not audit-logged

Core.GetPictureCount ( )

int

Type and Name Description Required Rights

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.

Not audit-logged

Core.GetSessionExpiry ( )

Type and Name Description Required Rights

Returns

Details of time remaining until the current session expires.

top

Returns details about the currently active user.

Not audit-logged

Core.GetUserDetails ( )

Type and Name Description Required Rights

Returns

top

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

Not audit-logged

Core.Handshake ( )

Type and Name Description Required Rights

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 Required Rights

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 Required Rights

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 Required Rights

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 Required Rights

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 Required Rights

Returns

void

top

Move a list of GUIDs to a specified destination

This supports files, file links, folders and folder links

Core.Move ( array guids, int destination[, bool upgradeFunctionalLevels = false][, bool forceSync = true] )

Type and Name Description Required Rights

array guids

An array of GUIDs of objects to move

int 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.

bool forceSync

If true, this forces this method to run synchronously, otherwise, if there are more than items the move will be performed asynchonously.

Returns

top

Recycle a list of GUIDs

This supports files and folders only

Variant Information: This method has 2 variants.
Variant 1

Core.Recycle ( int guids )

Type and Name Description Required Rights

int guids

An array of GUIDs of objects to delete

Returns

Variant 2

Core.Recycle ( array guids )

void

Type and Name Description Required Rights

array guids

An array of GUIDs of objects to delete

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 Required Rights

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 Required Rights

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 Required Rights

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 Required Rights

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 Required Rights

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 Required Rights

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 Required Rights

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 Required Rights

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.
Not audit-logged

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

Type and Name Description Required Rights

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
Not audit-logged
Variant Information: This method has 2 variants.
Variant 1

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

Type and Name Description Required Rights

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 Required Rights

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.

Not audit-logged
Variant Information: This method has 2 variants.
Variant 1

DownloadCategories.GetDownloadCategoryDetails ( int categoryId )

Type and Name Description Required Rights

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 Required Rights

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.

Not audit-logged
Variant Information: This method has 2 variants.
Variant 1

DownloadCategories.GetDownloadSizeDetails ( int sizeId )

Type and Name Description Required Rights

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 Required Rights

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.

Not audit-logged

DownloadCategories.GetDownloadSizeInfo ( int assetId )

Type and Name Description Required Rights

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.
Not audit-logged

DownloadCategories.GetEditableDownloadCategories ( [