Consuming Sage X3 REST Web Services

In Sage X3 Version 7 and later, REST services are available to access various entities. These REST services return data in a JSON format, and can be consumed from .net. This post provide some .net examples of making REST requests to Sage X3, and parsing the data.

Sage X3 Representations

The object we will be consuming in our example can be viewed by the representation SORDER. This can be viewed within X3 from the Development menu, under "Data and parameters > Classes > Representations". The representation is similar to a class in .net, and it defines a structure.

Note that this class has the following Facets available:

• Detail – returns details of the Order
• Query – returns a list of Orders
• Lookup

  

Preparing the REST URL

The REST URL is generated based on several variables in the X3 environment. Below is an example of a request:

http://x3server:8124/api1/x3/erp/SEED/SORDER?representation=SORDER.$query&count=10

http://x3server:8124/api1/x3/erp - This is the base url. X3server represents the X3 server name being accessed.

/SEED – This is the endpoint being accessed.

/SORDER – this is the Class code.

representation=SORDER – SORDER is the representation code.

Count – returns up to 10 orders.

Consuming the REST objects in .Net

The JSON Structure

The first step is to create the Business Object(s) required to deserialize the results from the call. The results of the REST call will return a json structure. This json can be deserialized into a .net object for further manipulation. One way to define the business object that represents the json is to use some tools available on the web.

One such site is called http://jsonutils.com.

Steps:

• Make a call to the Sage X3 REST using the url defined above.
• Copy the returned json to your clipboard.
• Go to the site above, and copy your json to the "JSON Text or URL" field, then click "Submit".
• The Class Objects will be generated in the area below, and can be copied and pasted into your .Net program.

  

• Below is a sample of what the class will look like in .Net.

  

In some cases, it may be necessary to modify the data types to match the possible values that may be returned. For example, if the order amount has no decimal positions in the return Json, it may make the data type for order amount an integer, but in reality, this should be a double or decimal to allow decimal positions.

Calling the REST URL to return a List of Sales Orders

Once the class object is defined in .net, the REST object can be called and deserialized. Below is an example.

The GetOrders function returns a list of Sales Orders. It accepts a record count as a parameter for the maximum number of rows to return in the list. Note that it is using the $query facet. Below are the steps:

1. Construct the URL for the request.
2. Add the Basic Authorization credentials to the request header.
3. Execute the request, and read the response into a string sData.
4. Using JavaScriptSerializer, deserialize the json text into object of type SORDERList, as defined above.
5. You will now have a list of orders which can be iterated through to perform any additional tasks.

   

Calling the REST URL to return Sales Order Details

The example above returns a list of sales orders. What if you wanted to take one of the sales orders, and return details? The following function will obtain sales order details for a sales order transaction number.

The GetOrder function returns details for a single Sales Order. It accepts a Sales Order Number as a parameter, and returns the sales order details. Note that we are now using the $details facet. The URL will include the Sales Order number in brackets. Below are the steps:

1. Construct the URL for the request.
2. Add the Basic Authorization credentials to the request header.
3. Execute the request, and read the response into a string sData.
4. Using JavaScriptSerializer, deserialize the json text into object of type SalesOrder object, as defined above.
5. You will now see the sales order, including the lines item details for the order, in the form of a .net object.

   

Summary

Classic X3 Web Services were in a SOAP format. With Sage X3 Update 7 and later, REST services are now available to consume and interact with X3.