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 Date Utility

Introduction

Microsoft’s DateTime Structure is an object that represents an instant in time, typically expressed as a date and time of day.

In Sage 300’s Web Screens, we use this object for dates and times in our C-Sharp code. However, we do not use its numerous properties and methods directly. Instead, we have encapsulated this functionality in our DateUtil class.

Let’s me explain why we came to the decision to encapsulate this functionality.

Encapsulation and Technical Debt

But, first let’s cover some concepts that were at the core of our decision.

What is encapsulation?

Encapsulation is the ability to provide users with a well-defined interface to a set of functions in a way which hides their internal workings.

Benefits of encapsulation

One of the principles of encapsulation is that the internal representation of an object should not concern its consumers. It also hides complex mechanisms and provides code reduction.

What is technical debt?

Technical debt is the set of problems in a development effort that make progress on customer value inefficient.

What does technical debt look like?

Technical debt are problems found through code analysis, duplicate code patterns, code complexity, spaghetti code, …

Encapsulation Decision

We analyzed the code and determined that individual usage of the DateTime properties numbered in excess of ten thousand lines of code. Yikes.

Sage 300 Web Screens can be localized and therefore these lines of code had to specify a locale along with the necessary conditional logic.

And, unfortunately we had different patterns being implemented in those individual lines of code.

So, the decision to encapsulate and to create a single design pattern for the developers to access a date and time was the best choice.

Date Utility Class

Thus, the DateUtil class was created and is available in the Sage.CA.SBS.ERP.Sage300.Common.Utilities assembly.

dateutil

Why should I use this class?

  • Sage 300 Web Screen Date and Time Pattern
    • Let this class do the date validations, acquire a new date, perform conditional checks, etc. for you
    • It’s the standard for Sage 300 Web Screen developers
  • Minimum Date logic is centralized
    • The DateTime structure has different values for the minimum date value based upon how the object was instantiated
    • The DateUtil class has the ability to standardize on a single minimum date value and therefore the application will not have multiple minimum date possibilities
  • Formatting based upon Current Culture
    • The encapsulation allows for the DateUtil class to perform the culture specific logic
    • This eliminates the developer from having to specify this where required
  • It’s easy and does the work for you
    • Enough said on this!

Before and After Examples

In this section, I will show some examples where we replaced code in our application with usage of the DateUtil class.

Example 1: Before

before1

Example 1: After

after1

Example 2: Before

before2

Example 2: After

after2

Example 3: Before

before3

Example 3: After

After3.png

Example 4: Before

Before4.png

Example 4: After

after4

Summary

This article presented the DateUtil class for dealing with dates and times in the Sage 300 Web Screens (C-Sharp code) along with the benefits of using a single pattern by developers.

By encapsulating the date and time functions, we are able to provide a consistent and simple pattern while reducing the potential for technical debt.

When this class was implemented, we removed over 6,500 lines of code from the application.

The DateUtil class is available in the Sage.CA.SBS.ERP.Sage300.Common.Utilities assembly which is referenced in most if not all projects.

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 Open Source SDK First Partner Contribution

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 article is about the first partner contribution to the SDK!

Ecosystem Benefits

As I mention in the README document for the SDK in GitHub:

All tools can only be so much to everyone in order to consider everyone’s based needs while providing functionality that is easy to use. The open sourcing of the SDK will allow the community to extend, enhance and tailor this SDK to their specific needs.

Sage wants this community to be successful in the conversion of their applications to the web paradigm. The open sourcing of the SDK will allow those who wish to contribute to the SDDK to do so in a way that not only addresses their needs, but potentially the needs of others as well. With this paradigm, Sage hopes to have a couple of outcomes:

  • Engagement and Excitement
    • Get ISVs and Partners involved by allowing an ownership stake
    • Generate excitement not only for themselves, but as an example for others to participate and contribute as well
    • The community can make the SDK more robust
  • Faster Pace to Improve/Enhance/Extend the SDK
    • Everyone benefits (Sage too!)
    • The SDK potentially gets uncompleted sections and areas to be completed

Making the first partner contribution is TaiRox!

TaiRox and the Merge ISV Project Utility

While in a recent discussion about the Merge ISV Project Utility (MergeISVProject.exe), TaiRox inquired about:

  • Adding an additional parameter to the utility in order for it to “not deploy to the local installation”
    • The idea is that the Deploy folder’s contents are only needed at this time
    • The absence of the optional parameter will allow for the utility to perform as before
  • Additionally, a few functions would like to be re-factored as the copy and deploy are currently co-mingled.

My response was “Go for it”!

I see the optional parameter as a nice addition to the utility and I’m all for atomic routines.

And, I certainly appreciated TaiRox giving me a heads-up on the “re-factoring” modification as it would have delayed acceptance of the change as I evaluated the purpose for the additional modifications.

Summary

While Sage has implemented modifications and enhancements to the SDK based upon feedback and suggestions from the community, congratulations goes to TaiRox for being the first to contribute to the SDK outside of Sage.

When we first started discussing the benefits of Open Source, this one was of our goals: participation from the community. Well done TaiRox!

Now, I wonder, who will be next?

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.

Open Source Web SDK – Policies and Procedures

Introduction

In my previous article, I shared my thoughts on open sourcing the Sage 300 Web SDK (SDK) and how, in my opinion, this will benefit the Sage 300 Ecosystem.

In this article, I am introducing the SDK as Open Source Software (OSS) and will explain the changes to the original vision since the idea of open source was first presented along with the policies and procedures for the repository.

It’s Available!

The SDK was pushed to the public repository on July 23rd, 2016. The goal was to make this available for our Sage 300 2017 Release (August 2, 2016) and to also have it available for Sage Summit 2016 in Chicago (July 25-28, 2016). We made it by 2 days!

Licensing

The original plan was to use the Apache License 2.0 for our OSS. However, in discussions with our Sage Legal Team and the Open Source Initiative team, The MIT License (MIT) was chosen instead. The license can be found here: https://opensource.org/licenses/MIT

GitHub Repository

Repository Name

The GitHub Repository is SageNADev/Sage300-SDK and can be found here: https://github.com/SageNADev/Sage300-SDK

Blog4Github

Administration

The administration of the repository is performed by Sage’s DevOps Team located in Richmond, BC.

Anonymous Users

The repository is read-only for anonymous users which means that these users cannot “push” their changes into the branches in the repository.

Collaborators

Collaborators are Sage assigned developers and personnel which have write/push access to the branches in the repository.

Collaboration Model

There are two main models for collaboration using GitHub:

  • The Shared Repository Model
  • The Fork and Pull Model

In the Shared Repository Model, in order to allow everyone to “push” to the repository, users have to be granted collaborator permissions. This is a good solution for small teams where members know and trust each other. This model cannot, or should not, be applied to large teams or a public repository where all users have the right to contribute.

In the Fork and Pull Model, any GitHub member can “fork” a public repository. When forking the original repository, another one is created. Modifications can be applied to the forked repository without the changes affecting the original repository until a pull-request is submitted and evaluated by a collaborator who may or may not merge the changes.

Therefore, with Sage in the collaborator role, the model of choice is the Fork and Pull Model.

See the following article on Forking: https://guides.github.com/activities/forking/

Forking and Branches

There is a difference between a fork for an anonymous user and one for a collaborator.

Blog4Branches

Story Branches (Private)

Story branches are where the Sage collaborators make modifications and enhancements to the next version of the SDK. However, on GitHub, the repository is either public or private and branches cannot be private in a public repository.

The branch where the work is performed is not ideally suited for public consumption from an interest perspective, but also from exposing the developer and potentially numerous changes.

Therefore, in order to take advantage of GitHub for both public and private development, a Sage collaborator will:

  • Fork the public repository
  • Change the settings of the new fork to private
  • Clone the private version down to their local machine
  • Create a story branch based upon the develop branch
    • Note: Story branches are prefixed with a Version One Story plus Description
  • Make changes locally
  • Commit to the local repository
  • Push up to the private fork
  • Use pull-requests to selectively copy the required branch (develop) to the public repository

The Sage collaborators use squashing in order to reduce the commit history being pushed into the public branch.

Fork (Anonymous Users)

While Sage collaborators used a forked repository for making changes to the public branch, any anonymous user can submit changes to the public repository. However, an anonymous user is not able to commit or push these changes themselves since they only have read-only access.

Therefore, an anonymous user will:

  • Fork the public repository
  • Clone the fork down to their local machine
  • Make changes locally
  • Commit to the local repository
  • Push up to the fork
  • Submit a pull-request, which is evaluated by a Sage collaborator for inclusion into the public repository

Development Branch

The development branch (develop) is just what the name implies as it contains the in-progress contents of the SDK that is currently being worked on for the next release.

Sage collaborators are pushing changes and potentially merging anonymous requests for the next version of the SDK.

Only Sage collaborators can make changes to this branch.

This is the branch to be accessed based upon the following question: “Get me the in-progress version of the SDK that is not ready for release, but is to be released with the next version of the SDK”.

Current Branch

The current branch (master) is the branch which holds the current release of the SDK.

Sage collaborators may push changes to this branch in response to defects or issues either discovered internally or externally which require immediate correction. Any changes to this branch are also made in the develop branch.

Only Sage collaborators can make changes to this branch.

This is the branch to be accessed based upon the following question: “Get me the current version of the SDK”.

Release Branches

The release branches (i.e. release-2017, release-2017.1, etc.) contain the contents for that particular release.

When the next version of the SDK is released, the current branch (master) is copied into a release branch (release-2017, for example), the development branch (develop) is copied to the current branch (master) and then the development branch (develop) becomes the basis for the next release.

Blog4Releases

  • There is only one in-progress branch: develop.
  • There is only one current version branch: master.
  • There will be numerous version branches: release-2017, release-2017.1, etc.

Only Sage collaborators can make changes to these branches.

Folders and Files

The folder structure is identical between the development, current and release branches. The folders are used to segregate the various components of the SDK. The contents are different in that they contain content relevant to the version of the SDK that the branch represents.

docs Folder

This folder holds the documentation for the SDK and contains the following sub-folders:

  • development
  • patterns
  • presentations
  • standards
  • upgrades
  • utilities
  • webapi
  • wizards

patch Folder

This folder holds files, if any, regarding any patch work required to the SDK due to late minute changes that were not able to be included in the Sage 300 application. The README file in the patch folder will discuss the patch, the requirements and any steps necessary to apply the patch.

samples Folder

This folder holds the sample projects, which are standalone, runnable versions of different web screens and reports within the Sage 300 application. These samples are to provide implementation knowledge.

src Folder

This folder holds the source files which comprise the wizards and utilities and contains the following sub-folders:

  • utilities
  • wizards

root Files

The branch root not only contains the folders just mentioned, but also contains the following:

  • LICENSE.md
    • A read-only file for displaying the MIT Copyright notice
  • README.md
    • A read-only file for displaying any SDK information on the main GitHub page
  • VERSION.md
    • A read-only file for displaying the current version of the SDK

Release Cycle

The SDK follows the release cycle established in the roadmap for the Sage 300 application. Therefore, new versions of the SDK are released when the application is released.

Approval Timeline

The approval process for changes submitted by anonymous users are performed by Sage collaborators who will review these changes for inclusion based upon the value added to the SDK for the benefit of all users.

Therefore, it is extremely important to provide as much useful information and rational to support the request being made. And, not all requests will be accepted. But, the good news with OSS is that the submitter can still enjoy their version of the SDK even if the request is not accepted.

Sage collaborators will review new pull requests on a bi-weekly basis.

Depending upon the SDK roadmap, Sage collaborators may be working throughout the development cycle on changes and enhancements and will want to potentially include any requests and issues discovered and presented by anonymous users.

Summary

The SDK is released to open source! This article covered the GitHub repository, the license strategy, and policies and procedures pertaining to usage and management of this public repository.

I am excited for the Partner and ISV community to participate and contribute to not only their success, but to the success of the SDK and to other users of the SDK. I look forward to the submissions from the community in modifying and enhancing the SDK.

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.

Open Sourcing the Web SDK

Introduction

In this article, I want to share my thoughts on open sourcing the Web SDK for Sage 300 and how, in my opinion, this will benefit the Sage 300 Ecosystem.

Open Source Software

Let’s start by first defining what Open Source Software (OSS) is:

Open-source software (OSS) is computer software with its source code made available with a license in which the copyright holder provides the rights to study, change, and distribute the software to anyone and for any purpose.[1] Open-source software may be developed in a collaborative public manner. Open-source software is the most prominent example of open-source development.[2] (https://en.wikipedia.org/wiki/Open-source_software)

Licensing

We are planning to use the Apache License 2.0 for our OSS as it allows for use of the source code for the development of free and open source software as well as proprietary software. The license can be found here: http://www.apache.org/licenses/LICENSE-2.0

 

GitHub Repository

We are planning to use a GitHub repository for the storage, source code management and collaboration of the OSS. Internally, Sage 300c uses GitHub repositories for its web source code.

Ecosystem Benefits

I want to first state that there are two SDK’s for Sage 300:

  • Sage 300 SDK (has been around for years and years)
  • Sage 300 Web SDK

The initial SDK has numerous utilities and tools for generating business views, macros, analyzing data, viewing business view configurations, etc.

The new Web SDK has only a few productivity tools (at the moment) for the generation of the Web UIs in an MVC framework, generating JavaScript code grids and a Resx Generation Utility for converting RC files to Resx files.

Only the new Web SDK will be open sourced.

The Sage 300 ISV and Business Partner community is very active (and vocal too!). This was very evident to me at the recent Business Partner Conference in South Africa where I met with numerous companies and individuals. Their applications, add-ons and plug-ins to the Sage 300 application are very exciting and are part of the community life blood. They have used the existing SDK to build their applications and have enabled compatibility with Sage frameworks and the Sage 300 application.

With the new MVC paradigm, this community will need to re-write their applications for our new Web UI screens. The SDK will provide assistance in getting screens developed quicker by creating Visual Studio Solutions based upon the structures that Sage 300 uses internally. It will also generate code for a screen based upon a business view or a report or a dynamic query, etc. The Code Generation Wizard at this point in time only generates “working code” (it compiles and runs, but only creates the base scaffolding without any “business logic” and only key fields, finder, and action buttons (Save, Delete, Create New)) for a basic setup type screen. The other types of screens (reports, queries, dynamic queries, etc.) generate code, but not a working/runnable screen as these have not been fully addressed in the wizard.

However, all tools can only be so much to everyone in order to consider everyone’s base needs while providing a tool that is easy to use. OSS will allow the community to extend, enhance and tailor the SDK to their specific needs. I believe there to be quite a bit of excitement around this OSS endeavor.

The new Web UI screens have certainly created a lot of excitement for the Sage 300 product and its future. Sage wants this community to be successful in the conversion/re-factoring of their products to the new paradigm. The open sourcing of the SDK will allow those who wish to contribute to the SDK to do so in a way that not only addresses their needs, but potentially the needs of others as well. With this participation, we hope to have a couple of outcomes:

  •  Engagement and Excitement
    • Get ISVs and Partners involved by allowing an ownership stake.
    • Generate excitement not only for themselves, but as an example for others to participate and contribute as well.
    • The community can make the SDK more robust. So, now there will be the opportunity to do so.
  • Faster Pace to Improve/Enhance/Extend the SDK
    • Everyone benefits (Sage too!)
    • The SDK potentially gets uncompleted sections and areas to be completed

Management

There are numerous policies and procedures for OSS in terms of contributions, accessibility, versioning, release cycles, etc. We have not chosen a specific one, but when we do, it will be something that is fairly lightweight, managed by the Sage 300 Framework Group, follows regular release cycles, etc. The goal is to allow the SDK to be enhanced and extended for not only the benefit of the contributor, but for the benefit of all users of the SDK. Therefore, Sage will perform the approval and merging of the contributions.

Summary

I am excited about open sourcing the Web SDK. And from the initial feedback, so is the ISV and Business Partner community. The community will benefit from participating and contributing to not only their success, but to the success of the SDK and to other users of the SDK. Of course, not every member in the community will participate in the contribution process, but this is natural and expected when it comes to OSS. The SDK is a tool to be leveraged by the community as they begin their re-writing/re-factoring journey. And, allowing this community to participate in the success of the SDK while satisfying their needs is not only beneficial but also empowering.

We are targeting a June 2016 timeframe for making the SDK OSS. However, as a standard disclaimer, any topic in this article is subject to review and doesn’t represent a commitment as to when this will be available.