Hi
Recently I’ve made a presentation at the Dublin user group on the new Power Apps Portals Web API. In this post I would like to share the slide deck and code used.
I haven’t done any post on the Web API, and the main reason is that I find Microsoft documentation pretty solid on this topic (and I am not a big fan of Microsoft’s documentation for new products).
You can check the official documentation on the Web API here: https://docs.microsoft.com/en-us/powerapps/maker/portals/web-api-overview
Why do we need a Web API?
Currently in Power Apps Portals, we can retrieve CDS data programmatically by using oData or FetchXML, but we have no way to perform insert/update operations against CDS data. The only ways to achieve these operations are through Entity Forms / Web Forms (there are alternative techniques but I won’t go into detail on these).
I have seen several business requirements that would need to perform operations without having an Entity Form associated, let me give you a few examples:
- Editable Grid
- Bulk delete within an Entity List
- Bulk workflow trigger within an Entity List
- Mark a Case or Notification record as read
- Insert/Update records on a page being rendered via Liquid Template
Basically with the new Power Apps Portals Web API all those requirements will now be possible to achieve. Basically the Web API will open the doors for many possibilities.
The editable grid
During my presentation, I created an editable grid to be used against the Account entity, let’s take a look at how it looks:
I want to share here the code used in my presentation, but note that there might be a few requirements necessary that I won’t be exploring in this post. At a high-level, this is what is required:
- Enable Web API via Site Settings (for both Account and Contact entities);
- Create Entity Permissions (for both Account and Contact entities);
- Create Web Template with Web API wrapper provided by Microsoft;
- I have a custom CSS loaded with very simple definitions just to render my custom grid;
- I have a “loading” gif just to give a better UX while the operation is happening
Okay, now I can talk about the code responsible for rendering my editable grid, as well as perform the Web API operations:
- I am extending the OOB Layout 1 Column, and overriding the block main, this is just for rendering my content;
- Now I have a fetch for the Account entity, which I am retrieving the Account Name, Primary Contact and telephone number;
- I am adding a button responsible for the “New” account – you can see that I am assigning the NewRecord function to the button (we’ll go through that later);
- Now I start rendering the table representing the editable grid itself, and just to simplify things, I am assigning an ID to each individual cell using the format (<account guid><_attribute name>). This will make it easier to retrieve the values later on, but you could achieve this in other ways as well;
- For each row, I am adding a “Remove” and “Update” button, assigning a JavaScript function as well
Now we can talk about the JavaScript functions:
- NewRecord() – This function creates a new line in the table, assigning a new GUID for the (to be created) Account. Here the remove button calls a different function, that won’t be calling the API, only removing the record from the table, and finally the button for create, which will obviously create the Account in the CDS;
- NewGuid() – This function simply generates a new GUID;
- CreateRecord(accountId) – This function is responsible for creating the Account and, along with it, it also creates a new Contact record in the same API request call. Finally, it refreshes the page so the remove and update functions are loaded correctly;
- UpdateRecord(accountId) – This function updates only the Account Name and Telephone, I am not too bothered with the Contact for the sake of this demo;
- RemoveUnsavedRecord(accountId) – This just removes a row without going through the API;
- RemoveRecord(accountId) – This function calls the DELETE API method and removes the row from the table
{% extends "Layout 1 Column" %}
{% block main %}
{% include "OR Web API Wrapper Web Template" %}
{% fetchxml accountFetch %}
<fetch version="1.0" output-format="xml-platform" mapping="logical" distinct="false">
<entity name="account">
<attribute name="name" />
<attribute name="primarycontactid" />
<attribute name="telephone1" />
<attribute name="accountid" />
<order descending="false" attribute="name"/>
</entity>
</fetch>
{% endfetchxml %}
<div>
<button type="button" class="btn btn-primary new-record btn-sm my-0 glyphicon glyphicon-plus" onclick="NewRecord()"></button>
<table id="accountTable" class="table table-responsive-md table-striped text-center">
<thead>
<tr>
<th class="text-center hidden">Account Id</th>
<th class="text-center">Name</th>
<th class="text-center">Primary Contact</th>
<th class="text-center">Telephone</th>
<th class="text-center"></th>
</tr>
</thead>
<tbody>
{% for acc in accountFetch.results.entities %}
{% assign accountId = acc.accountid %}
<tr id={{ accountID }}>
<td class="hidden" contenteditable="true">{{ accountId }}</td>
<td contenteditable="true" id="{{ accountID }}_name">{{ acc.name }}</td>
<td contenteditable="true" id="{{ accountID }}_contactName">{{ acc.primarycontactid.Name }}</td>
<td contenteditable="true" id="{{ accountID }}_telephone">{{ acc.telephone1 }}</td>
<td>
<button type="button" class="btn btn-danger btn-sm my-0 glyphicon glyphicon-remove" onclick="RemoveRecord('{{ accountId }}')"></button>
<button type="button" class="btn btn-success btn-sm my-0 glyphicon glyphicon-ok" onclick="UpdateRecord('{{ accountId }}')"></button>
</td>
</tr>
{% endfor %}
</tbody>
</table>
</div>
<script>
function NewRecord(){
var guid = NewGuid();
var newLine = '';
newLine += '<tr id=' + guid + '>';
newLine += ' <td class="hidden" contenteditable="true">' + guid + '</td>';
newLine += ' <td contenteditable="true" id="' + guid + '_name"></td>';
newLine += ' <td contenteditable="true" id="' + guid + '_contactName"></td>';
newLine += ' <td contenteditable="true" id="' + guid + '_telephone"></td>';
newLine += ' <td>';
newLine += ' <button type="button" class="btn btn-danger btn-sm my-0 glyphicon glyphicon-remove" onclick="RemoveUnsavedRecord(\'' + guid + '\')"></button>';
newLine += ' <button type="button" class="btn btn-success btn-sm my-0 glyphicon glyphicon-ok" onclick="CreateRecord(\'' + guid + '\')"></button>';
newLine += ' </td>';
newLine += '</tr>';
$("#accountTable").append(newLine);
$("#" + guid + "_name").focus();
};
function NewGuid(){
var dt = new Date().getTime();
var uuid = 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
var r = (dt + Math.random()*16)%16 | 0;
dt = Math.floor(dt/16);
return (c=='x' ? r :(r&0x3|0x8)).toString(16);
});
return uuid;
}
function CreateRecord(accountId){
$("#loading").fadeIn();
var accountName = $("#" + accountId + "_name").text();
var telephone = $("#" + accountId + "_telephone").text();
var contactName = $("#" + accountId + "_contactName").text();
var contactFirstName = "";
var contactLastName = "";
if(!!contactName){
contactFirstName = contactName.split(" ")[0];
if(contactName.split(" ").length > 1)
contactLastName = contactName.substr(contactName.indexOf(" ") + 1);
}
webapi.safeAjax({
type: "POST",
url: "/_api/accounts",
contentType: "application/json",
data: JSON.stringify({
"accountid" : accountId,
"name": accountName,
"telephone1" : telephone,
"primarycontactid":
{
"firstname": contactFirstName,
"lastname": contactLastName
}
}),
success: function (res, status, xhr) {
$("#loading").fadeOut();
alert("The record has been created successfully.");
location.reload();
},
error: function(){
$("#loading").fadeOut();
}
});
};
function UpdateRecord(accountId){
$("#loading").fadeIn();
var accountName = $("#" + accountId + "_name").text();
var telephone = $("#" + accountId + "_telephone").text();
webapi.safeAjax({
type: "PATCH",
url: "/_api/accounts(" + accountId + ")",
contentType: "application/json",
data: JSON.stringify({
"name": accountName,
"telephone1" : telephone
}),
success: function (res) {
$("#loading").fadeOut();
alert("The record has been updated successfully.");
},
error: function(){
$("#loading").fadeOut();
}
});
};
function RemoveUnsavedRecord(accountId){
if(!!accountId){
$("#"+ accountId).remove();
}
};
function RemoveRecord(accountId){
$("#loading").fadeIn();
if(!!accountId){
webapi.safeAjax({
type: "DELETE",
url: "/_api/accounts(" + accountId + ")",
contentType: "application/json",
success: function (res) {
$("#"+ accountId).remove();
$("#loading").fadeOut();
alert("The record has been deleted.");
},
error: function(){
$("#loading").fadeOut();
}
});
}
};
</script>
{% endblock %}
Can I use the Web API in production?
The Web API is currently in preview, and the general message is that it shouldn’t be used in Production environments. In my personal opinion, this feature is in good shape and shouldn’t have major changes until it reaches General Availability. I also doubt that Microsoft would cancel the rollout for this.
In other words, I would use it in Production, just keep in mind that you may have to re-factor some code in case of any changes from Microsoft.
Here is the slide deck I used in my presentation:
Oliver Rodrigues 