Help Center

Menu

SOAP server

The SOAP server asset lets you execute core-level Matrix functions using Simple Object Access Protocol (SOAP). This level of access lets third-party applications create, modify and retrieve content within the system. These functions are handled by several API assets linked and managed under the SOAP server. By adding only the assets you need, you can scope API system access based on what role you need it to do in your site.

Configure a SOAP API on your site

Create a SOAP API server that controls access to various endpoints that you explicitly enable or disable.

The basic steps to add a SOAP server are described in the following steps.

To add a SOAP server:

  1. Locate an area in your asset tree that is accessible through a URL.

  2. In the asset menu, select Add  Web services  SOAP server.

  3. Give the API a meaningful name and select Create.

  4. Select Edit to load the Details screen.

To make a SOAP server available for use:

  1. Configure the API endpoint assets you need as described in the endpoint documentation.

  2. On the SOAP server asset’s Details screen, select Enabled beside each API endpoint asset you want to use in your API.

  3. In the Change status field, select Live and then select Save to make the SOAP server and the enabled API endpoints available for use.

You can configure the settings of the SOAP server on its associated asset screens. The majority of these screens are similar to a standard page. They are described in the Asset screens documentation.

This documentation will describe the Details screen, which is different for a SOAP server.

HTTP authentication

Matrix’s SOAP server uses HTTP basic authentication to communicate with external systems.

Read the HTTP authentication with PHP documentation for more information on HTTP authentication.

This authentication type requires a username and password to be passed for each request. The username and password details must originate from a Matrix user account with appropriate permissions for all API endpoints operations configured in the SOAP API.

Matrix user accounts must have a minimum of read access to utilize the read operations available from the SOAP server. Depending on the request scope, read-write permissions may be required. Check the endpoint documentation for specific user account access levels required for operations.

Details screen

The Details screen lets you select the SOAP API endpoints used in the SOAP server.

Read the Asset screens documentation for more information about the Status, Future status, Thumbnail, and Details sections.

The API section of the Details screen allows you to select the APIs available on the SOAP server and manage the server’s Web Service Description Language (WSDL). API assets must be created as children of the SOAP server for the fields in this section to be available.

The fields available in this section are as follows:

APIs available to this service

Select an API to make it available for use on the SOAP server. If enable is selected for an API asset, the functions selected on the API asset’s Details screen will be available on the SOAP server.

Namespace

Define a static namespace to be used in the SOAP server’s response.

Regenerate WSDL

Select this field to regenerate the SOAP server’s Web Service Description Language (WSDL) XML file to reflect any new changes made to the server, such as an enabled API asset.
The WSDL for the SOAP server displays the operation parameters available for the functions enabled on the SOAP server. The WSDL of a SOAP server can be viewed by appending ?WSDL to the URL of the server. For example:

http://system_root_url/_web_services/SOAP-server?WSDL
If you want to run SOAP functions over a secure connection, you must generate the SOAP WSDL file over HTTPS.
Otherwise, the WSDL file will be incompatible with your SOAP function calls.