Sage CRM Developers Course
Using the Web
Services API (1)
Looking ahead to the classes
DP01: Introduction to the Development
Partner Program
DP02: Entities and the Data Model (Part 1 of
2)
DP03: Entities and the Data Model (Part 2 of
2)
DP04: Implementing Screen Based Rules
(Part 1 of 2)
DP05: Implementing Screen Based Rules
(Part 2 of 2)
DP06: Screen and User Independent
Business Rules
DP07: Workflow (Part 1 of 2)
DP08: Workflow (Part 2 of 2)
DP09: Using the API Objects in ASP Pages
(Part 1 of 2)
DP10 : Using the API Objects in ASP Pages
(Part 2 of 2)
DP11: Using the Component Manager
DP12: Programming for the Advanced Email
Manager
DP13: Using the Web Services API
DP14: Using the Web Services API (Part 2 of
2)
DP15: Coding the Web Self Service COM API
(Part 1 of 2)
DP16: Coding the Web Self Service COM API
(Part 2 of 2)
DP17: Using the .NET API (Part 1 of 2)
DP18: Using the .NET API (Part 2 of 2)
Agenda
Introduction to the Web Services API
Configuration and Setup of Web Services
Creating a Session
Usage of Objects and Functions
Introduction to the
SOAP Web Services
API
Software Requirements
To set up Web Services, you will need:
CRM installed on a server with a standard license key.
– For the SOAP web services
– All up-to-date development environments that are compatible with Soap 1.1 are
compatible with Sage CRM Web Services.
– For the SData Rest web services
– Sage CRM Version 7.x
Limitations
Does not provide users with a GUI
Web Services share business logic, data, and processes
Can add the Web Service to a GUI, such as a Web page or an executable program, to provide users with
the required functionality
Programmer must control error handling and session management
Performance Considerations
SOAP overheads include: extracting the SOAP envelope; parsing the contained XML information;
The XML parser will also have to carry out type checking and conversion, wellformedness checking, or
ambiguity resolution, and this all affects speed.
The Web Service SOAP messages move much more data than the average HTTP GET or POST call,
adversely impacting network performance. Repeated SOAP-client calls to access the server could start
to degrade the performance. So you may have to consider the design of the web service client
application.
To ensure secure transfer of XML data then HTTPS maybe desirable for the Web Service access. Web
Services that only use HTTP are vulnerable to eavesdroppers and "man in the middle attacks". HTTPS
requests are very slightly slower than HTTP requests.
There are a range of factors that will affect performance such as: web server response time and
availability; client application execution time; database views and indexes that are implicitly referenced in
CRM.
Configuration and Set
Up of Web Services
Preparation for Use
WSDL file contents
http://server/CRM/eware.dll/webservice/webservice.wsdl
Control & Configuration of
Web Services
Forcing Logons
Date Considerations
Restriction of Requests to Known Machines
Controlling absolute request size
Controlling Records Returned
Configuring Web Services
Maximum Number Of Records To
Return
The maximum number of records you want Web Services to be able to
return at one time.
Maximum Size Of Request
The maximum number of characters you want users to be able to send to
Web Services.
Make WSDL Available To All
When set to Yes, the WSDL file can be viewed by anyone from:
http://CRMservername/CRMinstallname/eWare.dll/webservice/webservice.ws
dl
Users will not need to be logged in to view the file. It is accessible to anyone.
Enable Web Services
Set to Yes to enable the Web Services functionality. Set to No to disable Web
Services.
Dropdown Fields As Strings In
WSDL File
Default is Yes. Drop down fields are displayed in the WSDL as enumerated
types, for example comp_status as an enumeration with the drop down
values in it. When set to Yes, makes the enumerated types "Strings". This is
the recommended setting. This means that, for example, within Company the
field comp_status now has a type of "String".
Send And Return All Dates And
Times In Universal Times
When this is selected, all dates coming from the server will be set to universal
time. Also, all dates coming to the web server will be offset from universal
time. This is primarily important for migrations to the hosting service from
different time zones.
Accept Web Request From IP
Address
The unique IP address that you want the WSDL file to be accessed from.
Force webservice log on
When logging on if the user id used in Web Service is already logged on then
cause existing session to be destroyed.
Web Service Requests from
Specific Clients
Accept web request from IP Address
Controls the unique IP address that you want the WSDL file to be accessed from
If a single IP address is entered here then only the machine that has this address may make calls to use the WSDL file.
Any other machine having a different IP address will be unable to access the WSDL file and will be returned with an "IP Address Mismatch" error.
Possible to specify a range of machines that can access the WSDL file by entering a partial IP address.
Only numeric characters are allowed and the * (asterisk) wildcard character is not supported.
Example usage:
If the following is entered into "Accept web request from IP Address":
–
192.168
Then machines with IP addresses that begin
–
–
–
–
192.168.1.*
192.168.2.*
192.168.3.*
etc
can access the wsdl file.
If the following is entered
–
192.168.2
Then only machines within IP addresses beginning with this will be allowed to access the wsdl file
–
–
–
192.168.2.1
192.168.2.2
etc.
Enabling the Web Services User
Administration -> Users -> Users
Allow Web Service Access = True
Option for dedicated user or reuse existing user
Cannot be a resource user
NB: security is applied to the user!
Control of SOAP and REST access
New Checkboxes to control access in Table Customization screen
Can also be set in Advanced Customization wizard
New entities and existing tables can then be access either by standard SOAP requests or by SData
URLs
– E.g. http://myserver/sdata/crm72j/sagecrm/-/project
Externally linked tables can also be made available via webservices and the SData provider.
Meta Data information may be accessed using SOAP Functions
– getmetadata()
– getallmetadata();
SData REST
– http://myserver/sdata/crm72j/sagecrm/-/$schema
– http://myserver/sdata/crm72j/sagecrm/-/company/$schema
Adding Web Reference
Wide range of methods to allow data
manipulation of exposed tables
Logon/Logoff, session management
Querying
Update
– Delete
Insert/Create
NOTE: Rights controlled by user
logon used
May trigger Table level scripts
Creating a Session
Session Management
Log on and Log off
Error Handling
Interaction with Security
Web Service Session (logon/logoff)
Web Services are Session based similar to
interactive user logons
To initiate a session call the logon method
– logon(string username, string password)
To end a session call the logoff method
– logoff(string sessionId)
Usage: logon()
Syntax
logon ( username As string , password As string ) As logonresult
Usage
private void buttonLogon_Click(object sender, EventArgs e)
{
try
{
logonresult CRMlogon = crm72.logon("Admin", "");
crm72.SessionHeaderValue = new SessionHeader();
crm72.SessionHeaderValue.sessionId = CRMlogon.sessionid;
}
catch (Exception exc)
{
MessageBox.Show(exc.Message);
}
}
Note
Exception handling required/Existing Session Management
Usage: logoff()
Syntax
logoff ( sessionId As string ) As logoffresult
Usage
private void buttonLogoff_Click(object sender, EventArgs e)
{
crm72.logoff(crm72.SessionHeaderValue.sessionId);
}
Using /sysadmin to control sessions
during build
Interactions
Session Usage
Web Service usage shows in Activity Reports
– Activity table
– SysAdmin
– Locking
Web and Web Service logon
– 1 instance of each allowed
– C.f. “Force Web Service Logon”
Triggering of Tablelevel scripts
Information Available
– Values() Collection
– WhereClause
Logging
CRM Web Service Logs provide details of Interactions
SOAP Requests
These are logged when logging level is set to max
Tip:
Where data is being migrated or a system is being tested then these files could become
very large.
Log Information
Example Task
Build a simple ‘3 button form’
Logon
Display Version
Logoff
Q&A
Looking ahead to the classes
DP01: Introduction to the Development
Partner Program
DP02: Entities and the Data Model (Part 1 of
2)
DP03: Entities and the Data Model (Part 2 of
2)
DP04: Implementing Screen Based Rules
(Part 1 of 2)
DP05: Implementing Screen Based Rules
(Part 2 of 2)
DP06: Screen and User Independent
Business Rules
DP07: Workflow (Part 1 of 2)
DP08: Workflow (Part 2 of 2)
DP09: Using the API Objects in ASP Pages
(Part 1 of 2)
DP10 : Using the API Objects in ASP Pages
(Part 2 of 2)
DP11: Using the Component Manager
DP12: Programming for the Advanced Email
Manager
DP13: Using the Web Services API
DP14: Using the Web Services API (Part 2 of
2)
DP15: Coding the Web Self Service COM API
(Part 1 of 2)
DP16: Coding the Web Self Service COM API
(Part 2 of 2)
DP17: Using the .NET API (Part 1 of 2)
DP18: Using the .NET API (Part 2 of 2)