Create a Web Service API to read Excel .csv and post Sales Orders

In this tutorial we start to pimp up our previous Supply Chain solution. We create an own API instead of the SYGR standard, which

• Reads Excel .csv data
• One line corresponds to one Sales Order
• Post them from one message in SYGR.

We will do the following:

• We create a Message Converter Plugin and
• configure the SYGR Regio server to use it.

In this tutorial you will learn how powerful the SYGR Plugins are.
But be prepared: you will need some basic Java experience to make it.

Let’s start!

SYGR Plugins

Plugins are the power tool of SYGR.
With Plugins you can do anything:

• Make a Synchronous or Asynchronous API to integrate your SYGR solution to any company IT environment
• Create multiple Entities from one message, define their content and initiate scheduled actions on them
• Replace the limited Internal Rules with External, where you can do anything you want with an Entity
• Make beautiful reports for end users.

SYGR Plugins are Java classes, implementing a Java Interface.
In order to create a Plugin, you need the Plugin API, which you can download free from the SYGR Documentation and Downloads page.
An empty Plugin class should look like this:

Every SYGR Plugin uses the same interface.
There are 6 Plugin types within the system:

• Message Converter – receive RESTful messages with any type of content, text or binary data
• Output Converter – produce the response in case of a synchronous request
• Entity Init – initialize a new Entity, trigger follow-up actions
• Rule – the most important, doing all complex business logic
• Entity and Transformation Reporting – to provide nice reports

What is more, we guarantee that the Plugin API will never be changed, so once you have created your Plugin, it does not need to be recompiled at system upgrades (we have our solution to add newer and newer features without changing the API).

The Plugin Interface has 2 Methods:

execute: this is the main method of the Plugin, will be executed every time the Plugin is needed.

reloadConfig: executed when something relevant configuration was changed. Plugins are stored in memory for faster execution and can themselves buffer different data. This method is a call to refresh the stored data.

Now let us start to create our API!

Creating the API

In the previous tutorial we used the standard SYGR API to create Sales Orders. We transferred the following data:

• Sales Order Number
• Material
• Delivery Date
• Quantity

Now we will use an Excel csv format to do the same, but posting several orders.

In the input one line corresponds to one Sales Order.

So, let us start.
The content (BODY) of the message is provided by PluginData.messageIn.getContent():

We make it secure. In the catch, util.log creates a system log and then we stop the execution.
You can any time just return from a Plugin. If you change something, that goes to data.

Next, we process the csv lines one by one.
Again, make sure nothing causes a trouble.

A line is a Sales Order, where we need 4 fields. If it is shorter, that is a problem.

For every new Sales Order we have to create a new Creator object for SYGR.
The structure of the Creator is the same as we used in the standard API.

Everything we do now is inside the loop on the input csv lines.

First we set the Entity Model.
Then the match for the sales order number.

In programming languages the indexing of series normally start with 0, so pts[0] is the first field in our csv line, which is the Sales Order number.

Now we create the Sales Order transactional data.
The flexible data structure which we have seen previously in the Attribute Editor is a Java class Attr.
We use the convenience function util.setNodeValue() to create the attribute nodes and to give value to them.
Convenient, isn't it?

See that the received quantity, being UNDER the requested quantity, is separated by a dot (.). This is very important in SYGR Attrs: level names are always separated by the dot (and because of it you cannot use dot in the node names. If you try, the Attribute Editor will refuse to use the name).

As the very last step, we just add the created Creator object to the Plugin data.
We use the data.messageOut.addCreator() method.

There is nothing more to do, our Plugin is complete.
You can find the full source code here.
Now we can configure SYGR to actually use it.

Configuring the API

First of all you have to save your work as a normal (non-executable) .jar.
SYGR works only with complete .jars, so in one program you can put as many Plugins and other classes to do the business logic, as you want.
In the end place the .jar file into the “lib” folder of your SYGR installation.

Important: this is a Message Converter, so it has to be available in every Catcher server you want to use it with. But it does not hurt to copy to every server.
After copy you have to restart the server.
(It may be confusing that we provide a 365/7/24 service of SYGR even in upgrade or update events, but now we request to restart the server, which obviously will make the server unavailable for a couple of seconds.
Well, that's why SYGR is designed a distributed software. If you have at least 2 Catcher servers and shut down one, the other will automatically take over all the work from the first, so the service will be not interrupted at all.)

The Plugins must be configured in the SYGR Regio (central) server.
Log in to the server:

and select “Configuration”.

Select “Plugins”,

and then select “Plugins” again.

Select “Create new”.

Fill the fields:

• Id will be the unique name of the Plugin. Use a simple name as it will be part of the URL to call the API.
• FQCN (Fully Qualified Class Name) is the package name and the class name separated by dot
• JAR is the created .jar file name
• Usage must be “Message Converter”

When done, press “Save”.

Next, from the Plugin Maintenance select “Catcher – Plugin Links”.
In a SYGR cluster there can be lot of Catcher servers for different business purposes. The Message Converter (and Output Converter) Plugins must be linked to one or several Catcher servers.

Create a new link, selecting a suitable Catcher server and the plugin you have just created.

Save it.

Try the new API

It is time to try our API.
Prepare an HTTP POST message e.g. in Postman:

See in the URL, that the previous “default” is replaced by our Plugin name, “postso”.
The BODY is the 3 lines of csv.
Let’s send it.

All the 3 Sales Orders were created from one message and the content is what we expected.

Conclusion

We have arrived to the end of this tutorial.
We have learned how to create a SYGR Plugin and how to configure it.
See you in our next tutorial, where we go into more details of the SYGR Automation System.

If you have questions, please contact us:
contact@sygr.ch
contact@sles-automation.com
+41 79 470 67 84