CIP - Canto Integration Platform

Canto Integration Platform
Developer Guide

It is assumed the reader is familiar with the concept of web service software technologies and in particular RESTful web services. You should be familiar with programming concepts related to the HTTP protocol, and data exchange mechanisms such as JSON or XML.

The Canto Integration Platform (CIP) is a web service that runs inside a web application container such as Apache Tomcat. The service is providing functionality via HTTP requests of type GET and POST. Unlike other RESTful web services CIP does not use the HTTP requests DELETE, PUT to make it easier to get started by just using a web browser.

You can use named parameter debug=1 to access all operations via HTTP GET method.

1.1. Pre-Requisites

Before going any further, please ensure you have the following setup.

You must have a running a Cumulus 8.5.x server. CIP works with both Workgroup and Enterprise editions of the Cumulus server. CIP does not work with Cumulus Single User, or versions of Cumulus earlier than Cumulus 8.5.
Your Cumulus Server needs an optional serial number for letting the CIP connect to it. This serial number needs to be activated.
Make sure your Cumulus server has a client license free to support write activities. CIP will reserve one or more licenses on startup (depending on your configuration).
Install CIP on some computer. It does not have to be the same as the one running the Cumulus Server.
For development you should have an up to date version of the Firefox browser with the “JSONView” plug-in installed. This will allow you to better see the results of some RESTful requests directly in the browser.
For developing your client-side code you can use whatever environment you feel comfortable with. CIP comes with a set of sample source files in different languages to be included in your project.

1.2. Secure Communication (Optional)

You can configure your web application server (e.g. Apache Tomcat) to use SSL for communicating with any client-side software. This ensures that all data is encrypted and cannot be decoded by any attacker. The actual configuration depends on the web application server software used.

The instructions for Apache Tomcat can be found here:

http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html

1.3. Authentication (Optional)

When accessing the Cumulus DAM system CIP needs to connect using a valid Cumulus user name and password. There are several options available in CIP to be used (in the given order, if available):

Provide the user name and password in the request URL using the named parameters “user” and “password.”
Provide the user name and password in the request using HTTP Basic Access Authentication (http://en.wikipedia.org/wiki/Basic_access_authentication).
Provide a session ID for a valid session in the request. The session had to be opened with valid credentials.
In the URL refer to a catalog alias definition in the configuration file that includes user name and password.
Without any of the above CIP will reply to the client according to the HTTP Basic Access Authentication protocol (http://en.wikipedia.org/wiki/Basic_access_authentication). In case the client software is a web browser it will ask the user to enter name and password for the realm “CIP.”

1.4. Session Handling (Optional)

Besides the typical HTTP Request-Response protocol CIP supports keeping a session for answering requests. The session is identified by a session ID and can store credentials and collections of items to be used across several requests. This way you only need to provide the credentials when opening the session and subsequent requests do not need the credentials anymore.

To start a session you call the “open” operation of the “session” service. This will create a new session at the CIP and will return a “jsessionid” cookie as well as the “jsessionid” value in the response data. The value of “jsessionid” is an arbitrary string that your client software needs to keep.

Your client software then provides the “jsessionid” with every subsequent request. You can use either the HTTP cookie mechanism or URL rewriting to provide the “jsessionid” value to CIP.

When you are done with the session you can call the “close” operation of the “session” service to close the session at the server (also providing the “jsessionid”). Every attempt to issue another request for the same session will fail after the session is closed.

1.5. Priority of Catalog Access Parameters

You have several options for specifying the parameters for catalog access: user, password, serveradddress, catalogname. They can be configured in the CIP configuration for a catalog, they can be kept in a session in the server and you can specify them in a request.

The CIP server evaluates these parameters in the following priority

Passing the parameter in a request has the highest priority and overwrites any of the below.
If you specified a collection name in the request the information kept in the collection is taken.
If you specified a session (passing a valid jsessionid) the parameter is taken from the session if it was specified when opening the session.
If the parameter is not specified by any of the above it is taken from the catalog configuration in the XML file.

Examples

a) Assume you have configured the following catalog:

Example Configuration

<?xml version="1.0" encoding="UTF-8"?>
<config>
...
    <catalogs>
    ...
        <catalog aliasName="mycatalog">
            <serverAddress>localhost</serverAddress>
            <userName>sample</userName>
            <password>sample</password>
            <catalogName>Sample Catalog</catalogName>
        </catalog>
    ...
    </catalogs>
...
</config>

Example Request

http://cip-server:port/CIP/session/open?catalogname=Test+Catalog

Example Response

    {
        "jsessionid" : "A045F54785152CE916F8ABA6916D22F4"
    }

Example Request

http://cip-server:port/CIP/metadata/search/mycatalog;jsessionid=A045F54785152CE916F8ABA6916D22F4?quicksearchstring=Zebra

The above will search in the catalog "Test Catalog" because the parameter catalogname is taken from the session and overwrites the catalog name specified in the configuration.

1.6. Data Model of a DAM System

CIP is assuming that the data inside a DAM system is organized in the following way:

A DAM server identified by the server address string is serving one or more catalogs.

Each catalog consists of one or more tables which are identified by their name. The table with the name "AssetRecords" is storing asset information, another table named "Categories" contains categories. Additional tables may exsist to store other information not directly related to assets.

Each table stores zero or more items identified by a number called "item ID."

The item ID is a unique identifier of an item inside a table of a catalog. You can safely identify the item representing an asset by specifying the catalog name and item ID (the table name for asset items is fixed).

The item ID is automatically generated and stable during the lifetime of an item.

1.7. Using Connection Pooling with the Cumulus DAM system

When using Cumulus as the underlying DAM system you can configure the pooling to use when the user name is taken from a configured catalog alias.

Whenever you specify a user name in a request the CIP server will not attempt to use a connection pool but will create a separate connection to the server. To get better performance for subsequent requests with the same user name you should open a session using the user name and password as parameters. In this case the connection will be kept open and stored in the server-side session data.

We recommend using a pool to improve the request handling performance whenever you have configured a technical user to be used to connect to the Cumulus server.

If you want to use a pool you can configure the maximum size and some other parameters for the pool in the CIP configuration file (see the section about configuration below).

For each combination of a user name and catalog the CIP server will keep a separate pool of connections to the catalog.

Each pool (combination of user name and cataog) that is used for write access occupies a separate client license at the Cumulus server.

To let CIP server support the configured pool maximum size you need to activate an additional serial number at the Cumulus server:

The "CIP Pooling 3" license allows to configure a maximum pool size of up to 3 connections.
The "CIP Pooling 10" license allows to configure a maximum pool size of up to 10 connections.
The "CIP Pooling 50" license allows to configure a maximum pool size of up to 50 connections.
The "CIP Pooling Unlimited" license allows to configure a pool of any maximum size.

Examples

a) Assume you have configured the following pooling parameters:

Example Configuration

<?xml version="1.0" encoding="UTF-8"?>
<config>
    <catalogs>
    ...
        <catalog aliasName="mycatalog">
            <serverAddress>localhost</serverAddress>
            <userName>sample</userName>
            <password>sample</password>
            <catalogName>Sample Catalog</catalogName>
        </catalog>
    ...
    </catalogs>
...
    <dam>
    ...
        <parameter name="com.canto.cumulus.pool.maxsize">5</parameter>
        <parameter name="com.canto.cumulus.pool.minsize">1</parameter>
    ...
    </dam>
...
</config>

Example Request

http://cip-server:port/CIP/metadata/search/mycatalog/myfields?quicksearchstring=zebra

The above will cause a pool of connections to be created for the user "sample" to acces the catalog "Sample Catalog" because the request is using a configured catalog alias.
The pool will start with a size of 1 connection but if subsequent requests find that all connections are in use for other requests the pool will grow to a maximum size of 5 connections.
Because the request is a read-only request no additional client license is occupied at the Cumulus server.
If the request would be one that modifies catalog data a writing pool for the user and catalog will be created which occupies an additional client license.
In order to support the maximum pool size of 5 connections you need to activate a CIP Pooling license at the Cumulus server.
The CIP Pooling license must be chosen so that it covers the configured maximum pool size: "CIP Pooling 10", "CIP Pooling 50", or "CIP Pooling Unlimited" would do this.

2. Services and Operations

The operations (functions) that CIP provides to clients are grouped into different “services.”
Each service offers a set of operations that conceptually belong together.
The URL for an operation always starts with the following:

http://cip-server:port/CIP/service/operation/path-parameters?named-parameters

The “cip-server” and “port” are the address and port number of the CIP web application server.
The “cip” specifies the web application “CIP”
The “service” is the name of the CIP service (operation group, always in lower case)
The “operation” is the name of operation inside the service (always in lower case)
The “path-parameters” are the optional path elements that the operation uses. Typically only parameters that need to occur exactly once for the operation are given as path-parameters. If a parameter is optional or can occur more than once it is typically provided using named parameters.
The “named-parameters” are optional parameters for the operation. Typically parameters that are optional or can occur more than once are passed this way. As usual in URLs named parameters are passed using “name=value” notation using a “&” to separate them.

Here is an overview of the services that CIP provides:

session - Creating and closing a session
metadata - Operations for searching, reading, and writing asset metadata
preview - Operations for generating images of assets in different sizes
asset - Operations for getting or uploading assets
developer - Operations for helping developers (e.g. generating client source code)
system - Operation for retrieving information about the CIP server system

2.1. Session Service

This service provides operations to create and close server-side sessions.
A session can store the credentials for later use in any subsequent request for the same session.
Any credentials provided explicitly with a request take precedence over session credentials.

2.1.1. session/open

Open a new session at the server. You can provide user name and password to store them in the session for subsequent requests.
The credentials can be provided in two different ways:

As named URL parameters “user” and “password”
In the HTTP request header following the HTTP “Basic Access Authentication” standard

The first option is more flexible as it can also handle user names and passwords that contain colon (":") characters.
If you want to hide the credentials and encrypt all communication you should configure your web application server to use SSL.
Then each URL you call needs to start with “https” instead of “http.”

Allowed HTTP method: POST

Available since: 8.5.2

Named Parameters

Parameter Type Description

apiversion

integer (optional)

Determine which API version should be used for the request processing. It's guarantee backwards compatibility for future releases. An application created to work with a given API version will continue to work with that same API version. If this parameter is not present then the newer API version will be used.

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

serveraddress string (optional) The DAM server IP address for later catalog access. e.g. localhost, 192.168.0.2

user string (optional) The user name for login to the server for later catalog access.

password string (optional) The password for login to the server. The user’s password to be used for later catalog access

catalogname string (optional) The DAM system catalog name for later catalog access e.g. Sample Catalog

locale string (optional) The two-letter language code (ISO 639-1) to be used for later catalog metadata fields access.

Result

The result contains the session ID of the newly created session. The session ID is returned as a HTTP cookie "jsessionid" as well as in the response text.

Examples

a) Open a new session at the server:

Example Request

http://cip-server:port/CIP/session/open?user=myself&password=secret

Example Response

    {
        "jsessionid" : "F045F54785152CE916F8ABA6916D22F4"
    }

2.1.2. session/close

Close an existing session at the server.
Any subsequent request for this session will fail after this operation is executed.
You need to provide a session ID (see section about session handling above) for this operation.

Allowed HTTP method: POST

Available since: 8.5.2

Named Parameters

Parameter Type Description

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

Result

None.

Examples

a) Close an existing session at the server:

Example Request

http://cip-server:port/CIP/session/close

2.2. Metadata Service

The main purpose of the metadata service is to provide operations for searching, retrieving, and modifying metadata. When searching you have the following options to keep the result:

Immediately return all IDs of the resulting items.
Immediately return metadata field values for each of the items of the result.
Store the resulting item IDs in a collection by optionally combining this search result with the previous contents of the collection. You then use the getfieldvalues operation to retrieve metadata for items in the collection. This way you can implement “paging” through a long list of items without returning metadata for all items found in a single operation.

Collections
The search operations allow you to optionally store the result in a named collection which is stored in the current session (see session handling above). You give the collection a name which has to be unique within the current session. The collection is bound to a specific catalog and table within the catalog and only contains a list of item IDs.

After storing a search result in a collection you can then either retrieve the metadata for items in the collection using a getfieldvalues operation or combine the collection with the result of a subsequent search operation. Each search always returns the total number of items found. The getfieldvalues operation allows you to specify a starting offset in the item IDs and a maximum number of items to return. This way you can implement client-side “paging” through a long list of resulting items.

2.2.1. metadata/getcatalogs

Return a list of all catalogs that the given user is able to work with.

Allowed HTTP methods: GET and POST

Available since: 8.5.2

Named Parameters

Parameter Type Description

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (required) The DAM system user name.

password string (required) The DAM system user’s password.

serveraddress string (required) The DAM system server IP address e.g. localhost, 192.168.0.2

Result

The result is the list of catalog names.

Examples

a) Get the names of all catalog on the server "localhost":

Example Request

http://cip-server:port/CIP/metadata/getcatalogs?user=myuser&password=mypassword&serveraddress=localhost

Example Response

    {
        "catalogs" : [
            {
                "id"   : 3,
                "name" : "Sample Catalog"
            },
            {
                "id"   : 5,
                "name" : "Test Catalog"
            }
        ]
    }

2.2.2. metadata/gettables

Return a list of all table names of a catalog.

Allowed HTTP methods: GET and POST

Available since: 8.5.2

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.

Named Parameters

Parameter Type Description

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result is the list of table names.

Examples

a) Get the names of all tables of the catalog with the alias “mycatalog”:

Example Request

http://cip-server:port/CIP/metadata/gettables/mycatalog

Example Response

    {

        "tables" : [
            "AssetRecords",
            "AssetRecords/{a89b908c-e98e-413b-ac4d-50668b2fafbc}",
            "AssetRecords/{04a4080f-fec0-4e01-822f-b9125c0b5ac9}",
            "AssetRecords/{04a4080f-fec0-4e01-822f-b9125c0b5ac9}/{03504c8d-c809-461c-a62e-55a4bd6c1adf}",
            "Categories"
        ]

    }

2.2.3. metadata/getlayout

Return a description of all the fields of a given table.

Allowed HTTP methods: GET and POST

Available since: 8.5.2

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.
`view`	string (optional)	The name of a view definition from the configuration file which defines a list of fields to use. See the configuration section on details on how to define views. The field list can be extended with additional fields specified in named request parameters.

Named Parameters

Parameter Type Description

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

table string (optional) You may want to specify the table to return the layout for. The default is "AssetRecords".

locale string (optional) The two-letter language code (ISO 639-1) to be used for the metadata field names and values for the result. This parameter affects the way field names and language-dependent metadata values are returned. For example you can specify “fr” to return all values suitable for French users. The default is the default locale the CIP server is running in (may be controlled using the “user.language” Java VM parameter when starting the web application server).

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result is the list of field definitions of the given table.
Each field definition contains the type of the field, the field name in the language of the specified locale and the user editable flag.
Fields of type Enum also contain a list of possible values which consist of an ID and a name in the given locale.

Examples

a) Get the asset records layout for the catalog with the alias “mycatalog” and view with the alias fields:

Example Request

http://cip-server:port/CIP/metadata/getlayout/mycatalog/fields

Example Configuration

    <view name="fields">
        <field>Status</field>
        <field>Status Label</field>
        <field>Record Name</field>
    </view>

Example Response

{

    "fields": [
        {
            "name": "Status",
            "type": "Enum",
            "usereditable": true,
            "sortable": true,
            "mandatory": false,
            "aliasname": "Status",
            "key": "{af4b2e07-5f6a-11d2-8f20-0000c0e166dc}",
            "values": [
                {
                    "id": 0,
                    "displaystring": "approved"
                },
                {
                    "id": 1,
                    "displaystring": "needs approval"
                },
                {
                    "id": 2,
                    "displaystring": "rejected"
                }
            ]
        },
        {

            "name": "Status Label",
            "type": "Label",
            "usereditable": false,
            "sortable": true,
            "mandatory": false,
            "aliasname": "Status Label",
            "key": "{d6ac1536-6ae3-41ea-8e92-d978f0fce2c2}",
            "labels": [
                {
                    "id": 0,
                    "color": "#FF796B"
                },
                {
                    "id": 1,
                    "color": "#FCBA58"
                },
                {
                    "id": 2,
                    "color": "#F0E45F"
                },
                {
                    "id": 3,
                    "color": "#B7E05F"
                },
                {
                    "id": 4,
                    "color": "#64ABFE"
                },
                {
                    "id": 5,
                    "color": "#D09ADD"
                },
                {
                    "id": 6,
                    "color": "#B5B5B5"
                },
                {
                    "id": 7,
                    "color": "#FFFFFF"
                },
                {
                    "id": 8,
                    "color": "#000000"
                }
            ]

        },
        {
            "name": "Record Name",
            "type": "String",
            "usereditable": true,
            "sortable": true,
            "mandatory": false,
            "aliasname": "Record Name",
            "key": "{af4b2e00-5f6a-11d2-8f20-0000c0e166dc}"
        }
    ]

}

2.2.4. metadata/search

Perform a search using a combination of QuickSearch, query string, or configured named query.
You must specify at least one of the following parameters: quicksearchstring, queryname, querystring to perform a search.
You can combine a quicksearch string with a normal search query string or named query. If you specify more than one parameter the single queries will be joined to complex one with the AND operator.

A query configuration can be defined in different ways:

A “QuickSearch” performed using a simple search string that searches across multiple metadata fields depending on the DAM system (use parameter quicksearchstring).
A preset query stored in the DAM system (use parameter queryname). This is best suited for searches using a fixed query that is also used by other users of the DAM system.
A query string that may contain placeholders to be replaced with URL named parameters at runtime (use parameter queryname). This is best suited for searches using a query with some variable parts that are specified in the request.
A query string explicitly provided with the request (use parameter querystring). This is best suited for any query that is created at runtime.

Allowed HTTP method: POST

Available since: 8.5.2

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.
`view`	string (optional)	The name of a view definition from the configuration file which defines a list of fields to use. See the configuration section on details on how to define views. The field list can be extended with additional fields specified in named request parameters. If no view or fields are specified then the resulting list of items is just an array of item IDs.

Named Parameters

Parameter Type Description

quicksearchstring string (optional) The text to perform a quicksearch with. It can be combined with a normal search query string or named query. The result depends on the DAM system and its configuration.

queryname string (optional) The name of a query defined in the CIP configuration file. It can be combined with a quicksearchstring or a normal search query string. The defined query is either one that is preset in the DAM system or is configured using a query string with optional placeholders. By convention the placeholders are named using an underscore as a prefix to avoid using a name that is later being defined by CIP. See the configuration file section for details on how to define queries.

querystring string (optional) The complete query string as expected by the DAM system. It can be combined with a quicksearchstring or a named query. You need to make sure all special characters are correctly escaped if you want to pass this parameter in an HTTP request URL. It is recommended to pass the parameter in the body of the request instead.

locale string (optional) The two-letter language code (ISO 639-1) to be used for parsing the query string and also for the metadata field values to be returned. This parameter affects the way language-dependent metadata values are returned. For example you can specify “fr” to interpret date values in the query in French format and to return all values suitable for French users. The default is the default locale the CIP server is running in (may be controlled using the "user.language" Java VM parameter when starting the web application server).

sortby

string array (optional)

A field name or field ID with optional sort direction separated by colon (e.g. ID:descending or ID) to specify the fields to be used for sorting the result. The default is that the result is not sorted by any field.

Supported values for sort direction:

`ascending`	(Default)
`descending`

collection string (optional) The name of a collection to save the resulting list of IDs. If you leave the value empty then CIP will create a unique collection name for you and will return this name in the result. This can be used for a temporary collection to make sure the name is unique in the session. When also using the parameter combine you can combine the existing collection contents with the result of this search operation.

combine

string (optional)

This parameter is only used when using a stored collection (see collection parameter above). It specifies how the result of this search operation is combined with the contents of the collection specified. If not specified the collection is created from this search operation’s result.

Supported values:

`new`	Default, do not use the previous contents of the specified collection but store the result of this search operation in the collection
`narrow`	Only keep items in the collection that are also in the result of this search operation.
`broaden`	Add all items of the result of this search operation to the collection (if not contained already).

table string (optional) You may want to specify the table in which the search should be performed. The default is "AssetRecords".

startindex

integer (optional)

The index (zero-based) to start returning the items. Using this parameter you can page through the result list by starting with 0 and then incrementing by a given number. The default is 0 which returns the items starting with the first one.

Available since: 8.6

maxreturned

integer (optional)

The maximum number of items returned by this operation. You may use this parameter to limit the size of the resulting JSON data. When used together with the startindex parameter you can implement paging through the result list. The default is to return all items starting at the one specified by the startindex parameter. Due to changes being encountered in the catalog this operation may return less than the specified number of items if items in the given range have been deleted from the catalog. However, to do proper paging you should start the next getfieldvalues operation at the index you calculate from the given parameters startindex and maxreturned.

Available since: 8.6

field

string array (optional)

You can select the fields that should be returned by specifying one or more of these named parameters.
The value for this parameter has the same format as the field specification in the view configuration.
For the Cumulus DAM system it is sometimes preferable to specify the field using the field UID and optionally the field name and an alias name.
When also specifying a configured view as a path parameter you can extend the view fields with the ones specified in the request.
By configuring an empty view you can let CIP return only the fields that are specified in the request.

Virtual fields (Available since: 8.6.1):

`{50f54d0a-0ebe-46ce-bf3c-dbb744349650}`	UID of a virtual field that contains the number of records being assigned to a category
`{b46eddc9-dc90-4e31-9474-bee1b9a3fd12}`	UID of a virtual field that contains the number of records being assigned to a category including its sub-categories
`{e85fd04a-7e4f-4718-9879-92c0f22ba892}`	UID of a virtual field that contains list of names of fields that the current user is allowed to modify

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result is returned in JSON format and consists of the total number of items returned and a list of items with the field values defined in the given view.
If no view and no collection are specified then the list of items is just an array of item IDs.
If no view but a collection is specified the result just returns the total count and the name of the collection. The item field values or IDs can then be retrieved using the getfieldvalues operation.

Examples

a) Perform a QuickSearch using the text “sample” and return the field values defined in the view “myfields” for all items found:

Example Request

http://cip-server:port/CIP/metadata/search/mycatalog/myfields?quicksearchstring=sample&sortby=ID:descending&sortby=Record%20Name

Example Configuration

    <view name="myfields">
        <field>Status</field>
        <field>Record Name</field>
        <field>Rating</field>
    </view>

Example Response

        {
            "items" : [
                {
                    "Status" : {
                        "displaystring" : "in progress",
                        "id"            : 0
                    },
                    "Record Name" : "IMG_3145.tif",
                    "Rating"      : 3
                },
                {
                    "Status" : {
                        "displaystring" : "approved",
                        "id"            : 1
                    },
                    "Record Name" : "IMG_6345.tif",
                    "Rating"      : 5
                }
            ],
            "totalcount" : 2
        }

b) Perform a search using a configured query containing a placeholder and only return the list of IDs. To return only a list of IDs the view path parameter is omitted. To specify a parameter for the query the placeholder name _status is used.

Example Request

http://cip-server:port/CIP/metadata/search/mycatalog?queryname=parameterquery&_status=approved

Example Configuration

    <?xml version="1.0" encoding="UTF-8"?>
    <config>
    ...
        <queries>
        ...
            <query name="parameterquery">
                <querystring>Status == ${_status}</querystring>
            </query>
        ...
        </queries>
    ...
    </config>

Example Response

        {
            "totalcount" : 2,
            "items"      : [
                1,
                5
            ]
        }

c) Perform a search using the query “"Host Item ID" is 136” in the table “AssetRecords/{a89b908c-e98e-413b-ac4d-50668b2fafbc}” and return the field values defined in the view “myusagefields” for all items found:

Example Request

http://cip-server:port/CIP/metadata/search/mycatalog/myusagefields?querystring="Host Item ID" is 136&table=AssetRecords/{a89b908c-e98e-413b-ac4d-50668b2fafbc}

Example Configuration

    <view name="myusagefields">
        <field>Asset Usage</field>
        <field>Date</field>
        <field>Host Item ID</field>
        <field>User</field>
        <field>Additional Information</field>
    </view>

Example Response

        {
            "items" : [
                {
                    "id"          : 176,
                    "Date"        : "/Date(1242028804000)/",
                    "Asset Usage" : {
                        "id"            : 1,
                        "displaystring" : "Copy To"
                    },
                    "Host Item ID"           : 136,
                    "User"                   : "U:{98ca1422-0171-4d1d-8b84-8cdda4ab70ae}:Peter",
                    "Additional Information" : null
                },
                {
                    "id"          : 1157,
                    "Date"        : "/Date(1320249354000)/",
                    "Asset Usage" : {
                        "id"            : 0,
                        "displaystring" : "Preview"
                    },
                    "Host Item ID"           : 136,
                    "User"                   : "U:{98ca1422-0171-4d1d-8b84-8cdda4ab70ae}:cumulus",
                    "Additional Information" : null

                }
            ],
            "totalcount" : 2
        }

2.2.5. metadata/setfilterquery

Set a query string or named query as a user live filter at the CIP session (see session handling above).
This query is always used when searching inside a catalog to limit the result to items also matching this query.
This way clients can be limited to see only a subset of assets.

Allowed HTTP method: POST

Available since: 8.5.2

Named Parameters

Parameter Type Description

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

table string (optional) You may want to specify the table to which the filter should be assigned. The default is "AssetRecords".

queryname string (optional) The name of a query defined in the CIP configuration file. The defined query is either one that is preset in the DAM system or is configured using a query string with placeholders. See the configuration file section for details on how to define queries.

querystring string (optional) The complete query string as expected by the DAM system. You need to make sure all special characters are correctly escaped if you want to pass this parameter in an HTTP request URL. It is recommended to pass the parameter in the body of the request instead.

Result

The result does not have any contents.

Examples

a) Set a named query called "approved" as a user live filter at the CIP session:

Example Request

http://cip-server:port/CIP/metadata/setfilterquery?queryname=approved

Example Response

The result does not have any contents.

2.2.6. metadata/clearfilterquery

Clear stored user live filter from the CIP session.
You can use this operation to remove user live filter from the CIP session.

Allowed HTTP method: POST

Available since: 8.5.2

Named Parameters

Parameter Type Description

table string (optional) The name of table for which the stored filter should be removed. The default is "AssetRecords".

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

Result

The result does not have any contents.

Examples

a) Clear stored filter query from the CIP session

Example Request

http://cip-server:port/CIP/metadata/clearfilterquery

Example Response

The result does not have any contents.

2.2.7. metadata/getfieldvalues

Retrieve the metadata fields or IDs of items in a stored collection. You can specify an offset to start at and a maximum number of items returned.

You specify the items either by setting the named parameter collection or by specifying the catalog and item ID using path parameters 1 and 2 respectively.

Allowed HTTP methods: GET and POST

Available since: 8.5.2

Path Parameters

Collection-based:

Parameter	Type	Description
`view`	string (optional)	The name of a view definition from the configuration file which defines a list of fields to use. See the configuration section on details on how to define views. The field list can be extended with additional fields specified in named request parameters. If no view or fields are specified then the resulting list of items is just an array of item IDs.

Catalog-based:

`catalog`	string (required)	The catalog alias for the catalog to work with.
`view`	string (optional)	The name of a view definition from the configuration file which defines a list of fields to use. See the configuration section on details on how to define views. The field list can be extended with additional fields specified in named request parameters. If no view or fields are specified then the resulting list of items is just an array of item IDs.
`id`	long (required)	The ID of the item in the catalog to return field values for.

Named Parameters

Collection-based:

Parameter	Type	Description
`collection`	string (required)	The name of an existing collection in the current session.
`startindex`	integer (optional)	The index (zero-based) to start returning the items. Using this parameter you can page through the result list by starting with 0 and then incrementing by a given number. The default is 0 which returns the items starting with the first one.
`maxreturned`	integer (optional)	The maximum number of items returned by this operation. You may use this parameter to limit the size of the resulting JSON data. When used together with the `startindex` parameter you can implement paging through the result list. The default is to return all items starting at the one specified by the startindex parameter. Due to changes being encountered in the catalog this operation may return less than the specified number of items if items in the given range have been deleted from the catalog. However, to do proper paging you should start the next getfieldvalues operation at the index you calculate from the given parameters startindex and maxreturned.

Catalog-based:

table string (optional) The name of the table to return field values for. The default is "AssetRecords".

locale string (optional) The two-letter language code (ISO 639-1) to be used for the metadata field values for the result. This parameter affects the way language-dependent metadata values are returned. For example you can specify “fr” to return all values suitable for French users. The default is the default locale the CIP server is running in (may be controlled using the “user.language” Java VM parameter when starting the web application server).

field

string array (optional)

`{50f54d0a-0ebe-46ce-bf3c-dbb744349650}`	UID of a virtual field that contains the number of records being assigned to a category
`{b46eddc9-dc90-4e31-9474-bee1b9a3fd12}`	UID of a virtual field that contains the number of records being assigned to a category including its sub-categories
`{e85fd04a-7e4f-4718-9879-92c0f22ba892}`	UID of a virtual field that contains list of names of fields that the current user is allowed to modify

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result is returned in JSON format and consists of the total number of items returned and an optional list of items with IDs or field values defined in the given view. If no view is specified then the list of items is just an array of item IDs.

Examples

a) Return the first 500 items of the collection "mycoll" with field values taken from view "myfields":

Example Request

http://cip-server:port/CIP/metadata/getfieldvalues/myfields?collection=mycoll&maxreturned=500

Example Configuration

    <view name="myfields">
        <field>Status</field>
        <field>Record Name</field>
        <field>Rating</field>
        <field>ModifiableFields:{e85fd04a-7e4f-4718-9879-92c0f22ba892}</field>
    </view>

Example Response

    {
        "items": [
            {
                "id"     : 100,
                "name"   : "IMG_3145.tif",
                "Status" : {
                    "displaystring" : "in progress",
                    "id"            : 0
                },
                "Record Name" : "IMG_3145.tif",
                "Rating"      : 3,
                "ModifiableFields": [
                    "Status",
                    "Record Name",
                    "Rating"
                ]
            },
            {
                "id"     : 103,
                "name"   : "IMG_6345.tif",
                "Status" : {
                    "displaystring" : "approved",
                    "id"            : 1
                },
                "Record Name" : "IMG_6345.tif",
                "Rating"      : 5,
                "ModifiableFields": [
                    "Status",
                    "Record Name",
                    "Rating"
                ]
            }
            ...

        ],
        "totalcount" : 173493
    }

b) Return all IDs of all items of the collection "mycoll":

Example Request

http://cip-server:port/CIP/metadata/getfieldvalues?collection=mycoll

Example Response

    {
        "items" : [ 1745, 1867 ],
        "totalcount" : 2
    }

c) Return field values taken from view "default" for the item of ID 254:

Example Request

http://cip-server:port/CIP/metadata/getfieldvalues/sample/default/254?locale=en

Example Configuration

        <view name="default">
            <field>Record Name</field>
            <field>Record Modification Date</field>
            <field>Status</field>
            <field>MultiStringList</field>
            <field>Status Label</field>
            <field>Rating</field>
            <field>Categories</field>
            <field>Asset Reference</field>
            <field>Asset Reference/Windows</field>
            <field>Asset Reference/ZIP</field>
        </view>

Example Response

    {
        "id" : 254,
        "Status" : {
            "displaystring" : "needs approval",
            "id"            : 1
        },
        "Rating"                   : null,
        "Record Name"              : "IMG065326.jpg",
        "Asset Reference" : [
            {
                "module"        : "{a5298d50-4643-11d2-8f00-0000c0e166dc}",
                "level"         : 0,
                "name"          : "Windows",
                "displaystring" : "C:\pictures\24278374_12fc4ef979b__8000\holiday.zip",
            },
            {
                "module"        : "{3baa1935-c9c6-11d4-83e8-0080ad78309d}",
                "level"         : 1,
                "name"          : "ZIP",
                "displaystring" : "berlin/IMG065326.jpg"
            }
        ],
        "Asset Reference/Windows"  : "C:\pictures\24278374_12fc4ef979b__8000\holiday.zip",
        "Asset Reference/ZIP"      : "berlin/IMG065326.jpg",
        "Categories" : [
            {
                "id"   : 124,
                "name" : "berlin",
                "path" : "$Categories:ZIP:holiday.zip:berlin"
            }
        ],
        "Record Modification Date" : {
            "datetime"     : "/Date(1304679134000)/",
            "milliseconds" : 1304679134000
        }
    }

d) Return field values taken from view “myusagefields” for the item of ID 1157 of the table “AssetRecords/{a89b908c-e98e-413b-ac4d-50668b2fafbc}”:

Example Request

http://cip-server:port/CIP/metadata/getfieldvalues/sample/myusagefields/1157?table=AssetRecords/{a89b908c-e98e-413b-ac4d-50668b2fafbc}

Example Configuration

    <view name="myusagefields">
        <field>Asset Usage</field>
        <field>Date</field>
        <field>Host Item ID</field>
        <field>User</field>
        <field>Additional Information</field>
    </view>

Example Response

    {
        "id"          : 1157,
        "Asset Usage" : {
            "id"            : 0,
            "displaystring" : "Preview"
        },
        "Date"                   : "/Date(1320249354000)/",
        "Host Item ID"           : 136,
        "User"                   : "U:{98ca1422-0171-4d1d-8b84-8cdda4ab70ae}:cumulus",
        "Additional Information" : null
    }

2.2.8. metadata/setfieldvalues

Set the metadata fields of catalog items.

The field values are specified using a JSON structure transferred in the request body of a HTTP POST request.

The JSON data always contains the ID of the item to be modified.

Allowed HTTP method: POST

Available since: 8.5.2

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The catalog alias for the catalog for the item to be modified.
`view`	string (optional)	The name of a view definition from the configuration file which defines a list of fields to use. See the configuration section on details on how to define views. The field list can be extended with additional fields specified in named request parameters.

Named Parameters

Parameter Type Description

table string (optional) The name of a table for the items to be modified. The default is "AssetRecords".

locale string (optional) The two-letter language code (ISO 639-1) to be used for the metadata field values. This parameter affects the way language-dependent metadata values are parsed. For example you can specify “fr” to specify all values suitable for French users. The default is the default locale the CIP server is running in (may be controlled using the “user.language” Java VM parameter when starting the web application server).

field string array (optional) You can select the fields that should be set by specifying one or more of these named parameters.
The value for this parameter has the same format as the field specification in the view configuration.
For the Cumulus DAM system it is sometimes preferable to specify the field using the field UID and optionally the field name and an alias name.
When also specifying a configured view as a path parameter you can extend the view fields with the ones specified in the request.

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result does not have any contents.

Examples

a) Set the "Status" and "Rating" field values of two asset records of ID 1537 and 638 to some values. In this example the "Rating" field for item 638 is cleared:

Example Request

http://cip-server:port/CIP/metadata/setfieldvalues/mycatalog

Example Request Body

    {
        "items" : [
            {
                "id"     : 1537,
                "Status" : 2,
                "Rating" : 3
            },
            {
                "id"     : 638,
                "Status" : 1,
                "Rating" : null
            }
    ...
        ]
    }

b) Set the "Record Modification Date" field value of the asset of ID 1537:

Example Request

http://cip-server:port/CIP/metadata/setfieldvalues/mycatalog

Example Request Body

    {
        "items" : [
            {
                "id"     : 1537,
                Record Modification Date": "/Date(1347882642000)/"
            }
        ]
    }

c) Set the date only field "Test Date Only" in different ways:

Item 129 via display string
Item 130 via day, month and year
Item 131 via month and year
Item 132 via year
Item 133 simple form via display string

Example Request

http://cip-server:port/CIP/metadata/setfieldvalues/mycatalog?field=Test%20Date%20Only

Example Request Body

    {
        "items" : [
            {
                "id" : 129,
                "Test Date Only" : {
                    "displaystring" : "23.07.2012",
                }
            },
            {
                "id" : 130,
                "Test Date Only" : {
                    "day"   : 23,
                    "month" : 7,
                    "year"  : 2012
                }
            },
            {
                "id" : 131,
                "Test Date Only" : {
                    "month" : 7,
                    "year"  : 2012
                }
            },
            {
                "id" : 132,
                "Test Date Only" : {
                    "year"  : 2012
                }
            },
            {
                "id" : 133,
                "Test Date Only" : "23.07.2012"
            }
        ]
    }

d) Set the time only field "Test Time Only" in different ways:

Item 129 via milliseconds value
Item 130 via display string
Item 131 short form via milliseconds value
Item 132 short form via display string

Example Request

http://cip-server:port/CIP/metadata/setfieldvalues/mycatalog?field=Test%20Date%20Only

Example Request Body

    {
        "items" : [
            {
                "id" : 129,
                "Test Time Only": {
                    "milliseconds": 40953000,
                }
            },
            {
                "id" : 130,
                "Test Time Only": {
                    "displaystring": "11:22:33"
                }
            },
            {
                "id" : 131,
                "Test Time Only": 40953000
            },
            {
                "id" : 132,
                "Test Time Only": "11:22:33"
            }
        ]
    }

e) Set the data size field "Asset Data Size (Long)" in different ways:

Item 130 via value
Item 132 simple form via value

Example Request

http://cip-server:port/CIP/metadata/setfieldvalues/mycatalog?field=Asset%20Data%20Size%20(Long)

Example Request Body

    {
        "items" : [
            {
                "id" : 130,
                "Asset Data Size (Long)": {
                    "value": 604609,
                }
            },
            {
                "id" : 132,
                "Asset Data Size (Long)": 604609
            }
        ]
    }

f) Set the multi enum field "Multi Enum Test" in different ways:

Item 129 via id
Item 130 via displaystring
Item 131 simple form via id

Example Request

http://cip-server:port/CIP/metadata/setfieldvalues/mycatalog?field=Multi%20Enum%20Field

Example Request Body

                        {
                            "items" : [
                                {
                                    "id" : 129,
                                    "Multi Enum Test": [
                                        {
                                             "id": 0,
                                             "displaystring": "Value0"
                                        },
                                        {
                                             "id": 1,
                                             "displaystring": "Value1"
                                        }
                                    ]
                                },
                                {
                                    "id" : 130,
                                    "Multi Enum Test": [
                                        {
                                             "displaystring": "Value3"
                                        },
                                        {
                                             "displaystring": "Value2"
                                        }
                                    ]
                                },
                                {
                                    "id" : 131,
                                    "Multi Enum Test": [
                                        {
                                             "id": 0
                                        },
                                        {
                                             "id": 2
                                        },
                                        {
                                             "id": 3
                                        }
                                    ]
                                }
                            ]
                        }

2.2.9. metadata/createitem

Create a new catalog item and optionally set the metadata fields for it.

The field values are specified using a JSON structure transferred in the request body of a HTTP POST request.

Allowed HTTP method: POST

Available since: 8.5.2

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The catalog alias for the catalog for the item to be modified.
`view`	string (optional)	The name of a view definition from the configuration file which defines a list of fields to use. See the configuration section on details on how to define views. The field list can be extended with additional fields specified in named request parameters.

Named Parameters

Parameter Type Description

table string (optional) The name of a table for the items to be modified. The default is "AssetRecords".

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result is returned in JSON format and consists of the ID of the created catalog item.

Examples

a) Create a new metadata catalog item and set the "Status" and "Rating" field values:

Example Request

http://cip-server:port/CIP/metadata/createitem/mycatalog

Example Request Body

    {
        "Status" : 2,
        "Rating" : 3
    }

Example Response

    {
        "id" : 25112
    }

2.2.10. metadata/getcategories

Get the sub-categories for a given parent category. You can either get the direct sub-categories of the parent only or the whole sub-tree.

Three options allow specifying the parent category:

Specify the category by the complete path (use parameter path).
Specify the category by its ID (use parameter categoryid).
If neither the path nor categoryid parameter is specified the operation will return the top-level categories.

The result can be returned as a JSON structure containing metadata field values for the categories or the IDs of teh categories can be stored in a named collection of the session.
When storing the result in a named collection the hierarchical structure of a possible sub-tree will be lost and all IDs will be stored in a flat list.

Allowed HTTP methods: GET and POST

Available since: 8.5.2

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.
`view`	string (optional)	The name of a view definition from the configuration file which defines a list of fields to use. See the configuration section on details on how to define views. The field list can be extended with additional fields specified in named request parameters. If no view or fields are specified then the resulting list of items is just an array of item IDs.

Named Parameters

Parameter Type Description

path string (optional) The complete path of the parent category in the tree starting at the top-level category name. The category names for each level are separated by colon. Use double-colon to escape a colon appearing in a category name.

categoryid long (optional) The ID of the parent category.

levels

string (optional)

This parameter specifies whether you want the result to contain not just the direct sub-categories of the given parent but the whole sub-tree including all categories down to the given level.

Possible values are:

`1`	(Default) Return the direct sub-categories of the given parent category only.
`0`	Return the requested category id only.
`n`	(Where “n” is a positive number) Return all the categories underneath the parent category down to the “n” level. They are returned in “depth-first”. The result nests sub-categories inside their parent category item so that the tree structure can be reconstructed. If you specify a collection to store the result the collection will contain the category IDs as a flat list.
`all`	Return all the categories underneath the parent category down to the bottom level. They are returned in “depth-first”. The result nests sub-categories inside their parent category item so that the tree structure can be reconstructed. If you specify a collection to store the result the collection will contain the category IDs as a flat list.

collection string (required) The name of a collection to save the resulting list of IDs. If you leave the value empty then CIP will create a unique collection name for you and will return this name in the result. This can be used for temporary collection to make sure the name is unique in the session.

field string array (optional) You can select the fields that should be returned by specifying one or more of these named parameters.
The value for this parameter has the same format as the field specification in the view configuration.
For the Cumulus DAM system it is sometimes preferable to specify the field using the field UID and optionally the field name and an alias name.
When also specifying a configured view as a path parameter you can extend the view fields with the ones specified in the request.
By configuring an empty view you can let CIP return only the fields that are specified in the request.
Since 8.6.1: the number of assets that are assigned to a category directly can be obtained by specifying a virtual field with the name "{50f54d0a-0ebe-46ce-bf3c-dbb744349650}".
Since 8.6.1: the number of assets that are assigned to a category or any of its sub-categories can be obtained by specifying a virtual field with the name "{b46eddc9-dc90-4e31-9474-bee1b9a3fd12}".
You can add an alias name for it to make it better readable in the result.

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result is returned in JSON format and consists of the total number of category items returned and a list of items with the field values defined in the given view.
The sub-categories are returned as a list with the name subcategories. Empty sub-category arrays are suppressed in the output.

If no view and no collection are specified then the format of the result depends on the value of the parameter levels.
If only direct sub-categories are returned then the result is just an array of category IDs.
If you wanted to get a whole sub-tree then the result is the same as if you would have specified the field “ID” as the only field of the view.
If no view but a collection is specified the result just returns the total count and the name of the collection.

The item field values or IDs can then be retrieved using the getfieldvalues operation.

Examples

a) Get all top-level categories and return the field values defined in the view "categories" for all items found:

Example Request

http://cip-server:port/CIP/metadata/getcategories/mycatalog/categories

Example Configuration

        <view name="categories">
            <field>Category Name</field>
            <field>ID</field>
        </view>

Example Response

        {
            "id"               : 0,
            "hassubcategories" : true,
            "subcategories"    : [
                {
                    "Category Name"    : "America",
                    "hassubcategories" : false,
                    "id"               : 4
                },
                {
                    "Category Name"    : "Asia",
                    "hassubcategories" : true,
                    "id"               : 5
                },
                {
                    "Category Name"    : "Europe",
                    "hassubcategories" : true,
                    "id"               : 3
                }
            ],
            "totalcount" : 3
        }

b) Just return the IDs of the top-level categories.

Example Request

http://cip-server:port/CIP/metadata/getcategories/mycatalog

Example Response

    {
        "id": 0,
        "hassubcategories" : true,
        "subcategories"    : [
            {
                "id"               : 4,
                "hassubcategories" : false
            },
            {
                "id"               : 5,
                "hassubcategories" : true
            },
            {
                "id"               : 3,
                "hassubcategories" : true
            }
        ]
    }

c) Store the result in a collection named “topcats” instead of returning any items in the result:

Example Request

http://cip-server:port/CIP/metadata/getcategories/mycatalog?collection=topcats

Example Response

    {
        "collection" : "topcats",
        "totalcount" : 3
    }

d) Return the sub-categories of a specific category (“Europe” above) as a tree:

Example Request

http://cip-server:port/CIP/metadata/getcategories/mycatalog/categories?categoryid=3&levels=all

Example Configuration

        <view name="categories">
            <field>Category Name</field>
            <field>ID</field>
        </view>

Example Response

    {
        "id"               : 3,
        "hassubcategories" : true,
        "subcategories"    : [
            {
                "Category Name"    : "Belgium",
                "hassubcategories" : false,
                "id"               : 31
            },
            {
                "Category Name"    : "France",
                "hassubcategories" : true,
                "id"               : 37,
                "subcategories"    : [
                    {
                        "Category Name"    : "Lyon",
                        "hassubcategories" : false,
                        "id"               : 371
                    },
                    {
                        "Category Name"    : "Paris",
                        "hassubcategories" : false,
                        "id"               : 576
                    }
                ]
            },
            {
                "Category Name"    : "Italy",
                "hassubcategories" : true,
                "id"               : 32,
                "subcategories"    : [
                    {
                        "Category Name"    : "Rome",
                        "hassubcategories" : false,
                        "id"               : 532
                    },
                    {
                        "Category Name"    : "Venice",
                        "hassubcategories" : false,
                        "id"               : 936
                    }
                ]
            }
        ],
        "totalcount" : 7
    }

e) Return the sub-category IDs for a specific root category (“Europe” above) as a tree:

Example Request

http://cip-server:port/CIP/metadata/getcategories/mycatalog?categoryid=3&levels=3

Example Response

    {
        "id"               : 3,
        "hassubcategories" : true,
        "subcategories"    : [
            {
                "id"               : 31,
                "hassubcategories" : false
            },
            {
                "id"               : 37,
                "hassubcategories" : true,
                "subcategories"    : [
                    {
                        "id"               : 371,
                        "hassubcategories" : false
                    },
                    {
                        "id"               : 576,
                        "hassubcategories" : false
                    }
                ]
            },
            {
                "id"               : 32,
                "hassubcategories" : true,
                "subcategories"    : [
                    {
                        "id"               : 532,
                        "hassubcategories" : true
                    },
                    {
                        "id"               : 936,
                        "hassubcategories" : true
                    }
                ]
            }
        ],
        "totalcount" : 7
    }

f) Return the sub-categories of a specific category (“France” above):

Example Request

http://cip-server:port/CIP/metadata/getcategories/mycatalog/myfields?path=Europe:France

Example Configuration

        <view name="myfields">
            <field>Category Name</field>
            <field>ID</field>
        </view>

Example Response

    {
        "id"               : 37,
        "hassubcategories" : true,
        "subcategories"    : [
            {
                "Category Name"    : "Lyon",
                "hassubcategories" : false,
                "id"               : 371
            },
            {
                "Category Name"    : "Paris",
                "hassubcategories" : false,
                "id"               : 576
            }
        ],
        "totalcount" : 2
    }

2.2.11. metadata/createcategory

Create a new category as a sub-category of a given other category.

Three options allow specifying the parent category:

Specify the parent category by the complete path (use parameter path).
Specify the parent category by its ID (use parameter categoryid).
If neither the path nor categoryid parameter is specified the operation will create a top-level category.

Allowed HTTP method: POST

Available since: 8.5.2

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.

Named Parameters

Parameter Type Description

name string (required) The name for the newly created category

categoryid long (optional) The ID of the parent category.

ifcategoryexists

string (optional)

Specify what to do when the newly created category refers to an existing one.

Available since: 8.6

Possible values are:

`createwithsamename`	(Default) Create another category with the requested name.
`returnexistingone`	Return category ID of the existing one.
`error`	Do nothing and return an error instead.

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result is returned in JSON format and consists of the ID of the newly created category.

Examples

a) Create a new top-level category named “Countries”:

Example Request

http://cip-server:port/CIP/metadata/createcategory/mycatalog?name=Countries

Example Response

        {
            "id" : 534
        }

b) Create a new category underneath "Countries" named "Sweden":

Example Request

http://cip-server:port/CIP/metadata/createcategory/mycatalog?path=Countries&name=Sweden

Example Response

        {
            "id" : 535
        }

c) Create a new category underneath “Sweden” called “Stockholm”:

Example Request

http://cip-server:port/CIP/metadata/createcategory/mycatalog?path=Countries:Sweden&name=Stockholm

Example Response

        {
            "id": 536
        }

2.2.12. metadata/assigntocategories

Assign categories to given catalog item.

Allowed HTTP method: POST

Available since: 8.5.2

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The catalog alias for the catalog for the item to be modified.
`id`	long (required)	The ID of the item in the catalog to be assigned to given categories.

Named Parameters

Parameter Type Description

path string array (optional) The complete path of the categories in the tree starting at the top-level category name to assign an item to. The category names for each level are separated by colon. Use double-colon to escape a colon appearing in a category name.

categoryid long array (optional) The IDs of the categories to assign an item to.

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result does not have any contents.

Examples

a) Assign categories "PDF" and "CDC/Custom" to the asset of ID 1537

Example Request

http://cip-server:port/CIP/metadata/assigntocategories/mycatalog/1537?path=$Categories:PDF&path=$Categories:CDC:Custom

2.2.13. metadata/detachfromcategories

Detach categories from given catalog item.

Allowed HTTP method: POST

Available since: 8.5.2

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The catalog alias for the catalog for the item to be modified.
`id`	long (required)	The ID of the item in the catalog to be detached from given categories.

Named Parameters

Parameter Type Description

path string array (optional) The complete path of the categories in the tree starting at the top-level category name to detach an item from. The category names for each level are separated by colon. Use double-colon to escape a colon appearing in a category name.

categoryid long array (optional) The IDs of the categories to detach an item from.

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result does not have any contents.

Examples

a) Detach categories of ID 12 and 20 from the asset of ID 1537

Example Request

http://cip-server:port/CIP/metadata/detachfromcategories/mycatalog/1537?categoryid=12&categoryid=20

2.2.14. metadata/deletecategory

Delete a given category and all of its sub-categories.

Two options allow specifying the category to be deleted:

Specify the category by the complete path (use parameterpath).
Specify the category by its ID (use parametercategoryid).

Allowed HTTP method: POST

Available since: 8.5.2

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.

Named Parameters

Parameter Type Description

path string (optional) The complete path of the category in the tree starting at the top-level category name. The category names for each level are separated by colon. Use double-colon to escape a colon appearing in a category name.

categoryid long (optional) The ID of the category to delete.

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result does not have any contents.

Examples

a) Delete the category with the ID 536:

Example Request

http://cip-server:port/CIP/metadata/deletecategory/mycatalog?categoryid=536

b) Delete the category "Sweden" underneath "Countries":

Example Request

http://cip-server:port/CIP/metadata/createcategory/mycatalog?path=Countries:Sweden

2.2.15. metadata/getrelatedassets

Return IDs list of all related assets.

Allowed HTTP methods: GET and POST

Available since: 8.5.2

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.
`id`	long (required)	The ID of the item in the catalog.
`relation`	string (required)	The relation type. Possible values: contains iscontainedin references isreferencedby isvariantmasterof isvariantof isalternatemaster isalternateof

Named Parameters

Parameter Type Description

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result is a list of IDs

Examples

a) Get the IDs of all related assets for item with the ID 137 of the catalog with the alias “mycatalog” and relation named “isvariantmasterof”:

Example Request

http://cip-server:port/CIP/metadata/getrelatedassets/mycatalog/137/isvariantmasterof

Example Response

{
    "ids" : [
        131,
        132
    ]
}

2.2.16. metadata/linkrelatedasset

Add a new relation to the given other record.

Allowed HTTP method: POST

Available since: 8.5.2

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.
`id`	long (required)	The ID of the item in the catalog.
`relation`	string (required)	The relation type. Possible values: contains iscontainedin references isreferencedby isvariantmasterof isvariantof isalternatemaster isalternateof
`otherId`	long (required)	The ID of the other item in the catalog.

Named Parameters

Parameter Type Description

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result does not have any contents.

Examples

a) Link asset of ID 137 to the asset of ID 133 with the relation named “isalternateof”:

Example Request

http://cip-server:port/CIP/metadata/assigntocategories/mycatalog/mycatalog/137/isalternateof/133

2.2.17. metadata/unlinkrelatedasset

Remove the relation to the given other record.

Allowed HTTP method: POST

Available since: 8.5.2

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.
`id`	long (required)	The ID of the item in the catalog.
`relation`	string (required)	The relation type. Possible values: contains iscontainedin references isreferencedby isvariantmasterof isvariantof isalternatemaster isalternateof
`otherId`	long (required)	The ID of the other item in the catalog.

Named Parameters

Parameter Type Description

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result does not have any contents.

Examples

a) Unlink asset of ID 133 to the asset of ID 137 with the relation named “isalternatemaster”:

Example Request

http://cip-server:port/CIP/metadata/assigntocategories/mycatalog/mycatalog/133/isalternatemaster/137

2.2.18. metadata/getfieldstatistics

Retrieve the number of records having a specific date value for each day.

Allowed HTTP methods: GET and POST

Available since: 8.6

Path Parameters

Collection-based:

Parameter	Type	Description
	-	There's no path parameters for the collection based operation.

Catalog-based:

catalog string (required) The catalog alias for the catalog to work with.

Named Parameters

Collection-based:

Parameter	Type	Description
`collection`	string (required)	The name of an existing collection in the current session.

Catalog-based:

table string (optional) The name of the table to return field values for. The default is "AssetRecords".

startdatetime long (required) The starting date and time in UTC as the number of milliseconds since January 1, 1970, 00:00:00 UTC.

numberofdays integer (required) The number of days starting at startdatetime.

field string array (required) You must select at least one field that should be returned by specifying one or more of these named parameters.
The value for this parameter has the same format as the field specification in the view configuration.
For the Cumulus DAM system it is sometimes preferable to specify the field using the field UID and optionally the field name and an alias name.
When also specifying a configured view as a path parameter you can extend the view fields with the ones specified in the request.
By configuring an empty view you can let CIP return only the fields that are specified in the request.

apiversion

integer (optional)

Available since: 8.6

Supported values:

`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The operation returns a list of integer values, one for each day.
The integer specifies the number of records have a field value within the given day.
The total number of integer values is the same as the "numberofdays" parameter value.

Examples

a) Return statistics for the fields Asset Modification Date and Asset Creation Date starting from 2009-05-06 14:03:09 UTC for 10 days.

Example Request

http://cip-server:port/CIP/metadata/getfieldstatistics/sample?numberofdays=10&startdatetime=1241618589000&field=Asset Modification Date&field=Asset Creation Date

Example Response

{

    "Asset Modification Date": [
        0,
        1,
        0,
        0,
        3,
        0,
        0,
        0,
        0,
        0
    ],
    "Asset Creation Date": [
        0,
        0,
        1,
        0,
        0,
        0,
        0,
        0,
        0,
        0
    ]

}

2.2.19. metadata/sendcollectionlink

Send collection link per e-mail

The ID of the items are specified using a JSON structure transferred in the request body of a HTTP POST request.

Allowed HTTP method: POST

Available since: 8.5.2

Path Parameters

Collection-based:

Parameter	Type	Description
	-	There's no path parameters for the collection based operation.

Catalog-based:

catalog string (required) The catalog alias for the catalog to work with.

Named Parameters

Collection-based:

Parameter	Type	Description
`collection`	string (required)	The name of an existing collection in the current session.
`startindex`	integer (optional)	The index (zero-based) to start including the items. Using this parameter you can page through the result list by starting with 0 and then incrementing by a given number. The default is 0 which returns the items starting with the first one.
`maxreturned`	integer (optional)	The maximum number of items included by this operation. You may use this parameter to limit the size of the resulting collection. When used together with the `startindex` parameter you can implement paging through the result list. The default is to return all items starting at the one specified by the startindex parameter. Due to changes being encountered in the catalog this operation may return less than the specified number of items if items in the given range have been deleted from the catalog. However, to do proper paging you should start the next getfieldvalues operation at the index you calculate from the given parameters startindex and maxreturned.

Catalog-based:

table string (optional) The name of the table to return field values for. The default is "AssetRecords".

linkcollection string (required) The name used to store a newly created link collection.

embargodate date (optional) The link embargo date. Date format is YYYYMMDD (ISO 8601) e.g. 20110520 (20 May 2011)

expirationdate date (required) The link expiration date. Date format is YYYYMMDD (ISO 8601) e.g. 20110520 (20 May 2011)

linkpassword string (optional) The collection link password.

linkbaseurl string (required) The base URL of the collection link server.

permit

string array (optional)

Specifies the link collection permissions.

Possible values are:

`download`	Recipients can download assets with the provided asset actions. See also options named parameter.
`preview`	Recipients can preview assets.
`openinfowindow`	Recipients can see info window with the metadata.
`print`	Recipients can print assets.

options string (optional) The name of an options set defined in the configuration file. The exact options are DAM system dependent.

`mailfrom`	string (optional)	The sender e-mail address.
`mailrecipients`	string array (required)	The list of e-mail recipients. Required to send an e-mail.
`mailcc`	string array (optional)	The list of e-mail Cc (carbon copy) recipients.
`mailbcc`	string array (optional)	The list of e-mail Bcc (blind carbon copy) recipients.
`mailsubject`	string (optional)	The subject line of the e-mail message.
`mailbody`	string (optional)	The body text of the e-mail message.

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result does not have any contents.

Examples

a) Send the first 500 items of the collection "mycoll" extendend by the items of ID 137, 138, 139 :

Example Request

http://cip-server:port/CIP/metadata/sendcollectionlink?collection=mycoll&maxreturned=500&permit=download&permit=openinfowindow&permit=print&mailrecipients=user1@host&mailrecipients=user1@host&linkcollection=mylinkcollection&options=myoptions

Example Request Body

b) Send the items of ID 501, 550, 1000 :

Example Request

http://cip-server:port/CIP/metadata/sendcollectionlink/sample?permit=download&permit=openinfowindow&permit=print&mailrecipients=user1@host&mailrecipients=user2@host&linkcollection=mylinkcollection&options=myoptions

Example Request Body

2.3. Preview Service

2.3.1. preview/image

Return a pixel preview for an asset.

An optional location allows you to store the result in the local file system of the CIP server or on an FTP server instead of downloading the result to the client.

Several options allow specifying the parameters for generating the preview image. The options are applied in the following order:

Cropping (use optional parameters left, top, width, height).
Scale down the image (use optional parameter maxsize or size).
Rotate the image in 90 degree steps (use optional the parameter rotate).
Output file format (use optional parameter format and quality).

To improve the performance of delivering preview images the CIP server caches the generated preview images.
The cache location is configured using the predefined name com.canto.cip.location.previewcache. If the image of the original asset cannot be delivered (e.g. the asset is not accessible) then this operation returns the thumbnail image instead. If even then thumbnail cannot be determined you can specify whether it should return a fallback image or an error instead.

Allowed HTTP methods: GET and POST

Available since: 8.5.2

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.
`id`	long (required)	The ID of the asset in the catalog specified by the first path parameter.
`previewname`	string (optional)	The name of a preview configured in the CIP server. By using named previews you can keep the actual preview parameters separate from the CIP client code. Every parameter that you specify explicitly in the URL replaces a corresponding value from the configured preview.

Named Parameters

Cropping

Parameter	Type	Description
`left`	integer (optional)	Specify the number of pixels to crop off the left side in original image space. The default is 0.
`top`	integer (optional)	Specify the number of pixels to crop off the top side in original image space. The default is 0.
`width`	integer (optional)	Specify the width of the cropping area in original image space. The default is the width of the original image.
`height`	integer (optional)	Specify the height of the cropping area in original image space. The default is the height of the original image.

Scaling

`maxsize`	integer (optional)	Scale the image down so that the longest side fits into the given number of pixels preserving the aspect ratio of the image.

`size`	integer (optional)	Scale down the image so that the shortest side fits into the square whose size is given in pixels. This option centers the image inside the square and crops away parts of the longer dimension. The resulting image is always square.

Rotating

rotate integer (optional) Rotate the image clockwise by the given degrees. Possible values are 0, 90, 180, and 270. Default is 0.

Output Format

`format`	string (optional)	The output file format to be used. Possible values are "jpeg" and "png" with the default being "jpeg"
`quality`	integer (optional)	When using a file format that supports a lossy compression method (e.g. "jpeg") you can specify the quality level that you want to be preserved. The value ranges from "1" (least quality, smallest resulting data size) to "10" (best quality, largest resulting data size).

Location

location string (optional) The location path of a folder to store the result. The path is either a complete URL that starts with a URL protocol like “ftp”, “sftp”, “ftps”, “file” or is based on a location defined in the configuration file.
When using a complete URL the protocol (e.g. "file") needs to be activated in the configuration file.
By using a configured location and a relative path you can hide details such as FTP passwords from the user of the service.
When executed the location name is replaced with the configured location string.

name string (optional) The name of the file to store the result as. This parameter is only used when a "location" is specified.

ifexists

string (optional)

Specify what to do when the result refers to an existing file or directory in the location.

Available since: 8.6

Possible values are:

`newuniquename`	(Default) Generate a unique name for the result.
`replace`	Replace the existing file or directory with the result.
`error`	Do nothing and return an error instead.

Cache Control

usecache

string (optional)

Specifies how to use the preview cache.

Possible values are:

`true`	(Default) - Return a cached preview if it exists and matches the asset modification date. Otherwise return a newly generated preview and store it in the cache.
`only`	Only generate the preview to store it in cache. No preview is returned to the caller.
`false`	Do not use the cache at all, return a newly generated preview.

cachecontrol

string (optional)

Allow to control client cache policy switch for CIP operation results. This could lead to better performance in case the browser can use cached images.

Available since: 8.6

Possible values are:

`no-cache`	(Default) - Switch off caching of images in the browser
`clientdefault`	Allow caching of images. The cache lifetime depend on constraint `com.canto.cip.constraint.clientcachemaxage` configuration. The default value is 3600 seconds (1 hour). See configuration section for details.

Fallback Image

fallbackimageonerror

string (optional)

Specifies whether the fallback image should be returned instead of the error message.

Possible values are:

`true`	Return a fallback image instead of error message. The error is logged in the server log only
`false`	(Default) - Do not use the fallback image, return the error message if any problem occurs.

version

version integer (optional) The number of the asset version to generate a preview for. A value of 0 represents the latest version.
You can retrieve the list of available versions for an asset using the asset/getversions operation.
Default is 0 (latest version).

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

Unless you specify "usecache=only" the response body contains:

If you specified a location to store the resulting asset then the response body contains JSON data specifying the exact location.
If you did not specify a location then the response body contains the image data you requested.

Examples

a) Get the preview of the asset ID 536:

Example Request

http://cip-server:port/CIP/preview/image/mycatalog/536

Example Response

 The binary image data (PNG or JPEG). This can directly be shown in a web browser.

b) Store the preview of the asset ID 536 inside a folder called "images" of the configured location named "mylocation":

Example Request

http://cip-server:port/CIP/preview/image/mycatalog/536?location=mylocation/images

Example Configuration

    <location name="mylocation">
        file://C:/cip
    </location>

Example Response

    {
        "location": "mylocation/images/PIC00342956.jpg"
    }

2.3.2. preview/purgecache

Purge specific cached preview files from the cache. You can purge all previews generated for a specific asset as well as previews generated with a specific parameter set.

Allowed HTTP method: POST

Available since: 8.5.2

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.
`id`	long (optional)	The ID of the asset in the catalog specified by the first path parameter for which to purge all cache files. If this is not specified the operation purges all cache files for the preview parameters that are specified.

Named Parameters

This operation uses the same named parameters as the preview/image operation but it uses them only to determine the files in the cache that are to be purged. All optional parameters that are missing are replaced internally with their default values to form a complete parameter set.

Result

The result does not have any contents.

Examples

a) Purge all cached previews for asset ID 724:

Example Request

http://cip-server:port/CIP/preview/purgecache/mycatalog/724

b) Purge all cached previews generated with the parameters "size=100&format=png":

Example Request

http://cip-server:port/CIP/preview/purgecache/mycatalog?size=100&format=png

2.3.3. preview/thumbnail

Return the thumbnail image of an asset. Typically the thumbnail image is a small representation of the asset stored in the catalog itself so retrieving the thumbnail.

An optional location allows you to store the result in the local file system of the CIP server or on an FTP server instead of downloading the result to the client.

Allowed HTTP methods: GET and POST

Available since: 8.5.2

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.
`id`	long (required)	The ID of the asset in the catalog specified by the first path parameter.

Named Parameters

Scaling

Parameter	Type	Description
`maxsize`	integer (optional)	Scale the image down so that the longest side fits into the given number of pixels preserving the aspect ratio of the image.

`size`	integer (optional)	Scale down the image so that the shortest side fits into the square whose size is given in pixels. This option centers the image inside the square and crops away parts of the longer dimension. The resulting image is always square.

Rotating

rotate integer (optional) Rotate the image clockwise by the given degrees. Possible values are 0, 90, 180, and 270. Default is 0.

Output Format

`format`	string (optional)	The output file format to be used. Possible values are "jpeg" and "png" with the default being "jpeg"
`quality`	string (optional)	When using a file format that supports a lossy compression method (e.g. "jpeg") you can specify the quality level that you want to be preserved. The value ranges from "1" (least quality, smallest resulting data size) to "10" (best quality, largest resulting data size).

Location

location string (optional) The location path of a folder to store the result. The path is either a complete URL that starts with a URL protocol like “ftp”, “sftp”, “ftps”, “file” or is based on a location defined in the configuration file. By using a configured location and a relative path you can hide details such as FTP passwords from the user of the service. When executed the location name is replaced with the configured location string.

name string (optional) The name of the file to store the result as. This parameter is only used when a "location" is specified.

ifexists

string (optional)

Specify what to do when the result refers to an existing file or directory in the location.

Available since: 8.6

Possible values are:

`newuniquename`	(Default) Generate a unique name for the result.
`replace`	Replace the existing file or directory with the result.
`error`	Do nothing and return an error instead.

Cache Control

cachecontrol

string (optional)

Allow to control client cache policy switch for CIP operation results. This could lead to better performance in case the browser can use cached images.

Available since: 8.6

Possible values are:

`no-cache`	(Default) - Switch off caching of images in the browser
`clientdefault`	Allow caching of images. The cache lifetime depend on constraint `com.canto.cip.constraint.clientcachemaxage` configuration. The default value is 3600 seconds (1 hour). See configuration section for details.

Fallback Image

fallbackimageonerror

string (optional)

Specifies whether the fallback image should be returned instead of the error message.

Possible values are:

`true`	Return a fallback image instead of error message. The error is logged in the server log only
`false`	(Default) - Do not use the fallback image, return the error message if any problem occurs.

version

version integer (optional) The number of the asset version to access a thumbnail for. A value of 0 represents the latest version.
You can retrieve the list of available versions for an asset using the asset/getversions operation.
Default is 0 (latest version).

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

If you specified a location to store the thumbnail image then the response body contains JSON data specifying the exact location.

If you did not specify a location then the response body contains the image data you requested.

Examples

a) Get the thumbnail of asset ID 724:

Example Request

http://cip-server:port/CIP/preview/thumbnail/mycatalog/724

Example Response

 The asset contents (e.g. JPEG data stream).

2.4. Asset Service

The Asset service offers operations that work with the original assets: importing, downloading, checking out, checking in, deleting an asset.

2.4.1. asset/import

You can import an asset either by referencing an existing asset accessible to the CIP server or by uploading the asset along with the request. Optionally you can also set metadata field values when importing the asset.

There are three ways of specifying the asset to be imported:

Specify an existing asset using a URL (using the location parameter).
Specify an existing asset based on a configured location and a relative path (using the location parameter).
Upload the asset in the HTTP request body. This is done by putting the asset contents into the request body and using the HTTP POST method. If no metadata fields are to be set with this request the body only contains the asset contents and you specify the file name to be used in the location parameter. If you want to be able to set metadata fields along with the importing you need to post the request using the MIME type multipart/form-data.

If you also want to set metadata fields for the asset you specify the field values in JSON format in the request body and use the HTTP POST method.
If you want to both upload the asset with the request and set field values the request body needs to have a MIME type of multipart/form-data. This is compatible with the way web browsers upload files to a web server. The asset contents are then embedded in the request body as a part named "file". If you also want to set metadata field values you also include a part named "fields" which contains the JSON structure with the field values similar to the way the metadata/setfieldvalues operation accepts them.

Allowed HTTP method: POST

Available since: 8.5.2

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.
`view`	string (optional)	The name of a view definition from the configuration file which defines a list of fields to use. See the configuration section on details on how to define views. The field list can be extended with additional fields specified in named request parameters.

Named Parameters

Location

Parameter	Type	Description
`location`	string (optional)	This is either the asset name if the request body only consists of the asset contants or the location path to an existing asset. The path is either a complete URL that starts with a URL protocol like “ftp”, “sftp”, “ftps”, “file” or is based on a location defined in the configuration file. By using a configured location and a relative path you can hide details such as FTP passwords from the user of the service. When executed the location name is replaced with the configured location string.

options string (optional) The name of an options set defined in the configuration file. The exact options are DAM system dependent.

locale string (optional) The two-letter language code (ISO 639-1) to be used for the metadata field values for the result. This parameter affects the way language-dependent metadata values are returned. For example you can specify “fr” to return all values suitable for French users. The default is the default locale the CIP server is running in (may be controlled using the "user.language" Java VM parameter when starting the web application server).

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result is returned in JSON format and consists of the ID of the imported asset.

Examples

a) Import an asset by uploading it with the request and set some metadata. The request needs to use POST method with the request body being of MIME type multipart/form-data. The asset contents is embedded as a part named "file" in the request body. It's MIME type can be application/octet-stream:

Example Request

http://cip-server:port/CIP/asset/import/mycatalog

Example Request Body

    ------------8cd9fcb9f7e5fab
    Content-Disposition: form-data; name="fields"

    {
        "Status" : 0,
        "Rating" : 3,
        "Notes"  : "Some notes on the newly added asset go here"
    }
    ------------8cd9fcb9f7e5fab
    Content-Disposition: form-data; name="file"; filename="MyImage.jpg"
    Content-Type: application/octet-stream

    ... binary contents of the asset ...

    ------------8cd9fcb9f7e5fab--

Example Response

    {
        "id" : 2374
    }

b) Import an asset by uploading it with the request without any additional metadata. The request needs to use POST method with the asset contents in the request body. The MIME type of the request content can be application/octet-stream:

Example Request

http://cip-server:port/CIP/asset/import/mycatalog?location=MyImage.jpg

Example Request Body

 The binary contents of the asset.

Example Response

    {
        "id" : 2343
    }

c) Import a file named "image.jpg" directly from a preconfigured FTP server location "ftp_uploads":

Example Request

http://cip-server:port/CIP/asset/import/mycatalog?location=ftp_uploads/image.jpg

Example Configuration

    <location name="ftp_uploads">
        ftp://myname:mypassword@ftp.mycompany.com:port/uploads
    </location>

Example Response

    {
        "id" : 2375
    }

2.4.2. asset/update

After you have created an item using the metadata/createitem operation you can assign an asset to this item using this asset/update operation. The operation has parameters similar to importing an asset but instead of adding a new asset to the catalog it updates the asset contents of an existing asset.

There are three ways of specifying the source asset:

Specify an existing asset using a URL (using the location parameter).
Specify an existing asset based on a configured location and a relative path (using the location parameter).
Upload the asset with the HTTP request. This is done by putting the asset contents into the request body and using the HTTP POST method. This request the body only contains the asset contents.

Allowed HTTP method: POST

Available since: 8.5.2

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.
`view`	string (optional)	The name of a view definition from the configuration file which defines a list of fields to use. See the configuration section on details on how to define views. The field list can be extended with additional fields specified in named request parameters.
`id`	long (required)	The ID of the asset in the catalog specified by the first path parameter.

Named Parameters

Location

Parameter	Type	Description
`location`	string (optional)	The location path for an existing asset. The path is either a complete URL that starts with a URL protocol like “ftp”, “sftp”, “ftps”, “file” or is based on a location defined in the configuration file. By using a configured location and a relative path you can hide details such as FTP passwords from the user of the service. When executed the location name is replaced with the configured location string.

options string (optional) The name of an options set defined in the configuration file. The exact options are DAM system dependent.

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result does not have any contents.

Examples

a) Update an asset contents of the asset with the ID 1234 by uploading it with the request. The request needs to use POST method with the asset contents in the request body. The MIME type of the request content can be application/octet-stream:

Example Request

http://cip-server:port/CIP/asset/update/mycatalog/1234

Example Request Body

The binary contents of the new version of the asset

b) Update an asset reference of the asset with the ID 1234 directly from the preconfigured FTPS server location:

Example Request

http://cip-server:port/CIP/asset/update/mycatalog/1234?location=ftps_checkouts/image.jpg

Example Configuration

    <location name="ftps_checkouts">
        ftps://myname:mypassword@ftps.mycompany.com:port/checkouts
    </location>

2.4.3. asset/download

You can download an asset using the "download" operation of the "asset" service. If the asset is available in several versions you can optionally specify the version that you want to download.

Optionally you can convert the asset prior to downloading.

An optional location allows you to store the result in the local file system of the CIP server or on an FTP server instead of downloading the result to the client.

In place of location you can specify e-mail parameters to send the asset as an e-mail attachment.

Allowed HTTP methods: GET and POST

Available since: 8.5.2

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.
`id`	long (required)	The ID of the asset in the catalog specified by the first path parameter.

Named Parameters

Settings

Parameter	Type	Description
`version`	integer (optional)	The version of the asset to download. The default is to download the latest version.
`options`	string (optional)	The name of a configured option set that contains the conversion options to be applied before downloading. The configuration contains the parameters for the actual conversion.

Location

location string (optional) The location path of a folder to store the result. The path is either a complete URL that starts with a URL protocol like “ftp”, “sftp”, “ftps”, “file” or is based on a location defined in the configuration file. By using a configured location and a relative path you can hide details such as FTP passwords from the user of the service. When executed the location name is replaced with the configured location string.

name string (optional) The name of the file to store the result as. This parameter is only used when a "location" is specified.

ifexists

string (optional)

Specify what to do when the result refers to an existing file or directory in the location.

Available since: 8.6

Possible values are:

`newuniquename`	(Default) Generate a unique name for the result.
`replace`	Replace the existing file or directory with the result.
`error`	Do nothing and return an error instead.

E-mail

`mailfrom`	string (optional)	The sender e-mail address.
`mailrecipients`	string array (optional)	The list of e-mail recipients. Required to send an e-mail.
`mailcc`	string array (optional)	The list of e-mail Cc (carbon copy) recipients.
`mailbcc`	string array (optional)	The list of e-mail Bcc (blind carbon copy) recipients.
`mailsubject`	string (optional)	The subject line of the e-mail message.
`mailbody`	string (optional)	The body text of the e-mail message.

Cache Control

cachecontrol

string (optional)

Allow to control client cache policy switch for CIP operation results. This could lead to better performance in case the browser can use cached images.

Available since: 8.6

Possible values are:

`no-cache`	(Default) - Switch off caching of images in the browser
`clientdefault`	Allow caching of images. The cache lifetime depend on constraint `com.canto.cip.constraint.clientcachemaxage` configuration. The default value is 3600 seconds (1 hour). See configuration section for details.

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

If you specified a location to store the resulting asset then the response body contains JSON data specifying the exact location.
If you specified e-mail parameters to send asset as an e-mail attachment then the response body contains JSON data specifying the name of the sent file.
If you did not specify either a location or an e-mail then the response body contains the resulting asset contents.

Examples

a) Download the original asset for the asset with the ID 1234 in the catalog whose alias is "mycatalog":

Example Request

http://cip-server:port/CIP/asset/download/mycatalog/1234

Example Response

The asset contents (e.g. JPEG data stream for a JPEG image).

b) Download the asset with the ID 1234 of the catalog whose alias is "mycatalog" after converting it to a PDF. The example is based on a Cumulus asset action of name “Convert to PDF” to be configured:

Example Request

http://cip-server:port/CIP/asset/download/mycatalog/1234?options=convert2pdf

Example Configuration

    <optionSets>
        ...
        <optionSet name="convert2pdf">
            <option name="com.canto.cumulus.assetaction">Convert to PDF</option>
        </optionSet>
        ...
    </optionSets>

Example Response

The PDF that is the result of converting the given asset.

c) Store the asset with the ID 1234 of the catalog whose alias is "mycatalog" to configured location "ftp_downloads":

Example Request

http://cip-server:port/CIP/asset/download/mycatalog/1234?location=ftp_downloads

Example Configuration

    <location name="ftp_downloads">
        ftp://myname:mypassword@ftp.mycompany.com:port/downloads
    </location>

Example Response

    {
        "location": "ftp_downloads/myimage.jpg"
    }

d) Send the asset with the ID 1234 of the catalog whose alias is "mycatalog" through e-mail to two recipients user1@mail.com and user2@mail.com.

Example Request

http://cip-server:port/CIP/asset/download/mycatalog/1234?mailfrom=cumulus@cumulus.com&mailrecipients=user1@mail.com&mailrecipients=user2@mail.com

Example Response

    {
        "location": "e-mail/myimage.jpg"
    }

2.4.4. asset/checkout

The checkout operation allows you to lock the asset for further modifications and also to download the latest version of the asset or to store it at a given location. This is typically done to work on a new version of the asset and check this back in later.

An optional location allows you to store the current asset in the local file system of the CIP server or on an FTP server instead of downloading it to the client.

After you have finished modifying the asset you can generate a new version in the catalog by using the asset/checkin operation. To revert to the normal state without checking in a new asset version call the asset/undocheckout operation.

Allowed HTTP method: POST

Available since: 8.5.2

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.
`id`	long (required)	The ID of the asset in the catalog specified by the first path parameter.

Named Parameters

Location

Parameter Type Description

location string (optional) The location path of a folder to store the result. The path is either a complete URL that starts with a URL protocol like “ftp”, “sftp”, “ftps”, “file” or is based on a location defined in the configuration file. By using a configured location and a relative path you can hide details such as FTP passwords from the user of the service. When executed the location name is replaced with the configured location string.

name string (optional) The name of the file to store the result as. This parameter is only used when a "location" is specified.

ifexists

string (optional)

Specify what to do when the result refers to an existing file or directory in the location.

Available since: 8.6

Possible values are:

`newuniquename`	(Default) Generate a unique name for the result.
`replace`	Replace the existing file or directory with the result.
`error`	Do nothing and return an error instead.

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

If you specified a location to store the resulting asset then the response body contains JSON data specifying the exact location.
If you did not specify a location then the response body contains the resulting asset contents.

Examples

a) Check out the asset with the ID 1234 in the catalog whose alias is “mycatalog” and download the current asset contents:

Example Request

http://cip-server:port/CIP/asset/checkout/mycatalog/1234

Example Response

The current asset contents

b) Store the asset with the ID 1234 of the catalog whose alias is "mycatalog" to configured location "sftp_downloads":

Example Request

http://cip-server:port/CIP/asset/checkout/mycatalog/1234?location=sftp_checkouts

Example Configuration

    <location name="sftp_checkouts">
        sftp://myname:mypassword@ftp.mycompany.com:port/checkouts
    </location>

Example Response

    {
        "location": "sftp_checkouts/myimage.jpg"
    }

2.4.5. asset/checkin

After you have checked out an asset using the asset/checkout operation you can check in a new version of the asset using this checkin operation. The operation has parameters similar to importing an asset but instead of adding a new asset to the catalog it adds a new version to an existing asset.

There are three ways of specifying the asset to be checked in:

Specify an existing asset using a URL (using the location parameter).
Specify an existing asset based on a configured location and a relative path (using the location parameter).
Upload the asset with the HTTP request. This is done by putting the asset contents into the request body and using the HTTP POST method. This request the body only contains the asset contents.

Allowed HTTP method: POST

Available since: 8.5.2

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.
`id`	long (required)	The ID of the asset in the catalog specified by the first path parameter.

Named Parameters

Location

Parameter	Type	Description
`location`	string (optional)	The location path for an existing asset. The path is either a complete URL that starts with a URL protocol like “ftp”, “sftp”, “ftps”, “file” or is based on a location defined in the configuration file. By using a configured location and a relative path you can hide details such as FTP passwords from the user of the service. When executed the location name is replaced with the configured location string.

options string (optional) The name of an options set defined in the configuration file. The exact options are DAM system dependent.

comment string (optional) The comment for this new version of the asset. This comment is available as version-specific metadata.

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result does not have any contents.

Examples

a) Check in a new version of the asset with the ID 1234 by uploading it with the request. The request needs to use POST method with the asset contents in the request body. The MIME type of the request content can be application/octet-stream:

Example Request

http://cip-server:port/CIP/asset/checkin/mycatalog/1234

Example Request Body

The binary contents of the new version of the asset

b) Check in a new version of the asset with the ID 1234 directly from the preconfigured FTPS server location:

Example Request

http://cip-server:port/CIP/asset/checkin/mycatalog/1234?location=ftps_checkouts/image.jpg

Example Configuration

    <location name="ftps_checkouts">
        ftps://myname:mypassword@ftps.mycompany.com:port/checkouts
    </location>

2.4.6. asset/undocheckout

If you have checked out an asset using the asset/checkout operation you can undo this action by calling this operation.

Allowed HTTP method: POST

Available since: 8.5.2

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.
`id`	long (required)	The ID of the asset in the catalog specified by the first path parameter.

Named Parameters

Parameter Type Description

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result does not have any contents.

Examples

a) Undo the checkout operation performed for the asset with the ID 1234 in the catalog whose alias is "mycatalog":

Example Request

http://cip-server:port/CIP/asset/undocheckout/mycatalog/1234

2.4.7. asset/rollback

You can returns an asset to the previous version by using rollback operation.

Allowed HTTP method: POST

Available since: 8.5.2

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.
`id`	long (required)	The ID of the asset in the catalog specified by the first path parameter.
`version`	integer (required)	The version number of the asset to be restored as newer one. You can retrieve the list of available versions for an asset using the `asset/getversions` operation.

Named Parameters

Parameter Type Description

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result is the newly created version number given to the restored (rolled back) asset.

Examples

a) Rollback the asset with the ID 1234 to the version number 2 in the catalog whose alias is "mycatalog":

Example Request

http://cip-server:port/CIP/asset/rollback/mycatalog/1234/2

Example Response

{
    "version" : 11
}

2.4.8. asset/getversions

You can retrieve the list of available versions for a DAM item.

Allowed HTTP methods: GET and POST

Available since: 8.5.2

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.
`id`	long (required)	The ID of the asset in the catalog specified by the first path parameter.

Named Parameters

Parameter Type Description

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result is returned in JSON format and consists of the item id and a list of available versions described by checkin user, checkin comment, checkin date and version number.

Examples

a) Retrieve the list of available versions for an asset with the ID 1234 in the catalog whose alias is "mycatalog":

Example Request

http://cip-server:port/CIP/asset/getversions/mycatalog/1234

Example Response

{
        "id"       : 1234
        "supportsversioning": true,
        "versions" : [
            {
                "versionnumber"  : 1
                "checkincomment" : ""
                "checkindate"    : "/Date(1314866536000)/"
                "checkinuser"    : "cumulus"
            },
            {
                "versionnumber"  : 2
                "checkincomment" : "Improved image"
                "checkindate"    : "/Date(1314876036000)/"
                "checkinuser"    : "cumulus"
            }
        ]
}

b) Retrieve the list of available versions for a not versionable asset with the ID 268 in the catalog whose alias is "mycatalog":

Example Request

http://cip-server:port/CIP/asset/getversions/mycatalog/1234

Example Response

{

    "id"        : 268,
    "supportsversioning": false,
    "versions"  : [ ]

}

2.4.9. asset/delete

Delete an item and optionally also the asset that is referenced by this item.

Allowed HTTP method: POST

Available since: 8.5.2

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.
`id`	long (required)	The ID of the asset in the catalog specified by the first path parameter.

Named Parameters

Parameter Type Description

withasset

string (optional)

This parameter specifies whether you want to delete not just the item but the asset as well.

Possible values are:

`false`	(Default) - Only the item will be deleted. The corresponding asset will be preserved
`true`	The item as well as the corresponding asset will be deleted.

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result does not have any contents.

Examples

a) Delete the item with the ID 1234 and corresponding asset in the catalog whose alias is "mycatalog":

Example Request

http://cip-server:port/CIP/asset/delete/mycatalog/1234?withasset=true

2.5. Comments Service

The comments service allow working with user comments (annotations).

2.5.1. comments/get

Return a list of all comments in a structure that has the "User Comment Thread" sub-table items on top level and nested within the "User Comments" sub-table.

Allowed HTTP methods: GET and POST

Available since: 8.6

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.
`id`	long (required)	The ID of the asset in the catalog specified by the first path parameter.

Named Parameters

Parameter Type Description

apiversion

integer (optional)

Available since: 8.6

Supported values:

`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

Return a list of all comments in a structure that has the "User Comment Thread" sub-table items on top level and nested within the "User Comments" sub-table.

Examples

a) List all comments for the item with the ID 989 in the catalog whose alias is "mycatalog":

Example Request

http://cip-server:port/CIP/comments/get/mycatalog/1234

Example Response

{
    "threads": [
        {
            "id": 3,
            "itemid": 989,
            "type": "icon",
            "user": "U:{98ca1422-0171-4d1d-8b84-8cdda4ab70ae}:cumulus",
            "creationdate": "/Date(1328616117000)/",
            "coordinates": {
                "x": 0.27944711538461536,
                "y": 0.515673511148744
            },
            "comments": [
                {
                    "id": 3,
                    "threadid": 3,
                    "user": "U:{98ca1422-0171-4d1d-8b84-8cdda4ab70ae}:cumulus",
                    "modificationdate": "/Date(1328616476000)/",
                    "comment": "Hi i am user comment created with the cumulus 8.6"
                }
            ]
        },
        {
            "id": 4,
            "itemid": 989,
            "type": "polygon",
            "user": "U:{98ca1422-0171-4d1d-8b84-8cdda4ab70ae}:cumulus",
            "creationdate": "/Date(1328616296000)/",
            "coordinates": [
                {
                    "x": 0.6510437710437711,
                    "y": 0.48570225730824096
                },
                {
                    "x": 0.6825589225589226,
                    "y": 0.6166236644362527
                },
                {
                    "x": 0.6534680134680135,
                    "y": 0.6368275852893409
                },
                {
                    "x": 0.652929292929293,
                    "y": 0.6020768414220292
                },
                {
                    "x": 0.6383838383838384,
                    "y": 0.6020768414220292
                }
            ],
            "comments": [
                {
                    "id": 4,
                    "threadid": 4,
                    "user": "U:{98ca1422-0171-4d1d-8b84-8cdda4ab70ae}:cumulus",
                    "modificationdate": "/Date(1329399392000)/",
                    "comment": "Polygon comment created with the cumulus 8.6"
                }
            ]
        },
        {
            "id": 5,
            "itemid": 989,
            "type": "rectangle",
            "user": "U:{98ca1422-0171-4d1d-8b84-8cdda4ab70ae}:cumulus",
            "creationdate": "/Date(1328616345000)/",
            "coordinates": {
                "topleft": {
                    "x": 0.14302884615384615,
                    "y": 0.5427193246705312
                },
                "bottomright": {
                    "x": 0.20372596153846154,
                    "y": 0.9087393343320523
                }
            },
            "comments": [
                {
                    "id": 5,
                    "threadid": 5,
                    "user": "U:{98ca1422-0171-4d1d-8b84-8cdda4ab70ae}:cumulus",
                    "modificationdate": "/Date(1328616476000)/",
                    "comment": "Rectangle comment created with the cumulus 8.6"
                }
            ]
        }
    ]
}

2.5.2. comments/getthread

Return a list of all comments from "User Comments" sub-table for the specified "User Comment Thread"

Allowed HTTP methods: GET and POST

Available since: 8.6

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.
`id`	long (required)	The ID of the user comment thread.

Named Parameters

Parameter Type Description

apiversion

integer (optional)

Available since: 8.6

Supported values:

`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

Return a list of all comments from "User Comments" sub-table for the specified "User Comment Thread"

Examples

a) List all comments for the comment thread with the ID 7 in the catalog whose alias is "mycatalog":

Example Request

http://cip-server:port/CIP/comments/getthread/mycatalog/7

Example Response

{
    "id": 7,
    "itemid": 162,
    "type": "icon",
    "user": "U:{98ca1422-0171-4d1d-8b84-8cdda4ab70ae}:cumulus",
    "creationdate": "/Date(1328617037000)/",
    "coordinates": {
        "x": 0.5411111111111111,
        "y": 0.718801996672213
    },
    "comments": [
        {
            "id": 7,
            "threadid": 7,
            "user": "U:{98ca1422-0171-4d1d-8b84-8cdda4ab70ae}:cumulus",
            "modificationdate": "/Date(1328617075000)/",
            "comment": "sticky note comment cumulus 8.0.1"
        },
        {
            "id": 18,
            "threadid": 7,
            "user": "U:{98ca1422-0171-4d1d-8b84-8cdda4ab70ae}:sample",
            "modificationdate": "/Date(1329303881000)/",
            "comment": "go ahead"
        }
    ]
}

2.5.3. comments/add

Add a new item to the "User Comment Thread" sub-table and an additional item to the "User Comments" sub-table.
Request Body: JSON structure containing coordinates, type (icon, rectangle, polygon, timesegment, discussion), comment and optionally creationdate.

Allowed HTTP method: POST

Available since: 8.6

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.
`id`	long (required)	The ID of the asset in the catalog specified by the first path parameter.

Named Parameters

Parameter Type Description

apiversion

integer (optional)

Available since: 8.6

Supported values:

`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result is returned in JSON format and consists of the ID of the created "User Comment Thread" item.

Examples

a) Add a new user comments thread of the icon type to the item with the ID 1234 in the catalog whose alias is "mycatalog":

Example Request

http://cip-server:port/CIP/comments/add/mycatalog/1234

Example Request Body

{
    "coordinates": {
        "x": 0.5411111111111111,
        "y": 0.718801996672213
    },
    "type": "icon",
    "comment": "My first comment",
    "creationdate": "/Date(1329820826270)/"
}

Example Response

    {
        "id" : 3312
    }

b) Add a new user comments thread of the rectangle type to the item with the ID 1234 in the catalog whose alias is "mycatalog":

Example Request

http://cip-server:port/CIP/comments/add/mycatalog/1234

Example Request Body

{
    "coordinates": {
        "topleft": {
            "x": 0.14302884615384615,
            "y": 0.5427193246705312
        },
        "bottomright": {
            "x": 0.20372596153846154,
            "y": 0.9087393343320523
        }
    },
    "type": "rectangle",
    "comment": "my first rectangle comment",
    "creationdate": "/Date(1329820828972)/"
}

Example Response

    {
        "id" : 3313
    }

c) Add a new user comments thread of the polygon type to the item with the ID 1234 in the catalog whose alias is "mycatalog":

Example Request

http://cip-server:port/CIP/comments/add/mycatalog/1234

Example Request Body

{
    "coordinates": [
        {
            "x": 0.6510437710437711,
            "y": 0.48570225730824096
        },
        {
            "x": 0.6825589225589226,
            "y": 0.6166236644362527
        },
        {
            "x": 0.6534680134680135,
            "y": 0.6368275852893409
        },
        {
            "x": 0.652929292929293,
            "y": 0.6020768414220292
        },
        {
            "x": 0.6383838383838384,
            "y": 0.6020768414220292
        }
    ],
    "type": "polygon",
    "comment": "my first polygon comment",
    "creationdate": "/Date(1329820835749)/"
}

Example Response

    {
        "id" : 3314
    }

2.5.4. comments/addcomment

Add a new item to the "User Comments" sub-table.
Request Body: JSON structure containing comment and optionally creationdate.

Allowed HTTP method: POST

Available since: 8.6

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.
`id`	long (required)	The ID of the comments thread in the catalog specified by the first path parameter.

Named Parameters

Parameter Type Description

apiversion

integer (optional)

Available since: 8.6

Supported values:

`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result is returned in JSON format and consists of the ID of the created "User Comments" item.

Examples

a) Add a new comment to the user comments thread with the ID 1234 in the catalog whose alias is "mycatalog":

Example Request

http://cip-server:port/CIP/comments/addcomment/mycatalog/1234

Example Request Body

{
    "comment": "my new comment",
    "creationdate": "/Date(1329820832410)/"
}

Example Response

    {
        "id" : 4312
    }

2.5.5. comments/adddiscussion

Add a new discussion type item to the "User Comment Thread" sub-table and an additional item to the "User Comments" sub-table.
Request Body: JSON structure containing comment and optionally creationdate.

Allowed HTTP method: POST

Available since: 8.6

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.
`id`	long (required)	The ID of the asset in the catalog specified by the first path parameter.

Named Parameters

Parameter Type Description

apiversion

integer (optional)

Available since: 8.6

Supported values:

`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result is returned in JSON format and consists of the ID of the created "User Comment Thread" item.

Examples

a) Add a new comment to the item with the ID 1234 in the catalog whose alias is "mycatalog":

Example Request

http://cip-server:port/CIP/comments/adddiscussion/mycatalog/1234

Example Request Body

{
    "comment": "my first discussion comment",
    "creationdate": "/Date(1329820833669)/"
}

Example Response

    {
        "id" : 5431
    }

2.5.6. comments/updatecoordinates

Update a user comments thread's coordinates
Request Body: JSON structure containing coordinates and type (icon, rectangle, polygon, timesegment, discussion).

Allowed HTTP method: POST

Available since: 8.6

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.
`id`	long (required)	The ID of user comments thread in the catalog specified by the first path parameter.

Named Parameters

Parameter Type Description

apiversion

integer (optional)

Available since: 8.6

Supported values:

`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result does not have any contents.

Examples

a) Update a user comments thread coordinates of the icon type to the item with the ID 1234 in the catalog whose alias is "mycatalog":

Example Request

http://cip-server:port/CIP/comments/updatecoordinates/mycatalog/1234

Example Request Body

{
    "coordinates": {
        "x": 0.5411111111111111,
        "y": 0.718801996672213
    },
    "type": "icon"
}

b) Update a user comments thread coordinates of the rectangle type to the item with the ID 1234 in the catalog whose alias is "mycatalog":

Example Request

http://cip-server:port/CIP/comments/updatecoordinates/mycatalog/1234

Example Request Body

{
    "coordinates": {
        "topleft": {
            "x": 0.14302884615384615,
            "y": 0.5427193246705312
        },
        "bottomright": {
            "x": 0.20372596153846154,
            "y": 0.9087393343320523
        }
    },
    "type": "rectangle"
}

c) Update a user comments thread coordinates of the polygon type to the item with the ID 1234 in the catalog whose alias is "mycatalog":

Example Request

http://cip-server:port/CIP/comments/updatecoordinates/mycatalog/1234

Example Request Body

{
    "coordinates": [
        {
            "x": 0.6510437710437711,
            "y": 0.48570225730824096
        },
        {
            "x": 0.6825589225589226,
            "y": 0.6166236644362527
        },
        {
            "x": 0.6534680134680135,
            "y": 0.6368275852893409
        },
        {
            "x": 0.652929292929293,
            "y": 0.6020768414220292
        },
        {
            "x": 0.6383838383838384,
            "y": 0.6020768414220292
        }
    ],
    "type": "polygon"
}

2.5.7. comments/updatecomment

Update a comment text in the "User Comments" sub-table.
Request Body: JSON structure containing comment and optionally modificationdate.

Allowed HTTP method: POST

Available since: 8.6

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.
`id`	long (required)	The ID of the user comment the catalog specified by the first path parameter.

Named Parameters

Parameter Type Description

apiversion

integer (optional)

Available since: 8.6

Supported values:

`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result does not have any contents.

Examples

a) Update a comment text for the comment with the ID 1234 in the catalog whose alias is "mycatalog":

Example Request

http://cip-server:port/CIP/comments/updatecomment/mycatalog/1234

Example Request Body

{
    "comment": "my first discussion comment",
    "modificationdate": "/Date(1329820833669)/"
}

2.5.8. comments/updatediscussion

Update a discussion comment text in the "User Comments" sub-table.
Request Body: JSON structure containing comment and optionally modificationdate.

Allowed HTTP method: POST

Available since: 8.6

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.
`id`	long (required)	The ID of the user comment the catalog specified by the first path parameter.

Named Parameters

Parameter Type Description

apiversion

integer (optional)

Available since: 8.6

Supported values:

`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result does not have any contents.

Examples

a) Update a discussion comment text for the comment with the ID 1234 in the catalog whose alias is "mycatalog":

Example Request

http://cip-server:port/CIP/comments/updatecomment/mycatalog/1234

Example Request Body

{
    "comment": "my new discussion comment",
    "modificationdate": "/Date(1329820835749)/"
}

2.5.9. comments/deletethread

Delete an item from the "User Comment Thread" sub-table and the corresponding items from the "User Comments" sub-table.

Allowed HTTP method: POST

Available since: 8.6

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.
`id`	long (required)	The ID of the user comment thread in the catalog specified by the first path parameter.

Named Parameters

Parameter Type Description

apiversion

integer (optional)

Available since: 8.6

Supported values:

`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result does not have any contents.

Examples

a) Delete the thread with the ID 1234 and the corresponding comments in the catalog whose alias is "mycatalog":

Example Request

http://cip-server:port/CIP/comments/deletethread/mycatalog/1234

2.5.10. comments/deletecomment

Delete an item from the "User Comments" sub-table.

Allowed HTTP method: POST

Available since: 8.6

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.
`id`	long (required)	The ID of the comments thread in the catalog specified by the first path parameter.

Named Parameters

Parameter Type Description

apiversion

integer (optional)

Available since: 8.6

Supported values:

`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result does not have any contents.

Examples

a) Delete a comment with the ID 1234 in the catalog whose alias is "mycatalog":

Example Request

http://cip-server:port/CIP/comments/deletecomment/mycatalog/1234

2.5.11. comments/deletediscussion

Delete a discussion item from the "User Comment Thread" sub-table and the corresponding items from the "User Comments" sub-table.

Allowed HTTP method: POST

Available since: 8.6

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.
`id`	long (required)	The ID of the discussion user comment thread in the catalog specified by the first path parameter.

Named Parameters

Parameter Type Description

apiversion

integer (optional)

Available since: 8.6

Supported values:

`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result does not have any contents.

Examples

a) Delete the discussion thread with the ID 1234 and the corresponding comments in the catalog whose alias is "mycatalog":

Example Request

http://cip-server:port/CIP/comments/deletediscussion/mycatalog/1234

2.6. Location Management Service

The location management services offer operation to manipulate files and folders in the file system of the CIP server or on FTP servers. In order to control who is allowed to perform the operations the DAM user needs to have specific permissions.

In a Cumulus DAM system the following list shows the server permissions required to perform location management operations:

$CanDeleteFiles - allow to delete a files and directories
$CanCopyFiles - allow to copy a files and directories
$CanMoveFiles - allow to move/rename a files and directories
$CanListFiles - allow to list a files and directories
$CanCreateDirectories - allow to create a directories

The locations can be specified either by a complete URL starting with "ftp:", "sftp", "ftps", or "file" or they can be starting with the name of a configured location.

When specifying a complete URL the corresponding protocol (e.g. "file") needs to be activated in the configuration file.

In order to be able to check the permission you need to specify the user, password, and server address in the request or use a session that contains these parameters.

2.6.1. location/list

Lists files and directories found in the requested location. This operation can be used to check whether a given file or directory exists.

If the location specifies a file the result is the same location again.
If the location specifies a directory the result contains a list of names for the contained files or directories.
If the location is not valid (e.g. file/directory does not exist) an error is returned.

The user specified in the request needs the server permission $CanListFiles to perform this action.

Allowed HTTP methods: GET and POST

Available since: 8.5.2

Named Parameters

Parameter Type Description

location string (required) The complete location path of the directory or file to list. The path is either a complete URL that starts with a URL protocol like “ftp”, “sftp”, “ftps”, “file” or is based on a location defined in the configuration file. By using a configured location and a relative path you can hide details such as FTP passwords from the user of the service. When executed the location name is replaced with the configured location string.

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

Result

A list of locations for all files/directories contained.

Examples

a) List contents of a directory "test" from the preconfigured FTPS server location "ftpsupload":

Example Request

http://cip-server:port/CIP/location/list?location=ftpsupload/test

Example Configuration

    <location name="ftpsupload">
        ftps://myname:mypassword@ftps.mycompany.com:port/uploads
    </location>

Example Response

    {
        "location" : "ftpsupload/test",
        "listing"  : [
            {
                "path" : "test1",
                "type" : "directory"
            },
            {
                "path" : "desktop.ini",
                "type" : "file"
            },
            {
                "path" : "Desert.jpg",
                "type" : "file"
            },
            {
                "path" : "Reichstag.jpg",
                "type" : "file"
            }
        ]
    }

b) List a single file "test/Desert.jpg" from the preconfigured FTPS server location "ftpsupload":

Example Request

http://cip-server:port/CIP/location/list?location=ftpsupload/test/Desert.jpg

Example Configuration

    <location name="ftpsupload">
        ftps://myname:mypassword@ftps.mycompany.com:port/uploads
    </location>

Example Response

    {
        "location" : "ftpsupload/test/Desert.jpg",
        "type"     : "file"
    }

2.6.2. location/createdir

Create a new directory specified in the location parameter.

The user specified in the request needs the server permission $CanCreateDirectories to perform this action.

Allowed HTTP method: POST

Available since: 8.5.2

Named Parameters

Parameter Type Description

location string (required) The complete location path of the directory to create. All missing directories are created. The path is either a complete URL that starts with a URL protocol like “ftp”, “sftp”, “ftps”, “file” or is based on a location defined in the configuration file. By using a configured location and a relative path you can hide details such as FTP passwords from the user of the service. When executed the location name is replaced with the configured location string.

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

Result

The newly created location.

Examples

a) Create a new directory "pictures" in the preconfigured location "ftps_checkouts":

Example Request

http://cip-server:port/CIP/location/createdir?location=ftps_checkouts/pictures

Example Configuration

    <location name="ftps_checkouts">
        ftps://myname:mypassword@ftps.mycompany.com:port/checkouts
    </location>

Example Response

    {
        "location" : "ftps_checkouts/pictures"
    }

b) Create a new directory "pictures" in the file system of the CIP server:

Example Request

http://cip-server:port/CIP/location/createdir?location=file://C:/pictures

Example Configuration

    <locations>
    ...
        <enableProtocol>file</enableProtocol>
    ...
    <locations>

Example Response

    {
        "location" : "file://C:/pictures"
    }

2.6.3. location/copy

Copy a file or directory.

The user specified in the request needs the server permission $CanCopyFiles to perform this action.

Allowed HTTP method: POST

Available since: 8.5.2

Named Parameters

Parameter Type Description

from string (required) The location path of the file or directory to copy. The path is either a complete URL that starts with a URL protocol like “ftp”, “sftp”, “ftps”, “file” or is based on a location defined in the configuration file. By using a configured location and a relative path you can hide details such as FTP passwords from the user of the service. When executed the location name is replaced with the configured location string.

to

string (required)

The location path for the destination. The path is either a complete URL that starts with a URL protocol like “ftp”, “sftp”, “ftps”, “file” or is based on a location defined in the configuration file. By using a configured location and a relative path you can hide details such as FTP passwords from the user of the service. When executed the location name is replaced with the configured location string.

If "to" is an existing directory then the "from" file/dir is copied there
If "to" does not exist then the "from" file/directory is copied to the parent of "to" which needs to be an existent dir and the copy gets the name specified in "to"
If "to" is an existing file and "from" is a file too the parameter ifexists controls how to handle this case.

ifexists

string (optional)

Specify what to do when the parameter to refers to an existing file or directory.

Possible values are:

`newuniquename`	(Default) Generate a unique name for the target and copy the source there.
`replace`	Replace the existing file or directory with the copied one.
`error`	Do nothing and return an error instead.

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

Result

The location of the copy.

Examples

a) Copy the local file "c:/pictures/IMG11223.jpg" to "c:/target/sample.jpg":

Example Request

http://cip-server:port/CIP/location/copy?from=file://c:/pictures/IMG11223.jpg&to=file://c:/target/sample.jpg

Example Configuration

    <locations>
    ...
        <enableProtocol>file</enableProtocol>
    ...
    <locations>

Example Response

    {
        "location" : "file://c:/target/sample.jpg"
    }

b) Copy a directory specified by the URL ftps://myname:mypassword@ftps.mycompany.com:port/checkouts/pictures directly from the preconfigured FTPS server location to the local location c:/stuff:

Example Request

http://cip-server:port/CIP/location/copy?from=ftps_checkouts/pictures/IMG22113.jpg&to=file://c:/stuff

Example Configuration

    <locations>
    ...
        <enableProtocol>file</enableProtocol>

        <location name="ftps_checkouts">
            ftps://myname:mypassword@ftps.mycompany.com:port/checkouts
        </location>
    ...
    <locations>

Example Response

    {
        "location" : "file://c:/target/sample.jpg"
    }

2.6.4. location/move

Move a file or directory. This works the same as first calling location/copy and then location/delete but is just faster because it does it in one step.
This can also be used to rename a file or directory.

The user specified in the request needs the server permission $CanMoveFiles to perform this action.

Allowed HTTP method: POST

Available since: 8.5.2

Named Parameters

Parameter Type Description

from string (required) The location path of the file or directory to move. The path is either a complete URL that starts with a URL protocol like “ftp”, “sftp”, “ftps”, “file” or is based on a location defined in the configuration file. By using a configured location and a relative path you can hide details such as FTP passwords from the user of the service. When executed the location name is replaced with the configured location string.

to

string (required)

If "to" is an existing directory then the "from" file/dir is copied there
If "to" does not exist then the "from" file/directory is copied to the parent of "to" which needs to be an existent dir and the copy gets the name specified in "to"
If "to" is an existing file and "from" is a file too an

ifexists

string (optional)

Specify what to do when the parameter to refers to an existing file or directory.

Possible values are:

`newuniquename`	(Default) Generate a unique name for the target and move the source there.
`replace`	Replace the existing file or directory with the moved one.
`error`	Do nothing and return an error instead.

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

Result

The location of the moved file / directory.

Examples

a) Rename the local file "c:/pictures/IMG11223.jpg" to "c:/target/sample.jpg":

Example Request

http://cip-server:port/CIP/location/move?from=file://c:/pictures/IMG11223.jpg&to=file://c:/target/sample.jpg

Example Configuration

    <locations>
    ...
        <enableProtocol>file</enableProtocol>
    ...
    <locations>

Example Response

    {
        "location" : "file://c:/target/sample.jpg"
    }

b) Move a directory specified by the URL ftps://myname:mypassword@ftps.mycompany.com:port/checkouts/pictures directly from the preconfigured FTPS server location to the local locationc:/stuff:

Example Request

http://cip-server:port/CIP/location/move?from=ftps_checkouts/pictures/IMG22113.jpg&to=file://c:/stuff

Example Configuration

    <locations>
    ...
        <enableProtocol>file</enableProtocol>

        <location name="ftps_checkouts">
            ftps://myname:mypassword@ftps.mycompany.com:port/checkouts
        </location>
    ...
    <locations>

Example Response

    {
        "location" : "file://c:/target/sample.jpg"
    }

2.6.5. location/delete

Delete a file or directory

The user specified in the request needs the server permission $CanDeleteFiles to perform this action.

Allowed HTTP method: POST

Available since: 8.5.2

Named Parameters

Parameter Type Description

location string (required) The complete location path of the directory or file to delete. The path is either a complete URL that starts with a URL protocol like “ftp”, “sftp”, “ftps”, “file” or is based on a location defined in the configuration file. By using a configured location and a relative path you can hide details such as FTP passwords from the user of the service. When executed the location name is replaced with the configured location string.

recursive

string (optional)

When deleting a directory this parameter controls whether to delete all the contents of the directory also.

Possible values are:

`false`	(Default) Only delete the directory if it is empty. Return an error otherwise.
`true`	Delete the specified directory and all of its contents.

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

Result

The result does not have any contents.

Examples

a) Delete the local file "c:/pictures/IMG11223.jpg":

Example Request

http://cip-server:port/CIP/location/delete?location=file://c:/pictures/IMG11223.jpg

Example Configuration

    <locations>
    ...
        <enableProtocol>file</enableProtocol>
    ...
    <locations>

b) Delete the file specified by the URL ftps://myname:mypassword@ftps.mycompany.com:port/checkouts/pictures/IMG22113.jpg directly from the preconfigured FTPS server location:

Example Request

http://cip-server:port/CIP/location/delete?location=ftps_checkouts/pictures/IMG22113.jpg

Example Configuration

    <location name="ftps_checkouts">
        ftps://myname:mypassword@ftps.mycompany.com:port/checkouts
    </location>

2.7. Developer Service

The developer service offers operations that can be used by developers writing client-side code.

2.7.1. developer/describe

Generate C# or Java wrapper class source code for the specified catalog and optionally a view.

The class is always derived from the Canto.Cip.Lib.DamItem class and is named according to the view it was generated for. The package name is always Canto.Cip.Client.Views.

C# programmers can use the class by initializing the CIPManager instance with the package name where these generated view wrapper classes are defined for:

    cipManager = new CIPManager(BaseUrl, "Canto.Cip.Client.Views");

Then CIPManager functions like GetFieldValues() will return an instance of this wrapper class instead of the generic DamItem class. Assume you have generated the code for a wrapper class for the configured view named "fields" (see example below). Then you can use the class like this:

        FieldsView item = cipManager.GetFieldValues (session, Catalog, "fields", id) as FieldsView;
        Console.WriteLine("Name: \"{1}\", Date: {2}, Status: {3}",
                           item.Name, item.RecordModificationDate, item.Status);

The variable and function names generated are stripped to meet the requirements of C# naming so every special character that occurs in field names or values is replaced.

Allowed HTTP methods: GET and POST

Available since: 8.5.2

Path Parameters

Parameter	Type	Description
`catalog`	string (required)	The name of a catalog alias definition from the configuration file. See the configuration section for details on how to define catalog aliases.
`view`	string (optional)	The name of a view definition from the configuration file which defines a list of fields to use. See the configuration section on details on how to define views. The field list can be extended with additional fields specified in named request parameters.

Named Parameters

Parameter Type Description

language

string (optional)

The target programming language for the generated source code.

Available since: 8.6

Possible values are:

`csharp`	(Default) Generate .net wrapper class source code.
`java`	Generate java wrapper class source code.

table string (optional) You may want to specify the table to generate C# wrapper class for. The default is "AssetRecords".

apiversion

integer (optional)

Available since: 8.6

Supported values:

`1`	CIP 8.5.2 release
`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

user string (optional) The DAM system user name.

password string (optional) The DAM system user’s password.

serveraddress string (optional) The DAM system server IP address e.g. localhost, 192.168.0.2

catalogname string (optional) The DAM system catalog name e.g. Sample Catalog

Result

The result is the generated C# or Java wrapper source.

Examples

a) Generate C# wrapper class for the catalog with the alias "mycatalog" and the configured view named "fields":

Example Request

http://cip-server:port/CIP/developer/describe/mycatalog/fields?locale=en&language=csharp

Example Configuration

    <catalogs>
        ...
        <catalog aliasName="mycatalog">
            <serverAddress>localhost</serverAddress>
            <userName>sample</userName>
            <password>sample</password>
            <catalogName>TestCatalog</catalogName>
        </catalog>
        ...
    </catalogs>

    <views>
        ...
        <view name="fields">
            <field>Status</field>
            <field>Asset Reference</field>
            <field>Asset Reference/Windows</field>
            <field>Asset Reference/ZIP</field>
            <field>Record Name</field>
            <field>Categories</field>
            <field>Record Modification Date</field>
            <field>Asset Name</field>
            <field>Image Width</field>
        </view>
        ...
    </views>

Example Response

    using System;
    using System.Collections.Generic;
    using Canto.Cip.Lib;
    using Canto.Cip.Lib.Entities;

    using Newtonsoft.Json;

    namespace Canto.Cip.Client.Views
    {
        [JsonObject(MemberSerialization.OptIn)]
        public class FieldsView : DamItem
        {
            public const string ViewName = "fields";


            private const string StatusKey = "Status";
            private const string AssetReferenceWindowsKey = "Asset Reference/Windows";
            private const string RatingKey = "Rating";
            private const string RecordNameKey = "Record Name";
            private const string AssetReferenceZIPKey = "Asset Reference/ZIP";
            private const string AssetReferenceKey = "Asset Reference";
            private const string ImageWidthKey = "Image Width";
            private const string CategoriesKey = "Categories";
            private const string AssetNameKey = "Asset Name";
            private const string RecordModificationDateKey = "Record Modification Date";

            private DamStringListValue _Status;
            private string _AssetReferenceWindows;
            private DamRatingValue _Rating;
            private string _RecordName;
            private string _AssetReferenceZIP;
            private IList<DamBinaryValue> _AssetReference;
            private double? _ImageWidth;
            private IList<DamCategoryValue> _Categories;
            private string _AssetName;
            private DateTime? _RecordModificationDate;


            [JsonProperty (PropertyName = StatusKey)]
            public DamStringListValue Status
            {
                get { return _Status; }
                set { _Status = value; }
            }


            [JsonProperty (PropertyName = AssetReferenceWindowsKey)]
            public string AssetReferenceWindows
            {
                get { return _AssetReferenceWindows; }
                set { _AssetReferenceWindows = value; }
            }


            [JsonProperty (PropertyName = RatingKey)]
            public DamRatingValue Rating
            {
                get { return _Rating; }
                set { _Rating = value; }
            }


            [JsonProperty (PropertyName = RecordNameKey)]
            public string RecordName
            {
                get { return _RecordName; }
                set { _RecordName = value; }
            }


            [JsonProperty (PropertyName = AssetReferenceZIPKey)]
            public string AssetReferenceZIP
            {
                get { return _AssetReferenceZIP; }
                set { _AssetReferenceZIP = value; }
            }


            [JsonProperty (PropertyName = AssetReferenceKey)]
            public IList<DamBinaryValue> AssetReference
            {
                get { return _AssetReference; }
                set { _AssetReference = value; }
            }


            [JsonProperty (PropertyName = ImageWidthKey)]
            public double? ImageWidth
            {
                get { return _ImageWidth; }
                set { _ImageWidth = value; }
            }


            [JsonProperty (PropertyName = CategoriesKey)]
            public IList<DamCategoryValue> Categories
            {
                get { return _Categories; }
                set { _Categories = value; }
            }


            [JsonProperty (PropertyName = AssetNameKey)]
            public string AssetName
            {
                get { return _AssetName; }
                set { _AssetName = value; }
            }


            [JsonProperty (PropertyName = RecordModificationDateKey)]
            public DateTime? RecordModificationDate
            {
                get { return _RecordModificationDate; }
                set { _RecordModificationDate = value; }
            }


            public override void OnDeserialized ()
            {
                base.OnDeserialized ();
                Status = getStringListFieldValue (StatusKey);
                AssetReferenceWindows = getStringFieldValue (AssetReferenceWindowsKey);
                Rating = getRatingFieldValue (RatingKey);
                RecordName = getStringFieldValue (RecordNameKey);
                AssetReferenceZIP = getStringFieldValue (AssetReferenceZIPKey);
                AssetReference = getBinaryListFieldValue (AssetReferenceKey);
                ImageWidth = getDoubleFieldValue (ImageWidthKey);
                Categories = getCategoriesFieldValue (CategoriesKey);
                AssetName = getStringFieldValue (AssetNameKey);
                RecordModificationDate = getDateTimeFieldValue (RecordModificationDateKey);
            }


            public override void OnSerializing ()
            {
                setStringListFieldValue (StatusKey, Status);
                setStringFieldValue (AssetReferenceWindowsKey, AssetReferenceWindows);
                setRatingFieldValue (RatingKey, Rating);
                setStringFieldValue (RecordNameKey, RecordName);
                setStringFieldValue (AssetReferenceZIPKey, AssetReferenceZIP);
                setBinaryListFieldValue (AssetReferenceKey, AssetReference);
                setDoubleFieldValue (ImageWidthKey, ImageWidth);
                setCategoriesFieldValue (CategoriesKey, Categories);
                setStringFieldValue (AssetNameKey, AssetName);
                setDateTimeFieldValue (RecordModificationDateKey, RecordModificationDate);
                base.OnSerializing ();
            }

            public enum StatusEnum : long
            {
                Approved = 0,
                NeedsApproval = 1,
                Rejected = 2
            }

        }
    }

b) Generate Java wrapper class for the catalog with the alias "mycatalog" and the configured view named "fields":

Example Request

http://cip-server:port/CIP/developer/describe/mycatalog/fields?locale=en&language=java

Example Configuration

    <catalogs>
        ...
        <catalog aliasName="mycatalog">
            <serverAddress>localhost</serverAddress>
            <userName>sample</userName>
            <password>sample</password>
            <catalogName>TestCatalog</catalogName>
        </catalog>
        ...
    </catalogs>

    <views>
        ...
        <view name="fields">
            <field>Record Name</field>
            <field>Record Modification Date</field>
            <field>File Format</field>
            <field>Status</field>
            <field>Caption</field>
            <field>Rating</field>
            <field>Notes</field>
            <field>Categories</field>
            <field>Asset Data Size (Long)</field>
            <field>Asset Modification Date</field>
        </view>
        ...
    </views>

Example Response

package com.canto.cip.client.views;

import java.util.*;

import com.canto.cip.client.DamItem;
import com.canto.cip.client.dam.entities.*;


public class FieldsView extends DamItem
{
	public static final String VIEW_NAME = "fields";


	private static final String RecordNameKey = "Record Name";
	private static final String RecordModificationDateKey = "Record Modification Date";
	private static final String FileFormatKey = "File Format";
	private static final String StatusKey = "Status";
	private static final String CaptionKey = "Caption";
	private static final String RatingKey = "Rating";
	private static final String NotesKey = "Notes";
	private static final String CategoriesKey = "Categories";
	private static final String AssetDataSizeLongKey = "Asset Data Size (Long)";
	private static final String AssetModificationDateKey = "Asset Modification Date";

	private String recordName;
	private Date recordModificationDate;
	private String fileFormat;
	private DamStringListValue status;
	private String caption;
	private DamRatingValue rating;
	private String notes;
	private List<DamCategoryValue> categories;
	private DamDataSizeValue assetDataSizeLong;
	private Date assetModificationDate;



	public String getRecordName ()
	{
		return recordName;
	}

	public void setRecordName (String recordName)
	{
		this.recordName = recordName;
	}



	public Date getRecordModificationDate ()
	{
		return recordModificationDate;
	}

	public void setRecordModificationDate (Date recordModificationDate)
	{
		this.recordModificationDate = recordModificationDate;
	}



	public String getFileFormat ()
	{
		return fileFormat;
	}

	public void setFileFormat (String fileFormat)
	{
		this.fileFormat = fileFormat;
	}



	public DamStringListValue getStatus ()
	{
		return status;
	}

	public void setStatus (DamStringListValue status)
	{
		this.status = status;
	}



	public String getCaption ()
	{
		return caption;
	}

	public void setCaption (String caption)
	{
		this.caption = caption;
	}



	public DamRatingValue getRating ()
	{
		return rating;
	}

	public void setRating (DamRatingValue rating)
	{
		this.rating = rating;
	}



	public String getNotes ()
	{
		return notes;
	}

	public void setNotes (String notes)
	{
		this.notes = notes;
	}



	public List<DamCategoryValue> getCategories ()
	{
		return categories;
	}

	public void setCategories (List<DamCategoryValue> categories)
	{
		this.categories = categories;
	}



	public DamDataSizeValue getAssetDataSizeLong ()
	{
		return assetDataSizeLong;
	}

	public void setAssetDataSizeLong (DamDataSizeValue assetDataSizeLong)
	{
		this.assetDataSizeLong = assetDataSizeLong;
	}



	public Date getAssetModificationDate ()
	{
		return assetModificationDate;
	}

	public void setAssetModificationDate (Date assetModificationDate)
	{
		this.assetModificationDate = assetModificationDate;
	}

	@Override
	public void onDeserialized ()
	{
		super.onDeserialized ();
		recordName = getStringFieldValue (RecordNameKey);
		recordModificationDate = getDateTimeFieldValue (RecordModificationDateKey);
		fileFormat = getStringFieldValue (FileFormatKey);
		status = getStringListFieldValue (StatusKey);
		caption = getStringFieldValue (CaptionKey);
		rating = getRatingFieldValue (RatingKey);
		notes = getStringFieldValue (NotesKey);
		categories = getCategoriesFieldValue (CategoriesKey);
		assetDataSizeLong = getDataSizeFieldValue (AssetDataSizeLongKey);
		assetModificationDate = getDateTimeFieldValue (AssetModificationDateKey);
	}

	@Override
	public void onSerializing ()
	{
		setStringFieldValue (RecordNameKey, recordName);
		setDateTimeFieldValue (RecordModificationDateKey, recordModificationDate);
		setStringFieldValue (FileFormatKey, fileFormat);
		setStringListFieldValue (StatusKey, status);
		setStringFieldValue (CaptionKey, caption);
		setRatingFieldValue (RatingKey, rating);
		setStringFieldValue (NotesKey, notes);
		setCategoriesFieldValue (CategoriesKey, categories);
		setDataSizeFieldValue (AssetDataSizeLongKey, assetDataSizeLong);
		setDateTimeFieldValue (AssetModificationDateKey, assetModificationDate);
		super.onSerializing ();
	}

	public enum StatusEnum
	{
		Approved (0L),
		NeedsApproval (1L),
		Rejected (2L);

		private long id;

		private StatusEnum (long id)
		{
			this.id = id;
		}

		public long getId ()
		{
			return id;
		}
	}

}

2.8. Configuration Service

This service offers operations that retrieve information about the CIP server system configuration.

2.8.1. configuration/getclientconfiguration

Access client custom configuration stored in the CIP configuration

Allowed HTTP methods: GET and POST

Available since: 8.6

Path Parameters

Parameter	Type	Description
`name`	string (required)	The name of the client configuration.

Named Parameters

Parameter Type Description

apiversion

integer (optional)

Available since: 8.6

Supported values:

`2`	CIP 8.6 release
`3`	CIP 8.6.1 release

Result

The result is the configuration of the client.

Examples

a) Get the client configuration for the name com.canto.cumulus.mobile.client:

Example Request

http://cip-server:port/CIP/configuration/getclientconfiguration/com.canto.cumulus.mobile.client

Example Configuration

    <clientConfigurations>
        ...
        <clientConfiguration name="com.canto.cumulus.mobile.client">
            <value name="timeout">3600</value>
            <list name="mydata">
                <value>1234</value>
                <value>647836</value>
                <record>
                    <value name="login">guest</value>
                    <value name="password">guest</value>
                    <record name="Status">
                        <value name="1">approved</value>
                        <value name="2">OK</value>
                        <value name="3">Rejected</value>
                    </record>
                    <value name="port">3333</value>
                    <list name="format">
                        <value>png</value>
                        <value>jpeg</value>
                        <value>gif</value>
                    </list>
                </record>
            </list>
            <list name="assetactions">
                <value>Standard</value>
                <value>Convert</value>
            </list>
            <value name="last">2012.02.20</value>
        </clientConfiguration>
        ...
    </clientConfigurations>

Example Response

{

    "timeout": "3600",
    "mydata": [
        "1234",
        "647836",
        {
            "login": "guest",
            "password": "guest",
            "Status": {
                "1": "approved",
                "2": "OK",
                "3": "Rejected"
            },
            "port": "3333",
            "format": [
                "png",
                "jpeg",
                "gif"
            ]
        }
    ],
    "assetactions": [
        "Standard",
        "Convert"
    ],
    "last": "2012.02.20"

}

2.9. System Information Service

This service offers operations that retrieve information about the CIP server system.

2.9.1. system/getversion

Return the current version of the following service components:

Canto Integration Platform
Server Operating System
DAM System
JAVA Runtime
WEB Server

Allowed HTTP methods: GET and POST

Available since: 8.5.2

Result

The result is the version of the service components.

Examples

a) Get the current version of the CIP server:

Example Request

http://cip-server:port/CIP/system/getversion

Example Response

{
    "version": {
        "cip": {
            "name": "Canto Integration Platform",
            "version": "8.6.1"
        },
        "dam": {
            "name": "Cumulus Java Classes",
            "version": "8.6.1"
        },
        "java": {
            "name": "Java HotSpot(TM) 64-Bit Server VM",
            "version": "1.7.0_09",
            "vendor": "Oracle Corporation"
        },
        "os": {
            "name": "Windows 7",
            "version": "6.1",
            "arch": "amd64"
        },
        "server": {
            "name": "Apache Tomcat/7.0.26",
            "version": "3.0"
        }
    }
}

3. CIP configuration

The CIP server is configured using the /WEB-INF/conf/cip-config.xml file.
You can modify cip-config.xml file with a text editor that is capable of handling UTF-8 encoding correctly.
Changes to the cip-config.xml file are effective within 60 seconds after saving the file.

3.1. Configure the DAM System

The DAM system configuration

3.1.1. Configure the DAM System implementation class

CIP is prepared to support different DAM systems as backends. This configuration defines the Java class that implements such a DAM system.
Cumulus is implemented in the class com.canto.cip.dam.cumulus.CumulusDamSystem

Examples

a) Set the DamSystem implementation class to the cumulus specific implementation:

Example Configuration

<?xml version="1.0" encoding="UTF-8"?>
<config>
    <dam>
        <class>com.canto.cip.dam.cumulus.CumulusDamSystem</class>
    ...
    </dam>
...
</config>

3.1.2. Configure the DAM runtime parameters

Define runtime parameters for the DAM system.
Each parameter is configured inside the <dam> node.
The set of parameters are DAM system dependent.
For the Cumulus implementation following parameters are used to configure the connection pool.
Using a pool with Cumulus requires an additional serial number to be activated at the Cumulus server. Please read the pooling section in the introduction on how to use connection pooling with Cumulus.
You can also specify pool parameters for a specific client product by adding the client product ID in lower case to the parameter name.
An example is given below.

Parameters

Parameter	Type	Description
`com.canto.cumulus.pool.maxsize`	integer (required)	Define maximal pool size. Default : 0 (do not use a pool). Specify a number for the size or "unlimited" to not limit the size of a pool.
`com.canto.cumulus.pool.minsize`	integer (required)	Define minimal pool size. Default : 1
`com.canto.cumulus.pool.maxclonecount`	integer (required)	Define maximal clone count of the pool objects. Default : 10
`com.canto.cumulus.pool.maxtimetolive`	integer (required)	Define maximal inactivity time in seconds. Default : 720

Examples

a) Set the cumulus DAM System pool properties:

Example Configuration

<?xml version="1.0" encoding="UTF-8"?>
<config>
    <dam>
    ...
        <parameter name="com.canto.cumulus.pool.maxsize">5</parameter>
        <parameter name="com.canto.cumulus.pool.minsize">1</parameter>
        <parameter name="com.canto.cumulus.pool.maxclonecount">10</parameter>
        <parameter name="com.canto.cumulus.pool.maxtimetolive">720</parameter>
        <!-- Here is an example that sets the maximum pool size to be used by a client product with the ID 12AC0
             (note that the client product ID is added to the parameter name in lower case) -->
        <parameter name="com.canto.cumulus.pool.maxsize.12ac0">5</parameter>
    </dam>
...
</config>

3.2. Configure catalogs

You can configure the access parameters for one or more catalogs for use with the CIP.
Each configuration gets an alias name which can be specified in many of the CIP operations.
The catalogs can be located on different servers.
Each parameter can be overwritten by specifying a request parameter of the same name.
This allows to have either a completely pre-configured catalog access or to pick some of the parameters from the cionfiguration (e.g. the user name, password, and server address) and specify others (e.g. the catalog name) in each request.
You can configure as many catalogs as you like as long as each has a unique alias name.

3.2.1. Configure a catalog definition

Catalog alias definition

Parameters

Parameter	Type	Description
`aliasName`	string (required)	The alias name of the catalog definition. e.g. `sample` User can define one or more catalogs to easy access it via alias. The location service require catalog with the alias name `com.canto.cip.catalog.serverpermissions` for the permission checking
`serverAddress`	string (optional)	The DAM server IP address. e.g. `localhost, 192.168.0.2`
`userName`	string (optional)	The user name for login to the server. e.g. `cumulus`
`password`	string (optional)	The password for login to the server.
`catalogName`	string (optional)	The catalog name. e.g. `Sample Catalog`

Examples

a) Configure a custom catalog with the alias name sample:

Example Configuration

<?xml version="1.0" encoding="UTF-8"?>
<config>
...
    <catalogs>
    ...
        <catalog aliasName="sample">
            <serverAddress>10.10.0.22</serverAddress>
            <userName>sampleUser</userName>
            <password>samplePassword</password>
            <catalogName>Sample Catalog</catalogName>
        </catalog>
    ...
    </catalogs>
...
</config>

3.3. Configure views

You can configure as many views as you like as long as each has a unique name.
These views are simple lists of fields of catalogs used to determine the fields that an operation returns.
For the Cumulus DAM system it is sometimes preferable to specify the field using the field UID and optionally the field name.
This allows to have a view configuration that is language-independent, so instead of

Status

you specify the field using

{af4b2e07-5f6a-11d2-8f20-0000c0e166dc}:Status

you can also map field to the alias:

aliasForStatus:{af4b2e07-5f6a-11d2-8f20-0000c0e166dc}:Status

```
aliasForStatus:Status
```

The field "Asset Reference" has some sub-fields that you can specify:

Asset Reference/Windows - The Windows file path to the file asset.
Asset Reference/Mac OS - The display string of the Mac OS path to the file asset.
Asset Reference/Unix - The display string of the Unix path to the file asset.
Asset Reference/ZIP - The name of the asset inside the ZIP archive.

Virtual fields (Available since: 8.6.1):

NumberOfAssignedAssets:{50f54d0a-0ebe-46ce-bf3c-dbb744349650}

contains the number of records being assigned to a category

NumberOfAssignedAssetsIncludingSubCategories:{b46eddc9-dc90-4e31-9474-bee1b9a3fd12}

contains the number of records being assigned to a category including its sub-categories

ModifiableFields:{e85fd04a-7e4f-4718-9879-92c0f22ba892}

contains list of names of fields that the current user is allowed to modify

It is also possible to include server view set to the view:

Standard/ReportView

3.3.1. Configure a view definition

Define a view with selected fields

Parameters

Parameter Type Description

name string (required) The alias name of the view definition. e.g. default

field array (optional) To define a view you must select fields for it.

serverviewname

array (optional)

or you can select one of the Record View Sets stored at the Cumulus server and an adequate view, e.g. Standard/InfoView

Standard is the name of the Record View Set
InfoView is the name of a view belonging to that Record View Set

The following views are defined in each Record View Set at the Cumulus server:

`ThumbnailView`	Thumbnail View
`ReportView`	Report View
`DetailsView`	Details View
`InfoView`	Info View
`InfoWindow`	Asset Info Window
`PaletteMode`	Palette Mode
`PreviewWindow`	Preview Window

Examples

a) Define a view with the name "default":

Example Configuration

<?xml version="1.0" encoding="UTF-8"?>
<config>
...
    <views>
    ...
        <view name="default">
            <field>{af4b2e07-5f6a-11d2-8f20-0000c0e166dc}:Status</field>
            <field>{af4b2e16-5f6a-11d2-8f20-0000c0e166dc}:Asset Reference/Windows</field>
            <field>{af4b2e16-5f6a-11d2-8f20-0000c0e166dc}:Asset Reference/ZIP</field>
            <field>{af4b2e00-5f6a-11d2-8f20-0000c0e166dc}:Record Name</field>
            <field>{af4b2e0c-5f6a-11d2-8f20-0000c0e166dc}:Categories</field>
            <field>{af4b2e02-5f6a-11d2-8f20-0000c0e166dc}:Record Modification Date</field>
            <field>{af4b2e69-5f6a-11d2-8f20-0000c0e166dc}:Asset Name</field>
            <field>{af4b2e11-5f6a-11d2-8f20-0000c0e166dc}:Image Width</field>
        </view>
    ...
    </views>
...
</config>

b) Define a view with the name "serverview" based on server view Standard/DetailsView extended by four fields:

Example Configuration

<?xml version="1.0" encoding="UTF-8"?>
<config>
...
    <views>
    ...
        <view name="serverview">
            <serverviewname>Standard/DetailsView</serverviewname>
            <field>Status</field>
            <field>Caption</field>
            <field>Rating</field>
            <field>Notes</field>
        </view>
    ...
    </views>
...
</config>

3.4. Configure queries

You can configure queries that you can then use by using their name in a search operation.
You can configure as many queries as you like as long as each has a unique name.

3.4.1. Configure a query

The configuration of a query can be based on a query string or a named query of the DAM system being used.
For queries based on a query string you can use placeholders in the query string that are later replaced by request parameters of the same name.
Each query configuration must contain either <querystring> or <serverqueryname>.

Parameters

Parameter	Type	Description
`querystring`	string (optional)	Use this instead of `<serverqueryname>` if you want to define the query by specifying a complete query string in the syntax of the DAM system. e.g. `Status == approved` The query string itself can contain named placeholders in the form `${`name`}`. Each placeholder is replaced by the request parameter of the same name, therefore we recommend that placeholder names start with an underscore to avoid conflicts with other named request parameters in the future.
`serverqueryname`	string (optional)	Use this instead of `<querystring>` to base the query on a DAM system predefined query. The name of the predefined query is specified in the body of this element.

Examples

a) Define a query by referencing a DAM system predefined query "MyApprovedQuery":

Example Configuration

<?xml version="1.0" encoding="UTF-8"?>
<config>
...
    <queries>
    ...
        <query name="approvedquery">
            <serverqueryname>MyApprovedQuery</serverqueryname>
        </query>
    ...
    </queries>
...
</config>

b) Define a query by query string:

Example Configuration

<?xml version="1.0" encoding="UTF-8"?>
<config>
...
    <queries>
    ...
        <query name="approvedquery">
            <querystring>Status == approved</querystring>
        </query>
    ...
    </queries>
...
</config>

c) Define a query by query string using placeholders. In this example the two placeholders are named "_status" and "_imagenumber" and are replaced in the metadata/search operation request with parameters of the same name.

Example Configuration

<?xml version="1.0" encoding="UTF-8"?>
<config>
...
    <queries>
    ...
        <query name="parameterquery">
            <querystring>Status == ${_status} && "Record Name" ? "IMG_${_imagenumber}"</querystring>
        </query>
    ...
    </queries>
...
</config>

Example Request

http://cip-server:port/CIP/metadata/search?queryname=parameterquery&_status=approved&_imagenumber=54637

3.5. Configure constraints

You can limit maximum number of items returned by the CIP metadata/search and collection based metadata/getfieldsvalue operations.

3.5.1. Configure the constraint

Constraint definition

Parameters

Parameter Type Description

name

string (required)

The alias name of the constraint definition.
Supported value:

`com.canto.cip.constraint.searchmaxresults`	Limit a maximum number of items returned by the CIP search operations e.g. `1000`
`com.canto.cip.constraint.clientcachemaxage`	Maximum time in seconds to specify age of the cached elements used when the named parameter cachecontrol is set to the "clientdefault" value e.g. `1800`

Examples

a) Configure a constraint with the alias name com.canto.cip.constraint.searchfetchsize for the search and getfieldvalues operations:

Example Configuration

<?xml version="1.0" encoding="UTF-8"?>
<config>
...
    <constraints>
        <constraint name="com.canto.cip.constraint.searchfetchsize">1000</constraint>
    </constraints>
...
</config>

3.6. Configure locations

You can configure several predefined locations and enable url based protocols for using complete URLs for locations.
The benefit in using configured locations is that you can hide credentials in the configuration file.
You can also change pre-configured locations without the need to change client-side applications.
You can configure as many locations as you like as long as each has a unique name.

3.6.1. Enabling url based protocols

In some operations you can specify a location as a URL (e.g. "file://C:/images"). CIP supports the following url protocols:

ftp
sftp
ftps
file

The usage of such URL locations can be disabled by protocol type for higher security. For example you may not want client-side applications to be able to specify file:// URL locations directly. By default all protocols are disabled. You do not need to enable a protocol when using configured locations (see below).

Examples

a) Enable url based protocols for ftp, sftp, ftps, file:

Example Configuration

<?xml version="1.0" encoding="UTF-8"?>
<config>
...
    <locations>
        <enableProtocol>ftp</enableProtocol>
        <enableProtocol>ftps</enableProtocol>
        <enableProtocol>sftp</enableProtocol>
        <enableProtocol>file</enableProtocol>
    ...
    </locations>
...
</config>

3.6.2. Configure a location

You can define one or more preconfigured locations.
By using a configured location and a relative path you can hide details such as FTP passwords from the user of the service.
When executed the location name is replaced with the configured location string.
For example you can define a location called "ftpupload" and then specify a location in a request by using this name as the start of the path: "ftpupload/myfolder/image.jpg".

Parameters

Parameter Type Description

name

string (required)

The alias name of the location definition. e.g. ftpupload
Some names are predefined by CIP and are required for proper operation of the CIP service:

`com.canto.cip.location.previewcache`	The location that is used to store the cached previews for the `preview/image` operation.
`com.canto.cip.location.tempdir`	Temporary directory used for various operations.
`com.canto.cip.location.checkout`	Location to check out assets to.
`com.canto.cip.location.storage`	Default storage location used by the `asset/import` and `asset/update` operations in case the asset is imported into a catalog without a central asset location.

Examples

a) Configure the system locations needed by the CIP service:

Example Configuration

<?xml version="1.0" encoding="UTF-8"?>
<config>
...
    <locations>
...
        <location name="com.canto.cip.location.previewcache">c:/temp/cache/</location>
        <location name="com.canto.cip.location.tempdir">c:/temp/</location>
        <location name="com.canto.cip.location.checkout">c:/test/</location>
        <location name="com.canto.cip.location.storage">c:/test/storage/</location>
...
    </locations>
...
</config>

b) Define custom user location with aliases ftpsupload, ftpupload, and localdownloads:

Example Configuration

<?xml version="1.0" encoding="UTF-8"?>
<config>
...
    <locations>
    ...
        <location name="ftpsupload">ftps://test:testtest@localhost/ftps_uploads</location>
        <location name="ftpupload">ftp://test:testtest@ftpserver/ftp_uploads</location>
        <location name="localdownloads">c:/temp/localdownloads/</location>
    ...
    </locations>
...
</config>

3.7. Option Sets

Option sets contain options for the DAM system or CIP. Each option set contains one or more named options that affect the operations.
Typical options include asset handling options, asset conversion options, etc. You can define one or more named option sets depending on your requirements.
The name of the set is specified in some of the operation request (e.g. asset/import) to select the options to be used. You can configure as many option sets as you like as long as each has a unique name.

3.7.1. Configure an option set

An option set is a list of options given by name and value.
All options for the Cumulus DAM system have names that start with "com.canto.cumulus."
An operation may use only one of the options of a set. It is up to you whether you want to bundle several options under a given name or define separate option sets for each option.

Parameters

Parameter Type Description

name string (required) The name of this option set.

option

string (required)

A single option that contains a name and a value. The exact option names and possible values are DAM system dependent.
This documentation contains the predefined options that are used by the Cumulus DAM system:

`com.canto.cumulus.assethandlingset`	The name of a Cumulus Asset Handling Set to be used for the operation. An Asset Handling Set affects how Cumulus deals with your assets – during the cataloging process and when accessing assets. Please read the Cumulus documentation about how to modify an Asset Handling Set.
`com.canto.cumulus.assetaction`	The name of a Cumulus Asset Action to be applied in the operation. An Asset Action defines how assets are converted or processed. Please read the Cumulus documentation about how to set up an Asset Action.
`com.canto.cumulus.permissiontemplate`	The name of a Cumulus Permission Template to be used for the operation. Permissions templates enable you to assign, remove or explicitly set individual asset or category permissions for users or entire groups at once. Please read the Cumulus documentation about how to set up a Permission Template.

Examples

a) Configure an option set that specifies to use the Cumulus Asset Handling Set "Standard" and the Asset Action "Convert and Compress":

Example Configuration

<?xml version="1.0" encoding="UTF-8"?>
<config>
...
    <optionsets>
    ...
        <optionset name="myoptions">
            <option name="com.canto.cumulus.assethandlingset">Standard</option>
            <option name="com.canto.cumulus.assetaction">Convert and Compress</option>
        </optionset>
    ...
    </optionsets>
...
</config>

3.8. Previews

When generating a preview using the preview/image operation you can either specify all parameters in the request or specify a preview configuration name.
In the configuration file you can define several previews and specify which parameters should be used for this kind of preview.
You can configure as many previews as you like as long as each has a unique name.

3.8.1. Configure a preview

A preview with specific parameters.

Parameters

Parameter	Type	Description
`name`	string (required)	The name of this preview configuration.
`option`	string (required)	A single option that contains a name and a value. Specify one of the following preview parameters as the option name: left top width height maxsize size rotate format quality usecache Please read the documentation of the `preview/image` operation for details about these parameters and their values.

Examples

a) Configure a small preview that returns a JPEG image of max. 100 pixels:

Example Configuration

<?xml version="1.0" encoding="UTF-8"?>
<config>
...
    <previews>
    ...
        <preview name="small">
            <option name="maxsize">100</option>
            <option name="format">jpeg</option>
            <option name="quality">4</option>
        </preview>
    ...
    </previews>
...
</config>

3.9. Configure fallback information

You can define a static fallback image for use with the CIP preview/image operation that is delivered in case of error.
It will be returned to the client instead of an error message.

3.9.1. Configure the fallback image

Fallback image definition

Parameters

Parameter Type Description

name

string (required)

The alias name of the fallback definition.
Supported value:

image used by the preview operations e.g. /pictures/FallbackImage.png

Examples

a) Configure a fallback with the alias name image for the preview operations:

Example Configuration

<?xml version="1.0" encoding="UTF-8"?>
<config>
...
    <fallbacks>
        <fallback name="image">/pictures/FallbackImage.png</fallback>
    </fallbacks>
...
</config>

3.10. Configure cache

Configure the preview cache.

3.10.1. Configure a cache auto purge

Cache auto purge configuration. A background task automatically purges the oldest entries in the cache if a certain limit size is exceeded. The automatic purging stops as soon as the total cache size is below the target size.

Parameters

Parameter Type Description

purgeEnabled

string (required)

Determine whether this service is enabled or not.
Possible values:

`true`	enabled
`false`	disabled

purgeInterval string (required) The interval in seconds between purge cache check e.g. 600 (10 minutes)

targetSize

string (required)

The target cache size reached after a run of an automatic purging. It must be less then purgeThreshold. An integer value with the optional unit descriptor.
The unit descriptor can one of the:

`K`	Kilobytes e.g. 12K (12 KB)
`M`	Megabytes e.g. 100M (100 MB)
`G`	Gigabytes e.g. 40G (40 GB)
`T`	Terabytes e.g. 2T (2 TB)
	If no unit descriptor was provided the value will be interpreted as bytes.

limitSize

string (required)

The cache size that triggers an automatic purging of the cache. This value must be greater then targetSize An integer value with the optional unit descriptor.
The unit descriptor can one of the:

`K`	Kilobytes e.g. 12K (12 KB)
`M`	Megabytes e.g. 100M (100 MB)
`G`	Gigabytes e.g. 40G (40 GB)
`T`	Terabytes e.g. 2T (2 TB)
	If no unit descriptor was provided the value will be interpreted as bytes.

Examples

a) Configure a purge cache:

Example Configuration

<?xml version="1.0" encoding="UTF-8"?>
<config>
...
    <cache>
        <purgeEnabled>true</purgeEnabled>
        <purgeInterval>600</purgeInterval>
        <targetSize>768M</targetSize>
        <limitSize>1G</limitSize>
    </cache>
...
</config>

3.11. Custom Client Configurations

You can store configuration data for your CIP client application code within the CIP server's configuration file. Each client configuration has a unique name and can be retrieved by the client using the "configuration/getclientconfiguration" operation.
The client configuration data consists of named values. Each value can itself be a string, a list of values or a record of named values. This allows you to give your configuration data almost any custom structure.

3.11.1. Sample client configurations

The following examples show how you can structure your client configuration data.
A more complex example can be found in the "configuration/getclientconfiguration" operation (click the "Get a client configuration" link below).

Examples

a) A client configuration with the name com.canto.cumulus.client.sample.1. It only conains three values named "timeout", "address", and "max."

Example Configuration

<?xml version="1.0" encoding="UTF-8"?>
<config>
    ...
    <clientConfigurations>
        ...
        <clientConfiguration name="com.canto.cumulus.client.sample.1">
            <value name="timeout">3600</value>
            <value name="address">192.168.0.1</value>
            <value name="max">32</value>
        </clientConfiguration>
    </clientConfigurations>
...
</config>

Example Request

http://cip-server:port/CIP/configuration/getclientconfiguration/com.canto.cumulus.client.sample.1

Example Response

{

    "timeout": "3600",
    "address": "192.168.0.1",
    "max": "32"

}

b) A client configuration with the name com.canto.cumulus.client.sample.2. It only conains two values named "timeout" and "regions" where the value of "regions" is itself a list of values.

Example Configuration

<?xml version="1.0" encoding="UTF-8"?>
<config>
    ...
    <clientConfigurations>
        ...
        <clientConfiguration name="com.canto.cumulus.client.sample.2">
            <value name="timeout">3600</value>
            <list name="regions">
                <value>America</value>
                <value>Europe</value>
                <value>Asia</value>
            </list>
        </clientConfiguration>
    </clientConfigurations>
...
</config>

Example Request

http://cip-server:port/CIP/configuration/getclientconfiguration/com.canto.cumulus.client.sample.2

Example Response

{
    "timeout": "3600",
    "regions": [
        "America",
        "Europe",
        "Asia"
    ]
}

c) A client configuration with the name com.canto.cumulus.client.sample.3. It only conains two values named "timeout" and "regions" where the value of "regions" is itself a record of named values with each value being a numbe.

Example Configuration

<?xml version="1.0" encoding="UTF-8"?>
<config>
    ...
    <clientConfigurations>
        ...
        <clientConfiguration name="com.canto.cumulus.client.sample.3">
            <value name="timeout">3600</value>
            <record name="regions">
                <value name="America">52382</value>
                <value name="Europe">23623745</value>
                <value name="Asia">5373</value>
            </record>
        </clientConfiguration>
    </clientConfigurations>
...
</config>

Example Request

http://cip-server:port/CIP/configuration/getclientconfiguration/com.canto.cumulus.client.sample.3

Example Response

{
    "timeout": "3600",
    "regions": {
        "America": "52382",
        "Europe": "23623745",
        "Asia": "5373"
    }
}

Allowed HTTP methods:	GET and POST
Available since:	8.5.2

Table of contents

1. Introduction

1.1. Pre-Requisites

1.2. Secure Communication (Optional)

1.3. Authentication (Optional)

1.4. Session Handling (Optional)

1.5. Priority of Catalog Access Parameters

Examples

1.6. Data Model of a DAM System

1.7. Using Connection Pooling with the Cumulus DAM system

Examples

2. Services and Operations

Named Parameters

Result

See also:

Examples

Named Parameters

Result

See also:

Examples

Named Parameters

Result

See also:

Examples

Path Parameters

Named Parameters

Result

See also:

Examples

Path Parameters

Named Parameters

Result

See also:

Examples

Path Parameters

Named Parameters

Result

See also:

Examples

Named Parameters

Result

See also:

Examples

Named Parameters

Result

See also:

Examples

Path Parameters

Named Parameters

Result

See also:

Examples

Path Parameters

Named Parameters

Result

See also:

Examples

Path Parameters

Named Parameters

Result

See also:

Examples

Path Parameters

Named Parameters

Result

See also:

Examples

Path Parameters

Named Parameters

Result

See also:

Examples

Path Parameters

Named Parameters

Result

See also:

Examples

Path Parameters

Named Parameters

Result