Advanced AL Development Tools

Quality isn't something you lay on top of subjects and objects like tinsel on a Christmas tree. Quality must be in the heartwood.

– Robert Pirsig, paraphrased

Often when you think you're at the end of something, you're at the beginning of something else.

– Fred Rogers

Business Central is extremely flexible and suitable for addressing many types of problems, there are a lot of choices for advanced Business Central topics. We'll try to cover those that will be most helpful in an effort to put together a complete implementation.

First, we will review the overall structure of Business Central as an application software system, aiming for a basic understanding of the process flow of the system, along with some of the utility functions built into the standard product. Before designing modifications for Business Central...

Business Central process flow

Primary data, such as sales orders, purchase orders, production orders, and financial transactions, flow through the Business Central system, as follows:

• Initial setup: This is where the essential master data, reference data, and control and setup data is entered. Most of this preparation is done when the system (or a new application) is prepared for production use.
• Transaction entry: Transactions are entered into documents and then transferred as part of a posting sequence into a Journal table, or data may be entered directly into a Journal table. Data is preliminarily validated as it is entered, with master and auxiliary data tables being referenced as appropriate. The entry can be via manual keying, an automated transaction generation process, or an import function that brings in transaction data from another system.
• Validate: This step provides for additional data validation processing of a set of one or more transactions, often in batches, prior to...

Initial setup and data preparation

Data must be maintained as new master data becomes available or when various system operating parameters and other elements change. The standard approach for Business Central data entry allows records to be entered that have just enough information to define the primary key fields, but not necessarily enough to support processing. This allows for a great deal of flexibility in the timing and responsibility for entry and completeness of new data. This approach applies to both setup data entry and ongoing production transaction data entry.

For example, a sales person might initialize a new customer entry with a name, address, and phone number, just entering the data to which they have easy access. At this point, there is not enough information recorded to process orders for this new customer. At a later time, someone in the accounting department can set up posting groups, payment terms, and other control data that should not be controlled by the sales...

Transaction entry

Transactions are entered into a Journal table. Data is preliminarily validated as it is entered; master and auxiliary data tables are referenced as appropriate. Data validation is one of more powerful existing feature in Business Central like FlowFields. Validations are based on the evaluation of the individual transaction data, plus the related master records and associated reference tables; for example, lookups being satisfied, application or system setup parameter constraints being met, and so on.

Testing and posting the Journal batch

Any additional validations that are needed to ensure the integrity and completeness of the transaction data prior to being posted are done either in pre-post routines or directly in the posting processes. The actual posting of a Journal batch occurs after the transaction data is completely validated.

Depending on the specific application, when Journal transactions don't pass muster during this final validation stage, either the individual transaction is bypassed while acceptable transactions are posted, or the entire Journal batch is rejected until the identified problem is resolved.

The posting process adds entries to one or more ledgers, and sometimes to a document history table. When a Journal Entry is posted to a ledger, it becomes part of the permanent accounting record. Most data cannot be changed or deleted once it resides in a ledger (an example exception would be the due date on a payable).

Register tables may also be updated during...

Utilizing and maintaining the data

The data in a Business Central system can be accessed by means of pages, queries, and/or reports, providing total flexibility. Whatever tools are available to the developer or the user, and are appropriate, should be used. There are some very good tools in Business Central for data manipulation, extraction, and presentation. Among other things, these include the SIFT/FlowField functionality, the pervasive filtering capability (including the ability to apply filters to subordinate data structures), and the Navigate function. Business Central includes the ability to create page parts for graphing, with a wide variety of predefined chart page parts included as part of the standard distribution. We can also create our own chart parts using tools delivered with the system or available from blogs or MSDN.

The Business Central database design approach could be referred to as a rational normalization. Business Central isn't constrained by a rigid normalized...

Data maintenance

As with any database-oriented application software, the ongoing maintenance of master data, reference data, and setup and control data is required. In Business Central, the maintenance of data uses many of the same data preparation tools that were initially used to set up the system.

Role Center pages

One of the key features of Business Central is the Role Tailored user experience, centered on Role Centers tied to user work roles. The Role Tailored approach provides a single point of entry and access into the system for each user through their assigned Role Center. Each user's Role Center acts as their home page. Each Role Center focuses on the tasks needed to support its users' jobs throughout the day. Primary tasks are front and center, while the ACTIONS ribbon and Search menu provide easy access to other functions, making them only a click or two away.

The standard Business Central distribution from Microsoft contains more than two dozen different Role Center pages, identified for user roles such as Bookkeeper, Sales Manager, Shop Supervisor, Purchasing Agent, and so on (page 9011 is identified as Foundation, rather than as a Role Center, or RC). Some localized Business Central distributions may have additional Role Center pages included. It is critical...

Role Center structure

The following screenshot shows page 9006—Order Processor Role Center:

The components of the Role Center highlighted in the preceding screenshot are as follows:

1. Action ribbon
2. Navigation pane
3. Activity pane
4. Headlines (headline is introduced from Business Central and is not available in previous versions)
5. Cues (in Cue Groups)
6. Page parts
7. System part

We need to understand the construction of a Role Center page so that we are prepared to modify an existing Role Center or create a new one. First, we'll take a look at page 9006 "Order Processor Role Center" in the Page Designer:

The Role Center page layout should look familiar, because it's very similar in structure to the pages we've designed previously. What is specific to a Role Center page? There is a container control of the rolecenter area. This is required for a Role Center page.

Note that the PageType is rolecenter, and there is no SourceTable.

Role Center headlines page

We'll take a quick look at the first part control's properties. The part property is page 1441 "Headline RC Order Processor":

Headline pages are used to show KPI information to the users and they are the first thing the users see when opening Business Central.

There is a special PageType property called HeadLinePart, and the RefreshOnActivate property is used to make sure new information is displayed when the Role Center updates.

More information can be found on Microsoft Docs, at https://docs.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-create-role-center-headline.

Role Center activities page

We'll take a quick look at the next part control's properties. The page property is page 9060 "SO Processor Activities":

In the previous screenshot, you can see the various properties of the part control.

Cue groups and cues

Now, we'll focus on page 9060—SO Processor Activities. Designing that page, we see the following layout. Comparing the controls we see there to those of the Role Center, we can see that this page part is the source of the Activities section of the Role Center page.

In the properties of the SO Processor Activities page, we can see that this is a PageType property of CardPart tied to SourceTable, which is Sales Cue.

There are three cuegroup controls—ForRelease, Sales Orders Released Not Shipped, and Returns. In each cuegroup control, there are the field controls for the individual cues:

An individual cue is displayed as an iconic shortcut to a filtered list through a FlowField, or to a query or other data source through a Normal field. The stack of papers in the cue icon resulting from a filtered value represents an idea of the number of records in that list. The actual number of entries is also displayed next to the icon (see the Sales...

System part

Now that we have covered the components of the Activities portion of the Role Center page, let's take a look at the other components.

Returning to page 9006 in the Page Designer, we can examine the properties of the system part control. This page part property is the one that incorporates a view of the user's notes data into the Role Center. Take a look at the following screenshot:

Looking at this control's properties, we see a PartType of systempart and a link to MyNotes, which displays as My Notifications.

Page parts

Let's look at the second group in page 9006, the group that defines the column appearing in the Role Center page:

As you can see, there are nine page parts and a system part defined.

Page parts not visible

If we look at the display of the Role Center page generated by this layout again, we will see a chart (Trailing Sales Orders), followed by two list parts (My Items and Report InBox). The My Job Queue page part does not appear. This page part is defined by the developer, with the Visible property equal to FALSE:

This causes it not to display unless the Role Center page is customized by the user (or an administrator or a developer) and the part is added to the visible part list.

Page parts for user data

Three of the page parts in Role Center page 9006 provide data that is specific to the individual user. They track My data, information important to the user who is logged in. When we design any one of the pages, we can open the page properties to find out what table the page is tied to. Then, viewing any of those tables in the table designer, we will see that a highly ranked field is User ID. An example is the My Item table, which is shown here:

The User ID allows the data to be filtered to present user-specific information to each user. In some cases, this data can be updated directly in the Role Center page part; for example, in My Customers and My Items. In other cases, such as My Job Queue, the data is updated elsewhere and is only viewed in the Role Center page part. If our users need to track other information in a similar manner, such as My Service Contracts, we can readily plagiarize the approach used in the standard page parts.

Navigation pane and action menus

The last major Role Center page components we'll review are the navigation pane and the action ribbon. Even though there are two major parts of the Role Center page that provide access to action choices, they both are defined in the Action Designer section of the Page Designer.

The display of Action Controls in a Role Center page is dependent on a combination of the definition of the controls in the Action Designer, certain properties of the page, and the configuration/personalization of the page. Many of the default Role Centers provided with the product are configured as examples of possibilities of what can be done. Even if one of the default Role Centers seems to fit our customer's requirements exactly, we should create a copy of that Role Center page as another page object and reconfigure it. This way, we can document how that page was set up and make any necessary tweaks.

We'll start with Role Center page 9006 because it is used as...

Action Designer

The actions for a page are defined and maintained in the action section. Open our new page 50120—WDTU Role Center in the Page Designer, then search for action to view the current set of actions defined for this page.

For our newly created page 50120, cloned from page 9006, the Action Designer contents look like the following screenshot:

Whether they are actually displayed, how they are displayed, and where they are displayed are all controlled by a combination of the following factors:

• The structure of the controls within the action list
• The properties of the individual actions
• The customizations/personalizations that have been applied by a developer, administrator, or user

Each action belongs to an area. In hierarchical order, the area can be Embedding, Sections, Creation, or Processing. The specific area entry of each actions entry determines the area, ribbon, or navigation pane in which the subordinate groups of actions will appear:

If the area...

Creating a WDTU Role Center ribbon

If we were creating a Role Center to be used in a real production environment, we would likely be defining a new activities page, new cues, a new or modified cue table, new FactBoxes, and so on. However, since our primary purpose here is learning, we'll take the shortcut of piggybacking on the existing role center and simply add our WDTU actions to the foundation of that existing Role Center.

There are several steps to be taken to define our WDTU Role Center ribbon using the developer tools. The steps we need to take for our WDTU actions are as follows:

1. Define one or more new ribbon categories for the WDTU actions
2. Create the WDTU action controls in the Action Designer
3. Assign the WDTU action controls to the appropriate ribbon categories
4. Finalize any look and feel items

Let's add the following functions to the WDTU portion of the Action Ribbon:

• Radio Show list page
• Playlist page

To add an action, access the page—Action Designer screen...

XMLports

XML (eXtensible Markup Language) is a structured text format developed to describe data to be shared by dissimilar systems. XML has become a standard for communications between systems. To make handling XML-formatted data simpler and more error resistant, Business Central provides XMLports, a data import/export object. In addition to processing XML-formatted data, XMLports can also handle a wide variety of other text file formats, including CSV files, generic flat files, and so on. XML-formatted data is text based, with each piece of information structured in one of two basic formats: elements or attributes. An element is the overall logical unit of information, while an attribute is a property of an element. They are formatted as follows:

• <Tag>elementvalue</Tag> (an element format)
• <Tag AttribName="attribute datavalue"> (an attribute format))

Elements can be nested, but must not overlap. Element and attribute names are case-sensitive. Names...

XMLport components

Although in theory, XMLports can operate in both an import and an export mode, in practice, individual XMLport objects tend to be dedicated to either import or export. This allows the internal logic to be simpler. XMLports utilize a process of looping through and processing data, similar to that of report objects.

The components of XMLports are as follows:

Let's take a look at the properties first.

XMLport properties

XMLport properties are shown in the following screenshot of the properties of the XMLport object 9170:

Descriptions of the individual properties are as follows:

• Caption: This is the name that is displayed for the XMLport; it defaults to the contents of the Name property.
• CaptionML: The Caption translation for a defined alternative language.
• Direction: This defines whether this XMLport can only Import, Export, or <Both>; the default is <Both>.
• DefaultFieldsValidation: This defines the default value (Yes or No) for the FieldValidate property for individual XMLport data fields. The default for this field is Yes, which will set the default for individual field FieldValidate properties to Yes.
• Encoding (or TextEncoding): This defines the character encoding option to be used: UTF-8 (ASCII compatible), UTF-16 (not ASCII compatible), or ISO-8859-2 (for certain European languages written in Latin characters). UTF-16 is the default. This is inserted...

XMLport triggers

XMLport has a very limited set of triggers, which are as follows:

• Documentation() is for documentation comments.
• OnInitXMLport() is executed once, when the XMLport is loaded, before the table views and filters have been set.

• OnPreXMLport() is executed once, after the table views and filters have been set. Those can be reset here.
• OnPostXMLport() is executed once, after all the data is processed, if the XMLport completes normally.

XMLport data lines

An XMLport can contain any number of data lines. The data lines are laid out in a strict hierarchical structure, with the elements and attributes mapping exactly, one for one, in the order of the data fields in the external text file, the XML document.

XMLports should not be run directly from a navigation pane action command (due to conflicts with Business Central UX standards), but can be run either from ribbon actions on a Role Center or other page or by means of an object containing the necessary AL code. When running from another object (as opposed to running from an action menu entry), AL code calls the XMLport to stream data either to or from an appropriately formatted file (XML document or other text format). This calling code is typically written in a codeunit, but can be placed in any object that can contain C/AL code.

The following example code executes an exporting XMLport and saves the resulting file from the Business Central service tier to the client machine...

The XMLport line properties

Different XMLport line properties are active on a line depending on the value of the SourceType property. The first four properties listed are common to all three SourceType values (Text, Table, or Field), and the other properties specific to each are listed after the screenshots, showing all the properties for each SourceType:

• Indentation: This indicates at what subordinate level in the hierarchy of the XMLport this entry exists. Indentation 0 is the primary level, parent to all higher-numbered levels. Indentation 1 is a child of indentation 0, indentation 2 is a child of 1, and so forth. Only one indentation 0 is allowed in an XMLport, so often, we will want to define the level 0 line to be a simple text element line. This allows for the definition of multiple tables at indentation level 1.
• NodeName: This defines the node name that will be used in the XML document to identify the data associated with this position in the XML document. No spaces are allowed...

SourceType as text

A description of the text-specific properties is as follows:

• TextType: This defines the Business Central data type as Text or BigText. Text is the default.
• VariableName: This contains the name of the global variable, which can be referenced by C/AL code.

The Width, NamespacePrefix, MinOccurs, and MaxOccurs properties will be discussed later in this chapter.

SourceType as table

The descriptions of the table-specific properties are as follows:

• SourceTable: This defines the Business Central table being referenced.
• VariableName: This defines the name to be used in C/AL code for the Business Central table. It is the functional equivalent of the definition of a global variable.
• SourceTableView: This enables the developer to define a view by choosing a key and sort order or by applying filters on the table.
• ReqFilterHeading and ReqFilterHeadingML: These fields allow for the definition of the name of the request page filter definition tab that applies to this table.
• CalcFields: This lists the FlowFields in the table that are to be calculated automatically.
• ReqFilterFields: This lists the fields that will initially display on the request page filter definition tab.
• LinkTable: This allows for the linking of a field in a higher-level item to a key field in a lower-level item. If, for example, we were exporting all of the purchase orders for a vendor...

SourceType as field

A description of the field-specific properties is as follows:

• SourceField: This defines the data field being referenced. It can be a field in any defined table.
• FieldValidate: This only applies to Import. If this property is Yes, then whenever the field is imported into the database, the OnValidate() trigger of the field will be executed.
• AutoCalcField: This applies to Export and FlowField data fields only. If this property is set to Yes, the field will be calculated before it is retrieved from the database. Otherwise, a FlowField will export as an empty field.

The details of the Width, NamespacePrefix, MinOccurs, and MaxOccurs properties will be in the next section.

Element or attribute

An element data item can appear many times, but an attribute data item can appear no more than once; the occurrence control properties differ based on the NodeType.

NodeType element data item

The element-specific properties are as follows:

• Width: When the XMLport Format property is Fixed Text, then this field is used to define the fixed width of this element's field.
• MinOccurs: This defines the minimum number of times this data item can occur in the XML document. This property can be Zero or Once (the default).
• MaxOccurs: This defines the maximum number of times this data item can occur in the XML document. This property can be Once or Unbounded. Unbounded (the default) means any number of times.
• NamespacePrefix: When an XMLport has multiple namespaces, this property allows you to select a specific one.

NodeType attribute data item

The attribute-specific property is Occurrence: this is either Required (the default) or Optional, depending on the text file being imported.

XMLport line triggers

There are different XMLport triggers, depending on whether the DataType is Text, Table, or Field.

DataType as text

The triggers for having the DataType as Text are as follows:

• Export::onBeforePassVariable(), for Export only: This trigger is typically used for manipulation of the text variable
• Import::OnAfterAssignVariable(), for Import only: This trigger gives us access to the imported value in a text format

DataType as Table

The triggers for having the DataType as Table are as follows:

• Import::OnAfterInsertRecord(), for Import only: This trigger is typically used when the data is being imported into temporary tables. This is where we would put the C/AL code to build and insert records for the permanent database tables.
• Import::OnBeforeModifyRecord(), for Import only: When AutoSave is Yes, this is used to update the imported data before saving it. 
• Import::OnAfterModifyRecord(), for Import only: When AutoSave is No, this is used to update the data after updating.
• Export::OnPreXMLItem(), for Export only: This trigger is typically used for setting filters and initializing before finding and processing the first database record.
• Export::OnAfterGetRecord(), for Export only: This trigger allows for access to the data after the record is retrieved from the Business Central database. This trigger is typically used to allow manipulation of the table fields being exported.
• Import::OnAfterInitRecord...

DataType as Field

The triggers for having the DataType as Field are as follows:

• Import::OnAfterAssignField(), for Import only: This trigger provides access to the imported data value for evaluation or manipulation before providing output to the database
• Export::OnBeforePassField(), for Export only: This trigger provides access to the data field value just before the data is exported

XMLport Request Pages

XMLports can also have a Request Page to allow the user to enter Option control information and filter the data being processed. The default filter fields that will appear on the Request Page are defined in the properties form for the XMLport line table.

Any desired options that are to be available to the user as a part of the Request Page must be defined in RequestOptionsPageDesigner. This Designer is accessed from the XMLport Designer through View | Request Page. The definition of the contents and layout of the Request Options page are essentially done in the same way as other pages are done. As with any other filter setup screen, the user has complete control of what fields are used for filtering and what filters are applied.

Web services

Web services are an industry standard software interface that allow software applications to interoperate by using standard interface specifications along with standard communications services and protocols. When Business Central publishes some web services, those functions can be accessed and utilized by properly programmed software residing anywhere on the web. This software does not need to be directly compatible with AL, or even .NET; it just needs to obey web services conventions and have security access to the Business Central web services.

Some benefits of Business Central web services are as follows:

• Very simple to publish, that is, to expose a web service to a consuming program outside of Business Central
• Provides managed access to Business Central data while respecting and enforcing the Business Central rules, logic, and design that already exist
• Uses Windows Authentication and respects Business Central data constraints
• Supports SSL (Secure Socket Layer)
• Supports...

Exposing a web service

Three types of Business Central objects can be published as web services: pages, queries, and codeunits. The essential purposes are as follows:

• Pages provide access to the associated primary table. Use card pages for table access, unless there is a specific reason to use another page type.
• Codeunits provide access to the functions contained within each codeunit.
• Queries provide rapid, efficient access to data in a format that is especially compatible with a variety of other Microsoft products, as well as products from other vendors.

An XMLport can be exposed indirectly, as a codeunit parameter. This provides a very structured way of exposing Business Central data through a web service. (See AJ Kauffmann's blog series on XMLports in web services, at http://kauffmann.nl/index.php/2011/01/15/how-to-use-xmlports-in-web-services-1/.) There is an example later in this chapter.)

When a page has no special constraints, either via properties or permissions, there...

Publishing a web service

Publishing a web service is one of the easiest things we will ever do in Business Central. However, as stated earlier, this doesn't mean that we will be able to simply publish existing objects without creating versions specifically tailored for use with web services. However, for the moment, let's just go through the basic publishing process.

The first column allows us to specify whether the object is a page, codeunit, or query. This is followed by the OBJECT ID, and then the SERVICE NAME. Finally, the PUBLISHED flag must be checked:

As you can see, at this point, the web services for that object are published.

Enabling web services

Prior to using web services, we must enable them from the Business Central administration application. In Business Central administration, we can see the checkboxes for enabling them. We can either enable SOAP Services, or OData Services, or both, as shown in the following screenshot:

We have now enabled the services.

Determining what was published

Once an object has been published, we may want to see exactly what is available as a web service. As web services are intended to be accessed from the web, in the address bar of our browser, we will enter the following (all as one string):

http://<Server>:<WebServicePort>/<ServerInstance>/WS/ 
<CompanyName>/services 

Some example URL addresses are as follows:

http://localhost:7047/DynamicsBusiness Central/WS/Services 
http://Arthur:7047/DynamicsBusiness Central/WS/CRONUS International Ltd 
/Services  

The company name is optional and case-sensitive.

When the correct address string is entered, our browser will display a screen similar to the following image. This screenshot is in an XML format of a data structure called WSDL (short for Web Services Description Language):

In this case, we can see that we have two Business Central SOAP services available: Codeunit/Radio_Show_Management and Page/Radio_Show_Card...

XMLport – web services integration example for WDTU

WDTU subscribes to a service that compiles listenership data. This data is provided to subscribers in the form of XML files. The agency that provides the service has agreed to push that XML data directly to a web service exposed by our Business Central system. This approach will allow WDTU to have access to the latest listenership data as soon as it is released by the agency.

WDTU must provide access to the XMLport that fits the incoming XML file format. The handshaking response expected by the agency computer from our web service is a fixed XML file with one element (Station ID) and an attribute of the said element (Frequency).

The first step is to build our XMLport. We do this by using the txmlport snippet from a new AL file in Visual Studio Code. Define the new XMLport lines, as shown in the following screenshot:

Set the Format/Evaluate property to XML Format/Evaluate. This allows Visual Studio to automatically understand...

Summary

In this chapter, we reviewed some of the more advanced Business Central tools and techniques. By now, you should have a strong admiration for the power and flexibility of Business Central. Many of these subject areas will require more study and hands-on practice. We spent a lot of time on Role Center construction because that is the heart of the Role Tailored Experience. Much of what you learned about Role Center design and construction can be applied across the board, in role tailoring other components. We went over XMLports and web services, and then showed how the two capabilities can be combined to provide a simple but powerful method of interfacing with external systems. By now, you should almost be ready to begin your own development project. In the next chapter, we will cover the debugger, extensibility (adding non-AL controls to pages), and some additional topics.

Questions

1. Users cannot delete or modify database data through web services. True or false?
2. What source do the action items for the Departments button come from? Choose one of the following options:
   • Action Menu entries
   • Cue Group definitions
   • MenuSuite objects
   • Navigation Pane objects
3. Software external to Business Central that accesses Business Central web services must be .NET compatible. True or false?
4. Action Ribbons can be modified in which of the following ways? Choose three of the following options:
   • AL changes in the Action Designer
   • Dynamic AL code configuration
   • Implementer/administrator configuration
   • User personalization
   • Application of a profile template

5. XMLports cannot contain AL code: all data manipulation must occur outside of the XMLport object. True or false?
6. The default PromotedActionCategoriesML includes which of the following? Choose two:
   • Page
   • Report
   • Standard
   • New
7. Web services are an industry-standard interface defined by the World Wide Web Consortium. True...