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.

Advertisements

Sage 300 Compiling Web Screens in Release Mode Tip

Introduction

When developing Web Screens for Sage 300, a developer typically compiles and runs in Debug mode within the Visual Studio IDE.

Changing to Release mode and compiling the solution performs an additional step which is to deploy or copy the required assemblies and files to the developer’s local Sage 300 installation. This is beneficial for the developer to see the screens running via the Sage 300 homepage.

This deployment or copy is performed by the post-build event utility MergeISVProject.

But, the files may be locked by another process. This article will explain who has these files locked and the steps required to successfully compile in Release mode or manually copy files.

Why are my files locked?

Files are targeting the Web folders will be copied without issue, while the files in the Worker folder will most likely be held by our worker service. This service is responsible for managing the worker role for the Sage 300 Web Screens.

This is the reason that a compile in Release mode or a manual copy of files to the Worker folder may not be successful.

Blog131

How do I unlock my files?

Stopping our worker service, compiling in Release mode or copying of files and then re-starting the worker service is the best and simplest way to resolve this issue.

Stop the Worker Service

Invoke the Services Desktop Application and scroll down to the Sage.CNA.WindowsService:

Blog132

Double-Click the service and select Stop:

Blog133

Compile in Release Mode or Manually Copy Files

When the developer solution is compiled in Release mode or files are manually copied, with the Sage.CNA.WindowsService stopped, the copy process will not run into a lock or contention scenario.

Re-start the Worker Service

To re-start the service, select Start:

Blog134

Summary

This article explained why a compile in Release mode or a manual copy of files to the Worker folder for the Sage 300 Web Screens may run into a locked or contention scenario.

The copy process will not encounter an issue if the Sage.CNA.WindowsService is stopped.

And, don’t forget to re-start the service after the compile or copy is successful!

Finally, after any file is updated in either the Web or Worker folders it is always good practice to perform an IIS Reset of the Default Web Site.

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.