Vince Bullinger

Writing A CRM Callout Assembly: A How To

I was recently asked to write a callout assembly to be attached to a client's CRM workflow service.  A callout assembly (in this regard) is an assembly that is attached to the CRM workflow service and is sort of like an external event handler.  So when someone adds/updates/deletes records in CRM, the callout assembly is fired.  I had never done it before, but I thought it wouldn't be too much of a problem.  There are some samples in the CRMSDK and I was sure that searching on Google and MSDN would yield the answers to any questions I'd have.  I was wrong.

There isn't too much help in either of those two sources, as I found out the hard way.  This possibly isn't the most common thing in the world to do, I'm guessing.

The problem I had with the "readme"s in the callout samples given in the CRMSDK is that they just blindly say "do this" and "do that," without any explanation of what's going on.  They also missed a step, as far as I can see.  They don't explain the callout.config.xml file at all.  I'll attempt to explain things, step-by-step, since I don't really see a definitive explanation of how these callout assemblies work anywhere (I've seen similar posts on other blog sites with less information, however).

Step 1: create a blank solution with a class library project inside.

Step 2: add a web reference to your CRM web service.  It should look something like this: http://<yourserver>/mscrmservices/2006/CrmService.asmx, as the readme got correct.  If you need to login, you better have all that information handy, as you'll need it later.  This information will include: a) user name b) password c) domain d) CRM server.

Step 3: add a reference to the Microsoft.Crm.Platform.Callout.Base.dll file.  If you need to download that, you should do so.  I had to.  This is necessary for the next step.

Step 4: create a class for your callout that extends the CrmCalloutBase class.  You will need the dll from the previous step to do this.  Make sure this class has "using Microsoft.Crm.Callout;" in the using directives for the base class and "using <yourassemblyname>.<yourwebreferencename>;" for the web service.  If you are ever going to need to connect to the web server (say, if a child object is updated/added/deleted, the parent needs to update its information, for example), then you'll need the user name, password, domain and CRM server information from before.  You'll need this code to access the CRM web service:

CrmService service = new CrmService();
service.Url = <CRM_SERVER> + "crmservice.asmx";
service.PreAuthenticate = true;
service.Credentials = new NetworkCredential(<CRM_USER>, <CRM_PASSWORD>, <CRM_DOMAIN>);
WhoAmIRequest userRequest = new WhoAmIRequest();
WhoAmIResponse userResponse = (WhoAmIResponse)service.Execute(userRequest);

And your service is now ready to use.  I.e. if a child's information is edited, you may want to use the web service to update the parent.  This may be the whole reason for creating a callout assembly.

Step 5: decide what events you want to listen into.  Do you want to react to whenever a case is submitted?  Do you want to react to whenever someone updates their contact information?  Do you want to check submitted information before it gets submitted?  Whatever it is, there are plenty of things to listen into.  To find out what you can listen to, inside your class, start a new line (with intellisense enabled) and type override and then a space to see what possibilities you have.  For quick reference, there's pre- and post-:

• Create
• Update
• Delete
• Assign
• Set state
• MergePersonally
• PreSend
• PostDeliver

Step 6: implement the code you want to fire when your event is triggered.  You can override a bunch of methods (all of them, actually) in the same callout class, so feel free.  I overrode three in mine.  I don't quite understand why the entity context is passed, as you can set your event to only listen for when an event is fired for an entity of a particular type.  I personally don't have any code in my callout I just wrote that worries about what type of entity I'm dealing with.

Step 7: create the callout.config.xml file.  Assuming you're using CRM 3.0, you should have this line of code as your second line of code instead of the ones in the CRMSDK samples: "<callout.config version="3.0" xmlns=" http://schemas.microsoft.com/crm/2006/callout/">" or your config file might not be recognized.  Inside the callout config file, you'll need a <callout> node for each event/entity combination you are listening into that looks like this: <callout entity="myentityname" event="Post/Pre<see above bulleted list for ideas>"> with an optional onerror property with the value of "abort" or "ignore."  Inside this node, you'll need a subscription node that looks something like this: <subscription assembly="myassembly.dll" class="myfullnamespace.myclass(from step four)">.  Inside this node, you'll need one or more <postvalue> nodes IF you are listening in on a "Post" event (not a "Pre" event).  Each of these <postvalue> nodes needs to have the name of a property of the entity you are going to work with in your code.  For example, if you working with an incident entity and want to look at the ticket number in your callout assembly's class, you'll need this inside your subscription node: <postvalue>ticketnumber</postvalue>.  One short cut, if you're going to use a lot of properties, or an expanding number of properties (in case your assembly will be modified as time goes on) or if you're just really lazy is to put this in your subscription: <postvalue>@all</postvalue>, and you'll then get all of the properties.  That's what I did.  Mainly because I knew that the objects don't have a lot of properties.  I would also suggest writing to a log file throughout your code so you can debug more easily.

Step 8: compile your code and attach it.  Attaching it is pretty tricky, so make sure you pay close attention.  I am not sure you'll need to do all of these things, but I did, so here's what should work for sure.  First, go into the services console (of the CRM server...) and stop the Microsoft CRM Workflow Service.  Next, if you've already deployed a previous version of your callout assembly, RENAME IT.  It won't let you delete it, but you can rename it...  Then, move (the new version of) your callout assembly to the \Program Files\Microsoft CRM\Server\bin\assembly folder.  Then, restart IIS.  I'll wait...  Ok, now start the Microsoft CRM Workflow Service.  Delete the old assembly (the one you renamed) if this isn't the first time you deployed it.  IF YOU MAKE ANY CHANGES TO THE DLL OR THE CALLOUT.CONFIG.XML FILE(S), YOU MUST REPEAT STEP 8 OR IT WON'T TAKE EFFECT!

That should do it!  Now, if you have trouble getting into the workflow or think it's too restrictive/not powerful enough, you can write C# code (or VB code, if you are so inclined) that can do whatever you want and then just attach it to the workflow process using the process outlined above.  Happy calling out!