SOAP API
Simple Object Access Protocol (SOAP) is a simple XML-based messaging protocol used to let applications exchange information over HTTP. In SuperOffice we can access the web services using WCF-based SOAP requests and responses.
Earlier versions of NetServer (ca. 7.0) used versioning to ensure that an applications targeting a specific API version would continue to work without issue til the end of time.
As newer versions came out, each one needed a complete set of mapping strategies for older versions. It just became a lot of technical debt. Around 2020 SuperOffice decided to discard all versions older than Services84, with the introduction access token support.
NetServer service API's only add functionality, so anyone transitioning from older versions would have minimal changes, depending on their choice of tooling, code generation and proxies.
Today we support the following versioned services:
Note
The above services do not contain SuperOffice Customer Service SOAP APIs (customer, admin, and ticket).
Those services are part of the Customer Service FastCGI modules and not part of NetServer web services. NetServer web services includes most of the same functionality, and will continue to evolve for 100% coverage.
WSDL files for all versioned endpoints are available for download in the reference section, or as individual files on each endpoint reference page.
Download All:
Download Single:
SOAP web service architecture
NetServer SOAP web services are built using Microsoft Windows Communication Foundation (WCF), and implement the Service Agent pattern.
Each agent represents one area, or entity, of SuperOffice. For example, to manage Appointments use service agent Appointment.svc. The .svc extension is specific to WCF hosted services.
The complete URL, assuming the target version is services88, is:
http://www.your-superoffice.com/remote/services88/appointment.svc
In SuperOffice Online, that would be:
http://{env}.superoffice.com/Cust12345/remote/services88/appointment.svc
Service agent and carrier pattern
All services are called through an agent that is designed to handle a specific business area.
An agent has a set of methods, typically for inserting, retrieving, updating, and deleting data. Each method on the agent corresponds to one HTTP request.
Depending on your development platform of choice, the following code snippets represent the interactions using SuperOffice NetServer .NET proxy. This may or not be similar to a proxy generated using Java toolkit or PHP, but is close enough to convey the concepts.
The following code segment shows how to create an AppointmentAgent. Once the agent has been created, we can use it to access the different methods exposed by the agent.
AppointmentAgent newConAgt = new AppointmentAgent();
The Appointment.svc endpoint, for example, has a list of methods that facilitate data transfer of Data Transfer Objects (DTOs). SuperOffice calls DTOs Carriers.
A Carrier is the data structure that represents data sent between the client [proxy] and Agent services. In an attempt to reduce the amount of XML send on the network, there are two kinds of carriers: lightweight carriers and entity carriers. The primary difference is that lightweight carriers are read-only, and only entity carriers are used to create or update entities in the database.
Read-only carriers
The read-only carrier is a lightweight DTO. It exposes its properties primarily as string values, or integer ID values correlating to the ID field in the corresponding table.
The advantage of a lightweight carrier is its simplicity, avoiding the overhead that comes with larger, more complex, entities classes.
Below is an example that shows how to load a read-only carrier using an Agent.
using SuperOffice.CRM.Services;
ContactAgent contactAgent = new ContactAgent();
Contact myContact = contactAgent.GetContact(4);
string myContactName = myContact.Name;
string myContactCategory = myContact.CategoryName;
string myContactWebUrl = myContact.URL;
Here, the ContactAgent will return a Contact instance through the GetContact method, then read a few of it's properties.
ContactAgent does not have a SaveContact(Contact) method, and therefore no changes to this DTO can be persisted - is it read-only.
Entity carriers
An entity carrier, unlike read-only carriers, expose their properties as more complex structures. For example, the PersonEntity.Contact contains all relational information about the corresponding contact - including name, address, contact ID, phone collection, and more.
The example below demonstrates how to retrieve a ContactEntity instance using the ContactAgent.GetContactEntity method.
using SuperOffice.CRM.Services;
ContactAgent contactAgent = new ContactAgent();
ContactEntity myContact = contactAgent.GetContactEntity(4);
string myContactName = myContact.Name;
string myContactCategory = myContact.Category.Value;
string myContactWebUrl = myContact.Urls.Length > 0 ? myContact.Urls[0].Value : "";
To summarize: an agent represents the service and the carrier represent the data passed between the client and the service. Agents are used to execute actions by calling methods.
Entity carriers resemble NetServer Core Entities. In contrast, lightweight carriers are more similar to NetServer Core Rows.
Example requests
Example SOAP request
This example demonstrates how to get a sent a GetContact request to the ContactAgent service.
<!--
POST https://www.your-superoffice.com/remote/services88/contact.svc
Content-Type: 'text/xml;charset=UTF-8',
Accept: 'text/xml;charset=UTF-8',
SOAPAction: 'http://www.superoffice.net/ws/crm/NetServer/Services88/Contact/GetContact'
-->
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://www.w3.org/2003/05/soap-envelope"
xmlns:SOAP-ENC="http://www.w3.org/2003/05/soap-encoding"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:NetServerServices882="http://schemas.microsoft.com/2003/10/Serialization/Arrays"
xmlns:NetServerServices881="http://schemas.microsoft.com/2003/10/Serialization/"
xmlns:Contact="http://www.superoffice.net/ws/crm/NetServer/Services88">
<Contact:ApplicationToken>1234567-1234-9876</Contact:ApplicationToken>
<Contact:Credentials>
<Contact:Ticket>7T:1234abcxyzExample==</Contact:Ticket>
</Contact:Credentials>
<SOAP-ENV:Body>
<Contact:GetContact>
<Contact:ContactId xsi:type="xsd:int">0</Contact:ContactId>
</Contact:GetContact>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example ContactAgent.ContactEntity
This example demonstrates how to get a ContactEntity using the ContactAgent, using the .NET SuperOffice.NetServer.Services nuget package.
using SuperOffice;
using SuperOffice.CRM.Services;
using(SoSession newSession = SoSession.Authenticate("sam", "sam"))
{
//Instantiate agent
using(ContactAgent myContactAgent = new ContactAgent())
{
//Retrieve a ContactEntity carrier
ContactEntity myContactEntity = myContactAgent.GetContactEntity(5);
//Retrieve values of the carrier properties
string conName = myContactEntity.Name;
string conDept = myContactEntity.Department;
}
}
Note
The ContactAgent class provides methods such as GetAddress, GetAddressByCountry, GetContact, DeleteContactEntity, and many more.
Warning
SuperOffice SOAP web services are not at the center of the API focal point any longer. Instead, focus has shifted towards REST web services. Therefore, it's recommended that all who wish to continue using Service Agent pattern switch to using the SuperOffice.WebApi library. It has the exact same Agent/Carrier/Methods, but uses the Agent REST API.