Sage 300 2020 Web SDK

Introduction

The Sage 300 Web SDK (SDK) is a collection of wizards, utilities, samples and documentation for developing Web Screens for the Sage 300 Application.

This week we released the Sage 300 2020 Web SDK to coincide with the release of the Sage 300 2020 Application.

It’s Available!

The SDK is available at https://github.com/SageNADev/Sage300-SDK.

Branches

As described in a previous blog and in the README file in the root of the repository, the branches contain the different versions of the SDK.

master

Contains the current version of the SDK (2020).

develop

Contains the in-progress version of the SDK (2020.1).

release-…

Contains the previous versions of the SDK (release-2017, release-2017.1, release-2017.2, release-2018, release-2018.1, release-2018.2, release-2019, release-2019.1, release-2019.2)

What’s New

Documentation

Updated documentation is available.

In the docs\upgrades folder is a document for the upgrade procedures for moving partner source from Sage 300 2019.2 to Sage 300 2020. There is a manual step in the upgrade process, so please familiarize yourself with the upgrade steps.

In the docs\development folder you will find the updated Developing New Application document that discusses and Security Resource Keys having a NONE value and the semantics for the AND and OR notation.

The docs\presentations folder has been updated and includes a PowerPoint presentation for what’s new in the SDK for 2020.

Visual Studio 2019

All wizard manifests have been revised to include Visual Studio 2019 as a target IDE.

Blog201.png

Visual Studio 2017 and Visual Studio 2019 are now supported targets.

Version Change

The Accpac.Advantage and Accpac.Advantage.Types versions are now 6.7.0.0 and all the AccpacDotNetVersion.props files for the source and samples have been updated.

 

Blog202.png

Visual Studio 2019 is now supported for web development and the .NET Framework remains at 4.7.2

Samples

The samples have been updated with new global references and modifications to support the new multiple session behavior.

The Segment Codes sample has been re-factored to use the new grid.

Solution Wizard

References to the global files were updated and a UI update added the Metro Modern UI Framework for an updated, consistent, and a Sage branded look and feel:

Blog203

The wizard is compatible with Visual Studio 2017 and Visual Studio 2019.

Customization Wizard

 References to the global files were updated and a UI update added the Metro Modern UI Framework for an updated, consistent, and a Sage branded look and feel:

Blog204

The Default Compatibility level was changed from 6.6A+ to 6.7A+.

The wizard is compatible with Visual Studio 2017 and Visual Studio 2019.

Code Generation Wizard

 References to the global files were updated and a UI update added the Metro Modern UI Framework for an updated, consistent, and a Sage branded look and feel:

Blog205.png

The wizard is compatible with Visual Studio 2017 and Visual Studio 2019.

Several items were addressed this release:

  • If wizard version does not match the Sage 300 Version, the wizard simply aborted
    • Added dialog for this scenario for developer to install the correct version of the wizard
  • Multiple Session Changes
    • With the ability in this version to run Sage 300 Web Screens in multiple tabs of the same browser, changes to support this behavior were required in the following files:
      • XXAreaRegistration.cs
      • Global.asax.cs
      • Web.config
      • PageUrl.txt
      • ..Behaviour.js
  • Added the ability to generate a grid for a Flat Code Type screen
    • The Accpac View must be Flat View and be a Revision List
      • #define FLAT_VIEW 1
      • #define HAS_REVSIONS 2

Blog206.png

Blog207.png

Upgrade Wizard

 References to the global files were updated and a UI update added the Metro Modern UI Framework for an updated, consistent, and a Sage branded look and feel:

Blog208

The wizard is compatible with Visual Studio 2017 and Visual Studio 2019.

With the ability in this version to run Sage 300 Web Screens in multiple tabs of the same browser, manual changes (documented in the docs/upgrade folder) to support this behavior are required in the following files:

      • XXAreaRegistration.cs
      • Global.asax.cs
      • Web.config
      • PageUrl.txt
      • ..Behaviour.js

 

Inquiry Configuration Wizard

No changes this release.

MergeISVProject Executable

This utility is a post-build utility used by various wizards and the generated partner solution to pre-compile Razor Views and deploy assets to a local Sage 300 installation for developer testing.

An issue was discovered where it failed during the minification operation if a space was present in the file path. This has been addressed.

For the upcoming 2020.1 release, an enhancement will be made to the utility to copy all external files in the projects required for the asp_compile.exe to perform without issue (not all manually added external developer references are currently copied).

Partner Enhancements in the Application

The following partner requests/suggestions have been added to the application to better support developer requirements:

  • Unhandled errors in the web screens are now logged in the trace.log file with the error stack
  • Issues for the grid and finder released in 2019.2 have been addressed
  • Mask issues in the finder have been addressed
  • Exception logging in the Business Entity Session now includes the error stack
  • IE11 has been removed as a supported browser for web screens
  • The “NONE” security resource key in the menu XML files to properly result in the menu item always showing regardless of security permissions of the user
  • The Instrumentation page (Core/Instrumentation) is available to display session resources used by the web screens

Desktop SDK CHM Files

Sage 300 is eliminating the delivery of CHM files starting with the 2020 release.

The Web SDK GitHub Repository is the perfect place to store these CHM and HTML help files. The Desktop SDK has been modified to point to the ‘master’ branch in the repository for these files:

Blog209.png

The files in the help/classic folder:

  • ACCPACControlsRef.chm
  • AccpacCOMAPI.chm
  • CViewChanges.zip (html files)
  • SDK-HELP.chm
  • TemplateQuickReference.zip (html files)

As with any file downloaded from the Internet, there is a possibility that the downloaded or cloned CHM and ZIP file may be blocked as the file system could detect that the files came from another computer and is protecting your computer.

If the CHM or ZIP file is blocked, simply access the properties of the file and select the “Unblock” checkbox.

 

Web API Sample POST Payloads

Sample POST payloads are now included in the samples/WebAPI_SamplePostPayloads folder and have sub-folders by module. These samples are great examples and learning tools for interacting with our Web API:

Blog2010.png

Multiple Sessions

Blog2011

Prior to 2020, the Sage 300 web screens could only be run in a single tab within a browser instance. This was because we stored a single key in the IIS Session Cache to identify the Sage 300 screen. Therefore, this mechanism made it impossible for multiple screens to be running at the same time since each screen would need to access the cache to ask, “who am i?”.

A new mechanism was required to allow Sage 300 to run in multiple tab pages with multiple contexts (user – company combinations):

  • A new segment was added to the URL
    • This session segment is an encoded value for the user-company combination

Blog2012.png

  • Each browser is sandboxed from other browsers
  • Each tab page is “partly” sandboxed from other tab pages
    • Each user-company combination is unique
  • Logging out will logout other tab pages in the same browser with the same user-company context, if they exist
    • There will only be a single warning from the main tab page
    • The Dirty flags will be ignored in the other tab pages

Blog2013.png

  • All ..Behaviour.js files were modified to invoke the PageUnloadManager in the window’s “beforeunload” event in order to properly skip the dirty checks if the screen is being unloaded from another tab pages logout

LanPak Licensing for the Web Screens

Prior to 2020, there were no LanPak checks in the web screens.

LanPak checks will be performed in the web screens:

  • A browser instance will be considered a sandbox. For example, if a user is logged into a web screen in Chrome as User1 – Company1, this will consume 1 license. If this same user was logged into Firefox, this would consume another license.
  • The browser instance will consider 1 license to be consumed for the same user regardless of how many tab pages it is used in.
    • For example, if User1 opens Company1, Company2, Company1, Company3 in 4 tab pages, this will be considered a single LanPak license.
    • For example, if User1 is logged in on tab 1 and user2 is logged in on tab page 2, this will consume 2 LanPak licenses.
  • There are several areas that still do not require LanPak licenses:
    • Web API
    • Sage 300 Web Screens invoked from CRM Integration
    • Payroll Timecard Web Screen

The Current User screen in the Desktop has been enhanced to show the web screen users:

Blog2014.png

User Eviction for Web Screens is coming in 2020.1

Coming in 2020.1

As a quick preview, here’s some of the items we will be working on for the 2020.1 release:

  • Web API
    • Better batch logic (all or nothing) (starting with AR Invoice)
    • Proper invalid error message when the payload contains an invalid item number
    • New Companies List endpoint
    • New CRM bi-directional endpoints as needed
  • Web SDK
    • Enhancement to open a view more than once in the business repository
    • Enhancement to provide a programmatic interface for displaying popups
    • Enhancement to the finder
      • Adding an Id property
      • Direct/Expanded interface without stacking parameters
      • Binding a ko.computed property to a label
      • Unifying the disable/disabled logic
      • Performance enhancement to the RVSpy utility
  • Application
    • PDX Improvements
      • Browser Icons, Menu Icons, Submenus, Signpost on Dashboard
    • Evict User from Web Screens
      • Using SignalR to free LanPaks and users from web
    • Multiple Contacts
      • Customer and Vendor (new MT module with backwards compatibility plus innovation)
    • CRM bi-directional integration

Summary

The Sage 300 2020 SDK is released and ready to be downloaded!

Documentation updates, the ability to run the wizards in Visual Studio 2017 or 2019, new grid implementation in the Segment Code sample, the ability to generate a grid for a Flat Code Type screen, synchronization of global files and references in the wizards, Sample POST Payloads, Desktop CHM files, and the multiple session enhancements are some of the features and enhancements in the Web SDK.

For functionality, documentation, tutorials, enhancements, etc. that are not currently in the SDK which should be there to better assist with efficient development practices and time-to-market considerations, please contact the Sage 300 Product Manager. The partners voice and feedback resound the loudest!

We continue to look forward to addressing the needs and expectations of the Sage partner community and ecosystem.

As a standard disclaimer, any topic in this article is subject to review and doesn’t represent a commitment as to when it will be available.

Sage 300 2019 Web SDK

Introduction

The Sage 300 Web SDK (SDK) is a collection of wizards, utilities, samples and documentation for developing Web Screens for the Sage 300 Application.

This week we released the Sage 300 2019 Web SDK to coincide with the release of the Sage 300 2019 Application.

It’s Available!

The SDK is available at https://github.com/SageNADev/Sage300-SDK.

Branches

As described in a previous blog and in the README file in the root of the repository, the branches contain the different versions of the SDK.

master

Contains the current version of the SDK (2019).

develop

Contains the in-progress version of the SDK (2019.1).

release-…

Contains the previous versions of the SDK (release-2017, release-2017.1, release-2017.2, release-2018, release-2018.1, and release-2018.2)

What’s New

Documentation

Updated documentation is available.

In the docs\upgrades folder is a document for the upgrade procedures for moving partner source from Sage 300 2018.2 to Sage 300 2019. There is a manual step in the upgrade process, so please familiarize yourself with the upgrade steps.

In the docs\development folder you will find a new document for partners wishing to add metadata for the Global Search feature.

The docs\presentations folder has been updated and includes a PowerPoint presentation for what’s new in the SDK for 2019.

In the docs\utilities folder the document for the MergeISVProject utility has been enhanced to include the changes for the new ExternalContent folder.

The DPP wiki has two new articles:

  • KB: 91472 (Using Visual Studio 2017 with the Sage 200 2019 SDK (desktop))
    • This covers issues and information discovered wen Sage moved to Visual Studio 2017 to compile the application and Business Views
  • KB: 91473 (Writing SDK (desktop) applications that do not require “Run As Administrator”)
    • This covers the issue and resolution discovered requiring Sage 300 to be Run As Administrator.

Visual Studio 2017

All wizard manifests have been revised to ONLY include Visual Studio 2017 as a target IDE.

Blog171

Visual Studio 2013 and Visual Studio 2015 are no longer supported targets.

Version Change

The Accpac.Advantage and Accpac.Advantage.Types versions are now 6.6.0.0 and all the AccpacDotNetVersion.props files for the source and samples have been updated.

Blog172.png

Going forward, any changes to the version number will be made in all 5 core libraries. 2018.2 introduced a flaw where a matrix was required to know which version of which library was compatible with another. Thus, by keeping all the libraries at the same version, a compatibility matrix will not be required!

Samples

The samples have been updated with new global references and no longer require the kendo.all.min.js file to be added to each sample prior to compiling.

The web project in all samples has been renamed to include the module in the name and namespace (ValuedParter.TU.Web) to accurately reflect the name of the web project being generated by the solution wizard.

A defect was corrected in the receipt sample regarding Optional Fields. The property ‘YesNoValue’ was renamed to ‘YesOrNoValue” as the Optional Fields framework expects this name.

Solution Wizard

Sage 300 2018.1 introduced vertical menus for navigation. However, the hardcoded images for partner menus were based upon the position of the partner menu (12 hardcoded images for 12 partner menus). It was not ideal, but all the time we had in 2018.1!

Sage 300 2018.2 removed the hardcoded images and replaced them with default images that maybe overridden by the partner who wishes to supply their own images.

However, this implementation was inefficient and not robust to provide the needed framework for third-party images and other files as well.

Sage 300 2019 introduces the ‘ExternalContent’ folder. This folder exists in the Areas\{module} folder and is the location for the 2 required images for partners and is now the location for any user created folders and content files (i.e. images, JavaScript, etc.) that may need to be delivered with the partner module. The previous implementation had limitations if a partner has multiple modules as well as not providing a place for other files and folders.

2018.2 location: ..\Online\Web\External\Images\nav\{companyname}

2019 location: ..\Online\Web\Areas\{module}\ExternalContent

As you can see, the new location in the Sage 300 installation allows for multiple modules per partner and content not specific or related to images or navigation

The 2 required images, menuBackGroundImage.jpg and menuIcon.png, have been renamed to:

  • bg_menu_{module}.jpg
  • icon_{module}.png respectively

These names follow the naming convention of these images used by Sage 300 for our modules. The Upgrade Wizard will rename these images to the new names.

The {module}MenuDetails.XML files will reference the new location of these files:

2018.2 reference:

<IconName>{companyname}/menuIcon.png</IconName>   <MenuBackGoundImage>{companyname}/menuBackGroundImage.jpg</MenuBackGoundImage>

2019 reference:

<IconName>

../../../../Areas/{module}/ExternalContent/icon_{module}.png

</IconName>

<MenuBackGoundImage>

../../../../Areas/{module}/ExternalContent/bg_menu_{module}.jpg

</MenuBackGoundImage>

References to global files were updated and the Crystal Reports components now reference 13.0.3500.0 instead of 13.0.2000.0

An issue was discovered when attempting to debug a report in Visual Studio. There is a requirement where the ‘aspnet_client’ folder and its contents must exist for the solution. The solution wizard will now create this folder and its contents.

Customization Wizards

References to global files were updated.

The Default Compatibility level was changed from 6.5A+ to 6.6A+.

This property is informational only.

Code Generation Wizard

References to global files were updated.

Several defects were addressed this release:

  • Invalid Character in Property Name
    • Replaced ‘%’ if discovered
  • Duplicate Property Name Message
    • Added property name to message for invalid, blank or duplicate field names
  • The ValidRecordFilter Property in Business repository
    • When a zero value or other irregular value is legitimate, this filter may prevent proper CRUD. The filter is still generated by wizard, but is commented out and a TODO statement is generated:

Blog173.png

  • Duplicate Entries in Web Bootstrapper Class
    • Invalid logic was corrected
  • Enumerations in View Model Need Type
    • Enumerations in the web’s ViewModel are used to bind to controls such as the drop-down list. However, the IEnumerable must have a type of CustomSelectList. The wizard now generates the correct code:

Blog174.png

Existing partner code will not be modified as it would have to have been modified for it to work and thus already have been modified

Upgrade Wizard

References to global files were updated and the Crystal Reports components now reference 13.0.3500.0 instead of 13.0.2000.0

The web project will be modified to add the ExternalContent folder (see Solution Wizard section).

The ‘aspnet_client’ folder and its contents will need to be added to the web project if it is not already present and the web project contains reports that wish to be debugged in Visual Studio. See the Upgrade document for manual instructions for locating, copying and adding this folder to the web project.

The MergeISVProject.exe will be updated to reflect a change dealing with Minify JavaScript changes (see MergeISVProject Executable section).

Inquiry Configuration Wizard

This is a new wizard that was to be introduced in 2019, but will be delayed until 2019.1

This is the wizard which will create the metadata required to add or modify scripts used to drive the generic and adhoc inquiry displays.

MergeISVProject Executable

This utility is a post-build utility used by various wizards and the generated partner solution to pre-compile Razor Views and deploy assets to a local Sage 300 installation for developer testing.

An issue was discovered where it did not properly deal with sub-folders. This has been addressed.

Process Unit of Work Enhancement

In previous releases, a base class routine was required to be overridden if a return value or values was needed from a process task (Business View).

Changes in this release have made it easier to return values without overriding a base class routine and instead a base class property is simply overridden. This is explained in detail is the following article: https://jthomas903.wordpress.com/2018/08/21/sage-300-how-to-return-super-view-values-from-the-process-service/

Summary

The Sage 300 2019 SDK is released and ready to be downloaded!

Documentation updates, KB articles, the ability to run the wizards ONLY in Visual Studio 2017, updates and corrections to samples, a new ExternalContent folder, synchronization of global files and references in the wizards, and the ability to easily return values from a process task are in the Web SDK.

Functionality, documentation, tutorials, enhancements, etc. that are not currently in the SDK which should be there to better assist with efficient development practices and time-to-market considerations, please contact the Sage 300 Product Manager. The partners voice and feedback resound the loudest!

We continue to look forward to addressing the needs and expectations of the Sage partner community and ecosystem.

As a standard disclaimer, any topic in this article is subject to review and doesn’t represent a commitment as to when it will be available.

Sage 300 2018.2 Web SDK

Introduction

The Sage 300 Web SDK (SDK) is a collection of wizards, utilities, samples and documentation for developing Web Screens for the Sage 300 Application.

This week we released the Sage 300 2018.2 Web SDK to coincide with the release of the Sage 300 2018.2 Application.

It’s Available!

The SDK is available at https://github.com/SageNADev/Sage300-SDK.

Branches

As described in a previous blog and in the README file in the root of the repository, the branches contain the different versions of the SDK.

master

Contains the current version of the SDK (2018.2).

develop

Contains the in-progress version of the SDK (2019).

release-…

Contains the previous versions of the SDK (release-2017, release-2017.1, release-2017.2, release-2018, and release-2018.1)

What’s New

Documentation

Updated documentation is available.

In the docs\upgrades folder is a document for the upgrade procedures for moving partner source from Sage 300 2018.1 to Sage 300 2018.2. This folder also contains documents for explaining the upgrade steps specific to the Bundle Registration class and the Behaviour JavaScript file.

In the docs\development and docs\wizards folders you will find documents pertaining the wizards and tutorials which have been updated to reflect changes regarding to a …Behaviour JavaScript change.

The docs\presentations folder has been updated and includes a PowerPoint presentation for what’s new in the SDK for 2018.2.

In the docs\utilities folder you will find a document for the new Sage300Utilities utility which is used by the Sage 300 UI Wizard during compilation and an updated document for the MergeISVProject utility which has been refactored and enhanced for JavaScript Minification and Partner Deployment folders.

The samples\customization folder has a new folder called Sample4_AR_Invoice_Entry_Customization containing a new sample and document.

Visual Studio 2017

All wizard manifests have been revised to include Visual Studio 2017 as a target IDE.

This means that when registering the wizards, the registration process will prompt you to select the Visual Studio version for the wizard being registered.

Visual Studio 2013 and Visual Studio 2015 are still supported targets and all three versions can be used for Sage 300 Web Screen development.

Blog122

Samples

The previous samples have been updated with new global references and now reference the common AccpacDotNetVersion.props file in the settings folder.

A new sample has been added to the Web SDK. The AR Invoice Entry Customization Sample illustrates the following:

  • Adding a tab control
  • Enhancing the display via CSS
  • Populating a dropdown list
  • Populating a grid with a method in the Finder!
  • Save, Delete, Update, Grid Refresh

Blog123

Solution Wizard

Minor changes to the wizard to support the updated components and references in the Sage 300 web screens.

Customization Wizards

Minor changes to the wizard to support the updated components and references in the Sage 300 web screens.

Code Generation Wizard

Minor changes to the wizard to support the updated components and references in the Sage 300 web screens.

See the Defects Corrected section for information on the resolved defects

Sage 300 Utilities Executable

This is a new utility for 2018.2 which facilitates the building of template files used by the wizards. This is only relevant if the Sage 300 UI Wizard package is compiled in Visual Studio.

MergeISVProject Executable

This utility is a post-build utility used by various wizards and the generated partner solution to pre-compile Razor Views and deploy assets to a local Sage 300 installation for developer testing.

It has been refactored and enhanced in 2018.2:

  • Minify JavaScript files
    • Now your JavaScript files can be minified when delivered to a customer
    • As of 2018.1, Sage 300 JavaScript files are minified
  • Create deployment folders
    • Helpful for when the partner needs to create an installation for a customer
  • New informative messages in the Visual Studio Output Window
    • Easily see what has been created in what deployment folder

New settings folder in the Web SDK

The new settings folder in the Web SDK now contains a common AccpacDotNetVersion.props file that is used by the wizard and sample source instead of every solution having its own version.

A generated solution will still have its own version as it should no longer reference the Web SDK’s version.

Defects Corrected

  • An error will be encountered in the Code Generation Wizard if a column in a partner model is named “EntityName” as this is the name of a public constant in the Model class. A warning message will prevent the code generation until the column name is changed.
  • Finder code generated by the Code Generation Wizard regarding data type and expressions has been simplified and corrected. Additionally, the …Behaviour.js file, on successful return from a finder selection, was not performing a Get to get the record from the repository and instead used the object returned from the finder. The record returned from the finder is out-of-process and needs to be fetched by the screen. Changes to partner code are only required if a partner’s business view has logic regarding a new record which was incorrectly being invoked by an existing record that “looked like” a new record. This has been corrected. The following shows the previous routine from the Source Code Sample and the new routine:

Previous Logic

setFinderData: function () {

var data = sourceCodeUI.finderData;

sg.utls.clearValidations(“frmSourceCode”);

         ko.mapping.fromJS(data, {}, model Data);

sourceCodeUI.finderData = null;

         modelData.UIMode(sg.utls.OperationMode.SAVE);

         sourceCodeUI.sourceCodeModel.isModelDirty.reset();

         sourceCodeUISuccess.setkey();

},

New Logic

setFinderData: function () {

var data = sourceCodeUI.finderData;

sg.utls.clearValidations(“frmSourceCode”);

sourceCodeUI.finderData = null;

sourceCodeRepository.get(data.SourceLedger, sourceCodeUISuccess.get);

},

The Upgrade Wizard includes a step that indicates that this change is optional and MUST be done manually in existing partner Behaviour JavaScript files. Because manual changes may have been made to this routine since it was generated by the Code Generation Wizard, we are unable to automatically make this change via the Upgrade Wizard.

  • A business view property name of “Type” was previously generated by the Code Generation Wizard as {EntityName}Type.cs. This creates an error in our Optional Fields JavaScript implementation. This has been resolved by generating the model property as “Type” but prefixing the property with the namespace to avoid ambiguous references with the System.Type.
  • Corrected issue where the Next step validated credentials for Code Types that do not use credentials

Images for Partner Menus

Sage 300 2018.1 introduced vertical menus for navigation. However, the hardcoded images for partner menus were based upon the position of the partner menu (12 hardcoded images for 12 partner menus). It was not ideal, but all the time we had in 2018.1!

Sage 300 2018.2 has removed the hardcoded images and replaced them with default images that maybe overridden by the partner who wishes to supply their own images.

The {module}MenuDetails.xml has been enhanced with two new elements that are supplied via the Sage 300 UI Wizard. The elements are: IconName and MenuBackGroundImage:

<IconName>ValuedPartner/menuIcon.png</IconName>   <MenuBackGoundImage>ValuedPartner/menuBackGroundImage.jpg</MenuBackGoundImage>

Where ValuedPartner is the name the partner supplied in the UI Wizard

  • The IconName element defaults to the “puzzle piece” image
  • The element value is added as $companynamespace$/menuIcon.png
  • The MenuBackGroundImage defaults to the “discussion” image
  • The element value is added as $companynamespace$/menuBackGroundImage.jpg

Blog124

The MergeISVProject utility is the post-build event utility that deploys your solution to the developer’s local installation of Sage 300 when your solution is in Release Mode. It copies these files (menuIcon.png and MenuBackGroundImage.jpg) from your web project’s Content\Images\Nav folder to the External\Content\Images\Nav\$companynamespace$ folder of your local Sage 300 installation.

Therefore, in your web project’s Content\Images\Nav folder is where your will place your partner images (named menuIcon.png and menuBackGroudImage.jpg) and overwrite the existing files.

Summary

The Sage 300 2018.2 SDK is released and ready to be downloaded!

Documentation updates, the ability to run the wizards in Visual Studio 2017, a new AR Invoice Entry Customization sample, minification of JavaScript files, enhanced deployment folders, and the ability to specify partner images for the vertical menus are all in the Web SDK.

We continue to look forward to addressing the needs and expectations of the Sage partner community and ecosystem.

As a standard disclaimer, any topic in this article is subject to review and doesn’t represent a commitment as to when it will be available.

 

Sage 300 2018.1 Web SDK

Introduction

The Sage 300 Web SDK (SDK) is a collection of wizards, utilities, samples and documentation for developing Web Screens for the Sage 300 Application.

This week we released the Sage 300 2018.1 Web SDK to coincide with the release of the Sage 300 2018.1 Application.

It’s Available!

The SDK is available at https://github.com/SageNADev/Sage300-SDK.

Branches

As described in a previous blog and in the README file in the root of the repository, the branches contain the different versions of the SDK.

master

Contains the current version of the SDK (2018.1).

develop

Contains the in-progress version of the SDK (2018.2).

release-…

Contains the previous versions of the SDK (release-2017, release-2017.1, release-2017.2 and release-2018)

What’s New

Documentation

Updated documentation is available.

In the docs\development folder you will find documents which have updated screenshots in the setup and tutorial documents to reflect the new flow of the Code Generation Wizard.

In the docs\patterns folder you will find a new document for Coding Patterns. At this time, only one pattern is documented, but will soon contain more patterns implemented in the Sage 300 Web Screens.

The docs\presentations folder has been updated and includes a PowerPoint presentation for what’s new in the SDK for 2018.1.

In the docs\templates folder you will find the updated Word Template used by our PDX Content group.

In the docs\upgrades folder is a document for the upgrade procedures for moving partner source from Sage 300 2018 to Sage 300 2018.1. This folder also contains a document for manually upgrading a customization solution’s controller to inherit from our MultitenantControllerBase class instead of Microsoft’s Controller class.

In the docs\wizards folder you will find documents which have updated screenshots to reflect the new flow of the Code Generation Wizard and the new HeaderDetail Code Type.

Visual Studio Code Maps

Visual Studio Code Maps have been provided for specific entities, controllers, utilities and helper classes.

In the maps folder you will find various code maps which can be opened in Visual Studio to see a graph of relationships in specific classes.

Blog11CodeMap

Samples

The previous samples have been updated with new references and minor corrections.

The Receipt sample has been re-factored to use the new base class and implementation for HeaderDetail code type.

Solution Wizard

Numerous changes to the wizard to support the updated components and references in the Sage 300 web screens.

Customization Wizards

Numerous changes to the wizard to support the updated components and references in the Sage 300 web screens.

The Customization Wizard Plugin was modified to generate a controller inheriting from Sage’s MultitenantControllerBase instead of Controller. See the document in the docs\upgrades folder for manual steps.

Code Generation Wizard

Numerous changes to the wizard to support the updated components and references in the Sage 300 web screens.

The new HeaderDetail code type generates enough code to have a functioning header-detail screen that compiles and can be run. However, in this initial offering, a grid (main component of a header-detail screen) is not generated by the wizard. This is being planned for the next release of the SDK!

Blog11Step1

The flow of the wizard has been enhanced to support the new HeaderDetail code type with multiple entities (Accpac Business Views). Information that is relevant to all entities has been moved to the first step.

 

Blog11Step2A tree control has been added to the second step for adding, editing and deleting entities. The tree control displays and allows for hierarchical entities as required by the HeaderDetail code type.

 

Blog11Step2aThe Entity tab of the second step allows selection of the entity and editing of the properties.

Blog11Step2bThe Options tab of the second step allows selection of assorted options.

 

Blog11Step2cThe Properties tab of the second step allows for manual entry of properties for the DynamicQuery and Report code types. It now allows for the modification of property names before the code is generated for the other code types as well.

 

Blog11Step2dThe Compositions tab of the second step is only relevant for the HeaderDetail code type and allows for the compositions of the entity to be included or not. The wizard will generate the composition logic in the CreateBusinessEntities routine of the Repository class.

 

Blog11Step3

The third step has been refactored to display an XML representation of what will be generated by the wizard.

WebApi

A new GL Segments endpoint has been added.

Defects Corrected

The module name for a development partner’s menu item was not being localized when displayed in the window manager. This has been resolved.

An error might be encountered in the Clear Statistics sample. This has been resolved.

Vertical Menus

There are no code or menu changes required for the new Vertical Menus of the Sage 300 web screens. A default icon (colored puzzle image) will be assigned to a partner’s menu item.

In 2018.2, we are modifying this implementation to allow the partner to specify an icon they want to associate with their menu in the menu XML. The partner will then be required to deliver this icon along with the other module assemblies.

Blog11VerticalMenus

Summary

The Sage 300 2018.1 SDK is released and ready to be downloaded!

Documentation Updates, new Visual Studio Code Maps, a new Code Generation Wizard flow along with a new HeaderDetail Code Type, updated Samples, and a new WebApi endpoint are all in the SDK.

We continue to look forward to addressing the needs and expectations of the Sage partner community and ecosystem.

As a standard disclaimer, any topic in this article is subject to review and doesn’t represent a commitment as to when it will be available.

 

Sage 300 Optional Resource Files

Introduction

The Sage 300 Web Screens use Resource Files (Resx files) to localize strings, text, captions, messages, etc. that are presented in the screens. Behind the scene, these Resx files are supported by Microsoft’s Resource Manager class and framework.

So, what happens if a Resx file for a language is not provided or blank values exist in a Resx file?

Supported Languages

Before we begin, let’s identify the languages that are currently supported in the Sage 300 Web Screens:

  • English (en-US) (i.e. MenuResx.resx)
  • Chinese Simplified (zh-Hans) (i.e. MenuResx.zh-Hans.resx)
  • Chinese Traditional (zh-Hant) (i.e. MenuResx.zh-Hant.resx)
  • Spanish (es) (i.e. MenuResx.es.resx)
  • French (fr-CA) (i.e. MenuResx.fr-CA.resx)

English is considered the default language and all Resx files without a locale extension are to be considered the English Resx files.

The Sage 300 PDX Group takes the completed English Resx files and translates the values into the other supported non-English languages.

How Does It Work?

The Sage 300 Web Screen implementation is to place the Resx files for the same screen into the same folder.

This is a requirement for the Resource Manager magic!

These resource files are referenced with a standard Object.Property notation and do not specify a locale. The magic is performed by the Resource Manager to understand the current locale and retrieve the string (property) from the correct Resx file based upon the locale.

This is very convenient from a code perspective in that the application code does not have to determine which Resx file to access.

Non-existent Resx File for a Locale

If a specified locale’s Resx file does not exist, the English Resx file is used instead. Since the code does not specify a locale, this default behavior by the Resource Manager is perfect and the resulting English resource allows the application to function without error.

Blank Values in a Resx File and Resulting Issue

A blank value is a value. It is just blank. But, this can cause issues in the application when a value is retrieved from any Resx file, not just non-English Resx files, and then the value is displayed on the screen. Where is my caption? Where is my menu item? Where is my message?

As mentioned in the previous section, a missing non-English Resx file will default to the English Resx file so there is no loss in functionality or behavior.

But, it was recently observed by a partner, that the Solution Wizard and Code Generation Wizard will generate the Menu Resx files and any screen Resx files for all supported languages. But, the values in these non-English Resx files will contain keys, but blank values, which is perfect for Sage internal developers, but in many cases not ideal for external developers.

Example 1: English Resx File

blob10example1

Example 2: French Resx File

blog10example2

External developers must also fill out these files to avoid having a Sage 300 supported locale selected by the customer, but now the screens and menus will display blank or key values (in the case of the menu system, it has explicit logic that states “if the localized menu value is blank, display the keys instead”). This behavior then places the burden on the partner to delete these non-English Resx files IF the partner does not intend to support the translation of a particular language.

Resolution to Blank Values in a Non-English Resx File

Blank values in an English Resx file must be resolved to contain a value. This is plain and simple in order to avoid any issues in the display.

Blank values in a non-English Resx file can be resolved in one of two ways:

  • If the partner is intending to support their screen in a Sage 300 supported locale, the locale’s Resx file must be translated with proper values
  • If the partner is not intending to support their screen in a Sage 300 supported locale, the locale’s non-English Resx file can simply be deleted from the project while in the Visual Studio IDE.

But, regarding the deletion of the non-English Resx file, what if it was never created in the first place? Yes, this is a better option!

Sage 300 Solution Wizard’s New Feature

If the partner is able to determine when creating the solution and projects that a Sage 300 supported language will not be supported by their screens (i.e. a partner in Asia may not want to provide Spanish and/or French for their screen), the Wizards should not create the non-English Resx files in the first place.

Therefore, an enhancement has been made to the 2017.2 version of the Sage 300 UI Wizards (Solution Wizard and Code Generation Wizard) to prompt the developer for the language Resx files to be included/created in the projects of the solution.

blog10newstep

This new step has been added to the Solution Wizard in order to allow the developer to decide which language Resx files to include/create.

English is defaulted as it is a requirement.

Sage internal developers will select all of the languages.

The Code Generation Wizard will not prompt again for this, but instead will look at the Menu Resx files that exist and when creating Resx files for the specific screen, will create the language files based upon this discovery.

If a new solution is being generated starting with release 2017.2, this ability to limit or restrict what is created is a welcome new feature.

For partners with solutions and projects created prior to release 2017.2, the Code Generation Wizard will discover the Menu Resx files and create the non-English Resx files accordingly. Therefore, if a particular locale’s Resx files exist and they are not required to be translated, deleting the MenuResx.{locale}.resx file(s) from the Resources project will need to be performed.

Summary

This article presented how the Sage 300 Web Screens implement the Microsoft Resource Manager, what happens when a locale’s Resx file is missing, what happens when a locale’s Resx file has blank values and the steps required to avoid “blank value” issues.

The Sage 300 Solution and Code Generation Wizards have been enhanced for the 2017.2 release (April 2017) to present a new step which allows for the selection of which non-English Resx files are to be included/generated. This new step is a proactive approach to not creating locale Resx files that are not used by the partner and therefore preventing display issues if a customer selects a Sage 300 supported language that is not supported by a partner screen.

As a standard disclaimer, any topic in this article is subject to review and doesn’t represent a commitment as to when it will be available.

Sage 300 JavaScript Bundle Names

Introduction

JavaScript Bundling is a technique that can be used to improve request load times. The Sage 300 Web Screens use this technique to bundle the required JavaScript files on a per screen basis.

Known Issue

There is a known issue that bundle names with a dot will generate a 404 error condition in certain situations. While the Sage 300 bundle names do not have a dot in the bundle name, it was recently discovered that the code generated by partners by the Code Generation Wizard might include a dot.

Remember that the bundle name is separate from the JavaScript file name which can contain a dot.

Manual Resolution

For any existing projects, the change is quite simple and must be performed in two locations: The Bundle Registration class where the bundle is registered and in the Index Razor View where the bundle is referenced.

Example 1: BundleRegistration.cs (Before and After)

blog8example1before

Blog8Example1After.png

Example 2: Index.cshtml (Before and After)

Blog8Example2Before.png

Blog8Example2After.png

Summary

This article presented a known issue with a dot being in the name of a JavaScript bundle, the potential existence of this issue in code generated by the Sage 300 Web Code Generation Wizard, and the steps required to resolve this issue.

The Sage 300 Code Generation Wizard has been modified for the 2017.2 release (April 2017) of the Web SDK to prevent this issue from being present in any newly generated code.

As a standard disclaimer, any topic in this article is subject to review and doesn’t represent a commitment as to when it will be available.

Sage 300 2017.1 Web SDK

Introduction

The Sage 300 Web SDK (SDK) is a collection of wizards, utilities, samples and documentation for developing Web Screens for the Sage 300 Application.

This week we released the Sage 300 2017.1 Web SDK to coincide with the release of the Sage 300 2017.1 Application.

It’s Available!

The SDK is available at https://github.com/SageNADev/Sage300-SDK.

This SDK has been previously made available via Sage’s DPP portal. However, starting with this release, we are only making the download of the SDK available via GitHub. It did not make sense to have almost identical downloads available from two different sources.

Branches

As described in a previous blog and in the README file in the root of the repository, the branches contain the different versions of the SDK.

master

Contains the current version of the SDK (2017.1).

develop

Contains the in-progress version of the SDK (2017.2).

release-2017

Contains the previous version of the SDK (2017).

What’s New

bin Folder

Now that we have a single download of the SDK, the previous version of the SDK, via GitHub, did not include the bin folder, which was included in the DPP download. The bin folder contains the assemblies generated by the wizards and utilities source.

This subtle addition allows the wizards and utilities to be used without first compiling the source for the wizards and utilities.

Documentation

Updated documentation is available.

The docs\presentations folder has been added and includes a PowerPoint presentation for what’s new in the SDK for 2017.1.

In the docs/development folder you will find two new documents. The first document is Sage 300’s updated brochure which highlights the benefits of the Sage 300 Software Architecture. The second document explains in detail the Worker Processing and Workflow Engine.

In the docs\customization folder are documents for the Customization Overview along with file specification for the XML and JSON files in the customization package.

In the docs\webapi folder are documents for the WebApi Endpoints and instructions for the WebApi Postman samples.

In the docs\upgrades folder is a document for the upgrade procedures for moving partner source from Sage 300 2017 to Sage 300 2017.1.

Customization

The SDK now provides a wizard, samples and documentation for the ability to customize a Web Screen. The bin\wizards folder contains the Sage300UICustomizationSolution.vsix plugin for Visual Studio, the docs\customization folder contains the documentation for the customization strategy, and the samples\customization folder contains three different samples illustrating how to customize a Web Screen.

Samples

The previous samples have been updated with new references and minor corrections.

The Clear Statistics sample has been added and is an example of the Process Type for Web Screens. This sample provides a working example of the A/R Clear Statistics screen along with the SQL required to participate in the Sage 300 Workflow Engine.

Three customization examples have been added and they use the OE Order Entry Screen, the OE Copy Orders Screen and the CS Tax Authorities Screen to illustrate the new customization abilities.

A new WebApi sample was added to illustrate integration and includes documentation and Postman collections.

Component Updates

Several core components were updated this release: Kendo UI (2016), Azure SDK (2.8) and the Target Framework (4.6.2).

Workflow Engine Enhancements

In order to facilitate participation with partner’s process screens, the Workflow Engine required an enhancement to ensure that partner process screens would not interfere with Sage processes or other partner processes. Therefore, integer fields were changed to GUID fields, enumerations changed, Landlord Database Tables modified and even the discovery location of SQL scripts were enhanced to facilitate successful integration with partner process screens.

Solution Wizard

Numerous changes to the wizard to support the updated components and references.

Code Generation Wizard

Numerous changes to the wizard to support the updated components and references.

The Process Type has been completed to generate a Process Screen will all of the required components in order for it to be compiled. A SQL file is generated that can be used to update the Landlord Database Workflow tables (via Portal button in the Database Setup Screen).

While the process screen is able to be compiled, it still requires manually completion to be functional.

WebApi

Several significant changes to the WebApi have been made, such as, an OData upgrade, support for the PATCH verb, Versioning, added endpoints, and Open API (Swagger).

 

Summary

The Sage 300 2017.1 SDK is released and ready to be downloaded!

Component Updates, new Customization Framework, new Samples, Processing enhancements and WebApi features and enhancements are all in the SDK.

We continue to look forward to addressing the needs and expectations of the Sage partner community and ecosystem.

As a standard disclaimer, any topic in this article is subject to review and doesn’t represent a commitment as to when it will be available.

Implementing an External Finder

Introduction

The following question was recently asked:

I am a developer working in my Sage assigned module and I need to invoke a finder from one of the standard Sage modules (i.e. AR, AP, GL, etc.). How do I do this?

This article will illustrate the steps required to invoke a finder from a module other than what is currently being developed.

Example

To illustrate the steps involved in adding a finder from another module, I have run the solution and code generation wizards and have created the TU Payment Codes setup screen. This screen is based upon the AR Payment Codes business view (AR0012) and only contains the key field and finder as generated from the wizards. For this example, I am going to want a finder for a vendor (just because it’s from another module).

Blog2Figure1

Step One

In this step, I need to locate the name for the Vendor Finder. The finder name is a descriptive field used to register the finder with Unity for dependency injection. The name is found in the Sage.CA.SBS.ERP.Sage300.Common.Plugin.Finder.js file. This file is located in the Areas\Core\Scripts folder of the Web project:

Blog2Figure2

This JavaScript file contains sg.finder object with the name definitions:

Blog2Figure3

The value “vendor” as this will be used later in the setFinder method.

Step Two

In this step, I need to add the required references to the AP binaries in the Web project in order for the finder to be invoked.

Finders for all modules have already been registered with Unity.

The AP binaries are located in your Sage 300 Online\Web\bin folder.

The following binaries will be added if they do not exist or have not been previously added:

Blog2Figure4

Step Three

In this step, I will add the controls to the razor view.

This example will not be bound to the data model as it is only being added to demonstrate invoking another finder and not data binding

Blog2Figure5

Step Four

In this step, I will add the required localization variables to the _Localization.cshtml partial view.

Blog2Figure6Untitled.png

Step Five

In this step, I will add the code to the JavaScript Behaviour file for this screen in order to setup and invoke the finder:

InitFinders:

Blog2Figure7finderSuccessVendor:

Blog2Figure8.pnggetFilterVendor:

Blog2Figure9.png

Step Six

Mission accomplished!

Blog2Figure10.png

 

Blog2Figure11.png

Summary

This article was meant to present the steps required to display a finder from another module not currently being developed. Since the finders are already registered via Unity in the Sage 300 application, the work involved is simply to locate the finder name, ensure the binaries for the finder’s module is added to the Web project and to hookup the plumbing in the JavaScript file.

As we begin to implement the customization framework, we will investigate the notion of externalizing the Unity Registrations into external XML files and therefore the discovery performed in Step One of this article will be simplified.