If you’ve been using the custom help toolkits for Dynamics 365 finance and operations apps or Dynamics 365 Business Central, then change is coming your way. If you’ve never used either toolkit, you can stop reading now.

What’s changing

The custom help toolkits started out as a way to connect your own help content to Dynamics 365 and to customize Microsoft’s help content. But times change, technology changes with them, and we no longer recommend that you customize our content. Instead, we recommend that you create your own help content using any tools you prefer, and then let that override Microsoft’s content.

After April 11, 2023, the toolkits will be archived.

We’re also removing content from our contributor guides that encourages customizing our content. Everyone can still contribute to our documentation, but in English only.

Why are you making this change?

The custom help toolkits are being used less and less. We know custom solutions are still running on versions that are or soon will be unsupported. We expect those migration projects will be complex enough that existing custom help can’t be easily reused.

If you find that you need one of the tools in the archived toolkits, you can download a release package and extract the one you need.

What about custom help?

If you develop a solution that’s based on Dynamics 365, you should continue to deliver documentation for its users. Use any tools you prefer.

If your solution includes Dynamics 365 Finance, Supply Chain Management, or Commerce, and you need to connect your content to the in-product help pane, download the AzureSearchCustomHelp solution. Learn more at Connect a custom help website to the Help pane.

Not yet a Dynamics 365 customer? Take a tour and get a free trial.

The post Custom help toolkits for Dynamics 365 to be retired in April 2023 appeared first on Microsoft Dynamics 365 Blog.

In any business operations software, the ability to visualize, inspect, and print data in an appropriate layout is paramount. In Dynamics 365 Business Central and in most other software, reports serve these purposes.

Our partner community is familiar with customizing built-in reports, either as suppliers of a vertical solution that adds capabilities to underlying data which must be reflected in the relevant reports, or as resellers who tailor reports to meet individual customer requirements.

In the past, you had to modify existing reports through code customization by directly editing the report object.

In Business Central online, direct customization is not possible. Instead, you add new objects or modifications in a controlled manner through extensions to the base product. The extensions make it easier to deploy, maintain, and upgrade the software.

However, until now you weren’t able to extend report objects, so partners had to copy and branch any report that required modification. These steps were a pain point that incurred costs and a maintenance burden even for the simplest changes. As a result, closing this gap has been the highest voted idea on the Business Central Ideas site year after year.

2021 release wave 1 brings support for report extensions in Dynamics 365 Business Central. You can now extend both document type, visual reports as well as processing reports. You no longer need to branch reports when you add capabilities, and multiple solutions can now add to the same base report dataset. Plus, as a reseller who adds additional customer requirements and custom layouts, you have access to all of the resulting report datasets.

With the introduction of report extensions, there are two approaches to customizing reports:

• Use the event-based substitution of a report, which is useful for taking over reports without changing any actions in the user interface.OK
• Use the new report extension for making additive changes.

New report extension AL object

Report extensions are based on a new object type in AL, the programming language used for manipulating data and controlling the execution of the various application objects, such as pages, reports, or codeunits. With this object type, you can extend an existing report in several different ways, including the following:

• Add new columns to existing data items.
• Add new nested data items.
• Add columns for fields in a source table, a table extension, related tables, variables, procedures, or expressions.
• Add a new RDLC layout or Word layout.
• Add or modify the request page.

Note that there is no support for extending or modifying an existing layout.

In an upcoming service update, we will add support for labels, as well as some limited abilities to modify existing data items, such as adding to request fields, calc fields, or triggers.

Use report extensions to make additive changes to existing reports, such as adding a country column to the existing customer top 10 list.

Choose layouts from report extensions

When an extension deploys to a customer environment, either as an AppSource app or as a per-tenant extension (PTE), any report layouts in the extension also become available in the environment. However, if you want to apply a report extension layout to a specific report, you need to add installation and upgrade code in the extension. Users will be able to choose a layout from a report extension in the Report Layout Selection page that lists all available layouts for a given report.

The Report Layout Selection page includes any layouts from report extensions so that the user can choose between all available layouts.

Next steps

Learn more about report extensibility in the release plans, the documentation, or at the virtual launch event session LE21-08 What’s new in Visual Studio code and AL, which covers report extensions in detail. The virtual launch event site has many other valuable sessions on new features in Dynamics 365 Business Central 2021 Wave 1 release.

We encourage you to explore the new report extension feature and provide feedback to our AL GitHub repo. You can also submit any suggestions for additional coverage or improvements on the Business Central Ideas site.

The post Extending reports in Business Central appeared first on Microsoft Dynamics 365 Blog.

If you’ve created your own custom solution for Dynamics 365 Finance, Dynamics 365 Supply Chain Management, or Dynamics 365 Commerce, you may be wondering how to connect your own Help content for the solution to the Help pane in the Finance and Operations client.

Microsoft provides a toolkit to help you generate HTML files from the Microsoft Help repositories, generate JavaScript Object Notation (JSON) files for search services, and change the locale of HTML files so that it matches the locale of your solution. The toolkit has now been updated in GitHub, and we’re looking forward to learning more about how the updated toolkit works for you.

Next time that you run your scripts to get Microsoft’s content from GitHub, make sure that you use the latest version of the toolkit, which brings additional support for working with the files. If you’ve never run the toolkit, now is the time, because it’s easier than ever to get a copy of Microsoft’s content and merge that with your own content for the best user experience.

For example, if you want to fetch Microsoft’s content for English (US) and German, here’s the new command that you can run in PowerShell if your solution is based on Dynamics 365 Supply Chain Management.

HtmlFromRepoGenerator.exe –json articles/ –out “D:\D365-Operations\de” –repo “https://github.com/MicrosoftDocs/Dynamics-365-Operations.de-de” –externalText “(This is an external link)” –EnRepo “https://github.com/MicrosoftDocs/Dynamics-365-unified-Operations-public” –EnOut “D:\D365-Operations\en-us” –replaceUrl “https://docs.microsoft.com/de-de/en-us/dynamics-365/blog/supply-chain” –lng “de” –LogsDir D:\D365-Operations\logs\de

Fork or clone the repo

To use the toolkit, we recommend that you fork or clone the repo at https://github.com/Microsoft/dynamics365f-o-custom-help. If you don’t want to get a GitHub account, you can instead download the toolkit as a .ZIP file.

Should you download, fork, or clone the repo? That depends on your needs. To be notified of future updates to the toolkit, it’s better to fork or clone the repo. If you want to extend the tools for your own use, you’ll probably want to fork the repo so that you can make any customizations that you want. If you just want to get the tools, you should clone the repo. In both cases, you’ll be notified when we make changes.

With this update, we invite you to collaborate with us on the tools. You can submit feedback using GitHub Issues, or submit a proposal for changes with a pull request, because the repo contains the source code for the tools. You can also request new tools by submitting your suggestions on the Ideas site.

Use the tools to configure the Help experience for your users

The following table outlines the main objectives that admins typically have for configuring the Help experience, including links to where you can read more about the tools.

The following link provides a video that shows how you can contribute to the Microsoft documentation.

How to contribute to the Dynamics 365 documentation

We hope you’ll start using the updated toolkit for your custom Help. Let us know if you have any feedback!

The post Get the updated toolkit for easier deployment of solution-specific Help content appeared first on Microsoft Dynamics 365 Blog.

We’re proud to announce that you can now find learning paths and e-learning modules on Microsoft Learn specifically for Dynamics 365 Business Central.

You can use this new content to educate yourself about business functionality, or to brush up on how to use multiple currencies, for example. Microsoft Learn is a completely free, open training platform available to anyone who has an interest to learn about Microsoft products – check out the FAQ!

To help you get started, we provide learning paths for the complex and not-so-complex end-to-end processes:

This e-learning library has been developed in a partnership between the Business Central team and e-learning specialists from Microsoft and the partner community. New content will be added in the coming weeks, so go to https://aka.ms/learn, set a filter for Business Central, and start learning!

Best regards,

Margo Crandall, Business Applications Group Learn

Eva Dupont, Business Applications Content Experience

The post Learning paths for Dynamics 365 Business Central on Microsoft Learn appeared first on Microsoft Dynamics 365 Blog.

Earlier, I blogged about the Dynamics 365 Business Central user assistance model and what we expect you to do about it. In this blog post, I’ll talk more about the Learn More content that we publish on the Docs.microsoft.com site, how we collaborate on delivering it, the tools and processes we use, and how you might be able to adopt some of our best practices.

The purpose of the docs

As I mentioned in the earlier blog post, we have three layers of user assistance where the context-sensitive links to Learn more play an important part by providing context and links to additional information. In other words, this is not really product Help in the classic sense where the product Help is intended to answer all questions in daily use of the product. There is nothing wrong with that type of Help and, believe me, I’ve written lots of it. But when we started work on what is now Dynamics 365 Business Central, we decided to tackle user assistance in a different way. Business Central is cloud-first, and that changes how we think about the functionality and the user experience.

So the docs are still docs, but the content is not an online version of a user manual. The product itself does far more of the job of helping people figure out how to complete tasks compared to way back when I started working on software in the ’90s.

In other words, the docs are there as a supplement, not a prerequisite. This applies to the business functionality content more than to the developer and IT-Pro content, but we work on both sets of content in roughly the same way: In MarkDown files in GitHub repositories where we collaborate with program managers (PMs) and engineers to develop the content.

Let’s take a look at how that works in the daily lives of the Business Central team.

How content is created and published

All content on the docs.microsoft.com site is created and published in the same way:

1. Person A creates a MarkDown file, adds content, and then submits it to a GitHub repository.
   The new file is automatically processed by our build system for the docs.microsoft site and rendered on an internal staging server where we can preview the content before it’s published.
2. If Person A is a technical writer like me, they will then send a link to the internal staging server to the PM and/or software engineer that they are collaborating with for technical review. The reviewers will submit a pull request with changes that Person A will then merge into the relevant branch.
3. If Person A is a PM or engineer, they will ask a writer to review the changes before the pull request is merged into the master branch. The writer usually makes light edits as part of the pull request and, if needed, more substantial edits in a separate iteration.
4. After a couple of iterations, the content is ready to be published as part of the weekly refresh (we publish every single Monday, in case you didn’t know), unless it has to wait until the next major update for Business Central.
   We have subbranches for individual features that are then merged into the relevant branch when it’s ready to be published as part of the monthly service update or the major update in April or October. Keeping track of what must be published when is not always easy, but we have two main tracks: Bug fixes and new features for the next major release.

The build system that the docs.microsoft.com site uses is essentially a bunch of scripts, but the main engine is the DocFx tool that you can also use. For more information, see https://dotnet.github.io/docfx/. We’re privileged by the fact that Microsoft is a pretty large company, so I don’t know much about the build system because it’s managed by a completely different team in a completely different part of the company in a completely different country.

Working in MarkDown files

I’m a technical writer, so I do heavy-duty work in MarkDown files in my local clone of the different repositories on my laptop. The PMs that I work with mainly do more lightweight work, so they tend to just make changes right in the browser at the equivalent of https://github.com/MicrosoftDocs/dynamics365smb-docs/tree/master/business-central. But let’s take a closer look at the tools I use. These examples are based on our internal, private repo that you can’t access, but the same principles apply to the public repos.

First of all, I use Visual Studio Code with a couple of nifty extensions, not least the Docs Authoring Pack, which I highly recommend. In general, jump over and take a look at what some of my colleagues are publishing in the Docs Contributor Guide!

Then I use GitHub Desktop to get updates from GitHub and then push my changes back to GitHub – my teammates are working in the same repositories as I am, and we synchronize changes several times a day to make sure we aren’t undoing each other’s work. It’s one of the drawbacks of having moved to GitHub: If you’re not careful with your commits, you can accidentally overwrite changes made by someone else, so pay attention to what is being merged in your pull requests!

This is what it looks like when I start work after someone else has submitted changes:

Once I pull those changes down, GitHub merges them into my clone so that I am ready to work on the latest version. In case you’re wondering, the screenshot is from the private repo that we use internally, but it’s the same mechanism in all repos.

Here’s what I see when I then open the folder with the Business Central docs in Visual Studio Code:

The green squiggly lines are validation errors thrown by the Docs Authoring Pack. In this case they’re shown because it wants a blank line after each heading. When I first wrote this article I was using the Atom markdown authoring tool, which doesn’t insist on blank lines after headings. Visual Studio code does, hence the squiggles.

After I’ve made my changes, I use GitHub Desktop to commit them.

Note the blue button at the bottom of the window – this is GitHub telling me what I’m about to do. in this case, I’m pushing to the master branch, which is the basis for content ready to go live. If I had intended this change to get published later, then I would have to stop here and commit my change to another branch.

In this case, it’s a small update that I want to apply to the already released content, so I’m committing to the master branch. After I commit the changes, I have to push the commit to GitHub.

This step is about pushing my change from my clone up into the online GitHub repository. The terminology can be confusing at first, but the trick is to think of the clone as being on your computer and the “real” repository being up in the cloud. At least, that’s done the trick for me.

Collaboration

As mentioned, having moved our docs to GitHub repos has enabled collaboration scenarios that we have dreamed about for many years. You as our partners, can extend and customize our docs easily because the public GitHub repo is always there for you to pick up from. No more native tooling because there is a world of open source tools readily available. And you can submit GitHub Issues or pull requests if there is something you want to change in the docs. This transparency and flexibility works very well for the way that our product, Dynamics 365 Business Central, is extended and customized, don’t you think?

We welcome your contributions, even when it might seem that we don’t, such as when it takes a while before we process your feedback. We’re a small team with a lot of work to do, and we don’t mean to appear like we don’t appreciate your feedback.  And that goes across our portfolio – application and developer content for Business Central, application and developer content for Dynamics NAV, and the emerging application and developer content for Dynamics GP.

For Dynamics NAV and Dynamics GP, our own support folks are actively contributing to the docs already, and you can as well. However, we only accept contributions to the English (US) source at this point in time.

For Business Central, we very much also welcome contributions, but as you know, the product is still evolving, and that means that docs are as well. For example, if you are frustrated that you can’t read about how to develop a specific solution in the new development environment, then that’s probably because the tooling isn’t available yet. Don’t be frustrated. Instead, rejoice in the fact that you are part of the collective journey that we are on in a true partnership to evolve Business Central.

So if you want to contribute to the content, just find the relevant place in the docs, notice the file name in the URL (it’s the last bit of the URL, such as contributor-guide), then find the right repo in GitHub ( business functionality is at https://github.com/MicrosoftDocs/dynamics365smb-docs, developer content is at https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb), find the file, and hit the Edit button. You will then get a notification like this:

You’ll need a GitHub account to do this, of course, but that’s easy to get. In your fork of the repo, you then make the changes that you want to make, and you end up submitting a pull request to our repo. For more information, see the GitHub docs.

We share our tools and processes with you, so join us, and collaborate on the content. We welcome you! For more information, see Extend, Customize, and Collaborate on the Help for Dynamics 365 Business Central.

Content in agile development projects

Some of you have moved to agile development methodologies, but you’re struggling to find out how you can deliver Help for your apps and solutions. Depending on whether you have in-house technical writers, or if you depend on external service providers to generate the docs for you, you’ll find different solutions to this problem, I am certain.

If you’re looking for inspiration, I have written several examples on LinkedIn about how to use agile methodologies to help you structure work and produce the content that you need.

For more information, see my post on LinkedIn. And keep up the good work that you’re already doing!

PS: This blog post was first published on the Communities blog in December 2018 but has been migrated and updated here on the Dynamics 365 blog.

The post Collaborate on content for Dynamics 365 Business Central appeared first on Microsoft Dynamics 365 Blog.

As part of getting your Dynamics 365 Business Central app validated for AppSource, you are expected to deliver content that helps users understand how to use the functionality that your app provides. Think of this as Help or docs, and you’re off to a good start. But there is more to it than that, and that’s what this blog post will try to help you get onboard with.

The Business Central user assistance model – and what that means to you

We have three levels of user assistance, meaning ways in which the product helps users understand what is going on. You can read about that in the docs, but here are the three things we want you to do:

• Help users get started
• Help users get unblocked
• Help users learn more

Help users get started

The user assistance concept of Get Started is not just about getting started with Business Central on the first day. It’s also about getting started all the other days, and about getting started with infrequent and unfamiliar tasks. Assistance in the shape of wizards is very helpful for setting things up, or filling in data for a complicated report, for example. Designing Home pages that are truly designed for that particular role or job is also very useful in helping users get started with their work every day – they can easily get to their most important tasks, and that means that Business Central helps them get their work done more efficiently.

You’ll also want to make it easy to onboard new customers – and your existing customers’ new employees.  For example, you can prepare a trial version of Business Central that you share with prospects and new users so that they can try out Business Central, or you can do in-hourse training based on such a trial tenant. Add tours or in-product videos, since such content can help with the onboarding.

We don’t have a firm rulebook that you can measure your app against, but we encourage you to design your interface with the intention to help users get started every day in mind.

Help users get unblocked

Even the best designed user interface can still be confusing to some. It can be difficult to predict what users will find confusing, and that is why we have applied tooltips to all (or almost all) controls and actions in the base application. In combination with descriptive captions and instructional text, the tooltips are our current implementation of embedded user assistance, which is an important principle in today’s world of software design.

The tooltips are there to help users unblock themselves by providing an answer to the most likely questions the users might have, such as “What data can I input here?” or “What is the data used for?”. Keep that in mind when you develop the user interface of your solution.

Help users learn more

So, you added the tooltips, you designed a user interface that helps users get started with their work, but the users are still asking for more?

Yes, of course they are – users are people, and people always want more, in case you didn’t know that from your own experience. But that’s not the point of the docs that we publish under the user assistance concept of Learn more. This content is in part intended to answer those questions that the user interface (including the tooltips) can’t answer, such as where that page fits into the bigger workflow, or what comes next, or what would be the alternative, and so on.

We’re publishing our content to an online library (Docs.microsoft.com) so that it can also serve as onboarding material and as feature overviews that you can share with prospects. The content is written in MarkDown, and our source files are available in a public GitHub repo so that you can extend and customize it for your customers. You can read about that in the Contributor Guide.

The link between the Help articles and the various pages in the user interface is managed based a mapping between page objects and target articles, but the configuration of where those targets are published is set at the application level – and that means that you can customize that configuration.

Customize the Help experience

With the April’19 release, we made it easier for you to customize the links to the Help. Your app can hi-jack the configuration of where the content lives for all or specific languages, and you can add context-sensitive, relative links to the Help in your code for individual page objects. If your solution is used on-premises, then you can configure the clients to use either an online library (actually, it can also be a private website) or the legacy Dynamics NAV Help Server.

You don’t have to convert your existing content to MarkDown, but we recommend that you do because it makes your job easier down the road. Working in GitHub and MarkDown means that you have access to a world of open source tools and no longer have a hard dependency on Microsoft providing you with tools. For more information, see Migrate Legacy Help to the Business Central Format.

Configuring for online and on-premises

You can use the same content for both online and on-premises deployments of Business Central – we do that: The same user interface design, the same tooltips, the same Learn more content. But you can also choose to have one set of content published to a public website for your online customers, and another set of content published to your on-premises customers’ own websites.

In fact, you can make things as simple and as complicated as you like. The rulebook is pretty much gone, and the ties are off. You can extend and customize the user assistance so that it works for your solution and your users.

Example

But let’s take a look at what it could like like in your AL app.

App-level configuration

Let’s say that you’re building a localization app, or perhaps you’re building a vertical solution. In both cases, you’ll want to take over the configuration of where the links to find context-sensitive Help. This is done in the app.json file for your app as shown in this example:

"contextSensitiveHelpUrl": "https://mysite.com/{0}/documentation",
"supportedLocales": [
"en-GB", "en-IE
],

In this example, the contextSensitiveHelpUrl and supportedLocales properties specify that the links to the Help must go to the mysite.com site when the user is using the product in one of the two specified languages. In contrast, the help property in the app manifest specifies the link that describes the app or solution itself, and it’s used in AppSource.

That’s it.

Page-level configuration

Let’s say you’re building an app that adds a couple of page objects to the base application in Business Central. In this case, you’ll want to add a link to context-sensitive Help to each of your pages as shown here:

page 50101 "Reward Card"
{
PageType = Card;
SourceTable = Reward;
ContextSensitiveHelpPage = 'sales-rewards';

}

With relative links like these, you don’t have to publish Help for the base application on your site, just Help for your particular solution. That’s what these object-level links do. The experience for the users is that if they want Help for the Customer Card page, they get Microsoft’s Help. If they want Help for the Rewards page, they get your Help. If they want Help for your Rewards field on the Customer Card page, they get your Help as well. Easy, isn’t it?

On-premises configuration

For on-premises deployments, you have access to configuration and customization in a different way. On-premises,  you own the end-to-end customization. As mentioned, you have a choice between using the same online library as your app in AppSource uses. Alternatively, use the legacy Dynamics NAV Help Server. For more information, see On-premises deployments.

Third party tools

There is a world of tools and best practices out there, isn’t that just great? The hard requirements are gone so that you can pursue the experience that your customers expect. Here are a couple of examples of what you can choose to do:

• You can add tours based on 3^rd party providers such as ClickLearn or WalkMe
• You can record and publish videos to highlight your features
• You can create and print a manual
• You can publish e-learning tutorials to a public or private site

For example, some of you have told me about an Open Source project where you can create content in MarkDown and then publish to an auto-generated website. It’s kind of cool, so check it out at https://www.mkdocs.org/. If you choose MKDocs, then you can configure your solution to use that site as the “online library” described above.

Oon a related note, one of my colleagues has published some tips and tricks for publishing to your own clone of Docs.microsoft.com on his private blog. There, he describes how you can automate the build processes in a way that even I (almost) understand.

Migrating content

For those of you who have been customizing the Help for Dynamics NAV, this is a major change. I hope you’ll agree with me that it’s a change to the better. You don’t have to use file-compare tools to figure out what we have changed in strangely formatted HTML files. You also don’t have to build anything using a particular tool.

On the other hand, some of you have made huge investments to the Help customization for Dynamics NAV. So what about that, now that you’re moving to Business Central? I wrote about this in another blog post: Reusing classic object-based Help on your Dynamics 365 Business Central Help Server.

You can also find links to related content in the docs at Extend, Customize, and Collaborate on the Help for Dynamics 365 Business Central.

PS: This blog post was first published in December 2018 on the Communities platform but has been migrated and updated here on the Dynamics 365 blog.

The post Extending and customizing the Help in Dynamics 365 Business Central appeared first on Microsoft Dynamics 365 Blog.

If you are upgrading customers from Dynamics NAV 2017 or earlier versions to the latest version of Dynamics 365 Business Central, then you probably have an existing Help solution for the customized functionality in their old Dynamics NAV solution. However, Business Central does not support the field-based approach to context-sensitive Help that Dynamics NAV 2017 and earlier use. So what to do?

The difference between Help in Dynamics NAV and Dynamics 365 Business Central

In this blog post, I will suggest a couple of options. None of them are particularly simple or easy workarounds, because Business Central understands Help in a completely different way compared to Dynamics NAV. It’s far easier to extend and customize the Help for Business Central than it was for Dynamics NAV 2009, for example – at least, I think so. The structure for the Help for the base application in Dynamics NAV was easy to understand but annoying to maintain: We shipped thousands of HTML files with each release, and you then had to guess which of them were completely new, which had been updated, and what that meant for your customized Help.

Here’s a list that I have shared before that outlines the journey the docs have been on since 1999:

Many of you never cared what Microsoft did with the Help, such as those of you who never installed the Microsoft content, or if you gave your customers PDF files rather than installed Help. That’s totally fine, and this blog post is not meant for you. Instead, I recommend that you read our content on how to migrate your content.

The rest of this blog post is for those of you who have existing content in the object-based format for a version of Dynamics NAV. In other words, you were planning to use the familiar Help Server with files such as T_12345.htm, T_12345_1.htm, N_12345.htm, R_12345.htm, and B_12345.htm.

But for Business Central, that no longer works for context-sensitive Help. Business Central relies on tooltips for the field descriptions and a mapping between page objects and conceptual Help for the description of features and workflows. So again: What to do?

Option 1: Use the object-based content as-is

This option is for those of you who prefer to keep things as-is until Microsoft comes up with a magic solution of some sort. That’s a perfectly legitimate approach, but it would mean that your Business Central customers would not get access to context-sensitive Help for your functionality.

If that’s an acceptable experience for your customers, then you can deploy a Help Server instance, populate it with your HTML files, and make sure that as much as possible is listed in the ToC.xml file so that users can find the relevant Help through navigation.

On a related note, you can still download the files that were made available for Microsoft Dynamics NAV 2017.

The download consists of 45 CAB files with the content from the Dynamics NAV 2016 DVD rebranded to Microsoft Dynamics NAV 2017. The download includes CAB files with the W1 application Help translated into each of the supported languages plus the local functionality for the country/region where that language is spoken. There are also CAB files with local functionality in English. The files were published as a single download so each administrator could choose exactly the files that they needed at the time. For more information, see Microsoft Dynamics NAV 2017 Classic Help Download.

Option 2: Update the Page Documentation system table with page-level UI-to-Help mapping

This option is for those of you who like to play around with PowerShell. I don’t, so I haven’t been able to give you an example of who to populate that mysterious system table that in the current version of Business Central provides a UI-to-Help mapping between page objects and Help.

In the current version, table 2000000198 Page Documentation, lists all page objects in the default version of Business Central and associates each of them with a target Help article. This means that multiple page objects can be associated with the same Help article, such as when a specific workflow involves multiple pages.

The table associates page IDs with target articles, but the URL to where to find the target article is specified at the application level that defaults to the https://docs.microsoft.com/en-us/dynamics-365/blog/business-central/ site. In an extension, you can overrule this URL so that all calls for Help go to your site instead, for example. For more information, see Configuring the Help Experience for Dynamics 365 Business Central.

Caution: The following content is intended as an example. You can choose to do things differently, and while you can use these scripts as inspiration, reusing the Dynamics NAV legacy Help, the legacy Dynamics NAV Help Server, and populating the system table, Page Documentation, is not the recommended path going forward. We recommend that you convert any existing content to the Business Central format instead, and that you fork our GitHub repos.

The way that Microsoft populated the system table was based on an Excel sheet in the following format:

In this example, you want to replace the values of the fields in the Relative Path column with classic page-level Help files:

With the Windows client and C/SIDE with the Object Designer soon gone, you cannot run that table anymore from the development environment. But you can find it in the SQL Server database and manipulate it there, for example. Or use PowerShell to set the ContextSensitiveHelpPage property on the relevant AL page objects, for example.

This option means that your users get context-sensitive Help on a page level, and you can then let them rely on Search and links to find information about tables, fields, and reports, if that is important to them and to you.

Option 3: Squeeze your field-level Help into tooltips and ditch the rest

This option is for those of you who want to deliver an experience that complies with the Business Central user assistance model but are fed up waiting for us to deliver you tools to help you achieve that. We might still surprise you in that area, but I can’t blame you for thinking you’re better off figuring it out on your own.

Again, this is where my lack of skills in PowerShell scripting comes into play. But I know it’s possible to write a script that takes the opening paragraph from a field topic such as T_12345_1.htm and puts that into the TooltipML property on the relevant page object. Or even better: Port the field description into the Tooltip property elements in the XLIFF file for your app, using whatever third party tool you use to process XLIFF files.

The following snippet illustrates what this might look like in an XLIFF file.

<ding="utf-8"?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:oasis:names:tc:xliff:document:1.2 xliff-core-1.2-transitional.xsd">
  <file datatype="xml" source-language="en-US" target-language=”da-DK” original="ALProject1">
    <body>
      <group id="body">
      <trans-unit id="PageExtension 3469146285 - Control 2143966609 - Property 1295455071" maxWidth="999" size-unit="char" translate="yes" xml:space="preserve">
        <source>Specifies the company's taxpayer identification number.</source>
        <target>Specificerer firmaets skatteydernummer.</target>
        <note from="Xliff Generator" annotates="general" priority="3">Page - Page</note>
      </trans-unit>
      </group>
    </body>
  </file>
</xliff>

Yes, you guessed it: We’re still working on getting our tooltips into XLIFF files.

Is this yet another breaking change?

No, it’s not. Business Central was born as a cloud-first offering, and the Business Central user assistance model serves that purpose. Getting from the Dynamics NAV 2016 Help experience to the Business Central user assistance model is not even as big a challenge as when we dropped the application manuals – and that wasn’t all that big a change to begin with because most of you kept the manuals from Navision Financials and shared them with your customers, if you were working on the product back then.

Then why is it so complicated, you may ask. Well, I might answer, it’s isn’t all that complicated. Here I have outlined a couple of scenarios, and there are probably many more. Depending on your particular solution and which format your existing Help is, things are either a bit tough or smooth and easy. Just like the code behind your solution – code customization makes upgrades more difficult, that’s just how it is. With the Help, you can even take it by degrees, slowly reworking the content you already have.

To make things easier going forward, join us in GitHub! For more information, see Extend, Customize, and Collaborate on the Help for Dynamics 365 Business Central.

Wait! What about Dynamics NAV 2018?

Oh, yeah … As you hopefully know, we were working on Dynamics NAV 2018 and Business Central at the same time, and as a result, the code change that disabled the classic way of looking up context-sensitive Help based on object IDs trickled back into Dynamics NAV 2018.

We did it on purpose at the time as part of a simplification effort that aimed at making things better for Business Central online, but we forgot that it would affect Dynamics NAV 2018 customers.

The good news is that you can use your classic object-based Help on a Help Server instance for both Dynamics NAV 2018 and Business Central on-premises. But as explained above, the website cannot give your users context-sensitive Help.

I hope we will have good news about context-sensitive Help in a few months, so cheer up, and let’s move forward.

The post Reusing classic object-based Help on your Dynamics 365 Business Central Help Server appeared first on Microsoft Dynamics 365 Blog.

You can get Dynamics 365 Business Central in many countries and regions across the world, including Russia. This includes access to context-sensitive Help articles for the base app. But the Learn more links on tooltips for those pages and fields that are part of the local functionality in the Russian version have not been working.

This is because there was no Help to link to for historical reasons. But now there is! We’re delighted to announce that Awara IT have helped us create Help for the local functionality in the Russian version!

Collaboration process

As part of our collaboration, two people from Awara IT submitted pull requests to our GitHub repo with the source files for the Help. Now for the complicated: We have a public GitHub repo for all languages that Microsoft translates into. But the https://github.com/MicrosoftDocs/dynamics365smb-docs/ repo is particular because it’s the twin of our source repo. Our actual source files are in a private repo. This helps us manage the content on the Docs.microsoft.com site. We have a script that pulls any contributions from the public repo to the private repo. And from there, we have now published to the Docs.microsoft.com site:

https://docs.microsoft.com/en-us/en-us/dynamics-365/blog/business-central/localfunctionality/russia/russia-local-functionality

The content is available in English only at this point in time. Awara IT have also submitted the content in Russian, and we are now getting that ready for publishing.

Why the delay? Because we have to fit the content into our existing translation processes where English is the starting point. Also still pending is the work to hook up the Help with the page objects, but we’re getting there bit by bit.

Thanks!

This would not have been possible without our collaboration with the smart people at Awara IT. They suggested it, and I was delighted to finally close a gap that we have had in the Help for a long time. This shows the strength of the Dynamics 365 Business Central community and our collective dedication to the success of our customers.

My special thanks go to Aliia Salikhova and Diana Malina from Awara IT. With their pull requests, we have now proven that the collaboration process works. Good work, great collaboration, and a fully transparent process – this is the Dynamics 365 Business Central community at work!

The post Docs for the Russian local functionality for Dynamics 365 Business Central appeared first on Microsoft Dynamics 365 Blog.

Dynamics 365 Business Central and Dynamics NAV use SQL Server Report Viewer control libraries to render our reports. 

The history of RDLC reporting 

The RDLC report template gets compiled into a small assembly and then in the runtime, that assembly is used to parse the data set and hereby generate a PDF or EMF pictures for printing. 

Inside reports, you can embed Visual Basic .NET code to do some advanced handling, for example. Depending on the code’s security asks, the report is either rendered in the server’s AppDomain or in another secure AppDomain that is generated by Report Viewer.

Running in the Report Viewer-generated AppDomain requires a lot of marshaling in between the two AppDomains, which results in much longer rendering times on reports, which means performance issues. For that reason, we only wanted to run the reports in the Report Viewer AppDomain when it was really needed. 

IMPORTANT: If you ran the reports in the server’s AppDomain, there would be a slight memory leak, because each of the created assemblies would never get unloaded in the server AppDomain. However, if the same was done in the isolated AppDomain, we would be able to get rid of the assemblies, by unloading the secure AppDomain. At the time, we decided that the trade-off between performance gain over the small leak was acceptable. 

Just before we launched Dynamics NAV 2013 R2, we changed the .NET runtime to version 4.0. In .NET Framework 4.0, Code Access Security (CAS) was deprecated because it was way too complicated. Anyway, if you allowed another assembly to load in your process, it was better to trust them up front or isolate them completely. However, Report Viewer continued to use the CAS policy. With the deprecation, all renderings were deferred to the Report Viewer-generated AppDomain and therefore running slowly with performance issues. 

Over time, we realized that we could start the process with a CLR legacy switch: 

  <NetFx40_LegacySecurityPolicy enabled="true" /> 

For more information, see https://docs.microsoft.com/en-us/dotnet/framework/configure-apps/file-schema/runtime/netfx40-legacysecuritypolicy-element.

This would enable us to achieve the old behavior, although with various consequences to the CLR process. As an example, we would not be able to use the Dynamic Language Runtime (DLR) and enable assemblies in non-homogenous AppDomains.

There have been several blogs written on this over the years (thanks to Duilio Tacconi from Microsoft Support) to help our community design their reports for performance: 

• RDLC Report and Performance in Microsoft Dynamics NAV
• RDLC Report and Performance in Microsoft Dynamics NAV 2015 and 2016

That was a description of the past. Now let’s look at how things work today. 

Reporting in Dynamics 365 Business Central 

Dynamics 365 Business Central online runs in Windows Azure. We have a new development environment, and we are using a lot of great features in our product, developed and released by many great teams inside and outside of Microsoft. One of the new features is used for communication between tiers, (SignalR). 

Business Central uses SignalR to communicate with the language service in Visual Studio Code, which is our new development environment, and the backend endpoint in the server. SignalR uses DLR in its implementation, so we turned off the legacy switch described above to do the communication in the development environment. This meant that rendering reports locally on a development machine would be much slower (e.g. REPORT.SAVEASPDF, REPORT.SAVEAS, etc.). 

Time was ripe for a rewrite of the server–rendered reports. In the Business Central October’18 update 4 (February 2019), this was all completely rewritten. 

Instead of running rendering in the server’s standard AppDomain, we create a specific Report AppDomain where we can control exactly how marshal the data. In the end, we specify two marshaling operations: 

• One for the RDLC stream 
• One for the data stream 

This means that we can now control the loading and unloading of the AppDomain and thereby control the performance of trusted reports. At the same time, we can unload the dynamic assemblies that are generated by the rendering, while still the DLR features are still supported. 

The Report AppDomain, by default, recycles on every 1000 renderings, which helps avoid piling up too much memory. 

This effectively means that if you build RDLC reports, we recommend that you stop using the legacy switch, because it will only revert the server to the behavior that we had in previous releases with slight and controlled memory leaks as consequence. 

How to configure the reporting environment 

To control how you would like to run your rendering, a set of switches has been introduced. Let’s go through them with a description of what they do together. Most of these switches are internal only, meaning there should be no need to mess with them, but for backwards compatibility reasons, they are still offered. 

To use the legacy switch 

  <NetFx40_LegacySecurityPolicy enabled="true" /> 

This switch sets if you want to run in the server’s AppDomain. If you enable the switch, all the new Report AppDomain isolation logic is disregarded. If you set the switch to false or remove it from the config files, the new logic kicks in and you will have fast reports rendered in the Report AppDomain. 

To run completely isolated on all renderings 

  <add key="LegacyReportAppDomainIsolation" value="true" /> 

If you add this switch to the CustomSettings.config on the server, you will be able to render reports in the high-security AppDomain, but you will have to set NetFx40_LegacySecurityPolicy to false or remove it completely. This will make all reports run slower. 

This switch is not available in the management UI. 

To control when to recycle the AppDomain 

  <add key="ReportAppDomainRecycleCount" value="1000" /> 

If you add this switch to the CustomSettings.config on the server and have enabled the new Report AppDomain, you will then be able to influence when the server will try to unload the Report AppDomain. I would not recommend changing this switch, which is why it is declared as internal. 

This switch is not available in the management UI. 

To control that custom RDLC layouts are trusted 

  <add key="ReportAppDomainIsolation" value="true" /> 

Specifies if application domain isolation is used for rendering custom RDLC layouts. Since custom reports are created by end-users in the client, they can contain some inline Visual Basic .NET code. For that reason, we would enforce secure AppDomain isolation to avoid any security risks from rendering custom RDLC layouts. However, it can considerably increase the time it takes to render reports.  

Disabling application domain isolation (<add key=”ReportAppDomainIsolation” value=” false ” /> ) can improve the rendering time but might have a negative impact on security and reliability.  

To be secure by default, we recommend that you leave this setting at the default value of true and change it only if you are running an on-premises installation where you can fully trust any custom report layout uploaded by end users. 

This does not apply to changes done through C/SIDE customization or AL extensions. 

 NOTE: The name of the switch will change in next major version because the name is not precise enough and we want to avoid confusion.  

The new switch will be <add key=“IsolateCustomReportLayoutsToSecureAppDomain“ value=“true“ /> 

Author:

Torben Wind Meyhoff – Dynamics 365 Business Central Server Architect 

The post RDLC Report Performance Enhancements in Dynamics 365 Business Central appeared first on Microsoft Dynamics 365 Blog.

With Dynamics NAV 2018, we invite you all to join us in GitHub where you can pick up content to customize, extend, or suggest changes to.

Find the right repo

For practical reasons, we have a lot of different repos in GitHub to support our various languages and target audiences. We hinted at it when we moved to the new Docs.microsoft.com site, and we talked about it at Directions in 2018, but here is the official statement:

• The Dynamics NAV 2018 application Help source files are here: https://github.com/MicrosoftDocs/nav-content
  • This includes the source files for the W1 application in the root folder, and for the supported localizations in the LocalFunctionality subfolder
  • We’ll update the master and live branches on occasion because the content publishes to the Docs site here: https://docs.microsoft.com/en-us/dynamics-nav-app/
• For each supported language, the translated files are in a translation repo
  • https://github.com/MicrosoftDocs/nav-content.da.dk for the Danish language
  • https://github.com/MicrosoftDocs/nav-content.nl-nl for the Dutch language, and so on
  • This content also publishes to the Docs site
    • Danish to https://docs.microsoft.com/da-dk/dynamics-nav-app/
    • Dutch to https://docs.microsoft.com/nl-nl/dynamics-nav-app/, and so on
• Baseline content for Dynamics NAV 2017 and Dynamics NAV 2018 is available as releases in the English source repo
• The repos contain conceptual descriptions of the capabilities of the Dynamics NAV application. We are not adding other content types, such as application reference for tables, fields, reports, batch jobs, or windows.

Customize the Help from Microsoft

By now, you’ll have found the repo with the files that you want to customize. But what to do next?

Get a GitHub account and fork the repo

That’s step 1, and you might already have done this. If you don’t have a GitHub account, we recommend that you sign up for one using the email account that you prefer. This is because you must be signed in to fork a repo, which is our recommended approach to customizing or extending the Microsoft Help.

If you’re signed in, then click the Fork icon in the top-right corner of the page.

The fork is essentially your shadow copy of the Microsoft repo. There, you can make any changes that you want without getting into trouble. If you want to suggest changes to us, you can submit a pull request to the English source repo.

Anyway, fork the repo, and then clone the fork so you get the files on your local disk (or VM or whatever). Make your changes, add your own content, and then use DocFx to generate files that you can deploy to the Dynamics NAV Help Server or any other website. Tips and tricks in the readme.md file in the source repo.

In fact, anyone can contribute to our content, or to your content, if they have access to the repo. nav-content is a public repo, so everyone can see it and fork it. You might want to work in a private repo instead, and that would mean that you would have to give people access to the repo. Get the basics right by reading up on terminology here: https://help.github.com/
We also recommend that you read the Microsoft Docs Contributor Guide because it has a lot of tips and tricks about writing in MarkDown.

Write MarkDown

MarkDown is a text language that is very well suited to write content that will be published to a website. All over the world, people  write content in a variant called Markdig-compliant MarkDown , and so do we.

This is not invented for Dynamics NAV – we are using tooling that our friends in the greater Microsoft have found or developed.  But we love the tooling because we can share it with you, and because our customers end up having a better and more transparent content experience.

Some of you have asked which editors we recommend that you use to write the content in. We don’t really recommend anything because there are so many tools out there. But internally we use Visual Studio Code with a MarkDown extension, while some use Atom.

All of this is Open Source, and there are videos, tutorials, blogs, and Help all over the Internet to help you get started. The team working on Dynamics NAV here at Microsoft have been practicing MarkDown for more than 3 years now, and we’re still learning. But getting started was easy – MarkDown is essentially just text, so you can focus on the content and not worry about the rendering the way that you do in Desktop Publishing, for example. And that means that you don’t have to be a DTP expert or a technical writer in order to contribute.

Generate files for Help Server

For Dynamics NAV 2018, we still make Help Server available for you to deploy as a lightweight website with Help for your customers. We use DocFx to generate HTML files for Help Server and to generate pages for the Docs.microsoft.com site – that’s why you can see .config files and .json files in the nav-content repo.

Next steps

Join us in the world of Dynamics 365 Business Central – for more information, see Migrate Legacy Help to the Dynamics 365 Business Central Format. You can also see the Dynamics 365 Business Central Contributor Guide for more information that also applies to the Dynamics NAV content in GitHub.

The post Find the source files for Dynamics NAV Help in GitHub appeared first on Microsoft Dynamics 365 Blog.