My first Dynamics 365 Extension – step by step – seventh step

Help and notification.

To make one thing clear.  The help we are used to build for the help server is not yet available for Extensions. Therefore we must make sure that all the help we anticipate the user needs will be available from the product.

Microsoft have added tool tips to most of the fields in the application.  To make sure you follow the requirements create tool tips and make sure to have the property for Application Area  populated.

In the previous post about the installation process you can see that a link to the Extension help must be provided.  I did short videos and posted them to YouTube.

With NAV 2017 and Dynamics 365 for Financials Microsoft released a new notification framework.  It is important to use this framework in your Extension.  For example, when a user open the General Ledger Entries after the G/L Source Names Extension installation a notification will appear.

And when the user reacts to the notification a setup video will start inside the web client.

The notification disappears and will not be displayed again for this user.

If the administrator has done the Assisted Setup and the user has the required permissions we will show a different notification.

and that notification will play the usage video.

Now, let’s look at how to do this.

There is a new data type for Notification.  You define variable of type Notification, set the properties and send it on it’s way.

I start by catching the event when the General Ledger Entries page is opened.  Then, depending on the permissions the user has to G/L Source Names table I select between two notifications.

You can have up to three actions added to each notification.  An action must point to a public function in a Codeunit.  That function must have a single parameter of type Notification.

The notification ID is a Guid.  Refer to my last post on how to get a new Guid and keep that Guid for the notification.  The history of the notification – which  user has acted on it, is saved by this ID.  Change it and the history will be lost.  Today, all the notifications must have Local Scope.  The Global Scope is not yet supported by the clients.

In the action for both these notifications I start a YouTube video for the user.  If the user is running web client, including phone client and tablet client, the video will be started inside the client.  For other client types I will start the video in the default browser.

That concludes my development.  Next part is to submit my Extension to AppSource.  Stay tuned…

 

 

 

My first Dynamics 365 Extension – step by step – sixth step

Assisted Setup and Permissions.

But first lets look at the Extension Management Codeunit.

I want to store the appId in my Extension.  This appId is used in several tables in my tenant.  This appId must always be the same for this solution even if the solution is updated.  In my last post you can see that I am also setting my appId parameter in the Git repository.  There are few easy ways to get your appId.  NAV has the function CREATEGUID.  Powershell has the function New-Guid.  But perhaps the easiest way is to use this online Guid generator.

In OnNavAppUpgradePerDatabase – executed once when the Extension is installed, I want to assign my Extension Setup permission set to the user installing.  This is required to be able to run the Assisted Setup after installation.

In OnNavAppUpgradePerCompany – executed once in every company when the Extension is installed, I want to restore data for some of the Extension tables and delete rest of the archive data.  Even if I am just using tables as a temporary tables I still need to define what to do with the non-existing-archived data.  In here I also want to remove the persistent Assisted Setup record in every company.

So, why would I like to remove the Assisted Setup record?  Not because I like to make the user execute the setup every time the Extension is updated.  The Extension has its own Setup table.  In that Setup table I store the setup information belonging to this Extension and the Setup data is restored from archive during the installation as you can see above.

In the current release the Assisted Setup record is a database record.  I know that Microsoft intends to change this and use the same discovery pattern that is used in Service Connections.  When that happens the Assisted Setup record will be temporary only.  So, by designing my Extension in this way I make sure that I will still support Assisted Setup after this change.

In NAV 2016 we had the Mini Role Center, page 9022.  Today this Role Center has been updated to fit Dynamics 365 for Financials.

From here the user can access the Extension installation we covered in the last post, and we can also access the Assisted Setup & Tasks.

I add my Assisted Setup by subscribing to the OnOpenPage Event in the above page.

Looking at the Assisted Setup record we can see that is has a media field for an Icon.  NAV setup data includes icon for the standard Assisted Setup items – so must we.

I decided to ship my icons with the code.  Each icon has a dedicated Codeunit.

To fit an icon into a Codeunit we need to convert the binary data to base64 data.  This we can do with the following code.

This allows me to create a Codeunit like this.

And then code like this to import the icon into my help resources.

Now, back to the Assisted Setup.  I start the setup for my Extension.

This sums up what needs to be done.  The basic setup, the one done with Set Defaults, is to assign permissions to all users based on their current permissions to the tables we build our extension around.

The G/L Source Name lookup table is read from a FlowField in G/L Entries.  We can therefore expect that everyone that has read access to G/L Entries must also have read access to the lookup table. The data in the lookup table is updated when ever any of the four master tables is updated.  Hence, everyone that has access to modify any of the master tables must have access to modify the lookup table.

The Set Defaults function assigns the Extension permission sets to users and user groups based on the current permissions and that should be enough in most cases.  If the user likes the advanced way that possibility is available.

When the user presses Finish the wizard data and the assigned permission sets are applied to the tenant database.

When I created the Setup Wizard page I started with a copy of the Email Setup Wizard, page 1805.

The model I have created to assign permission sets to users and user groups with a Wizard can easily be modified to fit any Extension.  Remember that all this code will soon be available on my GitHub account.

 

My first Dynamics 365 Extension – step by step – fifth step

Development and installation.

For my development I use source control management.  Soren Klemmensen did a short demo of that setup in his session in NAV TechDays 2016.  We are working on making that solution public in a few months.  In every branch we have a setup file in a json format. That file has all the parameters needed to build an extension.  Here is the one I use for the G/L Source Names project.  When I have this Extension completed I will publish it to my GitHub Account.

For every extension we need to make sure that the installation and configuration experience for the customer is easy.  When the Dynamics 365 for Financials user open the Extension Management page our Extension should be visible there.

Here we can see that we need to create images for our Extensions. Later in the process, when we register the Extension on AppSource we will need to supply images in different sizes for out Extension. The image that I used when I created my Extension is 250×250 points. Starting the installation will take the user through an installation wizard. In the installation process the user sees all the properties we add to the Extension manifest definition. I create the manifest with the following code.

The image and a set of screenshot images are used when creating the Extension package file (navx).

In the below screenshots you should be able to see how my parameters are used in the installation process.  I have not yet seen my screenshots used in the Extension installation.

Web links, in the order of appearance are the appUrl, appHelp, appEula and appPrivacyStatement parameters.

Installation done and the user has logged in again and ready to start the Extension setup process.

If the Extension contains any tables then it must also contain permission sets for every table.  From the parameters above you can see that I have three permission sets for my Extension.  One for read permissions, second for update permissions and the third for the Extension setup permissions.  I expect that the user that is installing the Extension has full permissions and is able to assign permissions to other users.

In a simple Extension like this, Extension that does not require any company based setup we still need to make sure that every user has the required permissions to use the Extension.  For this task I use the Assisted Setup feature.

Catch my next blog to read all about that.

 

NAVTechDays 2016

Now, ten days after a succesful NAV TechDays 2016, it is time to write a short recap.

NAV TechDays 2016

As usual I met with a lot of old friends and managed to gain new ones.  Had a great time.  I hosted a workshops on extending the Data Exchange Framework on Thuesday and Wednesday.  It looks like I am the only one in my MVP group to have dug deep into that functionality.  Huge thanks to the people who attended.  I always learn a lot from you guys.

On Thursday morning I had my first NAV TechDays session.  I talked about migrating to events.  I had a blast!

Luc has the video on Mibuso, so if you missed it or just want to relive the moment, go ahead and watch or download.

You can also watch the slides right here.  I have notes on most of my slides to better explain what I was thinking.

On Friday morning Soren presented Source Control.  There he talked about an initiative that Kamil and me started – to make Source Control available for every NAV developer.  Soren jumped on board and we can expect more to join.  On that note I have created my GitHub account where everyone can download the stuff that I publish.

I have published the presentations and objects to GitHub for everyone to play with.  What you download and do with it is on your own responsibility.

p.s. the NAV TechDays photo album is right here to browse through.

My first Dynamics 365 Extension – step by step – fourth step

I got the following response from Microsoft

Hello Gunnar,

We wanted to update you on your request to publish your app, G/L Source Names (Request ID# 835), on Microsoft AppSource. Based on our initial evaluation, your app has been moved to the Microsoft Dynamics NAV AppSource team for further evaluation. You will receive a follow up within 5-7 days or earlier with a status regarding your submission and next steps as relevant.

 Please let us know if you have any questions, or if there is anything we can do to help.

 Where you are in the process:

 appevaluationprocess

Request ID# 835

Thank you,
The Microsoft AppSource team

Soon after I got an Excel Template for my object request (microsoft-dynamics-365-for-financials-app-extension-questionnaire-and-object-range-request-form-october-2016).  Here posted for demonstration purposes, don’t use this for your actual process.

I did my object request and for this solution 50 objects is enough.

objectrequest

And this morning I got another email from Microsoft

Hi Gunnar,

50 objects have been assigned to “Kappi ehf.” (PSBC: 6433432) in the range: 70009200-70009249 for your app G/L Source Names.

You have most likely figured out by now that you need to be a Microsoft Partner.  Not a partner, jump to the partner website and sign up.

So, to PartnerSource Business Center to download a new development license.

licensekeyconfiguration

I like to start by downloading the “Permission Report Detailed (txt)” to verify that my objects are indeed in the license.

downloadkey

After verifying the below lines

I can download the license file and start my development process.  That process will be covered in later posts.

 

My first Dynamics 365 Extension – step by step – third step

I got a response from Microsoft from my first step.

Thank you for submitting your app for consideration to be listed on AppSource.

Once we have had the opportunity to review your app, you will receive a follow up within 1-2 weeks or earlier with a status regarding your submission and next steps as relevant.

Where you are in the process:

appsourceprocess

Request ID#: 835

Thank you,

The Microsoft AppSource team

This message from Microsoft is an important part of a program, service, or product that you or your company purchased or participate in.

From hereon I get out of sync with the steps on PartnerSource:

Step 3: Build your app

Find more information on how to build an extension in our learning plan on the Dynamics Learning Portal (DLP) (coming soon).

Refer to the Technical Validation Guidelines for Dynamics 365 for Financials (coming soon) to get insight into app technical requirements and recommendations.

To build the app I need to go through many steps.  You are building experience, not a solution.  Therefore we must make sure to have;

  • ToolTip for every field and every action
  • Correct value for ApplicationArea
  • Permission Set(s)
  • Friendly notifications
  • Assisted Setup
  • Help web page(s)
  • Help video(s)

I will go through this list in later blog posts.

Now for the main topic in this post.  Dynamics 365 requires all extension packages to be signed with a code signing certificate.  Microsoft says:

To sign an extension package

To help validate the authenticity of an extension package (the .navx file), we recommend that you have it signed. Code signing is a common practice for many applications. For more information about code signing, see Authenticode and Introduction to Code Signing in the MSDN Library.

  1. To sign an extension package, you need a computer that has the following:
    1. A code signing tool, such as SignTool or CodeSign.SignTool is part of the Windows Software Development Toolkit. For more information, see SignTool.
    2. Microsoft Dynamics NAV 2016 or later.
  2. Obtain a certificate that is enabled for the code signing purpose. You can have certificate as a file or installed in the certificate store of the computer.
  3. It is optional but we recommend that you use a time stamp when signing the .navx file.
  4. Sign the .navx file by using your signing tool.

So, if you want to publish to Microsoft AppSource get your self a valid code signing certificate.  There are number of vendors that can sell a code signing certificate.  Bing delivers this list.

I was allowed to quote one of Microsoft employees:

“I would only suggest using a self-signed certificate for testing and development purposes. If you plan to submit the extension as an app for Dynamics 365 for Financials, you will need to use a certificate from a trusted third party certification authority.

Every version of the extension doesn’t need to be signed using the same certificate. A new version could be signed with a different/new certificate.”

If you don’t already have the SignTool installed you can download it here for windows 7 and 8 and here for windows 10.  On Windows 10 all you need to select in the install process is the Windows Software Developement Kit.

sigtoolinsert

When the installation finishes you will find the SignTool.exe in the folders:

  • x86 -> C:\Program Files (x86)\Windows Kits\10\bin\x86
  • x64 -> C\Program Files (x86)\Windows Kits\10\bin\x64\

When I create the application package (navx file) I check for my code signing certificate and if not found I create one.  Now, of course this is done in PowerShell.

The first two lines are used to import modules and parameters from the AppPackageSettings file (below).  Lines four to nine create the application package (navx file), Lines eleven to seventeen check if the certificate selected in my AppPackageSettings is present, and if not it will be created in the certificate store and exported to a file.  For this to work this script has be executed in elevated mode (Run as Administrator).

Last line uses the SignTool to sign the application package (navx file).

My AppPackageSettings file looks like this

Don’t worry, I will share the whole script package when the time is right.

When I have the correct code signing certificate I update the two last lines in the settings file and point to my brand new certificate.

In next step we will start coding in C/AL – stay tuned.

 

My first Dynamics 365 Extension – step by step – second step

Now I need to be recognized as a developer.

Step 2: Complete Microsoft Development Center registration

Before you can publish your app to AppSource, you will need a Microsoft Development Center account.  A developer account lets you submit apps to Microsoft marketplaces, including the Windows Store, Office Store, Azure Marketplace, and Microsoft AppSource.

You can check to see if you already have access or register here:
https://developer.microsoft.com/en-us/store/register

NOTE:  You only need one developer account per company (not one per submission); a one-time registration fee applies.

This was a rather easy step, just needed to use my credit card.

I will go ahead and try the next step.  See you soon…

My first Dynamics 365 Extension – step by step – first step

You could say: “It is about time…”

And you would be right.  Finally, I am back to my blog.

My goal is to deliver my first app to Microsoft AppSource.  You can find a step by step instructions on PartnerSource.

I want to start with a very simple extension.  If you look closely at a general ledger entry in NAV and Dynamics 365 you will see that there are fields with information about the entry source.  For example, if you post a sales invoice then the customer will be the source.  If you post a purchase invoice then the vendor will be the source.  If you look at the balance account for a bank account you will see the actual bank account number as source.

My goal here is simple.  I want to add this information to the general ledger entry page.  Additionally I want to show the name for each customer, vendor or bank account.  After installation of this extension the user will be able to browse through his general ledger entries and see the source information for each entry.  Here is an example for CRONUS G/L Account No. 5610.

modifiedglentries

You can also see on the above screen shot that I have added a button to open the source card directly from the G/L Entry.

Today I will do the first step.

Step 1: Submit your app idea for pre-approval

We will review your app idea, provide any relevant feedback, and pre-approve.  Submit your idea here: Microsoft AppSource.

After pre-approval, you will receive a unique object range for your app along with additional information to guide you through the development, validation, and publishing of your app.

I will do my next blog post about step 2 and so forth…