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

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

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

Configure the X3 solution and multi-endpoints

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 your X3 solution to define the Sage X3 Services URL and the X3 database connection:

Optionally, you can define the Sage X3 Callback URL with an internal host URL. This can be done when the public URL can't be used internally or to facilitate the communication between X3 Services and the X3 web server.

By default, the public host will be used. Alternately, you can configure a different Sage X3 Services URLs per endpoint:

Note: If you don't set any value to an endpoint, the URLs defined for the X3 solution will be used.

Configure an MS SQL Server service

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

Field Description Example
Description Description of your service that identifies it uniquely SEED MSSQL service
Instance name Database server host name or IP followed by the instance name if any localhost
localhost\myInstance
Database name Name of the database used by the endpoint sagex3
User Name of the user to connect to the folder SEED
Password Password for the database folder Str0ng-seed-pwd
Connection encryption Signals if the connection between X3 Services and the SQL Server is encrypted.  
Trust server certificate Signals if a trust server certificates exists for the connection between X3 Services and the SQL Server.  

Note: To achieve a fully safe connection between X3 Services and the SQL Server, Connection encryption and Trust server certificate should both be selected during the configuration of an SQL Server service. For further information, consult the SQL Server Configuration documentation.



Configure the outgoing requests

When a client sends a request to a server, the client receives its certificate during the handshake. This certificate is either issued by a well-known Certificate Authority or by a self-signed authority in the case of internal usage.

Node.js trusts the well-known Certificate Authorities curated by Mozilla at the time the binary has been built. If the certificate is not issued by one of these well-known Certificate Authorities or if it is self-signed, the request will fail unless if you explicitly trust it. To do so, you need to edit the xtrem-security.yml file as follows: 

        loginUrl: https://login.dev-sagextrem.com/
        redirectUrl: https://cluster-a.dev-sagextrem.com/home
        jwksUrl: https://login.dev-sagextrem.com/.well-known/jwks.json
        issuer: login.dev-sagextrem.com
        audience: cluster-a.dev-sagextrem.com
        
        tls:
            extraCaFiles:
                - '/path/to/first/ssl/caCert.pem'
                - '/path/to/second/ssl/caCert.pem'

Note: extraCaFiles is an array of paths to the trusted Certificate Authority to add.

Configure an Oracle service

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

Field Description Example
Description Description of your service that identifies it uniquely SEED Oracle service
Host Database server host name or IP localhost
Port Database server port 1521
SID Oracle SID SAGEX3
User Name of the user to connect to the folder SEED
Password Password for the database folder Str0ng-seed-pwd

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:

Field Description Example
Sage X3 Services URL URL of the Sage X3 Services installed in the previous steps http://localhost:8240
SQL service Select the SQL server or Oracle service created in the previous step SEED mssql service

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

Configure the SOAP pool

Note: Since 2024 R1, this configuration is not required anymore.

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.

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.ps1
Uninstall complete.
  4. Follow the installation procedure.