CRM-service CIWS Library for SOAP

CRM-service CIWS is a client library used as an easy access interface for CIWS API.
To use the CIWS API you need a specific API key for your CRM-service instance.

Requirements

• .NET Framework 4.5 or later

CrmManager

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

CrmManager is used for accessing webservices. You can make a custom CrmManager class with an abstract CrmManagerBase class or you can use a default namespace.

Creating custom CrmManager allows you to create custom methods inside class:

using CRMservice.ciws.Manager;

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

   //custom methods
  }
}

Using CrmManager with a using statement will end the session after the curly braces:

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

You can also use the CrmManager without the using statement:

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

StartSession method creates a new session, which is needed for using CrmManager methods. The session is active for 1 hour from the last method invoke or until the EndSession -method is called.

StartSession method parameters:

• ApiKey (string): Used for authentication in CIWS API
• CrmUrl (string): CRM-service url
• KeepSessionAlive (bool): If used session is refreshed based on SessionTimeOut
• SessionTimeOut (TimeSpan): Refresh interval for keeping session alive (default value 30 minutes)

CrmObjects

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

Inside of CrmObjects namespace you can find abstract modules with permanent field names. You can use this to make Custom CrmObject or you can use a default namespace. For other field names, please contact your reseller.

These objects can be used with ExtendedSearch or BulkEntitySave methods. If you only need few fields from a module, it is recommended to make a custom object. If you need to use custom fields, you have to create Custom CrmObject or Custom Object.

Custom CrmObject example:

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

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

Custom Object example:

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;
 }
}

Methods

Namespace: CRMservice.ciws

class CrmSearch

Generic parameter object used with ExtendedSearch.

• Module (not required): Overrides object [CrmModule] attribute
• Fields[] (not required): Overrides object [CrmFieldName] attributes
• Conditions[] (required): string “fieldname = ‘123’”
• SortOrder (not required): CrmSortOrder(string field, enum SearchOrder)
• Buffer (not required): Maximum batch size of single CIWS API call
• Limit (not required): Maximum amount of results search can return
• Offset (not required): If Offset not assigned results are searched buffer sized batches and combined to result list. Using Offset you can search Limit sized batches and continue from last offset.

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

Search data from CRM and map the data with custom objects.
This method uses an ExtendedSearchLimit webservice on background.

• CrmModule: Defines what module is used
• CrmFieldName: Maps field to CRM field, only mapped fields are searched from CRM. The field types you can use are bool, float, double, int, string and DateTime (nullable types are valid as well).

Method example:

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)

Search data from CRM and returns the data with generic CrmObjects.
This method uses an ExtendedSearchLimit webservice on background.

• You need to use Module inside CrmSearch parameters
• You need to use Fields[] inside CrmSearch parameters
• CrmId: Only defined if “crmid” field is searched
• Fields: Dictionary of result fields

Method example:

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)

Use custom objects to update or create new data in CRM.

• CrmModule: Defines what module is used
• CrmFieldName: Maps field to CRM field, only mapped fields are saved to CRM. The field types you can use are bool, float, double, int, string and DateTime (nullable types are valid as well)
• CrmFieldName(“crmid”): Null or 0 creates a new entry or an existing value update entry

Method example:

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)

Use CrmObjects to update or create new data in CRM.

• Module parameter defines what module is used
• CrmId: Null or 0 creates a new entry or an existing value update entry
• Fields: Dictionary of fields which are saved to CRM

Method example:

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);
   }
  }
 }
}

Advanced options

Namespace: CRMservice.ciws.Settings

Each webservice manager has a default message buffer size: UInt16.MaxValue.
If called CIWS API response is larger than message buffer size library will throw exception.

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

Changes the global message buffer size for selected manager.

SetBuffer example:

using CRMservice.ciws.Settings;

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

   //code
  }
 }
}

All available methods

All available methods can be found from CRM Integration Webservice documentation page:

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