Flex Fields

Technical Specification Document

 Product Design Specification

Flex Fields
Document Title: Flex Fields Technical Specification document

Document Filename: STXade_DS_FlexFields.doc

Description: Describes the design details for supporting flex fields for few core objects
Current Owners: Lakshmi Satish
Status (Draft, In Review, Stable): Draft

Document Approvals:
Date Approver Name Role Approval Status (Pending,
In Review, Approved)
Sudhakar Senior Manager

Document Revision History:

Version # Date Revised by Remarks

Content
1 Introduction................................................................................................................6
1.1 Dependencies..........................................................................................................................6
1.2 Goals.......................................................................................................................................6
1.3 Non-goals................................................................................................................................6
1.4 Assumptions............................................................................................................................6
2 References.................................................................................................................7
3 Architecture Overview..............................................................................................8
4 Solution Overview.....................................................................................................9
4.1.1 Implementation Approach...............................................................................................9
4.1.2 Alternate approaches considered along with analysis....................................................9
5 Design Overview.....................................................................................................10
5.1 Design Principles..................................................................................................................10
5.2 Design Model........................................................................................................................10
5.3 Design Patterns Used............................................................................................................10
6 Database Layer........................................................................................................11
6.1 Schema..................................................................................................................................11
6.2 ETL Design...........................................................................................................................17
6.3 Dataset Design......................................................................................................................17
6.4 Naming Conventions:...........................................................................................................17
6.5 Flex XML Schema:...............................................................................................................17
6.5.1 Things to note about flex XML.....................................................................................17
6.5.2 Example Flex XML for AddUpdate operation..............................................................18
6.5.3 Example Flex XML for Search operation.....................................................................18
6.5.4 Example Flex XML for Get operation...........................................................................19
6.6 TI Design...............................................................................................................................19
6.7 Common Data Cache............................................................................................................19
6.8 Database Triggers.................................................................................................................19
6.9 Workflow Events..................................................................................................................19
6.10 Common Libraries/APIs....................................................................................................20
7 Presentation Layer..................................................................................................21
7.1 Menu/Sitemap.......................................................................................................................21
7.2 Common Controls/Libraries.................................................................................................21
7.2.1 Class: ObjFieldDefinition..............................................................................................21
7.2.2 Class: ObjFlexFieldDisplay...........................................................................................21
 7.2.3 Class: ObjFlexFormBinder............................................................................................21
7.3 Master Pages/Templates.......................................................................................................21
7.4 Style Sheets/Skins.................................................................................................................21
7.5 Pages.....................................................................................................................................22
7.5.1 Add/Update Pages.........................................................................................................22
7.5.2 Search UI.......................................................................................................................22
7.5.3 Grid/List UI...................................................................................................................23
7.5.4 Summary UI...................................................................................................................24
7.5.5 JavaScript: Page function modifications.......................................................................25
7.6 Master Page Reference..........................................................................................................25
7.7 Skin/StyleSheet Reference....................................................................................................25
7.8 Control Reference.................................................................................................................25
7.9 Controllers.............................................................................................................................25
8 Service Layer...........................................................................................................26
8.1 Services Contract..................................................................................................................26
8.2 Web Services Design............................................................................................................26
8.3 DataTransfer Objects............................................................................................................26
8.4 Scheduled Jobs......................................................................................................................26
8.5 Cache.....................................................................................................................................26
8.6 Common Libraries................................................................................................................27
9 Data Access Layer..................................................................................................28
9.1 ORM......................................................................................................................................28
9.2 Stored Procedure APIs..........................................................................................................28
9.2.1 New Stored Procedures.....................................................................................................28
9.2.2 Modifications to Stored Procedures:.................................................................................30
9.3 Considerations for Flex fields support in Activity:...............................................................33
9.4 Transaction Scope/Management...........................................................................................33
10 Integrations..............................................................................................................34
11 Impact of Existing Process....................................................................................35
11.1 Notifications......................................................................................................................35
11.2 Upgrade.............................................................................................................................35
12 Design Foundation..................................................................................................36
12.1 Performance and Scalability..............................................................................................36
12.2 Security..............................................................................................................................36
12.3 Globalization.....................................................................................................................36
12.4 Diagnosis and Supportability............................................................................................36
12.5 Setup and Deployment......................................................................................................36
 12.6 508 Support.......................................................................................................................37
12.7 Hosting Update..................................................................................................................37
12.8 Backward Compatibility....................................................................................................37
12.9 Third party.........................................................................................................................37
13 Unit Test Plan..........................................................................................................38
14 APPENDIX................................................................................................................39
14.1 Products and tools Used....................................................................................................39
14.2 Future Enhancements........................................................................................................39
14.3 Design Issues.....................................................................................................................39
15 Traceability Matrix...................................................................................................40
1 Introduction
Flex fields denotes flexible fields support for core entities in LMS. By flexible fields we mean the
ability to add new fields on the core entities. Flex fields allow the object to be extended with
additional information as per the needs of the customer. Flex fields will be available in the LMS
system as part of the data import options, UI display and form, data list pages and object search
functionality. However, they do not participate in the business rules and business logic associated
with the LMS.

1.1 Dependencies
None

1.2 Goals

1. Add new fields to objects (user, job, activity, etc.)

a. Fields of type integer, string (nvarchar max), date, decimal, float, bool, lookup
2. Adding new lookup type
3. Ability to show flex fields in UI
a. Add/update screens
b. List pages
c. Object Pickers
d. Summary pages
4. Ability to search on core + custom fields
a. Ability to do custom validation on flex fields before saving the object

1.3 Non-goals

1. Hiding core fields in add/update or summary UI

2. Sorting on flex field columns in data grids
3. Field level security for flex fields
4. Multi-valued lookup
5. UI for defining new lookup types or adding values to them
6. Custom renderer for flex fields of above types
7. Cross entity search (for example search on primary job name for an employee)
8. Grid extension shows cross-entity fields (core or flex fields)
9. String type for flex field are localized (L10N)
10. Support for password type of fields or similar advanced functionality
11. CFR Auditing of flex fields
12. Search on translated values

1.4 Assumptions
None
2 References

Document File Name Document Title

3 Architecture Overview
The overall architecture for flex fields is based on the existing stack (2 tier) of LMS. The flex field
display in the UI and fetching flex data will use existing components, namely, the current rendering
functions and stored procedures. For retrieving metadata information such as entity definitions,
service class will be created, and used directly in the web application tier instead of hosting as
services and web services.
The reason for this design is:
1. Leverage the capabilities of existing framework (namely rendering, localization, 508,
performance, security and skill set)
2. Reduce the risk involved (by sticking to established processes and best practices)
3. Testability (by using the current automation framework and established practices)
4 Solution Overview
The high level Requirements document (HRD) for Flex fields can be found here:
http://intranet.sumtotalsystems.com/engineering/releasedocs/82%20SP5/2.%20Requirements
%20and%20Design/LM%20Extensibility/ST_HRD_ExtensibilityFramework.docx
This document details out the various requirements from flex fields and the scope of this exercise. It
also lists out the use cases from customer perspectivce from an extensibility point of view.

4.1.1 Implementation Approach

The approach for supporting flex fields is based on design on the existing architecture of the product.
This design leverages additional metadata stored in database for each extensible entity that lists the
flex fields, their data type, default values and other information. This metadata is used by flex
renderer and stored procedures to render/save the fields in create/edit form, list page data grids,
search popup page and summary display pages in the system. The display will be done after the core
fields (for each group, if there is an inherent grouping of fields on the page). The approach leverages
XML to pass flex field data to and from stored procedures. The stored procedures are responsible to
parse and process this XML to add/update the flex data in extension table or to search on the flex
fields using given criteria. The flex fields for an entity is also retrieved as flex XML returned as a
XML column in the select query from the retrieval stored procedures in the system (Get* and List*
procedures). The XML column is named FlexData in the Recordset.

4.1.2 Alternate approaches considered along with analysis

Another approach that was considered but found to be costly and riskier was using NHibernate and
service oriented principle. This required redesigning the entire stack of LMS architecture. Some
things such as performance are also not proven in those architectures and the ramp up required is too
high. A proof of concept was done using this new stack but discarded due to exceeding timelines and
heavy overheads.
5 Design Overview
5.1 Design Principles
The core design principal for flex fields is the fact that to add support for new field on existing
entity, no core code modifications will be required. This ensures that when a new service pack is
uptaken by customer, the flex fields are not overwritten by new assemblies in a patch. The flex fields
handling will be done by core logic, be it persistence of data, searching or retrieving. The flex fields
of course will need to be defined in a certain manner as per the guidelines and need to be of certain
data types. This way no logic needs to be implemented when a new field needs to be added to an
existing entity and core knows how to handle it along with the core fields.

5.2 Design Model

The following diagram illustrates the overall design of fetching flex fields and rendering them in the
UI.

5.3 Design Patterns Used

Provider pattern can be used to load the metadata service provider via configuration. Also, renderers
for flex fields could be used to render based on the type of field (int, string, date, etc.). Dependancy
injection can be leveraged to set the renderers for flex fields instead of creating hard coded
references.
6 Database Layer
6.1 Schema
The following entity relationship diagram depicts the various metadata tables and their relationship:

The following is the list of metadata tables:

Table Name Table Description

Meta_Entity All entities are stored in this table. This includes core entities
such as user, job, etc. as well as lookup entities
Meta_EntityDesc Translation values of entity name and description
Meta_EntityProperty All entity properties are stored in this table. This includes the
flex properties for the entity.
Meta_EntityPropertyDe Translation values of property name and description
sc
Meta_LookupData Lookup values are stored in this table for all lookup entity
types
Meta_LookupDataDesc Lookup value translations are stored in this table.
Meta_PropertyGroup Property group information for an entity are stored in this table
Meta_PropertyGroupD Translation values for property group’s name and description
esc
Meta_ProcMediator Columns: Core Procedure, Custom Procedure, Action Type,
IsOverwrite, IsActive, Order . This table stores compute
custom validation, do custom save, custom search and custom
display procedure names
The following table describes some important columns in the metadata schema:
Table Name Column name and Description
Meta_Entity  KeyName – Value used as key to identify the
entity. This value is not localizable and
used to identify if PK value cannot be used.
 EntityName – The name of the entity that is
localized. The translation is found in the
Meta_EntityDesc table.
 IsLookup – True if the entity is a lookup
entity. A lookup entity is entity similar to
supplemental data entities such as Content
Type, Delivery Methods, etc. in LMS product.
 ManagedDataType – The .NET type of the
entity. Includes the fully qualified name
such as System.String.
 IsSystemDefined – True if the entity is a
core entity and False if it is custom.
 DataTable – The table which stores the data
for the entity. For example, for Employee,
it is tblEmp.
 DataKeyColumn – The primary key column of
the data table. For example, for Employee,
it is Emp_PK
 IsExtensible – True is the entity can have
flex fields. Generally in such a case, the
schema will have an extension table to store
the extended data. For example, for
Employee, table called as tblEmpEx will
store the extension data for Employee.
 IsTranslatable – True if the entity’s
properties can be translated into other
languages. If True, generally there would be
a translation table to store the
translations. For example, for Employee,
table called as tblEmpDesc will store the
translations for the Employee properties
that are translatable.
 ExtensionTable – The name of the extension
table.
 ExtensionKeyColumn – The primary key of the
extension table. Comma separated list can
specify multiple primary keys
 ExtensionJoinColumn – The column on which
join should be made between the data table
and extension table.
 TranslationTable – The name of the
translation table.
 TranslationKeyColumn - The primary key of
the translation table. Comma separated list
can specify multiple primary keys
 TranslationLangColumn – The name of the
column that stores the language FK.
  ExtensionPropertyName – The property name on
the Managed entity type that has the flex
fields (as a dictionary).

Note: Some of these columns may not be useful in the

legacy approach for flex fields but are useful in the new
stack that leverages NHibernate.
Meta_EntityDesc  EntityName – The translated name of the
entity.
 Description – The translated description of
the entity.

Meta_EntityProperty  EntityFK – FK of the entity for which

property is defined.
 KeyName – Key for the property. This is a
string value that is not localized and can
be used instead of PK.
 PropertyName – The localized name of the
property
 Description – The localized description of
the property.
 SQLDataType – The persistence data type. Can
be SQL Server data type for the possible
values. Or we can create another column to
store OracleDataType as well.
 ManagedDataType – The .NET data type. Should
be fully qualified name such as
System.String.
 Size – The size of the property. For string
types, represents the maximum length. For
other types it may not be used.
 Precision – Useful for decimal types to
represent the precision (upto how many
decimal places)
 IsSystemDefined – True if the property is
core property. Flex fields have value set to
False.
 IsPassword – Represents if the property is a
password type of field. Such properties have
special behavior such as encryption, showing
* in the textbox, etc.
 IsEncrypted – Represents if the property is
stored in database in encrypted format.
 IsAudited – Reprsents if the property is
audited for changes.
 IsUnique – True of the property value be
unique across entities. For example,
username of an Employee.
 IsPrimaryKey – True if the property is the
primary key of the entity.
 IsLookup – True if the property is of type
Lookup. For example, the Employee Code
 property is of type lookup, where the lookup
is Employee codes.
 IsEntityReference – True if the property
references an entity type value. For
properties with basic data type this is set
to False. For properties such as
Employee.UserAccount this is True since the
Employee.UserAccount property references the
entity UserAccount.
 ReferencedEntityFK – The entity that is
referenced by the property if
IsEntityReference=true.
 IsTranslatable – True if the property is
translatable.
 IsManyToOne – True if the property is many
to one.
 IsOneToMany – True if the property is one to
many.
 IsOneToOne – True if the property is one to
one.
 DataTable – The name of the table where this
property gets stored.
 DataColumn – The name of the column in the
DataTable where this property is stored.
 DataKeyColumn – The name of the primary key
column in DataTable.
 LookupPropertyFK – If the property is of
type Lookup, then which property of lookup
entity this property represents.
 TranslationTable – The table that stores the
translations for this property
 TranslationColumn – The column that stores
the translations in the TranslationTable for
this property.
 TranslationKeyColumn – The primary key
column of the TranslationTable.
 TranslationLangColumn – The language column
of the TranslationTable.
 TranslationEntityManagedType – The .NET type
of the translation entity associated with
the entity.
 IsNullable – Whether the property accepts
null value.
 IsActive – Whether the property is active.
Only active properties are considered for
UI, storage and TI operations.
 IsRequired – True if the property is
mandatory to be supplied.
 IsEditable – True if the property is
editable. Non editable properties can be
displayed with textbox grayed out in the UI.
 IsListable – True if the property needs to
be listed in the data grid
 IsSearchable – True if the property needs to
be provided in search criteria
 IncludeInAudience – True if the property
should appear in audience rules.
 IncludeInSummary – True if the property
should be included in the display summary
page.
 DisplayOrder – The order of display of the
property in a group
 PropertyGroupFK – The FK of group the
property belongs to.
 DefaultIntValue – If property is type int,
the default value to be used when none is
supplied.
 DefaultStringValue - If property is type
string, the default value to be used when
none is supplied.
 DefaultDateValue - If property is type date,
the default value to be used when none is
supplied.
 DefaultBoolValue - If property is type bool,
the default value to be used when none is
supplied.
 DefaultFloatValue - If property is type
float, the default value to be used when
none is supplied.
 DefaultDecimalValue - If property is type
decimal, the default value to be used when
none is supplied.
 DefaultLookupValue - If property is type
lookup, the default value to be used when
none is supplied.
 MinIntValue – If property is type int, the
minimum value that is acceptable.
 MaxIntValue - If property is type int, the
maximum value that is acceptable
 MinDateValue - If property is type date, the
minimum value that is acceptable
 MaxDateValue - If property is type date, the
maximum value that is acceptable
 RegexPattern - If property is type string,
the regular expression value that is
acceptable
 ViewPermissionName – The name of the
permission required to view the field
 ViewPermissionValue – The int value of the
permission that is required to view the
field
 EditPermissionName - The name of the
permission required to edit the field
 EditPermissionValue - The int value of the
permission that is required to edit the
field
 Note: Not all the fields mentioned above would be used. Many
of the fields are useful when we have a design that leverages
ORM such as NHibernate.
Meta_EntityPropertyDe  EntityPropertyFK – The property for which
sc translation is provided
 LangFK – The language FK for the translation
 PropertyName – Translated property name.
 Description – Translated decription
Meta_LookupData  EntityFK – The lookup entity FK for the
lookup value. For example, Awards is a
lookup entity with values such as Power of
One, Employee Achievement Award, Sport
Awards, etc.
 ValueType – The type of the value, either
string or int or date.
 LookupInt – The lookup value if type is int.
 LookupString – The lookup value is type is
string. Mostly this would be the column that
would be used for lookups.
 LookupDate – The lookup value if type is
date.
 DisplayOrder – The order of display of the
lookup values (specially when shown in a
combo box in the UI)
Meta_LookupDataDesc  LookupDataFK – The lookup value for which
translations are stored.
 LangFK – The language FK of the translations
 LookupString – Translated string values for
lookup types and translated values.
Meta_PropertyGroup  EntityFK – The entity for which property is
being created
 KeyName – The key of the property name in
case PK cannot be used.
 GroupName – The translated name of the group
 Description – The description which is
translated.
 DisplayOrder – The order of display of
groups
 IsSystemDefined – True if the property is a
core property group and not a flex group
Meta_PropertyGroupD  PropertyGroupFK – The group for which
esc translations are stored.
 LangFK – The language for which translations
are sent.
 GroupName – The translated group name
 Description – The translated group
description
Meta_ProcMediator  KeyName – This is the key used to get
procedures associated with the business
operation. This would be the name of the
 core procedure itself.
 ProcName – Name of the procedure to be
invoked. The signature of the procedure
should match the core procedure.
 Description - Description
 IsActive – If the procedure should be
handled.

 These tables store the flex fields data for the entity. Table naming convention is
<coretablename>Ex. For example, to store data for flex fields for employee (tblEmp), the table
would be named tblEmpEx
 The table consists of following columns:
o Str1, Str2, Str3,… Int1, Int2, Int3,… Bool1, Bool2, Bool3,… Date1, Date2, Date3,…
Decimal1, Decimal2, Decimal3,… Float1, Float2, Float3
 The columns are fixed in number for each type of flex field that would be supported.
 The string columns are of type nvarchar(max) on SQL Server and CLOB on Oracle. They have
full text indexing enabled.
 The integer and date columns need to have indexes created on them to enable search.

6.2 ETL Design

Not applicable

6.3 Dataset Design

Not applicable

6.4 Naming Conventions:

 Naming of custom stored procedure: PS_*
 Naming of custom tables or extension tables: PS_*
 Naming of custom triggers, functions etc.: PS_*
 Naming of resources (RESX file): L_*

6.5 Flex XML Schema:

The flex fields stored in extension table can be represented as an XML. This XML would be used to
store as well as retrieve the data stored in relational extension table in the database. Using XML is
beneficial because it can be used as a single parameter to the stored procedure to pass all flex fields
and also to return all the flex fields as a single XML column in the returned Recordset. For search
procedures, the XML also serves to specify the criteria to be used for flex fields.

<object key=”job” id=””>

<field id=”” key=”” data-type=”” search-op=”” search-path=””>
<object id=”” key=””>
<field id=”” key=”” value=””><value><!CDATA[[]]></value>
</object>
<value><!CDATA[[ value goes here ]]></value>
</field>
 </object>

6.5.1 Things to note about flex XML

 At least one of the attribute ‘id’ or ‘key’ must be supplied for the <object> and <field> elements.
If both are supplied, the id value takes precedence.
 The element <object> inside the <field> element is used to expand the field when it is of
complex type such as lookup value. This may be required when returning the flex XML in a Get
operation and the flex lookup values need to be expanded.
 During the search operation on flex fields, the ‘search’ attributes for the <field> element is used
to specify the search path and function to be used. The path can be one of the values ‘id’, ‘name’
or ‘description’ and is only relevant in case the field is of type lookup. The functions can be ‘eq’,
‘gt’, ‘ge’, ‘lt’, ‘le’ or ‘contains’. The inner element <value> can be string, int, bool, etc. for in
case of lookup values the id or the text depending on the path that was specified. There is no
provision in the XML to specify ‘AND’ or ‘OR’ between the flex field expressions. This is
because AND operation is assumed in case multiple flex field search values are specified.
 <!CDATA[[]]> element inside the <value> can be used in case the value is string and contains
special characters such as ‘<’ or ‘>’. However if the ‘value’ attribute is specified, it takes
precedence over the child element <value>.
 Please note that the flex xml itself does not contain any metadata about the flex field definitions.
This is intentional since the flex field metadata is anyways stored in the metadata tables and
could be queried separately. Also, storing metadata along with the data will bloat the XML and
lead to performance issues. However, during the Get operation ‘data-type’ attribute can be sent
for the <field> element to avoid an additional lookup to cast the value in UI to appropriate type.
‘data-type’ values can be one of int, string, bool, datetime, float, decimal and lookup.
 For money type of flex fields an additional attribute ‘currencyid’ can be specified for the <flex>
element to denote the currency associated with the flex field of type decimal.

6.5.2 Example Flex XML for AddUpdate operation

<object key=”job”>
<field key=”SSN” value=”ABCDEF” />
<field key=”Salary” value=”20000.50” />
<field key=”AdditionalNotes”>
<value><!CDATA[[These are additional notes!!]]></value>
</field>
<field key=”Award”>
<object id=”1” />
</field>
</object>

This xml is passed to the AddUpdate stored procedure as the last parameter. The stored procedure
then parses the XML and stores the data in a relational extension table for the entity. Note that for
lookup type of flex field called ‘Award’ the <object> element is used to specify the value.
6.5.3 Example Flex XML for Search operation
<object key=”job”>
<field key=”SSN” search-op=”contains”>
<value><!CDATA[[ AB* ]]></value>
</field>
<field key=”Salary” search-op=”gt” value=”10000” />
<field key=”AdditionalNotes” search-op=”contains”>
<value><!CDATA[[“add*”]]></value>
</field>
<field key=”Award” search-op=”eq” search-path=”id”>
<value><!CDATA[[1]]></value>
</field>
</object>

This xml is passed to the search stored procedure as the last parameter. The stored procedure then
parses the XML and uses the data to populate temp table with object PKs that match the supplied
criteria. Note that for flex field ‘Award’ which is of type lookup, the search path has been specified
as ‘id’ and the value denotes the id value to be matched.

6.5.4 Example Flex XML for Get operation

<object key=”job”>
<field key=”Award” data-type=”lookup”>
<object id=”1”>
<field key=”Name”><value><!CDATA[[ Power of One]]></value>
</object>
</field>
<field key=”Salary” data-type=”decimal” value=”20000.50” />
<field key=”AdditionalNotes” data-type=”string”>
<value><!CDATA[[These are additional notes!!]]></value>
</field>
</object>

This xml is passed as the last column in the selected Recordset in the Get procedure. The xml itself
is created by a SQL function that reads entity extension table and metadata table for flex fields and
returns the flex XML. Note that for lookup type ‘Award’ the <field> element contains <object>
element that contains the ‘id’ value as well as the ‘Name’ value that could be used by the caller for
display purposes. The value itself is returned as per the preferred language of the user.

6.6 TI Design
For TI, there is an additional requirement. TI uses property names to identify the fields to import
from flat files. The property names should hence be unique. Hence unique constraint needs to be
ensured on the KeyName and Name columns in the Meta_Entity and Meta_EntityProperty tables.
Changes in TI to support Flex fields will be added as part of a separate design document.
6.7 Common Data Cache
There are no changes or additions for cache tables in LMS for supporting flex fields.

6.8 Database Triggers

No triggers are required to support flex fields. However, if foreign key constraints need to be
managed between the extension table and primary tables (such as for lookup fields), they need to be
delivered as a custom trigger (for SQL Server as constraints are managed via triggers). Default
values for flex fields are managed by core logic itself and not via triggers. Mandatory fields are also
managed by core logic via the validation on flex XML.

6.9 Workflow Events

Flex fields will be supported for entities and their associated pages (create, update, list, pickers,
summary). For workflows, such as registration, supporting flex fields is a separate topic and will be
covered as part of extensible workflow design which is a separate design document. This design
targets to add custom screens/steps before launching a workflow or after ending a workflow via
configuration.

6.10 Common Libraries/APIs

None
7 Presentation Layer
7.1 Menu/Sitemap
Sitemap extension is covered as part of a separate design document. Flex fields support for entities
does not bring in any additional requirements for the site map implementation.

7.2 Common Controls/Libraries

Components and classes required to display flex fields are listed below:

7.2.1 Class: ObjFieldDefinition

Class to define the structure of a flex field definition including the name, label, description, IsActive,
property data type, length, size and other details.

7.2.2 Class: ObjFlexFieldDisplay

1. DisplayFor – method to display a flex field (in non editable mode)

2. ListFor – method to display a flex field in data grid cell
3. EditFor – method to display a flex field in editable mode
4. SummaryFor – method to display a flex field in summary page
5. SearchFor – method to display a flex field in search page

Each method should display the label (localized) as well as the form input element or text for the
flex field. Translations for the label are returned from Metadata SP that returns entity definition and
its translations (stored in database in the *Desc tables).

7.2.3 Class: ObjFlexFormBinder

Class to create flex XML from submitted form input values that could be passed to the AddUpdate
stored procedure. These form input values are submitted during AddUpdate as well as search
operation.
The binder has two methods:

1. EditFor – method to create XML for AddUpdate operation from submitted form values.
2. SearchFor – method to create XML for search operation from submitted form values.

The above methods also validate the input to confirm that submitted data was as per the field
definitions and with valid values.

7.3 Master Pages/Templates

No new master pages or templates need to be created.

7.4 Style Sheets/Skins

 As per the existing guidelines the CSS class names would be used for styling the flex fields. No new
classes or CSS files need to be created.

7.5 Pages
Pages in LMS are broadly categorized in multiple types based on the functionality provided.
Add/Update pages allow creation or updation of entities while Summary pages allow to see brief
summary of entities important properties. The List pages show the search results of entities in a data
grid while the search popup show searchable fields for the entity.

7.5.1 Add/Update Pages

1. Similar lines as domain settings extension design.

2. UI refactoring to display flex fields in the groups (old groups and new custom groups), displayed
in the end within a group. Display of fields is done by ObjFlexFieldDisplay.DisplayFor method.
3. JavaScript validation similar to domain settings extension design.
4. XML creation for submitted data in add/update/search for flex fields (done by
ObjFlexFormBinder)
5. Show fields where IsActive=true and show form input where IsEditable=true. Done by
ObjFlexFieldDisplay.EditFor method.

7.5.2 Search UI

1. Show flex fields after core fields where IsSearchable=true (displayed in the end). Done by
ObjFlexFieldDisplay.SearchFor method)
 2. Create a new JavaScript function in SYS_Util.js that creates XML from flex fields in the
advanced search popup UI before returning to caller page
3. Submit form from caller page (use POST instead of GET wherever GET is being used)

7.5.3 Grid/List UI

1. Flex field is visible in data grid if IsListable=true in object field metadata (displayed in the end).
Done by ObjFlexFieldDisplay.ListFor method.
2. Use Grid event handlers that use custom XML to render the flex field in data grid
7.5.4 Summary UI

1. Show flex fields that have IsInSummary=true in the object metadata (displayed in the end).
Done by ObjFlexFieldDisplay.SummaryFor method.
7.5.5 JavaScript: Page function modifications
The page JavaScript function for validation should raise alert message in user’s preferred language
in case a flex field is mandatory and not supplied before submitting form data, or when the input text
does not match the actual field type. The modifications in page and JavaScript file would be similar
as done for domain settings extension.

7.6 Master Page Reference

No changes

7.7 Skin/StyleSheet Reference

No changes

7.8 Control Reference

No changes

7.9 Controllers
No changes
8 Service Layer
Metadata Service class will be created to expose the metadata definitions. Other than this, no other
service is required since the existing stored procedures are leveraged to add/update, get, search and
delete the entities. The service class will not be hosted as a service but directly leveraged in the web
application layer as an assembly.

8.1 Services Contract

Service operations exposed by Metadata service:
1. GetEntityDefinition
a. Returns the entity definition given the ID or the key name of the entity. Entity definition
consists of the entity’s key name, given name in default culture, property groups,
property definitions and translations of the entity name in supported languages.
2. GetLookupValues
a. Returns the list of lookup values (in specified culture) given the entity key name or ID.
These may be cached by the web application tier so that the lookup values are not
retrieved everytime they need to be displayed in the UI (such as inside a combo box)

8.2 Web Services Design

 The Metadata service can be exposed as web services. This helps the web service consumer to know
the flex fields for each entity type.
 Web services such as UserManagement can be extended to return the extended data object with flex
fields populated in operations such as GetUserById, GetUsers, SearchUsersByPath, etc. operations.
o A new property will be exposed on entities called as ExtendedData. This has properties that
map directly to the internal database table (tblEmpEx) that stores the extended values for
entity.
o Web services entities.xml will have an additional left join on the extended data table to fetch
all the values in the extended data table as part of the ExtendedData property. The
ExtendedData class exposes String1, String2, Date1, Date2, type of members.
o It is upto the consumer has to map the general property to a meaningful value using the
metadata definitions returned from the metadata service.

8.3 DataTransfer Objects

The data transfer objects will be value objects with no behavior and use the [DataContract] and
[DataMember] attributes. However, at this time no WCF would be used to host or expose the
services.

8.4 Scheduled Jobs

No new scheduled jobs are required for flex fields support.

8.5 Cache
The supplemental data cache needs to be extended to also cache the lookup types since they need to
be displayed as a combo box with translated lookup values in the UI. The
 ObjFlexFieldDisplay.EditFor and ObjFlexFieldDisplay.SearchFor methods will use the
supplemental cache to get the values and render the combo box.
In addition to lookup types, the flex field definitions also need to be cached. The field definitions
contain not only the metadata for flex fields but also the translated labels for these fields in all
supported languages. This cache can be a simple Hashtable lookup.
Cache will be populated on request and need basis. It never expires once cached. An alternate
approach would be repopulate the cached item from database if its duration in cache is longer than
few minutes and if it was currently requested.

8.6 Common Libraries

None
9 Data Access Layer
9.1 ORM
This design does not leverage an ORM solution.

9.2 Stored Procedure APIs

There are some new procedures that would be created under Core_Object package. These procedures
are meant for basic functions on core objects with respect to flex fields.

9.2.1 New Stored Procedures

New procedures need to be created for operations on flex fields such as add/update into extension
table, creation of flex XML and validation of the Flex XML.

Validation of Flex fields:

Procedure Core_Object.ValidateFlexFields
Name:
Action The procedure takes the flex XML as input and does basic validation of the
performed: xml data against the entity flex field definitions. For example, checking if
valid integer value was passed, required property was sent, string length
was not exceeded, date time is correctly specified, etc. The core procedure
for AddUpdate calls this procedure by default to validate the input flex xml
before saving the flex data
Input: Flex field XML
Output: Integer output parameter where 1=validation success, 0 = validation failed

Add update of flex fields:

Procedure Core_Object. AddUpdateFlexFields
Name:
Action The procedure takes the core object PK and type as well as the flex fields
performed: XML as input and inserts or updates data in the extension table for the core
object. For example, after saving data for employee in tblEmp, iwc_Usr,
etc. by core AddUpdate procedure, this procedure will be called which then
inserts or updates data in tblEmpEx table. The data to be inserted comes
from the flex field XML. This procedure will call the validation procedure
before saving the data if flag has been supplied for validation.
Input: PK of core object, object type, Flex field XML and flag to indicate whether
validation should be performed before save.
Output: Integer output parameter where 1= success, 0 = failed
Retrieving flex fields as XML:
Function GetFlexFieldsAsXml
Name:
Action The SQL function takes the core object PK, object type, language PK as
performed: input and creates an XML of the flex fields read from extension table. The
language PK can used to return the translated value of lookup types if they
need to be expanded.
Input: PK of core object, object type and language PK
Output: Flex fields XML as string or XML type

Searching on flex fields:

Procedure Core_Object. SearchFlexFields
Name:
Action The procedure takes the core object type and flex fields XML as input and
performed: populates a temp table that matches all objects that satisfy the flex fields
XML. The XML itself has flex field data and operation to be performed for
search such as contains, greater than, etc. Search would be done assuming
AND condition between all passed flex parameters. The temp table is the
one that would be left outer joined by the calling core procedure to filter
records based on flex field search criteria. The join is in effect only when
flex criteria was passed (left outer join #temp_flexsearchdata x on x.PK =
emp.Emp_PK and @i_FlexSearchSupplied = 1).
Input: Core object type, flex fields XML (with operation information)
Output: Temp table that contains records matching the flex field criteria

Retrieving metadata on flex fields:

Procedure Core_Object. GetFlexFieldDefinitions
Name:
Action The procedure takes the core object type as input and returns the flex field
performed: definitions for that object. The definition includes detail about the field
name, data type, length and size restrictions, etc.
Input: Core object type
Output: Recordset containing the flex field definitions

Retrieving lookup values on lookup types:

Procedure Core_Object. GetLookupValues
Name:
Action The procedure takes the lookup entity id as input and returns lookup values.
performed: The lookup values include the Id and name of the lookup value. Value is
translated as per logged in user’s preferred language.
Input: Lookup entity ID
 Output: Recordset containing the lookup values (translated as per logged in user’s
preference). This output may be cached in the web tier’s Supplemental
cache infrastructure.

Note: There is no stored procedure to add, update or delete lookup values since there is no UI being
developed to manage lookup values. If there is a UI requirement, the appropriate stored procedures
to AddUpdate, Delete and Get for lookup values need to be created similar to existing supplemental
data infrastructure (for example Delivery Methods or Content Types).

9.2.2 Modifications to Stored Procedures:

To allow adding, updating, retrieving and searching on flex fields, the relevant core procedures need
to be modified such that the flex fields are taken into account. Also, they should be part of the same
transaction as the core procedure to maintain data integrity.

Modifications to core AddUpdate procedure for flex field support:

Following changes in red color below highlight the changes that would be done in AddUpdate
procedure for core objects supporting flex fields:

Changes to core AddUpdate procedures:

%%PROCEDURE [Package name].AddUpdate[Object name]
{
%%BODY
{
… Code for core validation before saving

%%TRANSACTION
{
%%ON_ERROR
{
%%RETURN { 1 }
%%ROLLBACK{ Error ocurred while AddUpdateUser}
%%RAISE { exception_addUpdateUser }
}
… Core logic to insert records into core tables

… Get all active custom procedures that exist for AddUpdate in the procedure metadata table, call them for
saving flex fields (pass all parameters as the core procedure)

… In case of an error, %%ROLLBACK

}
}

The same changes have been depicted in a flowchart below:

Modifications to core Search procedure for flex field support:
Following changes in red color below highlight the changes that would be done in Search procedure
for core objects supporting flex fields:

Changes to core Search procedure:

%%PROCEDURE [Package name].List[Object name]
{
%%BODY
{
… create temp table

… Get all active custom procedures that exist for Search in the procedure metadata table, call them one by one
(pass all parameters as the core procedure). This results in the population of object PKs in the temp table matching flex
criteria

… Core logic to paginate with extra left outer join on temp table
… left outer join #temp t on t.PK = emp.emp_PK and @i_flexFieldsSearched=1

Select core fields + flex fields XML column from core table (flex fields XML is returned via a function call)
}
}

The same changes have been depicted in a flowchart below:

Modifications to core Get procedure for flex field support:
Following changes in red color below highlight the changes that would be done in Get procedure for
core objects supporting flex fields:

Changes to core Search procedure:

%%PROCEDURE [Package name].Get[Object name]
{
%%BODY
{
… core logic

Select core fields + flex fields XML column from core table (flex fields XML is returned via a function call)
}
}

The same changes have been depicted in a flowchart below:

9.3 Considerations for Flex fields support in Activity:
Learning activity entity in LMS is created or updated via the staging editor and follows a slightly
different model that other objects. It has the concept of staging and production and uses property bag
XML to define the UI. There are slight differences to support flex fields for the activity object which
have been mentioned below:

1. AddUpdate support for flex fields – The property bag implementation should be enhanced to
read the flex fields for entity and based on the group, display those fields also for editing (at the
end of the page). The display of the elements is done via the ObjFlexFieldRenderer object like
for other objects. This takes care of emitting the JavaScript for validation of the fields also. The
ObjFlexFieldFormManager would be used in the staging editor to capture the flex field form
values and form the XML. This XML would be passed to the procedure responsible for saving
activity properties in the database. The procedure would be modified as indicated in previous
sections to validate the flex XML and insert data into custom table (TBL_TMX_ActivityEx).
This table should follow the same principle as the core table that uses negative PK values to
identify the records in staging vs. those in production.
2. Search support for flex fields – The ListActivities procedure will take the Flex XML as
parameter and follow similar approach as mentioned above to populate a temp table and join this
table for search results including core and flex fields. However, care needs to be taken to handle
the staging and production records (as per the core functionality).
3. Display of flex fields in staging editor – The property bag implementation checks for flex fields
using Metadata in database for the activity group and renders the fields using
ObjFlexFieldRenderer. If activity is in staging, textbox in edit mode is displayed (EditFor
method) else the fields are displayed using DisplayFor method.
4. List activities in data grid – Follows similar method as listed above for other entities.

9.4 Transaction Scope/Management

Transaction support is provided as part of database transactions. Flex fields addition or updation will
be part of the core database transaction block in the stored procedure. The flex procedure to
add/update is called from core stored procedure from inside the transaction block in core procedure.
10 Integrations
Not applicable
11 Impact of Existing Process
None

11.1 Notifications
Flex fields to be made available in notification templates will be done via extensions in notifications.
This is covered as part of notifications extensibility design document.

11.2 Upgrade
On the database side, tables, stored procedures and system data needs to be installed. No upgrade
cost here. On the UI side, new assemblies, pages, and configuration will be available. Even in this
case upgrade is simple enough. However, once flex field support is installed, upgrading database and
web needs to be considered carefully as it may lead to flex fields not working as expected or data
being corrupted.
12 Design Foundation
The following sections describe the concepts that support the design, or the system foundation.
These sections include concepts such as performance, security, and globalization. Detail should
be included in these sections to show that they were considered during the design process and
considerations for them are accounted for.

12.1 Performance and Scalability

 The performance criteria of core product with flex field support remains the same (as in SP4
release). < 5% deviation
 Since the overall design leverages current architecture, the performance considerations are at par
with current practices.
 Performance with flex fields added via extensions needs to be at a level with < 10% deviation.
Since flex fields are also handled by core logic, the code should be written in a efficient manner
and in most cases this will eliminate the risk on performance with flex fields.
 Most of the overhead would be due to additional data being passed to database and search
enabled on flex fields. Full text Indexes need to be created on the flex fields of type string to
enable contains based searching.
 Other indexes may be required such as on integer or date columns in extension table. These need
to be created at the time of providing the customization (as part of the extension patch) or
customer can create an index directly in the database to speed up the search queries on those
fields.

12.2 Security
Scripting attacks are eliminated since the core UI display library functions are used for displaying
HTML. Dynamic SQL should be avoided in the new SQL functions of stored procedures that are
required for flex fields as it exposes SQL injection vulnerability

12.3 Globalization
The flex field property labels would come from the flex field definition cache. The lookup
translations come from the supplemental cache. JavaScript alert messages and error messages would
be stored in the RESX resource manager of web site. Naming convention for the resource classes
would be L_Flex_[ObjectKey].ResourceName for resources specific to the object. For common to
flex fields, L_Flex_Common.ResourceName

12.4 Diagnosis and Supportability

Logging will be done as per the predefined process in LMS for tracing the function entry and exit
calls. No special loggers need to be created.

12.5 Setup and Deployment

No special setup is required. However to get installed extensions in the application, activating,
inactivating, uninstalling them, the design is detailed out in the Module management design
document.
12.6 508 Support
The code to display Flex fields in the UI should leverage existing rendering functions (available via
ObjHtml classes). They already support 508 and other guidelines for UI development for 508 should
be followed in the ObjFlexFieldRenderer implementation for the EditFor, DisplayFor, SummaryFor,
SearchFor and ListFor functions.

12.7 Hosting Update

No changes for hosting.

12.8 Backward Compatibility

No special handling is required since existing database schema and web site is used without major
changes.

12.9 Third party

No external third part components are used for supporting flex fields.
Spring.NET 1.3 can be leveraged for DI and configuration.
13 Unit Test Plan
Unit testing will be done using Autom tool and testing the stored procedure. Service created for
metadata can be tested using NUnit framework.
14 APPENDIX
14.1 Products and tools Used
None

14.2 Future Enhancements

To be decided

14.3 Design Issues

Identify any problems that exist with the current design, so that they can be tracked and resolved.
All design issues should be resolved before the design is approved

Open Date Issue description Resolution Status

15 Traceability Matrix

RD Number FS Section DS Section