In the first blog of our 5 Days of Web Services Series, we mentioned the importance of using web services, how they can provide real-time interfaces between your Sage X3 instance and external third-party or customer applications, and how to create a SOAP pool. The second blog focused on creating and publishing web services by exposing objects and creating subprograms. The third blog focused on testing the published web services through object-based and sub-program testers. Today, we'll create a new .Net project to consume an object-based web service from WSDL.
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.
Start with a new .Net solution, using Visual Studio. In this example, I am creating a Console App with Visual Studio 2019.
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. If this happens, contact our support team or your Customer Success Manager for more help.
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.
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.
Below is a sample .net context initialization.
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.
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.
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.
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.
1. The first step is the initialize the call context and the basic authentication properties.
2. When updating an existing record, the object key(s) for that record must be provided. In this example, we are providing the 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. When modifying an existing record, it returns the full XML for modified created record.
5. 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.
6. In the example provided below, the only changes are to the Customer Order Reference (CUSORDREF) and to the quantity ordered for each line (QTY).
7. Below is the full code. This function updates an existing sales order using the SOH object.
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.
For some Sage X3 videos, head over to our YouTube page and subscribe to stay up-to-date with the latest insights and tutorials. Our channel is dedicated to providing valuable resources for businesses looking to optimize their financial management with Sage X3.
Day 1 - Creating a SOAP Pool
Day 2 - Creating and Publishing Web Services
Day 3 - Testing Web Services
Day 5 - Consuming X3 Subprogram Web Services from .Net