CRM-service CIWS-kirjasto

CRM-service CIWS on asiakaskirjasto, joka tarjoaa helppokäyttöisen rajapinnan CIWS API:in.
CIWS API:n käyttöä varten tarvitaan erillinen API-avain kyseiselle CRM-instanssille.

Vaatimukset

• .NET Framework 4.5 tai uudempi

CrmManager

Namespace: CRMservice.ciws.Manager
Namespace: CRMservice.ciws.Manager.Default

CrmManagerilla päästään käsiksi webserviceihin. Tätä varten voidaan tehdä mukautettu CrmManager-luokka abstraktilla CrmManagerBasella tai käyttää oletus namespacea.

Mukautetun CrmManagerin luominen mahdollistaa mukautettujen metodien luomisen luokan sisään:

using CRMservice.ciws.Manager;

namespace Example
{
  public class CrmManager : CrmManagerBase
  {
   public CrmManager(string apiKey, string crmUrl)
   {
    StartSession(apiKey, crmUrl);
   }

   //mukautetut metodit
  }
}

Käyttämällä CrmManageria ”using”-lauseella istunto päätetään aaltosulkeiden jälkeen:

using (var crm = new CrmManager(apiKey, crmUrl))
{
 //koodi
}

CrmManageria voidaan käyttää myös ilman ”using”-lausetta:

var crm = new CrmManager();
crm.StartSession(apiKey, crmUrl);
//koodi
crm.EndSession();

StartSession-metodi luo uuden istunnon, jota tarvitaan CrmManagerin metodien käyttöön. Istunto on aktiivinen yhden tunnin ajan edellisestä metodikutsusta tai kunnes EndSession-metodia kutsutaan.

StartSession-metodin parametrit:

• ApiKey (string): Käytetään todennukseen CIWS API:ssa
• CrmUrl (string): CRM-servicen url
• KeepSessionAlive (bool): Päivitetäänkö istuntoa SessionTimeOut:iin perustuen
• SessionTimeOut (TimeSpan): Päivitysintervalli istunnon käynnissä pitämiseksi (oletusarvo 30min)

CrmObjects

Namespace: CRMservice.ciws.CrmObjects
Namespace: CRMservice.ciws.CrmObjects.Default

CrmObjects-namespacessa on abstrakteja moduuleja, joihin sisältyy pysyvien (permanent) kenttien nimiä. Tätä namespacea voidaan käyttää Custom CrmObjectin luomiseen; toinen vaihtoehto on käyttää oletusnamespacea. Olethan yhteydessä jälleenmyyjääsi, jos tarvitset muiden kenttien nimiä.

Näitä objekteja voidaan käyttää ExtendedSearch- tai BulkEntitySave-metodeissa. Jos on tarve käyttää vain muutamaa moduulin kenttää, on hyvä tehdä Custom Object. Jos mukaan tarvitaan mukautettuja kenttiä (custom fields), tulee luoda joko Custom CrmObject tai Custom Object.

Esimerkki Custom CrmObjectista:

using CRMservice.ciws;
using CRMservice.ciws.CrmObjects;

namespace Examples
{
 public class CrmContact : CrmContactBase
 {
  [CrmFieldName("cf_1234")]
  public string TransferStatus;
 }
}

Esimerkki Custom Objectista:

using CRMservice.ciws;

namespace Examples
{
 [CrmModule(Module.Contacts)]
 public class ContactData
{
  [CrmFieldName("crmid")]
  public int? ID;

  [CrmFieldName("firstname")]
  public string FirstName;

  [CrmFieldName("lastname")]
  public string LastName;

  [CrmFieldName("email")]
  public string Email;
 }
}

Metodit

Namespace: CRMservice.ciws

class CrmSearch

Generic parameter object ExtendedSearchissä.

• Module (ei pakollinen): Yliajaa objektin [CrmModule] attribuutin
• Fields[] (ei pakollinen): Yliajaa objektin [CrmFieldName] attribuutit
• Conditions[] (pakollinen): string “fieldname = ‘123’”
• SortOrder (ei pakollinen): CrmSortOrder(string field, enum SearchOrder)
• Buffer (ei pakollinen): Yksittäisen CIWS API-kutsun suurin eräkoko
• Limit (ei pakollinen): Suurin määrä tuloksia, joita etsintä voi palauttaa
• Offset (ei pakollinen): Jos offsetia ei määritetä, etsitään bufferin kokoisia eriä, jotka yhdistetään tuloslistaan. Käyttämällä offsetia voidaan etsiä Limitin kokoisia eriä ja jatkaa edellisestä offsetista.

List<T> ExtendedSearch<T>(CrmSearch search) where T : class

Metodilla etsitään dataa CRM:stä ja ”mäpätään” sitä custom objecteihin.
Metodi käyttää taustalla ExtendedSearchLimit-webserviceä.

• CrmModule: Määrittää, mitä moduulia käytetään
• CrmFieldName: Mäppää kentän CRM-kentän kanssa – ainoastaan mäpättyjä kenttiä etsitään CRM:stä. Kenttätyypit, joita voidaan käyttää, ovat bool, float, double, int, string ja DateTime (myös nullable-tyyppejä voidaan käyttää).

Esimerkkimetodi:

using CRMservice.ciws;
using CRMservice.ciws.Manager.Default;
using System.Collections.Generic;

namespace Examples
{
 [CrmModule(Module.Contacts)]
 public class ContactData
 {
  [CrmFieldName("crmid")]
  public int? ID;

  [CrmFieldName("firstname")]
  public string FirstName;

  [CrmFieldName("lastname")]
  public string LastName;
 }

 class Program
 {
  public static string ApiKey = "...";
  public static string CrmUrl = "...";

  static void Main(string[] args)
  {
   var search = new CrmSearch()
   {
    Conditions = new string[] { "contact_code = 'DEBUG'" }
   };

   using (var crm = new CrmManager(ApiKey, CrmUrl))
   {
    var results = crm.ExtendedSearch<ContactData>(search);
   }
  }
 }
}

List<CrmObject> ExtendedSearch(CrmSearch search)

Metodi etsii dataa CRM:stä ja palauttaa sen geneerisiin CrmObjecteihin.
Metodi käyttää taustalla ExtendedSearchLimit-webserviceä.

• CrmSearch-parametreissä tulee käyttää Modulea
• CrmSearch-parametreissä tulee käyttää Fields[]:ia
• CrmId: Määritetään vain, jos ”crmid”-kenttää etsitään
• Fields: Taulukko tuloskentistä

Esimerkkimetodi:

using CRMservice.ciws;
using CRMservice.ciws.DataObjects;
using CRMservice.ciws.Manager.Default;
using System.Collections.Generic;

namespace Examples
{
 class Program
 {
  public static string ApiKey = "...";
  public static string CrmUrl = "...";

  static void Main(string[] args)
  {
   var search = new CrmSearch()
   {
    Module = Module.Contacts,
    Fields = new string[] { "crmid", "firstname", "lastname" },
    Conditions = new string[] { "contact_code = 'DEBUG'" }
   };

   using (var crm = new CrmManager(ApiKey, CrmUrl))
   {
    var results = crm.ExtendedSearch(search);
   }
  }
 }
}

List<T> BulkEntitySave<T>(List<T> items)

Metodi käyttää custom objecteja päivittämään tai luomaan uutta dataa CRM:ssä.

• CrmModule: Määrittää, mitä moduulia käytetään.
• CrmFieldName: Mäppää kentän CRM-kenttään – vain mäpätyt kentät tallennetaan CRM:ään. Kenttätyypit, joita voidaan käyttää, ovat bool, float, double, int, string ja DateTime (myös nullable-tyyppejä voidaan käyttää).
• CrmFieldName(”crmid”): Null tai 0 luo uuden entiteetin ja olemassa oleva arvo päivityksen

Esimerkkimetodi:

using CRMservice.ciws;
using CRMservice.ciws.Manager.Default;
using System.Collections.Generic;

namespace Examples
{
  [CrmModule(Module.Contacts)]
  public class ContactData
  {
   [CrmFieldName("crmid")]
   public int? ID;

   [CrmFieldName("firstname")]
   public string FirstName;

   [CrmFieldName("lastname")]
   public string LastName;
  }

  class Program
  {
   public static string ApiKey = "...";
   public static string CrmUrl = "...";

   static void Main(string[] args)
   {
    var contact = new ContactData()
    {
     ID = 123,
     FirstName = "John",
     LastName = "Doe"
    };

   var contacts = new List<ContactData>();
   contacts.Add(contact);

   using (var crm = new CrmManager(ApiKey, CrmUrl))
   {
    var results = crm.BulkEntitySave<ContactData>(contacts);
   }
  }
 }
}

List<CrmObject> BulkEntitySave(Module module, List<CrmObject> items)

Metodi käyttää CrmObjecteja päivittämään tai luomaan uutta dataa CRM:ään.

• Module-parametri määrittää, mitä moduulia käytetään
• CrmId: Null tai 0 luo uuden entiteetin ja olemassa oleva arvo päivityksen
• Fields: Taulukko kentistä, jotka tallennetaan CRM:ssä

Esimerkkimetodi:

using CRMservice.ciws;
using CRMservice.ciws.DataObjects;
using CRMservice.ciws.Manager.Default;
using System.Collections.Generic;

namespace Examples
{
 class Program
 {
  public static string ApiKey = "...";
  public static string CrmUrl = "...";

  static void Main(string[] args)
  {
   var contact = new CrmObject();
   contact.CrmId = 123;
   contact.Fields["firstname"] = "John";
   contact.Fields["lastname"] = "Doe";

   var contacts = new List<CrmObject>();
   contacts.Add(contact);

   using (var crm = new CrmManager(ApiKey, CrmUrl))
   {
    var results = crm.BulkEntitySave(Module.Contacts, contacts);
   }
  }
 }
}

Kattavammat asetukset

Namespace: CRMservice.ciws.Settings

Jokaisella webservice managerilla on puskurin oletuskoko: UInt16.MaxValue.
Jos kutsutun CIWS API:n vastauksen koko on suurempi kuin viestin puskurin koko, kirjasto antaa poikkeuksen.

CrmSettings.[manager name].SetBuffer(int value)

Metodi muuttaa yleisen puskurin koon annettuun kokoon.

SetBuffer example:

using CRMservice.ciws.Settings;

namespace Examples
{
 class Program
 {
  static void Main(string[] args)
  {
   CrmSettings.SearchManager.SetBuffer(int.MaxValue);

   //code
  }
 }
}

Kaikki käytettävissä olevat metodit

Kaikki käytettävissä olevat metodit löytyvät CRM Integration Webservice -dokumenttisivulta:

https://yourCrmSite/CrmIntegrationWebservice/service.php?class=documentation