Customer Portal

Our Customer Portal module allows you to easily add extra menu options in the 'My Account' section. These new menu options are displaying real-time information from Microsoft Dynamics 365 Business Central. This gives your customers direct access to documents that would otherwise have to be handled by your staff manually.

Features

• Display Business Central customer-related data of your choice in the account section
• Display general ERP data such as orders, invoices, shipments, RMAs, and credit limit information
• Quickly place repeat orders for previously placed orders
• Connect to any Business Central table of your choice, depending on the information you need online.
• Allow your customers to download PDF files of the displayed information online, such as an invoice, packing slip, and order confirmation

Business Central

In order to make a connection with Business central via oAuth you have to register an app in Azure. To set this up please follow the steps below:

• Step 1: Register the app in portal.azure.com.
  a) Go to App Registrations – Add New.
  b) Name: Magento Customer Portal module.

  

• Step 2: Copy the Application (client) ID
  Copy it to Notepad and keep it in a safe place.

  

• Step 3: Go to Certificates & Secrets.
  Click ‘New client Secret’, set expiration to 24 months

  

• Step 4: Copy the Secret ID to Notepad and keep it in a safe place.
  This ID can be used by third party applications (e.g. Magento) to get access to Business Central.

  

• Step 5: Go To API Permissions.
  Click Add a permission, Select the Dynamics 365 Business Central in the right column.

  

• Step 5: Go to overview, click Redirect Urls.
  Add a new Platform of type ‘Web’, enter this redirect URL: https://businesscentral.dynamics.com/OAuthLanding.htm

  

• Step 5: Select API.ReadWrite.All and add the permission.

  

• Step 5: Next step is to ‘Grant admin consent’ for the user

  

• Step 6: Go to your Business Central and Search for Active Directory Applications.
  Type in the search bar ‘azure’, click on ‘Azure Active Directory Applications’

  

• Step 6: Add a new application
  a) Copy the Application ID from step 2 into the Client ID and set the state to ‘Enabled’.
  b) Assign the 365 Full Access user group to this application.

  

• Step 7: Click the ‘Grant Consent’ button in ribbon to authorize the module.

  

• Step 7: This should be done by an user with admin permissions.

  

Magento

Install the Tinx Customer Portal Magento extension. If you don't have access to our extension please reach out to our support department: support@tinx-it.nl. They can provide you with a composer key to use our extension.

Installation (Composer)

Add the following custom repository to your project's composer.json:

{
"repositories": [
{"type": "composer", "url": https://tinxit.repo.packagist.com/YOUR_TINX_USERNAME/}
]
}

Store the authentication credentials in your global Composer auth.json with the command below.

composer config --global --auth http-basic.tinxit.repo.packagist.com token YOUR_TINX_CUSTOMER_PORTAL_TOKEN

Configuration

In the Magento back-end go to Stores > Configuration. In the tab Tinx-IT, click on Tinx Customer Portal BC. In the configuration you can find the following fields:

• Field	Explanation
  Url to Access Token service	Url Magento uses to get a oAuth token from Business Central. Example: https://login.microsoftonline.com/GUID/oauth2/v2.0/token GUID: tenantGuid (see screenshot).
  Access token expires (UTC)	Read-only: Tells Magento when to request a new token from Business Central.
  Url to Business Central *	URL Magento uses to get document data from Business Central. The Web client URL has the following syntax: https://api.businesscentral.dynamics.com/v2.0/GUID1/ TinxDevelopment/api/ENVIRONMENT/customerPortal/v2.0/ companies(GUID2)/ Don't forget forward slash (/) at the end. GUID1: tenantGuid (see screenshot). ENVIRONMENT: environmentName (see screenshot). GUID2: companyGuid. Go to your Business Central and Search for the company you want to make a connection with. Type in the search bar ‘companies’, click on ‘Companies’, select the company and open the page inspection tool (CRTL+ALT+F1) (see screenshot).
  Url to PDF Codeunit	URL Magento uses to download PDF documents from Business Central. The Web client URL has the following syntax: https://api.businesscentral.dynamics.com/v2.0/GUID/ ENVIRONMENT/WS/COMPANY/Codeunit/printPDF GUID: tenantGuid (see screenshot). ENVIRONMENT: environmentName (see screenshot). COMPANY: companyName (see screenshot).
  Multiple API URL's?	Use this setting if you want to connect with multiple Business Central companies from one Magento website. NAV Company code: Company identifier of the Magento customer (see screenshot). Full Business Central API URL: Specify the URL to Business Central *
  Client ID	The Client ID is a public identifier for Business Central. You should be able to find this Client ID in Notepad. See step 2 in the Business Central section of this manual.
  Client Secret	The client Secret is a secret known only to Business Central. You should be able to find the Client Secret (Secret ID) in Notepad. See step 4 in the Business Central section of this manual.
  Customer Attribute	Customer identifier (Business Central Customer No.) of the Magento customer (see screenshot).
  Records limit	Meant for pagination in Magento, how many records should be shown per page? Functionality is currently not working
  Menu item label	Functionality is currently not working
  Column names with currency format	Separate multiple currency column names by comma (,). Functionality is currently not working
  Display currency sign	Will display currency sign when displaying prices at frontend. Functionality is currently not working
  Date Format	Specifies the date format for dates. Use Y for 4 digit year and y for 2 digit year Use d to display day of month (01-31) Use m to display month number (01-12) Use M to display month name (Jan to Dec) etc... Examples: Y-m-d, m-d-Y
  Customer Portal Menu block heading	Functionality is currently not working

• We created the following sales document * API pages in Business Central: Sales Orders, Sales Invoices, Sales Shipment, Sales Credit Memo and Return Receipt Headers. Those pages are used by the Customer Portal extension as a default to retrieve real-time information from Business Central. 

  
  

  Field	Explanation
  Enable Sales document * menu?	Determines if you want to activate the specific sales document functionality, to retrieve orders real-time from Business Central.
  Label	Title of the menu-item in the account section of the customer.
  Which columns should we display? If empty, all columns will be shown.	Use this if you want to specify which columns you want to display for this specific sales document header. The field identifiers (comma separated) should match the response of Business Central. To see the response of Business Central you can use an application like Postman. See our Postman section if you want to know how. For sales orders you can use the following example: no,yourReference,orderDate,shipTo,amount,tinxWebshopStatus
  Display Sales Order Lines?	Determines if you want to activate the specific sales document functionality, to retrieve sales lines real-time from Business Central. Subform-link display as: determine how to display the dropdown text button for sales lines to your customers (you can use any character).
  Which columns of the order lines should we display? If empty, all columns will be shown.	Use this if you want to specify which columns you want to display for this specific sales document sales lines. The field identifiers (comma separated) should match the response of Business Central. To see the response of Business Central you can use an application like Postman. See our Postman section if you want to know how. For sales orders you can use the following example: documentNo,itemNo,quantity,description,tinxWebshopStatus
  Display PDF Button?	Determine if you want to display a PDF button per sales document. PDF Icon: Should the link to the PDF displayed as an Icon? If you select 'No', it will be visible as a text link. What pdf function should we call? Determine which PDF function the sales document should use in Business Central to download the PDF. The following functions are supported: PrintPDFOrder (Sales Orders) PrintPDFInvoice (Sales Invoices) PrintPDFShipment (Sales Shipment) PrintPDFCredit (Sales Credit Memo) In order to use the PDF functionality you should publish a specific code-unit in Business central. Go to Business Central. Type in the search bar ‘web services’, click on ‘Web Services’ and click on new. The Object Type is 'Codeunit', Object id is '11205880' (TINX CPM General Functions) and the Service Name: 'printPDF' and publish the web service.
  Display ReOrder button?	Add a ReOrder button per sales document, to reorder previous items. Label to display on ReOrder button: Define how to display the text button to your customers (you can use any character). Label to display on ReOrder column: Define the title of the column to your customers (you can use any character). SKU column alias to be used to reorder item: The SKU field identifier. It should match the response of Business Central (document sales lines). For example: itemNo. Quantity column alias to be used to reorder item: The quantity field identifier. It should match the response of Business Central (document sales lines). For example: quantity. ID column alias to be used to reorder complete order: The Business Central sales document No. identifier. For example: Document_No or No. To see the response of Business Central you can use an application like Postman. See our Postman section if you want to know how.
  Who can see this menu item?	Table to configure the permissions of who can see this menu item. If no permissions are set, everyone can view it. You can create your own conditions based on customer attribute values. Functionality is currently not working
  What is the column name for default alphabetical A > Z sorting?	Which field identifier you want to use for sorting the sales document table in the customer account. Functionality is currently not working
  What is the direction for the default sort column?	Determine if the sorting for the the sales document table should be ascending or descending (based on the field identifier). Functionality is currently not working
  E-mail Button	Give per sales document the customers the ability to reach out to a sales person. Add extra column with e-mail button: Determine if you want to use this functionality. What label should the column have? Define the title of the column to your customers (you can use any character). What label should the button have? Define how to display the text button to your customers (you can use any character). What would the receiving address be? Define per sales document, who should receive the e-mail. What would the subject of this e-mail be?Define per sales document the subject of the e-mail. What would the body of this e-mail be? Define per sales document the body of the e-mail.

• If your implementation requires more than our standard Business Central sales document API pages, We've got you covered. We added three options in our Customer Portal extension to access a custom API page. Please use the Microsoft documentation to do so.

  
  

  Field	Explanation
  Enable custom menu?	Determines if you want to activate the custom menu functionality, to retrieve data real-time from Business Central.
  Label	Title of the menu-item in the account section of the customer.
  URL of service	EntitySetName value of the custom API page.
  filter field	Specify the Customer No. (business Central) identifier field.
  Which columns should we display? If empty, all columns will be shown.	Use this if you want to specify which columns you want to display for this specific sales document header. The field identifiers (comma separated) should match the response of Business Central.
  Who can see this menu item?	Table to configure the permissions of who can see this menu item. If no permissions are set, everyone can view it. You can create your own conditions based on customer attribute values. Functionality is currently not working
  What is the column name for default alphabetical A > Z sorting?	Which field identifier you want to use for sorting the sales document table in the customer account. Functionality is currently not working
  What is the direction for the default sort column?	Determine if the sorting for the the sales document table should be ascending or descending (based on the field identifier). Functionality is currently not working
  E-mail Button	Give per sales document the customers the ability to reach out to a sales person. Add extra column with e-mail button: Determine if you want to use this functionality. What label should the column have? Define the title of the column to your customers (you can use any character). What label should the button have? Define how to display the text button to your customers (you can use any character). What would the receiving address be? Define per sales document, who should receive the e-mail. What would the subject of this e-mail be?Define per sales document the subject of the e-mail. What would the body of this e-mail be? Define per sales document the body of the e-mail.

Postman (optional)

Postman is a standalone software testing API (Application Programming Interface) platform to build, test, design, modify, and document APIs. You can use Postman to test and see which field identifiers are available in the API pages. You can download Postman here.

To make life easier for you we prepared a Postman collection. You can download the collection here. This will help you setting up a Postman configuration to make a connection with Business Central. To set this up please follow the steps below:

• Step 1: Open Postman.
  a) Go to your workspace.
  b) Click on import and drag-and-drop the 'Example Customer Portal.postman_collection' file in the import-window.

  

• Step 2: Open the 'Example Customer Portal' collection and navigate to the 'Variables' tab
  Replace the dummy information in the 'Initial value' column with your business central data. The 'Initial value' and 'Current value' column should contain the same information. After this has been done save the collection
  
  a) tenantGuid - see screenshot
  b) companyGuid - see screenshot
  c) clientId - see step 2 in the Business Central section
  d) clientSecret - see step 4 in the Business Central section
  e) companyName - see screenshot
  f) environmentName - see screenshot

  

• Step 3: Open the 'Example salesOrders' request and navigate to the 'Authorization' tab
  a) To retrieve a Business Central token click on the orange button 'Get New Access Token'. If successful click on the orange button 'Use Token'. Now you've a token which is used to make a connection with Business Central (valid for one hour (by default)).
  b) Click on the blue button 'Send' to get the sales order information in the Postman response section. 
  
  Tip1: This example is for retrieving the sales orders list. To check which API pages are available remove the /salesOrders from the url.
  Tip2: You can add filters to your request, here you can find all supported filters. E.g.
  ../salesOrders?$filter=sellToCustomerNo eq 'XXXX'

  

• Step 4: Open the 'getPDF' request and navigate to the 'Authorization' tab
  a) To retrieve a Business Central token click on the orange button 'Get New Access Token'. If successful click on the orange button 'Use Token'. Now you've a token which is used to make a connection with Business Central (valid for one hour (by default)).
  b) Navigate to the 'Body' tab and replace the 'Your documentNo' with a Business Central sales order No.
  c) Click on the blue button 'Send' to get the sales order information in the Postman response section. 
  
  Tip: To get other PDF documents (not from sales orders). You can replace the 'PrintPDFOrder' element name in the 'Body' tab with: PrintPDFQuote, PrintPDFInvoice, PrintPDFShipment or PrintPDFCredit.