Sage X3

Class and Representation Workshop

Support to Business – Frédéric Marie
1/7/2016
 Objectives
Through this workshop you will acquire
autonomy in developing with class
and representation by a hands-on
workshop.

Workshop Agenda
• Part 1 – Introduction to Class &
Representation
• Part 2 – Show case: Develop a
simplified sales order management
At the end of the workshop you will be able to:

• Create and use a class, a representation and its mobile app without
source code to write

• Manage classes and representations with child class and collection

nested

• Setup the home page interface and its components

• Use a class as a service

• Develop scripts to handle all rules, events and methods part of the class
management and its behavior

• Setup and understand different kinds of link on representation

Initial patching of the training environment

To start in a stand alone folder or to redo it:

- Install the SRC_KT_DEV_INIT patch that will install required routines and
elements and clean the existing scripts
- Execute the YFIRST script (Run process function in Development > Utilities >
Miscellaneous menu) to delete existing classes & representation dictionaries with
the same names and fill YCUSTOMER and YITEM tables used later in the
workshop

Note: patches do not include authoring components because they are administration module
elements (menu items, personalization, home pages, mobile apps,…), but only development
features (dictionaries, scripts,…). Authoring components are deliverable by json files.
Part 1 – Introduction to
Class & Representation

• Concepts: metadata and

activity codes

• Table dictionary & data types

• Class dictionary

• Representation dictionary

• Menu item and landing

pages

• Mobile representation
Part 1- What you will
learn

• To create classes &

representations from a
table without source code to
write

• To add menu items in your

X3 page

• To create a mobile
application from a
representation
Meta Data

Sage X3 is using meta data description. This means that the database structure, the entities
managed, their methods, the UI description, the parameters, the navigation is stored as
administration data in dictionaries. The business logic rules are written in scripts using a very
simple language.
This is stored in dictionary tables. A standard dictionary is supplied, but every repository
(folder) can have modifications and additions managed by activity codes.
This makes it very easy to customize a folder by adding elements in the dictionary and
additional scripts.
The transition between versions is also simplified with meta data (the dictionary structure
changes are managed by the platform).
A powerful set of tool (patching system) allows to deliver consistent sets of modifications made
in a development environment to customers.

In a nutshell, the development environment allows our partners and customers to

deliver safely a set of bespoke or vertical adaptations.
Activity codes

The partners have the same development tools than the Sage internal
developers. They can write additional functions, describe additional tables, add new
columns in standard tables, create new scripts that interact with standard one
through entry points, create new pages or update existing pages…

But they use different naming spaces for

their additions and they protect the elements
with activity codes.
This point is fundamental. Activity codes allow
to identify a feature, to activate or deactivate
it, to size an array and to keep the additions
made safely when any update or upgrade
is delivered.

The benefit is simple: develop your vertical, if it is protected by a bespoke or

vertical activity code, it will remain safely in your dictionary and the upgrade is
streamlined.
Here, we will use YOH as an activity code for all the developments done. It belongs
to the range of vertical developments activity codes.
Concepts & Vocabulary

COLUMNS Defines the persistence

DATABASE TABLES (how data is stored)
INDEXES

PROPERTIES
Defines the business logic
CLASSES (what are the consistency
METHODS / controls done, which
(If persistent)
OPERATIONS : operations are possible)
 Creation When this is done, the entity
• Main table
 Read can be managed by web
associated
 Update service, by program, by user
 Delete interface)

PROPERTIES
REPRESENTATIONS Defines the UI (how and
• Device associated ORGANISATION where the fields appear on
• Class used (Sections, Blocks) the page, how can we
navigate from a page to
• Available behaviors NAVIGATION another)
(Filters, Links)
Simple lead management & its mobile app

YLEAD YLEAD YLEAD

table class representation

Lead
manageme
nt
Table dictionary – YLEAD table
Database tables are described in the table dictionary tabs.

The header defines the table code, a description, and an abbreviation used
in scripts.

An optional activity can be defined in the general tab (it can be activated and
deactivated), but also as a marker for a bespoke or vertical module (when it starts
with X,Y or Z) to protect the dictionary elements against standard updates.

Note: Standard activity codes are used to configure the folder , for instance, fields used for a
given legislation, or options that are used only in some activities (lot or serial number
managements for instance). An activity code can be defined at header or detail level of a
dictionary. The lowest level is usually the best: you protect only a field if you add a specific field
in a table, so you will be able to benefit from further modifications on a table; but protect the
table if it is completely specific.
Table dictionary – YLEAD table

The first tab defines the management and delivery conditions of the table, and additional
technical features
 Table dictionary – YLEAD table

The list of columns is described on the second tab of the dictionary.

Policy when data

Column name RTZ function is used
# of occurrences if de-normalized columns

5 technical columns
are automatically
filled by standard
methods that
updates the table

Titles are translatable For references, join expression

and the reference policy
The data type is defined by:
- A type that can be generic (A=alpha, D=date, C=integer) or
representing a reference (BPC=customer code, AUS=user code) Mandatory value
- A length (for generic types) and a local menu (enumerations)
Table dictionary – YLEAD table

On the third tab, we can define the indexes used to access the table

The fourth tab Audit is not used here. It allows to create triggers on a table in
the database in order to track data changes in the current table by filling audit
header and detail tables (AUDITH and AUDITL).

Note: The data dictionary is independent from the database used (SQL Server or Oracle). The
application we will write is completely independent from the database, the operating system,
and even the device, and this is important, because your investments are protected and can be
use on any platform supported the customer is accustomed to.
Class dictionary – YLEAD class

A class describes an entity with its business rules. Here, we have a very simple definition
(only 4 tabs are filled in this case):

The class is
persistent
(values of an
instance are
stored in the
database on the
main table
YLEAD), has the
same activity
code (YOH)

Standard methods are defined

(AINSERT for creation,
ADELETE for deletion, AREAD
to read, AUPDATE for
modification)
Class dictionary – YLEAD class

The property tab contains approximately the same columns that for a table, but additional
information is located here, especially the access code (to protect the property from access
in some cases), and the search policy (searchable flag, additional filter category)

Using “column selection” allows to populate

automatically the property grid from column
tables
Class dictionary – YLEAD class

The mapping table defines the database tables used for the persistence of data. Here, a unique
table (already defined in the General tab) is used, and the database updates will be done by the
engine on read, creation, modification and update.

Note: If this check boxes are not filled, the developer can create the code associated to the
persistence of data by himself. This can be the case for some dedicated classes where the
persistence is done in another way.
Data type dictionary – BPC type

Let’s have a look on the

BPC data type:
• Class tab is the most
important here
• The type is defined as
a reference to the
class BPCUSTOMER
• Default
representations are
available for every
device to implement
zoom on customer
details

The control rules are automatically

generated from data type, but
additional control scripts can be
added

Note: As we can see here, declaring a reference is simple. The reference will inherit
automatically from all the features defined in the class. For instance, if the class defines filters,
the filters can be selected when we define the reference in a class (in the parameters list).
Representation dictionary – YLEAD representation

The representation describes an interface class that is used to access to the data.

A representation has different facets:

• Query defines the record list
• Detail displays the record detail
• Edit is used for creation or
updates
• Lookup is used for selection
from the entity when a
reference exists on it
• Summary is a summarized
view of the data

The first tab defines notably the

activity code (YOH), the class
associated to the representation,
the type of device used, and the
behaviors managed.. The facets
available are deduced from
displayed properties
Representation dictionary – YLEAD representation

Properties and Methods describe additional properties and method defined on the representation
and not on the class (usually for UI purposes). These tabs are not filled here.

The Organization tab describes the default layout (in sections and blocks) and additional features
(filtering options). Here we define only one section and one block
Representation dictionary – YLEAD representation

The displayed property tab describes, for every facet, the different properties that are
displayed and/or entered:

Default UI characteristics (position, description)

Filter means that the property

value can be used for filtering
purposes in query and lookup
Entry means that it can be sent
as a forced value in edit mode

Property path: here YLE.xxx means that this is a property from the main class instance

Unique alias

For every facet, you can define if the property is present or not, if it is Visible by default or
not (this can be changed by user personalization), and if it can be entered
Control, patching and help
Part 1

• Execute the QLFYLE script to test the YLEAD class

• When QLFYLE result is ok, run the YLEADRND script to generate lead records
directly in the table
• To have the official training development install the SRC_KT_DEV_STEP0 patch,
then run YLEADGEN to generate lead records by using the class
• The JSON file Menu_KT_DEV_STEP0.json contains a menu item using the
YLEAD representation

Online help about Class and Representation dictionaries:

Technical help > Development platform > Workbench reference

Menu items, gadgets and landing pages

We have to add a menu item in the UI to access to the representation

Introduction to link on representation
Hands on – Setup to do

On YLEAD representation and CUSTOMER property in edit mode we want to have a

selection box filtered on a country value.

- Add a COUNTRY property on the YLEAD representation

- Add COUNTRY property in the displayed properties tabs and check:
• Query/Detail and Summary as invisible
• Edit as visible and enterable
- On the BPCUSTOMER representation (defined in the BPC data type) check CRY
displayed property as Filter P and visible on lookup facet
- On the YLEAD representation, on Links Tab look at the generated links at
property level
- Select the lookup link of the CUSTOMER property to access to its paramater
- Assign the YLEAD.COUNTRY property to the CRY parameter
Introduction to link on representation
Hands on – Link setup

- Generated links
- Property level

- Lookup link

- CRY parameter
- Filter P
- Parameter value
Introduction to link on representation
Hands on - Result

Only the customer from the selected country are displayed in the lookup
Mobile representation – YLEADM representation

The mobile representation

called YLEADM can be
simply done by duplicating
the representation called
YLEAD,
and by using the mobile
phone type.

That’s all !

Note: that the behaviors and the properties published can be different if needed.
Frequently, a mobile page is simpler than a desktop page.
Mobile application creation

Now we have to publish the application for mobile by creating a mobile

application that has a mobile dashboard including 1 mobile gadget:
Mobile application creation
And now, in our mobile dashboard, we have an additional vignette…

… that brings to a dashboard

with one item…

… that goes to the list of leads!

Part 1 - What you have
learned

• Basics features of class &

representation dictionnaries

• Menu item and X3 page

setup

• Mobile application and its

components
Part 2 – Show case to
develop simplified sales
order management

• Orders business logic basis

• Orders class usages
• Orders business logic
improvement
• Orders UI enhancement
• Orders management for mobile
Simplified sales order management
ORDER Order ID, Customer, Additional field
DOCUMENT Date, Site, Currency, used later: Mobile
Total, Comment, Status phone update date
Order modification
1,N
Item, quantity, unit price,
discount,
Order line price, shipped quantity
Status=ORDERED
creation
Order ID, sequence,
SHIPMENT
Order shipment Date, Customer,
DOCUMENT
Currency, Total
Status=TOTALLY
1,N
SHIPPED Item
Quantity
Order modification
Order shipment
(add lines or quantities)
“I want to manage
simplified sales order on
Status=PARTIALLY desktop and mobile, with a
SHIPPED
Order simplified shipment
modification process”
Step 1 – Orders Business logic basis
Class header & lines management
Part 2 – Step 1

• Child class & collection

• Events on property (Script)
• Global Events (Script)
• Method (stateful mode)
• Data types options
What you will learn with
Part 2 – Step 1

• To handle child class structure

and collections
• To write scripts to manage
controls, initializations or
updates of class and child
class properties
• To write scripts to add global
behaviors into the class
management
• To declare a bespoke
method for a class and writing
the related script
Manage creation and update of sales order

Use a script to handle

- default values
- controls
- events

YORDER YORDER YORDER_CSPE & YLINE_CSPE

table class Rules on properties
• INIT
YLINE YLINE • CONTROL
table class • PROPAGATE
Global events
Local menu Counter • Before creation or update
1001 YOH • Computation method for total

Data type
YDI
Table dictionary – YORDER & YLINE tables

A meta data dictionary that describes the tables present in the database.

On the header, three main information are given:

• The table code is the name of the table created in the database
• The abbreviation will be used to identify table elements later
• A simple description (translatable text)

Four tabs describe the characteristics of the table, but we will only describe
some characteristics on the three first tabs.
Table dictionary – YORDER fields

The columns tab describes the column present in the table.

Main info : column name, data type, length, description, mandatory flag,
additional info that depends from the data type.
Table dictionary – Local menu 1001

The column ORDSTA in YORDER table has been defined as a local menu
(#1001). This corresponds to an enumeration of choices of different values and
messages. The number column corresponds to the value of the ORDSTA field,
and the Message to the label displayed in the user interface.

A local menu can be translated in any language available in the user interface. In
the user interface, it can be see as a combo-box or a set of radio buttons.
Table dictionary – YLINE fields

The columns tab describes the column present in the table.

Main info : column name, data type, length, description, mandatory flag,
additional info that depends from the data type.
Data type dictionary – Options on YDI type

Let’s have a look to the

YDI data type:
• General tab and Class
tab are used in the type
dictionary
• A script performs the
controls and raises the
errors

A control rule has been

implemented in a dedicated script
Table dictionary – YORDER & YLINE indexes

Defines the index that can be used to access the data.

YORDER table: 3
indexes are given (one
as main reference, the
two others have 2
components)

YLINE table: 2 indexes

are given (one as main
reference, the second to
order the lines)
Class dictionary – YORDER class - Header
The class dictionary describes the application logic of the sales order entity.

The general tab describes the main characteristics and especially:

• The type Persistent: related instances are stored in database
• Activity code to protect bespoke / vertical
• Collections to define nested arrays of properties with standard
behaviors implemented (insert, delete, add lines, sort lines)
Class dictionary – YORDER class - Methods

This tab describes methods (stateful) or operations (stateless) that can be used on
a class instance.
• The TOTAMOUNT method computes the total amount of the order by summing
the amount of all the lines.
• We define also the DISC_ERASE method, that will be called from the
representation, to reset to zero discount on lines.
• Additional parameters and/or keys (for operations) can be defined as well for
every method or operation in the two additional grids present on the tab.
Class dictionary – YORDER class – Standard methods

This tab allows defining the standard methods that are allowed to the
class. A persistent class can usually use all the CRUD method (Creation,
Read, Update, Delete)
Class dictionary – YORDER class - Properties

• Defines the class properties (a selection of table columns is available)

• A property can be a children instances collection (sales order lines)
• There is a searchable flag and a category on properties if the class is
searchable
Class dictionary – YORDER class - mapping

This tab describes how the persistence operations (CRUD methods) are managed:
• Header level: main table and operation allowed are defined
• Collection level: join description, key values for join, operation allowed (class
management checkbox means that the child class operations are used)
Class dictionary – YLINE class - Detail
For the line, the structure is simpler: no collections, only the columns
from sales lines (including technical ones), no dedicated method, the
same CRUD methods, a unique “header-type” mapping:
Class dictionary – Adding controls with scripts
As soon as the two classes are defined and nested, the CRUD method are available and
a service can call them to create sales orders.

But usually we have to add some pieces of code to perform controls or to define default
values.

This is done by adding references to scripts in our classes. The scripts are defined in the
first tab of the class. Several scripts (standard, vertical, specific) can be added and their
execution order can be defined:
• On lines, we have a unique specific script

• On the header, two scripts are present, but the first one is the only one that is
necessary for the moment (the second will implement additional features):
Testing and practice
Step 1
• Execute QLFYOH_1 script after the YORDER and YLINES classes creation to
test the classes are correctly created
• Install patch SRC_KT_DEV_EXERCISE-STEP1 with incomplete scripts
• Complete the source code YLINE_CSPE to add:
 Control of the unit price
o Set an error if unit price < 0
 Compute the price after unit price is changed and ok
 Write the subroutine LINE_PRICE
o Price = quantity * unit price * (1 – discount/100), rounded 0.001
• Complete the source code YORDER_CSPE to add:
 DISC_ERASE method
o Loop on LINE collection to reset to zero the discount property
 Call to TOTMAOUNT method after control in creation and update event
YLINE_CSPE script - rules
This script implements consistency rule applying on the lines.
At $PROPERTY label, the rules can be scripted:
• this is the current class, this.PROP is the property PROP
• [L]CURPRO is the current property, [L]ARULE is the rule

INIT: defines default values for a property

CONTROL: performs a control

PROPAGATE: executed when a property was successfully modified

Call the error method

to refuse the control

Routine to compute the line price

YORDER_CSPE script - rules

For YORDER class, we have also rules associated to properties:

• Assignment of the currency when the customer changes (PROPAGATE)
• Default values for ORDDAT (current date) and ORDSTA (1=Ordered)
• Propagation rule for items on line: when the item is modified, call the pricing
function with the item and the currency found in the header (parent instance of
the line)

Let’s perform a database access on that BPCUSTOMER table

for the key value equal to the current customer code.
The customer currency is assigned to this.CURRENCY
YORDER_CSPE script – global events
The global events for YORDER class are running from $EVENT label:
• [L]CURPTH defines the scope ("" at main class level, "LINES" at the LINES
collection level)
• [L]AEVENT is the action type. Here the actions used are:
o Axxxxx_CONTROL_BEFORE : executed before a standard
method; allow you refusing the execution by triggering an error
o Axxxxx_CONTROL_AFTER: allows to perform additional actions

Routine that sets up technical

properties (keys for lines)

Before update, execute

TOTAMOUNT method,
assign the result to
this.TOTAL

Before order creation,

assign a sales order
number if not previously
entered
YORDER_CSPE script – global events

The routines called from the events are defined here:

Sequence number assignment: uses an API based on

the counter code (YOH), the site, the date

Assignment of technical property on all lines:

- ORDNUM (order number)
- NUMLIN (unique number for reference)
- SORTLIN (sorting order, assigned from AORDER property)
YORDER_CSPE script – methods & operation

The label $METHODS is used to handle the methods (stateful):

• TOTAMOUNT returns the total amount of a member of the collection by
using the sum operator
• DISC_ERASE erases all the discounts on the lines

The label $AOPERATION is used to handle the operation (stateless) and is not
used here.
TOTAMOUNT method
Use the sum operator on PRICE
properties in the LINES collection
(range from 1 to the maximum
number of lines given by maxtab)

DISC_ERASE method
Performs a loop on all the lines
and sets the discount to 0
YORDER numbering : YOH sequence number
The YOH sequence number code corresponds to a set up function that defines
sequence numbers:

Here, sequences Here, sequences

are defined at are reset to 0
site level every year

The sequence number

therefore includes :
• the site
• a dash
• the year
• a sequence on 6 digits
Testing, data generation & help
Step 1

• Execute QLFYOH_2 script after the controls added in the class script

• If QLF* are ok, execute the YRANDOM script to generate orders

Online help about Class dictionary, script and events:

Technical help > Development platform > Developper guide

• > Developer Guide Classes Events
What you have learned
in Part 2 – Step 1

• Child class and collection

• Event on properties and
global event
• Bespoke method
• Script structure and labels
for the class management
 Step 2 – Orders class usages
Class usage from a script (as a service) or a representation
 Part 2 – Step 2

• Class as a service
• Log management
• Representation and nested class
• Links for method
• Filter/Entry Parameter
What you will learn in
Part 2 - Step 2

• To use a class as a service

by writing script to work with
this class
• To write script instruction to
handle a log management
• To handle child class in a
representation
• To develop links in a
representation to trigger a
class method or access to
another representation
Manage creation and update of sales order

Create randomly data to test

and measure performances
YRANDOM
Loop calling standard creation method

User interface YORDER

representation

Create random Create Update Orders on a desktop

Read log file
orders page
Use the sales order class as a service (1)
Now we can use the CRUD operation on the class as a service.
A script that creates orders will allow to test the method, to measure the performances, to get
a data set for further tests.
The script is called YRANDOM, and the main routine looks like this:

Initialize arrays of customer

codes, item codes, comments,
sites used to get random values
in the order generation loop

Use a log class to get a trace of the creation

Write a header line in the log file

Perform a loop to create

500 random orders
Write a summary
line in the log file,
close the log file
and display its
name
Use the sales order class as a service (2)
The main routine creates an order and is very simple. It instantiates an order class, uses
AINIT method, assigns instance values, adds lines to the collection, and finally uses
AINSERT method to create the order:
Use the sales order class as a service (3)

The LOG_RESULT routine checks whether the return value is ok or not:

• If not, the error payload is dumped in the log file
• If everything is ok, the order number , the number of lines, and the total are
written on a result line
Use the sales order class as a service (4)
The additional routines are filling an array of random values and delivering random
values used by the previous routine

Select
• sales sites (SALFLG=2),
• Customers (with a repetition of
customers following *1 pattern code)
• Products

and fill the corresponding arrays

Fill an array with a list of comments

Define functions returning random values

• A random code from an array
• A random data between in a range
• A random integer in a range
• A random decimal in a range
Use the sales order class as a service
Process execution

Let’s read the log:

Now we have 500

sales orders
…
User interface: YORDER representation
A representation is a class dedicated to the user interface, that embeds a main class (here the
class YORDER, with the instance YOH protected).

A representation can be protected by an activity code (YOH).

The authorization function is to manage the X3 access right of the user regarding the rules
defined for the associated function.
User interface: YORDER representation
A representation has several facets (use cases) depending on the displayed properties on
each ones, manages behaviors that can be related to facet (Edit facet : Creation, Update and
Delete) and is associated to a device type.
User interface: YORDER representation

This first representation has no additional property nor method. The next tab to be filled is
the representation, that will generate a default layout based on sections containing blocks
User interface: YORDER representation
The displayed property tab defines the properties available in the user interface, for the
different facets. A direct selection can be done from the class.

Every property has a path:

• MYPROP is a property of the representation (we don’t have any yet)
• YOH.FCY is a property of the embedded class instance
• YOH.LINES.ITEM is a property of a collection from the class instance

.
.
.
.

Can the property be For every facet, you can check boxes to define if
List of properties with their path: all
a filter and can its the property is present on it.
their characteristics are displayed,
value be sent in the Additional properties (enterable, hidden, visible
including activity codes
URL? by default) are present
Link on properties
The Link tab defines the navigation links available on the UI. A link can be assigned to a
property, a page, a record, or a collection line.
Here we describe a link from ORDNUM field in the query facet to the detail (by default, the
link is available from an icon on the line, but here it is a detail link)

Display only the

filter associated
to properties

Popup view
of the link
definition
Link to trigger a method

Here we describe a link from the page level only available from the edit facet. This link will call
the DISC_ERASE method from the YORDER class.
The link will appear as a button on the right side of the UI.

Display only the

filter associated
to the page

Popup view
of the link
definition
User interface on a desktop page

Defining a representation associated to classes is enough to run the UI.

It is now possible:
• to query orders
• to create a new order
• to display an order
• to update an order
User interface on a desktop page
The link button to erase discount on lines is available on the edit facet.
Link management: YLEAD/YORDER representations

We can add a very simple but useful feature: have a link that goes from the leads to a page that
lists all the orders created for the customer.

If you look on the representation YORDER (that will be explained in the next steps), you might
see that Filter P and Entry P fields are set to yes for the customer:

This means that the

order lists can be filtered
by customer, and used
as default value when
creating a lead.
Link management : YLEAD/YORDER representations

Now we can add to the lead representation, in the link section, at the record level,
for the facets query and details, a link to the YORDER representation :

If you open the popup

view on the first line,
you can enter this:
Link management: YLEAD/YORDER representations
And now, for this line, you can see that there is a parameter that can be set by selection to the
current customer (YLE.CUSTOMER):

We can now validate the representation, and the links appears directly at the list level and on
the right bar of the details:
Patching & help
Steps 1 & 2

• Install the SRC_KT_DEV_STEP1-2 patch to get the official training

development

• Execute the YRANDOM script to generate orders (if not already done)

• The JSON file Menu_KT_DEV_STEP1-2.json contains a menu item

using the YORDER representation

Online help about Development exemples and best

practices:
Technical help > Development platform > How to guides
What you have learned
in Part 2 – Step 2

• Class as a service
• Log management
• Representation with child
class and collection
• Setup and functioning of the
navigation links of the
interface
Step 3 – Orders business logic improvement
Class interaction, additional controls and methods
 Part 2 – Step 3

• Additional class with no code

• Controls on collection
• Parent properties and snapshot
• Operation (stateless mode)
• Filtering condition on class
What you will learn in
Part 2 – Step 3

• To manage a child class as

basic type: the main class will
handle the standard methods
• To write additional controls and
events on collection lines
• To setup operations and write
its script that uses another class
as a service
• To use progression box and log
file downloading APIs for
asynchronous process
• To setup filtering condition on a
class
Manage shipment order

Create an additional script to

reinforce controls related to
shipping
Create the shipment method

User interface
YSHIP table YSHIP class YORDERSHI_CSPE
Restrict updates on shipped orders YSHIP
• CONTROL on customer, quantity, representation
YSHIPLINE YSHLINE shipped quantity
table class Prevent line shipped lines deletion
Shipment status according to quantities

YSHIP
YORDER
Use creation method on YSHIP class
class
Use update method on YORDER class
Table dictionary – YSHIP table
This table is simpler than the order:

Specific table with YOH activity code

5 fields +
5 technical fields

The index is the order number

and a sequential number
Table dictionary – YSHLINE table
This table is also simpler:

Specific table with YOH activity code

5 fields +
5 technical fields

The index is the order number, the

sequential number, and a line number
Class dictionary – Shipping line class (YSHLINE)
YSHLINE is a very simple basic class: no CRUD methods on it, no other methods, no mapping
information, only the fields present on the shipment line (5+5 technical).
Class dictionary – Shipping class (YSHIP)
YSHIP is a persistent class that includes a SHIPLINES collection.
No script will be used here. The only methods allowed are creation, modification, and read
Class dictionary – Shipping class (YSHIP)

The properties present on the shipping class are the property present in the main table, plus a
collection of shipping lines
Class dictionary – Shipping class (YSHIP)
The properties present on the shipping class are the property present in the main table, plus a
collection of shipping lines

Creation, modification, and read method

implemented for YSHIP table

Creation, modification, and read method implemented for YSHLINE table:

the class checkbox is not set because YSHLINE is not a persistent class
Reinforce the controls in sales order

If we consider that orders can be shipped, we have to add consistency controls and methods:
• ORDER STATUS should be automatically set according to the shipped quantities on the
lines
• FILTERING ORDERS by their shipment status must be possible
• CONTROL ON LINE DELETION: A shipped line cannot be deleted
• QUANTITY MODIFICATION: When modifying an order, the ordered quantities cannot
become smaller than the shipped quantities
• CUSTOMER MODIFICATION must be impossible on a shipped order
• SHIPPED QUANTITIES MODIFICATION must be impossible directly, but only in a
dedicated shipment method (OPERATION property of the YORDER class)
• A SHIPMENT METHOD will be created, and the corresponding written code

To implement these features, we will add an additional script to the YORDER class.
This script is called YORDERSHI_CSPE. The script YSHIP will manage the creation of
a shipment document from an order.
Additional features on sales order class (YORDER)
To manage additional controls and shipment operation the YORDER class has to be modified:
an additional script in the general tab and additional operations in the methods tab.
Filtering condition on sales order class (YORDER)

The miscellaneous tab is notably dedicated to filters. Here, we declare for instance legislation,
company, site, access code properties.

These properties are used to filter the data according to read, write, execution rights granted to
every user on legislations, companies, sites, and access codes.

A list of applicative filters defined by a code and a condition can also be defined.
Testing and practice
Step 3

• Execute QLFYSH script after the YSHIP and YSHLINE classes creation to test
the classes are correctly created
• Install patch SRC_KT_DEV_EXERCISE-STEP3 with incomplete scripts
• Complete the source code YORDERSHI_CSPE to add:
 Control of the delivred quantity
o Set an error if delivered quantity is modified and OPERATION property is
not « SHIP »
 Event to add a line
o Set an error if order status is « invoiced » to not allow the line addition
• Complete the source code YSHIPALL to add:
 Call to SHIP operation set on the YORDER class
 Set a message according to the return value of the SHIP operation
• Execute QLFYOH_3 script after the advanced controls are added in the
scripts
YORDERSHI_CSPE script

this.snapshot.PROPERTY gives access to the previous value of a property

If CUSTOMER was modified and if at least a shipped quantity exist, raise an error

A technical property called OPERATION has been added in the class. On a line
property, we access to this property through the this.APARENT path.
The delivered quantity can only be changed if OPERATION is equal to "SHIP".

QTY control on LINES collection: If the delivery quantity is greater

than the quantity, raise an error
YORDERSHI_CSPE script

Here we implement the events associated to the collection (LINES)

First rule: if ORDSTA (order status) is equal to 4 (invoiced) no line addition allowed

Line deletion is prohibited if the order is invoiced,

but also if a shipped quantity is found on the line

Set QTY to 0 if line is deleted

Order status assignment: we compare cumulated quantities and cumulated shipped

quantities to assign order status to not shipped, partially shipped, or totally shipped / invoiced
YORDERSHI_CSPE script

The shipping operation will be implemented with the SHIP routine in the YSHIP script
The SHIPALL operation is the SHIPALL routine in YSHIPALL script

We have no additional methods associated to the class

YSHIP script – Part 1
The shipment script implements an operation (stateless). When this method is called, this is
an empty order instance, and [L]ORDNUM the key that has been given as parameter to the
operation. We can prepare the work:
• Let’s verify that the order exists and can be shipped
• Let’s check if the operation is autonomous or embedded in a transaction
• Let’s create and initialize a shipment instance that will be filled before creation

Miscellaneous declarations

Let’s use the AREAD method to read the order and fill this instance

If the order doesn’t exist or is not shippable, raise an error (ASETERROR method) and exit

We create a SHIPMENT instance and call the

INIT method to assign the default value
YSHIP script – Part 2
Here, we will fill the SHIPMENT instance, firstly by assigning header values
Then we have a loop on every order line. For every line not completely shipped:
• We add a line in the shipment instance
• We assign the values of the line (item, quantity shipped, key values)
If everything is ok, we create the shipment (method AINSERT)

DLVNUM assignment

Header values

Loop on order LINES collection. Only the lines with QTY>DLVQTY are selected

Add a shipment line at the last position

Assign the different values of the lines.

The shipped quantities are QTY_DLVQTY

Compute the shipment total

Use the AINSERT method on shipment

class to create the shipment
YSHIP script – Part 3
If the creation of the delivery document was successful, we can now update the order lines
by assigning the delivery quantity to the ordered quantity.
The property OPERATION must be set to SHIP to allow modifying DLVQTY.
Using the AUPDATE method will update the database and assign the status of the order to
completely shipped.

Assign OPERATION technical property

Loop on order LINES collection.
Only the lines with QTY>DLVQTY are selected

Set the shipped quantities with order quantities

Use the sales order standard method AUPDATE

Manage the transaction if necessary

YSHIPALL script – Part 1
YSHIPALL is a script that implements a long operation. It ships all the orders associated to
the customer of the current order. As it is long, it has been declared as asynchronous, and
we will here use APIs that shows the status evolution of the task and finally gives access to
a log file.
The first lines are used for variable declaration, log file creation, and to count the number of
order to manage

Variable declarations

Read the current order (the operation is stateless) and raise an error if not found

Count the number of orders and

store their key in YORDNUM array

Declare and open the log

YSHIPALL script – Part 2
For the long operations, the platform provides a set of API that sends messages to
the user interface
These APIs do not trigger anything if called in service mode.

Loop on all the orders

Call the API to display the progression

Create an order instance and call the shipping

operation : YORDNUM(I) is the order to be shipped

Check errors and create the right log lines in the trace file

Check if interruption is requested

Display information about the current step

End of the loop: close the log and display a download link
The shipment representation (YSHIP)
The shipment representation is very simple: it doesn’t allow any CRUD operation except
reading, it has two sections (header/lines) with a block in each, it has no additional method, no
special link, and the displayed properties are the shipment header columns plus the shipment
line collection properties:
The shipment representation (YSHIP)

Now we can use the shipment

representation. The query looks like this page
(except there is no data at the moment).

The detail looks like the second page

What you have learned
in Part 2 – Step 3

• Basic type for a class,

standard method handled by
the main class
• Script for collection
management
• Operation of a class and
interaction between to class
• Filter on a class
• APIs for asynchronous
process
Step 4 – Orders UI enhancement
Advanced usage of the representation
 Part 2 – Step 4

• Representation properties,
methods & script

• Class filters usage

• Embedded link

• Links to trigger asynchronous

operation
What you will learn in
Part 2 – Step 4

• To handle properties, methods

and scripts at representation
level
• To use the class filter in a
representation
• To setup embedded and
asynchronous links in a
representation
• To manage personalization of
the UI facets
Enhance the sales order representation
• Display contact information on sales order details
• Filter the orders by status on the query
• Update grand total every time a line is updated (interface)
• Display shipments list for the order on details
• Add a link that erases the discounts during input
• Display opportunities list for the customer
• Create an operation that ships the order and call it from the UI
• Create an operation shipping several orders in asynchronous mode

Create a enhanced representation: YORDER1

• Add contact information representation
• Use filters on status
• Link to YSHIP and YLEAD representations
• Link to trigger shipment
YORDER_RSPE
PROPAGATE event on CUSTOMER
• Link to erase discount method
• Link to sales order generation
YSHIP script
Implements an operation
Create an additional script
associated to the YORDER representation: YSHIPALL script
• Assign contact information
Open a log file, use API to operation details
• Connect methods & operations
At the end, link to the log
User Interface: YORDER1 representation
General & properties

The representation is the same than YORDER, with just some differences.

A script is associated
to implement
additional actions

Additional properties have

been added
The PHONE property is
linked to the country for
formatting purposes
(parameter of the data type)
Data type dictionary – TEL data type

Let’s have a look on the TEL

data type:
• Class tab is the most
important here
• The type is defined as a string
that has a $phone format sent
to the client. This allows
phone links to be generated
automatically (emails fields
are managed that way)
• Control and Format scripts
are also available: they need
a COUNTRY parameter to be
effective
User Interface: YORDER1 representation
Organization

The representation is the same than YORDER, with just some differences.

A contact block has

been added to store
the contact
properties

Filters can be set up on the

representation to perform
filtering on queries:
• Filters inherited from the
class definition
• Additional filters (not
present here)
User Interface: YORDER1 representation
Method

A dedicated method has been added on the representation (RTZ_DISCOUNT)

No parameter is needed for this method

User Interface: YORDER1 representation
Displayed properties

The representation is the same than YORDER, with just some differences.

The 3 properties added in the representation

have been placed in the CONTACT block
User Interface: YORDER1 representation
Links (1)
The representation is the same than YORDER, with just some differences.

Two links are set up at page level:

• ERA_DIS is a method of the representation (only usable in user interface, this is an
implementation choice). It is called RTZ_DISCOUNT and erases the discount column. It
is a Default link (appears on the right panel)

• SHIP_DISPLAY is a link that displays the query associated to the YSHIP representation .
The link type is embedded and present on the detail facet: this allows to display the list
of the shipment associated to the order. The current order is sent as a parameter to the
query (the order number is defined as a filter property on the YSHIP representation)
User Interface: YORDER1 representation
Links (2)

The representation is the same than YORDER, with just some differences.

Two links are set up at Record level:

• SHIP is an operation that triggers the execution of the shipping operation on the
current record,
• SHIPALL is an operation that triggers the shipping operation for all the orders
having the same customer than the current order. As this operation can be long,
and has to provide a list of the shipped orders, it has been defined as asynchronous
Both run on the order number as current key
User Interface: YORDER1 representation
Links (3)
The representation is the same than YORDER, with just some differences.

An additional link has been added

at the property level (on the customer)

• LEADS is a link that displays the leads

associated to the customer.

• In YLEAD representation BPCNUM

property has to be declared as
Filter/Entry P

• The parameter has been set up

in the corresponding section.
YORDER_RSPE script (properties & events)
The shipment representation uses an associated script.
This script can be used with the same events than the class, in order to perform additional
controls, to implement rules used only when the UI runs.

First rule: every time a price is modified, re-compute the total amount. In the class,
this is only triggered before creation or update, for performance reasons. But if we
want a good interactivity of the UI, it is better to implement it as an interface rule.

Second rule: assign contacts properties in the representation every time the customer is modified

Assign also contacts properties in the representation after loading the order

Discount suppression is implemented with a single loop that sets the

discount to 0. The propagation rule of the class will trigger the line re-
computation and the grand total will be re-computed accordingly.
YORDER_RSPE script (contact read)
This section is the routine that reads the contact information in the YCUSTOMER
table. Here the script is very simple because everything is stored in a unique
table. But we can write code that performs joins between different tables and
selections (this would be the case on Sage X3 because you can have several
contacts per customer.

The call (present on the previous page) sends parameters that are either direct
properties from the class instance (“this” is the order, CURPTH is "YOH"), or
elements from the representation (which is the parent instance accessed with
APARENT pointer):
YORDER_RSPE script (methods and operations)

This last section implements the methods and operations. Here, we have only
one method, RTZ_DISCOUNT, that uses the label previously defined in this script
Enhanced User Interface
The query displays the order lines and all the links are present.

Hyper-link to edit the order

The record links are

present on every line

Filters links are

present. When clicking
Ships the current order on a filter, the list is
filled again
Executes the asynchronous task
Link to display customer’s leads

Hyper-link to order’s details

Enhanced User Interface
When the asynchronous operation is executed, a small windows open to display the
progress of the execution.

You can open or close the panel

let the execution continue, continue
to run your pages and navigate,
and
abort the task if not finished

When the execution is finished,

a download link is available to
get the detail log
Enhanced User Interface
The detail page displays the order details. Several sections are present here, we have to
scroll the page to see them all:

Header section
Lines withwith
section 2 blocks
(General ainformation,
onlysection
Total grid of
Embedded Contact)
lines
shipping list

The link section

allows to go to Edit
mode, to Create
Link to thetoshipping
Link phone bydetails
using the phone mode, to Delete the
capabilities or the software record, to go back to
(skype…) installed on the device the list, or to use
word and Excel to
display the order
Property attribute on representation
Hands on – What to do

On YORDER1 representation, we want a checkbox to automatically display or hide

the contact block properties in edit mode.
- Add a AUTUSR property on the YORDER1 representation
- Add AUTUSR property in the displayed properties tabs and check:
• Edit as visible and enterable
- On the representation script YORDER_RSPE:
• Add a property event that hide NAME and PHONE properties when AUTUSR is
not checked
• Use the ASETATTRIBUTE method

Tips on the online help to use ASETATTRIBUTE method:

Technical help > Development platform > How to guides > How to hide
or make a property visible from an update to a different property
Property attribute on representation
Hands on - Result

When the property is checked Contact block is visible, when unchecked it

becames invisible
Patching & help
Steps 3 & 4

• Install the SRC_KT_DEV_STEP3-4 patch to get the official training

development

• The JSON file Menu_KT_DEV_STEP3-4.json contains a menu item

using the YORDER1 representation

Online help about snapshot, log files represention events

and APIs:
Technical help > Development platform > Developper guide
Technical help > Development platform > API & library guides
What you have learned
in Part 2 – Step 4

• Properties, methods and scripts

at representation level

• Embedded and asynchronous

links

• Operation from a class

Step 5 – Orders management for mobility
Advanced mobile application
 Part 2 – Step 5

• Enhanced mobile representation

• Representation script
• Synchronize data
What you will learn in
Part 2 – Step 5

• To manage an enhanced
representation for mobile

• To add query facet rules in

representation script

• To update mobile app

components and synchronize
data
Enhanced representation for the mobile application

• Default values on some not entered fields

• Mobile update last date field
• Access to country and credit level (display mode)

Create mobile representations Create a script to default Update the mobile

• New mobile order values for mobile interface gadget
Including fields for UI purposes:
country and credit level
YORDERM1_RSPE
• With links to shipments for the
Global events
order and opportunities for the
• Read country and customer related
customer
data when reading an order
• Mobile shipment
• Automatic comment at order
creation
YORDERM1 YSHIPM • Mobile Update date set on update

Use mobile interface to create and modify orders Synchronize data

Mobile representations

This mobile representation:

- YORDERM1 copy from
enhanced one YORDER1.
- Script called
YORDERM1_RSPE to
assign default values

This representation still is a

simplified one (some fields, such
as the comment, will not be
present).

To be compliant with mobile use

the YSHIP representation for
desktop has to be copied into
YSHIPM for mobile.
Mobile representation
Properties

A property has been added in the representation (OSTAUZ, authorized credit)

It is defined as a technical property available only on the detail facet

The country is now present and visible on the query facet

Mobile representation
Links

A link has been added on the detail facet. It links to a mobile representation
YLEADM that lists all the leads for the customer (the parameter BPCNUM is set
with the order customer)
Mobile representation
Links

A link has been added at page level. It links to a mobile representation YSHIPM that
lists all the shipments of the order (the parameter ORDNUM is set with the order
number.
YORDERM1_RSPE script – part 1
This script manages default values used for display and/or input. We work here in service
mode: the default values can only be assigned at the end if no value has been entered,
except if they are at the document level and if they can be assigned independently from
other computed values

The site default value depend only from the user

and is assigned at the header level

Method reading the value of a user parameter

The parameter is called SOCDEF (default company)

The comment depends on the user (given by the context this.ACTX) and
on the current date (date$)
YORDERM1_RSPE script – part 2
Events are here defined at the 3 levels:
• Representation for query event (Join definition to get data from tables not described in the
class; transfer of data read to representation properties)
• Order Class level (default values defined after data entry)
• Lines level (default quantities after line insertion)

Allows to redefine the SQL request to fill the query facet

Assign COUNTRY property in query facet of the representation

Default values on header only if not entered

Assign mobile update last date

On detail facet, fill the country, the customer risk and the contact information

Default values on lines computed at the end if no value has been entered
YORDERM1_RSPE script – part 3
Default values are rather simple, but a little bit different than before

If no currency can be found for

the customer, we use “EUR” by
default

Default company
assignment (the
first company if no
company found
for the user)
YORDERM1_RSPE script – part 4

Events associated to the query.

Instead of using a cursor on sales order, we use a cursor based on a join

between order and customer to get customer values in the query

When the customer is read, we read the business

partner record to get the country code. We also read
the customer record to get the authorized credit. We
consider that the minimum credit level is always 1000
Assignment of country code
Update the mobile application
An important point to note is that any evolution on a mobile application, when finished,
must be updated by increasing its version number:

Once this is done, an update icon appears on the

tile when reloading the mobile page. Clicking on
the tile will propose you to update the application.
Personalize the mobile application
If many customized pages exist for the same dashboard or facet for mobile
usage, only the first one is used.
The access to different variants of the customized page can be set up in the
customized page dictionary.
Patching & help
Step 5

• Install the SRC_KT_DEV_STEP5 patch to get the official training

development

Online help about UI and Widget, Administration module:

Technical help > Development platform > UI definition

Technical help > Development platform > Administration reference
What you just learned
in Part 2 – Step 5

• Mobile enhanced
representation

• Query rules in representation

script

• Mobile update and data

synchronization
Conclusion -
What you have learned
• Create and use a class, a
representation and its mobile
app without source code to
write
• Manage classes and
representations with child class
and collection nested
• Setup the home page interface
and its comopnents
• Use a class as a service
• Develop scripts to handle all
rules, events and methods part
of the class management and
its behavior
• Setup and understand different
kind of links on representation
• Update and a mobile app
 Thank you

© 2016, The Sage Group plc or its licensors. Sage, Sage logos, Sage product and service names mentioned herein
are the trademarks of The Sage Group plc or its licensors. All other trademarks are the property of their respective owners.