Sage 300 2017.1 Web SDK

Introduction

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

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

It’s Available!

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

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

Branches

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

master

Contains the current version of the SDK (2017.1).

develop

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

release-2017

Contains the previous version of the SDK (2017).

What’s New

bin Folder

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

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

Documentation

Updated documentation is available.

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

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

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

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

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

Customization

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

Samples

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

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

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

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

Component Updates

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

Workflow Engine Enhancements

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

Solution Wizard

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

Code Generation Wizard

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

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

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

WebApi

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

 

Summary

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

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

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

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

Advertisements

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.

 

 

 

Implementing an External Finder

Introduction

The following question was recently asked:

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

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

Example

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

Blog2Figure1

Step One

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

Blog2Figure2

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

Blog2Figure3

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

Step Two

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

Finders for all modules have already been registered with Unity.

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

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

Blog2Figure4

Step Three

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

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

Blog2Figure5

Step Four

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

Blog2Figure6Untitled.png

Step Five

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

InitFinders:

Blog2Figure7finderSuccessVendor:

Blog2Figure8.pnggetFilterVendor:

Blog2Figure9.png

Step Six

Mission accomplished!

Blog2Figure10.png

 

Blog2Figure11.png

Summary

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

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

 

Sage 300c Transition

Stephen Smith

As most, if not all, are aware, Stephen Smith, Sage 300 Enterprise Architect, retired at the end of February, 2016.

I want to acknowledge Stephen’s leadership, mentoring, friendship, his knowledge of the Sage 300 product, technologies and the accounting industry. These qualities and attributes will be missed by all at Sage. Stephen was at Sage (and Computer Associates) for over 22 years and has certainly played a key role in the success of the Sage 300 (formerly Accpac) product.

Personally, I will miss his abilities and working with him on a daily basis. But, I know that Stephen is looking forward to the next chapter of his life.

Here are a couple of pictures of Stephen and me together on a trip to Bangalore India where we were working closely with the Sonata Group (Hari Hara and KP pictured) on the Sage 300c modernization.

BanyonTree

IMG_3944.JPG

John Thomas (aka JT)

I’ve been with Sage for almost 23 years. I was working on the MAS90 product (now Sage 100 in the US) when Sage bought State of the Art, Inc. I was on the team that started the Sage 500 product and worked on that product from 1995 until 2009 when I came to the Sage 300 product. I have been working with Stephen on various projects over the last seven years, but none more exciting and important than the modernization of the Sage 300 product.

Ever since I started working, there has always been another “John” in the company/group. So, back in 1983, I started going by JT. And, well, it has stuck!

Sage 300c

I’m excited to see where this product is going. With the vast ecosystem around Sage 300, the modernization of Sage 300 is an important aspect and the underlying technologies are exciting and modern (MVC, C#, JavaScript, CSS3, HTML5, etc.)!

Exciting times are ahead for the product, customers, partners, ISVs, etc. as we continue on our modernization journey. On that note, in this blog I hope to continue Stephen’s blueprint of passing on relevant information regarding the product, the technologies used, insights and tips regarding coding implementations, and other topics surrounding Sage 300c.

Summary

Thanks to Stephen for all of the hard work and dedication to the product over these years. I’ll be thinking of you while knee deep in a problem while you’re taking pictures of wildlife from the relative peace and quiet of your life on the Sunset Coast! J

Be sure to follow the Sage 300 Development Partner Forum in Sage City http://sagecity.na.sage.com/sage_partners/f/53 as this forum is monitored by DPP Support and myself.