RKL eSolutionsBlogs

X3 Integration with External Executable Calls Overview

Sometimes it is necessary to call an external process to perform tasks outside of Sage X3. This post will outline pulling data from a 3rd party, and populating a custom table in X3 by calling a .Net executable from X3 4GL code. The process will be done from a .net application which is triggered from an X3 screen. Once the process is complete, the data on the current screen will be refreshed.

This example will use a .net console application, which will accept a parameter from X3. It will perform two steps:

  • Retrieve a list of ship methods from a 3rd party web service.
  • Load the ship methods into a custom X3 table using a custom X3 subprogram web service.

The .net application will be using an external SOAP web service to pull the data and an X3 SOAP web service to load the data to X3.

3rd Party Web Service

For this example, the 3rd party web service will return a list of Ship Methods, similar to what is shown below. We will be loading each ship method into a custom table in X3.

Sage X3 Ship Methods Code

Create the X3 Table

The first step will be to create the custom table in X3. This can be done from Development > Data and parameters > Tables > Tables.

Below are the table details:

Sage X3 Table Details

The columns highlighted are added automatically by X3.

Sage X3 Table Columns

Only one index is required, but I added two here.

image007

Make sure you validate the table.

Create Subprogram to Save Records to Custom Table

The next step is to create the subprogram to add or update records in the YECSHIPM table. The code for this is shown below.

############################################################################
## Subprogram: SAVESM
## Description: Save a ship method to custom table YECSHIPM ############################################################################
Subprog SAVESM(SMKEY, COMPID, SMID, CALCUN, SMDESC, STAXKEY)

ValueInteger SMKEY
ValueChar COMPID
ValueChar SMID
ValueChar CALCUN
ValueChar SMDESC
ValueInteger STAXKEY

# Open shipments table
Ifclalev([F:YESM])= 0 : LocalFile YECSHIPM[YESM] : Endif

Read [F:YESM]YESM0=SMKEY
If !fstat
# Update existing records
[F:YESM]YCOMPID = COMPID
[F:YESM]YSMID = SMID
[F:YESM]YCALCUN = CALCUN
[F:YESM]YSMDESC = SMDESC
[F:YESM]YSTAXKEY = STAXKEY
Rewrite [F:YESM]
Else
# Write new record
[F:YESM]YSMKEY = SMKEY
[F:YESM]YCOMPID = COMPID
[F:YESM]YSMID = SMID
[F:YESM]YCALCUN = CALCUN
[F:YESM]YSMDESC = SMDESC
[F:YESM]YSTAXKEY = STAXKEY
Write [F:YESM]
Endif

CloseLocalFile [YESM]

End

Publish the Subprogram as a web service

The next step is to publish the subprogram created above as a web service. This web service will be called from the .net program to save records from the 3rd party web service to the new X3 table.

Create the subprogram

Go to Development > Script dictionary > Scripts > Subprograms. Create the subprogram as shown below. Make sure the “Web services” checkbox is checked.

Sage X3 SubPrograms

Create the Web Service

After adding the subprogram, click the “Publication” button to create the web service.

Sage ERP SubPrograms

Enter the Publication name and description, as shown below.

Sage X3 Web Services

After saving the web service, click the “Publication” button to publish it.

Sage ERP Web Services

Make sure the “Published on” date changes.

Sage X3 ERP External Web Services

The web service is now ready to consume.

Add Table to Screen

For this example, I am adding the ship methods to the customer screen management tab (BPC2).

Sage X3 Screen Directory

  • Add new block called “Ship Methods” for a Table.
    Sage X3 Ship Methods Block
  • Add fields to the screen block.
    Sage X3 Fields Block

Add Refresh Button

Add a button to the OBPC window to refresh the ship method values.

Sage X3 Buttons

Modify SPEBPC Code

Modify SPEBPC code to populate the table on the screen and to call the external .net .exe upon click of the button to refresh the X3 table by calling the 3rd party web service.

  • Add LIENS action to load table by calling subprog LOADSM.
  • Add EXEBOUT for code to execute when button is clicked. This is the process that calls the external executable.
    Sage x3 EXEBOUT Sage x3 EXEBOUT After Load Sage x3 EXEBOUT  Ship Methods Sage x3 EXEBOUT Button Clicked

Create a .Net Console Application

As was covered in previous blog posts, several steps will be required to prepare the .Net application to access the X3 SOAP services. These are summarized below, but refer to the original posts referenced below for more details.

Day 4 Consuming X3 Object-Based Web Services from .Net

Day 5 Consuming X3 Subprogram Web Services from .Net

Add WSDL Reference

  • Add the WSDL service reference to the project for X3.

Add Basic Authentication Class

A standard class is used to do the basic authentication for the web service calls.

  • Add a new class called CAdxWebServiceXmlCCServiceBasicAuth.cs to the project.

Retrieve Ecommerce Data

Create a function in the .net application to retrieve the data from the 3rd party. In this case, I am calling a SOAP web service to retrieve a list of ship methods. This is performed in class ECShipMethod.cs in the sample application.

Save the Records to the Custom X3 Table

  • Create a method to run a subprogram based web service. For this example, we will create a new class called X3ShpMeth.cs to save the data.
  • The SaveX3ShipM will receive the ship method details from the 3rd party web services, and call our custom subprogram to add/update the details to the custom table in X3.
  • The parameter passed in is sm, which is of type ShipMethodsShipMethod, which contains the ship method details retrieved from the 3rd party
    image035
  • We need to provide the XML (or JSON) for the subprogram being called. This will include all of the parameters defined in the subprogram.
    Build XML Sage X3
  • The code below is pretty standard for all web service calls.
    Sage X3 Web Service call code
  • In this case, we are calling the “run” function. Below we are using the run function, passing the callContext, the web service name (YWSSAVESM) and the XML parameter string.
    Call Web Service
  • The result of the web service call can be evaluated as shown below. This is standard for all web service calls.
    Webservice Evaluate Result
  • Copy the .exe, .dlls and .config files for the .Net application to the X3 server, for the endpoint where it will be executed.
    Endpoint Execute
  • If a new directory is created on the X3 server, it must also be create in X3 as a Storage Volume.
    • Go to Usage > Usage > X3 Storage Areas
    • Select Actions > Create to add a new storage area.
      Volume

View the Results

To test the results, we will go to the X3 customer screen. 

Notice that we now have a button called “Refresh Ship Methods”.

Customer

Additionally, there is not a block which contains a table of Ship Methods on the Management section. The contents of this grid were retrieved from a 3rd party web service, loaded into a custom X3 table, then refreshed on the screen.

Ship Methods

By clicking the “Refresh Ship Methods” button, the latest values will be retrieved and refreshed on the screen.

Summary

You now have everything you need to call external executable from a Sage X3 4GL program. Although this is a simple example, this can be used for many different integration requirements where accessing an external program from X3 is necessary.

Tagged With: Sage X3, Web Services, How-To
Denise Hartman

Written by Denise Hartman

Denise has a B.S. in Business Administration from Millersville University, and an M.B.A. from Loyola University of Maryland and has been working at RKL eSolutions as a Sage Enterprise Management Engineer since 2007. Her main focus is on integrations between third party systems and Sage Enterprise Management. In her free time she enjoys spending time with her husband and adult twin daughters, who are both accountants.

Questions? Need Support?
Get in Touch