Download Powerpoint

Full Integration of
Custom Fields and Custom Tables
2013 User’s Conference
Adam Ploshay
Rebecca Swords
Introduction
Hi!
How’s it going?
Did you see that ludicrous display last night?
Agenda
• Introduction
• Agenda (this slide)
• Using Custom Table Builder
–
–
–
–
–
Configuration
Templates
Custom Reports, Search
E-Form Extensions
Alerts
• Modifying XML Data Objects
–
–
–
–
Data object overview
XML-only modifications
Data object changes that also require database access
Creating entirely new tables or views
• Q&A
Custom Tables: Configuration
• Add info to student record (tied to idnumber)
• Up to 20 tables, 50 fields/table
• Specify:
– Label
– Description
– Data type
– Referenced code table
• May require clearing code cache or relaunch
General Configurations
-> Custom Fields Configuration
-> Custom Tables Configuration
General Configurations
-> Custom Fields Configuration
-> Custom Fields Configuration
Custom Tables: Templates
• Use to populate custom table
• May require re-launch before configuring
Custom Tables:
Custom Reports and Search
• Requires closing, relaunching sunapsis
• After that, they work just like any other table
This sounds so easy, it
makes me almost as
happy as this turtle.
Almost…
Custom Tables: E-Form Extensions
• Case study: using custom fields to control eform access
• Override isSupported
– Return true or false: is the person who is logged in
allowed to access services with this extension?
– Query jbCustomFieldsXX
Custom Tables: E-Form Extensions
• Can be used in any part of the extension:
– appendFormData – append custom data to an eform
– modifyService – conditionally show or hide fields
based on values of custom data
– verifyFormAction – ensure that form data is
compatible with custom data (or have an error
message if not)
Custom Tables:
Alerts
• Any idnumber-bearing table can be queried for custom alerts
• Some resources for writing custom alerts:
– AbstractCustomFieldMatchAlertService.cfc
• For logic based on a particular field value match
• See: ExampleCustomFieldMatchAlertService.cfc
– AbstractCustomFieldRangeAlertService.cfc
• For logic based on particular field value range
• See: ExampleCustomFieldRangeAlertService.cfc
– AbstractCustomTableMatchAlertService.cfc
• For logic based on particular table/view presence/absence
• See: ExampleCustomTableMatchAlertService.cfc
– BlankAlertService.cfc
• For anything!
Data Objects
• Used to describe table data and how it’s displayed
• Can configure (among other things):
–
–
–
–
–
Help text
Field labels and order
Field visibility
Field constraints
Record selection structure (“menu”)
• Official Sunapsis files: ioffice/xml/dataobjects_XXX.xml
Do NOT edit the Sunapsis files.
• Create your own (Edit these):
ioffice/xml/dataobjects_XXX_institution.xml
• Your institutional XML takes precedence
IMPORTANT Notes!
A friendly reminder from your neighborhood license agreement:
“Licensee may not modify the System other than to extend the System
through the pluggable component infrastructure for table views, alerts,
reports, e-mail services, and e-forms.”
• We strongly encourage you to make backups before applying
upgrades
• You should also review your custom XML and database changes
after any update
• We don’t support your database changes
• We don’t guarantee that the database structure won’t change
• We do reserve the right to laugh at you if you break something :D
Parts of a Data Object
<dataObject>
Attributes:
• name* – database table name
• label* – desired window title
• module – use “sunapsis”
Elements:
• menu
• description
• primary key*
• foreign key*
• datums*
• constraints*
Menu
<menu>
– How record list appears,
which data is included
– Attribute:
• type - “tree” or “list”
– Use % around field names
to put in record value
<menu type=“list”>
%label% (%tableName%)
</menu>
Tree Menu
Use | between tree levels:
<menu type=“tree”>
%campus% | %alertGroup%
</menu>
Description: Help Text
<description><![CDATA[
Customize help text here! <br /><br />
Use HTML tags to add formatting. ]]>
</description>
Keys
Configure primary and foreign keys, as they are
in the database.
<primaryKey>recnum</primaryKey>
Use self-reference if there is no foreign key:
<foreignKey dataObject="configCustomTables"
key="recnum"/>
Datum
• Order of datums matters
• Attributes:
–
–
–
–
key* – column name in database
label* – label displayed in Sunapsis
type* – data type
length – maximum number of characters (no more than DB
limit)
– data – required, recommended, optional
– display – show the field, or not
– sort – “asc” or “desc”, records are sorted by this field
– encrypt – if field should be encrypted (special requirements)
• Element: reference – for fields to reference a code
table
Datum with Reference
• Display a descriptive value rather than a code (ex:
“Mexico” vs. “MX”)
• Reference attributes:
– dataObject – table that is being referenced (no selfreference)
– valueKey – code column
– displayKey – description column
<datum key="country" label="Country" type="string" length="5">
<reference dataObject="viewCodeCompleteCountryList" valueKey="code"
displayKey="description"/>
</datum>
Constraints
•
•
•
•
•
Add constraints or data to fields
Run on submit
Attributes: type, key
Elements: compare, constant
Examples (see dataobjects_xml_overview for
more):
–
–
–
–
RegularExpressionConstraint
CompareDatesConstraint
ConditionalRequiredConstraint
AssignUserFullNameConstraint
Constraint Examples
<constraint type="AssignUsernameConstraint" key="username"/>
<constraint type="RegularExpressionConstraint" key="sevisid">
<constant>N\d{10}</constant>
</constraint>
<constraint type="ConditionalRequiredConstraint" key="alertGroup">
<compare>type</compare>
<constant>A</constant>
</constraint>
<constraint type="CompareDatesConstraint" key="prgStartDate">
<compare>prgEndDate</compare>
</constraint>
Complete Data Object
<dataObject name="jbPassport" label="Passport" module="sunapsis">
<menu>%cpass%: %passiss% - %passexp%</menu>
<description><![CDATA[ Passport info, see also <a href="40">this KB article</a>. ]]></description>
<primaryKey>recnum</primaryKey>
<foreignKey dataObject="jbInternational" key="idnumber"/>
<datums>
<datum key="lastname" label="Last Name" type="string" length="50" data="recommended"/>
<datum key="firstname" label="First Name" type="string" length="50" data="recommended"/>
<datum key="midname" label="Middle Name" type="string" length="50"/>
<datum key="cpass" label="Passport Country" type="string" length="5">
<reference dataObject="codeCountry" valueKey="code" displayKey="description"/>
</datum>
<datum key="passnum" label="Passport Number" type="string" length="255"
data="recommended" encrypt="true"/>
<datum key="passiss" label="Issue Date" type="date" sort="desc"/>
<datum key="passexp" label="Expiration Date" type="date" data="recommended"/>
<datum key="datestamp" label="Last Updated" type="datestamp"/>
<datum key="recnum" label=" " type="integer"/>
<datum key="idnumber" label=" " type="integer"/>
</datums>
<constraints/>
</dataObject>
Changing the
General Configurations Menu
• Official Sunapsis (don’t edit): display.xml
• Institution specific (edit this):
display_institution.xml
• <generalCodesDisplay> - menu configuration
– <set label=“Menu Title”>
– <dataObject> attributes
• reference – table name (data object name)
• view – multi or single (multiple records allowed)
• width, height, preferredHeight – configure dimensions
Changing the
Individual Display
• Modifications to Record Management
• Can only add, not remove
• Example use case: add a custom view of
student data that should be available from
their record
Data Objects XML:
Table/View Mods w/SQL changes
• So, you’re thinking of adding new fields to an existing table/view?
• Considerations:
–
–
–
–
Might break current code (!)
Might break future updates (!!)
Will require reviewing, merging XML from future updates (!!!)
Generally, DON’T DO IT. I DON’T KNOW WHY WE’RE EVEN TELLING YOU
ABOUT IT. Might seem desirable if you need new data in a 1-1 relationship
with an existing table/view. But road to hell is(1) paved with good intentions,
and (2) has an on-ramp any time you say “I know a shortcut!”
• Changes Needed:
– SQL: New fields needs to allow NULLs, or set default values
• This is so that you avoid breaking existing INSERT code
– XML: Copy into your _institution XML, add new fields
• This is necessary for your field to show up in the user interface
• Even if they have display=“false”, they should still be recorded here for the sake of
documentation
TOTALLY
PLAUSIBLE
EXAMPLE:
adding Pizza
Delivery Zone
to jbAddress
Data Objects XML:
SAMPLE Table Mod w/SQL changes
• EXAMPLE: Add a “pizza delivery zone” field on jbAddress:
– SQL:
– XML:
–
–
–
–
Please
Don’t
Do
This
ALTER TABLE dbo.jbAddress
ADD pizzaDeliveryZone INT NOT NULL
CONSTRAINT DF_jbAddress_pizzaDeliveryZone DEFAULT (0)
<dataObject name="jbAddress" label="Addresses"
module="sunapsis">
…
<datums>
…
<datum key="pizzaDeliveryZone“ label="Pizza Delivery Zone"
type="integer" />
…
</datums>
<constraints/>
</dataObject>
Data Objects XML:
Adding new tables/views: Overview
• Considerations:
– If it is an idnumber-bearing table, use the Custom
Tables Configuration, instead.
• Better yet, have someone else use it!
– This is useful for views, and non-idnumber tables
• Changes Needed:
–
–
–
–
Create the table/view, in the database
Update user permissions, in the database
Create the XML representation of the table/view
Relaunch sunapsis
Data Objects XML:
Adding new tables/views: SQL
• 3 SQL Steps:
– 1: Create your table/view
• Format: <prefix><institution name><description>
Example: codeIUBPizzaTopping
• See spreadsheet of standard table name prefixes
– 2: Update user permissions
• EXEC dbo.spIOfficeRoleUpdate --updates user permissions
• Additional configuration needed for a non-standard table
prefix. Don’t use those.
– 3: Generate skeletal XML description
• EXEC dbo.util_GetColumns 'someTableNameGoesHere'
• Copy resulting message text (2nd tab)
Data Objects XML:
Adding new tables/views: XML
•
2 XML Steps:
– 4: Paste skeletal XML into <prefix>_institution.xml file, modify
•
•
•
Label, (Module), Menu, Description
primaryKey, foreignKey
Datums: Required Fields
–
–
–
•
Datums: Optional Fields That May Be Already Set
–
•
If your table has lots of references, consider adding a '1' argument to the util_GetColumns call for longForm
Datums: Constraints
–
•
Sort: none/asc/desc (note importance of datum order)
Data: optional/required/recommended
Display: true/false
(Module)
Encrypt: false/true
» Note that encrypted fields need a database type of nvarchar(255), regardless of XML type
Datums: References
–
•
Length: no restriction by default, pre-set for nvarchar/varchar fields
Datums: Other Optional Fields
–
–
–
–
–
•
Key: pre-set
Label: will need to be changed
Type: pre-set, may need to be changed (for labels, and for nvarchar or datetime fields)
(see list)
Optionally add XML-only datums: header, paragraph
– 5: Add into display_institution.xml (if applicable)
Data Objects XML:
SAMPLE Table Addition: SQL 1/2
• SQL Steps:
– 1: Create your table
CREATE TABLE [dbo].[codeIUBPizzaTopping](
[recnum] [int] IDENTITY(1,1) NOT NULL,
[code] [nvarchar](5) NOT NULL,
[description] [nvarchar](20) NOT NULL,
CONSTRAINT [PK_codeIUBPizzaTopping] PRIMARY KEY CLUSTERED
(
[recnum] ASC
)WITH (PAD_INDEX = OFF, …
) ON [PRIMARY]
– 2: Update user permissions
EXEC dbo.spIOfficeRoleUpdate
--updates user permissions
Data Objects XML:
SAMPLE Table Addition: SQL 2/2
• SQL Steps:
– 3: Generate skeletal XML description
• EXEC dbo.util_GetColumns
• Copy message text:
'codeIUBPizzaTopping'
<dataObject name="codeIUBPizzaTopping" label="codeIUBPizzaTopping" module="">
<menu></menu>
<description><![CDATA[
codeIUBPizzaTopping
]]></description>
<primaryKey>recnum</primaryKey>
<foreignKey dataObject="codeIUBPizzaTopping" key="recnum" />
<datums>
<datum key="recnum" label=" " type="integer" display="false" />
<datum key="code" label="code" type="string" length="5" />
<datum key="description" label="description" type="string" length="20" />
</datums>
<constraints/>
</dataObject>
– a
–
–
Data Objects XML:
SAMPLE Table Addition: XML 1/2
• XML Steps:
– 4: Paste skeletal XML into code_institution.xml file, modify
•
<dataObject name="codeIUBPizzaTopping" label="Pizza Toppings“ module="sunapsis">
<menu>%description% (%code%)</menu>
<description><![CDATA[
Lists Aver’s Pizza toppings.<br/>
NOTE: All other pizza places are inferior and therefore irrelevant.
]]></description>
<primaryKey>recnum</primaryKey>
<foreignKey dataObject="codeIUBPizzaTopping" key="recnum" />
<datums>
<datum key="recnum" label=" " type="integer" display="false" />
<datum key="code" label="Code" type="string" length="5" />
<datum key="description" label="Description" type="string" length="20" />
</datums>
<constraints/>
</dataObject>
– a
–
–
Data Objects XML:
SAMPLE Table Addition: XML 2/2
• XML Steps:
– 5: Add into display_institution.xml (optionally)
<?xml version="1.0" encoding="iso-8859-1"?>
<display xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ...>
<individualDisplay> ... </individualDisplay >
<communityDisplay> ... </communityDisplay >
<sevisBatchDisplay> ... </sevisBatchDisplay >
<domCodeDisplay> ... </domCodeDisplay>
<generalCodesDisplay>
<set label="IU Specific: Pizza Logistics">
– a<dataObject reference="codeIUBPizzaTopping"
view="multi"
– width="600" height="200" preferredHeight="200" />
–</set>
a
</generalCodesDisplay
>
– a
</display>
Data Objects XML:
SAMPLE View Addition: SQL 1/2
• SQL Steps:
– 1: Create your view
CREATE VIEW [dbo].[viewStudentRecordQuotedUniversityID]
AS
SELECT
jbInternational.idnumber
,'`' + jbInternational.universityid AS universityid
FROM jbInternational
– 2: Update user permissions
EXEC dbo.spIOfficeRoleUpdate
--updates user permissions
Data Objects XML:
SAMPLE View Addition: SQL 2/2
• SQL Steps:
– 3: Generate skeletal XML description
• EXEC dbo.util_GetColumns ' viewStudentRecordQuotedUniversityID '
• Copy message text:
<dataObject name="viewStudentRecordQuotedUniversityID“
label=" viewStudentRecordQuotedUniversityID" module="">
<menu></menu>
<description><![CDATA[
viewStudentRecordQuotedUniversityID
]]></description>
<datums>
–<datum
a key="idnumber" label=" " type="integer" display="false" />
key="universityid" label="universityid" type="string"
–<datumlength="11"
/>
–
</datums>
<constraints/>
</dataObject>
Data Objects XML:
SAMPLE View Addition: XML 1/2
• XML Steps:
– 4: Paste skeletal XML into code_institution.xml file, modify
•
<dataObject name="viewStudentRecordQuotedUniversityID“
label="Quoted University ID" module="sunapsis">
<menu></menu>
<description><![CDATA[
Lists the University ID preceded by a backquote (`) to prevent
automatic numeric conversion in Excel.
]]></description>
<datums>
<datum key="idnumber" label=" " type="integer" display="false" />
–<datum
a key="universityid" label="University ID" type="string"
length="11" />
–
</datums>
–
<constraints/>
</dataObject>
Data Objects XML:
SAMPLE View Addition: XML 2/2
• XML Steps:
– 5: Add into display_institution.xml (optionally)
[this space intentionally left blank]
– Nope! Not applicable in this case. Just need it for custom
reports.
Q&A
– Questions (from you folks)
– Answers (from us)