Sage X3 Services installation

Overview

You need to install Sage X3 Services to use Mobile Automation (ADC) for distribution and Mobile Automation (ADC) for manufacturing.

There are two main steps to set up and check the server environment for Sage X3 Services:

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

Note: For Mobile Automation, read how to Install and configure Mobile Automation on all your devices.

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

Prerequisites

The Sage X3 Services component requires at least Sage X3 2021 R2 (V12) installation using a Microsoft® SQL Server or an Oracle database.
You must install it on a Windows Server 2019 or 2022 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:

Since 2024 R1

  1. Unzip x3-services-M.m.P.b-win.zip in the target folder (example: D:\SageX3\x3-services).
  2. In the target folder, a template called xtrem-security-template.yml is provided. You need to duplicate that file and rename it to xtrem-security.yml. In the renamed file, change the clientId and secret to 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.com
syracuse:
    clientId: create-your-own-client-id-uuid
    secret: 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. Setup the client ID and secret in the X3 global settings.
    Note: The secret should match the secret used to configure GraphQL. The secret must have at least 20 characters. Go to the lastpass or passwordsgenerator websites to generate a strong secret.

  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 from the previous installation folder. 
     PS D:\SageX3\x3-services> .\uninstall.ps1
  7. Enter the following command from the new installation folder. 
    PS D:\SageX3\x3-services> .\install.ps1
Install 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 Sage X3 Services is up and running in the Windows services list.

Before 2024 R1

  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.com
syracuse:
    clientId: create-your-own-client-id-uuid
    secret: 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.ps1
Install 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/ping
StatusCode        : 200
StatusDescription : OK
Content           : {}
RawContent        : HTTP/1.1 200 OK
                    Vary: Accept-Encoding
                    Connection: keep-alive
                    Keep-Alive: timeout=5
                    Content-Length: 2
                    Content-Type: application/json; charset=utf-8
                    Date: Wed, 04 Nov 2020 17:01:56 GMT
                    ETag: W/"2...
Forms             : {}
Headers           : {[Vary, Accept-Encoding], [Connection, keep-alive], [Keep-Alive, timeout=5], [Content-Length, 2]...}
Images            : {}
InputFields       : {}
Links             : {}
ParsedHtml        : mshtml.HTMLDocumentClass
RawContentLength  : 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: 8765
storage:
    managedExternal: true