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.

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.

 

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:

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:

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:

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

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:

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:

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:

Multiple Sessions

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

• 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

• 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:

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 How to Debug into a Business View from a Sage 300 Web Screen

Introduction

Some developers may already know how to debug into your C/C++ Accpac Business View while debugging/running your module’s Sage 300 Web Screen. But, for those who do not, this little tip is very handy.

This tip allows you to debug into your Accpac Business View (where you have the source) and from your module’s Sage 300 Web Screen.

Debugging in the IDE

You have your solution loaded in the Visual Studio IDE and when you debug, you want to debug all the way down into your C/C++ Accpac Business View.

In your solution, right-click on the Web project and select the Properties menu option:

Click on the Web tab page and notice the Native Code checkbox at the bottom in the Debuggers section:

Select this checkbox and Save the changes.

This will allow you to debug into your native C/C++ code.

Debugging in IIS

The previous section showed how you can debug into native code while debugging your web screen. But, what if you want to debug into native code while your screen is not running in debug (meaning it is running in IIS)?

Launch Visual Studio and be sure to Run as administrator

From the Debug menu, Select Attach to Process…:

In the Attach to Process popup, be sure to Select the show processes from all users checkbox. Look for the w3wp.exe and Click on it.

There may be multiple w3wp.exe’s listed and it is important to select the correct one. If the user is listed as IIS APPPOOL\…, this is NOT the correct one as it is an IIS executable not running Sage 300.

Once the correct w3wp.exe is highlighted, Click on the Select button:

In the Select Code Type popup, Select the Debug these code types: option and Select the Managed (v4.6, v4.5, v4.0) and Native checkboxes and Select the OK button:

This will allow you to debug into your native C/C++ code. 

Summary

This article explained how to debug into native C/C++ code when debugging your Web Screen solution in Visual Studio and also how to attach to an IIS process to debug into native C/C++ code if the Web Screen is running (not in debug mode).

Happy debugging.

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 How to Create a Class in Visual Studio from JSON

Introduction

Some developers may already know how to create a class from JSON metadata. But, for those who do not, this little tip is very handy.

I’ll use the Sage 300 Web API and create classes based upon the ARCustomers endpoint. Of course, this also possible with any JSON metadata, but since this is a Sage 300 blog, using Sage 300 metadata feels right.

I give credit for this tip to Vega and I’m simply providing an illustrated example in this article. Thanks Vega!

Sage 300 Web API

The Sage 300 Web API is a great source for JSON metadata since the payloads are JSON. And, since the Web API has implemented the Swagger UI, it is even easier to access the metadata.

The first step is to access the Swagger UI. This is accomplished by navigating to your Sage 300 Web API and accessing the Open Swagger UI button:

After the Swagger UI has loaded the endpoints, scroll down to the ARCustomers endpoint and click on it to expand the available actions:

Click on the first GET action to expand the UI. In the Model Schema section, you will see the metadata for the ARCustomers payload. Copy this entire section:

Now, we have the JSON metadata in our buffer. It is time to move onto Visual Studio to create some C# classes based upon this metadata!

Visual Studio

In this example, I will be using Visual Studio 2017 and C#.

Open Visual Studio 2017 and Create a new class called ARCustomers:

Before we paste the contents of the buffer, delete the 3 lines for the ARCustomers class, which are indicated by the arrow in the image above:

We are now ready to paste our JSON. From the Edit menu, select Paste Special –> Paste JSON As Classes:

That’s it! Well, almost. 😊 As you can see, we now have C# classes that follow the hierarchy of the JSON metadata. It is very easy to see the hierarchy as well as all the column names:

The Paste Special feature names the top class Rootobject and the first or main class is named value. It makes more sense that they are named ARCustomers and ARCustomer respectively:

Tip

The arrays should be changed to IList especially when dealing with optional fields.

Summary

This article explained how to create C# classes in Visual Studio 2017 from JSON metadata that was copied from the Sage 300 Web API ARCustomers endpoint.

Any copied JSON metadata can use the Paste Special feature in Visual Studio to create classes based upon the JSON. I used the Sage 300 Web API as an example of metadata that will create several classes based upon the JSON.

Thanks again Vega for the tip!

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.

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.

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:

• 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:

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 Trouble Installing Visual Basic 6.0 on Windows Server 2012/2016

Introduction

The Sage 300 SDK, not Web SDK, requires Visual Basic 6.0 SP6 to be installed on the computer. But, what happens when that computer has Windows Server 2012/2016 and there are compatibility issues when attempting to install Visual Basic 6.0?

This article will show how to get Visual Basic 6.0 successfully installed.

Solution

While this solution might not work for all, it has worked for Sage 300 developers.

Simply uncheck the Data Access Components option during the installation:

That’s it!

References

If more information is required or if the actual steps needed to install Visual Basic 6.0 on Windows Server 2012/2016 (and even Windows 10) are required, please refer to the following links:

https://stackoverflow.com/questions/30656303/vb-6-data-access-component-installation-on-windows-2012-server

http://donovanbrown.com/post/Build-Visual-Basic-60-applications-with-Visual-Studio-Team-Services

https://www.codeproject.com/Articles/1191047/Install-Visual-Studio-on-Windows

Summary

This article explained how to install Visual Basic 6.0 on Windows Server 2012/2016 by unchecking the Data Access Components option.

Reference links are provided if more information is required.

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 How to Return Super View Values from the Process Service

Introduction

So, you are developing Web Screens for Sage 300 and you want to be able to check a field value or some field values that are returned from the super view. In the Sage 300 Desktop, which is based upon the Visual Basic 6.0 development environment, this is simple and straight-forward.

But, how is this done in the Web Screens where the process is handled by a Worker Role?

This article will explain how this is accomplished by looking at our Sage 300 Web Screen Payment Batch Unit of Work (UOW) service implementation as an example.

Process Flow

But, before we begin, let’s briefly review the Web and Worker Roles as they relate to a Process task.

The Sage 300 Web Architecture uses both web and worker roles to serve the functionality of the web screens. Worker roles are used for most long running processes, usually indicated by a progress-meter, and some reports.

The above diagram illustrates the flow once a process screen submits or starts the process.

Because the super view is handled and processed in the worker role, the business view (which is mapped to an MVC model) is not returned to the web role to access the required values.

Process UOW Service

The Process UOW Service is the class that invokes the Process Repository where the super view’s Process function is invoked and hydrates a model upon return from the function.

var model = repository.Process(seedEntity.Model);

But, this model is in the worker role and the model is not serialized back to the web role.

Process Result’s ResultObject

The ResultObject in the ProcessResult object will contain the value or values that you will want to return to the web role. But, you must place what you want in this object since we do not serialize the model into this object (hindsight says we should have!).

Prior to Sage 300 2019, the setting of the ResultObject was done by the developer by overriding the Process UOW’s OnExecute base class method. The following routine is from our 2018.2 implementation of the Payment Batch UOW class:

While overriding this base class method effectively was able to access and set the ResultObject, it also needlessly had to implement a lot of other code.

Sage 300 2019 eliminated the need to override the OnExecute base class method by providing an override method which provides the ability to set the ResultObject without re-implementing the base class method. The overridden OnExecute was deleted in the Payment Batch UOW class and replaced with an override to the GetResultObject method instead:

Back in the Web Role

At the completion of the process, control is returned to the screen’s JavaScript callback function onProcessComplete. If the ResultObject was set in the Process UOW Service’s override method GetResultObject, it is now available in this callback event:

Summary

This article explained how to return a super view value or values from a process service in the Sage 300 Web Screens.

As indicated in the XML Comments for the GetResultObject virtual method, since this is a single object and not an array or dictionary, if multiple values are required, use the pipe symbol as separator to concatenate multiple fields.

The GetResultObject is a virtual method that can be overridden in the Process UOW service class to return a value or values from the worker role to the web role.

The onProcessComplete JavaScript callback function is invoked at the completion of the process and the ProcessResult.ResultObject is available for the developer with any values that may have been set in the worker role. By default, the ResultObject is null.

So, not as simple as the desktop implementation, but still doable with a few extra steps!

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 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.

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:

Double-Click the service and select Stop:

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:

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.

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

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

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.

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!

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.

 

A 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.

 

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

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

 

The 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.

 

The 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.

 

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.

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 and Visual Studio’s Code Maps

Introduction

The Sage 300 web screens are comprised of 113+ Visual Studio projects. This represents a large and complex code base. Simply opening a project and viewing the components and references to understand the relationships and dependencies can be a daunting task.

The relationships and dependencies between not only projects but also classes and methods are sometimes best understood when presented visually.

Microsoft’s Code Maps, which is a core feature of Visual Studio 2013 Ultimate and Visual Studio 2015/2017 Enterprise Editions, is a fantastic tool to assist with the visualization of these relationships and dependencies.

ReSharper, which all internal Sage 300 developers use, also offers a graphical code mapping feature. However, the features, functionality and even the debugging integration with Code Maps make Visual Studio tool, in my opinion, the best tool to use.

This post will introduce the Visual Studio Code Maps and present how developers can leverage this tool to graphically display relationships and dependencies for a project or projects, a class or a method. Code Maps can assist not only new developers, who do not know anything about the code base, but also experienced developers wanting to better understand relationships and dependencies.

Code Maps

Code Maps is an architectural tool in Visual Studio that generates a graph, like a dependency graph, to assist the developer with understanding and viewing the relationships and dependencies of a large code base in a visually appealing, dynamic and interactive graphical display.

A code map visualizes code and project relationships and can even be viewed in a tab next to the code editor inside of Visual Studio. This allows the developer to see where they are in the map and therefore in the hierarchy of the code while in the code itself.

A code map may be saved within the solution or even exported as an image to email or an XPS viewer. While inside Visual Studio, the code map is interactive:

• Add or remove or hide components in map
• Add or remove filters which control relationships (Class, Methods, Call, References, Calls, Returns, etc.)
• Add comments to a component or relationship
• Double-click component to be taken to that place in the code
• etc.

While all versions of Visual Studio can access (read-only) a Code Map, only the following versions of Visual Studio can create a Code Map:

Visual Studio 2013 Ultimate Edition and Visual Studio 2015/2017 Enterprise Edition

Example

In this example, I want to better understand the A/R Payment Code’s business repository located in the A/R Business Repository project of the A/R solution. I want a visual graph which Visual Studio’s Code Maps feature can generate.

Let’s start by creating a map for the Payment Code Repository. Open the PaymentCodeRepository class and Right-Click on the name in the code window and select the Show on Code Map option:

Figure 1: Generate code map for class

The code map for the class will be generated with a green chevron indicating where in the code the code window is:

Figure 2: Generated code map for class

Hover over the code map and select the dropdown chevron to retrieve the components in this class:

Figure 3: Retrieve components of class

The components (methods, properties, etc.) of the class are retrieved and added to the code map:

Figure 4: Components in class

We can visually see all the methods and properties in the class. I’m interested in the GetAccessRights method, the methods that this routine invokes, and where they are located. Rick-Click on the GetAccessRights component in the code map and select the Show Methods This Calls option:

Figure 5: Show methods

Note that the code map window is side by side with the code window.

Upon showing the methods that are called from this routine, you will notice that they are coming from an external assembly or assemblies:

Figure 6: Method calls are in external assembly(s)

Hover over the External component and select the dropdown chevron to retrieve the components in this class:

Figure 7: Retrieve and show assembly(s)

The external assembly is now shown:

Figure 8: External methods are in the Common BusinessRepository assembly

Hover over the external assembly and select the dropdown chevron to show the methods:

Figure 9: Retrieve and show methods

The methods are in a folder within the assembly (namespace):

Figure 10: External methods are in the BusinessRepositoryBase namespace

Hover over the external assembly and select the dropdown chevron to show the methods:

Figure 11: Retrieve and show methods

We are getting closer! We can see now that the methods are in two different classes:

Figure 12: External methods are in the BaseRepository and FlatRepository classes

Hover over the two classes and select the dropdown chevrons to show the methods which results in our final display:

Figure 13: PaymentCodeRepository showing external reference and methods

We wanted to see where the GetAccessRights and SecurityCheck methods were located and Code Maps provided a visual graph in just a few steps.

Figure 14: GetAccessRights routine in the PaymentCodeRepository

Code Map Toolbar

Figure 15: Code Map Toolbar

The Code Map Toolbar provides numerous options that can be undertaken on the code map:

• Undo
  • Undo recent changes to the code map
• Show Related
  • Context items for acting on the selected component, such as Find All References, Show Methods This Calls, etc.
• Layout
  • Context items for how the code map is displayed, such as Top to Bottom, etc.
• Find
  • Find feature
• Call Stack
  • Automatically show debugger call stack on Code Map
• Share
  • Collaboration options, such as Copy Image, Email as Image or Portable XPS (to be viewed in XPS viewer), Save as Portable XPS, Save as DGML, Move DGML (once saved) into a folder/project within the solution, etc.
• Comment
  • Add comment to the code map
• Zoom
  • Zoom to fit the code map window or enter a zoom percentage (mouse wheel also controls zooming in and out)
• Legend
  • Toggle to display window of icons and icon descriptions of icons
• Filters
  • Toggle to display window of filters available for selection and de-selection
• Skip Build
  • Toggle to determine if code map should build solution before generation of code map
• Include Parents
  • Toggle to determine if code map should include parents of components to be generated

Summary

The Sage 300 web screens represent a large and complex code base where understanding and viewing the components, relationships and references can be a daunting task.

Microsoft’s Code Maps, which is a core feature of Visual Studio 2013 Ultimate and Visual Studio 2015/2017 Enterprise Editions, is a tool that provides the ability to visualize relationships and dependencies in real time from within the Visual Studio IDE.

To create a Code Map you must be on either Visual Studio 2013 Ultimate Edition or Visual Studio 2015/2017 Enterprise Edition.

Developers can leverage this tool to graphically display relationships and dependencies for a project or projects, a class or method. A simple example was used to provide a graph of a class and its externally referenced method calls.

The graphs can be used at an elevated level to show project relationships or a detailed level to show code flow and dependencies. This visualization is a proven way to understand complex concepts, and understand and navigate complex 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.