Day 4 Consuming X3 Object-Based Web Services from .Net
This is Part 4 of a 5 part series on creating and consuming web services for Sage X3 Version 12. This part will focus on creating web services. In Part 1 we discussed setup of a Sage X3 Web Services Pool, and in Part 2 we discussed creating and publishing web services based on X3 objects and subprograms, and in Part 3 we discussed using the X3 web services tester to test and evaluate web services.
Consuming X3 Web Services in .Net
X3 Web Services can be consumed from .net by using the web services WSDL from X3. Below are the steps to creating a new .Net project to consume X3 web services.
Create the .Net Solution and Add the X3 WSDL
Start with a new .Net solution, using Visual Studio. In this example, I am creating a Console App with Visual Studio 2019.
1. Obtain the wsdl for the X3 web services from X3. Go to Administration > Administration > Administration > Web Services > Classic SOAP Web services.
2. Click the “CadxWebServiceXmlCC” link.
3. Right-click on the Url, and select Copy link address.
4. In the Visual Studio Solution, right-click on the project, and select Add > Service Reference.
5. From the Add Service Reference window, click the “Advanced” button.
6. From the “Service Reference Settings” window, click the “Add Web Reference” button.
7. In the “Add Web Reference” window, paste the X3 Web Service URL into the URL box, then click the arrow to the right of the URL.
8. The wsdl definitions will appear in the box. If this does not appear, the wsdl URL is incorrect or inaccessible.
9. Change the Web reference name to X3WebService, and click “Add Reference”.
10. The X3 Web Service wsdl will now be in the .Net solution, as shown below.
Create the Authentication Class
Since the X3 Web Services use Basic Authentication, a common class can be created to be used by all web service calls.
1. Create a class called CAdxWebServiceXmlCCServiceBasicAuth.cs, as shown below.
2. Below is the source for the class.
Initialize the Context
Below is a sample .net context initialization.
- X3 Language - i.e. “ENG”
- X3 WS Pool – this is the name of the web service pool defined in X3. This may or may not be the same as the endpoint, depending on how it was set up.
- Context – variable properties are defined here, including the return format (XML or JSON).
- Web Services Endpoint – this is added to the .config file by default when the WSDL is added to the project, but it can be changed. It should be specified here to override the original definition.
- Credentials – this is an X3 user. The user must be set up in X3 to allow web services access.
- Timeout – this can be increased if timeouts are occurring in web service calls.
- Object Keys – these are required for some types of web service calls, to read/update specific record, etc.
Error Handling
1. The web service resultXML will contain a status of 0 (failed) or 1 (successful)
2. If the status is 0, the error messages will be returned as an array of type CAdxMessage. These can be evaluated for severity, along with the message text.
3. If the status is 1, the web service was successful. The web service result can be deserialized from an XML or JSON string into a pre-defined class.
Call an X3 Object Web Service to Query the Left List
Calling an object-based web service to query a list of the object requires use of the “query” method from the web services. Below is an example of the calling the YWSSOH subprogram that we created in the Day 2 series.
1. The first step is the initialize the call context and the basic authentication properties.
2. For the query method, you can optionally specify object keys to further filter the results. In this example, it is filtering the results based on a customer number (BPCORD).
3. The List Size is required, and designates the maximum number or items to be returned in the query.
4. The pre-defined class that the results are deserialized into is shown below.
Call an X3 Object Web Service to Read Object Details
Calling an object-based web service to read a record returns the full details for that record. This requires use of the “read” method from the web services. Below is an example of the calling the YWSSOH subprogram that we created in the Day 2 series.
1. The first step is the initialize the call context and the basic authentication properties.
2. For the read method, you must specify the object key(s) for the record to be read. In this example, it is using the sales order number (SOHNUM).
3. The pre-defined class that the results are deserialized into is derived based on the SOH object web service definition, and will vary based on the transaction definition.
4. Below is the full code. This function reads a sales order using the SOH object.
Call an X3 Object Web Service to Create a new record
Calling an object-based web service can be used to create a new record. This requires use of the “save” method from the web services. Below is an example of the calling the YWSSOH subprogram that we created in the Day 2 series to create a new sales order.
1. The first step is the initialize the call context and the basic authentication properties.
2. The pre-defined class that the results are deserialized into is derived based on the SOH object web service definition, and will vary based on the transaction definition.
3. When creating a new record, it returns the full XML for the newly created record.
4. Although the object contains a lot of XML nodes and fields, only the fields that are being specified need to be provided. This means the full XML for the object does not need to be supplied.
5. Below is the full code. This function creates a new sales order using the SOH object, and returns the newly created sales order number.
Call an X3 Object Web Service to Modify an existing record
Calling an object-based web service can be used to modify an existing record. This requires use of the “modify” method from the web services. Below is an example of the calling the YWSSOH subprogram that we created in the Day 2 series to modify an existing sales order.
- The first step is the initialize the call context and the basic authentication properties.
- When updating an existing record, the object key(s) for that record must be provided. In this example, we are providing the SOHNUM.
- The pre-defined class that the results are deserialized into is derived based on the SOH object web service definition, and will vary based on the transaction definition.
- When modifying an existing record, it returns the full XML for modified created record.
- Although the object contains a lot of XML nodes and fields, only the fields that are being changed need to be provided. This means the full XML for the object does not need to be supplied.
- In the example provided below, the only changes are to the Customer Order Reference (CUSORDREF) and to the quantity ordered for each line (QTY).
- Below is the full code. This function updates an existing sales order using the SOH object.
Conclusion
You have now learned how to create a .net program to call the query, read, save and modify methods of an object-based web service.
More in this series
Day 1 - Creating a Classic SOAP Pool
Day 2 - Creating and Publishing Web Services
Day 4- Consuming Web Services in .NET
Day 5 - Consuming X3 Subprogram Web Services from .Net
GOT QUESTIONS ABOUT WEB SERVICES FOR SAGE X3?
Contact us if you want to learn more about Sage ERP X3 Web Services features or to request help with your system.
