Scenario

Creating a web part that fetch and display customers data from Business Central on selecting a Company in the dropdown list. In this scenario, the web part needs data from Customers and Companies entities from Business Central using APIs.

Create a web part project

Follow the steps in Build your first SharePoint client-side web part page to create a new web part project. Name the web part as Customers instead of HelloWorld. Otherwise, the complete Customers web part project's source code can be downloaded from GitHub.

API permissions

To consume Business Central APIs, it should be authenticated with Azure AD OAuth 2.0 authentication. SharePoint can acquire permissions for the web part from Azure AD, OAuth 2.0 for the resources configured in package-solution.json / solution / webApiPermissionRequests.

package-solution.json

The Following package-solution.json file contains the required permissions to access Business Central APIs.

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "customers-webpart",
    "id": "ff91b46e-3292-4100-9b77-c38d91fc6ed2",
    "version": "1.0.0.14",
    "includeClientSideAssets": true,
    "skipFeatureDeployment": false,
    "isDomainIsolated": false,
    "developer": {
      "name": "",
      "websiteUrl": "",
      "privacyUrl": "",
      "termsOfUseUrl": "",
      "mpnId": "Undefined-1.13.1"
    },
    "webApiPermissionRequests": [
      {
        "resource": "Dynamics 365 Business Central",
        "scope": "Financials.ReadWrite.All"
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/customers-webpart.sppkg"
  }
}

Services to consume Business Central APIs

Web part context has factory methods (aadHttpClientFactory) that can create HTTP client (AadHttpClient) for an endpoint. The same HTTP client can be used to consume secured APIs. SharePoint framework will take care of OAuth 2.0, sending access token in HTTP headers etc.

The following two services fetch data from Companies and Customers using AadHttpClient from Business Central.

Companies.service.ts

The following CompaniesService class gets companies data from Business Central API.

import { WebPartContext } from "@microsoft/sp-webpart-base";
import { AadHttpClient, AadHttpClientResponse } from '@microsoft/sp-http';
import { ClientUrl } from "../config/WebAPIs.constants";
import { APIResponse } from "../models/APIResponse.model";
import { Company } from "../models/Company.model";

export default class CompaniesService {
    constructor(private context: WebPartContext, private environment: string) {
        this.environment = environment || "Production";
    }

    public getCompanies(): Promise {
        return new Promise((resolve, reject) => {
            const apiUrl = `${ClientUrl}/v2.0/${this.environment}/api/v2.0/companies`;

            this.context.aadHttpClientFactory
                .getClient(ClientUrl)
                .then((client: AadHttpClient): void => {
                    client
                        .get(apiUrl, AadHttpClient.configurations.v1)
                        .then((response: AadHttpClientResponse) => {
                            if (response.ok) {
                                return response.json()
                                    .then((response: APIResponse): void => {
                                        resolve(response.value);
                                    });
                            } else {
                                response.text().then(text => {
                                    reject(JSON.parse(text).error);
                                });
                            }
                        })
                        .catch(error => {
                            reject(error);
                        });
                }).catch(error => {
                    reject(error);
                });
        });
    }
}

Customers.service.ts

The following CustomerService class gets customers data from Business Central API.

import { WebPartContext } from "@microsoft/sp-webpart-base";
import { AadHttpClient, AadHttpClientResponse } from '@microsoft/sp-http';
import { ClientUrl } from "../config/WebAPIs.constants";
import { Customer } from "../models/Customer.model";
import { APIResponse } from "../models/APIResponse.model";

export default class CustomerService {
  constructor(private context: WebPartContext, private environment: string, private companyId: string) {
    this.environment = environment || "Production";
  }

  public getCustomers(): Promise {
    return new Promise((resolve, reject) => {
      if (!this.companyId) {
        reject(new Error('Company ID should not be blank.'));
        return;
      }

      const apiUrl = `${ClientUrl}/v2.0/${this.environment}/api/v2.0/companies(${this.companyId})/customers`;

      this.context.aadHttpClientFactory
        .getClient(ClientUrl)
        .then((client: AadHttpClient): void => {
          client
            .get(apiUrl, AadHttpClient.configurations.v1)
            .then((response: AadHttpClientResponse) => {
              if (response.ok) {
                response.json()
                  .then((apiResponse: APIResponse) => {
                    resolve(apiResponse.value);
                  });
              } else {
                response.text().then(text => {
                  reject(JSON.parse(text).error);
                });
              }
            })
            .catch(error => {
              reject(error);
            });
        })
        .catch(error => {
          reject(error);
        });
    });
  }
}

React components

The following CompaniesDropdown and CompaniesList React components renders data using the above services. These code samples are using Fluent UI react components.

CompaniesDropdown.tsx

The following CompaniesDropdown class is a React component to render a dropdown using Companies service.

import * as React from 'react';
import { ICompaniesDropdownProps } from './ICompaniesDropdownProps';
import CompaniesService from '../../../../services/Companies.service';
import { Company } from '../../../../models/Company.model';
import { Dropdown } from '@fluentui/react-northstar';

interface ICompaniesDropdownState {
  companies: Company[];
  loaded: boolean;
  hasError: boolean;
  error?: Error;
}

export default class CompaniesDropdown extends React.Component {
  constructor(props: ICompaniesDropdownProps) {
    super(props);
    this.state = { companies: [], loaded: false, hasError: false };
  }

  public componentDidMount() {
    const service = new CompaniesService(this.props.context, this.props.environment);

    service.getCompanies().then(companies => {
      this.setState({ companies: companies, loaded: true });
    }).catch(error => {
      this.setState({ companies: [], loaded: true, hasError: true, error: error });
    });
  }

  public render(): React.ReactElement {
    const items = !this.state.loaded ? [] : this.state.companies.map((item) => {
      return { key: item.id, header: item.name };
    });

    const onChange = (_: any, event: any) => {
      this.props.onChange(event.value.key);
    };

    return (
      
    );
  }
}

CustomerList.tsx

The following CustomerList class is a React component to render a list using Customers service.

import * as React from 'react';
import { Loader, Segment, Text, List, Card, CardHeader, CardBody } from '@fluentui/react-northstar';
import { ICustomerListProps } from './ICustomerListProps';
import { Customer } from '../../../../models/Customer.model';
import CustomerService from '../../../../services/Customers.service';

interface ICustomerListState {
  customers: Customer[];
  loaded: boolean;
  hasError: boolean;
  error?: Error;
}

export default class CustomerList extends React.Component {
  constructor(props: ICustomerListProps) {
    super(props);
    this.state = { customers: [], loaded: false, hasError: false };
  }

  public componentDidMount() {
    this.getCustomers();
  }

  public componentDidUpdate(prevProps: ICustomerListProps) {
    if (prevProps.companyId != this.props.companyId) {
      this.getCustomers();
    }
  }

  public render(): React.ReactElement {
    return (
      
      {this.renderBody()}
    );
  }

  public renderBody() {
    if (!this.props.companyId) {
      return ();
    }

    if (!this.state.loaded) {
      return ();
    }

    if (this.state.hasError)
      return (
        
          
        );

    const listItems = this.state.customers.map(customer => {
      return {
        key: customer.id,
        header: customer.displayName,
        content: `${customer.addressLine1} ${customer.addressLine2} ${customer.city} ${customer.postalCode}`
      };
    });

    return ();
  }

  private getCustomers() {
    const { context, environment, companyId } = this.props;

    if (!companyId) {
      this.setState({ customers: [], loaded: false, hasError: false, error: null });
    }

    const service = new CustomerService(context, environment, companyId);
    service.getCustomers()
      .then(customers => {
        this.setState({ customers: customers, loaded: true, hasError: false, error: null });
      })
      .catch(error => {
        this.setState({ customers: [], loaded: true, hasError: true, error: error });
      });
  }
}

Customers.tsx

The following Customers class is a React component to render CompaniesDropdown and CustomerList components.

import * as React from 'react';
import { Provider, teamsTheme } from '@fluentui/react-northstar';
import CompaniesDropdown from './companies-dropdown/CompaniesDropdown';
import CustomerList from './customer-list/CustomerList';
import { ICustomersProps } from './ICustomersProps';

interface ICustomersState {
  companyId: string;
}

export default class Customers extends React.Component {
  constructor(props: ICustomersProps) {
    super(props);
    this.state = { companyId: null };
  }

  private onChange(value: string) {
    this.setState({ companyId: value });
  }

  public render(): React.ReactElement {
    return (
      
        
        

        
      
    );
  }
}

CustomersWebPart.ts

The following CustomersWebPart class is a SharePoint web part that renders Customers React component.

import * as React from 'react';
import * as ReactDom from 'react-dom';
import { Version } from '@microsoft/sp-core-library';
import {
  IPropertyPaneConfiguration,
  PropertyPaneTextField
} from '@microsoft/sp-property-pane';
import { BaseClientSideWebPart } from '@microsoft/sp-webpart-base';
import * as strings from 'CustomersWebPartStrings';
import Customers from './components/Customers';
import { ICustomersProps } from './components/ICustomersProps';

export interface ICustomersWebPartProps {
  environment: string;
}

export default class CustomersWebPart extends BaseClientSideWebPart {

  public render(): void {
    const element: React.ReactElement = React.createElement(
      Customers,
      { context: this.context, environment: this.properties.environment }
    );

    ReactDom.render(element, this.domElement);
  }

  protected onDispose(): void {
    ReactDom.unmountComponentAtNode(this.domElement);
  }

  protected get dataVersion(): Version {
    return Version.parse('1.0');
  }

  protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
    return {
      pages: [
        {
          header: {
            description: strings.PropertyPaneDescription
          },
          groups: [
            {
              groupName: strings.BasicGroupName,
              groupFields: [
                PropertyPaneTextField('environment', {
                  label: strings.EnvironmentFieldLabel
                })
              ]
            }
          ]
        }
      ]
    };
  }
}

Build & Deploy the Customers web part

Run the following command at the project root folder to build and package the solution:

gulp build && gulp bundle --ship && gulp package-solution --ship

This will generate a solution file in \sharepoint\solution folder with .sppkg extension that can be deployed in SharePoint's App Catalog site.

After deploying the web part solution in App Catalog site, the SharePoint administrator has to Accept API access in the SharePoint admin center.

Web part output

The following is the output of the Customers web part:

Conclusion

The above explanation is good enough to understand the concept of using Business Central APIs in SharePoint. The same approach can be used to consume Dataverse, Dynamics CRM, Graph APIs etc. To access multiple resources, an array of resource and scope should be updated in webApiPermissionRequests in package-soulution.json file.

Happy Coding!!!

Complete source code is available at GitHub.

#MSDyn365 #MSDyn365BC #BusinessCentral #SharePoint #NodeJS #WebAPIs

Postman is a very useful tool for developers to test various types of HTTP requests, including REST APIs. Business Central supports REST APIs in both On-Premises and Online environments. To test Business Central Online APIs, client application must pass through OAuth2 authentication. An advantage with Postman is that it supports OAuth2 authentication, therefore testing Business Central APIs becomes easy.

App registration

Business Central uses Azure Active Directory for authentication. To call Business Central APIs in Postman, an access token should be passed in the HTTP request headers. To get access token, firstly, it is required to register an App in Azure Portal.

The following sections explains how to register an Application in Azure Portal.

Register a new Application

1. Login to Azure Portal with an Azure AD account.

2. Search for App registrations in the search box and select App registrations > New registration.

3. Enter the application name, select the selected supported account type, and click the Register button.

Authentication

1. Select Authentication and click the Add a platform button.

2. Select Web in the Configure platforms panel.

3. Enter https://api.businesscentral.dynamics.com in Redirect URLs and click the Configure button.

API permissions

1. Select API permissions and click the Add a permission button.

2. Select Dynamics 365 Business Central in Request API permissions panel.

3. Select Delegated permissions, select permissions and click the Add permissions button.

Certificates & secrets

1. Select Certificates & secrets and click the New client secret button.

2. Enter Description and click the Add button.

3. Note the client secret Value and secure it. Once the application page is closed, client secret cannot be retrieved.

Inputs required for Postman

The following inputs are required in Postman to configure OAuth Authentication details:

1. Select Overview and note the Application (client) ID and the Directory (tenant) ID.

2) Click the Endpoints button in the Overview page and note the OAuth 2.0 authorization endpoint (v1) and the OAuth 2.0 token endpoint (v1) URLs.

Postman

The following sections explains how to update authentication details in Postman.

1. Open Postman, click the Authorization tab, and select OAuth 2.0 in the Type dropdown.

2. Enter a meaningful name in the Token Name field.

3. Enter https://api.businesscentral.dynamics.com in Callback URL field.

4. Enter the OAuth 2.0 authorization endpoint (v1) and the OAuth 2.0 token endpoint (v1) URLs noted in Auth URL and Access Token URL fields.

5. Enter the noted Application (client) ID in Client ID field.

6. Paste the Value copied in Certificates & secrets in the Client Secret field.

7. Select Advanced Options tab and enter https://api.businesscentral.dynamics.com in the Resource field, and click the Get New Access Token button.

8. Sign in with the AD account in the Sign in to your account window and Consent on behalf of your organization and click the Accept button.

9. Click the Proceed button.

10. Click the Use Token button.

11. Enter https://api.businesscentral.dynamics.com/v2.0/production/api/v2.0/companies in the URL and click the Send button.

The following is the response from the companies API.

The following is the response from the customers API.

Conclusion

Postman supports POST, GET, PATCH, DELETE and many more HTTP methods, so it is possible to test all CRUD (CREATE, READ, UPDATE, and DELETE) operations with Postman. Please refer to https://docs.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/ for standard APIs available in Business Central .

Postman collection for the above examples is available at GitHub.

#MSDyn365 #MSDyn365BC #BusinessCentral #DynamicsNAV #Postman #WebAPIs

App registration

The following sections explains how to register Application in Azure Portal for Node.js console application with API access to D365 Business Central (Online).

Register a new Application

1. Login to Azure Portal with your Azure AD account.

2. Search for App registrations in the search box and select App registrations > New registration.

3. Enter the application name, select the selected supported account type, and click the Register button.

4. Azure AD will assign a unique Client ID and an Object ID. These details can be seen in the Overview page.

Authentication

1. Select Authentication, scroll down to Advanced Settings > Allow public client flows and select Enable the following mobile and desktop flows.

Permissions and Consent

1. Select API Permissions and go to Add a permission

2. Select Dynamics 365 Business Central in the Request API permissions page.

3. Select Delegated permissions, check user_impersonation and Financials.ReadWrite.All permissions, and click the Add permissions button.

4. Click the Grant admin consent for Contoso button to grant admin consent to this application.

5. After providing admin consent in API permissions page, status should be “Granted for Contoso”.

Node.js Application

Following is the typescript code to get access token from Azure Active Directory using OAuth2 authentication and to get the companies data from D365 Business Central (Online) APIs.

bc-connector.ts

BCConnector class is used to get access token using ADAL library. The connect is a function which calls ADAL's acquireToken functions and return a promise of access token.

import * as adal from 'adal-node';

export class BCConnector {
    authorityUrl: string;
    resource: string;
    adalContext: adal.AuthenticationContext;
    tokenResponse?: adal.TokenResponse;

    constructor(tenantId: string, resource: string, private clientId: string, private username: string, private password: string) {
        this.authorityUrl = `https://login.microsoftonline.com/${tenantId}/oauth2/token`;
        this.resource = `https://${resource}/`;

        this.adalContext = new adal.AuthenticationContext(this.authorityUrl);
    }

    connect(): Promise {
        return new Promise((resolve, reject) => {
            const adalCallback: adal.AcquireTokenCallback = (error: Error, response: adal.TokenResponse | adal.ErrorResponse) => {
                if (!error) {
                    console.log('Authentication successful.');
                    this.tokenResponse = response as adal.TokenResponse;
                    resolve(this.tokenResponse);
                }
                else {
                    console.log('Authentication failed.');
                    reject(error);
                }
            }

            console.log('Authenticating ....');
            if (this.tokenResponse && this.tokenResponse.refreshToken) {
                this.adalContext.acquireTokenWithRefreshToken(this.tokenResponse.refreshToken, this.clientId, this.resource, adalCallback);
            } else {
                this.adalContext.acquireTokenWithUsernamePassword(this.resource, this.username, this.password, this.clientId, adalCallback);
            }
        });
    }
}

index.ts

The following code gets the access token using BCConnector class and calls the Business Central companies API using http request to get the companies data.

import { BCConnector } from './bc-connector';
import * as https from 'https';

const tenantId = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx';
const clientId = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx';
const hostName = 'api.businesscentral.dynamics.com';
const userName = 'admin@xxxx.onmicrosoft.com';
const password = 'xxxxxxxx';

const dynamics = new BCConnector(tenantId,
    hostName,
    clientId,
    userName,
    password);

dynamics.connect().then(response => {
    console.log(`retrieving data from bc...`);
    var req = https.request({
        hostname: 'api.businesscentral.dynamics.com',
        path: '/v2.0/production/api/v2.0/companies',
        headers: {
            "accept": "application/json",
            "Authorization": `Bearer ${response.accessToken}`
        }
    }, res => {
        res.on('data', d => {
            const responseJson = JSON.parse(d.toString());
            console.log(JSON.stringify(responseJson, null, 2));
        })
    });

    req.on('error', error => {
        console.error(error)
    })

    req.end();
}).catch(error => {
    console.error(error);
});

Output

The following is the output from the Node.js console application.

Authenticating ....                                                                                             
Authentication successful.                                                                                      
retrieving data from bc...                                                                                      
{                                                                                                               
  "@odata.context": "https://api.businesscentral.dynamics.com/v2.0/Production/api/v2.0/$metadata#companies",    
  "value": [                                                                                                    
    {                                                                                                           
      "id": "f53e0828-3d8a-eb11-bb5f-000d3a398a56",                                                             
      "systemVersion": "19.3.34541.34662",                                                                      
      "name": "CRONUS USA, Inc.",                                                                               
      "displayName": "",                                                                                        
      "businessProfileId": "",                                                                                  
      "systemCreatedAt": "2021-03-21T12:01:27.08Z",                                                             
      "systemCreatedBy": "00000000-0000-0000-0000-000000000001",                                                
      "systemModifiedAt": "2021-03-21T12:01:27.08Z",                                                            
      "systemModifiedBy": "00000000-0000-0000-0000-000000000001"                                                
    },                                                                                                          
    {                                                                                                           
      "id": "c2c5eb36-3d8a-eb11-bb5f-000d3a398a56",                                                             
      "systemVersion": "19.3.34541.34662",                                                                      
      "name": "My Company",                                                                                     
      "displayName": "",                                                                                        
      "businessProfileId": "",                                                                                  
      "systemCreatedAt": "2021-03-21T12:01:50.367Z",                                                            
      "systemCreatedBy": "00000000-0000-0000-0000-000000000001",                                                
      "systemModifiedAt": "2021-03-21T12:01:50.367Z",                                                           
      "systemModifiedBy": "00000000-0000-0000-0000-000000000001"                                                
    }                                                                                                           
  ]                                                                                                             
}                                                                                                               

Conclusion

The above code is just an example to read data from Business Central (Online). In this application, Business Central APIs can be used to perform all types of operations such as create, read, update, etc.

Node.js is a very popular platform to build robust applications, and very easy to develop applications using Node.js. Node.js application can be used as a middleware to integrate Business Central with other applications. Power Automate is a good option for integrations, but if there is a complex logic this would be a better approach.

Happy Coding!!!

Complete source code is available at GitHub.

#MSDyn365 #MSDyn365BC #BusinessCentral #DynamicsNAV #NodeJS #WebAPIs

Comparison between Publisher-Subscriber Events and Webhooks

Webhooks' design pattern is very similar to Publisher-Subscriber events in AL, but it is over HTTP. The design pattern (PubSub) for Publisher-Subscriber and Webhooks is same. The below comparison may help you to understand the differences better.

Publisher-Subscriber events

• Publisher-Subscriber events work within Business Central Extensions.
• Subscriber functions are executed synchronously.
• Subscriber function can cause performance issues because it is executed within the transaction.

Webhooks

• Webhooks work across applications. Publisher is Business Central and the subscriber can be any other application.
• Webhooks work asynchronously.
• There will not be any performance impact to Business Central.

Use cases

Extend the Business Central functionality

• Generating Airway bill on Sales Shipment in Warehouse application.
• Sending E-Mail, SMS, WhatsApp notifications to customer on Sales Order release by an external application.

Synchronize the Business Central data

• Synchronize Customer, Vendor masters with CRM application
• Synchronize Inventory masters with Warehouse application.

How to create Webhook

As of now, all APIs in Business Central support Webhooks, with the following exceptions:

1. API page with temporary / system table as source
2. API page with a composite key
3. API type query

Working with Webhooks

Subscriber for Business Central Webhook is always an external application. Typically, its a web application developed in .Net / Node.js, or it can be in any other framework / language.

The following series of code are written in Node.JS, and ExpressJS to illustrate Webhook operations. Business Central on premise is used just to avoid the complexity of registering Client Application in Azure portal, generating OAuth2 Authorization Token, etc.

Setup

The following JavaScript code listens to https port 3000 and assigns some constants which will be used in other functions.

const fs = require("fs");
const httpntlm = require("httpntlm");
const express = require("express");
const https = require("https");

const companyId = "74e35bd0-2590-eb11-bb66-000d3abcddd1";
const baseUrl = "http://localhost:7048/BC180";

// replace with actual values
const defaults = {
  username: "USER-NAME",
  password: "PASSWORD",
  workstation: "",
  domain: "DOMAIN-NAME",
};

const app = express();
const port = 3000;

const key = fs.readFileSync("./ssl/key.pem");
const cert = fs.readFileSync("./ssl/cert.pem");
const server = https.createServer({ key: key, cert: cert }, app);

app.use(express.json());
app.use(
  express.urlencoded({
    extended: true,
  })
);

server.listen(port, () => {
  console.log(`Example app listening at https://localhost:${port}`);
}); 

Register a Webhook Subscription

The following code registers webhook subscription for the Customer entity. If a customer is created, updated or deleted a notification is send to the subscriber.

app.get("/register-webhook", function (req, res) {
  const body = {
    notificationUrl: `https://localhost:${port}/customer-notification`,
    resource: `/api/v2.0/companies(${companyId})/customers`,
    clientState: "state123",
  };

  const options = {
    ...defaults,
    headers: {
      "Content-Type": "application/json",
    },
    url: `${baseUrl}/api/v2.0/subscriptions`,
    body: JSON.stringify(body),
  };

  httpntlm.post(options, function (err, response) {
    if (err) {
      return err;
    }

    res.setHeader("content-type", "application/json");
    res.send(response.body);
  });
});

Receive Notifications

The following code receives notifications from Business Central when a Customer entity is updated. Also, it executes at the time of registering / renewing the subscription to validate "notificationUrl".

app.post("/customer-notification", function (req, res) {
  // response to validation requests
  if (req.query.validationToken) {
    res.send(req.query.validationToken);
    return;
  }

  console.log("Customer entity updates:");
  console.log(req.body);
  res.send("");
});

Note: When creating a subscription and renewing a subscription, the client has to return the "validationToken" in the body with response code 200.

Renew the Webhook Subscription

By default, the Webhook Subscription will be expired after 3 days if it is not renewed. This setting can be changed in "CustomSettings.config" file. The following code renews the Webhook Subscription for the Customer entity.

 
app.post("/renew-subscription", function (req, res) {
  const subscriptionId = req.body.subscriptionId;
  const eTag = req.body.eTag;

  const body = {
    notificationUrl: `https://localhost:${port}/customer-notification`,
    resource: `/api/v2.0/companies(${companyId})/customers`,
    clientState: "state123",
  };

  const options = {
    ...defaults,
    url: `${baseUrl}/api/v2.0/subscriptions('${subscriptionId}')`,
    headers: {
      "Content-Type": "application/json",
      "If-Match": eTag,
    },
    body: JSON.stringify(body),
  };

  httpntlm.patch(options, function (err, response) {
    if (err) {
      return err;
    }

    res.setHeader("content-type", "application/json");
    res.send(response.body);
  });
});

Unsubscribe the Webhook Subscription

It is always better to unsubscribe when the notifications are no longer needed, otherwise the system has to try again and again until it expires. The following code deletes the Webhook Subscription.

app.post("/delete-subscription", function (req, res) {
  const subscriptionId = req.body.subscriptionId;
  const eTag = req.body.eTag;

  const options = {
    ...defaults,
    url: `${baseUrl}/api/v2.0/subscriptions('${subscriptionId}')`,
    headers: {
      "If-Match": eTag,
    },
  };

  httpntlm.delete(options, function (err, response) {
    if (err) {
      return err;
    }

    res.setHeader("content-type", "application/json");
    if (response.statusCode == 204) {
      res.send("subscription deleted");
    } else {
      res.send(response.body);
    }
  });
});

Get Subscriptions

The following code gets the active Webhook Subscriptions in Business Central.

app.get("/get-subscriptions", function (req, res) {
  const options = {
    ...defaults,
    url: `${baseUrl}/api/v2.0/subscriptions`,
  };

  httpntlm.get(options, function (err, response) {
    if (err) {
      return err;
    }

    res.setHeader("content-type", "application/json");
    res.send(response.body);
  });
});

Webhook Limitations

Only create, update and delete events are supported to send notifications to the subscribers. At the present, It is not possible to create a custom notification for an event like sales order approved / rejected, order shipped, delivered etc.

Instead, Firebase can be used to publish custom notifications, but that's for another post.

An anonymous URL is required to subscribe Webhook therefore, Business Central cannot be a subscriber. We always need an external application to get notifications from other applications into Business Central.

Power-Automate can be one of the options to overcome this limitation.

Conclusion

Webhooks are very helpful to send notifications to external applications asynchronously without compromising performance.

This is the area where compromised designs are seen in most of the implementations. Often, Push & Pull / Polling techniques are used to synchronize data with external applications, but both techniques can cause performance issues. Pull / Polling technique brings unnecessary load on the system by requesting data repeatedly at set intervals. Push technique can cause delay in completing the transaction (which causes locking errors).

Push is always better than Pull but in an asynchronous way (using job queues or background sessions). Webhooks does the same thing without any need of writing a single line of code.

Happy Coding!!!

You can find complete source code at GitHub.

#MSDyn365 #MSDyn365BC #BusinessCentral #DynamicsNAV #NodeJS #Webhooks

Why and Where to find Anomalies

Purpose of Anomaly Detector is to identify unknown threats in time-series data. Anomalies can be detected in any time-series data.

The following are the potential data sources in Business Central for anomaly detection:

• Bank Ledger (Payments / Receipts)
• Cash / GL (Payments / Receipts)
• Sales (Invoices / Cr. Memos)
• Purchase (Invoices / Cr. Memos)
• Row Material Consumption (Item Ledger)
• Production Output (Item Ledger)

Any data that has Time (Date / Time / DateTime) and Value (Integer / Decimal) columns is a valid data source for anomaly detection.

How to Setup Cognitive Service

• Login to https://portal.azure.com

• Select Cognitive Services and click the Create button in Cognitive Services page.

• Search for "Anomaly Detector" and click the Create button in "Anomaly Detector" card.

• Update the project details and click the "Review + Create" button.

• After creating your "Anomaly Detector" service, open the service and click the Overview link in the left panel.

You can check Endpoint URL (masked) in the above screen.

• Click the "Keys and Endpoint" link in the left panel or the "Click here to manage keys" link in the previous screen to get the API key.

You can take the API key (KEY 1) and the Endpoint URL from the above screen.

AL Code to detect anomalies using REST APIs

The following code sends date wise bank transactions to anomaly detector service and retrieves anomalies in those transactions.

Constants / Labels : SubscriptionKeyLbl is masked for security reasons. EndpointLbl is the value of "KEY 1" from "Keys and Endpoint" screen. Ideally these values should be kept in a Setup table.

var
        RequestUrlLbl: Label '%1/anomalydetector/v1.0/timeseries/entire/detect', Locked = true, Comment = '%1 = Endpoint';
        EndpointLbl: Label 'https://anomalydetector.cognitiveservices.azure.com', Locked = true;
        SubscriptionKeyLbl: Label 'XXXX95d2XXXX1ebaXXXX4fdbXXXX898', Locked = true;

FindAnomalies method takes Bank Account No., From Date and To Date parameters and returns Anomalies in the data.

procedure FindAnomalies(BankAccountNo: Code[20]; FromDate: Date; ToDate: Date; AnomalyData: Dictionary of [Date, Decimal]): Boolean
var
	TimeSeriesData: Dictionary of [Date, Decimal];
begin
	ToTimeSeriesData(BankAccountNo, FromDate, ToDate, TimeSeriesData);
	exit(CheckAnomaly(TimeSeriesData, AnomalyData));
end;

ToTimeSeriesData method takes data from "Bank Account Ledger Entry" and stores it in the TimeSeriesData variable.

Note: Query object can be used to achieve the same for better performance.

local procedure ToTimeSeriesData(BankAccountNo: Code[20]; FromDate: Date; ToDate: Date; TimeSeriesData: Dictionary of [Date, Decimal])
var
	BankAccountLedgerEntry: Record "Bank Account Ledger Entry";
	PrevValue: Decimal;
begin
	BankAccountLedgerEntry.Reset();
	BankAccountLedgerEntry.SetRange("Bank Account No.", BankAccountNo);
	BankAccountLedgerEntry.SetRange("Posting Date", FromDate, ToDate);
	if BankAccountLedgerEntry.FindSet() then
		repeat
			if TimeSeriesData.Get(BankAccountLedgerEntry."Posting Date", PrevValue) then
				TimeSeriesData.Set(BankAccountLedgerEntry."Posting Date", PrevValue + BankAccountLedgerEntry."Amount (LCY)")
			else
				TimeSeriesData.Add(BankAccountLedgerEntry."Posting Date", BankAccountLedgerEntry."Amount (LCY)");
		until BankAccountLedgerEntry.Next() = 0;
end;

TimeSeriesDataToJson method convert TimeSeriesData from Dictionary to JSON object.

local procedure TimeSeriesDataToJson(TimeSeriesData: Dictionary of [Date, Decimal]): JsonObject
var
	JTimeSeriesData: JsonObject;
	JSeriesItem: JsonObject;
	JSeriesItems: JsonArray;
	PostingDate: Date;
	Value: Decimal;
begin
	foreach PostingDate in TimeSeriesData.Keys do begin
		TimeSeriesData.Get(PostingDate, Value);
		JSeriesItem.Add('timestamp', Format(PostingDate, 0, 9));
		JSeriesItem.Add('value', Format(Value, 0, 9));

		JSeriesItems.Add(JSeriesItem);
	end;

	JTimeSeriesData.Add('series', JSeriesItems);
	JTimeSeriesData.Add('maxAnomalyRatio', 0.25);
	JTimeSeriesData.Add('sensitivity', 95);
	JTimeSeriesData.Add('granularity', 'daily');
	exit(JTimeSeriesData);
end;

CheckAnomaly method takes TimeSeries data and returns anomalies in that data.

local procedure CheckAnomaly(TimeSeriesData: Dictionary of [Date, Decimal]; AnomalyData: Dictionary of [Date, Decimal]): Boolean
var
	JTimeSeriesData: JsonObject;
	JResponse: JsonObject;
begin
	JTimeSeriesData := TimeSeriesDataToJson(TimeSeriesData);
	if not GetAPIResponse(JTimeSeriesData, JResponse) then
		exit;

	exit(AnomalyValuesToDataSet(JResponse, TimeSeriesData, AnomalyData));
end;

GetAPIResponse method sends TimeSeriesData to REST API and returns the JSON response from the API.

local procedure GetAPIResponse(JTimeSeriesData: JsonObject; JResponse: JsonObject): Boolean
var
	HttpClient: HttpClient;
	RequestHeaders: HttpHeaders;
	ContentHeaders: HttpHeaders;
	ReqHttpContent: HttpContent;
	ResHttpResponseMessage: HttpResponseMessage;
	ContentTypeValues: array[1024] of Text;
	JsonText: Text;
	Url: Text;
begin
	RequestHeaders := HttpClient.DefaultRequestHeaders();
	RequestHeaders.Add('Ocp-Apim-Subscription-Key', SubscriptionKeyLbl);

	JTimeSeriesData.WriteTo(JsonText);
	ReqHttpContent.WriteFrom(JsonText);
	ReqHttpContent.GetHeaders(ContentHeaders);
	if ContentHeaders.GetValues('Content-Type', ContentTypeValues) then
		ContentHeaders.Remove('Content-Type');
	ContentHeaders.Add('Content-Type', 'application/json');

	Url := StrSubstNo(RequestUrlLbl, EndpointLbl);
	if not HttpClient.Post(Url, ReqHttpContent, ResHttpResponseMessage) then
		exit;

	if not ResHttpResponseMessage.IsSuccessStatusCode() then
		exit;

	ResHttpResponseMessage.Content.ReadAs(JsonText);
	JResponse.ReadFrom(JsonText);
	exit(true);
end;

AnomalyValuesToDataSet method reads the API response, populates the anomaly data in a Dictionary variable and returns it.

local procedure AnomalyValuesToDataSet(JResponse: JsonObject; TimeSeriesData: Dictionary of [Date, Decimal]; AnomalyData: Dictionary of [Date, Decimal]): Boolean
var
	JAnomalyValues: JsonArray;
	JToken: JsonToken;
	Index: Integer;
	PostingDate: Date;
	Amount: Decimal;
begin
	if not JResponse.Get('isAnomaly', JToken) then
		exit(false);

	JAnomalyValues := JToken.AsArray();
	foreach JToken in JAnomalyValues do begin
		Index += 1;

		if JToken.AsValue().AsBoolean() then begin
			TimeSeriesData.Keys.Get(Index, PostingDate);
			TimeSeriesData.Get(PostingDate, Amount);
			AnomalyData.Add(PostingDate, Amount);
		end;
	end;

	exit(true);
end;

Conclusion

Azure Cognitive Service is the one which provides artificial intelligence to business applications like Business Central. Obviously, it is more convenient to have a system that can detect potential threats automatically, instead of analyzing data manually. Azure Cognitive Service fulfills that need.

Source code can be downloaded from GitHub.

Happy Coding!!!

#MsDyn365 #MsDyn365BC #BusinessCentral #DynamicsNAV #AzureCognitiveService #AzureAnomalyDetector

How to install?

This is an open source AL Project, source code can be downloaded from https://github.com/msnraju/inline-query. This tool is using Object IDs from 50100 to 50149, you may need to renumber the objects, if that Object ID range is already used.

Want to contribute?

Anyone can contribute to this project by submitting Pull Request at https://github.com/msnraju/inline-query. Submitting Ideas and reporting bugs is also a good way of contributing.

Demo

SELECT c1, c2 FROM t

Query aggregated data in columns c1, c2 from a table

SELECT c1, c2 FROM t

Query data in columns c1, c2 from a table

SELECT * FROM t

Query all rows and columns from a table

SELECT c1, c2 FROM t WHERE condition

Query data and filter rows with a condition from a table

SELECT TOP n c1, c2 FROM t WHERE condition

Query top n filter rows, columns c1, c2 with a condition from a table

SELECT TOP n c1, c2 FROM t ORDER BY c3

Query top n rows sorted by column 3, in columns c1, c2 from a table

Not supported in the current version:

GROUP BY, HAVING, DISTINCT, JOIN, UNION

Conclusion

Inline Query is a library with a small compiler written in AL to support SQL like queries in Business Central. Inline Query Analyzer is a page that uses Inline Query library to execute SQL like queries in Business Central. In the Online / SAAS environment we do not have access to the SQL database. Using this tool, SQL like queries can be executed in SAAS environment without any access to the SQL database.

See my previous post for more details on how to use Inline Query in AL Language.

Source code can be downloaded from GitHub. Issues can be reported at https://github.com/msnraju/inline-query/issues.

#MsDyn365 #MsDyn365BC #BusinessCentral #DynamicsNAV #InlineQuery

Query Object vs Inline Query

Inline Query is not a replacement for Query Objects. At present, Inline Query can only support retrieval of a single column from a single table (joins are not supported). Whereas Query Object supports multiple tables and multiple columns.

Why Inline Query?

I (MSN Raju) have created this library just to try something new. Actually, there is no purpose when I started writing this, but now I can give some use cases.

The following are the benefits:

• Dynamic - Inline Queries can compose and run at the runtime.
• No Record Variables - No need to declare record variables, it is just a simple Text Query.
• Readability - SQL is like simple English and it is easy to read. Example: select sum(Amount) from [G/L Entry] where [No.] = 'CASH' and [Document Type] = 'Payment'. Anybody can understand what this line is about.
• No of Lines - To write the same above query in AL, at least 3 lines of code should be written. Whereas, for Inline Query, it is a single line statement.

Limitations / Disadvantages:

• It compiles the Query Text every time before executing. This is not good for performance.
• FlowFields, multiple columns, and ORDER BY are not supported.
• Only SELECT queries are supported.

Query Syntax

SELECT [TOP n] FUNCTION() | [AS ] FROM [.] [ WHERE OPERATOR [ AND OPERATOR ] ]

Company Name

Name of the company from which data is to be retrieved, and this is optional. If there are any spaces or special characters in the company name, then it should be enclosed with brackets.

Table Name

Name of the table from which data is to be retrieved. If there are any spaces or special characters in the table name, then it should be enclosed with brackets.

Field Name

Name of the field in the source table. If there are any spaces or special characters in the field name, then it should be enclosed with brackets.

FUNCTION (Aggregate Function)

The following aggregate functions are supported in Inline Quaries:

• Count - To get a no. of records in the table after applying filters
• Min - To get minimum value of the field in the table after applying filters
• Max - To get maximum value of the field in the table after applying filters
• Avg - To get average value of the field in the table after applying filters
• Sum - To get sum of the field values in the table after applying filters
• First - To get the first value of the field in the table after applying filters
• Last - To get the last value of the field in the table after applying filters

OPERATOR

The following operators are supported in Inline Queries:

• Equal to: =
• Less than: <
• Less than or equal to: <=
• Greater than: >
• Greater than or equal to: >=
• Not equal to: <>
• Like: LIKE

Note: For LIKE - Field Filter expressions are accepted as Filter Value. (Internally uses SetFilter statement)

Filter Value

The following are the possible Filter Values:

• BOOLEAN: true or false can be use as filter value to apply filter on Boolean field.
• NUMBER: Integer and Decimal values are accepted as filter values to apply filter on Number type fields.
• TEXT CONST: Text constant values should always be wrapped with single quotes. Text Constant should be used to apply filter on Text, Code, Date, Time, DateTime, Option, Enum type fields.

Filter Value for LIKE operator should be a Text Constant and Filter Value should be in regional format for Date, Time and DateTime fields.

Inline Query Codeunit

This codeunit contains methods that can execute Inline Queries. It has the following methods:

• AsInteger

Input: Query Text

Returns: Integer vaue

• AsDecimal

Input: Query Text

Returns: Decimal value.

• AsBigInteger

Input: Query Text

Returns: BigInteger value.

• AsDate

Input: Query Text

Returns: Date value

• AsTime

Input: QueryText

Returns: Time value.

• AsDateTime -

Input: Query Text

Returns: DateTime value.

• AsBoolean -

Input: Query Text

Returns: Boolean value.

• AsText

Input: Query Text

Returns: Text value.

• AsCode

Input: Query Text

Returns: Boolean value.

• AsJsonArray

Input: Query Text

Returns: JsonArray

Note: SUM and AVG aggregate functions are not applicable to AsDate, AsTime and AsDateTime methods. Also, FIRST and LAST aggregate functions are the only functions that can be used in AsBoolean, AsText and AsCode methods.

Examples

1) Count of released Sales Orders

Query

SELECT COUNT(1) FROM [Sales Header] WHERE Status = 'Released'

AL Code

procedure GetOrderCount(): Integer
var
	InlineQuery: Codeunit "Inline Query";
	OrderCount: Integer;
	QueryTxt: Label 'SELECT COUNT(1) FROM [Sales Header] WHERE Status = ''Released''', Locked = true;
begin
	OrderCount := InlineQuery.AsInteger(QueryTxt);
	exit(OrderCount);
end;

2) Sales Order's total "Amount including VAT" for a particular order.

Query

SELECT SUM([Amount Including VAT]) FROM [Sales Line] WHERE [Document Type] = 'Order' AND [Document No.]='ORD001'

AL Code

local procedure GetOrderAmount(): Decimal
var
	InlineQuery: Codeunit "Inline Query";
	OrderAmount: Integer;
	QueryTxt: Label 'SELECT SUM([Amount Including VAT]) FROM [Sales Line] WHERE [Document Type] = ''Order'' AND [Document No.] = ''ORD001''', Locked = true;
begin
	OrderAmount := InlineQuery.AsDecimal(QueryTxt);
	exit(OrderAmount);
end;

3) Average Order value per Sales Line:

Query

SELECT AVG([Amount Including VAT]) FROM [Sales Line] WHERE [Document Type] LIKE 'Order|Invoice'

AL Code

local procedure GetAverageValue(): Decimal
var
	InlineQuery: Codeunit "Inline Query";
	OrderAmount: Integer;
	QueryTxt: Label 'SELECT AVG([Amount Including VAT]) FROM [Sales Line] WHERE [Document Type] LIKE ''Order|Invoice''', Locked = true;
begin
	OrderAmount := InlineQuery.AsDecimal(QueryTxt);
	exit(OrderAmount);
end;

Conclusion

This is an example on how AL Language can be extended. Though I have written tests for this library with 90%+ code coverage, but still It has to go through tough testing for production use. And most importantly compiled queries should be cached for better performance. I will implement the same in the next version.

You can find source code at GitHub.

Happy Coding!!!

#MsDyn365 #MsDyn365BC #BusinessCentral #DynamicsNAV #InlineQuery

]]>https://www.msnjournals.com/post/facade-pattern-in-business-central-al-language5f9e3ddd28ca5c001779f48fSun, 01 Nov 2020 15:18:24 GMTMSN RajuFacade Pattern is a Design Pattern to hide complexity of the multiple sub systems by providing a simple interface to the client. This pattern involves a single codeunit which provides simple methods required by the client and delegates call to methods of existing internal codeunits.

Class Diagram

Facade pattern class diagram:

• Subsystem: Each class / codeunit in Subsystems has some functionality that will be accessed by client using Facade.
• Facade: This will be the interface for client to access complex subsystem.
• Client: Client will access the subsystems using Facade

Facade: Sample Scenario

Let's take a simple scenario. Create a facade codeunit which will wrap the functionality to search an item by name, and to search a resource by name in two different codeunits (internal / subsystem).

Subsystem (ItemSearchImpl.Codeunit.al)

This is an internal codeunit. Methods in this codeunit can be accessed only within the current project / module. Internal access will ensure that it is not exposed to the Client.

codeunit 50130 "Item Search Impl"
{
    Access = Internal;

    procedure SearchItems(SearchText: Text[100]; Items: List of [Text[100]])
    var
        Item: Record Item;
    begin
        Item.SetFilter(Description, '@*' + SearchText + '*');
        if Item.FindSet() then
            repeat
                Items.Add(Item.Description);
            until Item.Next() = 0;
    end;
}

Subsystem (ResourceSearchImpl.Codeunit.al)

codeunit 50131 "Resource Search Impl"
{
    Access = Internal;

    procedure SearchResource(SearchText: Text[100]; Resources: List of [Text[100]])
    var
        Resource: Record Resource;
    begin
        Resource.SetFilter(Name, '@*' + SearchText + '*');
        if Resource.FindSet() then
            repeat
                Resources.Add(Resource.Name);
            until Resource.Next() = 0;
    end;
}

Facade codeunit (ItemResourceSearch.Codeunit.al)

This is a Facade codeunit which provides access to the functionalities in "Item Search Impl" and "Resource Search Impl" codeunits to the Client.

codeunit 50132 "Item / Resource Search"
{
    Access = Public;
    
    procedure SearchItems(SearchText: Text[100]; Items: List of [Text[100]])
    var
        ItemSearchImpl: Codeunit "Item Search Impl";
    begin
        ItemSearchImpl.SearchItems(SearchText, Items);
    end;

    procedure SearchResource(SearchText: Text[100]; Resources: List of [Text[100]])
    var
        ResourceSearchImpl: Codeunit "Resource Search Impl";
    begin
        ResourceSearchImpl.SearchResource(SearchText, Resources);
    end;
}

Module Architecture

Business Central Module Architecture has some special requirements. See Facade codeunit rules.

Conclusion

Using this Design Pattern, we can simplify the APIs of Business Central extension / module / project. The Facade codeunit should not be modified and should only be extended.

Happy Coding!!!

Source Code can be downloaded from GitHub

#MSDyn365 #MSDyn365BC #BusinessCentral #DynamicsNAV #DesignPatterns

]]>https://www.msnjournals.com/post/basics-of-json-data-types-in-business-central5f9a7eeaf796df0017d3caffFri, 30 Oct 2020 08:12:26 GMTMSN RajuThis post is about understanding the basics of JSON and how to handle JSON data in Business Central AL Language using JSON data types. JSON data types are introduced in AL Language with Business Central / Microsoft Dynamics NAV 2018. JSON stands for JavaScript Object Notation. The JSON format is a lightweight data interchange format originally specified by Douglas Crockford.

Why JSON?

JSON is text only, easy to read, easy to understand and lightweight format to transfer the data between applications or from the client to the server (Web APIs / Web Services). JSON files are also used to maintain configuration data for example AL project's app.json, vscode's launch.json, settings.json are the JSON configuration files.

JSON Data types

Following are the data types supported in JSON Objects. An Object or an Array can be root of the JSON file / document.

• JsonObject
• JsonArray
• String
• Number
• Boolean
• Null

Primitive data types supported in JSON format are String (Text, Code), Number (Integer, Decimal), and Boolean data types only. Because JavaScript supports String, Number and Boolean data types only, all other types are Object types in JavaScript. To support other complex types, they are serialized into text.

Example: the following is a Date type property, but it is formatted as String. But the value can be retrieved as Date data type by using JsonValue.AsDate() method.

  "orderDate": "2022-01-21"

JsonObject

JSON objects are always enclosed with curly braces, and it can contain one or more properties separated by comma.

Property / Attribute / Member

JsonObject can only contain properties, JSONProperty has key value pair syntax. Key values are separated by colon symbol (:). The property key should be a string enclosed with double quotes ("), and the property value can be of any data type supported by JSON.

In the below example "name" is the key, and "Business Central" is the value.

"name": "Business Central"

JsonObject with single property

{
	"name":  "Business Central"
}

JsonObject with multiple properties

{
	"name":  "Business Central",
	"version": 16.1,
	"company": "Microsoft",
	"isOnPrem": false
}

JsonArray

Array is a set of values where the value can be of any data type.

In the below example, "numbers" property value is a string array, "odds" property value is number array, and "customers" property value is a array of objects.

{
	"numbers":  ["One", "Two", "Three"],
	"odds": [1, 3, 5, 7],
	"customers": [
		{ "name": "Nike" },
		{ "name": "Adidas" },
		{ "name": "Puma" },
	]
}

String, Number, Boolean

String values should be enclosed with double quotes. In the below example "Business Central" is a string type value.

"name":  "Business Central"

Number can be an integer value or a decimal value. In the below example 43 and 5.8 are the number type values.

"age":  43,
"height": 5.8

A Boolean value should be either true or false. In the below example false is the Boolean type value.

"isOnPrem": false

JsonValue

JsonValue variable is a joker type variable, it can contain value of any primitive data type like Text, Code, Integer, Decimal, Date, Date Time Date Formula etc.

JsonToken

JsonToken variable is a joker type variable, it can contain JsonObject, JsonArray, or JsonValue variable. It is like Variant data type for JSON variables.

Null

Null values are used when there is no value. Null means nothing or unknown, null doesn’t mean false or zero or empty. In the below the example "modifiedOn" is null.

"modifiedOn": null

Useful Facts

• In AL by default JsonObject, JsonArray variables are auto initialized. To assign a new instance to the same variable, "Clear" method should be used.
• In AL by default JsonValue, JsonToken variables are initialized to null.
• All JSON variables are reference types (pointer). This means even method parameter is not defined as a reference type (var), but still it is treated as reference type. This also means, if a JSON variable is modified anywhere in the code flow (anywhere in the call stack) the original variable is modified.

Construction of JsonObject

The following code is an example of how to create JSON Object. The JsonObject (JSalesOrder) of a Sales Order is returned after adding multiple properties to it.

local procedure SalesOrderToJson(SalesHeader: Record "Sales Header"): JsonObject
var
	JSalesOrder: JsonObject;
begin
	// Sales Order Properties
	JSalesOrder.Add('orderNo', SalesHeader."No.");
	JSalesOrder.Add('orderDate', SalesHeader."Order Date");
	JSalesOrder.Add('sellToCustomerNo', SalesHeader."Sell-to Customer No.");
	JSalesOrder.Add('amountIncludingVAT', SalesHeader."Amount Including VAT");
	JSalesOrder.Add('isApprovedForPosting', SalesHeader.IsApprovedForPosting());
	JSalesOrder.Add('lines', SalesLinesToJson(SalesHeader));
	exit(JSalesOrder);
end;

Construction of JsonArray

The following code is an example of how to create or add multiple items to a JsonArray. The JsonArray (JSalesLines) of multiple Sales Lines JsonObjects are returned.

local procedure SalesLinesToJson(SalesHeader: Record "Sales Header"): JsonArray
var
	SalesLine: Record "Sales Line";
	JSalesLines: JsonArray;
begin
	SalesLine.SetRange("Document Type", SalesHeader."Document Type");
	SalesLine.SetRange("Document No.", SalesHeader."No.");
	if SalesLine.FindSet then
		repeat
			AddSalesLineToJson(SalesLine, JSalesLines);
		until SalesLine.Next() = 0;

	exit(JSalesLines);
end;

local procedure AddSalesLineToJson(SalesLine: Record "Sales Line"; JSalesLines: JsonArray)
var
	JSalesLine: JsonObject;
begin
	// Sales Line Attributes
	JSalesLine.Add('type', SalesLine.Type.AsInteger());
	JSalesLine.Add('no', SalesLine."No.");
	JSalesLine.Add('quantity', SalesLine.Quantity);
	JSalesLine.Add('unitPrice', SalesLine."Unit Price");
	JSalesLine.Add('amount', SalesLine."Line Amount");

	JSalesLines.Add(JSalesLine);
end;

Sample Output of a Sales Order JSON Object in text format of the above code:

{
  "orderNo": "101009",
  "orderDate": "2022-01-21",
  "sellToCustomerNo": "38128456",
  "amountIncludingVAT": 2887.11,
  "isApprovedForPosting": true,
  "lines": [
    {
      "type": 2,
      "no": "1976-W",
      "quantity": 5.0,
      "unitPrice": 396.562,
      "amount": 1982.81
    },
    {
      "type": 2,
      "no": "1964-W",
      "quantity": 2.0,
      "unitPrice": 452.152,
      "amount": 904.3
    }
  ]
}

Read JsonObject

The following code is an example of how to read properties from a JsonObject. It is reading properties of the Sales Order JsonObject (JSalesOrder).

local procedure ReadSalesOrderJson(JSalesOrder: JsonObject; SalesHeader: Record "Sales Header")
var
	JOrderNoToken: JsonToken;
	JOrderDateToken: JsonToken;
	JSellToCustomerNoToken: JsonToken;
	JLinesToken: JsonToken;
	JLinesArray: JsonArray;
begin
	if JSalesOrder.Get('orderNo', JOrderNoToken) then
		SalesHeader."No." := JOrderNoToken.AsValue().AsCode();

	if JSalesOrder.Get('orderDate', JOrderDateToken) then
		SalesHeader."Order Date" := JOrderDateToken.AsValue().AsDate();

	if JSalesOrder.Get('sellToCustomerNo', JSellToCustomerNoToken) then
		SalesHeader."Sell-to Customer No." := JSellToCustomerNoToken.AsValue().AsCode();

	if JSalesOrder.Get('lines', JLinesToken) then begin
		JLinesArray := JLinesToken.AsArray(); // Array of Objects
		ReadSalesLinesJson(JLinesArray, SalesHeader);
	end;
end;

Read JsonArray

The following code is an example on how to read Items from JsonArray. It reads Sales Lines from JsonArray (JSalesLines).

local procedure ReadSalesLinesJson(JSalesLines: JsonArray; SalesHeader: Record "Sales Header")
var
	SalesLine: Record "Sales Line";
	JSalesLineToken: JsonToken;
	JSalesLine: JsonObject;

	JTypeToken: JsonToken;
	JNoToken: JsonToken;
	JQuantityToken: JsonToken;
begin
	foreach JSalesLineToken in JSalesLines do begin
		JSalesLine := JSalesLineToken.AsObject();
		SalesLine."Document Type" := SalesHeader."Document Type";
		SalesLine."Document No." := SalesHeader."No.";

		if JSalesLine.Get('type', JTypeToken) then
			SalesLine.Type := "Sales Line Type".FromInteger(JTypeToken.AsValue().AsInteger());

		if JSalesLine.Get('no', JNoToken) then
			SalesLine."No." := JNoToken.AsValue().AsCode();

		if JSalesLine.Get('quantity', JQuantityToken) then
			SalesLine.Quantity := JQuantityToken.AsValue().AsDecimal();
	end;
end;

Conclusion

Though it is not a great post, you can find several posts explaining everything about JSON, but I still feel there is a need of this post so that Business Central developers can understand the basics of JSON in their language. I saw many developers using JSON data types without understanding the basics (mostly copy, and paste). In my opinion, even if one has successfully completed an integration project using JSON documents etc. without knowing the fundamentals, it has no worth.

Never late to begin, learn the basics to be a better coder.

Happy Coding!!!

#MSDyn365 #MSDyn365BC #BusinessCentral #DynamicsNAV

]]>https://www.msnjournals.com/post/the-rules-pattern-in-business-central-al-language5f86c49e88c88c00188af8e6Wed, 14 Oct 2020 15:48:11 GMTMSN RajuThe Rules Pattern is a Design Pattern to simplify the complex business logic which is based on multiple if-else statements. Using this Design Pattern each if-else branch in the business logic is segregated into a separate rules and also the processing logic is separated from the rules.

Class Diagram

Demo Scenario

To understand the Rules Design Pattern better, the following scenarios are being used:

• If the Customer's "Customer Price Group" is 'GOLD' and the "Business Posting Group" is 'DOM' then 15% discount will be given, else if the "Business Posting Group" is other than 'DOM' 25% discount will be given.
• If the Customer's "Customer Price Group" is 'SILVER' and the "Business Posting Group" is 'DOM' then 10% discount will be given, else if the "Business Posting Group" is other than 'DOM' 15% discount will be given.

Rule Interface (DiscountRule.Interface.al)

This is the implementation of Rule Interface for Discount Calculation. The method "Process" is going to return the Discount Percent based on conditions defined in the "CanProcess" method. If the "CanProcess" method returns false, it means there is no discount applicable for the given customer.

interface DiscountRule
{
    procedure CanProcess(CustomerNo: Code[20]): Boolean;
    procedure Process(CustomerNo: Code[20]): Decimal;
}

Evaluator (DiscountEvaluator.Codeunit.al)

The following logic calculates maximum possible discount. This evaluates the incoming Rule and updates the discount, if the previous discount is less than the current discount.

codeunit 50106 DiscountEvaluator
{
    procedure Evaluate(DiscountRule: Interface DiscountRule; CustomerNo: Code[20]; var Discount: Decimal)
    var
        NewDiscount: Decimal;
    begin
        if not DiscountRule.CanProcess(CustomerNo) then
            exit;

        NewDiscount := DiscountRule.Process(CustomerNo);
        if NewDiscount > Discount then
            Discount := NewDiscount;
    end;
}

Rules

End number of Discount Rules can be implemented, in this example two discount rules are being used. First Rule is for Gold Customers, and the second one for the Silver Customers.

Rule One (GoldCustomerDiscountRule.Codeunit.al)

codeunit 50110 GoldCustomerDiscountRule implements DiscountRule
{
    procedure CanProcess(CustomerNo: Code[20]): Boolean;
    var
        Customer: Record Customer;
    begin
        Customer.Get(CustomerNo);
        if Customer."Customer Price Group" = 'GOLD' then
            exit(true);
    end;

    procedure Process(CustomerNo: Code[20]): Decimal;
    var
        Customer: Record Customer;
    begin
        Customer.Get(CustomerNo);
        case Customer."Gen. Bus. Posting Group" of
            'DOM':
                exit(0.15);
            else
                exit(0.25);
        end;
    end;
}

Rule Two (SilverCustomerDiscountRule.Codeunit.al)

codeunit 50111 SilverCustomerDiscountRule implements DiscountRule
{
    procedure CanProcess(CustomerNo: Code[20]): Boolean;
    var
        Customer: Record Customer;
    begin
        Customer.Get(CustomerNo);
        if Customer."Customer Price Group" = 'SILVER' then
            exit(true);
    end;

    procedure Process(CustomerNo: Code[20]): Decimal;
    var
        Customer: Record Customer;
    begin
        Customer.Get(CustomerNo);
        case Customer."Gen. Bus. Posting Group" of
            'DOM':
                exit(0.1);
            else
                exit(0.15);
        end;
    end;
}

Rule Engine / Processor (DiscountCalculator.Codeunit.al)

This is the main codeunit to calculate the Discount. This follows Open Closed Principle which means it is closed for modification and open for extension.

To modify the discount logic, there is no need to change anything in this codeunit. To modify any condition or the logic in the Discount Rule, the appropriate Discount Rule codeunit has to be modified. To add a new Discount Rule, a new codeunit can be created that implements the Rule Interface and it has to be attached to the Processor (in OnExecute subscriber).

codeunit 50105 DiscountCalculator
{
    procedure Execute(CustomerNo: Code[20]): Decimal
    var
        DiscountEvaluator: Codeunit DiscountEvaluator;
        Discount: Decimal;
    begin
        OnExecute(DiscountEvaluator, CustomerNo, Discount);
        exit(Discount);
    end;

    [BusinessEvent(false)]
    local procedure OnExecute(DiscountEvaluator: Codeunit DiscountEvaluator; CustomerNo: Code[20]; var Discount: Decimal)
    begin
    end;
}

Rules Collection (DiscountRuleSubscriber.Codeunit.al)

This codeunit will attach the available Discount Rules to the Processor (DiscountCalculator).

codeunit 50112 DiscountRuleSubscriber
{
    [EventSubscriber(ObjectType::Codeunit, Codeunit::DiscountCalculator, 'OnExecute', '', false, false)]
    local procedure OnExecute(DiscountEvaluator: Codeunit DiscountEvaluator; CustomerNo: Code[20]; var Discount: Decimal)
    var
        GoldCustomerDiscountRule: Codeunit GoldCustomerDiscountRule;
        SilverCustomerDiscountRule: Codeunit SilverCustomerDiscountRule;
    begin
        DiscountEvaluator.Evaluate(GoldCustomerDiscountRule, CustomerNo, Discount);
        DiscountEvaluator.Evaluate(SilverCustomerDiscountRule, CustomerNo, Discount);
    end;
}

Conclusion

Design Patterns represents the best practices used by the experienced developers to solve general problems. In my opinion, the objective and the solution are more important than the implementation itself. Design patterns can be implemented in different ways depending on the Language features and the capability of the developer. And the most important thing is design patterns should not be implemented forcefully when it is not necessary.

The Rules Pattern solves complexity of the business problem by dividing it into multiple classes / codeunits so that the code becomes readable and extendable for future enhancements.

Happy Coding!!!

Source Code can be downloaded from GitHub

Credits to Steve Smith who is the originator of this design pattern.

#MSDyn365 #MSDyn365BC #BusinessCentral #DynamicsNAV #DesignPatterns

]]>https://www.msnjournals.com/post/generic-validator-method-pattern5f8185f8f5ae940017c6fa35Sun, 11 Oct 2020 07:49:03 GMTMSN RajuGeneric Validator Method Pattern is a design pattern which is an extension of Generic Method Pattern. Purpose of this design pattern is to validate one or more entities in a specific context. This is a very commonly used pattern in other languages, just that it is adjusted to Generic Method Pattern.

Generic Method Pattern

It has a public method and two business events which can be subscribed to change or extend the behaviour of the method.

Public Method may contain the following sequence of calls:

1. UI Confirmation (Optional)
2. OnBefore Business Event
3. Execute Logic
4. OnAfter Business Event
5. UI Acknowledgement (Optional)

Generic Method Pattern better explained in "Design patterns for developing repeatable IP for Dynamics 365 Business Central"

Generic Validator Method Pattern

It has two public methods and two business events which can be subscribed to change or extend the behaviour of the method.

This pattern contains HasErrors and Validate public functions.

HasErrors Method

This method will check validation errors in the entity and stores errors in Errors parameter and returns true if there are any validation errors.

This method should contain the following sequence of calls:

1. OnBefore Business Event
2. Execute Logic
3. OnAfter Business Event

Validate Method

This method will throw a multi line error message with all validation errors found in HasErrors method.

Sample Code

codeunit 50101 CreateSalesOrderValidator
{
    procedure Validate(Customer: Record Customer)
    var
        Errors: List of [Text];
    begin
        if HasErrors(Customer, Errors) then
            Error(ErrorsToText(Errors));
    end;

    procedure HasErrors(Customer: Record Customer; Errors: List of [Text]): Boolean
    var
        Handled: Boolean;
    begin
        OnBeforeCreateSalesOrderValidator(Customer, Handled);
        DoCreateSalesOrder(Customer, Errors, Handled);
        OnAfterCreateSalesOrderValidator(Customer);

        if Errors.Count() > 0 then
            exit(true);
    end;

    local procedure ErrorsToText(Errors: List of [Text]): Text
    var
        ErrText: Text;
        TxtBuffer: TextBuilder;
    begin
        foreach ErrText in Errors do
            TxtBuffer.AppendLine(ErrText);

        exit(TxtBuffer.ToText());
    end;

    local procedure DoCreateSalesOrder(Customer: Record Customer; Errors: List of [Text]; Handled: Boolean)
    begin
        if Handled then
            exit;

        ValidateGenBusinessPostingGroup(Customer, Errors);
        ValidateVATBusPostingGroup(Customer, Errors);
        ValidateVATRegistrationNo(Customer, Errors);
    end;

    local procedure ValidateGenBusinessPostingGroup(Customer: Record Customer; Errors: List of [Text])
    var
        GenBusPostingGroupErr: Label 'Gen. Bus. Posting Group should not be empty.';
    begin
        if Customer."Gen. Bus. Posting Group" = '' then
            Errors.Add(GenBusPostingGroupErr);
    end;

    local procedure ValidateVATBusPostingGroup(Customer: Record Customer; Errors: List of [Text])
    var
        GenBusPostingGroupErr: Label 'VAT Bus. Posting Group should not be empty.';
    begin
        if Customer."VAT Bus. Posting Group" = '' then
            Errors.Add(GenBusPostingGroupErr);
    end;

    local procedure ValidateVATRegistrationNo(Customer: Record Customer; Errors: List of [Text])
    var
        GenBusPostingGroupErr: Label 'Customer should have a valid VAT Registration No.';
    begin
        if Customer."VAT Registration No." = '' then
            Errors.Add(GenBusPostingGroupErr);
    end;

    [BusinessEvent(false)]
    local procedure OnBeforeCreateSalesOrderValidator(Customer: Record Customer; var Handled: Boolean)
    begin
    end;

    [BusinessEvent(false)]
    local procedure OnAfterCreateSalesOrderValidator(Customer: Record Customer)
    begin
    end;
}

Use Cases

This pattern can be used in the following senarios:

• Postings, Actions

Validate Transactional Entities before posting or before performaning an action.

• APIs, Web Services

Validating Entities before importing or accepting data via APIs or Web Services.

#MSDyn365 #MSDyn365BC #BusinessCentral #DynamicsNAV #DesignPatterns

]]>https://www.msnjournals.com/post/how-to-use-reactjs-components-in-control-add-ins5f51bd808ec7190017e6ebc0Fri, 04 Sep 2020 10:28:32 GMTMSN RajuControl Add-in is an Object type in Business Central to develop User Controls using JavaScript, and CSS. Though it is a very good option to enhance UI / UX in Business Central, we often have to struggle to build HTML markup in JavaScript, because we have to use string concatenate functions, or complex DOM methods build HTML elements. ReactJS library can give us the flexibility to write HTML markup inside JavaScript.

About ReactJS

ReactJS is a JavaScript library developed by the Facebook team to develop single page applications. ReactJS uses a new file type called JSX (JavaScript and Xml) which allows to write HTML markup in JavaScript (this is the exact requirement). Using npm scripts ReactJS application can be transpiled into JavaScript and CSS files.

A Simple React Component:

class HelloMessage extends React.Component {
  render() {
    return (
      

        Hello {this.props.name}
      
    );
  }
}

ReactDOM.render(
  ,
  document.getElementById('hello-example')
);

ReactJS Application

A new ReactJS application can be created using the following npx command. npx is a node package runner. You must install node.js before executing this command.

npx create-react-app my-app

The following command build the ReactJS application and creates a build folder with transpiled JavaScript, and CSS files.

npm run build

build folder:

  330.3 KB  build\static\js\3.2860d5eb.chunk.js
  19.96 KB  build\static\js\0.3e8005e8.chunk.js
  13.43 KB  build\static\js\4.c188f31c.chunk.js
  11.62 KB  build\static\css\3.fb09108b.chunk.css
  6.76 KB   build\static\js\5.eb238462.chunk.js
  5.16 KB   build\static\js\6.1a36259c.chunk.js
  1.21 KB   build\static\js\runtime-main.386c5c00.js
  856 B     build\static\js\main.da43e367.chunk.js
  584 B     build\static\js\7.3093821e.chunk.js
  214 B     build\static\css\main.b2c4a7d2.chunk.css

Bundle JS, CSS files using Gulp

Gulp is a JavaScript task runner. Using Gulp, multiple JavaScript and CSS files can be bundled into a single JavaScript, and into a single CSS file.

install the following packages:

npm install --save-dev gulp
npm install --save-dev gulp-clean-css
npm install --save-dev gulp-concat

"gulp-clean-css", "gulp-concat" are the gulp plugins to clean CSS files and concatenate files respectively.

gulpfile.js

Create "gulpfile.js" file in React Application's root folder. This takes JavaScript and CSS files from the build folder and bundles them into a single JavaScript and CSS files and saves in Control Add-in folder.

ControlAddInFolder: is the relative path to Control Add-in AL project folder.

var gulp = require('gulp');
var concat = require('gulp-concat');
var cleanCss = require('gulp-clean-css');

const ControlAddInFolder = '../app/src/ContentEditor';
const ControlAddInName = 'content-editor';

gulp.task('pack-js', function () {
    return gulp.src(['build/static/js/*.js'])
        .pipe(concat(`${ControlAddInName}.js`))
        .pipe(gulp.dest(`${ControlAddInFolder}/js`));
});

gulp.task('pack-css', function () {
    return gulp.src(['build/static/css/*.css'])
        .pipe(concat(`${ControlAddInName}.css`))
        .pipe(cleanCss())
        .pipe(gulp.dest(`${ControlAddInFolder}/css`));
});

gulp.task('default', gulp.series('pack-js', 'pack-css'));

Update build script in package.json

Update "package.json" to execute gulp after completing build automatically.

"react-scripts build && gulp" :- will execute gulp (gulpfile.js) after being build.

 "scripts": {
 "start": "react-scripts start",
 "build": "react-scripts build && gulp"
  },

ReactJS Component (ContentEditor.js)

The following React component renders "wix-rich-content-editor" in "controlAddIn" element on receiving "onLoadContent" custom event. And it will dispatch "onContentChange" custom event on content change.

import React from 'react';
import ReactDOM from 'react-dom';
import { EditorState, RichContentEditor } from 'wix-rich-content-editor';
import { createLinkPlugin } from 'wix-rich-content-plugin-link';
import { createCodeBlockPlugin } from 'wix-rich-content-plugin-code-block';
import { createHashtagPlugin } from 'wix-rich-content-plugin-hashtag';
import { createHtmlPlugin } from 'wix-rich-content-plugin-html';
import 'wix-rich-content-editor-common/dist/styles.min.css';
import 'wix-rich-content-editor/dist/styles.min.css';
import 'wix-rich-content-plugin-link/dist/styles.min.css';
import 'wix-rich-content-plugin-code-block/dist/styles.min.css';
import 'wix-rich-content-plugin-hashtag/dist/styles.min.css';
import 'wix-rich-content-plugin-html/dist/styles.min.css';
import './App.css';

import {
  convertFromRaw,
  convertToRaw,
} from 'wix-rich-content-editor-common';

const PLUGINS = [createLinkPlugin, createCodeBlockPlugin, createHashtagPlugin, createHtmlPlugin];
const ON_LOAD_CONTENT_EVENT = 'onLoadContent';
const ON_CONTENT_CHANGE_EVENT = 'onContentChange';

window.addEventListener(ON_LOAD_CONTENT_EVENT, (e) => {
  ReactDOM.render(
    
      
    ,
    document.getElementById('controlAddIn')
  );
})

class ContentEditor extends React.Component {
  constructor(props) {
    super(props);

    this.refsEditor = React.createRef();
    if (this.props.content) {
      const contentState = convertFromRaw(this.props.content);
      this.state = {
        editorState: EditorState.createWithContent(contentState),
      }
    } else {
      this.state = { editorState: EditorState.createEmpty(), };
    }

    this.onLoadContent = this.onLoadContent.bind(this);
    window.addEventListener(ON_LOAD_CONTENT_EVENT, this.onLoadContent)
  }

  onLoadContent(e) {
    if (!e.detail)
      return;

    const contentState = convertFromRaw(e.detail);
    this.setState({
      editorState: EditorState.createWithContent(contentState),
    });
  }

  onChange = editorState => {
    this.setState({
      editorState,
    });

    const rawContent = convertToRaw(editorState.getCurrentContent());
    let event = new CustomEvent(ON_CONTENT_CHANGE_EVENT, { detail: rawContent });
    window.dispatchEvent(event);
  };

  componentDidMount() {
    this.refsEditor.current.focus();
  }

  componentWillUnmount() {
    window.removeEventListener(ON_LOAD_CONTENT_EVENT, this.onLoadContent);
  }

  render() {
    return (
      

        
      
    );
  }
}

export default ContentEditor;

Install the following packages to use "wix-rich-content-editor":

npm install classnames
npm install wix-rich-content-editor
npm install wix-rich-content-plugin-code-block
npm install wix-rich-content-plugin-hashtag
npm install wix-rich-content-plugin-html
npm install wix-rich-content-plugin-link

Custom Events (content-editor-events.js)

Custom events are used to communicate ReactJS component with Control Add-in.

onLoadContent: this event tells React Component that it has to render new content.

onContentChange: this event tells Control Add-in that the content is modified in the React Component.

function onLoadContent(content) {
    const event = new CustomEvent('onLoadContent', { detail: content });
    window.dispatchEvent(event);
}

window.addEventListener('onContentChange', function (e) {
    const content = e.detail;
    Microsoft.Dynamics.NAV.InvokeExtensibilityMethod('OnContentChange', [content])
});

window.LoadContent = function (content) {
    if (JSON.stringify(content) == '{}')
        onLoadContent(null);
    else
        onLoadContent(content);
}

Control Add-in (ContentEditor.ControlAddin.al)

The above "gulpfile.js" creates "content-editor.js", "content-editor.css" files in "app/src/ContentEditor" folder when ReactJS application's build command is executed. These files should be used in Scripts and StyleSheets in Control Add-ins.

controladdin ContentEditor
{
    RequestedHeight = 300;
    VerticalStretch = true;
    VerticalShrink = true;
    HorizontalStretch = true;
    HorizontalShrink = true;
    Scripts =
        './src/ContentEditor/js/content-editor-events.js',
        './src/ContentEditor/js/content-editor.js';
    StyleSheets = './src/ContentEditor/css/content-editor.css';

    event OnContentChange(content: JsonObject)
    procedure LoadContent(content: JsonObject)
}

Customer Card (CustomerCardExt.PageExt.al)

Using "ContentEditor" Control Add-in, the "About" and the "Twitter" group controls are added after the "General" group.

This will allow to write rich text content in the "About" and the "Twitter" groups.

pageextension 50120 CustomerCardExt extends "Customer Card"
{
    layout
    {
        addafter(General)
        {
            group(About)
            {
                Caption = 'About';

                usercontrol("ContentEditor"; ContentEditor)
                {
                    trigger OnContentChange(Content: JsonObject)
                    var
                        ContentText: Text;
                        OStream: OutStream;
                    begin
                        Detail.CreateOutStream(OStream, TextEncoding::UTF8);
                        Content.WriteTo(OStream);
                        Modify();
                    end;
                }
            }
            group(Twitter)
            {
                Caption = 'Twitter';

                usercontrol("Twitter ContentEditor"; ContentEditor)
                {
                    trigger OnContentChange(Content: JsonObject)
                    var
                        ContentText: Text;
                        OStream: OutStream;
                    begin
                        Twitter.CreateOutStream(OStream, TextEncoding::UTF8);
                        Content.WriteTo(OStream);
                        Modify();
                    end;
                }
            }
        }
    }

    trigger OnAfterGetCurrRecord()
    begin
        LoadAbout();
        LoadTwitter();
    end;

    local procedure LoadAbout()
    var
        JObject: JsonObject;
        IStream: InStream;
    begin
        CalcFields(Detail);
        if Detail.HasValue() then begin
            Detail.CreateInStream(IStream, TextEncoding::UTF8);
            JObject.ReadFrom(IStream);
        end;

        CurrPage.ContentEditor.LoadContent(JObject);
    end;

    local procedure LoadTwitter()
    var
        JObject: JsonObject;
        IStream: InStream;
    begin
        CalcFields(Twitter);
        if Twitter.HasValue() then begin
            Twitter.CreateInStream(IStream, TextEncoding::UTF8);
            JObject.ReadFrom(IStream);
        end;

        CurrPage."Twitter ContentEditor".LoadContent(JObject);
    end;
}

Code in Action

The following screenshot shows "About" and "Twitter" tabs with rich text content embeded.

Conclusion

The sample ReactJS Component used in this post is Wix Rich Content. This is one of my favorite React Component for rich text editing. For Control add-ins, you can create your own React Component, or use any existing component. To match the Business Central UI you can use the Fluent UI framework (Business Central also uses this framework internally).

References:

• Absolutely Awesome React Components & Libraries
• Fluent UI

Source Code

You can download the complete source code at GitHub

Happy Coding!!!

#MSDyn365 #MSDyn365BC #BusinessCentral #DynamicsNAV #ReactJS

]]>https://www.msnjournals.com/post/how-to-connect-sharepoint-with-business-central5f45a78db3800500177c58e5Wed, 26 Aug 2020 03:27:29 GMTMSN RajuSharePoint integration with Business Central is one of the most common requirement. SharePoint Document Management System can be used to manage files for Business Central online. Sometimes for various reasons developer needs to handle files in SharePoint from Business Central AL Code programatically. This post explains how to integrate SharePoint with Business Central and handling Document Libraries and files using Microsoft Graph API.

The following topics are covered in this post:

• Retrieve Document Libraries from a SharePoint site.
• Retrieve folders and files from a Document Library.
• Upload and download files to and from a Document Library.
• Delete files and folders from a Document Library.

Prerequisits

Some of the topics are already covered in other posts. To avoid repetition, links are provided to the related posts.

Following are the prequisits:

• An app registration in azure active directory

How to setup app registration in ,Azure Portal is explained in ,How to use Microsoft Graph API in Business Central post.

• Generic OAuth2 Library

Using this library OAuth Access Token can be acquired from Azure AD. How to setup "OAuth 2.0 Application" is explained in ,Generic OAuth2 Library for Business Central post. Source code can be downloaded from GitHub,

API Functions

The following API functions are required to handle SharePoint Document Libraries.

1. Get Access Token
2. Fetch Drives (Document Libraries)
3. Fetch Drive's Items (Folders and Files from a Document Library)
4. Fetch Drive's Child Items (Folders and Files from a Folder in a Document Library)
5. Upload a File
6. Download a File
7. Create a Folder
8. Delete a Drive Item (File or Folder)

Get Access Token

The following code returns Access Token using "Generic OAuth2 Library". "OAuth 2.0 Application" table, "OAuth 2.0 App. Helper" codeunit objects are from "Generic OAuth2 Library".

procedure GetAccessToken(AppCode: Code[20]): Text
var
	OAuth20Application: Record "OAuth 2.0 Application";
	OAuth20AppHelper: Codeunit "OAuth 2.0 App. Helper";
	MessageText: Text;
begin
	OAuth20Application.Get(AppCode);
	if not OAuth20AppHelper.RequestAccessToken(OAuth20Application, MessageText) then
		Error(MessageText);

	exit(OAuth20AppHelper.GetAccessToken(OAuth20Application));
end;

Setup OAuth 2.0 Application

Setup "OAuth 2.0 Application" to acquire Access Token from Azure AD using ,Generic OAuth2 Library.

1) Search for "OAuth 2.0 Applications" in Business Central

2) Create a new "OAuth 2.0 Application" from the list

The above screenshot contains sample configuration to get Access Token from Azure AD using Generic OAuth2 Library.

Fetch Drives (Document Libraries)

The following code retrived Drives (Document Libraries) and saves it in "Online Drive" table.

var
	DrivesUrl: Label 'https://graph.microsoft.com/v1.0/drives', Locked = true;
	
procedure FetchDrives(AccessToken: Text; var Drive: Record "Online Drive"): Boolean
var
	JsonResponse: JsonObject;
	JToken: JsonToken;
begin
	if HttpGet(AccessToken, DrivesUrl, JsonResponse) then begin
		if JsonResponse.Get('value', JToken) then
			ReadDrives(JToken.AsArray(), Drive);

		exit(true);
	end;
end;

Online Drive (table 50115)

table 50115 "Online Drive"
{
    DataClassification = CustomerContent;

    fields
    {
        field(1; id; Text[250])
        {
            DataClassification = CustomerContent;
        }
        field(2; name; Text[250])
        {
            DataClassification = CustomerContent;
        }
        field(3; description; Text[250])
        {
            DataClassification = CustomerContent;
        }
        field(4; driveType; Text[80])
        {
            DataClassification = CustomerContent;
        }
        field(5; createdDateTime; DateTime)
        {
            DataClassification = CustomerContent;
        }
        field(6; lastModifiedDateTime; DateTime)
        {
            DataClassification = CustomerContent;
        }
        field(7; webUrl; Text[250])
        {
            DataClassification = CustomerContent;
        }
    }

    keys
    {
        key(PK; id)
        {
            Clustered = true;
        }
    }
}

HttpGet method

Following is a helper function to get json object response from the given Url using AccessToken.

local procedure HttpGet(AccessToken: Text; Url: Text; var JResponse: JsonObject): Boolean
var
	Client: HttpClient;
	Headers: HttpHeaders;
	RequestMessage: HttpRequestMessage;
	ResponseMessage: HttpResponseMessage;
	RequestContent: HttpContent;
	ResponseText: Text;
	IsSucces: Boolean;
begin
	Headers := Client.DefaultRequestHeaders();
	Headers.Add('Authorization', StrSubstNo('Bearer %1', AccessToken));

	RequestMessage.SetRequestUri(Url);
	RequestMessage.Method := 'GET';

	if Client.Send(RequestMessage, ResponseMessage) then
		if ResponseMessage.IsSuccessStatusCode() then begin
			if ResponseMessage.Content.ReadAs(ResponseText) then
				IsSucces := true;
		end else
			ResponseMessage.Content.ReadAs(ResponseText);

	JResponse.ReadFrom(ResponseText);
	exit(IsSucces);
end;

ReadDrives method

This function reads JsonArray and inserts data into "Online Drive" table.

local procedure ReadDrives(JDrives: JsonArray; var Drive: Record "Online Drive")
var
	JDriveItem: JsonToken;
	JDrive: JsonObject;
	JToken: JsonToken;
begin
	foreach JDriveItem in JDrives do begin
		JDrive := JDriveItem.AsObject();

		Drive.Init();
		if JDrive.Get('id', JToken) then
			Drive.Id := JToken.AsValue().AsText();
		if JDrive.Get('name', JToken) then
			Drive.Name := JToken.AsValue().AsText();
		if JDrive.Get('description', JToken) then
			Drive.description := JToken.AsValue().AsText();
		if JDrive.Get('driveType', JToken) then
			Drive.driveType := JToken.AsValue().AsText();
		if JDrive.Get('createdDateTime', JToken) then
			Drive.createdDateTime := JToken.AsValue().AsDateTime();
		if JDrive.Get('lastModifiedDateTime', JToken) then
			Drive.lastModifiedDateTime := JToken.AsValue().AsDateTime();
		if JDrive.Get('webUrl', JToken) then
			Drive.webUrl := JToken.AsValue().AsText();
		Drive.Insert();
	end;
end;

Fetch Drive's Items

The following code can fetch files and folders from a Drive (Document Library). DriveID is the value of the id property in Drive JsonObject (saved in "Online Drive" table).

var
	DrivesItemsUrl: Label 'https://graph.microsoft.com/v1.0/drives/%1/root/children', Comment = '%1 = Drive ID', Locked = true;
	
procedure FetchDrivesItems(AccessToken: Text; DriveID: Text; var DriveItem: Record "Online Drive Item"): Boolean
var
	JsonResponse: JsonObject;
	JToken: JsonToken;
	IsSucces: Boolean;
begin
	if HttpGet(AccessToken, StrSubstNo(DrivesItemsUrl, DriveID), JsonResponse) then begin
		if JsonResponse.Get('value', JToken) then
			ReadDriveItems(JToken.AsArray(), DriveID, '', DriveItem);

		exit(true);
	end;
end;

Online Drive Item (table 50115)

To store Files and Folder information

table 50116 "Online Drive Item"
{
    DataClassification = CustomerContent;

    fields
    {
        field(1; id; Text[250])
        {
            DataClassification = CustomerContent;
        }
        field(2; driveId; Text[250])
        {
            DataClassification = CustomerContent;
        }
        field(3; parentId; Text[250])
        {
            DataClassification = CustomerContent;
        }
        field(4; name; Text[250])
        {
            DataClassification = CustomerContent;
        }
        field(5; isFile; Boolean)
        {
            DataClassification = CustomerContent;
        }
        field(6; mimeType; Text[80])
        {
            DataClassification = CustomerContent;
        }
        field(7; size; BigInteger)
        {
            DataClassification = CustomerContent;
        }
        field(8; createdDateTime; DateTime)
        {
            DataClassification = CustomerContent;
        }
        field(9; webUrl; Text[250])
        {
            DataClassification = CustomerContent;
        }
    }

    keys
    {
        key(PK; id)
        {
            Clustered = true;
        }
    }
}

ReadDriveItems

Read JDriveItems JsonArray and saves in "Online Drive Item" table.

local procedure ReadDriveItems(
	JDriveItems: JsonArray;
	DriveID: Text;
	ParentID: Text;
	var DriveItem: Record "Online Drive Item")
var
	JToken: JsonToken;
begin
	foreach JToken in JDriveItems do
		ReadDriveItem(JToken.AsObject(), DriveID, ParentID, DriveItem);
end;

local procedure ReadDriveItem(
	JDriveItem: JsonObject;
	DriveID: Text;
	ParentID: Text;
	var DriveItem: Record "Online Drive Item")
var
	JFile: JsonObject;
	JToken: JsonToken;
begin

	DriveItem.Init();
	DriveItem.driveId := DriveID;
	DriveItem.parentId := ParentID;

	if JDriveItem.Get('id', JToken) then
		DriveItem.Id := JToken.AsValue().AsText();
	if JDriveItem.Get('name', JToken) then
		DriveItem.Name := JToken.AsValue().AsText();

	if JDriveItem.Get('size', JToken) then
		DriveItem.size := JToken.AsValue().AsBigInteger();

	if JDriveItem.Get('file', JToken) then begin
		DriveItem.IsFile := true;
		JFile := JToken.AsObject();
		if JFile.Get('mimeType', JToken) then
			DriveItem.mimeType := JToken.AsValue().AsText();
	end;

	if JDriveItem.Get('createdDateTime', JToken) then
		DriveItem.createdDateTime := JToken.AsValue().AsDateTime();
	if JDriveItem.Get('webUrl', JToken) then
		DriveItem.webUrl := JToken.AsValue().AsText();
	DriveItem.Insert();
end;

Fetch Drive's Child Items

Following is the code to read Folders and Files from a Folder in a Document Library. ItemID is the value of the id property in DriveItem JsonObject (saved in "Online Drive Item" table).

var
	DrivesChildItemsUrl: Label 'https://graph.microsoft.com/v1.0/drives/%1/items/%2/children', Comment = '%1 = Drive ID, %2 = Item ID', Locked = true;

procedure FetchDrivesChildItems(
	AccessToken: Text;
	DriveID: Text;
	ItemID: Text;
	var DriveItem: Record "Online Drive Item"): Boolean
var
	JsonResponse: JsonObject;
	JToken: JsonToken;
	IsSucces: Boolean;
begin
	if HttpGet(AccessToken, StrSubstNo(DrivesChildItemsUrl, DriveID, ItemID), JsonResponse) then begin
		if JsonResponse.Get('value', JToken) then
			ReadDriveItems(JToken.AsArray(), DriveID, ItemID, DriveItem);

		exit(true);
	end;
end;

Upload a File

The following code uploads a file into a Document Library and save newly created Drive Item (file) details in "Online Drive Item" table.

ParentID: Folder's Drive Item ID (should be blank for a file to be uploaded to the root drive)

FolderPath: Name of the target folder (ex: "/personal/documents" means file will be saved in documents folder which is a subfolder of personal folder)

FileName: Name of the file with extension (ex: "readme.pdf")

Stream: File Content

var
	UploadUrl: Label 'https://graph.microsoft.com/v1.0/drives/%1/items/root:/%2:/content', Comment = '%1 = Drive ID, %2 = File Name', Locked = true;

procedure UploadFile(
	AccessToken: Text;
	DriveID: Text;
	ParentID: Text;
	FolderPath: Text;
	FileName: Text;
	var Stream: InStream;
	var OnlineDriveItem: Record "Online Drive Item"): Boolean
var
	HttpClient: HttpClient;
	Headers: HttpHeaders;
	RequestMessage: HttpRequestMessage;
	RequestContent: HttpContent;
	ResponseMessage: HttpResponseMessage;
	JsonResponse: JsonObject;
	IsSucces: Boolean;
	ResponseText: Text;
begin
	Headers := HttpClient.DefaultRequestHeaders();
	Headers.Add('Authorization', StrSubstNo('Bearer %1', AccessToken));

	RequestMessage.SetRequestUri(
		StrSubstNo(
			UploadUrl,
			DriveID,
			StrSubstNo('%1/%2', FolderPath, FileName)));
	RequestMessage.Method := 'PUT';

	RequestContent.WriteFrom(Stream);
	RequestMessage.Content := RequestContent;

	if HttpClient.Send(RequestMessage, ResponseMessage) then
		if ResponseMessage.IsSuccessStatusCode() then begin
			if ResponseMessage.Content.ReadAs(ResponseText) then begin
				IsSucces := true;
				if JsonResponse.ReadFrom(ResponseText) then
					ReadDriveItem(JsonResponse, DriveID, ParentID, OnlineDriveItem);
			end;
		end else
			if ResponseMessage.Content.ReadAs(ResponseText) then
				JsonResponse.ReadFrom(ResponseText);

	exit(IsSucces);
end;

Download a File

The following code downloads a file from a Document Library. ItemID is the value of the id property in DriveItem JsonObject (saved in "Online Drive Item" table).

var
	DownloadUrl: Label 'https://graph.microsoft.com/v1.0/drives/%1/items/%2/content', Comment = '%1 = Drive ID, %2 = Item ID', Locked = true;

procedure DownloadFile(AccessToken: Text; DriveID: Text; ItemID: Text; var Stream: InStream): Boolean
var
	TempBlob: Codeunit "Temp Blob";
	OStream: OutStream;
	JsonResponse: JsonObject;
	Content: Text;
	NewDownloadUrl: Text;
begin
	NewDownloadUrl := StrSubstNo(DownloadUrl, DriveID, ItemID);
	if GetResponse(AccessToken, NewDownloadUrl, Stream) then
		exit(true);
end;

Create a Folder

The following code creates a new Folder in a Document Library.

ItemID: id of the Parent Folder (optional)

var
	CreateFolderUrl: Label 'https://graph.microsoft.com/v1.0/drives/%1/items/%2/children', Comment = '%1 = Drive ID, %2 = Item ID', Locked = true;
	CreateRootFolderUrl: Label 'https://graph.microsoft.com/v1.0/drives/%1/root/children', Comment = '%1 = Drive ID', Locked = true;

procedure CreateDriveFolder(
	AccessToken: Text;
	DriveID: Text;
	ItemID: Text;
	FolderName: Text;
	var OnlineDriveItem: Record "Online Drive Item"): Boolean
var
	HttpClient: HttpClient;
	Headers: HttpHeaders;
	ContentHeaders: HttpHeaders;
	RequestMessage: HttpRequestMessage;
	RequestContent: HttpContent;
	ResponseMessage: HttpResponseMessage;
	ResponseText: Text;
	JsonBody: JsonObject;
	RequestText: Text;
	EmptyObject: JsonObject;
	JsonResponse: JsonObject;
begin
	Headers := HttpClient.DefaultRequestHeaders();
	Headers.Add('Authorization', StrSubstNo('Bearer %1', AccessToken));
	if ItemID = '' then
		RequestMessage.SetRequestUri(StrSubstNo(CreateRootFolderUrl, DriveID))
	else
		RequestMessage.SetRequestUri(StrSubstNo(CreateFolderUrl, DriveID, ItemID));
	RequestMessage.Method := 'POST';

	// Body
	JsonBody.Add('name', FolderName);
	JsonBody.Add('folder', EmptyObject);
	JsonBody.WriteTo(RequestText);
	RequestContent.WriteFrom(RequestText);

	// Content Headers
	RequestContent.GetHeaders(ContentHeaders);
	ContentHeaders.Remove('Content-Type');
	ContentHeaders.Add('Content-Type', 'application/json');

	RequestMessage.Content := RequestContent;

	if HttpClient.Send(RequestMessage, ResponseMessage) then
		if ResponseMessage.IsSuccessStatusCode() then begin
			if ResponseMessage.Content.ReadAs(ResponseText) then begin
				if JsonResponse.ReadFrom(ResponseText) then
					ReadDriveItem(JsonResponse, DriveID, ItemID, OnlineDriveItem);

				exit(true);
			end;
		end;
end;

Delete a Drive Item

The following code deletes a folder or a file from a Document Library. ItemID is the id of the Drive Item (file or folder) saved in "Online Drive Item" table.

var
	DeleteUrl: Label 'https://graph.microsoft.com/v1.0/drives/%1/items/%2', Comment = '%1 = Drive ID, %2 = Item ID', Locked = true;

procedure DeleteDriveItem(AccessToken: Text; DriveID: Text; ItemID: Text): Boolean
var
	HttpClient: HttpClient;
	Headers: HttpHeaders;
	RequestMessage: HttpRequestMessage;
	ResponseMessage: HttpResponseMessage;
begin
	Headers := HttpClient.DefaultRequestHeaders();
	Headers.Add('Authorization', StrSubstNo('Bearer %1', AccessToken));

	RequestMessage.SetRequestUri(StrSubstNo(DeleteUrl, DriveID, ItemID));
	RequestMessage.Method := 'DELETE';

	if HttpClient.Send(RequestMessage, ResponseMessage) then
		if ResponseMessage.IsSuccessStatusCode() then
			exit(true);
end;

Conclusion

So this post has covered all basic operations that can be performed to handle documents in SharePoint within Business Central. Publishing, Version control etc. SharePoint features are not covered.

Tip: The same code with little changes can be used to integrate with OneDrive. Basically, Microsoft Graph API offers the same API for SharePoint and OneDrive to handle files.

Code in Action

Complete source code with working examples can be downloaded from GitHub. Issues and recommendations can be posted at GitHub Issue Tracker.

Happy Coding!!!

#MsDyn365 #MsDyn365BC #BusinessCentral #SharePoint #DynamicsNAV #MSGraphAPI

]]>https://www.msnjournals.com/post/generic-oauth2-library-for-business-central5f41e0c657cc36001795f9f6Sun, 23 Aug 2020 06:14:35 GMTMSN RajuGeneric OAuth2 Library for Business Central is to acquire Access Token from Azure AD, Google, Facebook etc. OAuth is most commonly used authorization method across all platforms. Acquiring Access Token is a little difficult in Business Central, though there is a Codeunit called OAuth2 available in the system. To help the Business Central developers' community, I thought of creating this generic library for OAuth2, so that developers can use this in their applications.

Supported Types

The following grant types are supported:

• Authorization Code
  • Tested with Azure AD, Google, Facebook
• Password Credentials
  • Tested with Azure AD
• Client Credentials
  • Not yet tested

Please refer oauth.net to understand OAuth and grant types.

Setup OAuth 2.0 Applications

First you need to setup a client application in the provider's website.

example: portal.azure.com, console.developers.google.com, developers.facebook.com/apps etc.

Note: Please refer to the Graph API post to learn how to register and setup an application in azure portal.

OAuth 2.0 Application (Page 50101)

Client ID, Client Secret, Scope / Permissions, Endpoints etc. inputs need to be updated in this page. Most of the inputs are available in the application that you have registered in the provider's website.

You can test the configuration by clicking on the "Request Access Token" action button.

OAuth 2.0 Applications (Page 50100)

You can see list of Applications with the status. Using this, you can create a new application.

How to Use

After updating the application details in "OAuth 2.0 Application" page, you can use the following Codeunit to get Access Token.

OAuth 2.0 App. Helper (Codeunit 50101)

RequestAccessToken method will update Access Token in "OAuth 2.0 Application" record. It will return false with an error message if it is failed.

The following code acquires access token from Google and displays in a message box.

procedure GetGoogleAccessToken()
var
	OAuth20Appln: Record "OAuth 2.0 Application";
	OAuth20AppHelper: Codeunit "OAuth 2.0 App. Helper";
	MessageText: Text;
begin
	OAuth20Appln.Get('GOOGLE');
	if not OAuth20AppHelper.RequestAccessToken(OAuth20Appln, MessageText) then
		Error(MessageText);

	Message('%1', OAuth20AppHelper.GetAccessToken(OAuth20Appln));
end;

Conclusion

You can download and use these objects in your application. But I recommend testing all integration scenarios thoroughly before using in production environment. If you have any questions you can ask by writing comments below this post.

Code in Action

Access Token from Facebook:

You can download the complete source code from GitHub, and you can report issues on GitHub Issue Tracker.

#MsDyn365 #MsDyn365BC #BusinessCentral #DynamicsNAV #OAuth2

]]>https://www.msnjournals.com/post/cryptography-support-in-business-central5f3a11c4ef93210017c77216Mon, 17 Aug 2020 22:30:09 GMTMSN RajuIn AL there is a codeunit called Cryptography Management (Codeunit 1266) which provides helper functions for encryption and hashing. Cryptography is used to keep the data safe by encrypting and depcrypting the data so that others canot misuse the data.

This post covers only basic usege of Cryptography Management codeunit. The following are the topics convered in this post.

• Encryption Key
• Importing / Exporting Encryption Key
• Encrypt / Decrypt data

Encryption Key

Encryption Key is a unique string used by Cryptography Management for data encryption. This is maintained at the tenent level. This key is generated by using .NET Framework Data Protection API interally by enabling Encryption Key.

The following code enables Encryption programatically:

local procedure EnableEncryptionKey()
var
	CryptographyManagement: Codeunit "Cryptography Management";
begin
	CryptographyManagement.EnableEncryption(true);
end;

Encryption can be enabled using "Data Encryption Management" page, by clicking Enable Encryption action button.

In Business Central online this is by default Enabled, and it can not be disabled.

After clicking Enable Encryption action button, it ask you to download a copy of encryption key so that you can keep it in a safe location.

Importing / Exporting Encryption Key

In this page there are few more options like Export Encryption Key, Import Encryption Key and Change Encryption Key.

• Export Encryption Key - To backup exiting encryption key.
• Import Encryption Key - Existing encrytion key can be restored / imported using this option.
• Change Encryption Key - When encryption is already enabled, you can use this option to change encryption key.

Encrypt / Decrypt data

You can encrypt secret data using Encrypt method, and when it is need you can decrypt the data using Decrypt method.

The following code encrypts the text 'Hello':

local procedure TryEncrypt()
var
	CryptographyManagement: Codeunit "Cryptography Management";
	EncryptedText: Text;
begin
	EncryptedText := CryptographyManagement.Encrypt('Hello');
	// pIuF3czIJLvv/KRQUKoGyXa2h2TEBonmxtlHu5lNJo4irzb5srQQl5isHuw182aL+op2FuehEq5/o0/8Nr3N1B34E8pbXdXRcC77sL+EfrXxZ2szebHNaQ47W6bTfLdLE4qYIQgcXx5s0VtFc6yLwvVe7bKHG02o8bYh6kiKrDIWdgwZyN5lOpbOrwMhl+ISAZo3iFrhR1OSnWF2uhCn4yyvGjhgA0Yp+9akLZqi8KycECRyIxhiGtSlg99be2aklDMWhGnNNTkL/BCxcEGPqp8ccXjMr/k5tRyw4VZsHSwYKIjnSUiVawh+1GqryG18vHV7JVpXyb1JFRDIkQ3uCQ==
end;

The following code decrypts the encryped text to 'Hello':

local procedure TryDecrypt()
var
	CryptographyManagement: Codeunit "Cryptography Management";
	EncryptedText: Text;
	Data: Text;
begin
	EncryptedText := 'pIuF3czIJLvv/KRQUKoGyXa2h2TEBonmxtlHu5lNJo4irzb5srQQl5isHuw182aL+op2FuehEq5/o0/8Nr3N1B34E8pbXdXRcC77sL+EfrXxZ2szebHNaQ47W6bTfLdLE4qYIQgcXx5s0VtFc6yLwvVe7bKHG02o8bYh6kiKrDIWdgwZyN5lOpbOrwMhl+ISAZo3iFrhR1OSnWF2uhCn4yyvGjhgA0Yp+9akLZqi8KycECRyIxhiGtSlg99be2aklDMWhGnNNTkL/BCxcEGPqp8ccXjMr/k5tRyw4VZsHSwYKIjnSUiVawh+1GqryG18vHV7JVpXyb1JFRDIkQ3uCQ==';
	Data := CryptographyManagement.Decrypt(EncryptedText);
end;

Conclusion

In the early versions on Business Central / NAV, to achieve this functionality we had to use .Net variables. Now its part of System. There are many other methods in "Cryptography Management" codeunit you must try.

Happy Coding!!!

#MsDyn365 #MsDyn365BC #BusinessCentral #DynamicsNAV

]]>https://www.msnjournals.com/post/how-to-use-microsoft-graph-api-in-business-central5f3940878aad1900179d1a2fSun, 16 Aug 2020 17:27:42 GMTMSN RajuMicrosoft Graph API is very powerful Restful Web API, and a gateway to data in Microsoft 365. Data from diffrent applications in Microsoft 365 like SharePoint, Teams, Calenders, OneDrive etc. can be accessed using very simple web queries.

Now Business Central data can also be accessed by using Microsoft Graph API from other applications using the same API. More information can be found at Working with the Dynamics 365 Business Central API in Microsoft Graph

How ?

We can use Microsoft Graph API by following 5 simple steps.

1. Register your Application in Azure Portal.
2. Add Redirect URI(s)
3. Add Permissions to the Application
4. Add Client Secret to the Application
5. Get Authetication Token
6. Quering Data

Register your application

1) Open www.portal.azure.com and sign-in using your organization credientials.

2) Search for App Registrations in the search bar and select App registrations.

3) Click on New registration button.

4) Enter your Application Name, and click on Register button.

5) You should be in the following screen after clicking the Register button.

Add Redirect URI(s)

1) Click on Add a Redirect URI link

2) Click on Add a platform and Select the Web option in the Configure platforms panel

3) Update the Redirect URI. You should replace localhost:8080 with your web servers host name. Then click the Configure button.

Add Client Secret to the Application

1) Select Certificates & secrets button in the left navigation menu and click the New client secret button in right panel.

2) You will get the following dialouge. Enter Description, and select Expires option. Click the Add button.

3) The above step creates a client secret. You need to copy this value and save it somewhere. Once this page is closed, you cannot copy this value again.

Add Permissions

1) Click on API permissions button from the left navigation menu

2)You will see the following screen on the right side of the navigation menu. Click on Add a Permission button under Configure permissions.

3) Select the Microsoft Graph option in Request API Permissions.

4) Select the Delegated permissions option.

5) Search for "Files" in the search box, and select Files.ReadWrite.All option in the list and click on the Add Permissions button.

6) After completing the above steps you should be able to see the following permissions.

API End Point

API Endpoints can be found after selecting Overview, by clicking on Endpoints button. we are going use OAuth 2.0 authorization endpoint (v2) for get AuthToken.

Get Authetication Token

We are using OAuth2 codeunit to get Autherization Token, this codeunit also has some useful functions related to OAuth2 authentication.

In the below code, the GetAccessToken function gets the AuthToken using OAuth2 codeunit.

codeunit 50115 "Graph API Helper"
{
    var
        OAuth2: Codeunit OAuth2;
        ClientIdTxt: Label '96e2efa1-a6fb-4f04-97d9-1f9ac9c15917', Locked = true;
        ClientSecret: Label '44Qi99bD4EC4S27~_.5htAp1o_lLd7tfBg', Locked = true;
        ResourceUrlTxt: Label 'https://graph.microsoft.com', Locked = true;
        OAuthAuthorityUrlTxt: Label 'https://login.microsoftonline.com/67c5a58a-7424-4d4d-b6c2-ddc89830cf74/oauth2/authorize', Locked = true;
        RedirectURLTxt: Label 'http://localhost:8080/BC160/OAuthLanding.htm', Locked = true;
        OneDriveRootQueryUri: Label 'https://graph.microsoft.com/v1.0/me/drive/root/children', Locked = true;

    procedure GetAccessToken(): Text
    var
        PromptInteraction: Enum "Prompt Interaction";
        AccessToken: Text;
        AuthCodeError: Text;
    begin
        OAuth2.AcquireTokenByAuthorizationCode(
            ClientIdTxt,
            ClientSecret,
            OAuthAuthorityUrlTxt,
            RedirectURLTxt,
            ResourceURLTxt,
            PromptInteraction::Consent,
            AccessToken,
            AuthCodeError);

        if (AccessToken = '') or (AuthCodeError <> '') then
            Error(AuthCodeError);

        exit(AccessToken);
    end;
}

Quering Data

In the below code, the GetOneDriveFiles function is quering data from OneDrive's root folders and files using Microsoft Graph API.

    procedure GetOneDriveFiles(): JsonObject
    var
        Client: HttpClient;
        RequestMessage: HttpRequestMessage;
        ResponseMessage: HttpResponseMessage;
        JsonResponse: JsonObject;
        AccessToken: Text;
        JsonContent: Text;
    begin
        AccessToken := GetAccessToken();

        RequestMessage.Method('GET');
        RequestMessage.SetRequestUri(OneDriveRootQueryUri);
        Client.DefaultRequestHeaders().Add('Authorization', StrSubstNo('Bearer %1', AccessToken));
        Client.DefaultRequestHeaders().Add('Accept', 'application/json');

        if Client.Send(RequestMessage, ResponseMessage) then
            if ResponseMessage.HttpStatusCode() = 200 then begin
                ResponseMessage.Content.ReadAs(JsonContent);
                JsonResponse.ReadFrom(JsonContent);
                exit(JsonResponse);
            end;
    end;

Conclusion

This is a very simple example to retrieve data from OneDrive. Using the Microsft Graph API you can access almost any data in Microsoft 365. For example, using this Microsoft Graph API we can integrate SharePoint documents with Sales Order, Purchase Order pages, show e-mail communications in the Customer page etc.

Happy Coding!!!

You can download complete sample code from GitHub.

#MsDyn365 #MsDyn365 #BusinessCentral #DynamicsNAV #ALLanguage

]]>https://www.msnjournals.com/post/how-to-solve-table-locking-issues-in-business-central5f2c0f2b9216880017b74551Sun, 09 Aug 2020 14:13:29 GMTMSN RajuTable Locking is a very common problem in Microsoft Dynamics 365 NAV / Business Central. If the problem is understood correctly and the right technique is used, Locking Errors can be solved very easily. This post explains different techniques that can be used to solve Locking errors.

What is a Transaction?

Transaction is a unit of work which contains one or more operations.

The following are the some of the events that creates a new Transaction in Business Central:

• Saving a record in a Page - Logic written in the OnInsert, OnModify, and OnRename triggers.
• Executing Action Button in a Page – Logic written in Run Object’s OnRun trigger, and OnAction trigger.
• On Execution of a Web Service – Logic written in Codeunits, XMLports, and Report

Transaction is automatically closed (committed) on completion of executing the logic. When a COMMIT statement is executed, the current Transaction is closed, and a new Transaction will begin. When an ERROR statement is executed, the current Transaction is terminated and all the changes made by the Transaction are rolled back.

About Locks

Database Locks are for your good only. Like a parent protecting siblings fighting with each other, Database Lock protects the data from being overwritten by the other Transactions executing at the same time.

When a Transaction tries to access the data that is being Locked by another Transaction, SQL Server blocks that Transaction. And when a Transaction is blocked for more than 10 seconds (Lock Time-out), it will be terminated automatically with the "Table was Locked by another User" error.

There is a setting called Lock Time-out in Alter Database / Advanced tab. Default value for the Lock Time-out is

10 seconds. Lock Time-out feature can be turned off for long running processes by calling Database.LockTimeout(false) function in the CAL / AL code.

In Business Central / Dynamics NAV, the SQL Server uses Row Level Locking, which means two Users can modify the data in the same table simultaneously but cannot modify the same data (rows).

Note: LockTable, FindSet (ForUpdate: true) statements also apply Row Level Locks.

Row Level Locking is not effective for Ledger table

Most of the Ledger Entry tables in Business Central / Dynamics NAV has "Entry No." as the Primary Key. To generate Primary Key in most of the places, following algorithm is used.

LedgerEntry.LOCKTABLE;
IF LedgerEntry.FINDLAST THEN
 NextEntryNo := LedgerEntry.”Entry No.” + 1
ELSE
 NextEntryNo := 1;

For some reason this algorithm is used everywhere. This algorithm will not allow "Row Level Locking" to work effectively. When this type of code is being executed simultaneously, only first Transaction gains access to the last row of the table. All other Transactions which need the last row will be Blocked until the first Transaction finished.

Note: Wherever possible, it is recommended to use the Auto increment property to generate Primary Key (Entry No.) instead of using the above algorithm.

Common Errors

Business Central / Dynamics NAV throws the following type of errors related to this topic.

• Another user has modified the record
• A record was locked by another user
• The activity was deadlocked with another user

Another user has modified the record

This error message is related to concurrency control, and it has nothing to do with Database Locks.

Business Central / Dynamics NAV maintains a Timestamp column in each table in the SQL Server to maintain row versions. Whenever a record is being Inserted or Modified, system will automatically update a new version number in the Timestamp column. And when a record is being modified, system will check the Timestamp of the current record with the previously saved Record. If it doesn’t match, the system will throw the given error message.

It is very very rare that it happens because another user has actually modified the record. It is usually because of the bad code.

Business Central: The changes to the Customer record cannot be saved because some information on the page is not up-to-date.

Dynamics NAV: Another user has modified the record for this Customer

The following code generates "Another user has modified the record" error message:

procedure ModifyCustomer()
var
	Customer: Record Customer;
begin
	Customer.FindFirst();
	SetName(Customer);
	SetEMail(Customer);
	Message('Name: %1, E-Mail: %2', Customer.Name, Customer."E-Mail");
end;

local procedure SetName(Customer: Record Customer)
begin
	Customer.Name := StrSubstNo('Customer - %1', Format(Random(10000)));
	Customer.Modify();
end;

local procedure SetEMail(Customer: Record Customer)
begin
	Customer."E-Mail" := StrSubstNo('cust.%1@test.com', Format(Random(10000)));
	Customer.Modify();
end;

In the above code, the SetEMail function is not aware that the row version of Customer record has changed in the SetName function, and it is trying to change the old version of the Customer record. Concurrency Control doesn't allow to modify the record of an older version.

This problem can be fixed by changing Customer parameter to reference type (var Cust: Record Customer), so that all these functions are working on a single record variable instance.

local procedure SetName(var Customer: Record Customer)
begin
	Customer.Name := StrSubstNo('Customer - %1', Format(Random(10000)));
	Customer.Modify();
end;

local procedure SetEMail(var Customer: Record Customer)
begin
	Customer."E-Mail" := StrSubstNo('cust.%1@test.com', Format(Random(10000)));
	Customer.Modify();
end;

A record was locked by another user

When a Transaction is blocked for more than 10 seconds (Lock Time-out), it will be terminated automatically with the following error.

Business Central: The operation could not complete because a record in the Sales Line table was locked by another user. Please retry the activity.

Dynamics NAV: The operation could not complete because a record was locked by another user

If the below code is executed in two clients simultaneously, it will generate the above error.

procedure First()
var
	SalesLine: Record "Sales Line";
	Window: Dialog;
	x: Integer;
begin
	Window.Open('#1##########');
	Window.Update(1, 'Waiting ...');
	SalesLine.FindSet();
	repeat
		x += 1;
		Window.Update(1, StrSubstNo('Processing - %1', SalesLine."No."));
		SalesLine.Modify();
		Sleep(1000);
	until (SalesLine.Next() = 0) or (x > 15);
	Window.Close();
	Message('Execution completed successfully.');
end;

This code is going to be executed for more than 20 seconds. 2nd client will exceed the Lock Timeout limit, and it will get the Locking error.

The below code can be executed in two clients simultaneously without any Locking errors:

procedure Second()
var
	SalesLine: Record "Sales Line";
	Window: Dialog;
	x: Integer;
begin
	Window.Open('#1##########');
	Window.Update(1, 'Waiting ...');
	SalesLine.FindSet();
	repeat
		x += 1;
		Window.Update(1, StrSubstNo('Processing - %1', SalesLine."No."));
		SalesLine.Modify();
		Sleep(1000);

		Commit();             // To generate a new Transaction
		Sleep(10);            // Allow blocked Transactions to get priority
	until (SalesLine.Next() = 0) or (x > 15);
	Window.Close();
	Message('Execution completed successfully.');
end;

There is a big difference between the first and the second code, though only two lines of code is different. The Code written in the first function creates a Transaction at FindSet() statement and it is going to last till the end for more than 20 seconds. Whereas the Code written in the second function is releasing the Transaction in each iteration, though it is creates a Transaction at FindSet() statement.

Transaction that takes more than 10 seconds can cause locking errors. To avoid locking errors, Transaction should be finished as quickly as possible.

The activity was deadlocked with another user

This error occurs when two transactions are blocking each other.

If LockingSequence1 and LockingSequence2 functions from the below code are executed simultaneously in two different clients, one of the Transactions will be terminated with the deadlock error.

procedure LockingSequence1()
var
	SalesHeader: Record "Sales Header";
	SalesLine: Record "Sales Line";
begin
	Counter1 += 1;
	SalesLine.LockTable();
	SalesLine.FindFirst();

	Sleep(5000);
	if (Counter1 > 1) then
		Message('The code with the "Sales Line, Sales Header" locking sequance has been executed more than once.');

	SalesHeader.LockTable();
	SalesHeader.FindFirst();

	Counter1 := 0;
	Message('Executed successfully.');
end;

procedure LockingSequence2()
var
	SalesHeader: Record "Sales Header";
	SalesLine: Record "Sales Line";
begin
	Counter2 += 1;
	SalesHeader.LockTable();
	SalesHeader.FindFirst();
	Sleep(5000);
	if (Counter2 > 1) then
		Message('The code with the "Sales Header, Sales Line" locking sequance has been executed more than once.');
	SalesLine.LockTable();
	SalesLine.FindFirst();

	Counter2 := 0;
	Message('Executed successfully.');
end;

Note: I have just noticed, if deadlock occurs in Business Central, it is automatically reattempting the failed transaction.

Deadlock errors can be fixed by correcting the sequence of Table Locking. The above code can be fixed by following the same Locking sequence in both functions.

Though it is not a good practice, the below code will fix the problem by forcefully locking the tables in the needed sequence.

procedure LockingSequence2Fixed()
var
	SalesHeader: Record "Sales Header";
	SalesLine: Record "Sales Line";
begin
	Counter3 += 1;
	SalesLine.LockTable();
	SalesLine.FindFirst();

	SalesHeader.LockTable();
	SalesHeader.FindFirst();
	Sleep(5000);

	if (Counter3 > 1) then
		Message('The code with the "Sales Line*, Sales Header" locking sequance has been executed more than once.');

	SalesLine.LockTable();
	SalesLine.FindFirst();

	Counter3 := 0;
	Message('Executed successfully.');
end;

Job Queues

Job Queues can be used to solve Locking Errors. The Transactions that can be executed in the background, can be queued to Job Queue. Job Queue Entry table holds the parameters in order to execute the Transaction and Job Queue processes the Job Queue Entries sequentially.

Locking Errors only occur, when more than one Transactions are executing simultaneously. No Locking Errors would occur, if they are executed sequentially. If the Transactions are delegated to Job Queue to process through Job Queue Entry, the Locking Error problem is almost solved.

Code Samples in Action

You can download and try the source code from GitHub.

Conclusion

This post is covering some of the problems related to Table Locking issues, but not all of them. There are various other factors that impacts performance and creates locking issues. The key thing to resolve Locking Errors is by optimizing the time to complete the Transactions. This can be done by optimizing the Code, the SQL Queries, the SQL Indexes, and the process.

Happy Coding!!!

#MsDyn365 #MsDyn365BC #BusinessCentral #DynamicsNAV

]]>https://www.msnjournals.com/post/how-to-add-filter-tokens-in-microsoft-dynamics-365-business-central5f2553d877b9a30017080515Sat, 01 Aug 2020 12:31:09 GMTMSN RajuCustom Filter Tokens is an interesting functionality in Business Central. Many of us do not know about this functionality. Using this functionality, you can add Filter Tokens like Tomorrow, Yesterday, ThisMonth, PrevMonth, FiscalYear, PrevFiscalYear, NextFiscalYear etc. so that User can use them just like Today and WorkDate Filter Tokens to apply date filters.

You can add Filter Tokens for Date, Time, DateTime and Text data types.

Filter Tokens [Codeunit 41]

This exposes functionality that allow users to specify pre-defined filter tokens that get converted to the correct values for various data types when filtering records.

It has the following events you can subscribe:

• OnResolveDateFilterToken
• OnResolveDateTokenFromDateTimeFilter
• OnResolveTextFilterToken
• OnResolveTimeFilterToken
• OnResolveTimeTokenFromDateTimeFilter

Sample Code

For demonstration purposes, we are using OnResolveDateFilterToken event to add Tomorrow, Yesterday, ThisMonth, PrevMonth, FiscalYear, PrevFiscalYear and NextFiscalYear tokens.

Date Filter Tokens Impl [DateFilterTokensImpl.Codeunit.al]

codeunit 50103 "Date Filter Tokens Impl"
{
    [EventSubscriber(ObjectType::Codeunit, Codeunit::"Filter Tokens", 'OnResolveTimeTokenFromDateTimeFilter', '', false, false)]
    local procedure OnResolveDateFilterToken(DateToken: Text; var FromDate: Date; var ToDate: Date; var Handled: Boolean)
    begin
        case UpperCase(DateToken) of
            'YESTERDAY', 'YD':
                begin
                    FromDate := CalcDate('-1D', Today);
                    ToDate := FromDate;
                    Handled := true;
                end;
            'TOMORROW', 'TO':
                begin
                    FromDate := CalcDate('-1D', Today);
                    ToDate := FromDate;
                    Handled := true;
                end;
            'THISMONTH', 'TM':
                begin
                    FromDate := CalcDate('CM - 1M + 1D', Today);
                    ToDate := CalcDate('CM', Today);
                    Handled := true;
                end;
            'PREVMONTH', 'PM':
                begin
                    FromDate := CalcDate('CM - 2M + 1D', Today);
                    ToDate := CalcDate('CM - 1M', Today);
                    Handled := true;
                end;
            'FISCALYEAR', 'FY':
                begin
                    FromDate := GetFiscalYear();
                    ToDate := CalcDate('+12M - 1D', FromDate);
                    Handled := true;
                end;
            'PREVFISCALYEAR', 'PFY':
                begin
                    FromDate := CalcDate('-1Y', GetFiscalYear());
                    ToDate := CalcDate('+12M - 1D', FromDate);
                    Handled := true;
                end;
            'NEXTFISCALYEAR', 'NFY':
                begin
                    FromDate := CalcDate('+1Y', GetFiscalYear());
                    ToDate := CalcDate('+12M - 1D', FromDate);
                    Handled := true;
                end;
        end;
    end;

    local procedure GetFiscalYear(): Date
    var
        AccountingPeriod: Record "Accounting Period";
    begin
        AccountingPeriod.Reset();
        AccountingPeriod.SetRange("New Fiscal Year", true);
        AccountingPeriod.SetRange(Closed, false);
        if AccountingPeriod.FindFirst() then
            exit(AccountingPeriod."Starting Date");
    end;
}

Filter Tokens in Action:

,Conclusion:

Users will definitely like this functionality because you are saving lot of his / her time. For example, If User can enter FiscalYear as Date Filter instead of recollecting the start and the end date of the fiscal year and typing it manually, he can save a lot of his time.

You can download the source code from GitHub.

#MsDyn365 #MsDyn365BC #BusinessCentral

]]>https://www.msnjournals.com/post/how-to-create-assisted-setup-for-your-business-central-extension5f22a8adcc80c50017f71ac3Thu, 30 Jul 2020 11:33:57 GMTMSN RajuAssisted Setup is a wizard page to help Business Central User setting up a module. When you are creating an extension for Business Central, you must consider creating one or more Assisted Setups for your extension.

Wizard Page:

Assisted Setup is nothing but a wizard page (guided page) containing one or more steps to help Business Central User to configure setups.

Page layout:

Page contains at least two steps, start and finish (welcome and thanks) steps. Each step is a field group and visibility which are controlled by a boolean variable or a step number condition.

For example, VAT Setup Wizard contains the following steps:

• Welcome to VAT Setup
• VAT Business Posting Groups
• VAT Product Posting Setup
• Assign VAT Setup to Customer, Vendor, and Item Templates
• Manual setup required
• That''s it!

Actions:

There will be Back, Next, Finish actions to navigate between steps, again actions are enabled or disabled based on the state of some variables.

For example, Back is disabled in the first step, and Next is disabled in the last step.

Assisted Setup [Codeunit 3725]

Assisted Setup is system codeunit which allows you to register your wizard page and execute your wizard page when the User opens it from Assisted Setup.

Assisted Setup codeunit has the following events:

• OnRegister - Triggered when Assisted Setup list page is being opened.
• OnReRunOfCompletedSetup - Triggered if the previously completed Assisted Setup is being run again.
• ·OnBeforeOpenRoleBasedSetupExperience - Triggered when Assisted Setup is opened from Navigation bar >> Settings >> Assisted setup
• OnAfterRun - Triggered after the Assisted Setup has finished.

,Best Practices:

• First step should contain Welcome message, and explanation of the wizard page.
• All actions (Back, Next, Finish) should validate User Inputs before navigating it to the next or back step.
• Only the Finish step should write data into actual tables. This is very critical because User can close the wizard page any time. Also, you should keep data in intermediate tables so that if the User opens the wizard page again, he doesn’t need to enter the same data again.

,,,Code Sample

Let us take a basic example; we will create an Assisted Setup to setup Sales Order, and Sales Invoice document Number Series.

We need minimum two objects; a codeunit to subscribe Assisted Setup codeunit events, and a page for the wizard page.

Assisted Setup Subscribers [NoSeriesSetupSubscribers.Codeunit.al]

We are subscribing Assisted Setup events to register our “No. Series Setup Wizard” page.

codeunit 50120 "No. Series Setup Subscribers"
{
    var
        Info: ModuleInfo;
        SetupWizardTxt: Label 'Set up Sales No. Series';
        x: Codeunit "Assisted Setup Subscribers";

    [EventSubscriber(ObjectType::Codeunit, Codeunit::"Assisted Setup", 'OnRegister', '', false, false)]
 local procedure Initialize()
 var
        AssistedSetup: Codeunit "Assisted Setup";
        Language: Codeunit Language;
        CurrentGlobalLanguage: Integer;
 begin
        CurrentGlobalLanguage := GlobalLanguage;
        AssistedSetup.Add(
            GetAppId(),
 Page::"No. Series Setup Wizard",
            SetupWizardTxt,
            "Assisted Setup Group"::GettingStarted,
 '',
            "Video Category"::Uncategorized,
 '');

        GlobalLanguage(Language.GetDefaultApplicationLanguageId());

 //Adds the translation for the name of the setup.
        AssistedSetup.AddTranslation(
 Page::"No. Series Setup Wizard",
            Language.GetDefaultApplicationLanguageId(),
            SetupWizardTxt);
        GlobalLanguage(CurrentGlobalLanguage);
 end;

 local procedure GetAppId(): Guid
 var
        EmptyGuid: Guid;
 begin
 if Info.Id() = EmptyGuid then
            NavApp.GetCurrentModuleInfo(Info);

 exit(Info.Id());
 end;
}

Wizard Page [NoSeriesSetupWizard.Page.al]

This page contains 3 steps, first step contains introduction, second step takes inputs from the User, and the third setup will finish the wizard by updating fields in Sales & Receivable Setup table.

page 50120 "No. Series Setup Wizard"
{
    Caption = 'Sales No. Series Setup';
    PageType = NavigatePage;
    SourceTable = "Sales & Receivables Setup";
    SourceTableTemporary = true;

    layout
    {
        area(content)
        {
            group(FirstStep)
            {
                Visible = CurrentPage = 1;
                group("Welcome to Email Setup")
                {
                    Caption = 'Welcome to Sales Number Series Setup';
                    Visible = CurrentPage = 1;
                    ;
                    group(Control18)
                    {
                        InstructionalText = 'You can setup Sales Order, Sales Invoice document Number Series.';
                        ShowCaption = false;
                    }
                }
                group("Let's go!")
                {
                    Caption = 'Let''s go!';
                    group(Control22)
                    {
                        InstructionalText = 'Choose Next so you can configure Number Series for Sales Orders, Sales Invoices.';
                        ShowCaption = false;
                    }
                }
            }

            group(Step2)
            {
                Caption = '';
                Visible = CurrentPage = 2;
                group("Para2.1")
                {
                    Caption = 'Select Number Series for Sales Orders';
                    field("Order Nos."; Rec."Order Nos.")
                    {
                        ApplicationArea = Basic, Suite;
                        ShowCaption = false;
                    }
                }
                group("Para2.2")
                {
                    Caption = 'Select Number Series for Sales Invoices';
                    field("Invoice Nos."; Rec."Invoice Nos.")
                    {
                        ApplicationArea = Basic, Suite;
                        ShowCaption = false;
                    }
                }
            }
            group(Step3)
            {
                ShowCaption = false;
                Visible = CurrentPage = 3;
                group("That's it!")
                {
                    Caption = 'That''s it!';
                    group(Control25)
                    {
                        InstructionalText = 'To update Number Series for sale documents, choose Finish.';
                        ShowCaption = false;
                    }
                }
            }
        }
    }

    actions
    {
        area(processing)
        {
            action(BackAction)
            {
                ApplicationArea = Basic, Suite;
                Caption = '&Back';
                Enabled = (CurrentPage > 1) AND (CurrentPage < 3);
                Image = PreviousRecord;
                InFooterBar = true;
                Promoted = true;

                trigger OnAction()
                begin
                    CurrentPage := CurrentPage - 1;
                    CurrPage.Update;
                end;
            }
            action(NextAction)
            {
                ApplicationArea = Basic, Suite;
                Caption = '&Next';
                Enabled = (CurrentPage >= 1) AND (CurrentPage < 3);
                Image = NextRecord;
                InFooterBar = true;
                Promoted = true;

                trigger OnAction()
                begin
                    case CurrentPage of
                        2:
                            begin
                                Rec.TestField("Order Nos.");
                                Rec.TestField("Invoice Nos.");
                            end;
                    end;

                    CurrentPage := CurrentPage + 1;
                    CurrPage.Update(false);
                end;
            }
            action(FinishAction)
            {
                ApplicationArea = Basic, Suite;
                Caption = '&Finish';
                Enabled = CurrentPage = 3;
                Image = Approve;
                InFooterBar = true;
                Promoted = true;

                trigger OnAction()
                var
                    AssistedSetup: Codeunit "Assisted Setup";
                begin
                    SalesSetup.Get();
                    SalesSetup."Order Nos." := Rec."Order Nos.";
                    SalesSetup."Invoice Nos." := Rec."Invoice Nos.";
                    SalesSetup.Modify();

                    AssistedSetup.Complete(PAGE::"No. Series Setup Wizard");
                    CurrPage.Close;
                end;
            }
        }
    }

    trigger OnInit()
    begin
        SalesSetup.Get();
        Rec := SalesSetup;
        CurrentPage := 1;
    end;

    trigger OnOpenPage()
    begin
        Insert;
    end;

    trigger OnQueryClosePage(CloseAction: Action): Boolean
    var
        AssistedSetup: Codeunit "Assisted Setup";
        Info: ModuleInfo;
    begin
        if CloseAction = Action::OK then
            if AssistedSetup.ExistsAndIsNotComplete(Page::"No. Series Setup Wizard") then
                if not Confirm(NAVNotSetUpQst, false) then
                    Error('');
    end;

    var
        SalesSetup: Record "Sales & Receivables Setup";
        CurrentPage: Integer;
        NAVNotSetUpQst: Label 'The Sales No. Series Setup has not been set up.\Are you sure you want to exit?';
}

Assisted Setup in Action

Conclusion

Assisted Setup are the best way to ask your User to configure setup data for your extension. You don’t need to provide training to your Users, because all the steps in the Assisted Setup are intuitive and guided with instructions.

You can download source code from GitHub.

#MsDyn365 #MsDyn365BC #BusinessCentral

]]>https://www.msnjournals.com/post/how-to-create-control-add-in-in-microsoft-dynamics-365-business-central5f20d57cc2c5090017ec8315Wed, 29 Jul 2020 03:02:46 GMTMSN RajuThis post explains you what is Control Add-in and you will learn how to create Control Add-in using existing resources on the internet. Sample code contains Carousel Control Control Add-in using Bootstrap resources. You can download source code from github. In the conclusion talked about why to use Control Add-in, what advantage Business Central User gains.

Introduction

Control Add-in is a special type of object in Business Central to create User Control. In other words Control Add-in (User Control) is a web component developed using JavaScript, HTML and CSS that can interact with Business Central. You need User Control when you do not have the required control available in standard Business Central. Also you need User Control when you want to simplify User Interface (UI) for your Business Central User.

Required Skills

You need to have the following skills to develop Control Add-ins:

• AL - Good • HTML - Basic • CSS - Basic • JavaScript - Basic

If you are smart enough, you just need to know how to copy paste :)

If you are new to HTML, CSS, and JavaScript, in my opinion w3shools.com is the best place to learn quickly.

Best Practices

You should always try to create reusable Control Add-ins. You should be able to use the same User Control in more than one page.

If you do not hard-code:

• A 'Map Control' can be used, in Customer, Vendor, Bank, Location pages.
• A 'Status Indicator Control' can be used in Sales, Purchase, and Service Orders, may also be in Bank Reconciliation page.

In the example given below, if you hard-code slides data in Control Add-in instead of sending as a parameter, you can not use this in other pages.

Let's create a Control Add-in

We don’t need to develop Control Add-in from scratch. There are tons of open source web components available on the web. We just need to understand the component and convert it to Control Add-in.

We are to using the following resources from bootstrap to create Control Add-in:

JavaScript

https://code.jquery.com/jquery-3.5.1.slim.min.js
https://cdn.jsdelivr.net/npm/popper.js@1.16.0/dist/umd/popper.min.js
https://stackpath.bootstrapcdn.com/bootstrap/4.5.0/js/bootstrap.min.js

CSS

https://stackpath.bootstrapcdn.com/bootstrap/4.5.0/css/bootstrap.min.css

,HTML

  

    

    

    

  
  

    

      
      

        
First slide label
        
Nulla vitae elit libero, a pharetra augue mollis interdum.
      
    
    

      
      

        
Second slide label
        
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
      
    
    

      
      

        
Third slide label
        
Praesent commodo cursus magna, vel scelerisque nisl consectetur.
      
    
  
  
    
    Previous
  
  
    
    Next
  

Now we are creating Carousel Control using the above resources.

1. Control Add-in Object [ CarouselControl.ControlAddin.al ]

This Carousel Control has OnStartup trigger, which will be triggered once the User Control is loaded.

SetCarouselData is a function that will send the slides data to Control Add-in.

controladdin "Carousel Control"
{
    HorizontalStretch = true;
    RequestedHeight = 200;

    // JS files required for Bootstrap
    Scripts = 'https://code.jquery.com/jquery-3.5.1.slim.min.js',
        'https://cdn.jsdelivr.net/npm/popper.js@1.16.0/dist/umd/popper.min.js',
        'https://stackpath.bootstrapcdn.com/bootstrap/4.5.0/js/bootstrap.min.js';

    StartupScript = 'src/startup.js';

    // Bootstrap css
    StyleSheets = 'https://stackpath.bootstrapcdn.com/bootstrap/4.5.0/css/bootstrap.min.css';

    procedure SetCarouselData(Data: JsonObject);
    event OnStartup();
}

2. Startup JavaScript file [ startup.js ]

This JavaScript file will be loaded once the User Control is ready. We are invoking OnStartup trigger so that the hosting page can receive the event and send the data back to the User Control.

Microsoft.Dynamics.NAV.InvokeExtensibilityMethod('OnStartup')

function carouselIndicators(slides) {
    var indicators = [];
    for (var i = 0; i < slides.length; i++) {
        var cssClass = i === 0 ? 'class="active"' : '';
        indicators.push(`
`);
    }

    return `
${indicators.join('')}
`;
}

function carouselItems(slides) {
    var carouselItems = [];
    for (var i = 0; i < slides.length; i++) {
        var slide = slides[i];
        var cssClass = i === 0 ? 'active' : '';

        carouselItems.push(`

    
        

        
${slide.title}
        
${slide.description}
    
`);
    }

    return `
${carouselItems.join('')}
`;
}

function carouselMarkup(data) {
    return `

    ${carouselIndicators(data.slides)}
    ${carouselItems(data.slides)}
    
        
        Previous
    
    
        
        Next
    
`;
}

window.SetCarouselData = function (data) {
    try {
        var markup = carouselMarkup(data);
        document.getElementById('controlAddIn').innerHTML = markup;
        $('#carouselExampleCaptions').carousel();
        console.log(markup);
    } catch (err) {
        console.log(err);
    }
}

3. Page [ CustomerListExt.PageExt.al ]

We are extending the Customers page to add Carousel Control at the top of the customers list. When the OnStartup event is triggered, we are preparing the Json Object that contains the slides data and sending it to Carousel Control.

pageextension 50100 CustomerListExt extends "Customer List"
{
    layout
    {
        addbefore(Control1)
        {
            usercontrol(Carousel; "Carousel Control")
            {
                trigger OnStartup()
                var
                    JObject: JsonObject;
                    Slides: JsonArray;
                begin
                    Slides.Add(AddSlide('Keep your promises', 'check before you make a promise', '//unsplash.it/1024/200'));
                    Slides.Add(AddSlide('Never forget', 'always register your conversations to ensure you follow-up promptly', '//unsplash.it/1025/200'));
                    Slides.Add(AddSlide('Qualify', 'be picky about which opportunities to spend time on', '//unsplash.it/1024/201'));
                    JObject.Add('slides', Slides);
                    CurrPage.Carousel.SetCarouselData(JObject);
                end;
            }
        }
    }

    local procedure AddSlide(Title: Text; Description: Text; Image: Text): JsonObject
    var
        Slide: JsonObject;
    begin
        Slide.Add('title', Title);
        Slide.Add('description', Description);
        Slide.Add('image', Image);
        exit(Slide);
    end;
}

Carousel Control in Action

Conclusion

If we think about it, The Users don't actually need training to work on portals just because they are intuitive. But in the case of Business Applications, we definitely need to provide training to the Business Users, where they already know their business more than us. Isn't it funny! It is simply because they are not provided proper and intuitive User Interfaces. I think we should try to provide proper UI to the Users so that it is convenient for their use. Proper UI means that we should not restrict our self only to the available controls. Where ever required, we should definitely try to create Control Add-ins / User Controls for better user experience.

Use Control Add-ins - Help customers!!

You can download the source code from Github

#msdynd365 #msdyn365bc #businesscentral

]]>