Vinyl Advanced Training Manual

VINYLTM ADVANCED TRAINING MANUAL
2.6
DEVELOPER TRAINING
© Zudy
1560 Lenox Ave • Suite 203
Miami Beach, FL 33139
Phone 305.763.8287 • Fax 305.763.8452
© 2019 ZUDY SOFTWARE - ALL MATERIAL AND INFORMATION CONTAINED WITHIN THIS SITE CONFIDENTIAL AND PROPRIETARY.
NO DISTRIBUTION, COPYING, OR DISSEMINATION OF THE CONTENTS IS ALLOWED WITHOUT PRIOR WRITTEN PERMISSION.
LAST UPDATED 12/4/2019

Table of Contents
Introduction ................................................................................................................................................................ 1
What is Vinyl? ............................................................................................................................................ 1
Course Objective .................................................................................................................................... 1
Vinyl Layers................................................................................................................................................................... 1
Data Storage Layer .............................................................................................................. 1
Business Logic Layer ......................................................................................................... 2
UI Layer ....................................................................................................................................... 2
Northwind Data Structure ............................................................................................................. 2
Data Storage Layer ................................................................................................................................................ 3
Logical Data Types for Table Columns .................................................................................. 3
Boolean ...................................................................................................................................... 3
Currency..................................................................................................................................... 4
Date, Date/Time, Time ..................................................................................................... 5
Email ............................................................................................................................................ 6
File ...................................................................................................................................................7
HTML............................................................................................................................................. 8
Number, Percent ................................................................................................................. 9
Percent ..................................................................................................................................... 10
Phone ......................................................................................................................................... 10
Photo .......................................................................................................................................... 10
String ............................................................................................................................................11
Unique ID .................................................................................................................................12
URL................................................................................................................................................13
Logical Data Types for Storing Address and Phone Data.....................14
Vinyl Data Services ........................................................................................................... 15
Insert, Update and Delete ............................................................................................................. 17
Chapter Exercise: Modify the Product Table .................................................................. 18
Default Values ....................................................................................................................................... 18
Chapter Exercise: Set a Default on the Product Table ............................................ 19
Usage ........................................................................................................................................................... 19
Other Common Usage Types .................................................................................. 20
Relationships ..........................................................................................................................................21
Chapter Exercise: Create a Relationship on the Supplier Table ......................23
Relationships: Cascade ...................................................................................................................23
Joins .............................................................................................................................................................................. 25
Union Joins ............................................................................................................................................. 25
CRUD ............................................................................................................................................................................ 28
CRUD Update ....................................................................................................................................... 28
Chapter Exercise: Create a CRUD Update Rule ........................................................... 29
CRUD Delete ......................................................................................................................................... 30
© 2019 ZUDY SOFTWARE - ALL MATERIAL AND INFORMATION CONTAINED WITHIN THIS DOCUMENT IS CONFIDENTIAL AND PROPRIETARY.
NO DISTRIBUTION, COPYING, OR DISSEMINATION OF THE CONTENTS IS ALLOWED WITHOUT PRIOR WRITTEN PERMISSION.
LAST UPDATED 12/4/2019

CRUD Rules with Events .............................................................................................................. 30
Chapter Exercise: Create CRUDs and Custom Events .............................................33
Firing Events ...........................................................................................................................................33
Chapter Exercise: CRUDs and Firing Events .................................................................. 35
Subquery Rules and CRUD Rules .......................................................................................... 35
Subqueries and CRUD Inserts .................................................................................................. 36
Validations ................................................................................................................................................................ 38
Chapter Exercise: Create a Validation ................................................................................ 39
Validation Rules and Events ...................................................................................................... 39
Chapter Exercise: Attach a Validation Rule to an Event .........................................41
UI Layer .........................................................................................................................................................................41
Board Panels ...........................................................................................................................................41
Chart Panel ..............................................................................................................................................42
Create a Business Object with an Aggregate Value ................................42
Create a Chart ......................................................................................................................43
Badging .................................................................................................................................................... 44
Reach .......................................................................................................................................................... 45
Add Region List Control to the Customer Page ........................................ 49
Add User List Control to the Employee Page .............................................. 50
Define a Reach Rule........................................................................................................ 51
Reach Registration ......................................................................................................... 52
Bridge........................................................................................................................................................................... 53
Message Types ..................................................................................................................................... 53
Options ...................................................................................................................................................... 53
Configuration ...................................................................................................................... 53
Data Object Event Binding ....................................................................................... 54
Bridge Registration .......................................................................................................................... 54
Linking to a Bridge .......................................................................................................... 54
Message Creation ............................................................................................................. 54
Translations ............................................................................................................................................ 55
Limitations .............................................................................................................................................. 55
Bridge Public Data Objects ........................................................................................................ 56
Common Columns ......................................................................................................... 56
Bridge_Email_Send ....................................................................................................... 56
Bridge_SMS_Send ........................................................................................................... 56
Bridge_Vinyl_Alert_Send ........................................................................................... 57
Bridge Setup Example ................................................................................................................... 57
Create a Bridge .................................................................................................................. 57
Steps to Create Bridge ................................................................................................. 57
Register Bridge with Application ......................................................................... 58
Define Bridge Options .................................................................................................. 58
Register Bridge with an Event ................................................................................ 59
SMS Bridge Setup ............................................................................................................................. 60
Setup Vinyl Security ....................................................................................................... 60
Setup Twilio.......................................................................................................................... 60
Configure Vinyl SMS Endpoint ................................................................................ 61
Configure Vinyl Website URL ................................................................................... 61
Configure Vinyl SMS Bridge ...................................................................................... 61
Beyond the Advanced Training Manual ............................................................................................. 63
Introduction
What is VinylTM?
Vinyl is the first No-Code Enterprise Application Development Platform. Vinyl allows you to
create beautiful yet powerful applications and charts from multiple data sources, including
complex analytics all together on the same screen without writing a single line of code. Vinyl is
database agnostic, meaning it can work with any database type, and a key benefit of using
Vinyl is that the application turnaround time is a few weeks vs. a few years.
Course Objective
This course covers some of the more advanced skills used to develop in Vinyl, as well as the
methodology used at Zudy to develop applications. In this course we will take a deeper look at
the Data Storage Layer and review Logical Data Types, Union Joins, CRUD Rules, Subqueries,
Validations, Board and Chart Panels, Badging and Reach.
Vinyl Layers
These are the three layers of Vinyl: Data Storage Layer, Business Logic Layer and the
UI Layer. Blue, Red, and Green are used to visually identify the 3 different layers of
Vinyl.
Data Storage Layer
Contains all the tables where the physical data is stored.
1
VINYL USER GUIDE
Business Logic Layer
Used to expose your data as well as allow you to manipulate and filter data from the tables in
the Data Storage Layer.
UI Layer
Where you build the actual application and customize the User Interface.
Northwind Data Structure

Here are the data tables and corresponding columns which have been included in the
application. The first column is the Primary Key (abbreviated as PK):
The Tables and Primary Key’s (PK’s) in the Northwind s Training Application
2
VINYL USER GUIDE
Data Storage Layer
To start off, we will take a deeper look at the Data Storage Layer in Vinyl. In this chapter we will
review different data storage types for Columns, assigning Columns a default value, and
configuring relationships between tables to improve the quality of data in the application.
Data Storage Layer Navigation Link
Logical Data Types for Table Columns

A database is typically a large collection of data that is organized for rapid search and retrieval.
A database is comprised of Tables, which are in turn made up of various Columns. Columns
store a set of data values of a particular type, one value for each row of the database. A column
may contain text values, numbers, or even pointers to files in the operating system.
In Vinyl, we leverage Logical Data Types to define the different type of data being stored in the
Column which can then be expressed in a manner that is unique to its data type. Logical Data
Types define the data type for the Column, while Physical Data Types determine how the data
in the Column is stored in the Data Storage Layer. In this next section we will take a look at the
different Logical Data Types available in Vinyl.
Boolean
Boolean is a Logical Data Type that can only store one of two possible values, intended to
represent the two truth values of logic and Boolean algebra. Boolean values in Vinyl are most
often stored as Bit Physical Data Types. In the example we’ll review, we will look at the Product
table’s Discontinued Column:
3
VINYL USER GUIDE
The Product Table’s Discontinued Column is an example of a Boolean Logical Data

Type
PHYSICAL DATA TYPES AVAILABLE FOR BOOLEAN
❖ Bit – stores data as 0 or 1, with 0 meaning False and 1 meaning True. This is typically the
option used when you want to represent a checkbox on the UI Layer, where unchecked
means False and checked means True.
❖ Char – If you store Boolean with Char, from the UI Layer you will see a list that has True and
False values on it, instead of a checkbox.
❖ Decimal - 10^38 + 1 – 10^38 – 1. Used when you want to store a number with a large decimal
value.
Currency
The Currency Logical Data Type supports numeric values with decimal places, and should be
used to store currency values. This data type only has one Physical Data Type available, which is
Decimal. In the UI Layer, a Control that makes use of a Currency Column will display a ‘$’
symbol next to the numeric value, to identify it as currency. We can review an example of the
Currency Logical Data Type by looking at the Product table’s UnitPrice Column:
4
VINYL USER GUIDE
The Product Table’s UnitPrice Column is an example of Currency Logical Data Type
PHYSICAL DATA TYPES AVAILABLE FOR CURRENCY
❖ Decimal - 10^38 + 1 – 10^38 – 1. Used when you want to store a number with a large decimal
value.
Date, Date/Time, Time
Date is the Logical Data Type used to store date information in a Column, complete with day,
month and year and formatted as MM/DD/YYYY. If you try and edit a field set as Date, you’ll see
a calendar pop-up which allows you to choose a new date value.
If you are also looking to capture and store Time information along with Dates, Vinyl has a
separate Date/Time Logical Data Type for that purpose. Similarly, if you are only looking to
store and present Time information, Vinyl has a Time Logical Data Type designed for that
purpose.
To review the Date Logical Data Type, we will review the Employee Table, BirthDate Column.
5
VINYL USER GUIDE
The Employee Table, BirthDate Column uses Date as its Logical Data Type
PHYSICAL DATA TYPES AVAILABLE FOR DATE
❖ Date - Date only

❖ Decimal – 10^38 + 1 – 10^38 - 1
❖ Integer – Int - -2,147,483,648 – 2,147,483,647
Email
The Email Logical Data Type should be used for Columns where you want to capture, store and
display Email Address information. It is important to use this Logical Data Type for Email
Addresses, as it will ensure proper formatting. In this example we will review the Employee
table’s Email Column:
6
VINYL USER GUIDE
The Employee Table’s Email column is an example of an Email Logical Data Type
PHYSICAL DATA TYPES AVAILABLE FOR EMAIL
❖ Char - Character data of fixed length

❖ NChar – UNICODE character data of fix length
❖ NVarchar - UNICODE character data of indeterminate length
❖ Varchar – Character data of indeterminate length
File
The File Logical Data Type stores a file, either as a Binary or NVarchar Physical Data Type. From
the UI Layer, File is often used in conjunction with a Photo Control to provide an end user the
ability to upload new files and replace existing ones with a data record. In the example we will
review, File is used for the Employee table’s Resume Column so that we can upload, store and
make available for download an Employee’s resume.
7
VINYL USER GUIDE
The Employee Table’s Resume Column is an example of a File Logical Data Type
PHYSICAL DATA TYPES AVAILABLE FOR FILE
❖ Binary - Binary data is the only category of data that can be directly understood and
executed by a computer. It is numerically represented by a combination of zeros and ones.
❖ NVarchar - UNICODE character data of indeterminate length.
HTML
The HTML Logical Data Type stores data containing HTML syntax. As an example we can review
the Employee table’s Notes Column:
8
VINYL USER GUIDE
The Employee Table’s Notes Column is an example of the HTML Logical Data Type
PHYSICAL DATA TYPES AVAILABLE FOR HTML

Number, Percent
The Number Logical Data Type stores numeric data and has many different Physical Data
Types available. If you want to store, present, and run calculations off of numbers as Percent
values Vinyl has a separate Percent Logical Data Type available for this purpose.
We can review an example of the Number Logical Data Type by looking at the Product table’s
UnitsInStock Column:
The Product Table’s UnitsInStock Column is an example of Number Logical Data Type
PHYSICAL DATA TYPES AVAILABLE FOR NUMBER
❖ Decimal - 10^38 + 1 – 10^38 – 1. Used to store a number with a large decimal value.
❖ Float - -1.79E + 308 through -2.23E -308. Used to store smaller decimal values.
❖ Integer – BigInt - -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807
❖ Integer – Int - 2,147,483,648 – 2,147,483,648
❖ Integer – SmallInt - -32,768 to 32,767
❖ Integer – TinyInt – 0 to 255
❖ Real - -3.40E + 38 through -1.18E - 38
9
VINYL USER GUIDE
Percent
The Percent Logical Data Type is available for capturing, storing and displaying percentage
data.
Phone
The Phone Logical Data Type supports storing Phone number data, along with proper
formatting. As the corresponding Physical Data Type for Phone is Varchar, we can use this field
for International phone numbers as well as the United States. In this example we will look at
the Employee table’s HomePhone Column to see an example of the Phone Logical Data Type:
The Employee table’s HomePhone column is an example of Phone Logical Data Type
PHYSICAL DATA TYPES AVAILABLE FOR PHONE

Photo
The next Logical Data Type we’ll review is for Photo. You might recall from the Intro Course
that we used the Photo Column in conjunction with a File Control to allow users to upload new
files and download existing files. Let’s look at the Employee Table’s Photo Column to review an
example of the Photo Logical Data Type.
10
VINYL USER GUIDE
The Employee Table’s Photo Column is an example of the Photo Logical Data Type
PHYSICAL DATA TYPES AVAILABLE FOR PHOTO
❖ Binary - Binary data is the only category of data that can be directly understood and
executed by a computer. It is numerically represented by a combination of zeros and ones.
String
The next Column Logical Data Type we will review is String. String is probably the most
frequently used Logical Data Type in Vinyl. String allows you to store an array of data in a
sequence of elements, typically characters, symbols and numbers. Let’s review the Employee
Table FirstName Column to review String. Note that we have Allow Nulls ticked off because we
want all Employees to have a First Name value:
11
VINYL USER GUIDE
The Employee Table, FirstName Column uses String Logical Data Type
PHYSICAL DATA TYPES AVAILABLE F OR STRING

❖ Encrypted – Encrypted data
❖ NVarchar – UNICODE character data of indeterminate length. Typically, all Vinyl Strings are
stored as NVarchar so they can support Unicode and take up less space.
Unique ID
The next Logical Data Type we’ll review is Unique ID, which is used to store a unique identifier
value. Unique ID’s are used to uniquely identify each row or record in a Table in a database.
Primary Keys are examples of Columns which use a Unique ID Logical Data Type.
TO VIEW A UNIQUE ID
1. Click the Action Drawer and select Vinyl IDE

2. Select Build your application from the Build menu
3. Click the Data Storage Layer button
4. Locate your application data source, and click the Tables gear icon
5. Expand the Category Table
6. Click the pop-up icon to view the Category ID Column information
7. Note that the Logical Data Type is Unique ID, the Physical Data Type is UUID, and the
Column Name ends in ‘ID’ which follows Vinyl naming methodology
8. Close this window, click the Results button and confirm you see UUID values being
stored for the CategoryID column
12
VINYL USER GUIDE
PK Settings available for a Column
Looking at the Column definition screen in Vinyl, there is a PK Settings Control Set which
contains three options which define the Primary Key Settings:
❖ Primary Key - Boolean flag that defines if a field is a Primary Key for a Table. Checking this
option indicates the Column is a Primary Key for the Table its associated with.
❖ Auto Gen – Boolean flag that determines whether you want the field to automatically be
generated upon new record creation (e.g., fill in the Unique ID field). Checking this causes
the Column to autogenerate its value as new records are created.
❖ Allow Nulls – determines whether a new record can be created which does not contain
any data (potentially creates bad data). Checking this indicates that nulls are allowed for
this Column, and having an X appear here indicates nulls are not allowed for this Column.
PHYSICAL DATA TYPES AVAILABLE FOR UNIQUE ID
❖ Char – Character data of fixed length.

❖ UUID – Universally unique identifier. 128-bit number used to uniquely identify information.
URL
The URL Logical Data Type is available for capturing, storing and displaying a URL value (the
address of a World Wide Web page). It is used to ensure the proper formatting is available for
this type information.
13
VINYL USER GUIDE
The Shipper table’s Website column is an example of a URL Logical Data Type
PHYSICAL DATA TYPES AVAILABLE FOR URL

Logical Data Types for Storing Address and Phone Data
Logical Data Types are designed to give more meaning to the data type(s) being stored. Added
in Vinyl 2.4, there are Logical Data Types available for storing Address and Phone data. By using
one of these values when storing data for these types, you can leverage the power of Vinyl Data
Services in validating data via external API resources that come preconfigured.
ADDRESS
❖ City
❖ Country
❖ Line1
❖ Line2
❖ Line3
❖ Line4
❖ State
❖ Zipcode
PHONE
❖ Cell
14
VINYL USER GUIDE
❖ LandLine
❖ Phone
Vinyl Data Services
Vinyl Data Services is a way to quickly and easily validate data before it is stored in an app. Vinyl
Data Services comes shipped and preconfigured with Vinyl 2.4 and above, and provides a
powerful API connection service to various API resources (e.g. Melissa Data) to run validation
against certain defined Logical Data Types.
For example, the Email Logical Data Type now uses Vinyl Data Services to validate that data
entered into an Email type Control is a valid ISO Standard Email Address. An error message will
be displayed to the User if not. No extra setup is required to leverage this Vinyl Data Service.
Vinyl Data Services, as they are used with Logical Data Types, is preconfigured through the
Vinyl IDE > Configuration > Logical Data Types. For example, here is the Logical Data Type
defined for Email:
The Logical Data Type defined for Email that uses Vinyl Data Services
15
VINYL USER GUIDE
After a Logical Data Type is configured in the Vinyl IDE > Configuration area, it gets assigned to
a Column in the Data Storage Layer. For example, here is the Email Logical Data Type assigned
in the Employee table to the Email Column:
The Employee Email Column is defined as an Email Logical Data Type
Lastly, with the configuration already in place in the Vinyl IDE along with the Data Storage
Layer configured to use the Logical Data Type, the application UI Layer will run validation
automatically and provide meaningful Error Messages if data being entered isn’t valid. For
example, this is an Error Message encountered when entering an invalid Email value on the
Employee SRP Panel:
16
VINYL USER GUIDE
Email Validation Error from Vinyl Data Services
Insert, Update and Delete

In Vinyl, each Table and Column can individually support Inserting, Updating and/or Deleting
data. Insert refers to creating new records, Update refers to modifying existing records, and
Delete refers to removing or deleting a record. Collectively these options control how a Table’s
data can be manipulated through the Vinyl Layers, so it is an important concept for a
Developer to understand when configuring these options.
Tables and Columns can have Insert, Update and Delete functionality enabled or turned off.
The settings here, to reiterate, control the behavior throughout the Vinyl Layers including the
Application Layer. In this example we will walk through changing the supported functionality
for the Employee table.
1. Click the Action Drawer icon, and select Vinyl IDE
2. Click the Build your application button on the Build menu
4. Click the Tables gear icon for your data source
5. Expand the Employee table to view the Table Definition
6. Click on Edge Case Settings at the bottom of the table panel on the left
17
VINYL USER GUIDE
Edge Case Settings available for a Table
7. The CRUD Support Control Set contains three options:

a. Insertable – allows new records to be added to this table
b. Updatable – allows records on this table to be modified
c. Deletable – allows records from this table to be deleted
8. Check that Insertable, Updatable, and Deletable are all checked (enabled) for the
Employee table and Save
Chapter Exercise: Modify the Product Table

In our Northwinds data source, when a Product sells out or is no longer being sold we want it
to be flagged as Discontinued, rather than being deleted as a record from the Table. This being
the case, there technically should not be a reason to need to Delete from the Product table.
Following the steps we reviewed for the Employee table, go review the Product table. Expand
the Product table to view the Table Definition, and click into the Edge Case Settings. From
there uncheck the Deletable option in CRUD Support.
Default Values
Columns in Vinyl can be created with default values. This can be useful when you have a field
that is usually the same value, or if you want to lock a field into a certain value by combining a
default with no support for Inserting and Updating.
To review a Default Value example, we’ll assign the Country Column of the Employee table a
default value of USA since the majority of Northwinds employees are based in the United
States.
18
VINYL USER GUIDE

5. Expand the Employee table to view the Table Definition
6. Click the pop-up icon to expand the Country column
7. Click the Edit button and enter the value USA in the Default Value field
The Default Value field is where you can set default information for Columns
8. Click the Save button

9. Click the Results button and then click the Create button, confirm that the Country
field gets defaulted to USA
Chapter Exercise: Set a Default on the Product Table

Following the steps we reviewed for the Employee table, go review the Product table. Set a
default on the UnitsInStock Column for the Product Table, so that the default value is zero (0).
Test your results after setting the default value.
Usage
All Columns in Vinyl have a Usage field, and the purpose of the Usage field is to flag that
Column for a specific role within the database and application. It is important to note that not
all Columns have Usage values defined, in fact most do not.
Title is the most common Usage value defined for Columns, and is used to flag a Column as a
List Title which means that it will be added to a List Business Object if the List button is used to
create a List object. You will receive an error message clicking the List button to create a List
19
VINYL USER GUIDE
object if you are trying to use it on a Table without a Title Column defined. To correct this issue,
simply defined one of the Columns as your Title and then click the List button again.
In this example, we’ll look at defining a Usage for the Category table.
5. Expand the Category table to view the Table Definition
6. Determine which Column makes the most sense to be used as a Title. If we made a list
object out of the Category table, we would assign the Category Column a usage of Title.
The Category Column has Usage defined as Title
7. Now if we create a List Business Object for Employee table, Category will be used as the
Title field
Other Common Usage Types

❖ Subtitle – A Column that is designated as Subtitle will also be added automatically to a List
Business Object, as well as a List that is created in the application.
❖ Added By/Added On – Columns with this designation will automatically be filled in with
either the Added By/Added On information upon record creation, without having to make
a Default Rule to do so.
❖ Changed By/Changed On – Columns with this designation will automatically be filled in
with a record of who or when a record was modified, without having to make a Default
Rule to do so.
20
VINYL USER GUIDE
Relationships
Relationships in Vinyl are most useful for data integrity, by preventing Users from entering bad
data and creating orphaned records (data which no longer has context). When creating
relationships between two tables, one table becomes the parent and the other becomes the
child. Each relationship is bound by a Primary Key which is common to both tables. By
creating the Relationship (in the Data Storage Layer), you ensure that information entered in
the child table will match information in the parent.
For example, if the Order table were the parent of the OrderDetail table, then it would ensure
that neither a User nor a Developer could enter Order Details for an Order that doesn’t yet exist.
Relationships constrain the Developers of the application as well because they are defined at
the Data Storage Layer.
To illustrate how Relationships in Vinyl work, we will be making a Relationship between the
Order table and the OrderDetail table, so that nobody can add an OrderDetail with an OrderID
that doesn’t exist in the Order table. Application Users would typically be restricted from doing
so simply because they can only add Order Details on an Order page, but adding this
Relationship ensures that nobody can do so.
5. Expand the Order table to view the Table Definition
21
VINYL USER GUIDE
The Table Definition panel where you

access and manage Table Relationships
6. In the Constraints Control Set, the Keys & Indexes icon allows you to view Primary Key
information for the table
7. The Relationships Control Set area is where you can view information about table
parent and child relationships
8. Click the One to Many arrow icon, and click the Create button
9. Set the Primary Table value to Order, and the Secondary Table to OrderDetail
10. Check that the Binding Keys information is populated with OrderID for both Columns.
Here the Primary Column represents the Primary Key of the parent table, and the
Secondary Column refers to the Foreign Key from the child table that points to the
Primary Key.
22
VINYL USER GUIDE
The Relationship between the Order parent and OrderDetail c hild tables
With this Relationship configured, it will be impossible to add to the OrderDetails table if
an Order does not exist. This should already be impossible to do through the application’s
UI, but now it will also be impossible for a Developer to make the same mistake or
accidentally allow Users to do so.
TABLE RELATIONSHIP TERMINOLOGY
❖ Primary Table – the table which contains the Primary Key for the relationship
❖ Secondary Table – the table which contains the Foreign Key for the relationship
❖ Primary Columns – the Column in the Parent Table that is the Primary Key that will be
used to bind the relationship
❖ Secondary Columns – the Column in the Child Table that is the Foreign Key that points to
the Primary Column
Chapter Exercise: Create a Relationship on the Supplier Table

Following the steps we walked through with the Order and Order Detail table, create a
Relationship where the Product table is the child of the Supplier table.
Relationships: Cascade
After you create a Relationship you can change its On Delete and On Update options, which
cause certain behaviors when data is changed on the parent table. The On Update options
ensure that information that is updated in the parent table is reflected in the child table, and
On Delete ensures that data with no context (orphaned data) does not remain in the tables.
23
VINYL USER GUIDE
Both On Delete and On Update can either be set to Cascade, Null or Default, but we will only
review Cascade in this manual. Cascade means that child data will be updated at the same
time as its parent data.
To help illustrate how Cascade works with relationships, we’ll configure a Relationship
between the Order table and the OrderDetail table that is set to On Delete Cascade. Doing this
will ensure that deleting an Order will delete its Order Details as well. It is important to note
that selecting the correct parent to child relationship is critical to success. If we chose the
parent as OrderDetail in this example, deleting the details of an Order would delete the Order
itself. To create this relationship:
5. Expand the Order table to view the Table Definition
6. Click the One to Many arrow icon
7. Expand the Order relationship (created in the Relationships section of this manual)
8. Click the Edit button
9. Set On Delete to Cascade, which will cause a deleted Order to cascade down and
delete any associated Order Details
Here we added Cascade On Delete to the Order to OrderDetail table Relationship
10. Click Save
24
VINYL USER GUIDE
Joins
Up until this point we have spent a good amount of time in the Data Storage Layer. For the rest
of this training manual we will focus on the Business Logic Layer and the UI Layer. Up next we
will look at the Business Logic Layer, and review how SQL Union Joins work in Vinyl.
Union Joins
In Vinyl, SQL Union Joins produce a combination of two Select statements which target the
same Column. A Union Join combines the results of two different Columns (that have the
same name) from two different Tables into one unified Column. While most Joins utilize a Join
column, the Union Join does not. This is because other Joins require shared context between
the two tables to function, but a Union Join only requires shared columns.
For example, an Inner Join between the Product and Supplier tables would show every
Product along with their Supplier, while a Union Join between Product and Supplier tables
would show you a list of all the different SupplierID fields. This is because the Union Join
essentially shows all the results from the same column in two different tables, and these two
tables only share the SupplierID. Remember with Joins that sharing context and having the
same Column are two different criteria.
Let’s review creating a Union Join to find all the countries that exist in the Northwinds data
source. The Union Join will allow us to take all the country fields from any table with country
data and combine them to make a collection of every country that belongs to each record:
3. Click the Business Logic Layer button
4. Click the BOBJ icon for your data source
5. Click the Create button under Rules
6. Assign the Name Supplier (Countries for Supplier and Customer)
7. Select the Purpose as Business Object
8. Set the Target to Supplier
25
VINYL USER GUIDE
The Union Join Rule Name, Purpose and Target

10. Click the SQL gears icon
11. Add the Supplier and Customer Tables in the Tables panel. In the Northwinds data
source, these are the only tables containing country data.
12. In the Joins panel, click the Create button and set Left to S (for Supplier), Type to Union,
and Right to C (for Customer). Click the checkmark to save.
13. In the Columns panel click Create and add the Country column and assign no Target.
Click the checkmark to save.
The Business SQL for the Union Join between Supplier and Customer tables
14. Click back to view details on this Rule and click the Edge Case Settings link
26
VINYL USER GUIDE
View Details information on the Union Join Rule
15. Click the Edit button and place a check in Select Distinct. We do this step in order to
not return duplicate values.
Edge Case Settings for the Union Join Rule
16. Click Save, and click the X to close the Edge Case Settings window
17. Click the Results button to verify the results of the Business Object. This is the
completed Union Join, and it will list all countries appearing in both the Supplier and
Customer tables.
27
VINYL USER GUIDE
CRUD
One of the most important Business Object Rules in Vinyl is the CRUD Rule. CRUD stands for
Create, Read, Update, Delete. As a Vinyl Developer you could not build a modern, intuitive
application without CRUD Rules. CRUD Rules are used to either insert, update or delete
records in a table. There are three different types of CRUD Rules in Vinyl:
❖ CRUD – used when you want to CRUD between two different databases
❖ CRUD Business Logic - will check and perform the different validations/actions as the
CRUD is executed
❖ CRUD XP – XP means cross platform and allows you to CRUD into different data sources the
application is linked to
CRUD Update
The first CRUD Rule to review is a CRUD Update, which has the action type Update and can
adjust existing records in a table. A CRUD Update can update an entire table’s records based
on a defined formula. It does this by adding numeric quantities or expressions against a record,
as well as changing a text entry from any existing value to a specified value.
In this chapter we will build a CRUD Rule since we want the Rule to run against the entire
database. The CRUD Rule we create will add 1 to the Quantity value.
6. Assign the Name OrderDetail (Quantity +1), which follows Vinyl naming conventions
7. Set the Purpose value to CRUD
8. Set the Action to Update
9. Set and the Target to the OrderDetail table
11. Click the SQL icon to define the logic for the CRUD Update
12. Confirm the OrderDetail table appears in the Tables panel
13. Click the PK button to add in the Primary Keys as Columns
14. Click Create in the Columns panel and enter the expression Quantity+1, assign the Alias
as QuantityPlus, and Target as Quantity
28
VINYL USER GUIDE
The Business SQL for the CRUD Update Rule
15. Although it is not necessary for the CRUD Update to function as expected, we will add
in the Quantity Column so we see that this works through the Results generated. Click
the Create button in Columns, and add in Quantity.
16. Click on the Results button, and confirm that the QuantityPlus column is adding 1 to
the Quantity column value.
The Results of the CRUD Update Rule
Chapter Exercise: Create a CRUD Update Rule

Following the steps we walked through to create a CRUD Update Rule, create a new CRUD
Update Rule with the purpose of it subtracting 1 from the OrderDetail table Quantity value.
29
VINYL USER GUIDE
CRUD Delete
In Vinyl, a CRUD Delete Rule is used to delete records from a table. Like other CRUD Rules, they
can be tied to a Control (like a button) to add functionality to an application. Since a User can
easily delete single records from the UI already, CRUD Delete Rules are mainly used to delete
many records at a time.
In this example, we will create a CRUD Delete Rule that will be applied to a button on the
Order panel of the Order page. The CRUD Delete Rule will delete all the Order Details
associated with an Order, as opposed to having a User delete each Order Detail record
manually one at a time.
6. Assign the Name OrderDetail (Delete OrderDetail for Order)
7. Assign the Purpose as CRUD
8. Select the Action Delete
9. Set the Target as the OrderDetail table
11. Click the SQL gears icon to define the Business SQL. Confirm that the OrderDetail table
has been added to the Tables panel.
12. Click the Create button in the Columns panel and add the OrderID column, and Target
OrderID. It is important to target the OrderID here, as you are stating that you only want
OrderDetail records with a specific OrderID value. Without this target you would delete
all OrderDetail records for all orders.
CRUD Rules with Events

In order for CRUD Rules to be used by the Application Layer, they must be attached to Events.
In Vinyl, Events are processes built into tables or Business Objects that get executed in
response to certain actions, such as saving a record. Each table and Business Object
intrinsically have Save, Update, Delete and Insert Events, which execute as you alter records
throughout Vinyl.
To activate the CRUD Rules we created, we will add them to an Event or create our own
Custom Event if the trigger is not one of the intrinsic ones. Unlike the intrinsic Events, a Custom
Event must be attached to a Control on the Application Layer to be executed. The CRUD Rules
we are creating will require Custom Events in order to execute when we want them to in Vinyl.
The first Custom Event we will create with a CRUD Rule will use the CRUD Delete Rule, where
we want it to delete OrderDetail records associated with an Order, if an Order gets deleted.
30
VINYL USER GUIDE

4. Click the BOBJ icon for the application data source
5. Click to select the Order table from the Tables panel, then click the Events icon for the
Order (Source) Business Object
6. We are creating a Custom Event, so click the Create button under All Events
7. Name the Event Delete Order Details
8. In the Messages section, enter the Confirmation text “Are you sure you want to delete
this Order’s Details?”
The CRUD Delete Custom Event
EVENT DETAILS TERMINOLOGY
❖ Active – this checkbox indicates if the Event is active or not

❖ Confirmation – this message is displayed to a user to confirm if they want to take an action
(such as submit a report)
❖ Success – this message is displayed to a user after a successful action has been performed
❖ Failure – this message is displayed to a user after an action has failed

10. Confirm your Custom Event now appears in the All Events panel:
31
VINYL USER GUIDE
The Custom Event now appears in All Events
EVENT TERMINOLOGY
❖ Save Event – this Event runs every time a record is saved

❖ Delete Event – this Event runs every time a record is deleted
❖ Update Event – this event runs every time a record is updated
❖ Insert Event – this event runs every time a record is inserted
11. At this point we have created the Event, but not attached the CRUD Rule to it. CRUD
Rules get attached as Actions, as an Event may execute one or more CRUD Rules. Click
to select the Delete Order Details event from All Events, and then click the Create
button in the Actions panel.
12. Click the drop-down menu for Rule, and select the CRUD Delete Rule OrderDetail
(Delete OrderDetail for Order)
13. In the Technical Help section, write a brief description of the Action, such as “Deletes all
Order Details for an Order”
14. Click Save
15. Under Explicit Bindings, verify that OrderID is the Source column and OrderID is the
Rule column. If that entry wasn’t added automatically, add it now by clicking the create
button.
32
VINYL USER GUIDE
The Action detail information for the Delete Order Details Custom Event
16. The Custom Event is configured and ready to be implemented on the Application Layer
Chapter Exercise: Create CRUDs and Custom Events

❖ Create an Event titled Quantity+1 on the OrderDetail (Source) Business Object, and add the
CRUD OrderDetail (Quantity +1) as an action
❖ Create the same Event in the location described above, except use the Quantity -1 CRUD
Rule we made
❖ Now we have finished configuring CRUD Rules and are ready to move onto the Application
Layer to implement the CRUD Rules in the application
Firing Events
After configuring the CRUD Rules, we attached them to Custom Events on a Business Object. If
we had attached them to intrinsic Events (Save, Insert, Update or Delete) instead of Custom
Events they would already be in effect. Because they are attached to Custom Events, we need
to add them to an application page via some type of Control. Events can be added to text,
image, list or button Controls. The CRUD Rules we defined are intended to be associated with
buttons.
Next, we will add the OrderDetail (Delete OrderDetail from Order) Rule to a button on the
Order panel of the Order page.
1. Navigate in the application to the Orders page
2. Click the chevron link from one of the Orders panel records to get to the Order page
3. Click on the Action Drawer, and select Design this page
4. Click to select the Order panel, and then click the Create button under Controls
5. Name the button Delete Order Details
33
VINYL USER GUIDE
6. Set the Control Type to Button. We don’t want a Data Column because this Control is
not trying to show any data.
7. Click Save
8. Click the Edit button in the Navigation and Actions panel
9. Select Delete Order Details as the Event
10. Click Save
Adding the Delete Order Details Event to a Button on the Order panel
11. Navigate back to the application Order page and refresh. Confirm that you now see the
Delete Order Details button on the Order panel.
34
VINYL USER GUIDE
The Delete Order Details button added to the Order panel
12. Test the button by clicking on it, clicking Proceed, and refreshing the page. If the Rule
was properly configured, only the Order Details of the Order will be deleted.
Chapter Exercise: CRUDs and Firing Events

❖ Create a button on the Order page, under the OrderDetails panel, which uses the Quantity
+1 Event we created.
❖ Create a button on the Order page, under the OrderDetails panel, which uses the Quantity -
1 Event we created.
Subquery Rules and CRUD Rules

Now that the CRUD Rules we created earlier have been implemented in the Application Layer,
we are going to take a step back to the Business Logic Layer and review a new Rule that is
available in Vinyl: the Subquery. Subquery Rules are used as an intermediary between a table
and its Business Objects/Rules. Subquery Rules are used to generate some sort of calculation or
make an adjustment to the data and pass that new information along to whatever object it is
placed in.
In this section, we will make a Subquery Rule and then attach it to a CRUD Insert. We will
make a Subquery used to find the maximum OrderID of the Order table, and then add one to
it. This will be used by a CRUD Insert Rule in the next chapter, whose functionality in turn will
be copying an order. Typically, the OrderID is autogenerated by Vinyl, but because we are
inserting a new record, we need to provide it with a new OrderID. In most cases we would
generate a new OrderID with the NewUUID() function, which generates a UUID, but the data in
35
VINYL USER GUIDE
this case won’t work with that method. Here the OrderID is not a UUID, rather, it is stored as a
numeric field.
6. Assign the Name Order (OrderID + 1)
7. Set the Purpose to Subquery
8. Set the Target to be the Order table
9. Click Save
10. Click the SQL gears icon to enter the Business SQL
11. Confirm that the Order table appears in the Tables panel
12. In the Columns panel, enter the expression Max(OrderID) + 1, and assign the Alias as
MaxOrderID. Here the MAX() function is used to search a column for its maximum
value.
The Business SQL for the Orders (OrderID+1) Subquery
13. Click on the Results button and confirm that you see one row with the MaxOrderID
column. The value should be the maximum OrderID value plus one.
Subqueries and CRUD Inserts

Now that we have a Subquery configured, we will build a CRUD Insert Rule to utilize the Order
(OrderID + 1) Subquery.
6. Assign the Name Order (Copy Previous Order)
7. Set the Purpose to be CRUD
36
VINYL USER GUIDE
8. Set the Action to be Insert

9. Set the Target to be the Order table
10. Click Save
11. Click the SQL gears icon to enter the Business SQL
12. Confirm that the Order table is added to the Tables panel
13. Click Create in Tables, and select Order (OrderID + 1) from the Subquery menu
14. Click the check mark to save the information
15. Click Create under Columns, and add in OrderID from the Order table with no Target.
We add this column because we need to bind to it.
16. Click Create under Columns and add the MaxOrderID column from the Subquery,
Target the OrderID column. We add this because we want the OrderID generated to be
used for the Order.
17. Click the All button for the Order table in the Tables panel to add in all remaining
columns from the table. These should target themselves because that is how the rule
copies the Order (taking all columns from the current Order and inserting their values
into a new Order).
The Business SQL for the Order (Copy Previous Order) CRUD Insert
18. Now with the CRUD Insert Rule configured, we need to attach it to an Event. We want
this CRUD to be on the same Order panel that the CRUD Delete was put on, so navigate
to your application’s Order page, click the Action Drawer and select Design this page.
19. Click the Business Logic icon for the Order panel
20. Click on the Events icon for the Order (Source) Business Object
21. Click the Create button under All Events
22. Name the Event Copy Order
23. Click Save, and close the pop-up
24. With the Copy Order Event selected in the All Events panel, click Create in the Actions
panel
25. Click the drop-down menu for Rule and select Order (Copy Previous Order)
26. Set the Binding Type to Explicit
27. Enter a short description on the Action into the Technical Help section, such as “Copies
Previous Order”. Click Save
37
VINYL USER GUIDE
28. In Explicit Bindings, Source should be OrderID and Rule Column should be OrderID
The Event Action for the Order (Copy Previous Order) CRUD Insert Rule
29. Now that your Rule is configured, it can be added to a new button named Copy Order.
Follow the steps we took for the Delete Order Details button, but instead add a Copy
Order button instead.
Validations
Validation Rules are used to ensure that the data entered in Vinyl is valid or correct, and also
when you want to ensure that a user enters data if it is required. Validation Rules differ from
configuring your Data Storage Layer to not allow nulls because you can customize the error
message the user receives with Validation Rules. When developing applications for companies,
you are often working with existing data that has been imported into Vinyl. If you were to set a
Data Storage Layer field to not allow null values, you may result in errors if data imported
contains nulls. This is another reason to configure a Validation Rule at the Business Logic Layer
vs. change the Data Storage Layer.
In this example, we will create a Validation Rule to make the FirstName column of the
Employee table a required field. This Rule will only require one table, the Employee table, in
the Business SQL configuration.
1. Navigate to the Vinyl IDE, select Build your application from the Build menu
2. Click on the Business Logic Layer button
3. Click the BOBJ icon for your application data source
38
VINYL USER GUIDE

5. Assign a Name for this Validation Rule. For example: Employee (FirstName Required)
6. Select the Purpose as Validation
7. Set the Target as Employee (Source)
8. Click Save
9. Click the SQL cogs icon to define the Rule
10. Click Create under Tables, and select the Employee table. Click the checkmark icon to
add it.
11. Click the PK button to add in the Primary Key Column for EmployeeID
12. Click Create under Columns, and then select the FirstName column. This is the column
we want to mark as required.
13. Click Create in the Where panel, and select E.FirstName as the Left value, set the
Operator value to IS NULL, and click the checkmark on the left to save the information
The Business SQL for the Employee (FirstName Required) Validation Rule
At this point we have finished configuring the Validation Rule in the Business Logic Layer. Like
any other Rule we create in Vinyl, for this to work in the UI Layer, we need to attach it to an
Event in order for it to function. We’ll look at configuring this connection in the next chapter.
Chapter Exercise: Create a Validation

❖ Follow the steps outlined to create a Validation Rule, and create a new Validation Rule that
makes the LastName column required for the Employee table.
Validation Rules and Events

Validation Rules must be added to the Events of a Business Object in order for it to function or
fire. The process to do this is similar to how we configured adding a CRUD Rule to an Event,
except that instead of adding the action in the Actions panel we will add the validation in the
Validation panel. The Validation Rule will get added to the existing Save Event, and does not
require a custom Event to be configured.
39
VINYL USER GUIDE
Next, we will step through configuring the Validation Rule we created for Employee
(FirstName Required) so that it is attached to an Event.
4. Click to select the Employee table, on the left Tables panel
5. Under the Rules panel, click to select the Events icon for the Employee (Source)
Business Object
6. Click to highlight the Save Event in the tables panel, and then click the Create button
in the Validations panel
7. For Rule, select Employee (FirstName Required) from the list
8. Set the Type to Rule
9. Set the Severity to Error
10. In the Message field, enter First Name Required. This is the actual message that will get
displayed to a user when this Event gets triggered.
11. Set the Error Type to Fail on data returned
12. Set the Binding Type to Implicit
13. Use the Technical Help field to provide a brief description of the Validation, such as
“Employee’s First Name is Required”
Configuring the Validation Rule to be attached to the S ave Event
15. Test that the Validation Rule is properly configured by navigating to the application’s
Employees page and creating a new Employee record with an empty or null FirstName
field. Make sure that the error message displays.
40
VINYL USER GUIDE
Chapter Exercise: Attach a Validation Rule to an Event

❖ Follow the steps outlined to attach the Employee (FirstName Required) Validation Rule to
the Save event, create a new Validation for the Employee (LastName Required) Validation
Rule. Attach this new Validation to the Employee (Source) Business Object.
UI Layer
Now that we’ve built out a good amount of Business Logic for our application, we’ll look at the
UI Layer and practice a few design elements we can add into the application that we haven’t
reviewed yet.
Board Panels
Board Panels function similar to Multi-row Panels in that they also allow multiple records of
data to be displayed, but different in that rather than showing all the records as rows on a grid
(MRP) they display as many Single-Row Panel looking boards on a page. Board Panels are
mostly used for aesthetic reasons. Board Panels do not support inline Create, Edit or Delete,
but do support linking to another page where you can edit values.
Employee page with Board Panel Type
In this example we will convert the existing Employees page, which is currently a Multi-row
Panel Type, into a Board Panel Type.
1. Navigate to the Employees page in the application
2. Click on the Action Drawer, and select Design this page from the menu
3. Click the pop-up icon to expand the Employees Multi-row Panel
4. Click the Edit button, and change the Type value to Board Panel
5. In the Intrinsic Control Options area, change the Create Mode value to be Link to Page
41
VINYL USER GUIDE
The Employees MRP converted to a Board Panel
7. Test the updates by Running the page or refreshing the application’s Employees page.
8. In the current state, the Employees page has too many Controls on it for an optimal
Board Panel Type page. Board Panels look best with just a few Controls. Go ahead and
remove all Controls except: Photo, Full Name, Title, and Email.
Chart Panel
Vinyl supports multiple Chart Types on Pages, using the Chart Panel Type. To use Charts in
Vinyl, you typically need to have an aggregate value defined in a Business Object. We don’t yet
have an aggregate value defined, so for this example we will first make a new Business Object
to use and then add a new page for a Chart. Here we will be adding in a Column Chart that will
display Order Total by Employee.
Create a Business Object with an Aggregate Value

1. Navigate to the Vinyl IDE, and select Build your application
2. Click the Business Logic Layer button, and the BOBJ icon for your data source
4. Assign the Name OrderDetail (Total by Employee)
5. Set the Purpose as Business Object
6. Target the OrderDetail table
7. Click Save
8. Click the SQL cogs icon to define the Business SQL
9. Add the Order and OrderDetails tables
10. Inner Join the Order table to the OrderDetails table
11. Join Columns by OrderID = OrderID
12. Click Create under Columns and add in the syntax:
SUM(OD.Quantity*OD.UnitPrice*(1-OD.Discount))
42
VINYL USER GUIDE
13. Alias this Column as SumLineTotal

14. Click Create under Columns and add in the EmployeeID column
The Business SQL for the OrderDetail (Total by Employee) Bus iness Object
15. Click the Results button and check to see the results are as expected
Create a Chart
Now that we have a Business Object with an aggregate value defined, we can add in a new
page to the application that will contain a Chart.
1. From the application, click the Action Drawer
2. Select Add a page
3. Assign the Name Order Total by Employee
5. Click Create under Panels, and select the Type Chart Panel
6. Select the Chart Type as Column
7. For the Source Rule, select the Business Object we just created, which is OrderDetail
(Total by Employee)
9. Click Create under Controls, and select EmployeeID as the Column
10. Select Category as the Control Type. Category represents the x axis for Charts in Vinyl.
11. Under List Control Properties, select Employee (Full Name List) for Data Object
12. Set the Key as EmployeeID
13. Set the Title as Employee
14. Click Save
15. Click Create to add another Control, for Column select SumLineTotal
16. Set Control Type to Value. Value represents the y axis for Charts in Vinyl.
17. Click Save
18. Run the page to confirm that the Chart looks as expected
43
VINYL USER GUIDE
The Column Chart that represents Order Total by Employee
Badging
Badging allows you to apply a small badge to Buttons in Vinyl. Badges work similar to how
they do on smartphones, where they create small notifications in the top right corner of a
button that gives you a dynamic number representing something. For example, you might
have a badge notification of 20 next to an Orders button, indicating you have 20 new Orders.
Badges in Vinyl are configured using information from a Column, such as an Order Count, and
put on a button to provide users with a view of their underlying data in a very convenient way.
In this example we will apply a Badge to the Orders button on the Customers page. We are
going to use Badging to display the count of orders on the Orders button. If you do not have an
Orders button Control appearing on your Customers page, go ahead and add one in prior to
following these steps.
1. Navigate to the Customers page in the application
2. Click the Action Drawer, and select Design this page from the menu
3. Select the Customers panel, and click the pop-up icon to expand the Orders button
4. Click the Edit button under Miscellaneous, and select CountOrders as the Badge
Source
6. Test that the badging worked correctly by navigating back to the application
Customers page and refreshing. You should now see the badge and its corresponding
information appear on the Orders buttons.
44
VINYL USER GUIDE
The Orders button with Badging applied to it
Reach
Reach is a row level security feature in Vinyl that you can implement in applications. It allows
you to restrict the data that certain Users have access to throughout the application. Users will
still be able to navigate to the same pages, but the data displayed on each page will be
customized to only show the data that the individual User should be seeing.
In the example we look at here for using Reach in our Northwinds app, we will apply Reach to
restrict the Customer records shown to a User based on a Region : Employee mapping.
Following this type of implementation logic, often the UserID Column is what needs to be
added to Table(s) where you want to restrict information by a value in that Table. Other values
than UserID can be used, but our example will work with UserID.
To use the UserID Column referred to in this example, we call this from the User_Read data
object that ships with Vinyl. First we’ll walk through establishing a connection to the Vinyl data
source that contains the User_Read object we need:
CREATE A DATA SOURCE CONNECTION TO VINYL
1. From the app view, click the Action Drawer icon and select Design a data source
2. Click Create
3. Click the dropdown menu in the Name column and select Default – Vinyl (Sealed)
4. Click the checkmark icon to save
45
VINYL USER GUIDE
Screenshot of the Vinyl (Sealed) Data Source added to an Application
Now that we have added the Vinyl (Sealed) Data Source to our application, we can add in the
Columns that need to get added to Tables for this particular example to work.
The Region table that we created earlier in the Vinyl Introduction Manual will be used to
restrict the Customers that an Employee User can view, based on the market they are assigned
to: East Coast or West Coast. We also added the RegionID column to the Employee table as a
foreign key, but now we will add it to the Customer table.
ADD REGIONID TO THE CUSTOMER TABLE
1. Navigate to the Customer page in the application

2. Click on the Action Drawer icon and select Design a data source
3. Click the Tables icon for your Northwinds data source
4. Click the right chevron icon on the Customer table to expand it
5. Click the Create button in the Columns panel
6. Name the column RegionID
7. Set the Logical Data Type to Unique ID, and the Physical Data Type to UUID
8. Make sure the PK Settings are as follows:
PK Settings for the RegionID Column
CREATE THE RELATIONSHIP FOR THE PRIMARY AND FOREIGN KEYS
For Reach to work with this example, it is not required to define the Relationship RegionID has
in the Customer table (in relation to the originating Region table), however, it is considered
best practice in data base design to do so. Here we will define the Relationship information.
1. Locate the Relationships area on Table panel
2. Click on the Many to One up arrow icon
46
VINYL USER GUIDE
Relationships area where we define a Many to One Re lationship
3. Click Create
4. Set the Primary Table value to Region. This indicates the source Table where the key
originated from.
5. Confirm that the Secondary Table value is Customer
6. In the Binding Keys section confirm the Primary Columns and Secondary Columns
values are RegionID
7. Click Save
Relationship Tables and Keys Configuration
8. Click X to exit out of the Relationship screen
ADD USERID TO THE EMPLOYEE TABLE
1. Click the Action Drawer icon, and select Site Menu

2. Launch your app and navigate to the Employee page
4. Click on the Data Storage Layer button
5. Click the Tables cog icon for your application data source
6. Click the right chevron icon on the Employee table
7. Click the Create button in the Columns panel
47
VINYL USER GUIDE
8. Name the column UserID

9. Set the Logical Data Type to Unique ID, and the Physical Data Type to UUID
10. Make sure the PK Settings are as follows:
PK Settings for the UserID Column
Note: In this case, we do not define a Relationship between the keys because the User_ID
comes from a separate database than the Employee table.
48
VINYL USER GUIDE
Add Region List Control to the Customer Page
In the Introduction Manual we added a Region List Object to the Employee Page and
associated some of our Employees with the available Regions from the Region table. Now that
we have added RegionID to the Customer table and the Customer (Source) Business Object,
we can add a Region List Control to the Customer Single-Row Panel Pop-up page as well.
1. Navigate to the Customers page, and click the Pop-up icon to view the Customer Single-
Row Panel page
2. Click the Action Drawer icon
3. Select Design this page from the menu
4. Click Create under Controls
5. For Column, select RegionID
6. Change the Control Type to List
7. Select Region (List) as the Business Object Set
8. Set the Key to RegionID
9. Set the Title to Region
10. Click Save
11. Close out of the Control window by clicking the X icon
12. Edit the Position value for the Region Control so that it appears before the Customer
location information.
13. Return to the app, refresh the page, and then open a dozen or so Customer records and
use the Region List Control we just created to select U.S. for half of them, and Non-U.S. for
the other half.
The Customer Pop-up page with Region List Control Added
49
VINYL USER GUIDE
Add User List Control to the Employee Page
Now that we have added UserID to the Employee table and the Employee (Source) Business
Object, and connected the Vinyl Data Source, we can add a User List Control to the Employee
Pop-up page to associate an Employee’s record with their User Name.
1. Navigate to the Employees page, and click on the Pop-up icon to view the Employee
Single-row Panel
2. Click the Action Drawer icon
3. Select Design this page from the menu
4. Click Create under Controls
5. For Column, select UserID
6. Change the Control Type to List
7. Under List Control Properties, Select User_Read as the Business Object Set
8. Set the Key to UserID
9. Set the Title to UserName
10. Click Save
11. Close out of the Control window by clicking the X icon
12. Edit the Position value for the Region Control so that it appears just under the Photo
control.
13. Return to the app and refresh the page. Use the User List Control just added to associate
your User Name with one Employee record.
The Employee Single-row Panel page with Region List and User Controls Added
50
VINYL USER GUIDE
Define a Reach Rule
Now that we have some Employees and Customers associated with Regions, and a UserID is
added to the Employee table, we are ready to move to the Business Logic Layer. Here we will
create a Reach Rule to check the User’s Reach, and then register the Reach Rule on a Business
Object so that Pages built out of it filter the results they display based on a logged in User’s
Reach.
1. From the app Employee page, click on the Action Drawer and select Design this page
2. Click on the Business Logic icon for Employee (Source)
3. Click the Create button under the Rules panel
4. Assign the Name Employee (Reach by UserID)
5. The Purpose will be Reach
6. The Target should be set to the Employee table
7. Click Save
8. Click the SQL cogs icon to define the Business SQL for this Business Object
9. Click the Create button under Tables and add in the Employee and Region tables
10. In the Columns panel, add the RegionID from the Employee table
a. Click the pop-up icon for RegionID, and set Usage Type to Reach Token
11. Click Create button again for the Columns panel and add in an Employee Name field
for debugging purposes. E.g., E.FirstName||' '||E.LastName
12. In the Where panel, set the UserID from the Employee table equal to Who(‘UserID’).
Business SQL for the Employee (Reach by UserID) Reach Rule
13. Click the Results button and verify that you see the expected record(s) returned
51
VINYL USER GUIDE
Reach Registration
Before we can use the Reach Rule on a page and see it in action, we need to explicitly register
our Reach Rule on a data object. In this case we will join our Reach Rule to the data object that
the Customers page is using. This should be the Customer (Order Count) Business Object.
1. Navigate in the app to the Customers page, click on the Action Drawer and select
Design this page
2. Click the Business Logic icon for the Customer (Order Count) Business Object
3. Double-click the Customer (Order Count) Business Object, and click on Edge Case
Settings
4. Click on the Reach icon
5. Click the Create button
6. For the Rule value, select the Reach Rule created. For example: Employee (Reach by
UserID)
7. Binding Column is required information, this should reflect the Column you set as
Reach Token on the Reach Rule (RegionID).
Registering the Reach Rule
8. Click Save
9. Now test by navigating to the Customer page in the application and refresh the web
browser. You should now only see Customer records from the Region assigned to your
User.
10. To help confirm the records are correct, add Region ID to the Customer page panel
Controls.
52
VINYL USER GUIDE
Bridge
Fundamentally, a Bridge can be thought of as the connection between a launching page, and
a landing page. A Bridge is an application level concept which enables a designer to send a
message to a user. This message may have multiple options which define how the user can
respond to the message. When options are present in a Bridge, the user's response is
automatically tracked by Vinyl.
Message Types
Currently a Bridge can use one of the following message types:
• Email - Not surprisingly, an email.
• SMS - An SMS message sent and received by the Twilio service.
• Vinyl Alert - A popup which shows up in the user's browser when they are logged into
Vinyl. Formerly called a Notification.
All message types support adding options which provide ways to for the user to respond to a
message. For Emails and Vinyl Alerts, URLs are included in the message that link back to Vinyl.
In the case of the SMS delivery type, you can also reply to an SMS with the name of the option
to run the associated event.
Future releases of Vinyl will likely support sending messages to REST servers.
Options
Bridges can have 0 or more options. When a Bridge contains no options, there is no expected
user response and consequently, no tracking of the user's response is provided. No links will be
added to the outgoing message. This is considered an Informational bridge.
When a Bridge contains 1 or more options, a message is sent with URL links back into Vinyl that
allow the user to respond in some way. The user's response to the message (i.e. which option
they selected) is tracked by the Bridge.
Configuration
Bridge options can be configured in two ways:

1. Link to page - A link is provided which allows the user to navigate to a page.
Successfully navigating to the page is considering a complete response to the option.
2. Run page event - A link is provided which sends the User to a page and runs a specified
Event before the page is rendered. Again, the User's response is considered complete
once the Event is triggered.
For a page to be eligible for either option above, the page must be marked Shared.
53
VINYL USER GUIDE
As an example, an Admin may execute an Event that causes an email to be sent to an End
User. The email has some text and three buttons in it:
1. Review - Clicking Review can bring the User to a specific page in Vinyl
2. Approve - Clicking Approve can bring the User to a different page AND execute an
Event against some data objects in the page
3. Reject - Clicking Reject can bring the user to a different page AND execute an Event
against the same page or a different page's data objects
The Event must be executed before the page is rendered as it may affect data that is contained
in the panels on the page. To execute an Event, the designer must:
• Make the Link To page Shared.
• Include the Event in either the Data Object for the page or as one of the Single-Row
Panel data sources on the page. Further illustration of this point is available in the Data
Object Event Binding section below.
Data Object Event Binding
Vinyl limits the Events that can be bound to a link. Specifically, this limitation only allows for
events that belong to a Data Object / Table that is bound to an unbound Single-Row Panel on
the target page. For example, let's consider a page that has 6 Single-row Panels:
• Customer -> CustomerAddress -> CustomerMap
• Employee -> EmployeeAddress -> EmployeeMap
In this example, Customer and Employee panels are not bound to any other panels on the
page. Therefore, a designer can choose events from those two panels data sources (along with
a page data object if one is specified).
Vinyl also limits the events that can be bound to non-system events. For example, the designer
cannot link back to the Save, Insert, Update or Delete events.
Bridge Registration
Linking to a Bridge
The Bridge Registration page in the Vinyl IDE allows the designer to link a Bridge to an
application. This is a 1 to 1 relationship. Additional information about the Bridge message can
be configured within the Bridge Registration.
Message Creation
The Bridge message can be defined in the Template section of the Bridge Registration page.
This is the main content of the Bridge itself.
54
VINYL USER GUIDE
Substitutions are performed on the Template and use the {{fieldname}} syntax. Substitutions
may add an optional url flag to indicate the value is an url and requires url-encoding e.g.
{{fieldname|url}}.
In regards to substitution, the body may contain:
In which case CustomerName must be contained in the Bridge rule's columns along with the
other required fields.
For emails, a Subject can be specified in the Bridge Registration page. The Subject field also
supports substitutions.
Translations
Bridges support rudimentary translations. There are three fields which are used for translations:
1. Bridge Option Name
2. Bridge Registration Message
3. Bridge Registration Subject (for Emails)
When creating the Bridge message, Vinyl will attempt to find translations for each of these
fields, assuming that their content specifies the corresponding translation key. The designer
also needs to add the keys to the translation bundle for the app manually (they are currently
not imported automatically for an app). Care must be taken with the Template field to add the
translation key as a raw string and not as HTML. There is a "code" icon at the bottom right of
the Bridge Registration Template field which allows you to directly edit the string.
Limitations
The event executed in the option link belongs to the Page Data or a Single Row Panel Data
Object. Currently, we do not display any validation results or post messages for page level
events. In other words, the event runs first, when it completes, the user is redirected to their
page. By the time they arrive at their page, the event results are lost.
Therefore, if the event has a post message or fails validation, the system will not show those
results to the end user. The designer can easily workaround this by displaying data in their
panels that changes based on the successful execution of an event.
Because of the above limitation, validation warnings will cause an event to not execute. We do
not have a UI in place that allows for the user to accept or reject the warning.
55
VINYL USER GUIDE
Bridge Public Data Objects

The public data objects used as Bridge targets are defined below.
Common Columns
These columns are common across the Bridge public data objects:
Bridge_Email_Send
The Bridge_Email_Send public data object is similar but not entirely consistent with the Smtp
Email Plugin functionality. The columns for the Bridge_Email_Send public data object are as
follows:
Bridge_SMS_Send
The Bridge_Sms_Send public data object is used for sending SMS. The columns for
the Bridge_Sms_Send public data object are as follows.
56
VINYL USER GUIDE
Bridge_Vinyl_Alert_Send
The Bridge_Vinyl_Alert_Send public data object is similar but not entirely consistent with
the Create_Notification public data object. The columns of
the Bridge_Vinyl_Alert_Send public data object are as follows:
Bridge Setup Example

Steps to setting up a Bridge. We'll assume that we're adding a Customer Approval Bridge to
the Northwinds Customers page.
Create a Bridge
Create a rule that targets a Bridge public data object.
Steps to Create Bridge

4. Click Create under Rules
5. Assign a Name for the new Rule. For example: CustomersRequestApprovalAlert
6. Select Bridge as the Purpose
7. Set the Target to Bridge_Vinyl_Alert_Send
57
VINYL USER GUIDE
8. Click the SQL cog icon to enter the Business SQL

9. Add your ‘Select From’ table. For example: Customer
10. Add the following Select Columns:
11. Note that we add "CustomerName" so that we can later use it as a substitution
parameter in our Bridge message.
Register Bridge with Application

2. Click the Bridges icon for your application
3. Click Create to add a new Bridge
4. Select the Bridge Rule we just created. For example: CustomerRequestApprovalAlert
5. Enter the Message information you want to appear for the Bridge. For example:
Please review the following customer:
Customer: {{Customer}}
6. Click Save
Define Bridge Options
Optionally define a landing page and prelaunch Event to run.

2. Click the Bridges icon for your application
3. Click the Pop-up icon to expand information on the Bridge we just created
58
VINYL USER GUIDE
4. Click Create under the Options panel

5. Set the Index value to 10
6. Set the Name to Review
7. Select the page to link to. In our example we'll link to the Northwinds 'Customer' page.
If the page you want to link to doesn't show up, ensure that it's been marked as
"Shared" in Edge Case Settings.
Register Bridge with an Event
Register Bridge as an Action with an Event. In this case, we're assuming the Event is associated
with a button on the launching page. We'll also assume the event is called 'Request Approval'.
1. Navigate to the Event for the Data Object. For example: Vinyl IDE > BUILD your
application > Northwinds > Pages > Customers > Customers Panel
2. Go to the Action Drawer > Design this page > click into the Business Logic icon
3. Click on Events for your Data Object
4. Select the Event. For example: Request Approval
5. Create an Action
6. Select Bridge as the Action Type
7. Select the Bridge we created in the previous step. For
example: CustomerRequestApprovalAlert
8. Click Save
9. Verify that the Explicit Bindings are correct. For example: CustomerId – CustomerId
Here's a screenshot example of what a Bridge Action should look like:
The Bridge Action configuration
Test it out!
At this point, the Bridge is completely set up. Navigate to your page, and click the button that
runs the Bridge event. All Vinyl users on the system should see a pop up with the Bridge
message.
59
VINYL USER GUIDE
SMS Bridge Setup

Steps to setting up an SMS bridge. We'll assume that we're adding a Customer Approval Bridge
to the Northwinds Customers page.
You will need access to a Twilio account to complete setup.
Setup Vinyl Security

1) Navigate to Vinyl IDE > Connect to your enterprise > Security Providers
2) Click Create on User Authentication panel.
a) Enter a name. For example: "Http Basic Auth"
b) Select HTTP Basic Authentication as the type.
c) Click Enabled to enable.
d) Click Save.
3) Navigate to Vinyl IDE > User Management
4) Double click the user you want to authenticate as when a SMS reply comes in.
5) Note that this user must have access to the following:
a) Vinyl application
b) The event that will be executed on the bridge itself.
6) Click the Keys icon
7) Click Create
8) Select the Http Basic Auth provider we created earlier.
9) Click Save
10) Note the secret "Key" that is created for this provider. The combination of the user name
and the secret key will be used when configuring Twilio.
Setup Twilio
Create Messaging Service

1) Log into your Twilio account
2) Navigate to Communications Cloud > Programmable SMS
3) Click Messaging Services
4) Create a new Messaging Service (Notifications, 2-way) and attach a Twilio phone number to
it.
5) Note down the MessagingServiceSid. This will be used for configuration later on.
6) Enable the Process Inbound Message option.
7) Enter the following Request URL:
a) https://<username>:<secret_key>@<your_vinyl_server>/webhook/v1/vinyl/bridge_inboun
d
b) E.g. https://admin:P124asfgOmkA@vinyl.zudy.com/webhook/v1/vinyl/bridge_inbound
Gather Twilio Credentials

1) Navigate to Console Dashboard > Settings
2) Note down the LIVE credentials:
a) Account Sid
b) Auth Token
60
VINYL USER GUIDE
Configure Vinyl SMS Endpoint

1) Navigate to Vinyl IDE > Connect to your enterprise > Notification Servers
2) Double click the SMS record
3) Click Edit and add the following configuration:
a) User Name -> Twilio Account Sid
b) Password -> Twilio Auth Token
c) MessagingServiceSid -> Twilio Messaging Service Sid
Configure Vinyl Website URL

1) Navigate to Vinyl IDE > Connect to your enterprise > Security Providers
2) Under Configuration click Edit
3) Set the Web Site URL to your website URL
a) E.g. https://vinyl.zudy.com
4) Click Save
Configure Vinyl SMS Bridge
Create Bridge
Create a rule that targets a Bridge public data object.
Steps to Create Bridge
1) Navigate to Rules
a) For example: Vinyl IDE > Build your application > Business Logic Layer > Northwinds >
Rules
2) Create a new Business Rule
3) Select Bridge as the Purpose
4) Select Bridge_Sms_Send as the Target
5) Click Save
Define Bridge mvSQL
6) Navigate to the mvSQL

7) Add your 'select from' table.
a) For example: Customers
8) Add the following select columns:
61
VINYL USER GUIDE
Note that we add "CustomerName" so that we can later use it as a substitution parameter in
our Bridge message.
Register Bridge with Application

1) Navigate to Bridges
a) For example: Vinyl IDE > Build your application > Northwinds > Bridges
2) Create a new Bridge Registration.
3) Select the Bridge Rule you created in the previous step. .
a) For example: Customer_RequestApprovalSms
4) Enter the following message for the bridge:
5) Click Save
Define Bridge Options

We will define two options. Once which is activated by replying to the SMS, another which is a
link to a page.
1) Navigate to Bridges
a) For example: Vinyl IDE > Build your application > Northwinds > Bridges
2) Open the details for the bridge we created in the previous step.
3) Click the Options tab
4) Create a new option:
a) Set Index to 10
b) Set Name to Review
c) Select the page to link to. In our example we'll link to the Northwinds 'Customer' page.
If the page you want to link to doesn't show up, ensure that it's been marked as
"Shared" in Edge Case Settings.
d) Set the Option Type to Link
5) Create a new option:
a) Set Index to 20
b) Set Name to 1
c) Select the page to link to. In our example we'll link to the Northwinds 'Customer' page
and run the 'Approve' event.
d) Set the Option Type to SMS Reply.
Register Bridge with an Event

Register Bridge as an Action with an Event. In this case, we're assuming the Event is associated
with a button on the launching page. We'll also assume the event is called 'Request Approval'.
1) Navigate to the Event for the Data Object
a) For example: Vinyl IDE > Build your application > Northwinds > Pages > Customers >
Customers Panel
2) Click Business Logic
62
VINYL USER GUIDE
3) Click Events for your Data Object

4) Select the Event
a) For example: Request Approval
5) Create an Action
6) Select Bridge as the Action Type
7) Select the Bridge we created in the previous step.
a) For example: Customer_RequestApprovalSms
8) Click Save
9) Verify that the Explicit Bindings are correct.
a) For example: CustomerId - CustomerId
Here's a screenshot example of what a Bridge Action should look like:
The Bridge Action configuration
Test it!
At this point, the Bridge is completely set up. Navigate to your page, and click the button that
runs the Bridge event.
Beyond the Advanced Training Manual
This concludes the Vinyl Advanced Training Manual. If you’re looking for more information on
learning and working with Vinyl, please see the online Knowledge Base at http://wiki.zudy.com
Zudy Clients should access the Knowledge Base from within Vinyl, go to the Action Drawer
menu and select Support. Zudy employees can access the Knowledge Base either via the Vinyl
Support link or by going to http://wiki.zudy.com and clicking the Azure button to authenticate.
63

Vinyl Advanced Training Manual

Uploaded by

Document Informationclick to expand document information

Document Informationclick to expand document information

Copyright:

Available Formats

Vinyl Advanced Training Manual

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Vinyl Advanced Training Manual

Uploaded by

Copyright:

Available Formats

VINYLTM ADVANCED TRAINING MANUAL

1560 Lenox Ave • Suite 203

Miami Beach, FL 33139

Phone 305.763.8287 • Fax 305.763.8452

LAST UPDATED 12/4/2019

LAST UPDATED 12/4/2019

Data Storage Layer

Contains all the tables where the physical data is stored.

Business Logic Layer

Northwind Data Structure

Data Storage Layer

Data Storage Layer Navigation Link

Logical Data Types for Table Columns

The Product Table’s Discontinued Column is an example of a Boolean Logical Data

PHYSICAL DATA TYPES AVAILABLE FOR BOOLEAN

PHYSICAL DATA TYPES AVAILABLE FOR CURRENCY

Date, Date/Time, Time

PHYSICAL DATA TYPES AVAILABLE FOR DATE

❖ Date - Date only

PHYSICAL DATA TYPES AVAILABLE FOR EMAIL

❖ Char - Character data of fixed length

PHYSICAL DATA TYPES AVAILABLE FOR FILE

PHYSICAL DATA TYPES AVAILABLE FOR HTML

❖ NVarchar - UNICODE character data of indeterminate length.

PHYSICAL DATA TYPES AVAILABLE FOR NUMBER

PHYSICAL DATA TYPES AVAILABLE FOR PHONE

❖ NVarchar - UNICODE character data of indeterminate length.

PHYSICAL DATA TYPES AVAILABLE FOR PHOTO

PHYSICAL DATA TYPES AVAILABLE F OR STRING

❖ Char - Character data of fixed length

1. Click the Action Drawer and select Vinyl IDE

PK Settings available for a Column

PHYSICAL DATA TYPES AVAILABLE FOR UNIQUE ID

❖ Char – Character data of fixed length.

PHYSICAL DATA TYPES AVAILABLE FOR URL

❖ NVarchar - UNICODE character data of indeterminate length.

Logical Data Types for Storing Address and Phone Data

Vinyl Data Services

The Employee Email Column is defined as an Email Logical Data Type

Email Validation Error from Vinyl Data Services

Insert, Update and Delete

Edge Case Settings available for a Table

7. The CRUD Support Control Set contains three options:

Chapter Exercise: Modify the Product Table

1. Click the Action Drawer icon, and select Vinyl IDE

8. Click the Save button

Chapter Exercise: Set a Default on the Product Table

The Category Column has Usage defined as Title

Other Common Usage Types

The Table Definition panel where you

TABLE RELATIONSHIP TERMINOLOGY

Chapter Exercise: Create a Relationship on the Supplier Table

Here we added Cascade On Delete to the Order to OrderDetail table Relationship

10. Click Save

The Union Join Rule Name, Purpose and Target

9. Click the Save button

View Details information on the Union Join Rule