SOAP-rajapinta

SOAP-rajapinta

Yleistä

SOAP on osa CRM-servicen tarjoamia avoimia Web Service -rajapintoja. Tämä dokumentti pitää sisällään yleiskatsauksen kolmannen osapuolen sovellusten käyttöön yhdessä CRM-järjestelmän kanssa.

Ajantasalla olevat tekniset tiedot ja palvelukuvaukset löytyvät aina web-dokumentaatiostamme:

https://<Yrityksen CRM-servicen URL>/CrmIntegrationWebservice/

Jos SOAP-pohjaiset web-palvelut eivät ole entuudestaan tuttuja, voi olla hyödyksi lukea aiheesta taustatietoja. Alla on kuitenkin lyhyt kuvaus, mitä SOAP ja WSDL ovat.

Mikä on SOAP?
SOAP (Simple Object Access Protocol) on standardoitu tietoliikenneprotokolla web-palveluiden väliseen tiedonvälitykseen internetin avulla.

Mikä on WSDL?
SOAP-perustaisissa web-palveluissa palvelu kuvataan WSDL (Web Service Descrpition Language) -dokumenteissa. WSDL on XML-perustainen kieli, joka yksinkertaisesti kuvaa kaikki toiminnallisuudet ja rakenteet tietystä web-palvelusta. WSDL-dokumentti kuvaa, kuinka palvelua voidaan kutsua, mitä parametrejä se odottaa ja mitä tietorakenteita se palauttaa.

Mikä on API-avain?
API-avain on uniikki avain, jolla saadaan pääsy CIWS (CRM Integration Web Services) -palveluihin. Jokainen API-avain voi sisältää joukon sille sallittuja web-palveluita.

Edellytykset
On suositeltavaa luoda WSDL-määrityksen mukaiset proxy-luokat. Useimmat uusimmista IDE:stä(Integrated Development Environment) tekevät tämän automaattisesti. Seuraavissa esimerkeissä luokat ja objektit luodaan ilmaisella wsdl2php- scriptillä (http://www.urdalen.no/wsdl2php/). Huomaa, että samaan tarkoitukseen on olemassa myös monia muita sovelluksia ja näistä voi käyttää mitä tahansa.

CRM Integration Web Service -palvelut

CRM Integration Web Service -palveluiden käyttöön tarvitaan toimiva API-avain.

Kaikki alla olevat esimerkit ovat kirjoitettu PHP-kielellä. Web Service API on kuitenkin käytettävissä myös millä tahansa muulla ohjelmointikielellä.

Kuva 1: Tunnistautuminen web-palvelun kanssa tehdään uniikilla API-avaimella, kun web-palvelu palauttaa istunnon. Istuntoa voidaan sen jälkeen käyttää tunnistautuessa muiden web-palveluiden kanssa.

Luo istunto
Ensimmäiseksi tulee luoda istunto, jolla tunnistus tehdään.

//sessionManager on wsdl2php avulla luotu proxy luokka

 require("POLKU_TIEDOSTO_KIRJASTOOSI/sessionManager.php");$apiKey = UNIIKKI_API_AVAIMESI;//istunnon luonti

 $sessionManager = new sessionManager();try {
 $session = $sessionManager->createSession($apiKey);
 catch(Exception $e) {
 //tee muutama poikkeuksien käsittely
}

Esimerkkikoodi 1:  Istuntomuuttujan luonti.

Kun istunnot on luotu, on haluttujen web-palveluiden käyttö mahdollista. Täysi luettelo mahdollisista menetelmistä on online-dokumentaatiossa.

Huom! Jos jotain menee vikaan, web-palvelu palauttaa SOAP-poikkeuksen. On aina tärkeää käsitellä Web-palvelun pyyntöjen poikkeukset. Monissa ohjelmointikielissä, kuten PHP:n alkuperäisessä SOAP-ohjelmassa, nämä käsitellään poikkeuksina.

Käytä API avainta – Todenna asiakkaasi Web Service API:n avulla

Rajapinta tarjoaa yksinkertaisen tavan todentaa asiakkaasi mille tahansa kolmannen osapuolen sovellukselle. Todentaminen voidaan tehdä Contact Manager –palvelun avulla. Jokainen kontakti voidaan asettaa portaalin käyttäjäksi CRM:stä.

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

 $login->email = $email_address;
 $login->password = $password;
 $login->portal_id = $portal_id; //tietyn portaalin id
 //CRM:ssä voi olla monia portaaleja, eikä jokainen kontakti ole automaattisesti
 //osa jokaista portaalia. portal_id parametri määrittää portaalin johon koetamme
 //todentaa itsemme. Kontakteja ja portaaleja voidaan hallinnoida CRM:stä.

 try {
 $user = $contactManager->authenticatePortalUser($session, $login);
 } catch(Exception $e) {
 //Todentaminen epäonnistui. Voit käsitellä poikkeusta esimerkiksi näyttämällä virhesivun.
 }

Esimerkkikoodi 2:  CRM portaalin käyttäjän (kontaktit) todentaminen Web Service API:n avulla.

Contact Manager tekee käyttäjän todentamisen portaaliin, joten ensiksi meidän täytyy luoda contactManager – objekti. Kirjautumistiedot siirtyvät contactManager objektiin PortalUserLoginDetails objektin avulla, joten meidän täytyy luoda myös se. PortalUserLoginDetails objekti tarvitsee toimiakseen 3 parametria: sähköpostiosoite, salasana ja portaalin ID. Portaalin ID on uniikki jokaiselle portaalille, johon koetamme ottaa yhteyden. Samassa CRM:ssä voi olla useita portaaleja, joten meidän täytyy määrittää minkä portaalin kanssa tahdomme kommunikoida. Kontaktin tulee olla määritettynä aktiiviseksi portaalin käyttäjäksi, jotta tunnistautuminen on mahdollista.

Vihdoin voimme kutsua contactManagerin authenticatePortalUser – metodia tunnistautuaksemme. Jos tunnistautuminen onnistuu, järjestelmä palauttaa authenticatedCustomer – objektin. Muussa tapauksessa järjestelmä palauttaa poikkeuksen.

Toinen esimerkki – Myyntitilauksen luonti

Alla olevassa esimerkissä luodaan uusi myyntitilaus käyttämällä CRM-servicen Web Service -rajapintaa.

require("POLKU_TIEDOSTO_KIRJASTOOSI/sessionManager.php");
require("POLKU_TIEDOSTO_KIRJASTOOSI/salesOrderManager.php");
require(“POLKU_TIEDOSTO_KIRJASTOOSI/accountManager.php”);//… luo istunto, kuten edellisessä esimerkissä …//Tiedämme vain tuotteen numeron, joten etsitään tuotteen ID Web Servicestä

 $productManager = new ProductManager();//Tarvitsemme productSearchCriteria-objektin etsiäksemme tietoa tuotteesta.
 $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) {
 //poikkeusten käsittely
 }

 $product = $products[0];//tehdään myyntitilaus

 $salesOrderManager = new salesorderManager();$salesOrder = new SalesOrder();
 $salesOrder->account_id = 10000; // Asiakastilin ID
 $salesOrder->assigned_user_id = 1; //Käyttäjän ID
 $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";

//Lisää tuote myyntitilaukseen. Tässä esimerkissä meillä on tosin vain yksi tuote.
 $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 {
 //vihdoin luomme myyntitilauksemme
 $newSalesOrder = $salesOrderManager->createSalesOrder($session, $salesOrder);
 }  catch(Exception $e) {
 //poikkeuksien käsittelyä
}

Esimerkkikoodi 3: Uusien myyntitilausten luonti Web Service API:n avulla.

Kaksi ensimmäistä riviä lisäävät tarvittavat Web Service -luokat web service -pyynnöille. Riveillä 7–22 etsitään tuote tuotteen numeron avulla. Riveillä 27–42 luodaan SalesOrder-objekti ja lisätään siihen tarvittavat parametrit.

Rivit 44–52 luovat yhden tuoterivin myyntitilaukseen. Tuoterivit määritellään SalesOrder-objektin ”rivit” parametriksi. Parametriksi käy lista tuoteriveistä ja rivejä voi lisätä niin monta kuin on tarpeen.

Viimeiseksi luodaan SalesOrder-objekti rivillä 56.

Kaikki API-pyynnöt tulisi tehdä try-catch -lauseen sisälle. Web Service API luo poikkeuksen virheilmoituksella virheen sattuessa.

Lisää luettavaa

Täysi lista Web Serviceistä ja lisää informaatiota löydät Web Service –dokumentaatioistamme:
https://<Sinun CRM-service-url>/CrmIntegrationWebservice/