Testing and Documenting Manage 2000 REST Services using Postman

Manage 2000 release 8.0 provided 15 poorly documented REST services.

Release 8.1 sp5, the current field release, provides 18 poorly document REST services.

Release 8.1 sp6 (projected release Q2 2023) will provide 50 well documented REST services.

Postman has become an invaluable development tool for both testing and documenting the Manage 2000  REST Services.

The results of Manage 2000 development using Postman can be found at: Manage 2000 REST Services

The Manage 2000 REST Services collection may be imported into Postman and used for your own testing and debugging.

Multiple environments may be setup for running examples against MANAGE-2000, xxx.MAIN, xxx.TRAIN, xxx.DEV...

Service root URL and Auth Tokens may be defined in one place in the environment and then used on all services.

The resulting documentation provides not only parameter specifications but also examples with results, so developers can clearly see the content and format of the data being passed in and the results being returned.  

The results of using Postman speak for themselves.  It is clearly a huge contributor to the usability and quality of today's and tomorrow's REST APIs.

Bearer Token Authorizations and JPATH Expressions

 Yeah, apples and oranges.  And I am not going to relate the two either.  They are just the flotsam and jetsam floating about in my mind from recent development.

Bearer token authorization comes out of the OAuth 2.0 standard, but has taken on a life of its own and become a commonly used authorization mechanism for REST services.

In the Rocket UniData UniBasic Extensions Version 8.2.2 you can find details on the Authorization setting required in setRequestHeader.  There is a whole intro page about OAuth 2.0 and U2.  

Short version:

setRequestHeader(HTTPRequest.Handle,"Authorization", "Bearer ":BEARER.TOKEN)

setRequestHeader(HTTPRequest.Handle,"Authorization", "DIRECT ":HMAC.TOKEN)

And these have to be done after the Request object is created.  There is no option in setHTTPDefault to specify the authorization type ahead of time. 

So in the REST.SERVICES table you just need to start the Auth Token prompt with "Bearer " or "DIRECT " and then the token, and REST.SERVICE will setRequestHeader and your REST.SERVICE request will be off to the races.

JSONPath or JPATH is for JSON what XPATH is for XML; a standard for declaratively specifying pieces of a JSON string to be returned.  I stumbled into the need for such a thing while working on the REST provider for NEWS.ARTICLES.  If you want to provide the capability to an article author to layout an HTML div and specify replacements from a REST service then you need some standard declarative expression to say "put THAT piece from the REST service results HERE!". And it would be nice to make the replacement expressions familiar and consistent with some larger standard.

The REST.NEWS news provider subroutine simply calls out to JPATH to extract out the pertinent data.

 *

2110* Replace dictionary references with values

 *     

     VAR.CNT = COUNT(LINE, "&")/2

     FOR VAR.IDX = 1 TO VAR.CNT

        VAR.IDX = VAR.IDX ;* Audits!

        VAR.NAME = FIELD(LINE, "&", 2, 1)

        TARGET.NAME = VAR.NAME

        TARGET.VALUE =  JPATH(udoRESTData, TARGET.NAME )

JPATH is not yet a W3C standard.  There is an IETF working group developing a standards-track JSONPath specification based on work by Stefan Goessnerwhich.  So while not set in stone there is general consensus on what a JPATH expression ought to look like and how it ought to function.

There are no JPATH features in the Rocket UDO functionality currently. However, the primitives are there for building a JPATH function.  And that is what I have started. It is available as a patch to Manage 2000 8.1 sp5.  And I would lead with "not complete yet".  But it provides the basic functionality which allows expressions in NEWS.ARTICLES like "&$.Customers[1].OutputEmailAddresses.SaleseQuoteEmail&" and since "$" is optional and array slice filter defaults we can write more concisely &Customers.OutputEmailAddresses.SalesQuoteEmail&.  

Why "not complete yet"?  Well it will do basic array slicing expressions, but a lot of work remains to implement all the possible filter expression and array slices within array slices and so forth.  

Manage 2000 Release 8.1 Service Pack 5 Now Available

Just in case you missed the official announcement:

 "We are pleased to announce that Release 8.1 Service Pack 5 was released today, March 23^th, 2022 and is now available for upgrades."

The surprise in the official announcement is the limited support for LINUX.  We still have the vsi-fax caveat, faxing out of Manage 2000 on LINUX is NOT there yet. But if you want to run Manage 2000 8.1 sp5 on rhe LINUX 8 and do not need faxing then we are ready to support you in that. 

Bud and I continue digging through the options trying to find the best path to get faxing support on LINUX, without ESKER directly supporting vfx... on rhe LINUX 8.  You'll probably hear us shout when we finally find the right path.

Customer enthusiasm for moving forward on Manage 2000 has been gratifying to see with four 8.1 sp5 upgrade orders already in the first week of GA.

So what will we imagine for service pack 6?  

My journey this last year has included the opportunity to explore what other software teams are doing with REST API development.  While 8.1 sp5 includes a nice REST API platform, it is mostly 'toolsey' stuff that you can use to build your own, but does not provide the full manufacturing application provider API that I am seeing other software teams working on.  So one of my research and development projects is imagining how we can take the REST API platform and build out an API to specific sales and manufacturing processes.

The current leg of my continuing journey has me exploring POSTMAN and using it to test and document existing REST services:

Manage 2000 JSON Services

A little quicker and easier than running JSONServices, viewing source, and reverse engineering :-)

Manage 2000 on LINUX Anyone?

The Manage 2000 8.1 sp5 cutoff went off on scheduler last Friday.  Now Lane has doffed his Release Control hat, and I am setting up work space for Manage 2000 8.1 service pack 6 development.

In other news... "Support for HPE's Itanium-powered Integrity servers, and HP-UX 11i v3, will come to an end on December 31, 2025".  So what does that mean for the 20 or so Manage 2000 sites running on HP?

Well, we on the Manage 2000 development team have taken notice.  Lane has Manage 2000 8.1 sp4 running on a LINUX RHE machine and the rest of us are banging away on it.  VSI-Fax is one of our last major hurdles to supporting Manage 2000 on LINUX.  Esker will not support the traditional local Vsi-Fax install on RHE 8.  That pretty much strands Manage 2000 FXJ capabilities.   I will be trying to build a bridge to the Esker 'On-Demand' web service API.  And Bud is looking into another option hosting Vsi-Fax on Windows and accessing the database from a LINUX machine. One way or another we'll get there.

RHE is the Red Hat Enterprise flavor of LINUX.  It has the chops to become the foundation for larger Manage 2000 sites going forward.  I am expecting this to be mostly Itanium sites needing to move to a supported platform by the end of 2025.  But, I will not be surprised if some larger Windows Server sites eye the LINUX option favorably, if for no other reason than 85% of ransomware attacks still target Windows systems.  

Yep, just gets interesting-er and interesting-er.

Manage 2000 8.1 service pack 5 - sneak peek

Final touches are going into service pack 5 of Manage 2000 release 8.1. Tees are getting dotted and eyes are getting crossed.

Another year of development items are releasing in this service pack along with the year's supply of bug fixes.  There are a number of new features I am excited about, along with a couple more upgrade challenges than usual for a service pack:

• The website has been upgraded to ASP.NET 4.8
• The JavaScheduler has been upgraded to version 5.3.1.

This means a little extra installation work during the service pack upgrade.

The upgrade to ASP.NET 4.8 was necessary to work with the new  5.3.1 version of the JavaScheduler. The new version of the JavaScheduler is faster in our testing than the old version, and it is built with the Open Java SDK eliminating any licensing controversy.

So what other new things can you do with Manage 2000 service pack 5?

• Access documentation and training material more easily
• Cross browser compatible Help and Documentation make these items available from outside the EOT Viewer web view, using any browser.
• See Also documentation access from portal menus - pertinent documentation links on local portal menus keep overviews, courses, and HowTos at your user's fingertips.
• Text from Manage 2000 to your phone, your user's phone, your customer's phone, your sales rep's phone...
• Receive text messages from the Manage 2000 Event Condition Action system. The text message may contain only the ECAs Title or the Title and Body based on the CONTACTS  ECA TextMsg option for Notify events
• Administrators! Receive text messages from Master Agent notifications
• Configure plug-able interfaces with Twilio, Nexmo, and other texting services using TEXTING.SERVICES.
• Specify carrier gateway conversion sites in PHONE.CARRIERS.
• Send text messages from UniBasic using SUB.TEXT.OUTPUT.
• Send quick text messages from the command line using TXT and TID.
• Use UserPreferences Contact Information page to maintain your cell phone carrier. This enables carrier gateway text messaging.
• Share data through REST APIs
• REST Consumer API
• Configure access to RESTful service endpoints through the REST.SERVICES table.
• Display RESTful data in ANY Manage 2000 function using Manage 2000 Software Objects. Configure in MSO.BUILD using subroutine REST.MSO which will access RESTful services and display results in Manage 2000 functions.
• Read REST sourced news articles in Newsreader.
• Display REST sourced news articles in Portal news panels.
• Call RESTful services from UniBasic using new tools subroutine REST.SERVICE.
• REST Provider API introduced in 7.3 and expanded in 8.0 and 8.1
• Access packages of UniData database information from Power BI or Excel. Use REST endpoint /mt/jsonservices/getdata from Microsoft's GetData wizard. Specify the package contents like a UniQuery request in JSON.PACKAGE.MAINT.
• Use the new preselect to optimize access
• Use the new postselect to reprocess/reformat the results
• Obtain single source validation information from Manage 2000. Use REST endpoint /mt/jsonservices/gettmtable to access TM tables as JSON arrays. Use REST endpoint /mt/jsonservices/validateitemservice to validate inventory part numbers, sales order numbers and more.
• Call UniBasic subroutines from web browsers.  Use REST endpoint /mt/jsonservices/calludtsub to call backend UniBasic subroutines.  Call GetItemsAsJSON to pickup UniData database information in JSON format.

• Manage 2000 JSON Services

• Configure Manage 2000 to use the VERTEX O-Series Tax Calculation service
• Have CUSTOMERS verify addresses using the US Postal Service Web API Interface for Zip+4. It will even add the 4 digit zip code suffix to improve delivery accuracy.
• Cleanly install new custom development in one step using ARCHIVER REPLACE
• Validate user input based on prompt definitions using the same validation logic used in SCREEN.IP by calling SIP.VALIDATE.
• Collapsible Panel Memory - okay maybe this is more a bug fix than a new feature, but finally the collapsible panels work the way I want them to on my phone and my desktop, right out of the box!
• See the resulting displays of I-Descriptors already available on a file using new phrase records I, I2,I3… built by DICT.INIT.ALPHA.  
• Stop worrying about JAVA licensing controversies.  The new JavaScheduler is 100% OPEN JDK.
• See inquiry function results in your browser. 
• EOTViewer is a web client prototype of an alternative to the Greenbar Browser. A number of people have been asking for this, so I thought I'd give it a shot.  It is still develop-mental,  but if you are daring, give it a try using USER.OPTIONS screen 2 prompt 24 and 25.  Then give me some feedback (aka encouragement to take it to the next level:-).

I don't have a hard date to give you just yet for availability.  We need to support you all through year end. Then, hopefully, we will still have enough time in January for the development cutoff.  Release Management will need Feb-Mar to clean the release, create media, test installs... So stay tuned for an announcement of general availability in the March - April timeframe.