Additional notes when installing or upgrading X3 services (New ADC)

When installing the X3 Services component (sometimes referred to as "New ADC") you should follow the instructions in the online help at https://online-help.sageerpx3.com/erp/12/public/getting-started_Sage-X3-Services-installation.html

This document aims to collate additional notes that you may find useful during this process, by highlighting known issues or other additional useful information.

1. Prerequisites

a. What version of X3 Services should I use
The "Sage X3 Version 12 : Latest Release Information" blog article lists the current recommendations

b. What X3 badges do I need
One or more of the following badges can be used for ADC:

• ADCDIS for distribution
• ADCMAN for manufacturing
• ADCALL for both distribution and manufacturing

You need to setup a role to use these badges, but make sure your Sage X3 license includes whichever badges you are planning to use
Any issues with badges would manifest as a error message "No ADC badge can be granted" when you try to login using the ADC URL such as "http://localhost:8124/handheld"

2. Syracuse configuration of nodelocal.js

a. You need to edit the nodelocal.js as part of the process, to add the authentication method of "Bearer" and to provide the clientID and Secret Key. Make sure you restart Syracuse after editing for the changes to take effect

b. It is important to use an appropriate secret key. By this I mean that not all special characters can be used unless explicitly escaped and this will stop Syracuse from restarting if such characters are not escaped. As mentioned in the online help, you can review the yaml.org website to confirm which characters to use with or without escaping being required, but also put the whole secret key in double quotes in the nodelocal.js file. It might just be easier to avoid special characters.

3. Web service SOAP pool configuration

a. If you already have Web Service pools in use, there is no specific need to create a new one just for ADC (unless you want to). In any case, ADC will use the first web pool for whatever folder you are connecting to.

4. Error messages using ADC

a. After login "Failed to start: cannot read properties of undefined (reading 'sitemap')"

This is likely some issue with the synchronisation of the client ID and/or Secret key between ADC (xtrem-security.yml) and Syracuse configuration (nodelocal.js).
Check for any messages in Syracuse log files. If you see "Cannot generate token: no secret defined in security config" then you may not have defined the secret key in the Syracuse nodelocal.js correctly

b. Error when trying to create a document (1)

"TypeError: Cannot read properties of undefined"
You also see message "self signed certificate in certificate chain" in "xtrem.server-XXX.log"
This is due to using HTTPS URL. See "Additional reading" article 112644 for explanation and solution

c. Can login and navigate around, but when access data get error message "Failed to fetch options"

You also see message "Server requires encryption, set 'encrypt' config option to true" in "xtrem.server-XXX.log"
This is due to the database being configured for encryption. See "Additional reading" article 112949 for explanation and solution

d. Error when trying to create a document (2)

"Cannot read properties of undefined (reading 'stockChange')" (Where stockChange is the type of transaction I am trying to create)
The Syracuse Web Services log file (2022-02-18.SERVERNAME_W0.log for example) shows error soap.request | error | WebServiceExecutor intercept No Pool: X3_Services_ADC Error: No Pool: X3_Services_ADC
The X3 Services log file (xtrem.server-XXXX-2022-02-18.log for example) shows error Error: Failed to get description for web service 'CWSSCS': No Pool: X3_Services_ADC
This is due to the Web Service Pool not being available. Check the web pool is running and can service requests.

5. How can I enable additional logging to help diagnose any issues

Refer to KB article "Diagnosing "New ADC" (Automated Data Collection) issues (aka X3Services) "

6.  ADC Web Services are not copied from X3 folder to new folder during validation

This is a known feature for which the current suggested workaround is to take the web services from a working SEED folder (of the same patch level)  You can manually copy the required records across, or create a patch for AWE objects for the CWS to CWT records.

 Additional information

In a reported instance, the upgrade instructions were followed and the ADC solution was not functioning. The solution was instead of extracting to the existing X3 Services directory, clear this directory out first, then extract the files into this folder. This prevents mismatched files or files not being overwritten properly.

Additional reading

ADC: Cannot read properties of undefined when creating records from ADC connected to HTTPS connection

Mobile Automation Error: "Could not fetch items..." in Purchase Receipt: