In the first blog of our 5 Days of Web Services Series, we mentioned the importance of using web services and how they can provide real-time interfaces between your Sage X3 instance and external third-party or customer applications. We also discussed how to create a SOAP pool. Today, we'll focus on creating and publishing web services by exposing objects and creating subprograms.
5 Days of Web Services Series:
- Day 1 - Creating a SOAP Pool
- Day 3 - Testing Web Services
- Day 4- Consuming Web Services in .NET
- Day 5 - Consuming X3 Subprogram Web Services from .Net
Day 2 - Creating and Publishing Web Services
How to Expose a Sage X3 Object as a Web Service
Once logged in to your Sage X3 instance, navigate to Development > Script dictionary > Scripts > Web services.
Click the “Plus” icon on the right-hand side of the screen to add a new web service.
Although Publication name and Type are the only two fields required to configure a new web service, we highly suggest filling in the publication name description, object, and transaction fields as well. I'll define their purpose and the information I've entered in the example below:
- Publication name: this is the web service publication name. It should begin with “Y” or “Z”, indicating it is a partner or customer customization.
- Example: YWSSOHECM
- Description: enter a description for the web service.
- Example: Sales Order Web Sync
- Type: for objects, select the type of Object. Sub-programs will be covered in the next section.
- Example: Object
- Object: enter the object name for the web service to be published.
- Example: SOH
-
Transaction: if the object is transaction-based, the transaction must be selected. Since the number of fields for web services is limited, if too many fields are published, an error will occur. To limit the number of fields published for the web service, select a transaction that has minimal fields enabled.
- Example: ECM
Once you've finished entering the information, click on the “Create” icon (the checkmark) on the right-hand side. A message will appear indicating that the web service has been created, and now you can click the "Save" icon on the right-hand side.
After the web service is created and saved, the “Publication” button will be enabled. Once you click the “Publication” button, the Publication date will be updated.
How to Create a custom sub-program to call as a web service
Custom subprograms can also be created and called as web services. The example below retrieves a list of customers who were updated in the past n days.
Step 1: Create the 4GL Source Code
First, we have to create the Sage X3 4GL Source code in order to create a subprogram to be called as a web service. Once you're in Eclipse, navigate to File > New > Safe X3 Source File.
Next, enter the file name or browse for it and select Finish. In the example below, my source folder is "X3V12DEV_DENISE" and the file name is "YCUSTLIST".
Enter the Sage X3 4GL code below to select the customers from Sage X3.
Make sure to compile the code which will be used to create the subprogram.
Step 2: Create the Sage X3 Subprogram
Now that you've created and compiled the 4GL source code, we can create the subprogram. Once you've logged into Sage X3, navigate to Development > Script dictionary > Scripts > Subprograms.
- File: this is the source file name created in Eclipse
- Example: YCUSTLIST
- Subprogram: enter the subprogram name as it was created in the source file
-
- Example: CUSLIST
- Description: enter a description for the subprogram
- Example: Customer List
- Activity code: assign an activity code for the subprogram
- Example: YDCH
- Module: select the module
- Example: Common Data
-
Web services: this must be checked to create a web service
Next, scroll down to the Parameters section located at the bottom of the page. When the subprogram is first created, the Dim values will all default to 1. This represents the number of array elements that can be returned in the web service call. Since we specified up to 100 in the subprogram source, the Dim value for each return field (with the Argument type as Address) must be changed to 100, as shown below.
Once you've updated the Dim values, click on the "Create" icon (the checkmark) to define the subprogram in Sage X3. Next, you'll have to click the "Publication" button located at the top of the screen.
Now that the subprogram has been published, you can navigate to Web services and enter the publication name of the web service name and its description. The web service name should begin with “Y” or “Z”.
In the example below, my publication name is "YWSCUSTLIS," the description is "Customer list," and I selected the "Sub-program" button for the type.
Once you've entered the web service information, click on the "Create" icon (the checkmark) to publish the subprogram as a web service in Sage X3. Next, you'll have to click the "Publication" button located at the top of the screen.
Once you click the “Publication” button, the Publication date will be populated, indicating that the web service is published and ready for use.
The object-based web service and subprogram based web service are now ready for consumption using any programming language, such as C#, Java or PHP.
Want More Sage X3 Features & Functions?
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.
5 Days of Web Services Series:
Day 1 - Creating a SOAP PoolDay 3 - Testing Web Services
Day 4- Consuming Web Services in .NET
Day 5 - Consuming X3 Subprogram Web Services from .Net
