Sage 300 2018.1 Web SDK

Posted on by jthomas903

Introduction

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

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

It’s Available!

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

Branches

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

master

Contains the current version of the SDK (2018.1).

develop

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

release-…

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

What’s New

Documentation

Updated documentation is available.

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

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

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

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

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

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

Visual Studio Code Maps

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

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

Blog11CodeMap

Samples

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

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

Solution Wizard

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

Customization Wizards

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

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

Code Generation Wizard

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

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

Blog11Step1

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

 

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

 

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

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

 

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

 

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

 

Blog11Step3

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

WebApi

A new GL Segments endpoint has been added.

Defects Corrected

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

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

Vertical Menus

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

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

Blog11VerticalMenus

Summary

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

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

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

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

 

69 thoughts on “Sage 300 2018.1 Web SDK”

  1. Hi Thomas,

    Where should I get the following file to create web screens.

    Sage.CA.SBS.ERP.Sage300.Common.BusinessRepository.Menu

    When I am compiling my program that I am getting following error.

    Error 160 The command “”C:\AECS\WorkingFolder_Tamil\Samples\2018\January\Sage300CMvcApplication1\Sage300CMvcApplication1\.nuget\NuGet.exe” install “C:\AECS\WorkingFolder_Tamil\Samples\2018\January\Sage300CMvcApplication1\Sage300CMvcApplication1\ATTA.Web\packages.config” -source “” -NonInteractive -RequireConsent -solutionDir “C:\AECS\WorkingFolder_Tamil\Samples\2018\January\Sage300CMvcApplication1\Sage300CMvcApplication1\ “” exited with code 1. ATTA.Web

    Thank you,
    Tamil

    Like

    Reply

  4. The 2018.1 Web SDK is not compatible with Sage 300 2017 PU4. The version of the Web SDK is strictly tied to the version of the Sage 300 application as there are always library references and global web files that may have been modified or enhanced.

    Like

    Reply

  5. Hi Thomas,

    Is there an API command available for shipment entry in the latest version of the WEB API? In previous versions you could only process a shipment and invoice from order entry, but not directly create just a shipment from an order number.

    Like

    Reply

  6. Hey Aaron, I have checked with the team and this endpoint is not available at this time. We have created a story for this in our backlog to address in a near/future release. This transaction type when implemented will complete all of the OE Transaction types. So, in addition to yourself, we will also look forward to getting this implemented! Thanks!

    Like

    Reply

  7. Hi Jt,

    This is Lakki. I have been trying to consume the Web APIs exposed from inside Sage 300. I was able to locate the documentation with respect to the endpoints available from Sage 300 but when I try these, all I get is a “404 – location not found error”. May be I got to enable Web APIs inside Sage 300 for it to work. What am I missing?

    Thanks,
    Lakki

    Like

    Reply

  8. Just to be clear, I tried to consume the API from within the server where Sage 300 is running. So I used “https://localhost/Sage300WebApi”. I did also try this with http but I get the same error message on both. I see that the physical path mentioned on this error page is “C:\inetpub\wwwroot\sage300webapi” but I see on the server that this folder sage300webapi is absent.

    Like

    Reply

  9. Hey Lakki,

    Does the WebApi folder exist where you installed your Sage 300? For example, if you installed Sage 300 into the “C:\Sage\Sage300” folder, then there will be a folder called “C:\Sage\Sage300\Online\WebApi”. Do you see this? And, this also assumes that you selected the Web Screens option when installing Sage 300 as it is this option that installs the WebApi. I have heard of a couple of complaints such as this where the folder is missing. I would suspect it to be bad installation media and if the WebApi folder is not being installed when the Web Screen option is selected, the media would be the culprit. Also, if you look in IIS, is there a Sage300WebApi instance as well as the Sage300 instance?

    Like

    Reply

  10. I try to consume sage web api using the swagger ui, but i got Unauthorized Exception when i login with ADMIN ADMIN.. Thank you in anticipation

    Like

    Reply

    1. This is the error….
      {
      “error”: {
      “code”: “Unauthorized”,
      “message”: {
      “lang”: “en-US”,
      “value”: “Authentication error from invalid credentials.”
      }
      }
      }

      Like

      Reply

  11. Hey Hakeem,

    Starting with Sage 300 2018.1, we’ve implemented tighter security in the Web API for the ADMIN user, since an ADMIN user bypasses normal security rights and security groups.

    in the …\Online\Web and …\Online\WebApi folders you will find web.config files. These files have a new element specifically for the ADMIN’s use in the Web API. The element “AllowWebApiAccessForAdmin” by default is false and must be set to true for the ADMIN user to be able to use the Web API. For a normal user, you would simply grant access to the “Sage 300 Web API” security group for the module’s endpoint in the Web API that you want to access (i.e. AP, AR, GL, etc.). But for the ADMIN user who is not bound by security groups, the element in the web.config files must be set to true. And, following the setting of this element to true, simply re-start IIS for access.

    Thanks,
    John

    Like

    Reply

    1. Hi John,
      Thanks for the response… i’ve modified the web config for both “Web api” and “Web” to allow access for Admin but is still given the same issue.

      Like

      Reply

  12. Hi John,
    Thanks for the response… i’ve modified the web config for both “Web api” and “Web” to allow access for Admin but is still given the same issue.

    Like

    Reply

  13. Hmmm. Did you re-start IIS? Did you shut your browser down and re-open? When you enter the credentials, are you typing in upper case letters (since Sage 300 login UI’s upper case the user and password, but the dialog in the web api for credentials is not ours and does not force case. This is why it must be entered in caps.

    Like

    Reply

      1. Are you entering your credentials in upper case? Have you ensured that the user that you are using has been given access rights to the web api in Security Groups? If you are using an ADMIN user, have you enabled the administrator as a user via the web.config file?

        Like

  16. Hello John,
    Yes, the Web API; is there a way to post a list of records at a go, rather than looping through the list.
    thank you.

    Like

    Reply

  17. Hey Hakeem,

    Unfortunately not at this point. The API, which is essentially a RESTful wrapper around our .NET API is not orientated toward batches or sets. So, iterating a list is the approach at this point.

    Like

    Reply

  19. Currently, only Sage modules (GL, AP, AR, etc.) are available as endpoints in the Web API. We have it on our radar to look at extending the Web API endpoints to partner modules as well.

    Like

    Reply

  20. I am posting an order using the REST API and when I try to post an item number that does not exist, I get an error message “General” without a specific error. If I open the order entry screen and type an item number that does not exist I get the actual error of the item number being invalid.

    Like

    Reply

  21. Hey Aaron, The error message only says “General”? We do have an error framework in the Web API that catches and “cleanses” an error message because the Web API is available on the public internet. Our security folks ensure that we do not provide too much information on a failure or error condition which might be useful to less than savory types. Therefore, it is always a balance between providing enough information and useful information. And, this is why a message will likely not be identical to what is received in the regular application.

    I hope this help explain the difference.

    Thanks, John

    Liked by 1 person

    Reply

    1. Sometimes when I enter an invalid item number when trying to POST an order, it shows me the warning from changing the tax group rather than displaying the reason for why the order didn’t post properly (the invalid item number)…

      See below, for the exact response I get..
      {
      “error”: {
      “code”: “General”,
      “message”: {
      “lang”: “en-US”,
      “value”: “Warning. You have changed the tax group for this document. Please verify the tax information accordingly.”
      }
      }
      }

      Liked by 1 person

      Reply

  22. Hmmm. That is certainly strange. I know that the error stack that is bubbled up from the server may have multiple messages in it and it could be that the desktop client has some filtering logic that the web api does not have. I will have the team take a look at this as I agree that this is misleading. I appreciate the information!

    Liked by 2 people

    Reply

  23. Hi John,
    WebApi: Though the sample project works, but i have issues calling the api from my project. once it calls the httpClient.SendAsync(request) it will just hang there.
    thank you.

    Liked by 1 person

    Reply

  24. Hey, I’m not sure what could be the issue other than discovering what could be different between the two projects in getting to that point. Possible getting DPP support involved if needed although not sure if they address these kind of issues.

    Liked by 1 person

    Reply

  25. I see that in the Web.config file, under the appSettings node, you have a key of ‘UserSignalR’; are you guys planning on using SignalR in the future? That would be very cool if you did.

    Liked by 1 person

    Reply

  27. Hey Fella,

    I am integrating Sage 300 2019 with Sage CRM 2018 R3 as per the documentation and getting following error while running Synchronization from CRM in webapi_log_SAMINC.log file:

    Error Code: InternalServerError, Error Message: Sage 300 WebApi Internal Server Error

    I have configured Sage WebAPI rights in both config files.
    Did Metadata and IIS restart
    I am using Standard Sage 300 ADMIN user for integration.
    It is a fresh install on new VM
    Sage 300 and CRM are installed on same VM over 2012 R2

    Any Clue?
    Thanks in advance for help.

    Like

    Reply

  28. Hey, sorry as I have been out of the office for a few days. It sounds like you have enabled the ADMIN user. Are you able to launch our swagger api page (localhost\sage300webapi) and perform any of the endpoints manually (like retrieve a customer or customer)?

    Like

    Reply

    1. Thanks for your reply….

      What do you mean by enabling Admin user? In Sage 300 I have enabled security and it asks for login password. The password I am putting in from CRM side for 300 user is ADMIN (all caps).

      I will try swager and let you know.

      Thanks V much
      Sharad

      Like

      Reply

  29. By default, the ADMIN user is restricted from the Web API process since it is not governed by security rights setup in the application. In the …\Online\Web and …\Online\WebAPI folders is the web.config files that contain a property to enable the ADMIN user to use the Web API.

    However, from a security standpoint, we do encourage the use of a typical Sage 300 user who has been given access rights to the Sage 300 Web API as a better mechanism than using the ADMIN user.

    Like

    Reply

      1. Hey, It seems like you have found the issue. In looking at the screenshot on the link you referenced in Sage City, I would have assumed that the issue was that you had “Windows Authentication” enabled. For the Web API, we disable/remove that feature in IIS.. Glad it is working.

        Like

  31. Hiya…

    I am able to run Swagger UI and for following request url:

    http://localhost/Sage300WebApi/V1.0/-/SAMINC/AR/ARCustomers('1100‘)?%24select=CustomerNumber

    I am getting following error in response body:
    {
    “error”: {
    “code”: “InternalServerError”,
    “message”: {
    “lang”: “en-US”,
    “value”: “Internal Server Error”

    }
    }
    }

    Cold it be related to this:
    https://community.sagecrm.com/user_community/f/84/p/14369/39492.aspx

    I however applied sugestion given by Jeff for anonymous user as I was getting “Class not registered error in the begining” and than it was resolved.

    Thanks
    Sharad

    Like

    Reply

  33. When I check the same URL
    (http://localhost/Sage300WebApi/v1.0/-/SAMINC/AR/ARCustomers?%24select=CustomerNumber&%24top=1)

    on Fiddler composer, it gives me this error:
    HTTP/1.1 401 Unauthorized
    Cache-Control: no-cache
    Pragma: no-cache
    Content-Length: 166
    Content-Type: text/plain; charset=utf-8
    Expires: -1
    Server: Microsoft-IIS/8.5
    WWW-Authenticate: Basic realm=”localhost”
    X-AspNet-Version: 4.0.30319
    X-Powered-By: ASP.NET
    Date: Thu, 06 Sep 2018 14:26:48 GMT

    {
    “error”: {
    “code”: “Unauthorized”,
    “message”: {
    “lang”: “en-US”,
    “value”: “Authentication error from invalid credentials.”
    }
    }
    }

    Where and which is this authentication it is looking for ?

    Like

    Reply

  34. When I copied and pasted that URL in my browser it works as expected:

    {
    “@odata.context”:”http://localhost/Sage300WebApi/v1.0/-/SAMINC/AR/$metadata#ARCustomers(CustomerNumber)”,”value”:[
    {
    “CustomerNumber”:”1100″
    }
    ]
    }

    Now, are you sure you enabled this element in the web.config files?:

    If you are using ADMIN as a user, this flag must be set to true. Also, remember that the Web API uses basic authentication. The dialog presented in the Web API is not Sage 300’s dialog. Therefore, it does not force the upper case of the user and password, which is required by Sage 300. So, if your user is ADMIN and password is ADMIN, it MUST be entered that way. If you enter admin and admin, it will generate this message because admin is not the same as ADMIN.

    If the flag above is not set, you will need to do so and then re-start/reset IIS. If it is incorrect case on credentials, then the proper case is the resolution.

    One last thing to check, if you are using Chrome, you must set Windows Authentication to disabled (if the option exists in IIS Authentication). To do this, in IIS Manager, go to Sites–> Default Web Site –> Sage300WebApi; click on Authentication, IF “Windows Authentication” is present AND it is enabled, it must be set to disabled. Restart IIS.

    I hope this helps.

    Like

    Reply

  35. Yes I am using ADMIN & ADMIN when the popup comes up for authentication and the error comes after that.

    This is how values in both web config looks like:

    For Sage300WebApi in IIS Windows authentication is always disabled.
    IIS and System restart done multiple time.

    I tried on both IE 11 and Chrome & Firefox too

    Phewwwww…

    Like

    Reply

  39. I see that key is present and is needed with that value is ADMIN is to be used. So, you should have all of the configurations that make sense. But, you are still unsuccessful. Correct? But, you are successful without the top= 1? Are you successful but not limiting the payload and returning all columns instead?

    Like

    Reply

  41. Hey,

    Well, there certainly seems to be a config issue somewhere as that URL is valid as it works when I use it. At this point, I suggest opening a ticket with either CS or DPP support to help you resolve the issue.

    Like

    Reply

  42. Hey John,

    Happy Friday !!
    The issue is resolved. I did Portal deployment again and it started working, may be some files were missing earlier.

    Mannnyyy thanks for your guidence.

    Cheers !

    Like

    Reply

  44. Hi John,

    A quick question for your insight:
    I am working on an integration between Sage 300 2017 with Sage CRM 2017R3, I know Sage 300 version is out of support but if you can suggest on this will be great:

    * With these above versions on a single server installation is it possible to use Sage 300 order and quote pages inside CRM ? As I think it needs both Web deployment and PORTAL installation while on a single server either PORTAL or Web deployment is suggested till these versions.

    Thanks in advance
    Sharad

    Like

    Reply

    1. This version of Sage 300 and CRM has the “old” integration between 300 and CRM where an ASP page is rendered and is used as a middle man. In the new integration, these middleman pages have been removed and now the actual Sage 300 Web Screen is displayed in an iFrame in CRM.
      But, in that 2017 version, it is recommended that the sage 300 and CRM installation be on different servers because of the TomCat conflict.

      Like

      Reply

      1. Thanks John for your swift response.
        I will suggest our costumer accordingly. I am assuming if I upgrade CRM and ERP to new versions it should work on single server.

        Thanks !
        Sharad

        Like

  45. Hi John,

    Was trying to POST APVendors in Sage 300 via API but i got the error msg below.

    {
    “error”: {
    “code”: “InvalidPayload”,
    “message”: {
    “lang”: “en-US”,
    “value”: “The payload is invalid for this resource.An unexpected ‘PrimitiveValue’ node was found when reading from the JSON reader. A ‘StartObject’ node was expected.”

    }
    }
    }

    This is what i entered under the PARAMETER

    “VendorNumber”: “OTHER1”
    “ShortName”: “OTHER1”
    “GroupCode”: “OTHERS”

    Like

    Reply

Leave a comment