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"
    }
}

Manage your service calendar resources in Dynamics 365 CE

I know we shouldn’t use the good-old Dynamics CRM Service Calendar anymore. But let’s be honest: it still works for a lot of companies! I have multiple customers still using the old service calendar. Wanting to move to Universal Resource Scheduling, but waiting for some extra features to come.

With the use of the service calendar, I always find it annoying that all users will be on there. Most of the time you just need the users that need planning and not all (especially not your service users or administrative users). So I tried to figure out if there is a way to get rid of some users on the service calendar.

So the data model works as this: the service calendar shows both users and equipment. To show both of these in one view, MS created an extra entity: resources. When a user or an equipment record is created in the system, an equivalent record is created in the resources entity. The status of the user or equipment record is being copied to the resource record. When the user gets disabled, the equivalent resource record will be disabled as well. The same goes for equipment records.

But what if you have a user that you need to be enabled, but you don’t want it on the service calendar? This could be for service users of administrative users, but maybe also ‘normal’ users. Unfortunately there is no way to disable/inactivate the resource record via the user interface. The only way is to do it via the API. You can do this grammatically or you could use Flow or a tool like Scribe to do this.

Enjoy!

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!

Check if all required fields are populated

In my previous post Workaround for double update on statecode change via WebAPI, I use a custom Action to make a status change. However, when this is done the status of the records gets changed regardless of the required fields that might not be populated by the user. So in this case, we need to check if all the reuired fields have been populated before we call the custom Action.

First, we need to have a function that checks if all required fields are populated. After the check, I want the function to return “true” when all required fields are populated and “false” if otherwise. This is the function:

function allRequiredFieldPolutated() {
    var populated = true;
    Xrm.Page.getAttribute(function (attribute, index) {
        if (attribute.getRequiredLevel() == "required") {
            if (attribute.getValue() === null) {
                populated = false;
            }
        }
    });
    return populated;
}

Now this function can be used in other functions, such as the function that has been used in my previous post, to check if the status can be changed.

Ignore the added https in a Text Field type URL

Since Dynamics 365 version 2016 (8.0), text fields with type URL get automatically https added in front of the URL if the user has not typed that. In previous versions of Dynamics 365 / CRM this addition was http. Since a lot of websites still don’t have secure certificates and don’t do https, we want Dynamics 365 to use http instead of https.
With a simple JavaScript Web Resource, we can apply the old functionality as we used to have it. These 6 lines of code fire when an URL is typed in by the user, so the URL gets http as addition instead of https.

Make it work

In order to make this work, we first need to add the JavaScript Web Resource into Dynamics 365. So open your Dynamics 365 environment and go to your customization (either a solution or the default customizations). Now go to Web Resources and add a new Web Resource. Give the Web Resource any name you want to and upload the file that can be downloaded at the bottom of this page. Save and publish the Web Resource.

Next, go to the form on which you want this functionality and start editing this form. Open the Form Properties and add the Form Library you just created. After you clicked ok, you open the properties of the URL field and go to the Events tab. Add an Event Handler in which you select your library, set the Function field to ‘setHttp’ and check the ‘Pass execution contact as first parameter’. Now click ok, close all and publish your customizations.

That’s it! You’re good to go now. Please keep in mind that Dynamics 365 can sometimes experience some caching issues. When you open the form next time and you get a scripting error, please press Ctrl+F5 once. The scripting error should be gone now.

The code

UPDATE (2018): Since there have been some changes in javascript actions since Dynamics 365 v9.0, there is a new script for the v9.0 and above organisations.

V8:

function setHttp(context) {
    var webUrl = Xrm.Page.getAttribute(context.getEventSource().getName()).getValue();
    if (webUrl != null && webUrl.substring(0,7) != "http://" &&  webUrl.substring(0,7) != "https:/") {
        Xrm.Page.getAttribute(context.getEventSource().getName()).setValue("http://" + webUrl)
    }
}

V9:

function setHttp(executionContext) {
    var formContext = executionContext.getFormContext();
    var webUrl = formContext.getAttribute(executionContext.getEventSource().getName()).getValue();
    if (webUrl != null && webUrl.substring(0, 7) != "http://" && webUrl.substring(0, 7) != "https:/") {
        formContext.getAttribute(executionContext.getEventSource().getName()).setValue("http://" + webUrl)
    }
}

Download your file here

Download v8.0 and above

Download v9.0 and above