 | Beta Feature The pimcore SOAP feature still has a Beta-Status, it is currently being tested and still subject to changes |
Pimcore provides a web service to retrieve and save objects, documents and assets through a SOAP API. When the web service feature is enabled in the system settings (by default it is disabled), any admin user can access and utilize the SOAP API.
Once the web service feature has been enabled, the WSDL can be accessed through the following URL. It describes the services methods and data types.
When the web service API is enabled, for each admin user his API key is displayed in Settings > Users. Please be aware that the API Key changes when the user changes his/her password.
The API key mentioned above, also needs to be provided with each SOAP call. The following code snippet shows how a Zend_Soap_Client would be set up.
$client = new Zend_Soap_Client("http://YOUR.DOMAIN/webservice/soap/endpoint/apikey/" . $apikey . "/?wsdl", array( "cache_wsdl" => false, "soap_version" => SOAP_1_2, "classmap" => Webservice_Tool::createClassMappings() ));
 | SOAP Basics All Code Snippets and examples provided in this documentation assume the usage and a basic knowledge of the Zend_Soap library. For basics please refer to the Zend Framework Documentation about SOAP calls. Or the manual of the SOAP library / programming language of your choice. |
Available Methods
The following methods are available for web service calls:
Retrieve Data:
- getAssetFileById
- getAssetFolderById
- getAssetList
- getDocumentFolderById
- getDocumentLinkById
- getDocumentList
- getDocumentPageById
- getDocumentSnippetById
- getObjectConcreteById
- getObjectFolderById
- getObjectList
Update:
- updateAssetFile
- updateAssetFolder
- updateDocumentFolder
- updateDocumentLink
- updateDocumentPage
- updateDocumentSnippet
- updateObjectConcrete
- updateObjectFolder
Create:
- createAssetFile
- createAssetFolder
- createDocumentFolder
- createDocumentLink
- createDocumentPage
- createDocumentSnippet
- createObjectConcrete
- createObjectFolder
Delete:
- deleteAsset
- deleteDocument
- deleteObject
The WSDL documentation can be found here.
Example Usage
The next snippet shows an example how to retrieve a list of objects through the SOAP API:
$condition = "o_type='object'";
$order = "";
$orderKey = "";
$offset = 0;
$limit = 10;
$groupBy = "";
$wsObjectList = $client->getObjectList($condition, $order, $orderKey, $offset, $limit, $groupBy);
This returns a webservice object list. All data types which are used as arguments and return values are fully described in the according WSDL. It is advised to provide a classmap when setting up the SOAP Client. This makes the mapping and handling of data much easier, but it is not necessary.
To retrieve the first object in this list, the following consecutive call could be made:
$id = $wsObjectList[0]->id; $wsObject = $client->getObjectConcreteById($id);
If the SOAP API is used in a pimcore to pimcore context, and both pimcore instances dispose of the same object classes, it is fairly easy to map the returned $wsObject back to a pimcore object.
$className = "Object_" . ucfirst($wsObject->className); $object = new $className(); $wsObject->reverseMap($object);
As the following snippet shows, in return it is also possible to save data through the SOAP API.
// myPimcoreObject is a pimcore object of the local pimcore instance $apiObject = Webservice_Data_Mapper::map($myPimcoreObject, "Webservice_Data_Object_Concrete_In", "in"); $id = $client->createObjectConcrete($apiObject);
In case the SOAP API is not used in a pimcore to pimcore context, the web service data classes have to be created and filled individually.
What if I don't want to send data from pimcore to pimcore, but still use SOAP access?
Of course, the SOAP API is not restricted to pimcore to pimcore usage. The SOAP client can be developed in any programming language, supported by any framework of the programmer's choice. As long as both parties stick to SOAP standards and adhere to the defintions of the underlying WSDL. All request and response objects are described in the WSDL and they can be formed by clients other than a pimcore instance.
For the sake of simplicity this documentation asumes pimcore to pimcore communication so that the code samples stay short and readable. However, developing a SOAP client outside of a pimcore context, requires basic SOAP knowledge and a profound knowledge of the pimcore internal data classes, Assets, Documents with their Document_Tag elements, Objects with their Object_Class_Data elements, Properties, and how those elements can be related to each other.