Brutus Online

Wanneer je op onderzoek gaat in de wereld van plugins voor Microsoft Dynamics CRM 4.0, dan komen er vragen boven. Wat moet er gebeuren om een plugin te kunnen maken/gebruiken. Wat is bijvoorbeeld het verschil tussen een workflow en een plugin? Wat is de inhoud van de context gevoelige objecten? Is debuggen mogelijk en zo ja : hoe? Daar kan ik een heel mooi epistel over schrijven maar dat kunnen anderen ook.

Deze vragen worden in deze post beantwoord aan de hand van een scenario, om een beeld te krijgen van een mogelijk doel van een plugin.

Scenario

Stel : De afdeling Finance krijgt een brief binnen met daarin de melding dat een bepaalde medewerker schade heeft gereden aan de lease-auto. De Finance medewerker wil hiervan de medewerker op de hoogte stellen door middel van een email, maar er niet teveel tijd aan besteden. De stappen die de Finance medewerker dus zal doorlopen zijn de volgende :

1. Zoek de desbetreffende medewerker op in CRM.
2. Start een nieuwe email activiteit voor de medewerker.
3. Koppel eventueel een attachment aan de email.
4. Kies een template die overeenkomt met de soort brief.
5. Klik op Send.*

* Dit zou ook in bulk mogelijk moeten zijn : bijvoorbeeld alle medewerkers emailen hoeveel vakantie dagen ze nog hebben of dat de urenstaat nog ingevuld moet worden.

Omdat het over Finance emails gaan, en omdat de inhoud niet aan andere gebruikers van CRM zichtbaar mag zijn, moeten de emails afgeschermt worden, maar wel onder een medewerker komen te hangen in een soort van berichtgeschiedenis.

Het idee

Wat uit dit scenario op te maken is,  is het volgende :

Voordat een email gecreeerd wordt aan de hand van een speciale Finance template, moet de betreffende persoon in het Regarding veld (dus niet de Recipient) vervangen worden door een Finance Dossier van die persoon. De email komt hierdoor dan niet onder de History van Activities van de persoon zelf. De email komt nu in de History van Activities van het Finance Dossier van die persoon. Waarom? Omdat niet iedere CRM gebruiker hoeft te zien dat een medewerker een boete heeft gereden of schade veroorzaakt aan een lease-auto. Deze informatie is namelijk alleen nuttig voor de afdeling Finance. Dus : het dossier moet afgeschermt worden. Dit kan met behulp van Security Roles setten voor gebruikers groepen. Voordat de email verzonden moet worden,

Stap 1 : Het begin

Men neme de CRM 4.0 VPC van Microsoft, open het meegeleverde Visual Studio 2005 en start een nieuw Class Library project.

• Hernoem Class1 naar FinanceDossierPlugin (of iets anders moois)
• Leg een referentie naar de Microsoft.Crm.Sdk.dll en de Microsoft.Crm.SdkTypeProxy.dll.
• Voeg een paar usings toe :

using Microsoft.Crm.Sdk;
using System.IO;
using Microsoft.Crm.Sdk.Query;

• Implementeer de interface IPlugin met Shift+ALT+F10
• Om ook te kunnen loggen :

using (TextWriter logger = TextWriter.Synchronized(File.AppendText(@"C:\Program Files\Microsoft Dynamics CRM Server\Trace\FinancePlugin.txt")))  {
//plugin code
}

• Een try… catch om de code heen om InvalidPluginExecutionException af te vangen :

try {

}
catch(Exception ex)
{
string logMessage = "Exceptie in de Finance plugin: ";
log.WriteLine(logMessage + ex.Message);
throw new InvalidPluginExecutionException(logMessage, ex);
}

• Nu gaan we bepalen of we in de goede context zitten :

if (  context.InputParameters.Properties.Contains(ParameterName.Target) &&
context.InputParameters.Properties[ParameterName.Target] is Microsoft.Crm.Sdk.DynamicEntity
)
{
Microsoft.Crm.Sdk.DynamicEntity entity = (Microsoft.Crm.Sdk.DynamicEntity)context.InputParameters.Properties[ParameterName.Target];
if (entity.Name != EntityName.email.ToString())
{
log.WriteLine("De entiteit in deze context is geen email maar " + entity.Name);
return;
}
if (context.Stage != (int)Microsoft.Crm.Sdk.MessageProcessingStage.AfterMainOperationOutsideTransaction)
{
log.WriteLine("Plugin moet in post-stage runnen!");
throw new InvalidPluginExecutionException("Plugin moet in post-stage runnen!");
}
// Business Logic
}
else
{
log.WriteLine("Verkeerde context...");
return;
}

In regels 1 t/m 4 kijken we of de Message wel een Create opdracht is. Aan de hand van de target kun je dat bepalen. In regel 7 t/m 11 kijken we of het een email bericht betreft. We willen natuurlijk een actie uitvoeren voordat de email verstuurd wordt. In regel 12 t/m 16 wordt gekeken of we daadwerkelijk wel in de post-stage zitten.

Stap 2 : Business logica

Nu de business logica. De email moet dus voordat deze verzonden wordt het regarding veld omgezet hebben naar een bij een medewerker behorend contactpersoon. Hiervoor hebben we het Id van de email nodig omdat hier aan een contactpersoon gekoppeld zit. Met het emailId kunnen we het contactId ophalen, die we daarna kunnen gebruiken om de bijbehorende Finance Dossier op te halen en die te koppelen aan het regardingobjectid van de email. Vervolgens moet de email geupdate worden. De email wordt namelijk voor het verzenden opgeslagen als Activity.

ICrmService service = context.CreateCrmService(false);   Guid EmailID = Guid.Empty;
Guid ContactID = Guid.Empty;
Guid FinanceDossierID = Guid.Empty;

if (context.OutputParameters.Properties.Contains(ParameterName.Id))
{
EmailID = new Guid(context.OutputParameters.Properties[ParameterName.Id].ToString());
if (entity.Properties.Contains("regardingobjectid"))
{
email deEmail = (email)service.Retrieve(EntityName.email.ToString(), EmailID, new AllColumns());
if(deEmail.regardingobjectid.type == EntityName.contact.ToString())
{
ContactID = deEmail.regardingobjectid.Value;
DynamicEntity financeDossier = RetrieveFinanceDossier(ContactID, service);
Key financeSleutel = financeDossier.Properties["new_financedossierid"] as Key;
FinanceDossierID = financeSleutel.Value;
}
deEmail.regardingobjectid.type = "new_financedossier";
deEmail.regardingobjectid.Value = FinanceDossierID;
service.Update(deEmail);
}
} 

In regel 1 halen we de context afhankelijke CrmService op. Deze gebruiken we in regel 11 om de huidige email op te halen met alle kolommen. Om de custom entiteit op te halen die new_financedossier heet, heb ik een method gemaakt die RetrieveFinanceDossier heet.

In regel 12 t/m 18 verkrijgen we het FinanceDossierId die we nodig hebben om in regel 19 t/m 20 te koppelen aan het regardingobjectid van de email. In regel 21 updaten we de email.
Aan het einde van deze post-send executie van de plugin, wordt de geupdate email verstuurd. Maar voordat onze plugin uberhaubt iets gaat doen, moet deze uiteraard eerst gedeployed worden.

private DynamicEntity RetrieveFinanceDossier(Guid ContactID, ICrmService service) {    ConditionExpression con = new ConditionExpression();
con.AttributeName = "new_financedossierlookupid";
con.Operator = ConditionOperator.Equal;
con.Values = new string[] { ContactID.ToString() };
FilterExpression filter = new FilterExpression();
filter.FilterOperator = LogicalOperator.And;
filter.AddCondition(con);
QueryExpression query = new QueryExpression();
query.EntityName = "new_financedossier";
query.ColumnSet = new AllColumns();
query.Criteria = filter;
RetrieveMultipleRequest retrieve = new RetrieveMultipleRequest();
retrieve.Query = query;
retrieve.ReturnDynamicEntities = true;
RetrieveMultipleResponse retrieved = (RetrieveMultipleResponse)service.Execute(retrieve);
if (retrieved.BusinessEntityCollection.BusinessEntities.Count == 1)
{
return (DynamicEntity)retrieved.BusinessEntityCollection.BusinessEntities[0];
}
else
{
return null;
}
}

Stap 3 : Plugin deployen

Voordat de CRM server de dll slikt, moet deze eerst gesigned worden.

• Sign het project door met de rechtermuisknop op het project klikken, Properties te kiezen en vervolgens het tabblad Signing.
• Vink “Sign the assembly” aan.
• Klik in de dropdownbox op New..
• Kies in de popup een naam voor de plugin keyfile.
• Zet het vinkje “Protect my key file with a password” uit.
• Klik op OK.
• Build het project.

Nu het project gesigned is, hebben we de PluginRegistrationTool nodig. Deze is standaard meegeleverd met de SDK, maar die moet je dan nog wel zelf builden. Pas wel op dat je de referentie naar de webservices aanpast, voordat je gaat builden. Wanneer de build succesvol is, is het aan te raden om de Plugin Registration tool als Tool in Visual Studio op te nemen :

• Klik op tools, External Tools.
• Klik in de popup op Add, en vul een naam.
• Zoek de zojuist gebuilde executable op bij Command.
• Vink “Use Output window” aan.
• Vink “Close on exit” uit.
• Klik op OK.

Start nu de geregistreerde Visual Studio tool. Om connectie te kunnen maken met je CRM server moet je een paar connectie gegevens invullen :

• Een label (voor meerdere connecties)
• Discovery Server (meestal localhost)
• Poort (op de CRM 4.0 VPC van Microsoft is dat standaard 5555)
• Domain niet invullen
• User Name = administrator (moet als Security Role in CRM in de groep “System Administrators”)
• Klik op Connect
• Voer een wachtwoord in.
• Nu de CrmService Url en de MetaDataService Url in beeld zijn, klik op Connect.

Hieronder een screenshot van de Plugin Registration Tool :

Zoek nu je zojuist gebuilde assembly op en kies voor de optie Disk (voor het debuggen in het Stap 4)
Klik op Register Selected Plugins, gevolgd door OK van de popup.

Nu ga we een Step toevoegen. Een step is een actie die uitgevoerd moet worden. Een image is een exacte kopie van deze step, maar is alleen nodig als je meerdere servers hebt waar CRM op draait.

• Klap de Assembly op en klik met de rechtermuisknop op de plugin en kies “Register New Step”.
• Dit scherm gaat het om. Hier voeren we de Step gegevens in.

• Voer bij message “Create” in. Dit omdat we voordat een email gecreeerd (en verstuurd wordt) deze stap uit moet voeren.
• Voer bij Primary entity “email” in
• Voer bij Secondary entity “none” in.
• Klik op “Register New Step”

De nieuwe stap staat in de treeview onder de assembly. Naast de Create message kun je ook nog andere messages (voor andere stappen of steps) afvangen zoals Update of Delete.
Nu gaan we de plugin testen.

Stap 4 : Testen

Voor het testen gaan we in CRM gaan we naar de browser van de client en selecteren een medewerker.

• Open het scherm voor de medewerker.
• Klik op “Send Email”
• Kies nu een template uit die je eerder aangemaakt hebt en klik op OK.
• Zoals je ziet in onderstaand screenshot is, staat er in het regarding veld de medewerker naar wie we de email gaan sturen. Deze wordt zometeen door de plugin gewijzigd in het bijbehorende Finance Dossier.

• Klik nu op “Send” om de email te verzenden.

Om te kijken of alles gelukt is, gaan we naar de medewerker zijn Finance Dossier en zien daar een email staan die verstuurd is, aan de hand van een template.
Open de email en zie dat het regarding veld verander is van de medewerker zijn of haar bijbehorende Finance Dossier :

En zoals ze in die filmpjes van Channel9 en ASP.NET altijd zo mooi kunnen zeggen : “And there you have it…” .

Opmerkingen

Een paar opmerkingen betreft deze uitwerking :

1. De code in dit artikel houdt geen rekening met de selectie van meerdere medewerkers.
2. Wanneer je een contactpersoon (medewerker) enkel selecteerd en vervolgens op de email knop klikt, een template kiest en “Send” kiest, wordt de email niet aan een Finance Dossier gekoppeld (lees : komt in de History van bijbehorend Finance Dossier te staan). De email wordt in dit geval aan de History van de persoon zelf gekoppeld.
3. Voor bulkmail naar meerdere contactpersonen (medewerkers) moet je je step anders configureren. Misschien behandel ik dit in een volgende post.

Tracing

Indien je tracing aangezet hebt voor CRM, kun je naast onze eigen plugin-logfile (FinanceDossier.txt) ook andere logging vinden in de volgende map :

C:\Program Files\Microsoft Dynamics CRM Server\Trace\*.*

Debugging

Het debuggen van je plugin word goed beschreven op deze site van Robert John.

Tijdens het debuggen is het handig om je Dynamic Entity objecten weer te kunnen geven. Net als de standaard Debugger Visualizers van Visual Studio kan dat als je de stappen van deze site van Simon Hutson uitvoerd.

Tenslotte

Mijn blogposts zijn persoonlijk en schrijf ik in eigen tijd. Ze beschrijven meestal onderzoeken die ik voor mijn werk doe, maar dat geeft niet per definitie aan hoe ik bij Sogyo te werk ga.
Plugins worden door Microsoft tot op zekere hoogte ondersteund, maar je blijft altijd zelf verantwoordelijk voor je code.

Mocht je vragen hebben met betrekking tot deze post of heb je hulp nodig met andere aanverwante CRM activiteiten, dan hoor ik dat graag!

This entry was posted on Wednesday, April 1st, 2009 at 12:43 and is filed under C#, CRM. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.