Support Portal ContactGet in touch

Calling a Dynamics 365 Action using the Organisation Webservice

   Words by Paul McQuillan

   on 27/12/2018 13:00:00

Dynamics allows us to invoke System or Custom Actions from an external App or internal Plugin using a small amount of code to call the Organisation Webservice.

This can be useful for keeping our Business Logic in the Action, but re-using this Business Logic from our Custom App or Custom Code.

Dynamics 365 performs a variety of ‘out-of-the-box’ System Actions that we can invoke in the same way, particularly the SetWordTemplate Action which can be useful to generate new Documents from the Templates in CRM.

If we look at how this would be invoked from a Workflow, we can see how this is similar from Custom Development:

image

Looking at how we invoke the System Action for SetWordTemplate

This allows us to gauge the Parameters expected for the Action and design our code accordingly – so for the SetWordTemplate Action, we have two Input Parameters that we would specify:

  • SelectedTemplate
    • Entity Reference to point to the ‘documenttemplate’ record that we want to use as our Template
  • Target
    • Entity Reference to the Record in Dynamics that we want to Generate the Document for

We can then apply this in our App or Plugin code quite easily:

OrganizationRequest actionRequest = new OrganizationRequest("SetWordTemplate");

actionRequest["SelectedTemplate"] = new EntityReference("documenttemplate", myTemplateId);

actionRequest["Target"] = new EntityReference(myCrmRecordType, myCrmRecordId);

OrganizationResponse actionResponse = service.Execute(actionRequest);

This code will then invoke the Action in the same way as calling from a Workflow or other Action would.

This works for our Standard Dynamics Actions, but works in the same fashion for Custom Actions that we may add to CRM.

If we take the following simple Custom Action:

image

Building a simple Custom Action that we can then invoke from Code

This Custom Action implements a single component of our Opportunity Sales Process to generate the Template Document for an Opportunity, Set the Proposal Date to Today and then send an Email to the Customer to inform them that the Proposal is ready for review.

We could invoke this Action as part of our wider Opportunity Business Process Flow, or alternatively invoke from our Custom Code in the same fashion as we saw for the System Action:

(but taking note of the different parameters and invoking accordingly)

OrganizationRequest customActionRequest = new OrganizationRequest("crmcs_ExampleCustomAction");

customActionRequest["OpportunityRecord"] = new EntityReference("opportunity", myCrmOpportunityRecordId);

customActionRequest["Target"] = new EntityReference("opportunity", myCrmOpportunityRecordId);

OrganizationResponse customActionResponse = service.Execute(actionRequest);

This will then invoke our Custom Action and the Steps of logic within – keeping the logic contained within the Action and helping us avoid duplicating the logic in multiple Plugins or Apps, and so helping us maintain one common Business Logic layer that other Apps or Plugins can invoke rather than duplicate.

Custom Actions can also be invoked from other Workflows or even other Actions to complete the concept of re-using our Business Logic from multiple Triggers:

image

Invoking our Example Custom Action from another Action

This gives us a range of options for how the logic can be invoked.

What is the Target Parameter?

One point we will notice here is the Target Parameter – this is automatically added to any Action we implement as the base record that we pass into the Action. 

By default, this is the Record of a particular Entity Type that we are running the Action from, and so identical to how we run a Workflow against a particular Record of the selected Entity Type.

But – the Target Parameter is similar to the Regarding Record for a Task or other Activity in Dynamics, allowing the ability for any Record to be passed into the Action as the Record that the Action is being run about.

So in our above example of the System Action, this is the Record (and essentially any Record) that we want to generate the Document for – as we could want to generate a Document for any possible Record of any possible Type in Dynamics.

We see this Target is any of the Custom Actions we create, or any of the System Actions we invoke, indeed any call to an Action will fail if the Target Parameter is not supplied as the Primary Record we are running the logic about.

image

The Target Parameter in Code is our Primary Entity in Workflow

Global Actions

Typically when we create an Action, we supply the Type of Entity we want people to run this Action for.  This is a hold-over from Workflows that need to be run under the context of a particular Entity, and so the default behaviour of a new Action is similarly to be run from a particular Type of Entity in the same way.

However, as we have seen, the Target Parameter is neutral of any particular Entity Type and so we can define Actions that are similarly independent.

This is done by creating our Action and setting the Entity to ‘None (global)’ – which is an option that only appears when creating new Actions:

image

Creating a Global Action that is not tied to triggering from a particular Entity Type in Dynamics

This creates the same Action but without a default Primary Entity to work with inside Workflow – as Dynamics has no ability at Design-Time to know what type of record would be supplied prior to Run-Time:

image

The Global Action must invoke EntityReference Parameters with a known Entity Type at Design-Time for the Update Step to be usable

However, in code we can make strong use of Global Actions by supplying whatever Primary Record / Target as we need within code:

OrganizationRequest customActionRequest = new OrganizationRequest("crmcs_GlobalAction");
customActionRequest["Target"] = new EntityReference(someRecordType, someRecordId);
OrganizationResponse customActionResponse = service.Execute(customActionRequest);

This gives a flexible and manageable way of controlling how different elements of our Business Logic can be designed and invoked.

  • "Paul has made a real difference to how my team of 24 people record and store valuable customer data and sales opportunities. Highly recommended."

    James, Operations Director

  • "Understanding your business allows us to advise when to implement aspects of CRM and, likewise, when not to."

    Paul McQuillan, Managing Director

  • "Dynamics 365 and CRMCS have made a real lasting difference to our business, allowing us to replace older systems that were holding back our performance."

    Grahame, Chief Operating Officer

  • "James worked well with us to help connect CRM with Outlook and relate how this might benefit our team using CRM for Property Care."

    Natalie, Property Care Supervisor

  • "Matt was really good with helping us run User Testing on the new Compliance Module of our CRM System."

    Tom, Compliance Administrator

Prefer to go old-school?

Write to us using the below addresses.

Head Office
CRM Consultancy
61 Oxford Street
Manchester
M1 6EQ

London Office
CRM Consultancy London
Grosvenor Avenue
London

Content © CRM Consultancy.