Sage X3 Services installation

Overview

This document provides information on how to set up and check the server environment for Sage X3 Services. There are two main steps:

1. Install Sage X3 Services
2. Configure the database connection in the Syracuse server

Important: Use a PowerShell prompt with administrator privilege for all the commands below.

Prerequisites

The Sage X3 Services component requires Sage X3 2021 R2 (V12) installation using a Microsoft® SQL Server or an Oracle database.
You must install it on a Windows Server 2016 or 2019 operating system.

The Sage X3 Services component is not available on Linux.

'hostname':'port' combinations used by client devices to reach the application must also be reachable by the X3 Services server and correctly defined in Syracuse.

You need to have one of the following badges associated with your user:

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

Install Sage X3 Services

Follow these steps to install Sage X3 Services:

1. Unzip x3-services-M.m.P.b-win.zip in the target folder (example: D:\SageX3\x3-services).
2. In that folder, edit the xtrem-security.yml file and change the clientId and secret with your own values.
   Note: The secret must have at least 20 characters. Go to the lastpass or passwordsgenerator websites to generate a strong secret.
3. Set the loginUrl with the public URL of your server.

   loginUrl: https://public-syracuse-server.example.comsyracuse:clientId: create-your-own-client-id-uuidsecret: change-to-use-a-strong-secret-for-your-client-id

   Note: Respect the rules regarding special characters like backslashes in YML files. You can learn more on this topic on the yaml.org website.
4. In the Syracuse server installation folder, edit the nodelocal.js file to add or edit the etna section without the [...] markers.

   exports.config = {[...]etna: {security: {clientId: "create-your-own-client-id-uuid",secret: "change-to-use-a-strong-secret-for-your-client-id"}}[...]};

5. Make sure you have the bearer authentication mode enabled in in the list of authorized auth methods in the nodelocal.js file.

   exports.config = {[...]session: {auth: ["oauth2", "bearer"],}[...]};

6. Open a PowerShell prompt with administrator privilege and uninstall any running Sage X3 Services.

   PS D:\SageX3\x3-services> .\uninstall.ps1

7. Enter the following command from the target folder.

   PS D:\SageX3\x3-services> .\install.ps1Install complete.Start complete.PS D:\SageX3\x3-services>

   This command creates a Sage X3 Services Windows service. Make sure that the Install complete and Start complete messages return.
8. Verify that the server is up and running. Run invoke-webrequest http://localhost:8240/ping and make sure that StatusCode : 200 is returned.

   PS D:\SageX3\x3-services> invoke-webrequest http://localhost:8240/pingStatusCode : 200StatusDescription : OKContent : {}RawContent : HTTP/1.1 200 OKVary: Accept-EncodingConnection: keep-aliveKeep-Alive: timeout=5Content-Length: 2Content-Type: application/json; charset=utf-8Date: Wed, 04 Nov 2020 17:01:56 GMTETag: W/"2...Forms: {}Headers : {[Vary, Accept-Encoding], [Connection, keep-alive], [Keep-Alive, timeout=5], [Content-Length, 2]...}Images : {}InputFields: {}Links: {}ParsedHtml : mshtml.HTMLDocumentClassRawContentLength : 2

Change the Sage X3 Services listening port

This step is not mandatory.

By default, port 8240 is used. You can change this by editing the xtrem-config.yml file to add the port parameter with another value. Then restart the service.

Example

port: 8765loginUrl: https://public-syracuse-server.example.comsyracuse:clientId: create-your-own-client-id-uuidsecret: change-to-use-a-strong-secret-for-your-client-id

Configure the X3 solution

You need to configure the X3 solution in the Syracuse administration pages for the Sage X3 Services connection to work with your Sage X3 application.

Depending on the Sage X3 application database type, you need to configure an SQL Server service or an Oracle service.

Configure an MS SQL Server service

Go to All > Administration > Administration > Endpoints > SQL Server service and edit the following fields:

Configure an Oracle service

Go to All > Administration > Administration > Endpoints > Oracle service and edit the following fields:

Update the X3 solution instance

Once you have created the appropriate SQL server or Oracle service, edit the X3 solution to fill in the following fields:

Note: If the Sage X3 Services URL is not displayed, select the Default authoring.

Configure the SOAP pool

You need to configure and start a SOAP pool for the X3 endpoint that will be used by Sage X3 Services integration. For further information, consult the Classic SOAP pools configuration documentation.

Note: If you have multiple SOAP pools for a given endpoint, the first one is used.

Navigate to the handheld application

Important: Restart the Syracuse agent service to reload the nodelocal.js configuration.

Open the handheld page: https://loginUrl/handheld/

Example: http://syracuseserver:8124/handheld/

Resize the handheld application on a PC

Note: This section is relevant only if you open the handheld application on a PC.

You need to size the screen correctly to replicate a width between 3.5 and 6 inches.

1. In your Chrome browser, go to More > Install Sage X3.
   
2. A confirmation window pops up. Click Install.
   
3. The following screen displays.
   
4. You can resize the window manually to a size similar to the one of a portable device.
   
5. A shortcut has been created on your desktop.
   

Chrome is the recommended browser for Sage X3 Services because the web view embedded in the web application uses Chrome for scanning and the camera.

It is possible to use Edge for demo purposes as long as you do not use the scanner (Settings and more > Applications > Install the site).

Portable devices

Note: Sage does not provide the devices.

The browser required to connect to Sage X3 Services is Chrome version ≥ 45.

Select or scan the URL on first use and add it to the Home screen to easily access the web application login page the next time.

Transactions have been tested using:

• Zebra MC930B-GSEEG4NA and Zebra MC930P-GSCDG4RW. The required OS is Android and the minimum version is 8.1.
  MC9300 was initially released under OS Android 8.1 and Zebra now also offers Android 10. Consult the MC9300 support documentation.
• Zebra MC339R-GF2HG4EU and Zebra MC330K-GI2H. The required OS is Androïd and the minimum version is 7.1.
  OS available for MC3300 (1st generation) are Android 7.1.2 (Nougat) and 8.1 (Oreo). Consult the MC3300 support documentation.
  OS available for MC3300x (2nd generation) are Android 10, 11 for 2021 and 12 for 2022. Consult the MC3300x support documentation.

According to Zebra, other Zebra MC33xx and MC93xx devices with the same configuration can work however they have not been tested.

MC33 limitation: On the physical keyboard, it is possible to select the first letter but not the second and the third. To manage that, you need to scan or use the virtual keyboard.

Scanner: 2D imager scanning 1D and 2D codes (barcode, QR code, and Datamatrix simple code).

Update a previously installed version

Follow these steps to update the Sage X3 Services component:

1. Save a backup of your previous version.
2. Open a PowerShell prompt with administrator privilege.
3. Enter the following command from the target folder:

   PS D:\SageX3\x3-services> .\uninstall.ps1Uninstall complete.

4. Follow the installation procedure.