The SOAP Interface

Table of Contents

The SOAP Interface

Introduction

SOAP is a part of the CRM-service’s open Web Service interfaces. This document provides a technical overview to developers for integrating third party applications with CRM-service.

The latest specifications and service descriptions are available in our online documentation:

https://<Your CRM-service-url>/CrmIntegrationWebservice/

If you are not familiar with SOAP based Web Services it might be useful to read some background information about it. There is a very brief description about SOAP and WSDL below as well.

What is SOAP?
SOAP (Simple Object Access Protocol) is a standard protocol for Web Services to exchange structured information over the internet.

What is WSDL?
In a SOAP based Web Service, the service is described in WSDL (Web Service Description Language) documents. WSDL is a XML based language which simply describes all the functionalities and structures of specific Web Service. WSDL document describes how the service can be called, what parameters it expects, and what data structures it returns.

What is an API key?
An API key is unique key to grant access to CIWS web services. Each API key can have their own set of allowed web services to use.

Prerequisites
It’s recommended to generate proxy classes based on the WSDL definition. Most modern IDEs do this automatically. In the examples below the classes and data objects are generated with the free wsdl2php-script (http://www.urdalen.no/wsdl2php/). Please note that there are many other applications as well and you are free to use the application you prefer.

CRM Integration Web Services

In order to use CRM Integration Web Services you need a valid API key.

All the examples below are written in PHP. However, you can use the Web Service API with any programming language.

Image 1: Authentication with Web Service is done using a unique API key when Web Service returns session instance. The session can then be used to authenticate the rest of your web service requests.

Create your session
To get going, you have to first create a session to authenticate your requests.

//sessionManager is a proxy class generated using wsdl2php

 require("PATH_TO_YOUR_LIBRARY_FILES/sessionManager.php");$apiKey = YOUR_UNIQUE_API_KEY;//creating session

 $sessionManager = new sessionManager();try {
 $session = $sessionManager->createSession($apiKey);
 catch(Exception $e) {
 //do some exception handling
 }

Code Example 1: Creating a session variable.

After you have created the session, you are ready to use the wanted Web Services. For the full list of available methods, please check the online documentation.

Important – If something goes wrong, the Web Service will return a SOAP fault exception. It’s always important to handle exceptions of your Web Service requests. Many programming languages, like the native PHP SOAP client, raise these as exceptions.

Use the API – Authenticate your customers with Web Service API
The API provides simple method to authenticate your customers to any third party application. Authentication can be made with Contact Manager service. Every contact can be set as a portal user from CRM.

require("PATH_TO_YOUR_LIBRARY_FILES/sessionManager.php");
require("PATH_TO_YOUR_LIBRARY_FILES/contactManager.php");$contactManager = new contactManager();$login = new PortalUserLoginDetails();

 $login->email = $email_address;
 $login->password = $password;
 $login->portal_id = $portal_id; //id for specific portal
 //there can be multiple portals in CRM and every contact is not involved
 //automatically to every portal. portal_id parameter defines the portal we are
 //authenticating to. Contacts and portals can be managed in CRM.

 try {
 $user = $contactManager->authenticatePortalUser($session, $login);
 } catch(Exception $e) {
 //Authentication failed. Handle exception for example by showing error page.
}

Code Example 2: Authenticating CRM portal users (contacts) with the Web Service API.

Portal User authentication is made by Contact Manager, so first we have to create contactManager object. Login information is passed to contactManager with PortalUserLoginDetails object, so we create a one as well. It needs three parameters: email, password and portal id. Portal id is unique ID for portal we are trying to authenticate with. There can be several portals in the same CRM so we have to define, which portal we are trying to authenticate with. Contact has to be active portal user in that specific portal for the authentication to succeed.

Finally we can call contactManager’s authenticatePortalUser-method for authentication. If authentication was successful an authenticatedCustomer object is returned, otherwise an expectation is raised.

Another Example – Create Sales Order
In the example below we create a new sales order using CRM-service’s Web Service API.

require("PATH_TO_YOUR_LIBRARY_FILES/sessionManager.php");
require("PATH_TO_YOUR_LIBRARY_FILES/salesOrderManager.php");
require(“PATH_TO_YOUR_LIBRARY_FILES/accountManager.php”);//… create session as in the previous example …//We only know the product number, so let’s find the product ID from the Web Service.

 $productManager = new ProductManager();//We need a productSearchCriteria-object for our product search
 $productSearchCriteria = new ProductSearchCriteria();
 $productSearchCriteria->field = "product_no";
 $productSearchCriteria->value = "PRO2124";
 $productSearchCriteria->limit = 1;
 $productSearchCriteria->offset = 0;$products = null;try {
 $products = $productManager -> searchProducts($session,
 $productSearchCriteria);
 } catch (Exception $e) {
 //handle exceptions
 }

 $product = $products[0];

 //let’s create the sales order
 $salesOrderManager = new salesorderManager();
 $salesOrder = new SalesOrder();
 $salesOrder->account_id = 10000; // ID of Account
 $salesOrder->assigned_user_id = 1; //ID of Assigned User
 $salesOrder->bill_city = "Helsinki"
 $salesOrder->bill_code = "00100"
 $salesOrder->bill_country = "Finland";
 $salesOrder->bill_street = "Mannerheimintie 55";
 $salesOrder->contact_code_ext;
 $salesOrder->contact_id = 10001;
 $salesOrder->description = "Test sales order from PHP example file";
 $salesOrder->duedate = date("Y-m-d”);
 $salesOrder->status = "Created";
 $salesOrder->subject = "Test Order from PHP example";

//Add products to the sales order. In this example we have only one product though.
 $orderProductRow1 = new OrderProductRow();
 $orderProductRow1->productid = $product->id; //get product id f
 $orderProductRow1->description = $product->description
 $orderProductRow1->qty = 2;
 $orderProductRow1->value_period = 1;
 $orderProductRow1->unit_price = 200;

 $salesOrder->rows = array($orderProductRow1);

try {
 //finally we create our sales order
 $newSalesOrder = $salesOrderManager->createSalesOrder($session, $salesOrder);
 }  catch(Exception $e) {
 //do some exception handling
}

Code Example 3: Creating a new Sales Order using the Web Service API

The first two lines add necessary Web Service classes for the web service request. On lines 7–22 the product is searched with a corresponding product number. Lines 27–42 create a SalesOrder object and adds needed parameters to it.

Lines 44–52 create one order product row to the SalesOrder. The product rows of the order are set to SalesOrder-object “rows” parameter which takes array of order product row objects as a parameter. You could add as many rows as you wanted.

Finally the salesOrder is created on line 56.

All the API requests should be wrapped inside a try-catch clause. Web Service API generates exception with error message in case of an error.

The SOAP Interface