Sage CRM Developers Course
Using the .NET 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
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.
About the .NET API
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)
.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.
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
Calling .NET Application Extensions
From Tabs/Menus
Action:
– CustomDotNetDll
Custom DOT NET DLL Name
Method Name
From List Block Hyperlinks
Hyperlink to
– CustomDotNetDll
Custom DOT NET DLL Name
Custom ID Field
Method Name
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
The SDK and
Resources
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
SDK Files
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\SageCRM
Net.dll
C:\Program
Files\Sage\CRM\CRMDotNet\7.0\SageCRM
Net.dll
C:\Program
Files\Sage\CRM\CRMDotNet\7.1
Tip: Use Object Browser to
Examine Namespaces
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
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
Sage.CRM.WebObject
DataPageBase
Abstract class to all Data Pages
DataPage
DataPageBase
DataPageDelete
DataPageEdit
DataPageNew
ListPage
SearchPage
Web
Sage.CRM.Utils
Dispatch
Keys
Metadata
TableInfo
TranslationFamily
UserSession
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
Starting a Project
Using the Sage
CRM .NET API for
Sage CRM
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
Creating a first project with
Basic Template
Check that the project references
are correct
Project automatically creates
Base Class
Example Custom Page
Change Build Location for Quick
Testing
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
Base Class
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.
Creating a Simple Web Class
using System;
using System.Collections.Generic;
using System.Text;
using
using
using
using
Sage.CRM.WebObject;
Sage.CRM.Controls;
Sage.CRM.Data;
Sage.CRM.Utils;
namespace Sample1
{
public class HelloWorld : Web
{
public override void BuildContents()
{
}
}
}
BuildContents
Override this to build your own page
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");
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
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
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.
User, Session and System
Information
CurrentUser
Available in BuildContents
AddInfo(CurrentUser.UserName);
User Preferences
System Parameters (from
custom_sysparams)
AddInfo(Metadata.GetParam(Sage.ParamN
ames.GlobalTemplateDocStore))
AddInfo(CurrentUser[Sage.UserOptions.GridSize]);
DLL and Method Information
GetContextInfo()
AddInfo(ThisDotNetDll +"/"+
ThisDotNetFunction);
AddInfo(GetContextInfo("user","user_lastname"));
AddInfo(GetContextInfo("selecteduser","user_lastn
ame"));
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];
– Useful for building URLs in buttons and redirects
HTTP Information
AddInfo(Dispatch.ServerVariable("HTTP_RE
FERER"));
Themes, Translations
and Captions
.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/
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);
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"]);
Adding Coaching Captions to a
screen
Automatic Behavior
Use Inline Coaching editing to add caption to screen.
Caption added will behave as default captions
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)