New Technical Features Overview

New Technical

Features Overview

Sage X3 2022 R2 & R3

Raheel Khan - 5

th

October 2022

Contents

Sage X3 Notification Servers For Workflow

• Old MELADX & its limitations

• New Notification Server

• Setting Workflow Email to use Notification Server

• Advantages of New Notification Server

HTML Workflow Notifications

• General parameter settings

• Enabling at the Workflow level

• Themes & Example

• Troubleshooting

SADFSQ Protocol As Opposed To Apache

• Advantages of using the SADFSQ protocol

• Prerequisites to switch to SADFSQ

• New installation

• Existing install & decommissioning legacy components

• Troubleshooting

Page 2

Sage X3 Notification

Server for Workflow Email

Page 3

What is Meladx

Historically (V6) Sage X3 used a basic application called meladx at the runtime level to relay workflow email

messages to an SMTP server. The application can be found in \X3ERPV12\Runtime\bin\ directory

Page 4

Email (From, To,

Subject)

Email body generated by

the workflow message

File name and location in

the

Folders\FolderName\tmp

location

What is Meladx

Once the text message had been relayed to the mail server by

meladx.exe, there is an accompanying .tra (trace) file created

For example, you could manually call MELADX with the

required parameters to send the email.

Page 5

Parameters

-v Generate trace file

-s Mail server

-r Sender address

Meladx Limitations

• There are no SMTP authentication options for the Meladx binary the only parameter available is SERMES which is used to define the address

of the SMTP server.

• Customers always had to use a third-party SMTP server to relay messages if authentication is a requirement.

• Customers need to authorize SMTP relay from the X3 mail server to the external mail server.

• Emails are always sent in plain text. There is no options of using HTML

Page 6

SERMES the only parameter

available to define your

mail server name

Sage X3 Notification Server

Sage X3 has embedded the notification server function since PU9. It would be primarily utilized to send out notifications for defined events,

like license expiry web service consumption and web service slow-down events. With the latest release, we can now utilize the notification server

to dispatch workflow emails

The notification server uses the nodemailer open-source module for node.js as its underlying technology https://nodemailer.com/about/

Page 7

There is the possibility of having

multiple notification servers for

different activities and to also define

notification themes

Using Workflow Email With Notification Server

With the release of Sage X3 2022 R3, we can now utilize the

Sage X3 notification server to dispatch workflow emails

instead of the old MELADX program.

This is optional and you can still use the MELADX included

with the Sage X3 runtime if you prefer

You can define and configure the notification server

Administration, Server, NotificationServers entity

Features include

• Advanced authentication settings in the security section

you can enable TLS connection and use certificates to

secure your connection if your mail server supports this.

• Basic authentication options with username and

password to connect to your SMTP server

• SMTP Pooled connection and timeout settings for the

connection to your SMTP server.

• The message configuration section allows you to

configure the theme you want to use with this

notification server & the sender email address of mail

dispatched from the server.

Page 8

Using Workflow Email With Notification Server

• Test the notification server Administration, Administration, Server, Notification Servers

• Set workflows to use the notification server Parameters, General Parameters, Parameter values (ADPVAL)

Page 9

Set the parameters in the Supervisor (SUP) module workflow group

(GRP).

SYRMAIL – Set Parameter to Yes to use notification server as

opposed to MELADX for the particular endpoint. NO is the default

value.

SYRAMAILSRV – Set to the name of your notification server, you

can have multiple notification servers one for workflow and

another for other notifications.

Summary

Page 10

• Reviewed the existing MELADX

• How we can use notification servers as a replacement

• The advanced authentication features available

• How to switch workflow to start using the notification servers.

HTML Workflow

Notifications

Page 11

HTML Workflow Notifications

With the introduction of the notification server for workflow email, we can also send HTML formatted emails

1. Set the general parameter setting (ADPVAL)

Page 12

Set the parameters in the Supervisor (SUP) module workflow group

(GRP).

SYRMAIL – Set Parameter to Yes to use notification server as

opposed to MELADX

SYRAMAILSRV – Set to the name of your notification server, you

can have multiple notification servers one for workflow and

another for other notifications.

2. Enable an HTML theme for the notification server, this is selected in

the notification server settings. Sage X3 is shipped with one SAGE

Factory theme called sage-theme Administration, Administration,

Server, Notification Servers

HTML Workflow Notifications

3. In the workflow rule setup (parameters,

workflow, workflow rules) GESAWA we need to

select the option ‘use a theme’ this then picks

up the theme set at the notification server level

and uses this as the container for the workflow

messages.

Page 13

One advantage is that there is no need to modify the

workflow message setup if you are switching from

using plain text notifications

Workflow Notification Themes

You can create a theme for each of your notification servers. Using the notification themes function which is accessed from the right menu in the

notification server entity

Page 14

In the notification themes function, you can

insert your template HTML body there is no

fully-fledged editor so you may need to use

an external application to create to form the

body of your email.

You can also upload images to be used

embedded in the template

We are expecting further enhancements to

the theme designer in subsequent releases.

Workflow Notification Themes

Page 15

• The themes use HTML and mustache format tags, mustache tags begin with two opening

braces ({{) and end with two closing braces (}}) and contain a variable, that will be

populated with data from the workflow message.

• Because of the use of this format there is no need to modify your workflow message, the

same message can be utilised for HTML & Plain text emails.

• You can also have conditions for example {{#link}} {{link.label}} {{/link}} so Link label

will be visible if data is passed to the link.label variable.

More detailed info on mustache (logic-less templates) can be found on https://mustache.github.io/mustache.5.html

Tag name that can be used in the template

Contents

content

The body content of the mail.

signature

The name of the signer.

title

The title of the email.

subtitle

A subtitle for the mail.

link.href

The link reference if the email includes a link.

link.label

The link reference if the email includes a link.

date.label

The current date (localized string).

date.value

The current date value.

time.label

The current time (localized string).

time.value

The current time value

HTML Workflow Notifications

Page 16

This is an example of a purchase order request email received without a theme applied and with the standard factory sage-

theme applied.

Time variables

<href> style link

Embedded Image

HTML Format body

Raw text from the

workflow

Advantages of Notification Server for Workflow Email

• SMTP Authentication options enable a secure connection to the customer’s email server

• No need for a local mail server to relay messages from Sage X3

• Ability to use HTML utilizing themes in workflow emails

• You can imbed images in the theme that will be sent with the email

• Text and formulae setup remains the same in the Workflow setup so you can seamlessly switch to HTML

without the need to modify the workflow message content.

• You can also switch back to plain text if the need arises

Page 17

Troubleshooting the Notification Server

In global settings, you can enable node JS level logging for notification & notification service which will write to the Syracuse

logs. The debug level will show the HTML output of your HTML template and see the parameters passed to the variables as well

as the other useful information for troubleshooting

Page 18

The notification server configuration name, from & to

address of the generated email

The RAW HTML with the mustache variables being passed to

the template

Text & mustace variable section we have all the information

from X3 passed into the variables and body of the email

formed

Troubleshooting the Notification Server

An issue that we came across in our internal testing was we found that when using Mozilla thunderbird as your

email client the signature links were not clickable, and the image was not displayed correctly. We expect this to

be a setting in thunderbird as in outlook the same message is correctly formed.

Page 19

Troubleshooting the Notification Server

The notification server settings and notification themes are all stored in new collections in Mongo DB

Page 20

NotificationEmailTest – This collection contains a log of all the test emails sent

NotificationServer – Collection contains the definitions of the Notification Servers

NotificationTheme – Collection contains the definition of the notification server theme including the HTML

Summary

Page 21

• Using HTML notifications for Workflow

• Themes and how they use templates

• Compared a plain text email with one using a theme

• Advantages of notification servers

• Troubleshooting the notification servers

Using SADFSQ

protocol opposed to

Apache for Sage X3

Page 22

Using SADFSQ Protocol opposed to Apache

Sage X3 uses an Apache HTTP server to transfer static files from the Sage X3 application server to the Sage X3 Web

presentation layer (Syracuse). From 2022 R2, Apache is no longer needed. Static files can now be transferred using the native

application protocol known as SADFSQ.

Some examples of static files are exports from grids, local exports to excel and transferring files from storage areas.

Advantages of using SADFSQ

• SADFSQ is already used for internal communications; the print server embeds SADFSQ to transfer reports.

• No need to deploy the separate Apache web server component, which simplifies the Sage X3 deployment

• Using SADFSQ reduces the potential for security vulnerabilities in the third-party component like the Apache log4j

vulnerability (CVE-2021-44228) seen in November 2021

• Internal testing showed no performance degradation when using the SADFSQ Protocol

Page 23

Prerequisite to Switch to the SADFSQ Protocol

The feature is available from Sage X3 version 2022 R2

• Syracuse 12.15

• Runtime & ADXAdmin 94.1.17

• Console 2.54

Legacy components cannot be used with the native SADFSQ Protocol, so they should be decommissioned before switching

protocols.

Java Web (VT) Web Server – used for the old ADC (typically hand-held RF terminals)

• Java Bridge component is a deprecated component. However, it can still be installed to support legacy outgoing web

services (SOAP)

Page 24

Using SADFSQ in a New Installation

Page 25

With all new installations, the

recommendation is not to deploy

Apache

1. When configuring the

application, set the use Apache

flag to ‘False’. This will be the

default on a new installation

2. Save and Configure the

application; the console will not

look for the Apache HTTP server

installation and will no longer

create the Apache service

3. Set the solution file protocol to

X3 Protocol (SADFSQ) to use the

native Sage X3 protocol

Legacy components and switching to use SADFSQ

Once you meet the prerequisites, the following steps can be performed to switch to the native

SADFSQ Protocol

1. Backup your solution/environment by way of an environment snapshot

2. Unpublish/unconfigure VT Web server from Sage X3

3. Unpublish/unconfigureJava Bridge Server from Sage X3

4. Uninstall / Remove windows services

5. Switch console parameter to ‘false’ and configure the application

6. Switch solution settings in Sage X3 to use SADFSQ

Page 26

Decommission VT Web Server From Sage X3

Sage Management Console

1. Navigate to the ADC Server

module in the Sage X3

management console

2. Select the solution and view the

published folders

3. Deselect the folders

4. Apply publication

5. Select X3 solution identifier and

unpublish the solution

6. Unconfigure the ADC Server

7. Remove the ADC Server from

Page 27

Decommission VT Web Server From Sage X3

Windows Steps

1. After the decommission in the

Sage X3 management console the

services for the Web server will be

removed.

2. In the windows control panel

uninstall the component

3. The ‘WEB’ entry in the adxinstalls

will also now be removed.

Page 28

Decommission components (Java Bridge Server)

Steps in Sage Management Console

1. Navigate to the Java Bridge Server module

in the Sage X3 management console

2. Select the solution identifier to load the

published folders

3. Unpublish your folders from the Java Bridge

Server

4. Apply the publication changes

5. Unpublish the solution from the Java bridge

server

6. Unconfigure the Java Bridge Server

7. Delete the Java Bridge entry from the

console

Steps in Windows

6. Uninstall from the windows control panel

Page 29

Switching to use SADFSQ

In the Sage X3 Management console

1. Log into the solution. As long as you

have the required components, the ‘Use

Apache’ parameter will be available in

the application server section

-Syracuse 12.15

-Runtime & ADXAdmin 94.1.17

-Console 2.54

2. Set the parameter to ‘No’ in the

console. It will change the value to

‘False.’

3. Save the configuration

4. Configure the application

5. Confirm all tasks are completed

successfully

Page 30

Switching to use SADFSQ

In Syracuse

1. Navigate to the X3 solutions in

Administration, Administration,

Endpoints

2. Click edit on the page

3. Change the file protocol setting

to use Sage X3 Protocol SADFSQ

4. Save the settings

5. Sage X3 is no longer using the

Apache service so that we can

disable this in windows

6. Test that you can access a

classic page without any errors

and download files

7. Finalize all other testing

Page 31

Disabling Apache in windows

You can now disable the Apache service in windows, by launching the services.msc console, stop the service and set the

startup type to disabled.

Page 32

• Restart the server and complete your testing with the Apache service

disabled.

• It is not recommended to uninstall Apache if the application was

initially deployed using Apache

• If you do decide to remove the Apache binaries, the application server

component will need to be removed and reinstalled, which is not

recommended

Troubleshooting

Errors during legacy component uninstall in Windows

When attempting to uninstall the legacy components from

the windows control panel, the Error “This component is

currently used and cannot be uninstalled” is displayed

This error occurs when the adxinstalls.xml file does not clear

down after the un-configuration of the component

1. Navigate to the AdxAdmin\inst\ADXinstall.xml file

2. Backup the file

3. Delete the <module> to </module> section for the

component you are uninstalling. For example, for the web

server, delete the WEB section.

4. Save & Restart the AdxAdmin Service

5. You will now be able to uninstall the component

Page 33

Troubleshooting

Syracuse display warning

When using the SADFSQ protocol with

Syracuse 12.16.0.40 you will notice some

warning messages in the solution itself

and the solution list these messages can

be ignored and are expected to be

removed in Syracuse 12.17

Page 34

Summary

Page 35

• Advantages of using SADFSQ

• We went through the prerequisites to switch to using SADFSQ

• Unpublishing & unconfiguring legacy components

• The steps in a new install

• Process to switch to the SADFSQ protocol in an existing install

Useful Resources

Blog Post on switching to SADFSQ

https://www.sagecity.com/us/sage_erp_x3/b/sageerp_x3_product_support_blog/posts/replacing-Apache-with-the-native-x3-

application-protocol

Notification servers online help

https://online-help.sageerpx3.com/erp/12/staticpost/notification-servers/

Nodemailer – underlying technology used by Notification Server.

https://github.com/nodemailer/nodemailer-smtp-transport/blob/master/README.md

Information about mustache templates

https://www.elated.com/easy-html-templates-with-mustache/

Page 36

Sage logos, and Sage product and service names mentioned herein

are the trademarks of Sage Global Services Limited or its licensors.

All other trademarks are the property of their respective owners.

Questions

Sage logos, and Sage product and service names mentioned herein

are the trademarks of Sage Global Services Limited or its licensors.

All other trademarks are the property of their respective owners.

Thank you!