Dynamics 365 portals Spring Roadmap and Portal Source Code

If you frequent the Dynamics 365 Roadmap site (built on portals 🙂 ) you may notice a new area has been added for the CRM based Applications (Sales, Customer Service, Field Service, Project Service) for portals features. A number of items for all areas of Dynamics 365 has been posted as we near the Spring release of Dynamics 365 (v8.3), but this is a first for the portal to have been posted which seems to be the makings of a Spring Roadmap for the product. There are some exciting items on there including a release of the portal source code, Azure AD B2C and more. Below is all the items posted to the roadmap as well as some comments on each.

Let’s get to the big one first, portal source code.

Source code for Portals
A one time release of Portals code will be released to the Microsoft Download Center under MIT license for developers to download.

This feature enables Portals to be deployed to Dynamics 365 on-premise environments, and allows developers to customize the code to suit their specific business needs.

This is a huge news, complete open source of all portals code! This should also be taken with some caution though. Let’s understand what this means.

  • One time release – it will never be updated, ever, ever again.
  • Under MIT License – free, and full open source software (OSS), no direct support from Microsoft.
  • Microsoft Download Center – not taking pull requests, no contributing back to a master branch

Some awesome news but a big caution for corporations looking to invest in a supported product. With it being a one time release it is basically a point in time and will not be updated with bug fixes, new features nor will it be supported by Microsoft. The future is very much still online with portals as a service which will continue to be updated with bug fixes, new features and fully supported by Microsoft. If you choose the OSS path then support could come from partners, or other corporations but they will all come with their own costs and potentially different versions of the portal. Being OSS MIT means that anyone can take the source change it and re-publish it, so we could end up with endless different versions of OSS portals. These are the pitfalls with any OSS product so just be very aware if you are someone interested in it.

If your an on premise customer that was still considering v7 of Adxstudio Portals then you should strongly consider this as the cost is a lot less 😉 (free vs $20k+ and even getting a license). However the same cautions apply and if your looking for a fully supported product then online with portal service is the future of the product. If you were looking at Adxstudio Portals v7 because of it’s event or retail functionality then that is still a gap in the OSS version as well.

For developers, this will be a gold mine for those to see the inner workings of the portals product. Look at how the Adxstudio and Microsoft product teams built features, implemented the CRM SDK, and gain a better understanding of how the product operates or why it does something a certain way or modify it to your liking.

Myself and Adoxio will have more to say on Open Source Portals shortly and the direction Adoxio will be taking.

The next big roadmap item…

Support Azure AD-B2C for Portal authentication using a single sign-on (SSO) configuration

For Portals that require a consumer based login, this feature will now support the ability to:

  • Configure your portal authentication to use a Single Sign-On configuration
  • Support Azure AD-B2C for customer authentication
  • Manage your Portal security in Azure

* depends on Azure AD-B2C availability in the region(s) Portals are deployed

I blogged about B2C working in CRM portals late last year, but at the time B2C while supported in portals was not exactly recommended by Microsoft due to some user experience elements not being as desired. It’s great to see that it will be natively supported and recommended with the user experience elements corrected and even more included features released. I can’t more strongly recommend using B2C as your authentication in the portal and moving your authentication outside of Dynamics 365 so that it can be used by all applications and not just the portal. One identity for all your external applications.

Some other interesting new functionality coming soon:

Post installation language add-ons
This feature makes it easier to manage new additions to the existing portal language support.

Great to see, so many portals start off in 1 language and later want to add additional support and this will make that painless now.

Admin wizard to add an entity to the Portal
Easily publish any entity on your Portal using our new administrative wizard. When data is updated in the entity, it will automatically be available to Portal users who have access to these data.

This is likely a tool that will automatically make entity lists, entity forms, and entity permissions with all the web pages setup for you. Will make exposing new entities in the system extremely easy for out of box functionality.

Portal interaction tracking
Track your customer’s interactions with your Portal and funnel it to Dynamics 365 Customer Intelligence to plot a 360 view.

Sort of like Google Analytics but with all the relationships to your other Dynamics 365 data!

Whew! That is a lot of awesome news of features that are going to be coming to the portals shortly. There are a couple more smaller features, you can checkout the full listing on the roadmap site. The exact release dates for all of these is not mentioned, the earliest would be with the Spring release of portals. Previous releases of portals from Microsoft have typically lagged approximately a month behind the Dynamics 365 release. They could also come in monthly updates between now and the fall release.

We will have to keep an eye on the roadmap for future features being announced!

Dynamics 365 portals: Use aggregate FetchXML queries and Chart.js

A frequently requested feature of all types of portals is to display Dynamics 365 data in different displays like charts. The Dynamics 365 portal has a pre-built chart function that utilizes the out of box CRM charting functionality so that you can take the charts you create in CRM and display then easily on the portal. This functionality is somewhat limited but using the techniques discussed in Using liquid to return JSON or XML we can easily build a services that uses FetchXML aggregate queries to build data returns to summarize or roll-up data. With the aggregated query results you can quickly work with many of the JavaScript charting libraries like d3.js, chart.js, flot.js or many others to display a rich interactive view of the data that the default chart liquid component can’t do. In this post is a simple implementation of Chart.js which is a powerful, but simple library that has a very small footprint to build some charts with the FetchXML aggregate data.

Let’s start by creating the web template that is going to return the JSON data for the chart to display. As in the previous examples we will use the fetchxml liquid tag to retrieve the data but using the aggregate function of FetchXML to summarize data. Our example is going to continue using the course schedules and instructors, for this chart we would like to get a count of schedules by instructor.

{% fetchxml feed %}
<fetch version="1.0" output-format="xml-platform" mapping="logical" aggregate="true">
  <entity name="dpx_courseschedule">
    <attribute name="dpx_coursescheduleid" alias="schedule_count" aggregate="countcolumn" />
    <attribute name="dpx_instructorid" alias="dpx_instructorid" groupby="true" />   
  </entity>
</fetch>
{% endfetchxml %}[
  {% for item in feed.results.entities %}
    {
      "count": "{{ item.schedule_count }}",
      "instructor": "{{ item.dpx_instructorid.name }}",
      "instructorid": "{{ item.dpx_instructorid.id }}"
    }{% unless forloop.last %},{% endunless %}
  {% endfor %}
]

You’ll notice this FetchXML is different from previous examples. Firstly in the opening fetch tag it removes the distinct property and adds aggregate="true". Within the entity tags the attributes are limited to one to count by with the aggregate="countcolumn" for the dpx_coursescheduleid and then because we want the count by instructor the attribute for dpx_instructorid has the property groupby="true". As in previous examples we take the results, iterate through them and create a JSON array. Also don’t forget to set the web template Mime Type to application/json and ensure that you give the return JSON template a URL using the instructions in Use liquid to return JSON or XML.

With aggregate FetchXML queries you can include filter criteria so if you want to dynamically filter the data in the aggregation you can easily add parameters that are then added as filters. You could do some cool combinations with other components that use the same technique like the previous post on FullCalendar so that as you change months or filter down your calendar data it also is filtering the chart with the same parameters.

Now that we have a JSON data return template we can build the web template that will process it with the chart.js library. Below is the basic scaffolding for our template which is a canvas HTML5 element, the chart.js Javascript library and then a document ready with the get of the canvas element.

<canvas id="myChart"></canvas>

<script src="//cdnjs.cloudflare.com/ajax/libs/Chart.js/2.5.0/Chart.min.js"></script>
<script>
  $(function(){  // document ready    
      var ctx = $("#myChart");
  });
</script>

Firstly within document ready we need to make a call to retrieve the data using a jQuery AJAX GET method to the JSON return template URL. With the returned JSON we will transform it into a chart.js data object so that it can be added easily to any chart type. To do so we are going to create a couple of arrays, one for labels and one for data values, then populate them by iterating through the resulting JSON array from the AJAX call.

$(function(){ // document ready
    $.ajax({
      method: "GET",
      url: "/courses-aggregate-json/"
    })
    .done(function( results ) {
      
      var labels = [], datavalues = [];
      
      for (i = 0; i < results.length; i++) { 
        labels.push(results[i].instructor);
        datavalues.push(parseFloat(results[i].count));
      }

      var dataobj = {
          labels: labels,
          datasets: [{
              data: countdata
          }]
      };

      var ctx = $("#myChart");

      // bind data to chart object
    });
});

With the returned data now formatted for chart.js data object we can initialize the chart element with a chart type and the data object. The chart.js options for the pie type are also set to animate its display and have the legend displayed at the bottom of the chart.

// inserted within the done of the ajax get
// after the transform of return JSON and creation of dataobj

var ctx = $("#myChart");

var myChart = new Chart(ctx, {
  type: 'pie',
  data: dataobj,
  options: {
    animation:{
        animateScale:true
    }, 
    legend: {
      display: true,
      position: "bottom"
    }
  }
});

After getting this web template a URL with a page template and web page you should end up with your pie chart. Although its probably looking a little gray as we didn’t assign any colors.

If you read the previous post on FullCalendar then we know that our instructors entity actually contains an attribute that holds a hex color code value which we could use to color the chart. With following code which should be located at the top of the script tag prior to the document ready method, we can get those color codes, as well as create a function that will find the color for a specific instructor.

{% fetchxml feed %}
  <fetch version="1.0" output-format="xml-platform" mapping="logical" distinct="false">
    <entity name="dpx_instructor">
      <attribute name="dpx_instructorid" />
      <attribute name="dpx_colorcode" />
    </entity>
  </fetch>
{% endfetchxml %}

var instructorData = [{% for item in feed.results.entities %} {
      "instructorid": "{{ item.id }}",
      "color": "{{ item.dpx_colorcode | default:"#ffff00" }}"
    }{% unless forloop.last %},{% endunless %}
  {% endfor %}];

function findInstructorColor(lookupId) {
  for(var a = 0; a < instructorData.length; a++) {
    if(instructorData[a].instructorid == lookupId)
    {
      return instructorData[a].color;
    }
  }
}

With this code we are doing similar to the previous JSON return template but within the JavaScript so on render of the template it dynamically renders an object called instructorData which is a JSON array with the instructorid and color.

In the transform into the data object section update it with a new array called color and populate the array in the result iteration (line 6) which uses the findInstructorColor method, then include that new array in the dataobj (line 13).

var labels = [], countdata = [], color = [];

for (i = 0; i < results.length; i++) { 
  labels.push(results[i].instructor);
  countdata.push(parseFloat(results[i].count));
  color.push(findInstructorColor(results[i].instructorid));
}

var dataobj = {
  labels: labels,
  datasets: [{
    data: countdata,
    backgroundColor: color
  }]
};

With these changes you should now have a much nicer looking pie chart with color!

Using JavaScript charting libraries in combination with the FetchXML aggregate queries can allow you to start creating some really cool looking dashboards that go beyond the out of box functionality of portals. You can even use some Bootstrap components to help you do some nice formatting in combination with charts.

If your interested in learning more about liquid techniques I will be giving a webinar with xRMVirtual on April 26th at 12pm EST – Advanced Liquid Templates for Dynamics 365 portals.

Dynamics 365 portals: Implement FullCalendar with Liquid

Using the techniques discussed in Using liquid to return JSON or XML we can easily build a services that work with various with JavaScript libraries. FullCalendar is one of the most popular libraries for displaying events in various views on the web and can easily be used in the portal and creating a JSON return template for the event data. With FullCalendar you can fully customize a calendar output in the portal to really get that user experience you might be looking for. In this post is a simple implementation of FullCalendar with a custom entity JSON return template that will help outline how you can use this library in your portal projects.

First we can start with creating the web template that will be the return JSON data. Within this template a fetchxml query that takes at least the parameters of start and end so that it will filter for the date range being displayed on the calendar by adding the necessary conditions in the fetch.

{% fetchxml feed %}
<fetch version="1.0" output-format="xml-platform" mapping="logical" distinct="false" count="100" returntotalrecordcount="true" {% if request.params['page'] %} page="{{request.params['page']}}" {% else %}
page="1"
{% endif %}>
  <entity name="dpx_courseschedule">
    <attribute name="dpx_number" />
    <attribute name="createdon" />
    <attribute name="dpx_starttime" />
    <attribute name="dpx_endtime" />
    <attribute name="dpx_courselocationid" />
    <attribute name="dpx_courseid" />
    <attribute name="dpx_coursescheduleid" />
    <filter type="and">
      <condition attribute="statecode" operator="eq" value="0" />
      {% if request.params['location'] %}
        <condition attribute="dpx_courselocationid" operator="eq" value="{{ request.params['location'] | xml_escape }}" />
      {% endif %}
      {% if request.params['start'] %}
        <condition attribute="dpx_starttime" operator="ge" value="{{ request.params['start'] | xml_escape }}" />
      {% endif %}
      {% if request.params['end'] %}
        <condition attribute="dpx_endtime" operator="le" value="{{ request.params['end'] | xml_escape }}" />
      {% endif %}
    </filter>
    <link-entity name="dpx_instructor" from="dpx_instructorid" to="dpx_instructorid" visible="false" link-type="outer" alias="instructorlink">
      <attribute name="dpx_contactid" />
      <attribute name="dpx_number" />
    </link-entity>
    <link-entity name="dpx_course" from="dpx_courseid" to="dpx_courseid" alias="courselink">
      <attribute name="dpx_coursecategoryid" />
      {% if request.params['category'] %}
        <filter type="and">
          <condition attribute="dpx_coursecategoryid" operator="eq" uiname="Category 1" uitype="dpx_coursecategory" value="{{ request.params['category'] | xml_escape }}" />
        </filter>
      {% endif %}
    </link-entity>
  </entity>
</fetch>
{% endfetchxml %}[
  {% for item in feed.results.entities %}
    {
      "title": "{{ item.dpx_courseid.name }} - {{ item['instructorlink.dpx_contactid'].name }}",
      "start": "{{ item.dpx_starttime | date_to_iso8601 }}",
      "end": "{{ item.dpx_endtime | date_to_iso8601 }}"
    }{% unless forloop.last %},{% endunless %}
  {% endfor -%}
]

The JSON is formatted to follow the FullCalendar Event Object and return an Event Source Object. Providing the return format directly in the service allows us to now easily hook up this service to the FullCalendar event configuration. The sample above only includes a number of simple properties but you can add any number of properties from the Event Object and map them to data in the query results.

Ensure that you now give the return JSON template a URL using the instructions in Use liquid to return JSON or XML and the Mime Type is set to application/json.

Now create a new web template that is going to implement the FullCalendar library and consuming the event return JSON template.

The first thing that needs to be added is references to both the CSS as well as JavaScript for FullCalendar as well as a reference to Moment.js. FullCalendar utilizes Moment.js for all date functions and therefore the Moment.js library needs to be referenced prior to the FullCalendar JavaScript library. Below is a simple template that uses the CDN’s for FullCalendar as well as Moment.js.

<link href="//cdnjs.cloudflare.com/ajax/libs/fullcalendar/3.3.1/fullcalendar.min.css" rel="stylesheet" />

<div id='calendar'></div>

<script src="//cdnjs.cloudflare.com/ajax/libs/moment.js/2.18.1/moment.min.js"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/fullcalendar/3.3.1/fullcalendar.min.js"></script>

<script>
  $(document).ready(function() {
      $('#calendar').fullCalendar({
          // FullCalendar configuration properties
      });
  });
</script>

The JavaScript in the code above initializes FullCalendar on the HTML element with the id of calendar and takes a series of parameters. You can review all the parameters available for configuration on the FullCalendar documentation. There are configuration properties for just about every function and include event callbacks that can be configured for certain events which could be utilized to make further calls to return JSON based templates.

To display event data on the calendar there are a couple of parameters that can be used to inject event data. For the following configuration we will be using the previously created web template that returns the FullCalendar Event Object based on our custom entity, but you can retrieve the data in various ways with the options that FullCalendar provides including multiple event sources.

<script>
  $(document).ready(function() {  
      $('#calendar').fullCalendar({
        events: {
          url: '/fullcalendar-json/',
          type: 'GET',
          error: function() {
            alert('there was an error while fetching events!');
          },
          color: 'yellow',
          textColor: 'black'
        }
      });
  });
</script>

Here we have replaced the blank configuration properties with the Events property which uses a url to retrieve event data. The URL is configured to our previous templates URL and the GET HTTP method is configured as the type. The event properties color and textColor are also configured for the default display of events on the calendar. After hooking up this new web template to a page template and web page you can view it in the portal and should have a result similar to the following:

Now we can take this further and enhance the display of events as well as add event filtering options. For my custom entities, I extended the Instructor with 2 additional fields, color and text color which I put in HEX color code values into for each record. I extended the fetchxml query to include these fields as well as the JSON output to add these fields as Event Object properties, below is the new JSON output including as well a URL that will link to the event details using a site marker.

{% fetchxml feed %}
<!-- fetchxml statement removed for length -->
{% endfetchxml %}[
  {% assign urlMarker = sitemarker['Event Details'] %}
  {% for item in feed.results.entities %}
    {
      "title": "{{ item.dpx_courseid.name }} - {{ item['instructorlink.dpx_contactid'].name }}",
      "start": "{{ item.dpx_starttime | date_to_iso8601 }}",
      "end": "{{ item.dpx_endtime | date_to_iso8601 }}",
      "color": "{{ item['instructorlink.dpx_colorcode'] }}",
      "textColor": "{{ item['instructorlink.dpx_textcolor'] }}",
      "url": "/{{ urlMarker.Url }}?id={{ item.id }}"
    }{% unless forloop.last %},{% endunless %}
  {% endfor -%}
]

In my FullCalendar liquid template I have add a fetchxml query so I can get a list of locations which are displayed in a drop down so users can then filter events in the calendar by this property.

{% fetchxml locationfeed %}
<fetch version="1.0" output-format="xml-platform" mapping="logical" distinct="false">
  <entity name="dpx_courselocation">
    <attribute name="dpx_name" />
  </entity>
</fetch>
{% endfetchxml %}

<p>
  <div class="input-group">
    <select id="course-location" class="form-control">
        <option value="" selected disabled>Select a location...</option>
      {% for item in locationfeed.results.entities %}
        <option value="{{ item.id }}">{{ item.dpx_name }}</option>
      {% endfor %}
    </select>
    <span class="input-group-btn">
      <button id="refresh-events" class="btn btn-primary">Refresh Events</button>
    </span>
    <span class="input-group-btn">
      <button id="clear-events" class="btn btn-danger">Reset/Clear</button>
    </span>
  </div>
</p>

Then the JavaScript I have added 2 events for the new refresh and clear buttons, as well I have added a data property to the events call that will inject the location value if it is selected.

$('#calendar').fullCalendar({
  events: {
    url: '/fullcalendar-json/',
    type: 'GET',
    data: function() {
      var locationId = $('#course-location option:selected').val();            
      if (locationId) {
        return {
          location: locationId
        };
      }            
      return null;
    },
    error: function() {
      alert('there was an error while fetching events!');
    },
    color: 'yellow',   // a non-ajax option
    textColor: 'black' // a non-ajax option
  }
});

$('#refresh-events').on('click', function(){
  $('#calendar').fullCalendar('refetchEvents');
});

$('#clear-events').on('click', function(){
  $('#course-location').prop('selectedIndex',0);
  $('#calendar').fullCalendar('refetchEvents');
});

The display and function of the calendar should now be enhanced with colors for each instructor and the ability to filter the course schedules by location!

Hopefully this has helped show an example of the power you can get out of liquid templates by creating your own JSON based service and utilizing a JavaScript library like FullCalendar.

If your interested in learning more about liquid techniques I will be giving a webinar with xRMVirtual on April 26th at 12pm EST – Advanced Liquid Templates for Dynamics 365 portals.

Dynamics 365 portals: Use liquid to return JSON or XML

For many business requirements to get a desired user experience you may push the limits that the entity list functionality provides. With liquid you can write your own service to return data in various formats using the web template Mime Type property. By returning your own data you can inject logic and specific formatting using liquid functionality, this will allow you to utilize new components or libraries to help you provide the specific experience your requirements demand. This post will look at how liquid can be used with web templates to return JSON or XML so that the data can be consumed and used to build a complex user experience.

With liquid there are many ways to query for data. There is the entities object which can be used to retrieve a single record by ID. To get lists of data you can use the entity list which behind is using one or many entity views and an entity view is a fetchxml query that defines the view. Entity list contains a feature, OData feed, that allows you to take an entity view and make it available as a service. The OData feed is a great way to get a RESTFul JSON return but it has many shortcomings. If your interested in trying out the OData feed functionality then check out the documentation still available on the Adxstudio Community site – Entity List OData Feeds.

If you want to directly write your own queries in web templates, perhaps dynamically constructing them, utilize entity permission relationship based data, then you can use the liquid fetchxml tag. Below is a little outline of the functions of this liquid object.

{% fetchxml my_query %}
  <fetch version="1.0" mapping="logical">
    <!-- Write FetchXML here, use Liquid in here if you want, to build XML dynamically. -->
  </fetch>
{% endfetchxml %}
 
{{ my_query.xml | escape }}
{{ my_query.results.total_record_count }}
{{ my_query.results.more_records }}
{{ my_query.results.paging_cookie | escape }}
{% for result in my_query.results.entities %}
  {{ result.id | escape }}
{% endfor %}

Reference: Adxstudio Community Forums

With Dynamics 365 portals entity permissions is required by default and does not need to be referenced in the liquid tag. This differs from Adxstudio Portals v7.x, so if you are getting blank results using the fetchxml liquid object then ensure to first validate your entity permissions.

The fetchxml liquid tag and web templates Mime Type functionality provide the ability to build a web template that returns custom JSON or XML objects. With this you can build endpoints that intake custom parameters, perform logic while constructing the query, logic in returning the results, formatting the results and doing related record queries, all the while adhering to the entity permissions in place for that entity.

Below is an example of a web template that queries a custom course schedule entity with joins to related entities, course and instructor. The liquid code looks for 2 parameters location and category and if they exist it adds the fetch conditions for those parameters.

{% fetchxml feed %}
<fetch version="1.0" output-format="xml-platform" mapping="logical" distinct="false" count="10" returntotalrecordcount="true" {% if request.params['page'] %} page="{{request.params['page']}}" {% else %} page="1" {% endif %}>
  <entity name="dpx_courseschedule">
    <attribute name="dpx_number" />
    <attribute name="createdon" />
    <attribute name="dpx_starttime" />
    <attribute name="dpx_endtime" />
    <attribute name="dpx_courselocationid" />
    <attribute name="dpx_courseid" />
    <attribute name="dpx_accountid" />
    <attribute name="dpx_cost" />
    <attribute name="dpx_coursescheduleid" />
    <order attribute="createdon" descending="true" />
    <filter type="and">
      <condition attribute="statecode" operator="eq" value="0" />
      {% if request.params['location'] %}
        <condition attribute="dpx_courselocationid" operator="eq" value="{{ request.params['location'] | xml_escape }}" />
      {% endif %}
    </filter>
    <link-entity name="dpx_instructor" from="dpx_instructorid" to="dpx_instructorid" visible="false" link-type="outer" alias="instructorlink">
      <attribute name="dpx_contactid" />
      <attribute name="dpx_number" />
    </link-entity>
    <link-entity name="dpx_course" from="dpx_courseid" to="dpx_courseid" alias="courselink">
      <attribute name="dpx_level" />
      <attribute name="dpx_lengthunit" />
      <attribute name="dpx_length" />
      <attribute name="dpx_coursecategoryid" />
      {% if request.params['category'] %}
        <filter type="and">
          <condition attribute="dpx_coursecategoryid" operator="eq" value="{{ request.params['category'] | xml_escape }}" />
        </filter>
      {% endif %}
    </link-entity>
  </entity>
</fetch>
{% endfetchxml %}{
  "totalcount": {{ feed.results.total_record_count }},
  "morerecords": {{ feed.results.more_records }},
  "page": {{ request.params['page'] | default: 0 }},
  "results": [
    {% for item in feed.results.entities %}
      {
        "starttime": "{{ item.dpx_starttime | date_to_iso8601 }}",
        "endtime": "{{ item.dpx_endtime | date_to_iso8601 }}",
        "instructorname": "{{ item['instructorlink.dpx_contactid'].name }}",
        "courselevel": "{{ item['courselink.dpx_level'].label }}",
        "location": {
          "id" : "{{ item.dpx_courselocationid.id }}",
          "name": "{{ item.dpx_courselocationid.name }}"
        }
      }{% unless forloop.last %},{% endunless %}
    {% endfor -%}
  ]
}

The fetchxml result is then formatted into a JSON object using the forloop liquid object to iterate through each entity record. Linked entity attributes are easily accessed via the linked entity alias {{ entityRecord['alias.attribute'] }}. With the return being JSON you will want to set the Mime Type property to application/json.

Another example using Case (incident) where we also use a N:N relationship of all child cases in the custom data object returned with the referenced attribute to load the entity relationship.

{% fetchxml feed %}
<fetch version="1.0" output-format="xml-platform" mapping="logical" distinct="false" count="10" returntotalrecordcount="true" {% if request.params['page'] %} page="{{request.params['page']}}" {% else %} page="1" {% endif %}>
  <entity name="incident">
    <attribute name="ticketnumber" />
    <attribute name="prioritycode" />
    <attribute name="title" />
    <attribute name="createdon" />
    <attribute name="customerid" />
    <attribute name="ownerid" />
    <attribute name="statecode" />
    <attribute name="incidentid" />
    <attribute name="caseorigincode" />
    <order attribute="title" descending="false" />
  </entity>
</fetch>
{% endfetchxml %}{
  "totalcount": {{ feed.results.total_record_count }},
  "morerecords": {{ feed.results.more_records }},
  "page": {{ request.params['page'] | default: 0 }},
  "results": [
    {% for item in feed.results.entities %}
      {
        "ticketnumber": "{{ item.ticketnumber }}",
        "title": "{{ item.title }}",
        "customer":  {
          "id" : "{{ item.customerid.id }}",
          "name": "{{ item.customerid.name }}"
        },
        "incident_parent_incident": [
            {% for parent in item.incident_parent_incident.referenced %}
              {
                "parentticketnumber": "{{ parent.ticketnumber }}"
              }{% unless forloop.last %},{% endunless %}
            {% endfor %}
          ]
      }{% unless forloop.last %},{% endunless %}
    {% endfor -%}
  ]
}

If you instead wanted to return XML then it is just a matter of updating the Mime Type of the web template to application/xml and the code to output XML instead of the JSON format. Below is a sample of the first example but returning XML.

<!--FETCHXML query -->
{% endfetchxml %}<?xml version="1.0" encoding="UTF-8" ?>
<fetchxmlquery>
  <totalcount>{{ feed.results.total_record_count }}</totalcount>
  <morerecords>{{ feed.results.more_records }}</morerecords>
  <page>{{ request.params['page'] | default: 0 }}</page>
  <results>
    {% for item in feed.results.entities %}
      <item>
        <starttime>{{ item.dpx_starttime | date_to_iso8601 }}</starttime>
        <endtime>{{ item.dpx_endtime | date_to_iso8601 }}</endtime>
        <instructorname>{{ item['instructorlink.dpx_contactid'].name }}</instructorname>
        <courselevel>{{ item['courselink.dpx_level'].label }}</courselevel>
        <location>
          <id>{{ item.dpx_courselocationid.id }}</id>
          <name>{{ item.dpx_courselocationid.name }}</name>
        </location>
      </item>
    {% endfor %}
  </results>
</fetchxmlquery>

Once you have setup your web template with your liquid logic and Mime Type you need to get a URL for it. Create a page template of the Type, Web Template, and the previous Web Template referenced. As well ensure that Use Website Header and Footer is unchecked so that all that is returned is the data formed by the web template.

Now using the portals front-end editor, create a new web page using the new page template that references the web template. This will give your web template a URL and you can now refer to this endpoint within other JavaScript on the site. Here is a small jQuery sample calling a JSON endpoint URL and logging the result to the browser console. You can also do testing of your endpoints with Postman.

<script>
  $(function(){
    $.ajax({
      method: "GET",
      url: "/cases-json/"
    })
    .done(function( msg ) {
      console.log(JSON.parse(msg));
    });
  });
</script>

Note for entity permissions to function beyond anonymous a cookie for authentication must be attached to the request. JavaScript on the site already making requests will include the necessary cookie by default.

If your interested in learning more about liquid techniques I will be giving a webinar with xRMVirtual on April 26th at 12pm EST – Advanced Liquid Templates for Dynamics 365 portals.

Dynamics 365 portals: Events and iCalendar Download with Liquid

A popular component of Adxstudio Portals was its event management system, which unfortunately has not made the transition to Dynamics 365 portals. There will be a new event management system coming in the future (as seen at eXtreme365 in Lisbon), which will come with a portal component that will list and allow registration to events. Until then you may still want to create some simple event functionality using the out of box configuration based components that allows you to list events and allow users to add an event to their own calendar. In this post we will use Liquid Templates to create your own display of events from a custom entity with an entity list and an iCalendar download (Add to Calendar button) so that users can add it to their own calendar.

First we are starting with an entity (this could be any entity that already exists or creating a new one) that includes the event information. All you need for an event is really a subject and a date. If you want to get a little more complete then we want a start date, end date, subject, description, location. It’s really up to you and the functionality or detail you want to contain in your event. I am starting with an entity called Group Meetings which includes the following fields:

To display the events on the portal you can use an entity list with a custom web template to create a custom output of the information instead of just a grid/table display. Here is the entity list web template used on xrmvirtual.com (I have removed the paging to keep the code length displayed here brief).

{% assign meetingDetails = sitemarkers["Meeting Details"] %}

{% entitylist id:page.adx_entitylist.id %}
  <div class="meeting-list-body">
    {% entityview id:params.view, search:params.search, order:params.order, page:params.page, pagesize:params.pagesize, metafilter:params.mf %}
      {% if entityview.records == empty %}
        <div class="alert alert-info">
            {% if entitylist.empty_list_text %}
              <p>{{ entitylist.empty_list_text | escape }}</p>
            {% else %}
              <p>No items matching your selected criteria were found.</p>
            {% endif %}
        </div>
      {% else %}
        {% for meeting in entityview.records %}
          <div class="media">
            <div class="media-left jumbotron-icon">
              <span class="fa fa-calendar fa-2"></span>
            </div>
            <div class="media-body">
              <h4 class="media-heading"><a href="{{ meetingDetails.url }}?id={{meeting.id}}">{{meeting.xv_name}}</a></h4>
              <p class="meeting-date">Speaker: <span class="meeting-speaker">{{meeting.xv_primaryspeakerid.name}}</span> | <time datetime="{{meeting.xv_starttime | date_to_iso8601}}"></time></p>
              <div class="meeting-abstract">
                <p>{{meeting.xv_abstract}}</p>
              </div>
              <div class="meeting-actions">
                {% if meeting.xv_recordingposted | false and meeting.xv_recordingurl %}
                  <a href="{{meeting.xv_recordingurl}}" target="_blank" class="btn btn-success btn-sm">
                    <span class="fa fa-video-camera"></span>&nbsp;
                    Download Recording
                  </a>
                {% endif %}
                {% if now < meeting.xv_starttime and meeting.xv_meetingurl %}
                  <a href="{{meeting.xv_meetingurl}}" target="_blank" class="btn btn-primary btn-sm">
                    <span class="fa fa-calendar"></span>&nbsp;
                    Join Meeting
                  </a>
                {% endif %}                
                {% if now < meeting.xv_starttime %}
                  {% assign iCal = sitemarkers["XRM iCal"] %}
                  <a href="{{iCal.Url}}?id={{meeting.id}}" target="_blank" class="btn btn-default btn-sm">
                    <span class="fa fa-calendar-plus-o"></span>&nbsp;
                    Add to Calendar
                  </a>
                {% endif %}
              </div>
            </div>
          </div>
          <hr/>
        {% endfor %}
      {% endif %}
    {% endentityview %}
  </div> 
{% endentitylist %}

If you review the code it is basically taking the entity list that the page references {% entitylist id:page.adx_entitylist.id %}, does a check to make sure the entity view is not empty {% if entityview.records == empty %}, if it is not then it iterates through the items with a for loop {% for meeting in entityview.records %}. Within the for loop we have the individual record with the {{meeting}} object, which we then format the attributes of it with some HTML.

As this entity list template is used for upcoming and past meetings there are also some checks so that we can conditional show certain elements on each meeting, one of those being if there is a meeting URL and we are before the start time then show the join meeting button {% if now < meeting.xv_starttime and meeting.xv_meetingurl %}.

When building an event display the highest requested feature is to provide a download or add to calendar button so that users can easily add the event to their own calendars. With liquid templates we can easily satisfy this requirement. Not well documented and really only 1 public example is the web templates MIME type. With the MIME type field on web template we can actually set a custom type that the browser will use to interpret the content it is trying to process. If you don't set a MIME type then this will default the MIME type to text/html. For browsers to detect the content as calendar data then we can set the MIME type to text/calendar and then within the web template define the standard iCalendar format.

Let's start off with creating a new Web Template called iCal Download Handler. At the bottom of the form fill in the MIME type with text/calendar so that when a browser accesses this content it tries to interpret it using the calendar format. Now for the contents of the web template we want to output the standard iCalendar format. You can read through the entire RFC (if you really want) for iCalendar here to understand all the formatting options. Alternatively you can review the Wikipedia iCalendar document, as well below is a simple single event example.

{% assign meeting = entities.xv_groupmeeting[request.params.id] %}
{% if meeting %}
BEGIN: VCALENDAR
VERSION:2.0
PRODID: -//xrmvirtual.com//NONSGML ical.net 2.1//EN
BEGIN:VEVENT
DTEND:{{meeting.xv_endtime | date_to_iso8601 | remove: '-'}}
DTSTAMP:{{meeting.xv_starttime | date_to_iso8601 | remove: '-'}}
DTSTART:{{meeting.xv_starttime | date_to_iso8601 | remove: '-'}}
SEQUENCE: 0
SUMMARY:{{meeting.xv_name}}
X-ALT-DESC;FMTTYPE=text/html:{{meeting.xv_abstract}} {% if meeting.xv_meetingurl %}<p><a href="{{meeting.xv_meetingurl}}">Join meeting...</a></p>{% endif %}
UID: {{meeting.id}}
END:VEVENT
END:VCALENDAR
{% endif %}

The first check in the template is that we assume the ID of the event we want to provide as a download is provided as a query string parameter called 'id'. We use this parameter and the liquid entities object to retrieve the group meeting record. If the meeting exists then we output the iCalendar format with attributes from the group meeting as values for the iCalendar attributes.

The date/time iCalendar attributes do expect date/times formatted in the ISO8601 format and does not included any dashes. Luckily there are liquid filters that can help us achieve this exact format. Taking the meeting start or end time which is stored as a CRM date/time object we can apply the date_to_iso8601 filter and then apply the string filter to pull out the dashes that are included in that format remove: '-'.

In the SUMMARY attribute just simply use the liquid to expose a CRM attribute from the meeting object, {{meeting.xv_name}}. For the description (abstract in XRM Virtual group meeting) because we are using the CK editor to provide rich text for the description contents this is stored as HTML we need to provide the X-ALT-DESC iCalendar attribute and tell it the format FMTTYPE=text/html so that the encoding is properly interpreted. To this we also add a simple conditional check to see if there is a URL and then include the HTML to generate that link as part of the description. Finally the UID attribute of iCalendar format we just make the CRM GUID of the record.

To make this web template accessible we need to give it a URL. First create a new Page Template with the type of Web Template. Ensure the set the Use Website Header and Footer is not selected and set the Web Template to your iCal Download Handler. It is important that the Use Website Header and Footer is turned off as this will ensure that when this template is rendered it only includes the content in the web template and none of the scaffolding of the portal (like the header and footer HTML). With your page template create a new Web Page that references the new Page Template.

Page Template:

For ease of access in web template I also created a Site Marker that refers to the web page, then used the following code in my event list template to get the URL and pass the ID of the record:

{% assign iCal = sitemarkers["XRM iCal"] %}
<a href="{{iCal.Url}}?id={{meeting.id}}" target="_blank" class="btn btn-default btn-sm">
  <span class="fa fa-calendar-plus-o"></span>&nbsp;
  Add to Calendar
</a>

From this we have taken a custom entity that has event type data and displayed it in a nicely presented format on the portal and included an add to calendar or download calendar item functionality so that users can include it in their own calendar. Now because of the various versions of iCalendar that vendors have implemented you may notice this iCalendar format does not work on every device, you can though create specific web/liquid templates for the various formats and provide links to each of them or you can look at JavaScript libraries that help provide this format. AddEvent is a common plugin that can be used freely for personal use and licensed for commercial sites that will provide an easy implementation in a web template (below is a sample) that will cover all iCalendar formats.

AddEvent Liquid Template Sample:

<span class="addtocalendar  atc-style-blue">
  <var class="atc_event">
    <var class="atc_date_start">{{ event.adoxio_startdate | date: 'yyyy-MM-dd hh:mm:ss' }}</var>
    <var class="atc_date_end">{{ event.adoxio_enddate | date: 'yyyy-MM-dd hh:mm:ss' }}</var>
    <var class="atc_timezone">America/Vancouver</var>
    <var class="atc_title">{{ event.adoxio_name }}</var>
    <var class="atc_description">{{ event.adoxio_name }}</var>
    <var class="atc_location">{{ event.adoxio_name }}</var>
    <var class="atc_organizer">City of Victoria</var>
    <var class="atc_organizer_email">info@adoxio.com</var>
  </var>
</span>