1. Sage CRM Developers Course
Using the Web Services API (1)

2. 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 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)

3. Agenda
Introduction to the Web Services API Configuration and Setup of Web Services Creating a Session Usage of Objects and Functions

4. Introduction to the SOAP Web Services API

5. 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

6. SOAP XML HTTP WSDL SOAP transfers the data
A Web Service is a software system designed to support interoperable machine-to-machine interaction over a network.
Sage CRM has
SOAP based web services
These use SOAP-formatted XML envelopes and its interface is described by WSDL
Full CRUD
SData Restful web services
Read Only
SOAP
SOAP transfers the data
Simple Object Access Protocol SOAP is an XML based protocol for exchange of information. Has three parts:
Envelope that defines framework for describing what is in a message and how to process it,
Set of encoding rules for expressing instances of application-defined datatypes,
Convention for representing remote procedure calls and responses.
XML
XML Tags the data
Acronym for Extensible Markup Language. An open standard for exchanging structured documents and data over the Internet
HTTP
The Hypertext Transfer Protocol is the set of rules for exchanging files on the World Wide Web.
WSDL
WSDL defines the Types and Methods exposed
The Web Services Description Language (WSDL) is an XML format published for describing a Web service's capabilities as collections of communication endpoints capable of exchanging messages

7. 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.

8. Configuration and Set Up of Web Services Preparation for Use

9. WSDL file contents

10. Control & Configuration of Web Services
Forcing Logons
Date Considerations
Restriction of Requests to Known Machines
Controlling absolute request size
Controlling Records Returned

11. 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:
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.

12. 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":
Then machines with IP addresses that begin * * *
etc
can access the wsdl file.
If the following is entered
Then only machines within IP addresses beginning with this will be allowed to access the wsdl file
etc.

13. 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!
Enabling the Web Service User
Go to Administration | Users | Users and select the user logon that you are going to use for the Web Service Logon. Edit this user’s profile and set the Allow Web Service Access setting in the Security screen to True.

14. 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.
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

15. 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

16. Creating a Session

17. Session Management
Log on and Log off Error Handling Interaction with Security

18. 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)
Before clicking any button, it is important that the following fields are correctly filled out.
WSDL URL: Must point to a valid CRM Web Services URL
User Logon: Must contain a valid CRM User logon
Password: Must contain a valid password for the CRM User Logon
Every time a button is clicked, the logon()method of the web service is called, and a new web service user session initiated. Once the actions associated with a button are completed, the logoff() method is called to terminate the users session.
The logon() method of the Web Service takes two string arguments, and returns a logonresult object. When a new web service session is created on a new WebService instance, the SessionHeaderValue property of the WebService instance must be initiated and it’s sessionid property set.
To end a session, the logoff() method must be called and passed a valid session identifier.
In the sample code, the logon and logoff functions are handled in 2 helper functions, WSLogon() and WSLogoff() are called to initiated and terminate a web service session each time a button is clicked.

19. 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

20. Usage: logoff() Syntax Usage
logoff ( sessionId As string ) As logoffresult
Usage
private void buttonLogoff_Click(object sender, EventArgs e) {
crm72.logoff(crm72.SessionHeaderValue.sessionId); }

21. Using /sysadmin to control sessions during build

22. Interactions Session Usage Triggering of Tablelevel scripts
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

23. 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.

24. Log Information

25. Example Task
Build a simple ‘3 button form’ Logon Display Version Logoff

26. Q&A

27. 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 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)

28. Visit the Sage CRM Ecosystem at www.sagecrm.com
Facebook: Sage CRM
Twitter: wwwsagecrmcom
LinkedIn: Sage CRM (Official Group)
YouTube: wwwsagecrmcom