WebApi batch request

The WebApi in Dynamics CRM has the option to send batch requests. This reduces the number of calls from client to server and when e.g. you need to delete a lot of records from JavaScript it saves time processing these deletes.

Unfortunately, creating a batch request is not as straight forward as doing a POST call for example. The MSDN documentation is a good starting point, but then I still had some trouble making it work. I’ve created a question on stackoverflow and the Dynamics Community. As I needed the functionality I kept trying different options and reading the documentation and I finally figured it out.

It’s very important that you build the content in the batch request as documented with MSDN. Also note that when you do a delete batch request you still need to send an empty object. With a single delete call to the api you don’t have to explicitly do this. Another things that’s a bit hard creating a batch request, the errors that are returned are not existent. You just get an empty result and you have to figure out yourself what you have done wrong.

This is the request if you’re using jQuery to do the call.

$.ajax(
{
    method: 'POST',
    url: 'http://crm/api/data/v8.0/$batch',
    headers: {
        'Content-Type': 'multipart/mixed;boundary=batch_' + batchId,
        'Accept': 'application/json'
    },
    data: payload
});

And here’s the way to build the payload:

var data = [];
data.push('--batch_123456');
data.push('Content-Type: multipart/mixed;boundary=changeset_BBB456');
data.push('');
data.push('--changeset_BBB456');
data.push('Content-Type:application/http');
data.push('Content-Transfer-Encoding:binary');
data.push('Content-ID:1');
data.push('');
data.push('POST http://tenanturl/api/data/v8.0/accounts HTTP/1.1');
data.push('Content-Type:application/json;type=entry');
data.push('');
data.push('{ "name": "batch acount 2"}');
data.push('--changeset_BBB456');
data.push('Content-Type:application/http');
data.push('Content-Transfer-Encoding:binary');
data.push('Content-ID:1');
data.push('');
data.push('DELETE http://tenanturl/api/data/v8.1/accounts(52eb1677-427b-e611-80bb-0050568a6c2d) HTTP/1.1');
data.push('Content-Type:application/json;type=entry');
data.push('');
data.push('{}');
data.push('--changeset_BBB456--');
data.push('--batch_123456--');

var payload = data.join('\r\n'); 

Easy contact form to CRM lead using Microsoft Flow

Many companies are looking for an easy solution to process a contact form on their website to a lead in CRM. In this post I’ll provide an easy, self service solution that requires no code.

Tools

To build this solution we are assuming you use the following tools.

  • You have Dynamics 365 for Customer Engagement
  • Microsoft Flow is enabled in your Office 365 tenant
  • You are ok with using Cognitoform or any other form tool or custom code that can post the form data to an url
  • You already use WordPress and Contact Form 7

I’ll be using a generic approach where you parse the json data from a webhook call. The tool above also has a built in connector to Microsoft Flow. That would even be a better option, but not all platforms support Flow. This approach is very easy to implement for a developer building your website.

Setup

The first thing we need to create is the basic Microsoft Flow. Go to Microsoft Flow and log in with your Office 365 credentials. Create a new flow and start with a blank canvas. The first step is adding a trigger. The trigger you are looking for is the Request trigger. Select it and don’t fill out anything just yet. Next, add the Dynamics 365 connector and configure it to create a lead in your CRM instance. For now just use some dummy values. Save your flow and notice that you’ll get a request url in the Request trigger. Copy that so we can use it in the Cognitoform setup.

It’s pretty easy to setup a test account with Cognitoformand and create your first form. It took me less than 5 minutes. After you are done configuring your fields, you want to go to the submission settings on the bottom of the page. Add the Flow url in the “Post Json data to a website”:


Test your form and return to your flow and you’ll likely see one run has failed. That’s ok for now. Click this failed run and look for the request body of the trigger. Copy that:

Edit your flow and click the Request trigger. Click “Use sample payload to generate schema” and paste in the json from the previous step. Now you have defined the schema from the request and you can use those schema values to create the lead. Click the “Create record” step and use the defined values form the previous step to enter the values for your CRM fields.

Now you’re all setup. Fill out a form a see that a lead is created in CRM.

New: the Scribe Online Toolbox

Six years ago, I started working with Scribe and since then I use some Scribe component in almost every project I do. With Scribe Online as my no. 1 integration platform I’ve been able to take most of my integration requirements to a success.

When you work with Scribe Online a lot, you notice some features are missing. Features that don’t affect the integration itself, but that make your life as a Consultant or Developer easier. Well here is www.scribeonlinetoolbox.com. Together we should make life easier!

Let’s make a wishlist:

  • Bulk enable/disable Solutions – one of the connecting application goes into acquaintance mode. Your Solution tries to connect every 5 minutes, but since the application is down, email start to run. Would it be easy to just enable or disable a couple Solutions with one click?
  • Bulk enable/disable Maps – exactly the same as above, but now for Maps 🙂
  • Easy transfer Maps from one Solution or Org to another – most customers have separate Orgs for their dev, test, acceptance and production. It would be great to have the possibility to just transfer a Map from one Org to another without the need to download and upload the json file, modifying the name, validating etc.
  • Documentation in one click – a nice presented Word file with your block-structure and mappings in place? (ps. I know about the Google Docs tool, but let’s face it… it’s Google Docs….)

I’m sure you can think of more tools we might need ;-). For now, I started with the first one and will continue to work on the other tools. Please let me know if you have any ideas or what you think of the Scribe Online Toolbox :-).


Hidden feature: OpenAPI Spec for Scribe Online Request/Reply Maps

Since Scribe launched the Request/Reply functionality, it’s hard for me to think of any project where it couldn’t be used. For those of you who don’t have any idea what I’m talking about: Scribe Online Request/Reply offers the capability to create you own WebApi without any coding. With just a few clicks, you are able to get a url and define any (complex) logic behind. If you want to read more on Scribe Online Request/Reply, check out this blog post by Paul Varley.

OpenAPI Specification / Swagger

With the ability to create and customize your own WebApi rapidly, the need for a specification about your API grows. Especially when you provide the API to customers or partners. Lucky for us, someone thought of this. The world of API’s has embraced an open standard for API specifications. This standard – formerly know as Swagger – is called OpenAPI Specification. You can read all about it at https://swagger.io/.

How to get a specification on my Request/Reply?

This is where the fun part starts, cause it’s so-so-simple! When you create your Request/Reply, you get the endpoint url. Let’s say it’s like this:
https://endpoint.scribesoft.com/v1/orgs/123456/requests/1234?accesstoken=XYZ

Now in order to get the OpenAPI Specification, all you need to do is to add ‘/api-docs’ at the end of your url, right before the parameter! It’ll be like this:
https://endpoint.scribesoft.com/v1/orgs/123456/requests/1234/api-docs?accesstoken=XYZ

Now dump the url in your browser and you’ll get the OpenAPI Specification you want. In a next blog, I’ll tell you all about how you can use this together with Microsoft Flow.

Creating an activity through the CRM WebApi

Recentely I had to create a phonecall activity through the WebApi in Dynamics 365 CRM. As most WebApi calls are pretty straight forward, I didn’t think much of this task, although I haven’t done this before. As I knew activities are special in CRM I looked around to see examples and couldn’t find any good ones. Therefore I’m writing this post, to make sure I have an example on hand when I need one.

Endpoint

To create an activity you use the relevant endpoint. These are /api/data/v9.0/phonecalls, /api/data/v9.0/emails, ect. Maybe there’s an option to use the generic endpoint, but I haven’t tested this.

Json message

For a phonecall the Json message could look like this

{
    "description" : "Lorem ipsem",
    "directioncode" : true,
    "leftvoicemail": false,
    "regardingobjectid_account@odata.bind" : "/accounts(EA82D93B-CFD9-E711-812D-E0071B6C2F31)",
    "subject" : "lorem ipsem", 
    "phonecall_activity_parties" : [
        {
            "partyid_systemuser@odata.bind" : "/systemusers(5549B1A7-A7CD-4047-84CC-64BA1FF4756F)",
            "participationtypemask" : 1
        },
        {
            "partyid_contact@odata.bind" : "/contacts(4F2D083E-D3D8-E711-812C-E0071B6C2F31)",
            "participationtypemask" : 2
        }]
}

Validate your IBAN bank numbers

During multiple implementations of Dynamics 365 for Customer Engagement or Dynamics 365 Business Central, we get the question weather it’s possible to validate the entered IBAN bank account numbers and generate the BIC / Swift code. Especially when companies use Direct Debit as a payment method, you want to make sure the IBAN is correct.

I’ve created a simple REST service based on Azure Functions to validate the entered IBAN bank account number and provide the name of the bank and the BIC / Swift code.

How it works

Let’s start with testing this in your browser. For now we want to check if an IBAN is valid. We can do that by combining the url below with and IBAN (for instance NL63TRIO0379272687).
URL: https://iban-validation.dynamics365blog.nl/api/IBANCheck?iban=NL63TRIO0379272687
You’ll get back all the information you need:

{
    "valid": true,
    "messages": null,
    "iban": "NL63TRIO0379272687",
    "bankData": {
        "bankName": "TRIODOS BANK N.V",
        "bic": "TRIONL2U"
    }
}

Currently for Dutch and Belgian IBAN, but more coming!

Currently, the REST service only Dutch and Belgian IBAN bank numbers. If you want to have other countries supported, please provide me a url in de comments where I can find a list of banks and their local bank identifiers. If you’ve proved the url I will setup the new country as soon as possible.

Using Dynamics 365 CRM lookups and alternate keys in Microsoft Flow

I’ve written a blog a while ago on using alternate keys with the Dynamics 365 / CRM WebApi. You can read the blog here. The post guides you in creating an alternate key and identifies some usage scenario’s.

Lately I’ve been working on an integration between Eventbrite and Dynamics 365 / CRM with Microsoft Flow. Currently I’m going back and forth between enthusiasm and disappointment. Sometimes it does more than you would expect and sometimes you’re missing the details you are looking for.

Lookup

Most often you would want to set a lookup value in a record you are creating and updating. With flow this might be a bit hard as looping is cumbersome, or even impossible, to implement (e.g. nested loops are not supported).

The first thing you could do it set hard coded values. E.g. when creating a product in CRM it’s sometimes feasible to hard code the unit of measure. Simply pasting in the Guids works fine in such case:

Alternate key

Other time you want want to set a lookup to a record you are also integrating. E.g. with Evenbrite you have the ‘entity’ Events that I integrate with a custom entity Events. Event tickets I’m integrating with a custom entity Event tickets. On that event ticket entity I need to set the lookup to the related event. One option would be query for the event in CRM using Flow and setting the value.

However, to simplify things, I’ve created an alternate key on the Event entity in CRM, using the EventId from Eventbrite. Now setting the lookup is fairly easy, and we don’t have to query CRM to fetch the record. This sample works perfectly:

Conclusion

For now, Microsoft Flow seems to be a perfect tool to do lightweight integration scenario’s. Using alternate keys might really help in making your life a little easier in extending the options you have with Microsoft Flow.

Create a Dynamics 365 trial in just a few clicks

This post will let you create a Dynamics 365 trial real quick. All you need to have in place is an Office 365 instance and a Dynamics 365 (trial) license. Creating the trial for Dynamics 365 can be useful to test some things in new versions or if your trial instance is stuck.

Error when creating a Dynamics 365 trial: “no instances found for this user ID”

I’ve had it numerous times: you create an Office 365 trial and want to add a Dynamics 365 trial to the tenant. You go to the “purchase services” section and select the trial for Dynamics 365. Unfortunately, the Dynamics 365-tab is not showing up at the “Admin centers” section and when you go to the Dynamics 365 management url you get an error. No instances found for this user ID. Bugger! Now what?

Create a Dynamics 365 trial org in just a few clicks

In order to create a new Dynamics 365 trial org for testing purposes – or just because you wanted a trial org in the first place – you need to make sure that you have a Dynamics 365 license in place and added to your user profile. Haven’t got a (trial) license? Go to the “Purchase services” section and add a trial.

Now go to this url: https://port.crm4.dynamics.com/G/Setup/ConfigureNewEmailTrialInstance.aspx. You’ll get a form you’re probably familiar with. Just fill out the form, wait a few minutes and your trial org is ready for use!

 

Using alternate keys with the WebApi

Alternate keys are very powerful feature in Dynamics 365 / CRM. Especially when you are integrating with other systems it’s very helpful to use alternate keys to efficiently retrieve and update records. In this blog post I’ll guide you through creating alternate keys and using them in retrieving, updating and upserting records.

Creating an alternate key

The first thing you need to do is to create a field that holds the alternate key. Please keep in mind that you can only use the field types: Decimal Number, Whole Number and Sinlge line of text for an alternate key. There’s also a maximum of five alternate keys per entity and a restriction in size. For a full reference visit the documentation.

When you created the field you need to go to the keys of the entity and create the alternate key. The key can be a combination of multiple fields. In this example I kept it simple by using one field:

For the key to work, a system job needs to run to create an index. Please check if this is successful. The key I created for this blog post had an error on the first try.

Creating an account

Setting the alternate key in the request is the same as setting the value of any other field:

url: /api/data/v8.2/accounts
method: POST
body: {
	"name": "Alternate key account",
	"blg_alternatekey" : "blg12345"
}

Retrieving a record

Retreiving a record is quite simple. Normally you would use a get request to /account(0000-000-000-000-000) to retreive a single record using the guid of the record. Using an alternate key the request is this:

url: /api/data/v8.2/accounts(blg_alternatekey='blg12345')
method: GET

Here you can see that instead of using the guid, you need to use the field name of the key (not the keyname) and the value to retrieve the account.

Updating a record

The sample to update the record:

url: /api/data/v8.2/accounts(blg_alternatekey='blg12345')
 method: PATCH
 body: {
     "name": "Alternate key account updated"
}

The nice thing with the PATCH request like this is, that by default it will update the account if it exists, or it will create the account if it doesn’t exist. This is a great feature for integration scenario’s with other systems.

Navigation properties

You can also use the alternate key for setting a lookup value. In this example we will create a contact for the account created above.

url: /api/data/v8.2/contacts
method: POST
body: {
	"firstname" : "john",
	"lastname" : "smith",
	"parentcustomerid_account@odata.bind" : "/accounts(blg_alternatekey='blg12345')"
}

Conclusion

Alternate keys are a great feature, especially when you’re integrating with other systems. It’s good to see that the WebApi has full support for this, even with upsert requests and using it in navigation properties. This saves writing a lot of logic and a lot of calls getting guids from Dynamics365 / CRM.

Authenticate to the Dynamics 365 oData API with AppId and Secret

Authentication to the Dynamics 365 oData API (CRM) is something that all CRM Developers have been busy with. Previously, this was done by a normal user. The downside of this method is that the CRM web interface can be used with this user as well. Some versions ago, Microsoft introduced the concept of “Non-Interactive” users (see this article). This was already a huge step forward from security point of view. We could use a user now that didn’t have access to the web interface. There is still a downside to this: a username and password need to be stored somewhere. Since a username mostly has some kind of logic in it’s name, this can be predicted and may be available with an attack. Conclusion: still not so secure as you’d want to.

Introducing the AppId for Dynamics 365 oData API

Microsoft created the ability to authenticate to the Dynamics 365 oData API with the use of an AppId (in the December 2016 update)! Together with a secret, this replaces the username and password. Guess what: readability and logic are far more complex with an AppId and a secret, than usename and password. Again a great step forward in security. So to wrap up:

  • A username and password are readable and therefore less safe
    Username: api-user@domain.com
    Password: somePassword
  • An Appid and Secret are far more difficult to read and therefore safer
    AppId: 82068d67-54a7-4698-a4eb-876dcc90b9d1
    Secret: BD”m_hIy461-E!p&;u0l@7sPCvp?579MA`iU3ek|5rD]V

If you want this, please read on and I’ll describe what steps you should take to use this new feature.

Steps to take to implement the AppId

A quick overview of the steps for the quickies is here:
1. Create an Application with AppID and Secret in Azure Active Directory
2. Assign the Dynamics CRM Online API rights to the Application
3. Create an application user in CRM and attatch the AppId
4. Enjoy!

Now here we go for the deep-dive.

Create an Application with AppID and Secret in Azure Active Directory

  • Sign in to the Azure Portal and Azure AD tenant by selecting your account in the top right corner of the page.
  • On the left side of the page, go to Azure Active Directory and select App registrations.
  • Click New application registration and provide the name. The application type must be Web app / API. You can chose any valid URL as Sign-on URL.

Assign the Dynamics CRM Online API rights to the Application

  • Open the new App registration and select Required permissions. Click Add, Select an API and Chose Dynamics CRM Online. Select all permissions and click Select and Done. Now the permissions should look like this.
    Application registration Permissions for the Dynamics 365 oData API
  • Now select Keys and create a new Key. Save the Key for later, this is the Secret you need to authenticate. Together with your Application ID, you are now done creating the Application.

Create an application user in CRM and attatch the AppId

  • Go to the CRM users and open the Application Users view.
  • Click New and you’ll get a special form for Application Users. Here you’ll provide the Application ID of the registrated application, a full name that sounds logical to you and a primary email. This e-mail must contain an existing domain within the same tenant.
  • For the final step, assign a custom security role to this user. Please make sure it’s a custom security role. A default security role won’t do.

Sample Code and Libraries

If you want to test if authentication works properly, you can download and use this VS project. If you change the config-file and you run the project, you should see your 5 first Accounts.

Since not everyone uses C# for their projects, you should know Microsoft also has the ADAL Libraries in all kinds of programming languages. ADAL stands for Azure Active Directory Authentication, which you can use to authenticate to Dynamics 365 Online as well. You can find the ADAL Libraries here.

Enjoy!