Microsoft Dynamics CRM 4.0

If you are maintaining this today

CRM 4.0 is out of support. Microsoft’s lifecycle page starts it on 29 February 2008, with mainstream support ending on 9 April 2013 and extended support on 10 April 2018.

This page comes from Microsoft’s install media, the release readme, the 4.0 SDK (version 4.0.13, November 2010), the 4.0 Implementation Guide (its 2011 revision), and what the CRM 2011 SDK says about 4.0 code. Neither the SDK nor the Implementation Guide was on the DVD; the readme points to both as separate downloads.

Two things about 4.0 shape everything after it:

• A deployment can host several organizations. The web service description files include a Discovery service for finding the organizations available, which the Help describes as mainly for multitenant implementations such as CRM Live. The customization URLs gain the organization name. The readme warns that disabling the default organization stops users reaching the other organizations until a new default is set.
• Upgrade comes only from CRM 3.0. CRM 1.2 and the 4.0 pre-release builds can’t be upgraded to the final release.

What changed for customizers

Area	CRM 3.0	CRM 4.0	Modern equivalent
Server logic	Callouts	.NET assemblies called plug-ins, registered on the server	Plug-ins and custom APIs
Workflow	Workflow Manager on the server, rules owned by the organization	Workflows built in the web application and owned by users; custom work through Windows Workflow Foundation	Power Automate, or classic workflows
Relationships	1:N and N:1; the only N:N was opportunity to competitor	Custom N:N and self-referential relationships	Same, with more options
Web services	CrmService and a read-only MetadataService; see the CRM 3.0 web services	Main data, metadata and discovery services, each with its own WSDL	Web API and the SDK for .NET

Relationships

Source: the CRM 4.0 application Help.

• 1:N and N:1 are the same relationship, viewed from the primary entity or from the related entity.
• N:N relationships are new. They’re reciprocal, so records can be related from either side, and can be self-referential. Relating records needs Read and Append on one entity, and Read, Write and Append To on the other.
• Self-referential relationships are new, for both hierarchical and N:N relationships. A record can’t be its own parent.
• Each entity can take part in only one parental relationship. Most system entities already have one, and it can’t be changed.
• Custom entities can’t relate to the composite Customer. System entities such as opportunity and case link to “account or contact”; custom entities can’t have that kind of lookup.
• Required fields aren’t enforced on the web services. The Help says field requirement levels apply only in the application. Records created through the web services don’t have to honour them. Integration code that assumes a Business Required lookup is always filled in is relying on something the platform doesn’t guarantee.
• Export related entities together. Relationship definitions are included only when both entities are exported and imported at the same time.

Customization privileges

Source: the CRM 4.0 application Help, “Customization Privileges”.

• Customization privileges have only two levels: None or Organization. You can’t grant customization rights for one business unit.
• System Customizer is almost enough. Adding the role gives most customization privileges without widening access to data. Only importing security roles and organization settings needs System Administrator.
• Export Customizations, Import Customizations and Publish Customizations are separate privileges. You can let people build customizations, including form scripts, without letting them publish.
• isv.config buttons need two things. Client extensions must be enabled in System Settings, and users need the ISV Extensions privilege at Organization level. Without both, imported buttons and menus stay hidden.
• A new custom entity is invisible until security roles are updated to include it.
• There’s no attribute-level security. The Help says 4.0 has no direct way to secure individual attributes. Later versions added field-level security for custom attributes, and CRM 2015 extended it to system attributes.

Form scripting

Source: the CRM 4.0 application Help, “Form Scripting”.

The model is 3.0’s, carried forward: JScript on the form’s onLoad and onSave events and each field’s onChange, reached through crmForm. What 4.0 adds is guidance:

• Scripts are entity metadata. Once published, they travel with exported customizations.
• Use only the supported objects, properties and methods documented in the Client Programming Guide, so that the script survives the next upgrade. CRM 2013 removed the 4.0 object model outright and warned that scripts using unsupported methods might stop working.
• The Quick Create trap remains. Check crmForm.FormType, make the field Business Required or Business Recommended, or test that the field exists before using it.

Plug-ins

Sources: Microsoft’s CRM 4.0 SDK, the plug-in registration entities on the 4.0 install media, and the CRM 2011 SDK.

CRM 4.0 replaced CRM 3.0 callouts with plug-ins. Registration moved out of a hand-edited server file and into records in the organization: an assembly, its plug-in types, and steps saying which message, entity, stage and pipeline each runs on.

• The registration tools were samples. The 4.0 SDK shipped a graphical PluginRegistration tool and a PluginDeveloper console tool as source code to build yourself. The 2011 SDK says a ready-built tool arrived with SDK version 5.0.13.
• Only two stages were open to custom code, pre-event and post-event, both outside the database transaction. Each had a parent and a child pipeline. CRM 2011 maps a parent pre-event step to stage 10 and a child one to stage 20.
• CRM Online didn’t support plug-ins as of the last 4.0 SDK; online customers used workflows.
• Registrations weren’t validated. Invalid step and image settings were ignored at run time, and surfaced after upgrading to 2011 as failed solution imports. Fix them with the 2011 tool before exporting.
• 4.0 plug-ins kept running on 2011 without a rebuild, but couldn’t use the sandbox. 2011 doesn’t run plug-ins created for CRM 3.0.

The full picture, including the context, impersonation, offline plug-ins and the registration permissions, is on CRM 4.0 plug-ins.

The 2007 web services

Sources: Microsoft’s CRM 4.0 and CRM 2011 SDKs.

• 4.0 code calls /mscrmservices/2007/. Each organization gets its own WSDL and endpoint, and a discovery service finds them. On-premises deployments authenticate with Active Directory, and CRM Online with Windows Live ID.
• The MetadataService can write, which the 3.0 one couldn’t.
• The 2006 endpoint still works in 4.0 for code written against the CRM 3.0 web services, with limits.
• CRM 2011 kept the 2007 endpoint so 4.0 code could keep working, except for Office 365 organizations, but dropped the 2006 one. The CRM 2013 page covers the end of the 2007 endpoint.

Web service authentication

Sources: the CRM 4.0 SDK, and the CRM 2011 SDK for what came next.

4.0 has three authentication models. Code chooses one with CrmAuthenticationToken.AuthenticationType, and each has its own discovery service:

Deployment	How users authenticate	AuthenticationType	Discovery service
On-premises	Active Directory (Windows integrated)	0 (AD)	/MSCRMServices/2007/AD/CrmDiscoveryService.asmx
Internet-facing deployment (IFD)	Forms-based, still against Active Directory	2 (Spla)	/MSCRMServices/2007/SPLA/CrmDiscoveryService.asmx
CRM Online	Windows Live, formerly Passport	1 (Passport)	/MSCRMServices/2007/Passport/CrmDiscoveryService.asmx

• On-premises code uses Windows credentials on the service proxies and puts the organization name in the token. Discovery is optional when you already know the organization’s endpoint URL.
• IFD users still need an Active Directory account. Code sends the domain user name and password to the SPLA discovery service, calls RetrieveCrmTicket for the organization, and sets the ticket in CrmAuthenticationToken.CrmTicket with type 2. The SDK names the value “Internet-Facing Deployment authentication (formerly known as SPLA)”, the Service Providers License Agreement.
• CRM Online code retrieves a policy from the discovery service, logs on to Windows Live for a Passport ticket, then retrieves a CRM ticket for the organization. The SDK describes client-to-server, server-to-server, and server-to-server with impersonation.
• A custom ASPX page calls the services inside a using block with CrmImpersonator, which runs the code under the process identity, and CrmAuthenticationToken.ExtractCrmAuthenticationToken gets the current user’s token. Records created this way need ownerid set explicitly. The SDK’s sample covers on-premises, IFD, and the page running inside the Outlook client online or offline.
• The token carries four values: AuthenticationType, CallerId, CrmTicket and OrganizationName.

What replaced it in CRM 2011: claims-based authentication, with a signed SAML token from a security token service such as Active Directory Federation Services 2.0, alongside Active Directory. A 2011 IFD uses claims-based or Active Directory authentication, and the SDK’s proxy classes handle the exchange. The 2011 SDK sends administrators to the 2011 Implementation Guide to configure an IFD. The rest of the endpoint story is on CrmService to the Web API.

Internet-facing deployment (IFD) setup

Source: the CRM 4.0 Implementation Guide, in its 2011 revision.

An IFD lets users reach CRM from the internet without a VPN. The guide supports three configurations: internal users only, internal users plus internet access, and internet access only.

• One site, two kinds of sign-in. Internal users keep integrated Windows authentication. External users get anonymous access to the site and a sign-on page that issues an authentication ticket cookie. A request without a valid, unexpired ticket goes back to the sign-on page. The authentication strategy in web.config changes from OnPremise to ServiceProviderLicenseAgreement.
• The client’s IP address decides which. The IfdInternalNetworkAddress registry value lists internal addresses and subnet masks, separated by commas with no spaces, for example 10.10.1.1-255.255.255.0. Any other address gets the sign-on page. For internet-only access, enter the CRM server’s own address with the mask 255.255.255.255.
• Three ways to configure it: a new installation or an upgrade from CRM 3.0, each through command-line Setup with an XML file containing <ifdsettings enabled="true">; or, on an existing deployment, the Internet Facing Deployment Configuration Tool, a separate download described in KB article 948779.

Setting	XML element	Stored in	Holds
Internal network address	internalnetworkaddress	IfdInternalNetworkAddress registry value	Internal clients’ addresses and subnet masks
Root domain scheme	rootdomainscheme	MSCRM_CONFIG database	https for internet access
Web application root domain	webapplicationrootdomain	MSCRM_CONFIG database	The domain for the web application
SDK root domain	sdkrootdomain	MSCRM_CONFIG database	The domain for the web services and SDK
Discovery root domain	discoveryrootdomain	—	Appears in the guide’s sample file only

Domain values include the port when it isn’t the default, as in mycompany.com:5555. When server roles are on different computers, the web application and SDK root domains must differ.

• One DNS record per organization. Each organization is reached at https://<organization name>.<domain name> and needs a host or alias record. Remove host headers from the CRM website, because SSL doesn’t work with them. The configuration tool has a Check DNS command.
• SSL, with a wildcard certificate. Forms sign-in sends credentials in clear text, so the guide says always use SSL. The certificate must be a wildcard, such as *.contoso.com. The website takes only one certificate, so SSL can’t cover both internal and external connections.
• Moving an existing IFD to SSL means editing DeploymentProperties in MSCRM_CONFIG: set IFDRootDomainScheme to https in lowercase, and set the SDK and web application root domains to the certificate name. On non-default ports, also set the LocalSdkPort registry value. Then reset IIS and restart the Asynchronous Processing Service. The guide warns to back up first.
• Hardening the guide recommends:
  • put the Help server role on its own computer, because anonymous access makes the Help site a denial-of-service target;
  • behind ISA Server, set “Requests appear to come from original client”, or users get a Windows logon prompt instead of the sign-on page;
  • in a perimeter network, open ports to SQL Server, Reporting Services, Exchange and the domain controllers.
• Reporting on SQL Server 2005 Workgroup isn’t supported for an IFD’s Reporting Services connector, because Workgroup lacks custom data extensions, so features such as report scheduling don’t work.

Workflow in the web application

Source: the CRM 4.0 application Help.

Workflows are built in Settings. You create one, set its properties, add its logic and publish it, which moves it from Draft to Published.

• Properties: a name, one primary entity, a scope limited by the owner’s permissions, and whether it’s a workflow or a template. It also sets which events start it automatically, and whether it can run on demand, as a child workflow, or both.
• Stages group steps for readability and progress display, and don’t change behaviour.
• Steps can nest without limit. They are check condition, conditional branch, default action, wait condition, parallel wait branch (used for timeouts), and custom steps.
• Actions are create, update or assign a record; send e-mail; start a child workflow; change status; stop the workflow; or run a custom workflow action.
• Every run is a workflow job, a kind of system job you can monitor.
• Custom workflow activities are built with the SDK, and programmers can build workflows with Windows Workflow Foundation.

Upgrading from CRM 3.0

Source: the CRM 4.0 server readme, December 2007.

Before Setup:

• Stop every Workflow service. On a multi-server 3.0 deployment, running workflow jobs can otherwise be lost.
• Only one server’s workflow is upgraded. Its workflow rules, workflow assemblies and running instances are upgraded; other servers’ are not. Shut those servers down, and copy any rules or assemblies unique to them onto the server being upgraded.
• Remove custom indexes and statistics. The Environment Diagnostics Wizard warns about them, and installation may fail if you carry on anyway.

Setup can lose data:

• Notes longer than 100,000 characters are truncated.
• Some 3.0 reports can’t be upgraded, and 4.0 provides similar reports instead.
• Workflows that reference missing objects fail to upgrade, along with their jobs. Examples are missing attachments, invalid custom entities or attributes, missing workflow assemblies, deprecated attributes, and owners who no longer match their business units. Fix them in Workflow Manager and continue.

Afterwards, behaviour is different:

• Workflow jobs belong to the workflow’s owner, not the owner of the record. Record owners can stop seeing jobs running on their records until access to the Workflow and System Job entities is widened.
• Some attributes 3.0 rules could use aren’t supported in 4.0 workflows, including owneridtype, importsequencenumber, regardingobjecttypecode and isworkflowcreated on many entities.
• Status Reason changes can now start workflows. A workflow that started on a status change may now also start on a status reason change.
• Moving a user to another business unit stops their organization-scope workflows. 3.0 rules belonged to the organization; 4.0 workflows belong to a user. Reassign those workflows before moving the user.
• Appointment attendees get read-only access. Earlier versions gave activity parties full access.

Duplicate detection and data import

Sources: the CRM 4.0 application Help and server readme.

• Duplicate-detection rules work by building a matchcode for every record when a rule is published. Matchcodes for new and changed records are updated every five minutes. The default rules match accounts, contacts and leads on e-mail address.
• Checks run when a record is created or updated, when the Outlook client comes back online, and during import. Scheduled jobs catch what those miss.
• An import trap: a custom entity that once had duplicate detection enabled, then disabled, fails to import into a new system with a SQL Server error. The workaround is to turn duplicate detection back on before exporting.
• Two import tools:
  • The Import Data Wizard takes one CSV file at a time, for most users, and can update existing records and detect duplicates.
  • The Data Migration Manager is for administrators. It handles multiple related files, can transform data, and can set Created On from the source.
• Translation: customization happens only in the base language. The exported text goes out as an Excel workbook, and a translation longer than 500 characters makes the import fail.

What this page still needs

Written from Microsoft’s CRM 4.0 install media, its readme, its lifecycle page, the 4.0 SDK and Implementation Guide, and the CRM 2011 SDK’s topics on 4.0 code. Not read, and not guessed at: the separate Internet Facing Deployment Scenarios document and KB article 948779, which the Implementation Guide points to for the configuration tool.