Assets Server SOAP API - import – Home

Note: The Assets Server SOAP Web service has been deprecated. It remains available and fully supported for on-premise or privately hosted installations so that existing third-party applications or integrations can stay compatible with newer Assets Server versions. Because the SOAP Web service is not available for the cloud version of WoodWing Assets, we advise to use the REST API for any new developments.

Below are example requests and responses to import content and create relations.

Note: The wrapping SOAP envelope and authentication header have been omitted to make the samples easier to read. Detailed documentation about each of the elements and their possible values is provided in the WSDL.

Import request body

Import content and manage relations between newly imported assets and/or existing assets.

<e:importRequest
    xmlns:e="http://www.dutchsoftware.com/xmlns/elvis/webservice/1.0">
    <i:importInstruction
        xmlns:i="http://www.dutchsoftware.com/xmlns/elvis/import/1.0"
        xmlns:q="http://www.dutchsoftware.com/xmlns/elvis/query/1.0">
        <i:saveAsset localId="1">
            <i:identification>
                <i:field name="sceId">
                    <i:value>34</i:value>
                </i:field>
            </i:identification>
            <i:metadata>
                <i:field name="assetPath">
                    <i:value>/Zone A/Publications/Daily News.scePublication</i:value>
                </i:field>
                ...
            </i:metadata>
        </i:saveAsset>
        <i:saveAsset localId="2">
            <i:identification>
                <i:field name="sceId">
                    <i:value>74</i:value>
                </i:field>
            </i:identification>
            <i:metadata>
                <i:field name="assetPath">
                    <i:value>/Zone A/Publications/Daily News/
                             Issue 2008-007.sceIssue</i:value>
                </i:field>
                ...
            </i:metadata>
            <i:relations>
                <i:relation type="contained-by">
                    <i:localAssetRef localId="1"/>
                </i:relation>
            </i:relations>
        </i:saveAsset>
        <i:saveAsset localId="3">
            <i:file>
                <i:includeRef>cid:H34G-5L2K3KH52-3KHJ-G3254KL4</i:includeRef>
            </i:file>
            <i:identification>
                <i:field name="sceId">
                    <i:value/>
                </i:field>
            </i:identification>
            <i:metadata>
                <i:field name="">
                    <i:value/>
                </i:field>
            </i:metadata>
            <i:relations>
                <i:relation type="contained-by">
                    <i:localAssetRef localId="2"/>
                </i:relation>
                <i:relation type="related">
                    <i:query>
                        ...
                    </i:query>
                </i:relation>
                <i:relation type="contains">
                    <i:metadata>
                        <!-- metadata for relation, 
                             for example 'rating' -->
                    </i:metadata>
                    <i:saveAsset>
                        <i:metadata>
                            <!-- metadata for asset -->
                        </i:metadata>
                    </i:saveAsset>
                </i:relation>
            </i:relations>
        </i:saveAsset>
        <i:saveAsset>
            <i:file>
                <i:fileRef
                    path="\\some-server\share-or-path\that-is\accessible-from\elvis-server.jpg"
                />
            </i:file>
            <i:identification/>
            <i:metadata>
                <i:field name="assetPath">
                   <i:value>/Zone A/Publications/elvis-server.jpg</i:value>
                </i:field>
            </i:metadata>
        </i:saveAsset>
    </i:importInstruction>
</e:importRequest>

saveAsset element

The saveAsset element makes it possible to create or update an asset. The system will try to find an existing asset to update using the identification element (when specified). When no existing asset is found or when no identification element is specified, a new asset is created.

<i:saveAsset>
    <i:file></i:file>
    <i:identification></i:identification>
    <i:metadata></i:metadata>
    <i:relations></i:relations>
</i:saveAsset>

The localId attribute on the saveAsset element is only used within the importInstruction to be able to create relations between separately defined assets. This element can also be used to identify asset-results returned by the import process, if unspecified it's harder to identify asset-results.

All sub-elements are optional in the schema, however the following rules apply:

You can specify a file for the asset by adding a file element referencing an attachment, or a file on a server-accessible filesystem. When no file is specified and you are trying to create a new asset, an empty file (0 Kb) will be placed in the storage engine to reserve the location. When updating an asset with a specified file, the file is overwritten (its file metadata will be extracted and updated as well). When you don't specify a file while updating, the original file remains untouched.
When you want to create a new asset certain metadata is required. It is needed to determine where the file will be stored in Assets Server.
The identification element determines whether to update or create the asset. When it is present it is used to find an existing asset. If found, the other elements will be used to update its file, metadata and relations. When no asset with the given identification is found, behavior depends on how the identification element is set up.

file element

The file elements specifies a reference to the asset file to be added or updated in the system. Two variants are available. The first references a webservice attachment. This element is only valid when adding files through the webservice as attachment.

<i:file>
    <i:includeRef>cid:H34G-5L2K3KH52-3KHJ-G3254KL4</i:includeRef>
</i:file>

The second variant references a file on the filesystem (outside the filestore). The file must be accessible from the server. You can specify whether the file should be deleted after importing it (default: false). The file will only be deleted if the import succeeds and the server has enough rights to delete the file.

<i:file>
    <i:fileRef path="\\some-server\share-or-path\
                    that-is\accessible-from\elvis-server.jpg"
                deleteAfterImport="true|false"/>
</i:file>

When you omit the file element, a placeholder asset will be created. This can also be used to create virtual assets like collections.

identification element

The identification element specifies one or more metadata fields used to identify and update an existing asset in the system. When no assets are found matching the identification, by default a new asset will be created including the metadata used for identification. This behavior can be influenced with the notFound attribute.

<i:identification notFound="CREATE|WARNING|ERROR">
    <i:field name="sceId">
        <i:value>...</i:value>
    </i:field>
</i:identification>

Any metadata field in Assets Server can be used for identification, including custom fields.

Note: When using the Assets Server 'id' field the actual value will not be used when no asset is found (and a new asset has to be created). In this case the system will generate a new unique id.

The identification element is not required, it can be omitted when creating a new asset that does not have a unique identification in an external system. Not specifying an 'external' id makes it harder to update the asset later on.

metadata element

The metadata element makes it possible to specify additional metadata to be added to the file.

relations elements

The relations element specifies relations to be created with other assets. These can be assets defined in the same import XML or assets already in the system.

The type of the relation depends on the direction and the kind of relation you wish to specify. For example:

contains
parent to child relation, asset contained or referenced by relation is the child
contained-by
child to parent relation, reverse of contains
related
generic non-directional relation

There are three ways in which a relation can reference another asset.

Reference an asset defined in the same import instruction using its localId:

<i:relation type="contained-by">
    <!-- reference another save-asset element in this file by its local-id -->
    <i:localAssetRef localId="2"/>
</i:relation>

Query Assets Server for existing assets to create a relation with:

<i:relation type="related">
    <i:query>
        ...
    </i:query>
</i:relation>

Embed an asset to be created. This is useful for creating assets from 'hierarchical' structures when generating the import instruction from an XSLT.

<i:relation type="contains">
    <i:saveAsset>
        ...
    </i:saveAsset>
</i:relation>

Import response body

The following is an example of an import response message. This message is returned after an import. It specifies the assets added, including their id and assetPath. It also specifies possible errors or warnings that occurred during the import.