1. Sage CRM Developers Course
Using the .NET 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
About the .NET API The Architecture and how the .NET assemblies link to the CRM Interface The SDK and Resources Creating a First Project: Hello World Designing Simple Web Pages using the Web Class Note: This presentation assumes you are using Sage CRM 6.2g or Sage CRM 7.0c or later.

4. About the .NET API

5. About the .NET API
Sage CRM Application Extensions are .NET projects or assemblies (dlls) that implement custom behaviour. API slightly updated and changed for Sage CRM 6.2g and Sage CRM 7.0c Part of a strategy of choice for development partners. It expands the range of tools to allow integrations to be developed Available for Development Partners and Internal Sage OpCo development team use only To prove the API it is being used to develop new features (similar to early usage of COM ASP API)

6. .NET API .NET API is not a replacement for ASP COM API
Bug fixes and improvements to COM API continue
You can code with what ever .NET language you like e.g. C#, VB.net
Tight integration with Existing system
Exposes deeper and richer functionality than COM API
Designed for functionality. (COM designed for simplicity)
Sophisticated design environment available
By using Sage CRM meta data Application Extensions constructed using the Sage CRM .NET API will look, feel and perform exactly like core system pages.
Compiled end product (human non-readable)
Protection for Intellectual Property
Can not just ‘tweak’ a line – Development Cycle Implied
Drop in Deployment – NO IISRESET required
.NET API methods manage all HTTP interaction and do NOT use ASP.NET classes or ASP Objects
Reference to the Sage CRM .NET component from within ASP.NET projects is not supported.

8. CustomDotNetDll action calls Application extension
CustomDotNetDll action uses COM interop to trigger behaviour in CRM .NET Component.
Passes CRM Application Extension DLL name and session information
Calls CRM Application Extension
CRM Application Extension processes data and generates and returns HTML

9. Calling .NET Application Extensions
From Tabs/Menus
Action:
CustomDotNetDll
Custom DOT NET DLL Name
Method Name
From List Block Hyperlinks
Hyperlink to
Custom ID Field
From Application Extension Buttons
string sUrl = UrlDotNet(ThisDotNetDll, "RunViewOpportunity");
AddUrlButton("Cancel", "Cancel.gif", sUrl);
From ASP Pages
mycontainer.AddButton(CRM.Button("Add","new.gif",CRM.Url("myproject.dll-RunMyCustomPage")))
Redirection from other DLLs

10. The SDK and Resources

11. New Resources available for Development Partners
.NET Developers Guide
Revised Class Diagram
Advanced Customization Wizard
Updated SDK
CRM Entity Template reflects new class constructors
New Snippets
Sample Projects include source code for RelatedEntity module.
Developers Site
Free Online Classes and recorded sessions
Training Material

12. SDK Files

13. Main Features of API Workflow support added Debugging
Workflow Buttons available
Debugging
Simplification and standardization of API code.
This will require existing developments to edit code base.
Assemblies created for 6.1 will not work with 6.2 & 7.0
Assemblies created for 6.2 & 7.0 will not work with 6.1
Easy constructor mechanism for specialist classes
DataPage
DataPageDelete
DataPageEdit
DataPageNew
ListPage
SearchPage
Component Manager
Delivery of .NET component files
Extended SDK
Related Entities Feature
A case study in .NET
Calling from the API
Sample Code available only post release

14. Assemblies
SageCrmNet.dll and SageCRMWrapper.dll added to Global Assembly Cache during installation
C:\windows\assembly
SageCRMNet.dll
SageCRMWrapper.dll
Reference Path
C:\Program Files\Sage\CRM\CRMDotNet\6.2\SageCRMNet.dll
C:\Program Files\Sage\CRM\CRMDotNet\7.0\SageCRMNet.dll
C:\Program Files\Sage\CRM\CRMDotNet\7.1

15. Tip: Use Object Browser to Examine Namespaces

16. Namespaces
Sage Sage.CRM.Blocks Sage.CRM.Controls Sage.CRM.Data Sage.CRM.Errors Sage.CRM.Graphics Sage.CRM.HTML Sage.CRM.UI Sage.CRM.Utils Sage.CRM.WebObject

17. Sage.CRM.Controls
Entry EntryAdvSearchSelect EntryCustom EntryGroup EntrySelect EntrySelectTable GridCol GridColCheckBox List
EntryAdvSearchSelect
Class used to represent Advanced Select Search Entry
EntryCustom
Class to represent a Custom Entry
GridColCheckBox
Provides capability to specify a CheckBox Column to be added to List Grid

18. Sage.CRM.WebObject DataPageBase Abstract class to all Data Pages
DataPage DataPageBase DataPageDelete DataPageEdit DataPageNew ListPage SearchPage Web

19. Sage.CRM.Utils
Dispatch Keys Metadata TableInfo TranslationFamily UserSession

20. Sage.CRM.UI
Objects
ComplexBox
ContentBox
HorizontalPanel
HTMLString
Hyperlink
ImageLink
ImageObject
Panel
UIEntry
UIObject
VerticalPanel
This namespace contains objects which allow better control of the positioning of screen elements.
Much easier to create complex screens
Lists with detail screens
Complex ‘button’ groups
Stacked or side-by-side lists
Custom entry screens
Discussed in later slides

21. Using the Sage CRM .NET API for Sage CRM
Starting a Project
Using the Sage CRM .NET API for Sage CRM

22. Create a new project: Basic Template
Note: Sage CRM Templates found under Visual C# templates
CRM Entity Template
Use this to create a project that will generate screens for working on a new CRM entity
CRM Basic Template
Create a new application extension for Sage CRM

23. Creating a first project with Basic Template
Check that the project references are correct
Project automatically creates
Base Class
Example Custom Page

24. Change Build Location for Quick Testing

25. CRM Entity Template
Template will create example pages for a new entity
You will need to ‘Load Project Normally’
Template DOES NOT
Carry out database tasks – the new table is not created
Carry out Meta Data changes – new screens and lists are not created
Tips:
If using the wizard it is recommended to create a new dll for each entity
Create the new Table using the Advanced Customization Wizard (Main Entity Wizard) to have table, screens and lists created

26. Base Class Typically All classes within same namespace Must contain
using System; using System.Collections.Generic; using System.Text; using Sage.CRM.WebObject; namespace Sample1 { //Every thing should be declared in same namespace. //static class AppFactory is REQUIRED! public static class AppFactory /* * Name of Method here is what you enter into CRM admin as the Method * name when adding new tab with action CustomDotNetDll * */ public static void RunHelloWorld(ref Web AretVal) AretVal = new HelloWorld(); }
Typically All classes within same namespace
Must contain
public static class AppFactory
This contains the methods that are called by CRM. These in turn reference others.
RunTask Method
May contain calls to other tasks but can not use CRM classes
Note:
The ref keyword on a method parameter causes a method to refer to the same variable that was passed as an input parameter for the same method. If you do any changes to the variable, they will be reflected in the variable.

27. Creating a Simple Web Class
using System; using System.Collections.Generic; using System.Text; using Sage.CRM.WebObject; using Sage.CRM.Controls; using Sage.CRM.Data; using Sage.CRM.Utils; namespace Sample1 { public class HelloWorld : Web public override void BuildContents() }
BuildContents
Override this to build your own page

28. Simple Methods GetTabs() GetTabs(“Tabgroup Name”) AddContent("")
Method used to add HTML to the page that you are building.
AddContent("<marquee>Hello World</marquee>");
AddContent("Hello World", "InfoContent");
AddInfo("Hello World");
AddButtonContent("<div class= viewbox>hello</div> ");
AddHeaderContent("custom content goes here");

29. Error Handling and Error Messages
Error Related Methods available AddErrror(“Message”) LogMessage("Hello World", 5); Standard Dot Net log LogMessage("myfile", "Hello World", 5); Custom Log
try {
//code goes here }
catch (Exception e)
AddError(e.Message);
Handle different types of exceptions e.g.
ArithmeticException
OverFlowExceptions
FormatExceptions

30. Adding Client Side Code
AddHeaderScript
Add JavaScript to the <Head> section of the page
This can use the new Client Side API
string strHS = "crm.ready(function(){crm.infoMessage(‘Hello World’);})";
AddHeaderScript(strHS);
Note: Custom Script Library files in Sage CRM v7.2 are automatically available to .NET assemblies
C:\Program Files (x86)\Sage\CRM\CRM\WWWRoot\js\custom

31. Important Objects
Sage.CRM.Utils.Metadata Methods to GetScreen and GetList and GetTranslation (discussed later) Sage.CRM.Utils.CurrentUser All info on the currently logged on user Sage.CRM.HTML.HTMLBuilder Methods for wrapping up text in HTML tables and TRs and TD etc. (discussed later) Sage.CRM.Utils.Dispatch Methods for starting/committing transactions and getting locks, also gives access to content and query fields.

32. User, Session and System Information
CurrentUser
Available in BuildContents
AddInfo(CurrentUser.UserName);
User Preferences
AddInfo(CurrentUser[Sage.UserOptions.GridSize]);
GetContextInfo()
AddInfo(GetContextInfo("user","user_lastname"));
AddInfo(GetContextInfo("selecteduser","user_lastname"));
Key Information
AddInfo(Sage.KeyList.UserId.ToString());
NB This will retrieve the UserID in keys NOT the owner of the session.
Identify Dominant Key
int iDomKey = Keys[(int)Sage.KeyList.DominantKey];
System Parameters (from custom_sysparams)
AddInfo(Metadata.GetParam(Sage.ParamNames.GlobalTemplateDocStore))
DLL and Method Information
AddInfo(ThisDotNetDll +"/"+ ThisDotNetFunction);
Useful for building URLs in buttons and redirects
HTTP Information
AddInfo(Dispatch.ServerVariable("HTTP_REFERER"));

33. Themes, Translations and Captions

34. .NET Pages and Themes
Themes are automatically picked up for main pages
When building custom paths can use
CurrentUser.VirtualImgPath()
E.g. /crm62/Themes/img/default/

35. Handling Translations
Explicit Use
GetTranslation method
Implicit Use
Buttons automatically use the Caption Family “Buttons”
AddUrlButton("edit", "edit.gif", strURL);
Name and Translations may hold apostrophes (GetJsString)
string strMessage = Metadata.GetTranslation("GenCaptions", "UserWizardInstruction");
string strScript = "javascript:window.alert('"+GetJsString(strMessage)+"')";
AddUrlButton("edit", "edit.gif", strScript);

36. Interacting with Translation Families
Sage.CRM.Utils. TranslationFamily TranslationFamily tf = new TranslationFamily(“testset"); tf.Add("test1", "Test1 Value"); tf.Add("test2", "Test2 Value"); tf.Add("test3", "Test3 Value"); tf.Add("test4", "Test4 Value"); AddContent(tf["test1"]);

37. Adding Coaching Captions to a screen
Automatic Behavior Use Inline Coaching editing to add caption to screen. Caption added will behave as default captions

38. Q&A

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

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