AureaCRM - Web DeveloperGuide 13.3

CRM Web Developer Guide
Version 13.2.0
Notices
Notices
Copyright © 2004–2021. Aurea Software, Inc. (“Aurea”). All Rights Reserved. These
materials and all Aurea products are copyrighted and all rights are reserved by Aurea.
This document is proprietary and confidential to Aurea and is available only under
a valid non-disclosure agreement. No par t of this document may be disclosed in
any manner to a third par ty without the prior written consent of Aurea. The information
in these materials is for informational purposes only and Aurea assumes no respon-
sibility for any errors that may appear therein. Aurea reserves the right to revise
this information and to make changes from time to time to the content hereof without
obligation of Aurea to notify any person of such revisions or changes.
You are hereby placed on notice that the software, its related technology and services
may be covered by one or more United States (“US”) and non-US patents. A listing
that associates patented and patent-pending products included in the software,
software updates, their related technology and services with one or more patent
numbers is available for you and the general public’s access at https://markings.ip-
dynamics.ai/esw/ (the “Patent Notice”) without charge. The association of products-
to-patent numbers at the Patent Notice may not be an exclusive listing of associa-
tions, and other unlisted patents or pending patents may also be associated with
the products. Likewise, the patents or pending patents may also be associated with
unlisted products. You agree to regularly review the products-to-patent number(s)
association at the Patent Notice to check for updates.
Aurea and Aurea Software are registered trademarks of Aurea Software, Inc. in the
United States and/or other countries. Additional Aurea trademarks, including regis-
tered trademarks, are available at: https://www.aurea.com/legal/trademarks/. Jive
is a registered trademark of Jive Software, Inc. in the United States and/or other
countries. Additional Jive trademarks, including registered trademarks, are available
at: https://www.jivesoftware.com/legal/.
Table of Contents
Preface............................................................................................................6
About this documentation.....................................................................................................................6
Notation conventions.............................................................................................................................6
Aurea global support.............................................................................................................................7
Chapter 1: Introduction................................................................................8
Chapter 2: Advanced designer Customizations.....................................10

Page Designer.....................................................................................................................................10
Form Designer.....................................................................................................................................13
Form Cells.................................................................................................................................15
Using Forms within Wizards....................................................................................................26
Generic Form Controls.............................................................................................................27
Special Forms...........................................................................................................................28
Global Scripts......................................................................................................................................30
Chapter 3: Client-Side Programming Concepts.....................................32

Architectural Overview........................................................................................................................32
Adding Client Code to the Application...............................................................................................35
Client Code Structure...............................................................................................................36
Controls and the Control Builder........................................................................................................36
Hook for client-side OnLoad Event.........................................................................................37
Controller Window...............................................................................................................................38
Details Control.....................................................................................................................................40
Expand Control....................................................................................................................................42
Controls for Accessing Server Data..................................................................................................43
Record Control..........................................................................................................................43
Query Control............................................................................................................................44
RecordSet Control....................................................................................................................47
RecordTree control...................................................................................................................48
Form Control........................................................................................................................................49
Creating a Form........................................................................................................................49
Calling a Generic Form from a Menu......................................................................................49
Form Hook Functions...............................................................................................................50
Static Form Definition...............................................................................................................51
Accessing Form Cells...............................................................................................................55
Customizing the Start Page.....................................................................................................57
Record Parameters in Forms...................................................................................................59
Using Query Result Lists as Record Input.............................................................................59
Passing Page Parameters to a Generic Form........................................................................60
Displaying a Generic Form in a Sub-List................................................................................60
Generic Controls in Forms..................................................................................................................62
Standard Generic Form Controls............................................................................................64
Generic Controls Interface Functions.....................................................................................69
Sample: Generic Form Controls..............................................................................................71
Parent Cell Notification............................................................................................................74
Sub Analysis Controls..............................................................................................................75
Analysis Input Controls............................................................................................................76
Client Code within Wizards.................................................................................................................78
Global Functions..................................................................................................................................79
Navigating to Pages.................................................................................................................80
Info Area Functions..................................................................................................................81
Client Caching...........................................................................................................................82
Conversion Functions...............................................................................................................82
Image Handling.........................................................................................................................82
Select Functions.......................................................................................................................83
MessageBox Functions............................................................................................................94
Calling Custom Code Before/After Sending E-Mails.............................................................96
JScriptCall Pages................................................................................................................................97
Other Controls.....................................................................................................................................98
The Generic List.......................................................................................................................98
The Tree View............................................................................................................................99
Implementing a Custom Match-Up..................................................................................................102
Calling an External Address Check.................................................................................................103
Opening a Mask Configuration Dialog.............................................................................................104
Displaying Contact Times in Day & Week Planning.......................................................................104
OTC | Using the Serial Entry in a Generic Form............................................................................106
Conditional Formatting for Tree Views.............................................................................................108
Generalization/Specialization aka Virtual Info Areas.....................................................................110
Chapter 4: Server-Side Programming Concepts..................................111

Introduction........................................................................................................................................111
Including Custom Code in Aurea CRM Web...................................................................................112
The mmObjects assembly................................................................................................................112
Core and CoreContext...........................................................................................................113
Business Objects and Conditions.........................................................................................115
Containers...............................................................................................................................118
Dedicated Business Objects..................................................................................................119
Business Object Events.........................................................................................................119
Custom Fields.........................................................................................................................121
Deriving Business Objects and Core....................................................................................122
Custom Links..........................................................................................................................122
The mmConfig Assembly..................................................................................................................125
Aurea CRM Web Assembly and mmChannels Assembly..............................................................126
Using Channel Events............................................................................................................127
Creating Custom Channels....................................................................................................128
Adding ASPX Pages to Aurea CRM Web........................................................................................131
Generalization/Specialization aka Virtual Info Areas.....................................................................131
Chapter 5: Other Programming Concepts.............................................133

Creating a Custom Cascading Style Sheet.....................................................................................133
XML Exports & Reporting......................................................................................................134
Notes on Generated XML Output..........................................................................................134
Export Options Reference.....................................................................................................135
How to Set Export Options....................................................................................................139
How to Create Reports from Multiple Queries.....................................................................142
Directly Calling a Report for a Query...................................................................................143
Displaying win Reports & Diagrams in web....................................................................................144
Preface
Preface
For details, see the following topics:
• About this documentation

• Notation conventions
• Aurea global support
About this documentation

This guide is par t of the documentation set for Aurea CRM.
Notation conventions
This document uses the following notation conventions:
Convention Meaning
Fixed-width Fixed-width font indicates code, path names, file names, envi-
ronment variable names, parameter names, command names,
machine names, URLs.
Bold Fixed- Bold Fixed-width font is used to indicate user input or to
width emphasize cer tain lines of code.
Italic Fixed-width Italic Fixed-width font indicates a placeholder for which you
must supply a value.
Bold Sans serif Bold sans serif typeface indicates the names of graphic user
interface elements such as dialog boxes, buttons, and fields.
Italic serif In text, italic serif typeface indicates the first use of an impor-
tant term. The term is defined in the glossary.
Underlined Underlined text in command lines and parameter descriptions
indicate that you only have to enter the underlined par t of the
command or parameter name. For example, if you use
the -LOGFILE parameter in a command, you only need to enter
-LOGF .
[ ] Brackets enclose optional arguments.

{ a | b | c } Braces enclose two or more items. You can specify only one
of the enclosed items. Ver tical bars represent OR separators.
For example, you can specify a or b or c.
AUREA CONFIDENTIAL 6
Preface
Convention Meaning
... Three consecutive periods indicate that you can repeat the
immediately previous item. In code examples, they can be
horizontal or ver tical to indicate omissions.
Menu > Choice An angle bracket between two menu items indicates that you
should choose an item from a menu. For example, the notation
File > > Exit means: "Open the File menu and choose Exit."
>> Links to related information in other chapters or documents are
indicated using the >> symbol.
Aurea global support

If you encounter a problem while using an Aurea product or require assistance with
downloading the software or upgrading a product release, please open a ticket on
Aurea Suppor t Central. Preferably, search the ar ticles on the Aurea Knowledge
Base for solutions to your issues before opening a ticket.
Information about the suppor t organization is available on Suppor t Central. The
product documentation is available athttps://help.aurea.com/crm/#.
For information about purchasing an upgrade or professional services, contact your
account executive. If you do not know who your account executive is, or for other
queries, contact us through our website.
Chapter 1: Introduction
1
Introduction
This document provides you with the information you need for customizing Aurea
CRM Web using the advanced designer features and by applying client- and/or
server-side using the provided SDKs.
There are three methods to customize and extend the functionality of Aurea CRM
Web:
1. Customize the application using Aurea CRM Designer.
2. Extend the client functionality by adding JavaScript code.
3. Extend the server-side framework by adding C# code.
The order of these methods reflects the complexity of using them – while it is rather
simple to use Aurea CRM Designer to customize the application, there may be some
specific features that cannot be implemented with this tool, and you will need to do
some JavaScript programming. In some cases - especially when you add ASPX
pages with server-side code - if you want to extend to underlying data model by
adding complex vir tual links or custom fields, or if you want to transfer data from
the server to the client in a way that is not suppor ted out-of-the-box, you may even
extend the server business logic using C# (or any other .Net programming language
you like).
The Aurea CRM Designer application itself and its mechanisms for handling config-
urations, users, and data stored in the designer database are described in the
CRM.designer chapter in the CRM.Web Administrator Guide.
With CRM.designer, you can perform simple customizations like defining field groups,
headers, menus, queries, analyses and wizards (described in the CRM.Web Admin-
istrator Guide) as well as advanced customizations as described in this document
in Advanced designer Customizations on page 10 which often only make sense in
connection with some programming.
With client-side programming you can e.g. extend the functionality of the details
control with field hooks, include project-specific record handling functions especially
in wizards, or even build your own custom pages using the existing Aurea CRM Web
framework. You can find details on the possibilities of client-side programming in
Client-Side Programming Concepts on page 32; additionally the Aurea CRM web
Client Reference (available separately as a .CHM file) provides you with a descrip-
tion of the complete client SDK.
The server par t of the Aurea CRM web application consists of the ASP.NET applica-
tion itself and the mmObjects.dll containing the Aurea CRM business logic (plus
some additional suppor t DLL’s). You can extend both by adding additional pages
to the application or including your own business logic DLL that derives from and
extends existing classes. You can find all information you require for server-side
programming in Server-Side Programming Concepts on page 111 of this manual; and
the Aurea CRM web Server Reference (available separately as two .CHM files)
provides you with the complete server SDK of Aurea CRM web. Other Programming
Concepts on page 133 of this manual provides you with information on some special
customization topics like XML repor ts.
Chapter 2: Advanced designer Customizations
2
Advanced designer Customizations
The following advanced customization options are available in Aurea CRM Designer:
• Page Designer on page 10: Allows you to register additional ASPX pages (or any
other content page) used in the application menu, context menus, direct buttons,
or wizards.
• Form Designer on page 13: Allows you to define custom generic forms to arrange
available controls and content on a page. You can e.g. use a generic form with
the Wizard Form page to prompt for user input, for star t pages, or with the
ShowForm page call to display content.
• Global Scripts on page 30: Allows you to add your custom JavaScript code to the
Controller window on the client.
Page Designer
All available standard pages and their parameters are registered in the Page Designer
(for detailed description of the most useful pages, see Aurea CRM Web Administra-
tion Guide).
On the designer main page, click on Page Designer to get a list of available pages.
For each page you have the standard options of adding, copying, viewing or deleting
pages.
Page Designer
Each page defined in the Page Designer has the following attributes:
• Callable from: Defines from where the Page can be called: from the application
menu (possible only if the page does not need a record parameter), from the
context menu (which also includes the possibility to call the page from a direct
button), and/or from within Wizards (if the page is “wizard enabled”). Any
combination of these options is possible.
• Description: A description of the page, visible only in Aurea CRM Designer.
• Page ID: Not used.
• Help ID: Used when the user opens the context-sensitive help (by pressing “F1”).
• Filename: Physical Filename of the ASPX page.
Note: To display the content of an URL in Aurea CRM Web, you can use the existing
standard page “URL”.
• Each page can have any number of parameters (listed in the 2nd “Query String
Arguments” section). A parameter Type is a combination of the type of element
and whether it is required or not.
The following Type parameters are available:
• Value: A text string.
• Record: A record consisting of two physical parameters: “Table” for the info
area and “Record-ID” for the record id. Note: Two additional Record types exist
for records with a fixed info area.
• Fieldgroup, Expand-Config, Search&List, HeaderGroup, Filter,
TableCaption, Treeview, Query, Form, Analysis: The name of a configuration
unit of that type (when configuring the page reference in menus etc. you may
either enter the name manually or select a unit from a combo box).
• RecordSet: A RecordSet consisting of records from one or more info areas.
• FormParam: A special structure used within wizards to pass user input from
a form to a page.
• Special: A placeholder that will be replaced by another value.
Each of the parameters listed above can be either fixed, mandatory or optional:
• Fixed: The value is defined in the Page Designer and cannot be modified in
the page call.
• Mandatory / Must: The value must be supplied in the page call.
• Optional: The value may be supplied or omitted in the page call.
• Each parameter has a Name and a Description (both visible in the Page Call),
and – depending on the type – some sor t of value.
• For each parameter you may enter a sor t number Nr.. In the Page Call, all
parameters are sor ted according to these numbers (and parameters without a
Form Designer
number are added at the end). The most impor tant parameters for your page
should have a number, but this numbering is only used within Aurea CRM Designer
and does not influence the web application.
Whether a parameter is available depends on the context of the Page Call:
• References from the application menu (where you have no context information):
No Record, but Form or Special parameters are available.
• References from the context menu: Besides Value parameters, use the Record
parameter of the record for which the context menu is displayed. If available, you
can also use the Linked Record parameter containing the linked record from the
SearchAndList page.
• References from direct buttons: The same rules as for context menus apply. On
SearchAndList pages, the record id of the selected record from the list completes
the Record parameter.
• References within wizards: You can use each input parameter of the wizard step
and each output parameter for the optional sub-step for the Page Call. You can
also use Form parameters.
Form Designer
Generic forms can be used e.g. to define formats like the activity execution format,
in wizards to enable users to enter custom data, or to create a role-specific star t
page. Using the Form Designer, you can define and/or modify generic forms.
Examples of existing generic forms are:
• ActExecution : Used to edit Activity Execution formats. ActExecution uses the
sub-forms
AD_eMail,AD_MailMerge,AD_SMS, AD_Std,
RecordFormat,SplitChars
and
Format:Label.
• StartPage_General : Used on the star t page.
• WizForm:OJPartType and WizForm:Y1PartType : Used in the “Create New Par ticipant”
wizard for Proper ties (OJ) and Oppor tunities (Y1) in the BTB ver tical; exemplifies
how to use a form within a wizard.
• TestDataViewer : An example of a form with dependent combo boxes.
On the designer main page, click on Generic Form to see a list of all available
forms. For each form you have the standard options of adding, copying, viewing or
deleting the form.
To create a new generic form, enter its name in the entry field at the bottom of the
page. From the combo box, select whether you want to create a new form or copy
an existing one and press the button.
Each Generic Form has the following attributes:
• Mask Type: Defines the primary layout of the form - select “Standard (Tabbed)”
for a form containing several tabs or “Plain” for a single tabbed form that has no
tabs on its top.
Note: “Steps (Tabbed)” is currently not implemented in Aurea CRM web.
• Description: A description of the form, visible only in Aurea CRM designer.

• Default Textgroup: The text group displayed by default when you create a new
text in Aurea CRM Designer.
• Hook-Function: An optional JavaScript function that allows you to react to events
such as initialization or a tab change via client code.
• Label: not unused.
• Width and Height: The fixed dimensions of the form.
A form consists of one or more tabs (depending on the type). To create a tab, click
the button next to “New Tab”.
If you are using a tabbed control (type=“Standard (Tabbed)” ), you can add
the Text displayed for the tab and set HTML attributes on the tab’s <table> element
using Attr.
A tab consists of one or many rows. Click the button next to “New Row” to add
a row.
Form Designer
For each row you can add Row-Attributes which are applied to the corresponding
table’s <tr> HTML element. For example style=’background-color:black;’ leads
to a black background for that row.
Note: No syntax check is performed, so syntax errors can lead to a corrupt form
layout.
Each row consists of one or many cells that are arranged horizontally. Select the
cell Type from the combo box and click the button to add the cell. The different
cell types and their attributes are described in the next section Form Cells on page
15.
If you want to rearrange elements on a form, cut an element using and then paste
it at another position using . (Note: You can also use to delete an element - the
removed element is still available from the paste buffer). The element is inser ted
before the element for which the paste button was clicked. You can cut and paste
tabs, rows and cells.
If you paste a row to a tab, the row is appended at the end of the tab. If you paste
a cell on another tab, it is added at the end of the first row. If you paste a cell on
another row, it is appended at the end of that row.
Form Cells
To add a cell to a form, select the desired cell type from the combo box and click
the button. The following cell types are available:
• Label to display a language-dependent fixed text.
• Text to display an editable text box (=edit field).
• Combo for a combo box filled with values downloaded from the server
(see Combo Box Values / Combo-Data-Functions on page 21).
• Check to display a check box.
• Radio to display a radio button
• Form to display a tab of a sub-form within the form (see Using Sub-Forms on
page 26 for details).
• File to display a file upload control.
• IFRAME to display an <iframe> HTML element.
• Button to display a button e.g. to send a message to the wizard engine.
• Single Listbox to display a single-selection list box (with data retrieved from the
server, analogous to Combo).
• Multi Listbox to display a multi-selection list box (with data retrieved from the
server, analogous to Combo).
• DIV Element to display an HTML <div> element (with custom contents)
• Repetetive Form to display a reccurring sub-form (not implemented in Aurea
CRM Web)
• Date to display a date input field (i.e. and editable text box containing either a
valid date or nothing).
• Query to display a query field (which you can e.g. use on star t pages to display
query results).
• Analysis to display a predefined analysis.
Note: You should always define a width & height when using analyses in generic
forms. If you omit either of these values, the default behavior is as follows: If a
width but no height is defined, then the height is automatically set to be equal to
the width. If neither width nor height are defined, a default width is calculated
(100% divided by the number of columns used in the form), and the height is set
equal to the width.
• MenuLink to display a link that executes a menu action.

• Invisible is a special cell type for invisible objects.
• Generic allows placing a Generic Form Controls on page 27 onto the form.
• Rep to display a rep input control.
Form Designer
• SubAnalysis for a special Generic Control displaying an analysis that is dependent

on another analysis.
• AnalysisInput for a special Generic Control that produces input for an Analysis
or SubAnalysis control.
• TabGroup creates a tab control that places the following rows onto different tab
pages (see RowGroup and TabGroup on page 24).
• RowGroup allows the following rows to be grouped together in a cell to create a
sub-table (see RowGroup and TabGroup on page 24).
Form Cell Attributes

Several attributes can be supplied for each cell. Some attributes can have more
than one meaning depending on the type of cell.
• Valuename: The name of the cell. This name is used to reference the cell in
JavaScript code and to define dependencies between cells.
For radio buttons, all buttons belonging to the same group must have the same
Valuename.
• Text: A language-dependent text displayed for the following cell types:
Label, Check, Radio and Button.
For Query cells, this is the text displayed above the query results (e.g. “You have
%1 new appointments”). “%1” is replaced with the number of records.
• Func: Provides information about how to pre-fill the cell. The content of Func
depends on the cell type:
• For Combo boxes and List boxes, Func contains the server function for
downloading the combo box / list box values (see Combo Box Values / Combo-
Data-Functions on page 21).
• For Radio buttons, you can either supply the value if the radio button is checked,
or you can supply two values separated by a semicolon with a checked (first)
and unchecked (second) value. If you omit this attribute, the radio button has
no specific value in its group, but will get the value “true” or “false” depending
on its checked state.
• For Check boxes, you can supply the checked and unchecked value. Default
values are “true” and “false”. You can change the default values by entering
two values separated by a semicolon. If you only supply one value, this is the
checked value and the unchecked value is left blank.
• For IFRAMEs, Func contains the source for the <iframe> contents.
• For Forms, Func contains the name of the sub-form.
• For DIV Elements, Func contains the <div>’s ID-attribute.
• For Buttons, Func contains the event number fired to the Wizard handler when
the button is clicked (if used within a wizard).
• For Query and Analysis, Func contains the name of the query / analysis. See
the Aurea CRM Web Administrator Guide (chapter “Advanced Customisations”,
sections “Filters and Queries” and “Analyses”) for a complete description on
defining a query or analysis used in the Func argument.
• For MenuLink, Func contains the name of the menu action (e.g.
ID_NET_PERSON_SEARCH) that is executed when the user clicks on the link.
• For Generic, this entry is used for parameters for the Generic Form Controls
on page 27.
• For Rep, Func may contain a variable default value for the rep: curRep, cur-
Group, curLeader, curDeputy and curSuperior (Note: in the generic form,
you must not use $ as a prefix for the default value since $ is reserved for
variables of the form).
• Span: Sets the colspan attribute of the corresponding <td> table cell.
• Hook: Allows you to provide a client JavaScript function that is called whenever
the field value is changed. If you use the Hook attribute, enter a valid function
call using the following four arguments:
• “ msg ”: the sent message - for cells the FORM_MSG_CHANGED (3)
• “ addparam ”: an additional parameter; currently 0 is passed for this message
• “ window ”: the window in which the form is displayed
• “ form ”: the form object
• Flags: Used to change the display style. Select BOLD to display text in bold
or UNDERLINE to display text underlined (for labels, check boxes and radio buttons).
If you select NO NOBR , the cell is not placed within <nobr> tags and the browser
wraps the content of this cell.
• TD-Attributes: Attributes applied to the <td> HTML element of the form’s table.
You can use more than one TD attribute.
• Item Attributes: Additional attributes applied to the item in HTML.
• Querystring: Copies the field into a Wizard Form Parameter with this value (see
section Using Forms within Wizards on page 26for details).
• Options: Allows you to define additional options - multiple options are separated
by semicolons. The content of Options depends on the cell type:
• For Combo boxes, you can set the CATCOMBO option to access the “Add Catalog
Value” feature. ENABLEDESELECT creates an empty entry in the combo box
Form Designer
allowing users to deselect the current value. If you want to set an initial value
for a combo box, use selectedIndex=<index> .
• For Check Boxes, the ORDERS (<Ordername>) attribute enables a special sor ting
feature. When the user clicks the check box labels, all check boxes with the
same Ordername are ordered in a specific way.
• If you have an XML path set, you need two XPath expressions separated by
semicolon: the first is the standard XPath and the second is the XPath for the
order attribute in XML (which defines the order of possible channels in the “Act.
Execution” format).
• For Repetitive forms, you can define the minimum and maximum occurrence
using MIN(<number>) and MAX(<number>) . With INIT(<number>) you can define
the count of occurrences initially used. ORDER allows reordering, DELETE allows
deletion, ADD creates an “Add” button and AUTOADD adds a new occurrence
every time an occurrence is filled.
Note: Repetitive forms are not implemented in Aurea CRM web.
• For Query, the mode(<mode number>) parameter defines the compact display
mode:
• 1 (default): Displays a link to the Query Result page, supplying the count of
records (if defined) in the link text.
• 2 : Displays a link to the Query Result page and also a button that opens a
popup window containing the data. You can specify the width and height of
the popup window using width([pixel]) and height([pixel]) e.g.
“ width(700);height(300) ”.
• 3 : Displays only the query results data.
• 4 : Displays the link to the Query Result page and the data itself.
mode(1) mode(2)
mode(3) mode(4)
The autostar t(<0|1) parameter defines whether the query is automatically

star ted when the form tab is displayed (default=1 … queries are automatically
star ted). If the query execution depends on an event occurring after the form
was displayed (e.g. the user selecting a record), you might want to disable
autostar t.
The record option defines that the form’s current record is passed to the query
as the linked record.
• For Analysis, nocontroller suppresses the display of an analysis controller which

contains the category, values and additional criteria (default = controller is visible).
nolist hides list view of the result data of the analysis. nochar t hides the char t
view of the analysis.
The three items of an analysis (controller, results list and char t) are arranged in
separate tabs. If you always want to see the analysis controller, define the con-
trollerfixed option.
The SVG option influences the type of the displayed char t (either SVG or Compo-
nentAr t char t). If you define this option using svg(<Char t Type Name>), the type
of the analysis is fixed (e.g. svg(Bar3D);).
The autostar t option defines whether the analysis shall be star ted immediately:
• autostar t(0): The analysis is not star ted automatically.
• autostar t(1): The analysis is star ted automatically and the list (default) tab is
displayed.
• autostar t(2): The analysis is star ted automatically and the char t tab is displayed.
Form Designer
If not explicitly defined, autostar t is turned off in case a controller is displayed.

If there is no controller displayed, autostar t is turned on by default.
The default view is the list; if you want to use the char t as default, use the option
nolist.
The record option sets the current record of the form as the link record for the
underlying query of the analysis.
• The XML path attribute enables the form to interact with XML. The form can be
initialized with data from an XML file, and data can be written back to an XML
file. This feature is used for editing formats like the “Act. Execution” format.
For cells of type Query, the XML-Path is used to enter the maximum number of
records read.
Combo Box Values / Combo-Data-Functions

You can pre-fill combo boxes with values retrieved from the server. The content of
a combo box is defined by a semicolon-separated expression entered in
the Func column within the form definition: the 1st par t of this expression is the
function, the format of the 2nddepends on the 1st par t.
• Combo-Data-Functions returning Aurea CRM Catalog Values (the text value of
the catalog is displayed and the numeric value is returned):
• CAT: Displays all values of a catalog (with the optional provided value of the
parent catalog if this catalog is a child catalog.
Syntax: CAT;<Info Area>;<Field Id>[;<UCat Value>]
• UCAT: Displays all values of the parent catalog of the provided catalog field.
Syntax: UCAT;<Info Area>;<Field Id>
• LABELS: Displays all values of the “Labels” catalog.
Syntax: LABELS
• Combo-Data-Functions returning Formats:

• FMTPUB: Displays all public formats of the provided type.
Syntax: FMTPUB;<FormatType Id>
• TRANSFORMATFIELDS: Displays all public read engine formats.
Syntax: TRANSFORMATFIELDS
• Combo-Data-Functions returning Data Model Information:

• TABLES: Displays all table names (i.e. infarea names) and returns the infarea
ID.
Syntax: TABLES
• FIELDS: Displays all field names of an infarea and returns the field ID.
Syntax: FIELDS;<InfArea>
• CATFIELDS: Displays all catalog fields of an infarea and returns the field ID.
Syntax: CATFIELDS;<InfArea>
• UCATFIELDS: Displays all catalog fields of an infarea that depend on a parent
catalog, and returns the field ID.
Syntax: UCATFIELDS;<InfArea>
• Combo-Data-Functions returning Web Configuration Parameters (used to display

the values of a Web Configuration parameter that is defined as a combo box):
• WEBCONFIG: Displays the values of the provided Web Configuration parameter.
Syntax: WEBCONFIG;<Parameter Name>
• MMOUTPUTFORMATS: Displays the values of the “MMOutputFormats” Web
Configuration parameter.
Syntax: MMOUTPUTFORMATS
• SEPARATORS: Displays the values of the “Separators” Web Configuration
parameter.
Syntax: SEPARATORS
• Combo-Data-Functions returning XML data:

• XML: Displays the values from the provided XML file.
Syntax: XML;<Xml File>;<XPathExpr>[{;<Parameters>}]
<XML File> is a valid XML file located in the Aurea CRM Web Data\Form sub-
directory (create this directory if it does not exist). The <XPathExpr> is executed
on that document to obtain a list of XML nodes that are displayed in the combo
box. Note that the label attribute of that node is used for the display value and
the value attribute is used for the returned value. If there is no label attribute,
the value attribute is also displayed.
You can supply additional parameters that are replaced in the <XPathExpr> -
“{0}” with the first value, “{1}” with the second and so on. You can use this
feature to define an XML-filled combo box depending on other values of the
form.
• CATXML: Displays the values from an XML file that is based on an Aurea CRM
catalog.
Syntax: CATXML;<Info Area>;<Field Id>;<Xml File>;<XPathExpr>[{;<Parame-
ters>}]
Form Designer
With the CATXML function the XML definition is based on an Aurea CRM catalog.
The value attribute represents the catalog value, and the catalog text is dis-
played if no label attribute is supplied.
• SCATXML: Displays the values from an XML file that is based on an Aurea
CRM catalog which has a parent catalog.
Syntax: SCATXML;<Info Area>;<Field Id>;<UCatValue>;<Xml File>;
<XPathExpr>[{;<Parameters>}]
With the SCATXML function the XML definition is based on an Aurea CRM
catalog that has a parent catalog. The value attribute represents the catalog
value and the catalog text is displayed if no label attribute is supplied.
Dependent Catalogs using Combo Boxes

With generic forms you can define dependent combo box values without a limit in
hierarchies. To define a dependent combo box, set one or more parameters of the
function string to the value name of the field containing the parent catalog (the value
name muse be preceded by a dollar).
Examples:
Value Name Func parameter
1. RootCatalog CAT;KP;38
2. SecondCatalog CAT;KP;161;$RootCatalog
3. ThirdCatalog XML;ms.xml;/RootCatalogs/RootCatalogs[@value={0}]/
Second-
Catalogs/Second/Catalog[@value={1}/XMLCats/XMLCat;
$RootCatalog;$SecondCatalog
Value Name Func parameter
1. Infoarea TABLES
2. CatField UCATFIELDS;$Infoarea
3. UCatValue UCAT;$Infoarea;$CatField
4. CatValue CAT;$Infoarea;$CatField;$UCatValue
RowGroup and TabGroup

The cell types RowGroup and TabGroup allow other cells to be arranged differently
for a better layout but have no function themselves (i.e. they are not involved in the
control flow of the generic form and do not change it).
• A RowGroup cell allows you to display sub-tables in a row of a generic form. A
RowGroup creates a new HTML <table> element inside its cell and groups a
distinct count of rows - the content of the Func parameter - into it. The “Item
Attributes” of a cell are applied to the new <table> element.
Example:
web: Generic Form with two sub- tables using RowGroup cells
designer: Generic Form definition for the top-most three rows of the right-hand
image
• A TabGroup displays a tab control. Each of the following rows is placed in a

separate tab (and these rows typically contain RowGroups defining the whole tab
content).
The count of tabs is defined by the first argument of the Func parameter, the
second argument defines the initially active tab (note: this is a zero-based index)
e.g. Func = 2;1 defines that there are two tabs, and that the second tab is active
by default.
Form Designer
The labels of the tabs may either be set as the label in the TabGroup cell (semi-
colon-separated list), or as individual texts in the RowGroup cells of the rows
belonging to the tab.
If the TabGroup element has a cell hook, it is called every time a tab is changed.
Note: When using a RowGroup inside a TabGroup, those rows that belong to
the RowGroup are not counted for the number of rows that belong to the TabGroup.
Example:
Generic Form definition:

The Parameter RowGroup refers to rows
1. Row with data 4 and 5 (because of FUNC=2) which are
2. TabGroup (Func:2) displayed in the sub-table. Thus, Tab-
Group refers to rows 3 and 6 (because
3. RowGroup (Func:2) of FUNC=2).
4. Row with data The result of the Form definition sketched
5. Row with data corresponds to the images above.
6. Row with data
As RowGroup and TabGroup elements do not change the behavior of the form but
only how the cells are arranged, all cells of all tabs are created when the form is
created (there is no tab loading on demand as e.g. for the details control).
Using Sub-Forms
It is possible to use a tab from a sub-form within another form (a cell of type “Form”
is filled with the whole tab). Create a “Form” cell and enter the name of the desired
sub-form in the Func attribute. If the sub-form has more than one tab, you can select
the tab by providing the tab number (semicolon-separated) e.g. Func=myForm;2 .
The value name of the cells in the sub-form is the value name of the form cell plus
the defined value name of the cell in the sub-form.
The XML path is added with the correct separator between the two XPath expres-
sions, the same applies for the QueryString argument.
In UPDATE_DEFAULT, examples that makes use of sub-forms are “Act. Execution”
(for defining the Activity Execution format) and “Recurring” (for defining the recur-
rence pattern of an appointment).
Using Forms within Wizards

You can display a generic form within a wizard e.g. to ask the user for custom input.
Use the WizardForm
page call from within your wizard and select the form you want to display.
You can place one or more buttons on the form with the event number as Func at-
tribute. If the user clicks the button, the event is sent to the server. The correspond-
ing event parameter is a special array parameter containing key-value pairs for each
cell that has a Value and a QueryString attribute.
If you use this form parameter within your wizard on a page handling form parame-
ters, you get a comma- separated list of keys with the name of the form parameter.
Each key-value pair of the parameter is also added to the query string.
Example: “NewAppointmentPar ticipant” wizard
1. The Wizard-Step WIZARD_ID_CREATEOPPPART_PERSON calls the Wizard-
Form page displaying the form “WizForm: Y1Par tType”.
2. “WizForm: Y1Par tType” contains a Combo box cell with Func attribute CAT;Y2;6 –
this Func attribute fills the combo box with the available par ticipation types from
the corresponding catalog.
Form Designer
3. When the user clicks the “Save” button, event 1 (as defined in the Func attribute
of the button) is fired. An array parameter contains a key-value pair with key F6 (as
defined in the Querystring attribute of the Combo) and the selected value of the
combo box.
4. The next step of the wizard calls the WizardSave-(New) page that creates the
new record. Par t of the QueryString is the F6 parameter from the passed array
parameter - it forces the page to fill field number 6 (Par ticipation Type) with the
value selected by the user.
Generic Form Controls

Generic Form Controls extend the possibilities of displaying content in generic forms.
Generic form controls are complex JavaScript objects that implement a predefined
interface. Out-of-the-box you get a list control, a details control, a tree view control
etc..
• Using Generic Controls
To include a generic form control into a form cell, select cell type Generic, click
on and then select the desired generic form control.
For details on the generic controls delivered by update, see chapter Standard
Generic Form Controls on page 64.
• Using your Own Generic Controls
On the Aurea CRM Designer main page, click the “Generic Controls” button if you
want to register your own generic form controls.
To create a new control, enter the name of your form control, select type
“Generic Control” from the combo box, and click the button. Then click
the button to configure your control (or any existing control that was created
in the current configuration).
See the chapters Generic Controls Interface Functions on page 69 and Sample:
Generic Form Controls on page 71 for fur ther information on implementing your
own generic controls.
Special Forms
The generic forms listed in this chapter have a special behavior or need special
configuration when used.
FormInlineQueryParametersTemplate
This form is used to include parametered queries in another form. The following
customizations are possible:
1. MaxRows (1): Users have a combo box at their disposal to choose the number of
results returned by the query. To adjust this value, enter the name of the
Form Designer
corresponding Web Configuration parameter in the "Func" column. By default,

the parameter valid for all queries (QueryRecordSteps) is used.
2. If you define Style='display: none' (2) for a row, that row is not visible when
the form is initially called. However, the row is displayed once the query is
executed if showTR (or showTD ) is defined in the Options column.
3. showOnMore (3) determines that the hyperlink allowing users to display all result
records is only visible if more results exist than can be displayed (by default the
hyperlink is always visible). showOnMore can be specified in the "Options" column
(optionally in addition to showTR , separated by semicolon).
OrgChart
This form is used to graphically display a user’s position in the organizational hier-
archy of your company (and called in the menu action ID_NET_ORGCHART. This
generic form requires at least two parameters:
• Type=Rep, ValueName= RepKey
• Type=Generic Control | FormOrgTreeControl, Func= $RepKey
The Rep control also suppor ts a variable default value for the rep in the FUNC pa-
rameter: curRep , curGroup , curLeader , curDeputy and curSuperior .
Note: In the generic form, you must not use $ as a prefix for the default value since
$ is reserved for variables of the form
The following settings can be defined in the “Options” columns of FormOrgTreeCon-

trol:
• ClassName(ProviderClass) : Name of an alternate data provide class instead
of RepOrgChartControl to display other hierarchies (see Implementing a Custom
Organisational Hierarchy Char t on page 101).
• DisableParent : Superiors are not displayed.
• CheckParent : If true , the rep’s superior is read and the “+” above the current rep
is displayed only if the superior record exists. If false (default), the “+” is always
displayed until the user clicks on it (then the superior is read and the icon adjusted
accordingly).
• DisableChildren : Subordinates are not displayed.
• DisableCheckChildren : If false , the check whether the rep has subordinates is

disabled and the icon is always initially displayed (the icon disappears when
the user clicks on it but the rep does not have subordinates).
• ExpandUp : If true , the complete hierarchy up to top-level is automatically
determined (attention: no recursion check is currently implemented).
• ExpandLevel(nr) : Defines how many levels of subordinates are visible when the
org char t is initially opened.
• Options{...} : Defines fur ther options (in the same format as ListParams) which
are passed on to the data provider, e.g. Options{ExpandUp;ExpandLevel,1}
• FromTop, nr : Defined that not only node of the direct branch are displayed
(default), but that all branches parallel to the selected rep are also
visible. nr levels are expanded.
Global Scripts
The global scripts section controls which JavaScript source files are included in the
Controller window, and in which order.
Note: The JavaScript code included in the Controller must be correct to ensure
that the application works without errors.
To add additional JavaScript files, enter a name, the filename (with the path relative
to the application) and the order (you should append your files at the end of the
list!). Edit the settings of your script using the button.
Global Scripts
Filename contains the relative path and name of your file. Note that the Display-
Order determines the order in which the JavaScripts files are loaded by the controller.
If you set “not included” for Flags, your script will be loaded on demand (recommend-
ed), while setting “source” will load the script immediately when the user logs in.
The “encoded” flag is deprecated.
You can call functions of global script files in context menus and from direct buttons
(using the JScriptCall
page call), and in hook functions.
Chapter 3: Client-Side Programming Concepts
3
Client-Side Programming Concepts
To provide the rich user interface of Aurea CRM Web, a substantial amount of client-
side code is used.
All client-side code uses Microsoft JScript V5.6 (closely related to ECMA JavaScript
V1.5) which comes with Microsoft Internet Explorer V6.0 or higher.
ActiveX controls are solely used for specific functionalities like single letter creation,
timeline and flowchar t display, and for the integration with Aurea CRM phone.
Architectural Overview
To get a better understanding of Aurea CRM Web’s client-side framework, let’s take
a closer look on its architecture: Aurea CRM Web uses a combination of a frameset
and <iframe> elements to create its overall layout.
Architectural Overview
The frameset contains the following 3 frames:

• Controller: Most JavaScript code making up Aurea CRM Web's client-side
framework will be loaded into this frame. Scripts running in the context of other
frames (e.g. the worker frame) can prefix a method or variable with Controller or
use the function GetController() to gain access to this code.
For example, to write a message to the Info Box you can use:
Controller.InfoBox.PostMessage(“some message”);
or
GetController().InfoBox.PostMessage(“some message”);
• Top Frame: Contains the logos and the Quick Search (if positioned in the top
frame).
• Menu Frame: In addition to the left- and the top menus, the menu frame contains
an <iframe> element hosting the worker frame.
The frameset may also contain an extra frame for the Aurea CRM phone toolbar if
this functionality is enabled.
The Worker Frame acts as a host for all web pages (details, search and list, tree
view, analysis, …) displayed by Aurea CRM Web.
Every web page contains one or more Controls that work together to provide the
page’s functionality.
Controls build the client-side user interface by dynamically creating HTML using
Microsoft Internet Explorer's Document Object Model (DOM). Each control is imple-
mented by a JavaScript class.
Samples of controls used frequently throughout Aurea CRM Web are:
• SearchControl for looking up records.
• DetailsControl for displaying detailed information about a record.
• ListControl for displaying and manipulating lists of records.
• HeaderControl for displaying captions and toolbars.
• WizardControl for guiding users through complex operations.
• ...
A complete list of controls is provided in the Aurea CRM Web Client SDK Reference.
Example: The SearchAndList page contains a SearchControl, at least one ListControl
and several HeaderControls.
In order to provide their services, most controls require data from the server. The
controls request this data by using Aurea CRM Web's communication Channels.
Channels provide a means to transfer data to and from the web server. Every
channel opened on the client has a corresponding endpoint on the Aurea CRM Web
server. This endpoint is called a Server Channel (or the "target" of the channel),
and is implemented as a C# class (see Chapter 4 Server-Side Programming Concepts
for more details on server channels).
Since all transfer operations on a channel are asynchronous, a callback function
can be provided that is called when the requested data has arrived from the web
server.
A typical request will result in the following flow of actions:
The JavaScript code for implementing a request might look as follows:

[javascript]
...
var oChannel = Controller.OpenChannel(window);
oChannel.SetData("MyRequestParameterName1", "RequestValue");
oChannel.SetData("MyRequestParameterName2", "AnotherRequestValue");
oChannel.Submit(MyCallbackFunction, chMyChannel, null);
...
Adding Client Code to the Application
function MyCallbackFunction(elCallerWindow, oChannel)

{
var oResponse = oChannel.GetResponse();
...
}
Summary
This chapter provided a brief overview about the client-side programming concepts,
we will go into more detail in the following sections, where you will learn how:
• to add your own code to the application.
• controls are instantiated.
• you can hook into existing controls to customize their behavior.
• you can read, update and create new records.
• to customize your own wizards.
• to customize your forms.
• to create custom pages within the Aurea CRM Web framework.
Adding Client Code to the Application

There are several different ways to jump into your customized JavaScript code from
Aurea CRM Web:
• Navigating to one of the JScriptCall Pages on page 97 from the application menu,
a context menu, direct button or from a wizard.
• Defining Field Hooks in the Details Control (see chapter “Field Details Function
Attributes” in the Aurea CRM Web Administrator Guide).
• Defining Hook Functions in the Generic Form (see Form Hook Functions on page
50).
• Using the Generic Page (see chapter “Generic Page” in the Aurea CRM Web
Administrator Guide).
You can either add your JavaScript file to the Controller Window (see Controller
Window on page 38 for details) by adding it to the Global Scripts on page 30 in Aurea
CRM Designer, or you can add it directly to the page where it is required (which is
the preferred method of adding JavaScript files) – for example the Wizard page and
the Generic Page allow you to add a JavaScript file directly to the page.
You can also add a completely new ASPX page without any code-behind or server
programming that just uses controls from the Control Builder (e.g. like executing
some predefined queries as on the Star t page – see the example below), and/or a
page that does some work on the client like the Generic Page. To add an ASPX
page, just copy the page to your application directory and register it in the Page
Designer in Aurea CRM Designer, and you can use your page like any standard
page.
Client Code Structure

Although adding a global script is the easiest way to add your custom code to the
project, you should not use it if possible because this slows down the star tup process
of Aurea CRM. Register just one additional global script and use the possibilities
of the Aurea CRM framework to dynamically reload all the others.
Your one and only global script could look like this:
// custom namespace;
Controller.MyCompany = {};
// register a class called MyCompany.Controls, located in the given path, relative
to
// the ClientScript folder
Controller.ClassFactory.RegisterType
("MyCompany.Controls", {Script:"MyCompany/Controls.js"});
Controller.ClassFactory.RegisterType
("MyCompany.Resources", {Script:" MyCompany/Resources.js"});
Whenever you add a reference to a specific script in the designer (e.g. a hook
function), you can now use this namespace structure (e.g. MyCompany.Controls.My-
Control ) and the framework will automatically take care about downloading the re-
source.
If you want to use one of your resources manually within another script, you have
to call LoadType :
// load the resource MyCompany.Controls, inside the function _OnResourceLoaded
// all elements of the given scriptfile will be available
Controller.ClassFactory.LoadType("MyCompany.Controls", _OnResourceLoaded);
Normally it’s a good idea to just use an anonymous function directly in the call of
the LoadType method:
// load the resource MyCompany.Controls, inside the function _OnResourceLoaded
Controller.ClassFactory.LoadType("MyCompany.Controls", function()
{
// the resources are available now.
});
Controls and the Control Builder

If you want to define your own page and place controls on it, there are two possibil-
ities:
1. Put HTML container elements (e.g. <div> elements) on your page, and manually
initialize these containers with controls in the OnLoad function of the page.
The Control Builder can be invoked by calling the Page.Init or Page.OnLoad func-
tions from basics.js .
[javascript]
Page.OnLoad = function()
{
[some JavaScript code]
}
Controls and the Control Builder
or
[HTML]
<head>
<script type="text/javascript">
Page.OnLoad = function()
{
[some JavaScript code]
}
</script>
</head>
2. Let the Control Builder build the controls automatically.

A <div> element which will be filled by the Control Builder has
• a build attribute containing the type of the control you want to build,
• an optional sequence attribute to define the creation order of the controls,
• and, depending on the type of the control, additional options.
<DIV id='divMyForm' build='Form' formName='MyForm'></DIV>
You can build the following commonly usable controls with the Control Builder (or
manually using their JavaScript classes):
• Query Control in compact display mode (class QueryControl ).
• Search Control (class SearchControl ).
• Context Menu Control (class ListMenuControl ).
• Button Control (class ButtonControl ).
• Lists and Sub-Lists ( class ListControl ) to display records in list view; the
Favourites List and Selection List as special record lists (also implemented in
class ListControl ).
• Text Control ( class TextControl ) to display one language-dependent text.
• Header Control ( class HeaderControl ).
• Generic Form Control ( class FormControl ).
Hook for client-side OnLoad Event

It is possible to execute custom code once a page is loaded in Aurea CRM Web.
The ControlBuilder builds the controls on each page and calls a call-back function
afterwards. After its Finished- Callback, the ControlBuilder calls the following func-
tions (if they exist):
• the method OnControlBuilderFinished(oControlBuilder,bSuccess) on the local
page (or from a script that was provided in the “Scripts” parameter of the page
call)
• if no local function exists, a function in the controller is called (if that exists):
OnControlBuilderFinished(oControlBuilder,bSuccess,elWindow)
Example for testing these functions:

• Global Function
Add a script to the “Global Scripts” in designer containing
function OnControlBuilderFinished (oControlBuilder, bSuccess, elWindow)
{ alert ("Control Builder finished"); }
as soon as a page (e.g. Expand Page, Treeview, SearchAndList) is loaded, the
message box is displayed.
• Local Function
Add a script containing
function OnControlBuilderFinished(oControlBuilder,bSuccess)
{ alert("Control Builder finished"); }
e.g. to the “Expanded View Page” (to do so, go to the “Page Designer”, change
the parameter ‘Scripts’ to type Value – Fixed , and then go to the desired page
call and provide the name of your JavaScript file there) after “Invalidate Cache”
you will get a message box on the Expand page.
For another example using OnControlBuilderFinished , see also Conditional Format-

ting for Tree Views on page 108.
Controller Window
The controller window is an invisible frame of the Aurea CRM Web application that
is created after the user has successfully logged in, and remains active until the
user ends the session. The controller window includes all global scripts defined in
Aurea CRM Designer.
From any window of the Aurea CRM Web application, you can access the Controller
Window using either the function getController() or the prefix Controller , e.g.
[javascript]
var sApplyText = Controller.g_sApplyButtonText;
or
var sApplyText = getController().g_sApplyButtonText;
One special JavaScript file which is included in the controller window is the ASPX
page JSConfiguration.aspx , which produces JavaScript code and includes session-
specific information for the controller:
Information about Application, Session and Current User

g_sStarted … the star t date and time of the application.
g_sStyleImagePath … the web path to the images for the style selected by the user.
g_sDateFormat … the user’s display format for date values (e. g. “ %d.%m.%Y ”).
g_sCurrentRep … the name of the representative that is associated with the current
login.
Controller Window
g_sCurrentRepID … the Id of the current representative.

g_sCurrentGroupID … the Id of the current representative’s group.
g_sCurrentDeputyID … the Id of the current representative’s deputy.
g_sCurrentSuperiorID … the Id of the current representative’s superior.
g_sCurrentGroupLeaderID … the Id of the current representative’s group leader.
g_sCurrentPersonRecordId … the record Id of the person associated with the current
representative.
g_sCurrentUserName … login name of the current user.
g_nCurrentTenantNo … the current representative’s tenant number.
g_sCurrentTenantName … the current representative’s tenant name.
g_nStationNumber … the current representative’s station number.
g_nLanguage … the Id of the user’s current language.
g_bIsSuperUser … indicates if the current user is the super user.
g_sApplicationPath … the absolute URL to the application.
Information about Formatting

g_cYes … the language-dependent character for “Yes”.
g_cNo … the language-dependent character for “No”.
g_sTimeSeparator … the separator character between hours and minutes for time
fields.
g_bAMPMFormat … a Boolean parameter defining whether 12-hour or 24-hour mode
is used.
g_sDecimalSeparator … the separator character used for float values.
g_sThousandSeparator … the separator that groups numeric values into groups of
3 digits.
g_sDateSeparator … the separator character between the day, month and year for
date fields.
Information about Web Configuration Values

The user’s current Web Configuration settings are accessible using the g_UserSet-
tings array. The value of a parameter can be accessed using g_UserSettings[Pa-
rameterName] .
If you define your own Web Configuration parameters in Aurea CRM Designer, these
values will automatically be included in this array.
Information about Page Definitions

All pages defined in the Page Designer are available using the g_PageCalls array.
The information can be retrieved using g_PageCalls[PageName] which returns an
array with two elements: the 1st is the file name of the page (relative to the applica-
tion root), and the 2nd contains all fixed parameters and the page Id.
Information about Info Areas

The infoareadefs array contains information about all info areas of the currently
used ver tical version: the info area Ids (i.e. the two- or four-character abbreviation),
the info area index, and the language-dependent info area name in singular and
plural form (please note that singular and plural names will remain the same as long
as they are not defined in the Aurea CRM Designer).
Note: You should not access this array directly but use the utility functions described
in Info Area Functions on page 81.
Information about Images

Images are registered in Aurea CRM Designer with their logical and physical name.
The g_Images array translates the logical name of an image into the physical file
name – the file is located at g_StyleImagePath (relative to the application root).
Each element of the g_Images array is an array with two elements; the file name
and the display name (which is used for tool tips).
Note: You should not access the g_Images array directly but use the Controller
functions, image_getFilename(sImageName) and image_getLabel(sImageName) to
retrieve the filename and display label of an image.
Language Dependent Texts

g_sApplyButtonText … the “Apply” button’s text. g_sCancelButtonText … the
“Cancel” button’s text. g_sBackButtonText … the “Back” button’s text. g_sCloseBut-
tonText … the “Close” button’s text. g_sLoading … the text used for displaying the
loading state.
Details Control
Details Control
The Details Control is displayed on the Expand page and several other pages that
show the details of a record (like the Tree View page or Dashboard page). It is de-
fined by a Field Group’s “Details Control” definition which contains the displayed
tabs and the fields on those tabs.
The easiest way to manipulate data within the Details Control is to use a Hook
Function. Simply set a hook function in Aurea CRM Designer (in the Field Details)
on any field you want to observe (see also see chapter “Field Details Function At-
tributes” in the Aurea CRM Administrator Guide). The JavaScript code must be
added to a Global Scripts on page 30, and only the function name needs to be en-
tered in the Hook Function field in designer.
The following hook example shows how to access the Details Control and alter its
content:
[JavaScript]
// This hook is set on the “Company” field (field number 2)
// Whenever the company name is changed, the first 8 letters of the field’s value
// are copied to the “Synonym” field (field number 3)
function SetSynonymHook(elSource)
{
// get the details control object
var oDetails = DetailsControl_Get(elSource);
// get previous contents of the field
var oValue = oDetails.GetValue(elSource);
var sOldValue = oValue.FieldData.fieldvalue;
// get the new contents of the field
var sNewValue = elSource.value;
// if the field value has changed, copy the first 8 characters
// to the “Synonym” field (field number 3)
if(sOldValue !== sNewValue)
{
var oFieldValues = { 3: { Value: sNewValue.substr(0, 8) }};
oDetails.SetValues(“FI”, oFieldValues);
}
}
The following example shows how to access the text values of catalogs. We will
combine a number of values to create a subject for an appointment.
[JavaScript]
// This hook is set on the “Contact” and “Status” fields of MA (numbers 0 & 1 in
BTB).
// Whenever the value of these fields changes, the text values of the two fields
// are copied to the “Subject” field (number 103 in BTB), separated by ‘-’.
function SetSubjectHook(elSource)
{
// get the details control object
var oDetails = DetailsControl_Get(elSource);
// check if we have an appointment in the detail control object
if("MA" == oDetails.GetInfoArea())
{
// create an object for retrieving the catalog texts
var oCatalogsCtrl = new CatalogsControl(window);
// retrieve the type of the appointment (field number 0)
var oTypeVal = oDetails.GetValue("MA", 0);
var sType = oCatalogsCtrl.NumericToValue(oTypeVal.FieldData.fieldinfo,
oTypeVal.Value);
// retrieve the status of the appoinmtment (field number 1)
var oStatusVal = oDetails.GetValue("MA",1);
var sStatus = oCatalogsCtrl.NumericToValue(oStatusVal.FieldData.fieldinfo,
oStatusVal.Value);
// set field “Subject” (feld number 103) to 'Type - Status'
var oFieldValues = { 103: { Value: sType + " - " + sStatus }};
update software AG | Operngasse 17 - 21 | A-1040 Wien | Austria Page 26

Tel.:+43.1.878 55-0 | Fax:+43.1.878 55-200 | info.at@update.com |
www.update.com 26.03.2012
oDetails.SetValues("MA", oFieldValues);
}
}
To create your own details control, you need to define a Field Group in designer
and a <div> element in an HTML/ASPX file that contains the new control:
[html]
<div ID="myDetailsContainerDiv"></div>
[JavaScript]
var oDetails = DetailsControl_Display(elCallerWindow, 'FI', sRecID,
'myDetailsContainerDiv',
'Update', null, false, 'MyFieldGroup', null);
Expand Control
The Expand Control is used to display a record. It can be configured in Aurea CRM
designer for each info area in the “Expand-Configurations” section and consists of
a details control to display the actual record, a header control, a table caption, a
context menu, a default action, an attribute list, parent relations, a breadcrumb path
and alternative expand configurations. For more details on the elements of an Expand
Configuration, please see the Aurea CRM Web Administrator Guide.
An Expand Control can be created on a custom ASPX page using JavaScript:
[JavaScript]
// Create the Expand Control
var oExpandCtrl = new Controller.ExpandControl(elCallerWindow);
// Set the Expand Configuration you want to use
// - in this case “KP” (standard Expand Configuration for persons)
oExpand.SetExpandName(“KP”);
// Set the record you want to display
oExpand.SetRecord(sInfoArea, sRecordId);
// Create the Expand Control to show the record
oExpand.Create(“ExpandDiv”, “Show”);
[html]
<div ID="ExpandDiv"></div>
Controls for Accessing Server Data
You can find the full list of the methods available for the Expand Control object in
the Aurea CRM Web Client SDK Reference.

Using the Record Control on page 43, the RecordSet Control on page 47 or the Query
Control on page 44, you have direct access to data from the Aurea CRM database
from your client-side JavaScript code:
• An instance of the Record Control on page 43 represents one record in the
database. Use this class to create new records, read and update data from a
specific record, or delete a record.
• With the Query Control on page 44 you can load and execute predefined queries
(as well as queries created on the fly), and you can use one of the display modes
of the Query Control to present the results to the user.
• For operations that may result in more than one record, use the RecordSet Control
on page 47 (which is based on the Query Control).
All controls use server channels to execute the requested operations - thus, the
operations are executed asynchronously:
This following chapters provided you with a description of how to use these controls.
For a full description of the control’s classes and methods, see the Aurea CRM Web
Client SDK Reference.
Record Control
The Record Control can be used for creating, reading, modifying or deleting a single
record.
Create a New Record

[JavaScript]
var oNotify = { RecordControl_OnNotify : myOnNotifyFunction };
var oRecord = new Controller.RecordControl(window, sInfoArea);
oRecord.SetFields(aFieldIndexArray, aFieldValueArray);
oRecord.SetLinkInfo(LinkInfo); // optional
oRecord.SetNotifyObject(oNotify);
oRecord.New();
In the notification function, you can get the record id of the newly created record
by calling the method GetRecordId() .
Load Data from an Existing Record

[JavaScript]
oRecord.SetRecordId(nRecordId);
oRecord.SetFieldIndices(aFieldIndexArray);
oRecord.Load();
In the notification function, you can get the values of the requested field indices by
calling the method
GetFieldValues() .
As a special feature, the Record Control allows you to load records that are linked
to the current record with a vir tual parent relation – if you set this relation name by
calling method SetRelationName , you get the values of the parent record. In this
case, after loading the parent record, the record id and the info area of the Record
Control will change to that of the parent record. You can get the info area and record
id using the methods GetInfoArea() and GetRecordId() .
Update an Existing Record

[JavaScript]
oRecord.SetFields(aFieldIndexArray, aFieldValueArray);
oRecord.Save();
Delete an Existing Record

[JavaScript]
oRecord.Delete();
After a successful deletion of a record, the record id is set to -1 (since the record
no longer exists). If you need to know the record id of the deleted record, use the
method GetDeletedRecordId() .
Query Control
The Query Control allows you to load and execute predefined queries as well as
define custom queries to save, execute, or display the query definition or the query
result on the screen. You would also use the Query Control to read e.g. all child
records of a given parent record.
The Query Control can either be created manually in JavaScript code or by the
Control Builder.
Creating a Query Control from JavaScript Code

To create a Query Control in your JavaScript code, call the constructor of the
QueryControl:
[javascript]
var QueryObject = new Controller.QueryControl(sControlName, sDisplayMode, window);
The QueryControl constructor accepts the following parameters:

sControlName
The name of the control (e.g. the name of an existing <div> element in the current
window) if a display mode is used. The parameter can be null if no display mode
is used.
sDisplayMode
The display mode – “ Compact ” for the compact display mode showing a text and the
count of records only, or “” for the design mode. This parameter is ignored if the
Query Control is not displayed.
window
The current window.
Creating a Query Control via the Control Builder

The Query Control may also be directly created by the Control Builder. Place a DIV
element with the following arguments onto the page:
<DIV id='QueryDivId' build='Query' queryname='QueryName' maxresults='10'
text='%1 results'>
The given text is displayed, the predefined query is loaded and executed and when
the count of records are returned the text is redisplayed replacing “%1” with the
rowcount (“>maxresults” if more rows exist). Instead of hard coding the text, you
may use the textinfo attribute instead of the text attribute to select a language
dependent text from Aurea CRM Designer.
<DIV id='QueryDivId' build='Query' queryname='QueryName' maxresults='10'
textinfo='[textgroupname].[textid]'>
Loading an Existing Query

To load an existing query, set its name and load it:
[javascript]
var Query = new Controller.QueryControl("", "", window);
var sQueryName = "…";
var bPrivate = true; // true for private queries, false otherwise
Query.SetQueryName(sQueryName, bPrivate);
Query.LoadQueryDefinition(QueryDefinitionLoaded);
function QueryDefinitionLoaded()
{
[…]
}
Executing an Existing Query

To execute a loaded or defined query, you may either use the RecordSet object or
call the method Post2Channel on the Query object.
Post2Channel requires the following arguments:
sMode
The action performed with the query definition.
“Show” causes the query to be executed (as do “Expor t” or
“XslExpor t”, these produce slightly different output). “Save”
saves the Query definition under the current name and privacy
setting – replacing any existing query with the same name.
nMaxRes The maximum number of rows returned by the query.
sQueryName The name of the query (only required with sMode = “Save”).
bPrivate The privacy setting of the query. “True” saves the query as
private, “False” saves the query as public (only required with
sMode = “Save”).
fCallbackFunc- The callback function that is called when the request is
tion completed.
oCallbackObject An optional callback object used by fCallbackFunction if it is
set.
oExport An expor t object (only required with sMode = “Expor t” or
“XslExpor t”).
nSkipRecords The number of initial records which are not returned.
The following example shows you how to execute a query:

[javascript]
Query.Post2Channel("Show", 21, "", false, QueryExecuted, null, null);
function QueryExecuted(oCallerWindow, oChannel)
{
var aErrorMessages = oChannel.GetErrors();
if (aErrorMessages)
{
// Error handling
}
else
{
var oResult = oChannel.GetResponse();
}
}
In this example you find the result values in the oResult variable, which has the
following members:
Rows An array of result rows. A result row is an array with two elements
– the first element is an array of record Ids (one for each par ticipating
InfoArea) and the second element is the array of result values of

that row.
InfoAreas An array of InfoAreas that each result row contains.
FieldIndices For each InfoArea of the InfoAreas array, you get the array of field
indices in the query. FieldIndices[0] is the array of field indices for
the first InfoArea, FieldIndices[1] for the second, and so on.
Creating or Modifying a Query

You can use the following methods to create a new query definition “on the fly” or
to modify an existing definition (please refer to the Aurea CRM Web Client Reference
Help for full details):
• AddInfoArea … add info areas to your query.
• CreateFilter … create a new filter node without inser ting it into the tree.
• AddFilter … add an existing filter node (created using CreateFilter ) to the given
info area. The filter is AND-related to the current filter.
• InsertFilter … inser t an existing filter node into the query - replaces the current
filter.
• SetLinkedRecord … set a linked record that is applied to the first info area.
Example for creating and executing a query that reads the fields “First Name” (2)
and “Last Name” (3) for all persons with “Priority” (16) =“A” linked to a given com-
pany:
[javascript]
var query = new QueryControl ("", "", window)
var querynode = query.AddInfoArea("KP",[2,3]);
var filter = query.CreateFilter("KP",16, "L", "=", "A");
query.InsertFilter(querynode, "", filter, false);
query.SetLinkRecord("FI", parentRecordId, 0);
query.Post2Channel("", -1, "", false, OnExecuted);
function OnExecuted(sender, args)
{
var controller = GetController();
var results = args.GetResponse().Rows;
if(results.length == 0) // no results
return;
for(var index in results) // loop through all results
{
// process the query results
// results[index][0][0] contains the result’s record Id
// results[index][1][0] contains result for field “First Name” (2)
// results[index][1][1] contains result for field “Last Name” (3)
}
}
RecordSet Control
The RecordSet Control allows you to load and access sets of records. You can either
read data from a set of records defined by their Id, or you can execute a predefined
or custom query using the query control.
Reading Data for multiple Records:

[javascript]
var oNotify = { RecordSet_OnNotify : myOnNotifyFunction };
var oRecordSet = new Controller.RecordSet(window);
var aRecordIds = new Array(4, 17, 43, 98);
var aFieldIndices = new Array(1, 2, 3, 4);
oRecordSet.SetNotifyObject(oNotify);
oRecordSet.Read(sInfoArea, aRecordIds, aFieldIndices);
Reading Data from a predefined Query:

[javascript]
var oNotify = { RecordSet_OnNotify : myOnNotifyFunction };
var oRecordSet = new Controller.RecordSet(window);
var sQueryName = "QueryName";
var nMaxResults = 21;
var bQueryPrivate = true;
oRecordSet.SetNotifyObject(oNotify);
oRecordSet.ExecuteQuery(sQueryName, nMaxResults, bQueryPrivate);
If you want to read data from an already loaded query or custom created query,
pass the query control object instead of the query name to the ExecuteQuery method.
To retrieve the number of rows returned, call the method GetRowCount; to retrieve
the data itself, create an enumerator object by calling the method CreateEnumerator.
[javascript]
var oEnumerator = oRecordSet.CreateEnumerator();
The following methods may be called for the Enumerator Object to retrieve the
data (refer to the
Aurea CRM Web Client Reference Help, RecordSet.CreateEnumerator method for
full details):
• MoveNext to move from the current row to the next row. The current row is initially
invalid, so you have to call MoveNext once to make the first row the current row.
• MoveTo to set the current row to a specific row.
• GetRecord returns a RecordControl object for the current row.
• GetRecordId returns the record Id for the current row.
• GetValues returns an array with all values of the current row.
If you want to update a field value in a set of records, use the RecordSet controls Up-
dateField method. To delete records by their Ids, use the Delete method.
RecordTree control
The RecordTree control is based on the TreeControl to display a record with its
children in a tree view. The RecordTree control is used on the treeview page and
for the Generic Tree Control within Forms.
Form Control
Form Control
The Form Control allows you to display custom forms that are defined in the
Generic Form Designer of the Aurea CRM Designer.
Usages of the Form Control:
1. Defining Formats (e. g. the Activity Execution format) on the EditFormat page.
[javascript]
var oForm = Controller.FormControl (window, DIVName, FormName);
2. Asking the user for input to trigger custom actions within wizards.
[javascript]
oForm.SetDimensions (500,300);
3. Use the form to display information in a custom layout.

[javascript]
oForm.Create();
To use generic forms, you can either use a standard page (like the WizardForm
page or the ShowForm page), or you may create your own instance of the form
control in your JavaScript code.
Creating a Form
Create a form with the following steps:
1. Create a new Form Control by passing the window, the name of the containing
DIV element within the window and the name of the Form to the constructor:
[javascript]
var oForm = Controller.FormControl (window, DIVName, FormName);
2. Set additional options like the width and the height:

[javascript]
oForm.SetDimensions (500,300);
3. Call the Create method to display the form within the containing DIV element:
[javascript]
oForm.Create();
Calling a Generic Form from a Menu

To call a Generic Form from the application- or context menu, open the menu in the
designer and add a new action.
After pressing the Save button, open the definition of the new action to specify the
Page Call ShowForm.
ShowForm accepts the following page parameters:

• Name of the Form: inser t the name of your generic form
• Record: allows you to specify a parent record if applicable
• Additional JScript-Files: add your JavaScript file (with relative path & name e.g.
myScripts\myForm.js).
• Option String for Jscript evaluation: ignore this parameter
• Header-Name: enter the name of the header you specified before in the Special
Header section.
• Header-Type: enter Special for a header in the Special Header group.
• Additional Textgroups: add textgroups you additionally need.
• Initial Tab Number: The selected tab when the form will be shown
Form Hook Functions

You may influence the behavior of the form by setting hook functions:
[javascript]
function formhook (message, messageParameter, elWindow, form)
{
[…]
}
form.SetHookFunction ("formhook (msg,param,window,form);"); //deprecated
OR
form.SetHookFunction (Function.CreateDelegate(this, "MethodToBeCalled"),{});
Form Control
The first parameter in this case is a function pointer for the hook function. The
second parameter is optional object on which the hook function will be called. If this
parameters is set the first parameter must be a function pointer rather than a string.
The hook function can be set in Jscript or in the form definition in the Aurea CRM
designer and is called when the form is initialized and every time a tab on the form
is displayed or destroyed – you can determine the reason for the hook call by the
message. See the Aurea CRM Web Client Reference Help FormControl.SetHook-
Function method for full details on the hook function.
You may also define a cell hook function for any cell on the form in the Aurea CRM
Designer to immediately react to changes of values on the form.
Accessing Form Cells on page 55 provides you with some information on how to
access cell specific information. For cell hooks the CellDefinition and CellNamespace
form proper ties will allow you to access the current cell:
[javascript]
form.CellDefinition; // static cell definition
form.CellNamespace; // namespace of the cell
A special button call-back function may be set with the SetButtonCallback method
to be called when a button on the form is clicked (this mechanism is used within
wizards to fire events on button clicks).
Static Form Definition

The static form definition structure reflects the definition of a form in the Aurea CRM
Designer.
You can create a form by calling the constructor with the name of the form definition,
but you can also construct a form definition on demand with the information below
and pass it (instead of the form definition name) to display a custom form without
using a definition from the form designer.
If you create a form with its form definition name, you can obtain the static form
definition after a Create method call (please note that as you get this definition by
reference, changes to this structure results in unpredicted behavior).
//[javascript]
form.Create();
StaticDefinition = form.GetStaticDefinition();
The static field definition is an array with the following entries:
Index Field Constant Meaning
0 FORMDEF_ID The corresponding form ID in the Aurea CRM Designer

database (unused).
1 FORMDEF_NAME The name of the form definition.
2 FORMDEF_TAB- The count of tabs in the form.

COUNT
3 FORMDEF_TYPE The form type (0 = Tabbed, 1 = Steps, 9 = Plain).

Steps for wizard- like behavior are not implemented
at the moment.
4 FORMDEF_TABS Array of tab definitions.
5 FORMDEF_SUB- Array of sub-forms that are referenced in the form.

FORMS
6 FORMDEF_HOOK The hook function for the form.
7 FORMDEF_WIDTH The explicit width of the form.
8 FORMDEF_HEIGHT The explicit height of the form.
9 FORMDEF_AT- Form attributes.

TRIBUTES
For each tab, the tab definition consists of the following entries:
0 FORMTAB_ID The ID of the tab.
1 FORMTAB_LABEL The tab text.
2 FORMTAB_ROW- The count of rows on the tab.

COUNT
3 FORMTAB_COL- The count of columns on the tab.

COUNT
4 FORMTAB_ROWS Array of row definitions.
5 FORMTAB_AT- Tab attributes – this HTML code will be appended to

TRIBUTES the TABLE element.
For each row within a tab, the row definition consists of the following entries:
Form Control
0 FORMROW_ID The ID of the row.
1 FORMROW_ATTR Row attributes – this HTML code will be appended to

the TR element of the row.
2 FORMROW_CELLS Array of cells of the row.
For each cell within a row, the cell definition consists of the following entries:
0 FORMCELL_ID The ID of the cell.
1 FORMCELL_LABEL The label text if applicable

for the type.
2 FORMCELL_FUNC The function argument (see

designer documentation for
details).
3 FORMCELL_VALUENAME The value name.
4 FORMCELL_TYPE 0 for label

1 for textbox
2 for combo box
3 for check box
4 for radio button
5 for sub-form
6 for file
7 for IFRAME
8 for button
9 for list box with single
selection
10 for list box with multiple
selection
11 for DIV element
12 for repetitive form (not
implemented)
13 for date field
14 for query field
15 for analysis field
16 for menu link
17 for an invisible cell
18 for Generic control
19 for a Rep field
20 for sub analysis
21 for analysis input
5 FORMCELL_COLSPAN The colspan attribute of the

field.
6 FORMCELL_HOOK The cell hook function.
Form Control
8 FORMCELL_ATTRIBUTES The attributes of the cell –

this html code will be ap-
pended to the TD element
of the cell.
9 FORMCELL_QUERYS- The query string name.

TRING
10 FORMCELL_ITEMATTR The item attributes will be

appended as html code to
the DOM element that is
the item itself
11 FORMCELL_OPTIONS The options.
12 FORMCELL_XPATH The XPath definition.
13 FORMCELL_CONTROL- The name of the generic

NAME control (for cell types
generic, analysis input and
sub analysis).
If a cell references a sub-form, the form definitions of these sub-forms are stored
in the sub-forms array of the form definition – each array entry defines one sub-form
with the following array entries:
0 FORMSUB_ID The ID of the sub form.
1 FORMSUB_NAME The name of the sub form.
2 FORMSUB_TABS The tab definitions of the sub form.
3 FORMSUB_HOOK The hook function of the sub form.
Accessing Form Cells

Each cell can be defined by one of the following unique indexes:
1. The Cell Namespace.
2. The Cell ID – an array of integers in the form [tabid][rowid][cellid].
3. The Cell QueryString name as defined in the Aurea CRM Designer.

4. The Cell Value name as defined in the Aurea CRM Designer.
To access cell data, you need the Cell ID so if you hold any other type of identifica-
tion, use one of the conversion routines to obtain the ID:
[javascript]
id = form.GetIdOfItemName (Namespace);
id = form.GetIdOfValueName (ValueName);
id = form.GetIdOfSubFormValueName (ValueName, SubFormID);
Each cell in the form has a static definition (this is the configured information that
comes from Aurea CRM Designer) and the dynamic information containing runtime
information like the current value.
To get the static cell definition of a cell from the mask definition, apply the ID en-
tries for tab, row and cell (please note that the constants are defined in the controller
and therefore must be prefixed with “Controller.” to work within the worker frame):
[javascript]
var staticFormDef = oForm.GetStaticDefinition();
var staticTabDef = oStaticFormDef[FORMDEF_TABS][id[0]];
var staticRowDef = oStaticTabDef[FORMDEF_ROWS][id[1]];
var staticCellDef = oStaticRowDef[FORMDEF_CELLS][id[2]];
If the cell is of type sub-form, you can load the sub-form and find the static definition
within the form:
[javascript]
var staticSubFormTab = oForm.GetSubFormTab(StaticCellDef[FORMCELL_FUNC]);
var staticSubFormRow = oStaticSubFormTab[FORMDEF_ROWS][id[3]];
var staticSubFormCell = oStaticSubFormTab[FORMDEF_CELLS][id[4]];
The dynamic cell information can be obtained by calling the method GetAddInfo :
[javascript]
var dynamicCellDef = oForm.GetAddInfo(id);
The dynamic cell contains the following proper ties:
Property name Content
valuename The value name.
querystringname The querystring name (same logic for repetitive fields as for
valuename).
definition The static cell definition (array structure as described above).
tab The dynamic information for the whole tab.
rowindex The row index of the cell within the tab.
cellindex The cell index of the cell within the row.
optionstring The option string from the static definition
Form Control
Property name Content
optionarray Array of options from the option string
xpathstring The XPath string from the static definition
xpath The splitted XPath – xpath[0] points to the value, for special
behaviors like ordered items, a second path may be supplied
on xpath[1]
xpath.full The full XPath path, including prefix paths from parent forms
truevalue Value if checked (check button)
falsevalue Value if unchecked (check button)
radiovalue The value if the radio button is checked
value The current value of the cell.
The value proper ty of the dynamic field info is not guaranteed to contain the currently
displayed value because, for performance reasons, the dynamic cell information is
updated on tab changes or when necessary.
To transfer the current value of all fields to the dynamic cell information, call the
method
GetCurrentTabValuesFromMask or UpdateFormValues
[javascript]
form.GetCurrentTabValuesFromMask();
or
form.UpdateFormValues();
You may change the value proper ty in the dynamic cell information and call
method Redraw to reflect the changes on the screen:
[javascript]
form.Redraw();
Customizing the Start Page

Any page can be used as a star t page within Aurea CRM and the user is allowed to
select which page is displayed on login or when the Star t page icon is clicked (see
the User Configuration).
The framework contains a star t page that can be customized to display information
which is of use to the user. The page “Star t Page” takes a form name as its input,
the user can create a form containing user defined queries to display relevant data
on login.
The default implementation of the Star t Page uses the form Startpage_General which
displays data from the queries, ThisWeeksAppointments, ThisWeeksTasks and Up-
comingToDos.
If you want to change the behavior of the star t page, you can modify the Star t-
page_General form in your configuration. You can also create a new form and a
menu entry which calls the star t page with this form as an argument, this menu entry
can then be added to the possible star t page in the Customize section.
To place a query which displays a list of the people with a bir thday today onto your
customized star t form, you should follow these steps:
1. Define a query “TodaysBir thdays” which displays the fields First Name, Surname,
DOB from the Person infoarea when DOB is equal to “$curDay” (although it is
allowed to have this query stored as Aurea CRM format for consistency, it is
recommended that you store queries that are referenced from the designer
configuration in the designer database). See the section “Queries and Filters” in
the Aurea CRM Administrator document for full details on creating queries.
2. Copy the Star tpage_General form to your configuration and place a Query Cell
on the form. Put “TodaysBir thdays” in the FUNC parameter and “record;mode(4)”
in the Options parameter of that cell.
3. Add a display name to the query cell. This text will be displayed but an occurrence
of “%1” will be ignored within the string. After the query was executed and the
count of records returned is known the count of records will replace the “%1
placeholder.
4. In the additional info 2nd parameter (it has the name “XML-PATH” in the Aurea
CRM Designer application) you may enter a max records number. If this is the
case only maxrecords + 1 records are read from the server and an eventual “%1”
placeholder is replaced by “>maxrecords” if there are more records.
If the user clicks on the linked display texts, the application will navigate to the
standard query result page for that specific query. Although it is recommended
to only place queries on the star t page that can be executed quickly, it is also
implemented that only one query at a time is executed and that the user may
leave the star t page anytime by clicking a link or using the application menu
without having to wait for the remaining query executions to be completed.
Tip: If you want your users to be able to edit the list data, you can place a Generic
List Control on page 66 (instead of a Query Control) onto the star t page. When using
a Generic List control, users can edit the data from the info area of that list directly
in the generic form.
Form Control
Record Parameters in Forms

With the introduction of Query cells, Analysis cells, and Standard Generic Form
Controls like the Details Control, the Treeview Control and the List Control, cells
within a form may not only have “normal” string value dependencies (like parent
and child catalogs), but also record parameters may be either consumed as one
input parameter of the FUNC argument and may also be produced as current value
of a control.
A record parameter is a string parameter with format <Infoarea>.<RecId> , e. g. the
person with record ID 27 is identified by record parameter “KP.27” or
“KP.x000000000000001b” (it is recommended to use the long RecordId Syntax).
Record parameters can also be used in the standard cell types Query and Analysis:
• The FUNC argument of the query has the format
<QueryName>;<QueryType>;<LinkRecord> where parameters at the end may be
omitted – the third parameter may be used to set a link record.
• The FUNC argument of the analysis has the same format as for queries (with the
analysis name as first argument, and the type being ignored – “all” is assumed).
Standard generic controls listed above will use record parameters in the following
manner:
• The Form Details Control expects a record as first input parameter in the FUNC
argument.
• The Form List Control accepts a link record as first input parameter in the FUNC
argument, the second parameter represents the InfoArea of the list and the value
of the list is the record parameter of the currently selected line.
• The Form Treeview Control expects the root record as first input parameter in
the FUNC argument and the value of the control is the record parameter of the
currently selected record within the tree.
Using Query Result Lists as Record Input

While most form cells return either a simple value (like text box or a combo box) or
a record (like a generic list), a line of a query result consists of more than one record
– so the query control has no chance to return one current record that might be
consumed as input from other form cells.
Instead the query cell returns a special indexed current record output – with the info
area as index. If you define a Query Cell with name “MyQuery”, you may access the
current record of info area xx from another cell with FUNC argument “$MyQuery[x]”
Passing Page Parameters to a Generic Form

You can pass parameters to a generic form via the page call. This enables you to
e.g. create a general form accepting different parameters that you can use in several
places.
Before Create you can pass a parameter array to a generic form using the
method SetParameters .
• If the “FUNC” column contains $Parameter[<Parameter Name>] and the parameter
array contains a proper ty named <Parameter Name> , then the respective “FUNC”
par t is replaced by the value of the proper ty.
• You can also use $Parameter[<Parameter Name>] in the “Options” column. You
can provide a default value for the option using $Parameter[<Parameter
Name>]:<Default Value> . Note: If no default value exists and the parameter value
is undefined, the option is ignored.
• By default, the ShowForm.aspx page passes the page parameters to a generic
form as Parameter , thus you can access these page parameters in “Options” and
“FUNC” using $Parameter.
How to make a generic form parameterizable?
1. Define a generic form and use $Parameter[...] in “FUNC” / “Options” for the
parameterizable par ts.
2. In the Page designer, create a page analogous to “ShowForm” which additionally
offers the parameters used in your generic form. Note: Parameters used in “FUNC”
should be mandatory.
Displaying a Generic Form in a Sub-List
Form Control
Star ting with service pack 4, you can include not only a list of child records in a tab
of a sub-list but “any information” using a Generic Form e.g. an analysis of the
current record or a map depicting the address. The history of a record is displayed
using this functionality, too.
You include a Generic Form in a sub-list using the ExpandChildren and/or Search-
SubList header by entering the name of a Generic Form in the new Form columns
in the desired row.
You can pass parameters to the form using SubListParams (this data is evaluated
using “eval” and set using SetParameters ).
Example: Integration of Google Maps in Sub-Lists
A Google map can be displayed for companies, persons, additional addresses,

proper ties, and any info area that has a company or person as parent.
To find an address on the map, the fields “Street”, “Zip”, “City” and “Country” must
contain correct values.
If a Google map is integrated for a child info area that does not contain the above-
mentioned fields, the address of the of the parent company or person is used.
You can integrate a Google map using a Generic Control of type GoogleMaps in a
Generic Form. The current record is passed in the FUNC cell using $Record; .
You can then integrate this Generic Form in the ExpandChildren and/or SearchSublist
header in the Form columns. The info area (or its direct parent info area) must
contain fields with the XML names "Street", "ZipCode", "City", and "Country".
Fur thermore you need to enter a valid registration key for your Aurea CRM Web
URL (see http://code.google.com/apis/maps/signup.html) in the Web Configuration
parameter GoogleMapsKey .
Generic Controls in Forms

Beside the standard form controls like combo boxes, labels or text field’s additional
controls may be implemented and integrated in Generic Forms. Generic Control all
implement a predefined interface and have enriched functionality compared to
standard form controls.
The following types of generic controls are currently suppor ted:

• Generic Control: A generic control that acts like other form cells but has no
special behaviors that exceed the standard mechanisms of data interchange
between form cells
• Sub Analysis: A Sub analysis control shows data of another Analysis Control
with different category, value columns, char t types or additional filters
• AnalysisInput: A control that creates an additional filter for a SubAnalysis control.
For all types of Generic Controls you may either use standard generic controls that
are shipped with Aurea CRM Web, use this implementations to add your own features,
or implement your own generic controls.
The following standard generic controls are shipped with Aurea CRM Web:
• Generic Details Control encapsulates the Details control to display a record.
• Generic List Control encapsulates the List control to display a list of records.
• Generic Tree Control encapsulates the RecordTree control to display a record
with its children in a tree.
• A Multiplex Control to switch a display section between details and list depending
on the input.
• Generic Search and List Control encapsulates the Search and List control to
find and display a list of records.
• Chart allows to include generic char ts into a form.
• FormHeaderControl encapsulates the Header Control.
• FormGetParentRecord returns a specific parent record of the input record as
output.
• FormAnalyticsModelControl,
FormAnalyticsSessionControl
FormAnalyticsDimensionControl
and
are using within the analytics add on.
Aurea CRM Web has implemented a Standard Sub-Analysis Control that allows
to display a sub analysis with different category, values, char t types or additional
filters.
A sample implementation of an Analysis Input Control is the AnalysisCatego-
ryCombo that displays a combo box with specific form data like categories or catalog
values and if the user selects a value, an additional filter is applied to Sub Analyses.
To implement and integrate your own Generic Control within a generic form, you
must:
1. Implement a JavaScript Control that meets the required interface for generic form
controls.
2. Add this control to your web application by adding a global script in Aurea CRM
Designer.
3. Add this control to the generic control of the appropriate type within Aurea CRM
Designer.
4. Add your control to a cell by selecting type “Generic”, “SubAnalysis” or
“AnalysisInput” and then selecting your custom generic control.
The following sections describe the features of the standard generic control as well
as the interfaces that must be implemented for own generic controls. The source
code of the standard generic controls may be found in file ctlFormAddOn.js that is
available in clear text.
Standard Generic Form Controls

Generic Details Control
The Generic Details Control displays a record in a details control and is controlled
by the semicolon- separated par ts of the FUNC argument of the cell:
1. The first argument par t is the identification of the record to be displayed, either
in the standard record argument format (“<infoarea>.<recid>”) or a special format
for creation of new records linked to another record
(“<infoarea>.new.<linkinfoarea>.<linkrecid>” or “new;<infoarea>;$Record”).
2. The second argument par t controls whether the details control has a header or
not – the Generic Details Control has no header by default; set this value to “true”
if the details control shall have a header. It is also possible to explicitly specify
the name of a header (instead of using the default).
3. The third argument par t controls whether the details control is in edit or in view
(read-only) mode, set this parameter to true if you want the details control to be
read-only.
4. The four th argument par t controls the field group of the details control – if omitted
the default field group is used. You may use “%%” as placeholder for the info
area to specify the field group (if you specify “%%form” as field group name for
a record with info area “KP”, field group “KPform” will be applied, and if this field
group does not exist, the default field group is used.
If the details controls is in new mode (see first argument par t) and a new record is
saved the control calls method OnNewRecord (if available) to notify its parent. The
Generic Details Control also has an output value: the record itself (useful e.g. if
reps use the paging control and thus change this value).
Fur thermore it is possible to enter the following parameters, separated by semicolon,
in the “Options” column:
• ShowExtras: Displays parent and related data (sub-lists) below the details mask
(default=off).
• ShowPaging: Displays the paging control (this option can only be used in
conjunction with the default header).
• HideBreadCrumb: The breadcrumb trail is not displayed.

• AutoSwitchToShowMode: Only relevant when saving a new record; replaces the
“new parameters” described in argument 1. for FUNC (listed above) with the newly
created record and thus switches the details control from “new” into “edit/view”
mode.
Generic Tree Control

The Generic Tree Control displays a tree as known from the tree view page with
the following argument par ts in the FUNC argument:
1. The first argument par t defines the root record of the tree control.
2. The second argument par t defines the treeview configuration (the default treeview
configuration
3. The third argument par t defines the header name of the tree header (set this to
“Tree” if you want the default tree header to be displayed, by default the Generic
Tree Control has no header).
The value proper ty if the tree control is the currently selected record which may be
used with the TreeMultiplexer or a Generic Details Control.
The following options may be set in the OPTIONS cell:
• If infoareavalue is set, the info area nodes are also clickable and if the user
clicks on a infoarea node, it creates a value with format
“<parentinfoarea>.<parentrecid>;<clickedinfoarea>” (that may be consumed by
a Generic List Control).
• If menu is set, the nodes within the tree have a context menu.
• If initial(<info area>) is set, this info area node is initially selected when the tree
is created (e.g. allowing you can definfe a tree view of a company record and
initially select the tree node of all persons working in that company by
providing initial(KP) , thus displaying the list of persons in the right area).
The Generic Tree Control implements the following parent cell notification callbacks:
• OnNewRecord (oSender, sInfoArea, sRecId) – appends the new record to the
currently selected infoarea node and selects it
• GetCurrentTreeNodeConfiguration (oSender) – returns the tree node configuration
of the currently selected tree node
• OnDblClick (oSender, sInfoArea, sRecId) – sets the record as selected record
within the tree
Generic List Control

The Generic List Control displays a list of records with the standard list control
with the following FUNC argument par ts:
1. The first argument par t defines the link record of the list (or “-1” for no link record)
2. The second argument par t defines the info area of the record to be displayed.
3. The third argument par t defines the name of the field group to be used. You may
either directly enter an field group name or the name of a SearchAndList
configuration prefixed with a dot (“.FI for SearchAndList configuration FI”) which
is needed if you want to have a context menu within the list for the displayed
records. You may use “%%” as placeholder in SearchAndList configurations for
the info area.
4. The four th argument is an optional filter name.
The output value of the List Control is the currently selected record of the list. In
the OPTIONS cell you may specify the following special behaviors:
• InheritsFilter asks a parent tree element if there is a current filter set (by calling
method GetCurrentTreeNodeConfiguration on the parent node) in the tree view
configuration and applies it.
• DblClickNotify: if the user double-clicks a list item, instead of executing the
default action the parent object is notified by calling OnDblClick .
• ListParams can be provided to control the list’s look and feel, e.g. the width of
a list’s header ListParams{HeaderWidth,75%} . For a full list of available ListParams,
see the Aurea CRM Web Administrator Guide.
Note: Using the Generic List Control you can display editable lists in any generic
form (e.g. on a star t page).
It is possible to explicitly apply HTML formatting to elements of a generic list using

the callback hooks OnCellCreating or OnCellCreated (note that the numbering of
rows and columns is zero-based).
[javascript]
function MyCellHook(oList, oArgs)
{
// set the background color of every 2nd row to #ffee00
if ((oArgs.Row % 2) == 0)
oArgs.Cell.parentNode.style.backgroundColor = "#ffee00";
// for the 4th column, use a bold red font if the value is above 100
if (oArgs.Column == 3 && oArgs.RowData[oArgs.Column] > 100)
{
oArgs.Cell.style.color= "red";
oArgs.Cell.style.fontWeight = "bold";
}
}
var oGenericList = new Controller.GenericListControl(...);
...
oGenericList.OnCellCreated = MyCellHook;
Generic Search And List Control

The Search and List Control displays a search control and list of records of retrieved
records after the search and related records of the select list record. The settings
for the search control are defined in the FUNC argument par ts:
1. The first argument par t defines the link record of the search specified
(“<infoarea>.<recid>”) or “-1” for no link record.
2. The second argument par t defines the infoarea of the record to be searched for.
In addition, the link id can be specified after the infoarea (“<infoarea>#<linkid>”).
Alternatively “ #children ” or “ #parent ” can be specified in which case the link
record infoarea is used.
3. The third argument par t defines the name of the SearchAndList
Configuration group to be used. You may use “%%” or “$$” as placeholder in
searchandlist configurations for the infoarea. If no field group is specified, the
default for the infoarea is used.
4. The four th argument is an optional filter name.
5. The fifth argument is an optional form name. The default value is the
standard SearchAndListForm.
In the OPTIONS cell you may specify the following special behaviors:
• InheritsFilter (valid only if used with FormTeeControl or Multiplexer) asks a
parent tree element if there is a current filter set (by calling method
GetCurrentTreeNodeConfiguration on the parent node) in the tree view
configuration and applies it.
• Options: To set any of the options AutoStar t, HistoryEnabled, MaxResults,
showFilter, defaultFilter, CollapseSearchForm for the SearchAndList control, use
the syntax Options{param1;param2;…} e.g. Options{AutoStart;CollapseSearch-
Form} . If you need to specify ListParams too, add these using the syntax Op-
tions{param1;param2;…};ListParams{…}
For example: Options{AutoStart;CollapseSearchForm}; ListParams{showCon-

textMenu,false;} .
Multiplexer Control
The Multiplexer Control is a control without a display state and it switches between
form cells depending on the input FUNC argument as typically produced by the
Generic Tree Control – this control can produce three types of output values:
1. record (format “<infoarea>.<recid>”)
2. list of records (format “<linkinfoarea>.<linkrecid>;<infoarea>”)
3. new record (format “<infoarea>.new.<linkinfoarea>.<linkrecid>”) – this format is
produced by the A_TreeNew menu action within Generic Tree Controls.
The item attribute cell of the control is used to specify which cells shall be displayed
in format
<DetailsFormCellName>;<ListFormCellName>;<NewFormCellName>. The output
value of the control is the same as the input value.
The Multiplexer Control implements notification functions OnDblClick , GetCurrent-
TreeNodeConfiguration and
OnNewRecord and if called calls the parent implementation of these functions.
FormGetParentRecord Control
The FormGetParentRecord Control returns the parent record of the input record
as output. Typically this control is placed in an invisible row – the control has the
input record as first FUNC argument and the parent info area as second – and
with $<ValueName> the id of the parent record can be obtained. If you need a specific
link id for the parent info area (2nd parameter), use the syntax <info area>#<link
id> e.g. KP#2 .
Chart Control
The Chart Control allows displaying custom char ts (based on project related data)
using the same ComponentAr t char t engine that is used for Analyses.
The FUNC cell contains the char t engines data provider. The Char t control suppor ts
the following options:
• ParentSize defines that the size of the char t is taken from the parent container
of the char t control and not from the char t itself. Please note that the char t engine
needs a size to create a char t so either you set a size in the item attributes of
the char t control or the parent control must have a defined size and this option
is set.
• ChartSelector defines whether the char t control shall have a char t selector
allowing the user to select the char t type and some char t options. By default, the
the char t control has no char t selector. You may set this option with a value and
in this case the value is interpreted as form name that is used to display the char t
selector.
• ChartType defines the type of char t that is displayed – the parameter is a valid
char t type name of those configured in the char t type section of the designer.
One valid char t provider is the Controller.Charting.StaticChartProvider object,
which can be included in a generic form using the Generic Control FormExplicit-
JavascriptChartProvider. This control is included in the source shipped by update
but as it is a test control it is not registered – the control displays a textarea box
where the user may enter the data that shall be shown in the char t – and the value-
name of that control can directly be used as char tdataprovider.
Other Generic Controls

• Static Image: Displays a static image - FUNC contains the name of an image
which has to be registered in the designer’s Images with its filename.
• Show Func (Test Control): Displays the current value of its FUNC argument; use
this as test cell to receive changes within the generic form.
• FormCellTemplate (Demo Control): Test implementation displaying two text
boxes.
Accessing the Base Control from a Generic Form Control

For the standard form controls, you can access the base object in order to be able
to use the full functionality of those objects in your custom code:
• FormDetailsControl: GetDetailsControl
• FormTreeView: GetRecordTreeControl
• FormListControl: GetListControl
• FormSearchAndListControl: GetSearchAndListControl
• FormHeaderControl: GetHeaderControl
Generic Controls Interface Functions

A Generic Control must implement the following interface (you may omit functions
where no special action is needed):
function MyClass (elCallerWindow, oForm, oAddInfo)
The constructor receives 3 arguments:

• The caller window (elCallerWindow) which is the window where the form is
displayed.
• The form control (oForm).
• The dynamic cell info of the current cell (oAddInfo).
MyClass.GetHtml
Returns the HTML string of the current control. The returned text
()
is placed within a table cell within the form. The HTML text should
fulfil the following needs:
• The named HTML objects should be prefixed with
the namespace of the current cell supplied by the dynamic
field info passed in the constructor. Please note that the
namespace is not valid when the constructor is called, because
the constructor call occurs during building of the dynamic field
info, but will be available when GetHtml is called (and will not
change after that).
• You are responsible for applying the item attributes on the
appropriate HTML element ( definition[FORMCELL_ITEMATTR] of
the dynamic cell info).
• You may define the onchange handler to be automatically
called by applying the HTML produced by Form.GetOnChange-
HandlerHtml (sEvent, sNamespace) to the appropriate HTML
element. An alternate way to reflect changes of your cell to
the form is by calling the onchange-Handler explicitly.
MyClass.OnCreat- This function is called when the HTML text returned by

ed () method GetHtml was already placed into the DOM and you may
apply changes that cannot be directly applied with HTML text.
MyClass.Update This method is called every time at least one par t of the FUNC
(oRequest, bCom- argument changes. oRequest is an array containing the par ts of
plete) the FUNC argument. bComplete is true if all dependent arguments
have a concrete value, if bComplete is false typically the control
should be emptied. The Update method should be used instead
of methods ClientRequest and DataToMask.
MyClass.ValueTo- This function must be implemented if the generic control suppor ts
Form () changing the value from outside the control (or if the control
suppor ts setting initial values). If the value is changed from
outside the outside caller may call this function to reflect the
changes to the value proper ty in the visible state of the generic
control. The standard generic controls all do not suppor t this and
therefore have no implementation of ValueToForm.
MyClass.FormTo-
If the current value of your cell changes (e. g. by user input),
Value ()
you may not immediately change the value proper ty of the dynam-
ic cell info but if somebody requests the current value of the cell
this method is called. So you may either change the value prop-
er ty each time the value of your control changes or you do it
when this method is called.
MyClass.Get-
The FUNC argument of your cell may work as arguments (sepa-
DataRequestCom-
rated by semicolons) for your generic form – and it may be static
mand ()
or parameterized by values of other cells within the form (in this
case the FUNC argument has some “$” parameters that are re-
placed with the current values of the cells with the names.
Every time the dynamic FUNC argument (that is, the FUNC argu-
ment with replacements for available values) changes, this
method is called and you may change the parameters of the
FUNC request.
MyClass.Clien-
[obsolete – please use method Update instead]
tRequest (oRe-
quest, bCom- Every time the dynamic FUNC argument changes, the ClientRe-
plete) quest method is called with the FUNC argument in oRequest (this
may be different to the Func proper ty of the dynamic cell info if
it was changed by a call to GetDataRequest ). You may either re-
turn an array if you don’t want the request to be passed to the
server, or you return null. The bComplete argument signals
whether the FUNC argument still contains some open arguments
(bComplete = false) or not. If bComplete is false, the request will
not be sent to the server even if you return null.
My-
[obsolete – please use method Update instead]
Class.DataToMask
(oData) Sends the Response of a FUNC request to the control – this may
either be the result of a server request, or a server request that
could be completed from the client cache, or the data returned
by the preceding call to method ClientRequest .
Sample: Generic Form Controls

The following sample form displays all of today’s contacts for the current rep in a
list, and if the user selects one appointment, the appointment details plus the details
of the person linked to it and a tree view of the linked company are displayed. The
resulting page has the following layout:
This form may be implemented with the following steps:

1. Define a filter named “MA.TodayRep” which displays today’s contacts for the
current rep for the info area MA in Aurea CRM Designer:
2. Create a new Generic Form, and a menu entry in the application menu to display
the form.
3. Create a form cell with a headline text and one cell with a Generic List Control
displaying a maximum of 10 contact records with the filter MA.TodayRep.
For the generic cell the following arguments should be set:
Type = Generic Control, ListControl

Valuename = MAList
Func = -1;MA;MA;MA.TodayRep
XML-Path = 10 (max. Results)
4. Create a details control that displays the currently selected record. For this task,
add a generic cell with the following attributes:
Type = Generic Control, DetailsControl
Func = $MAList
5. The following task is a little more difficult, because we need the linked company
and person – and there is no standard control that does the trick, so we have to
implement it ourselves.
Our GetParent control will get a record as the first argument of the FUNC param-
eter and the parent info area as the second argument, and return the parent record
as value (or blank if this parent does not exist). The table caption of the parent
record shall be displayed.
First, register a new control with the following attributes in the Generic Controls
section of the designer:
Name = GetParent
Class = FormGetParent
Core = Yes
Second, include this control twice in your form - once for the company and once
for the person.
Third, you have to implement your FormGetParent control in a new global

Javascript:
function FormGetParent (elCallerWindow, oForm, oAddInfo)
{
// we only need to implement methods GetHtml and ClientRequest
this.GetHtml = FormGetParent_GetHtml;
this.ClientRequest = FormGetParent_ClientRequest;
// remember constructor parameters
var _self = this;
var m_oAddInfo = oAddInfo;
var m_oForm = oForm;
var m_elCallerWindow = elCallerWindow;
var m_sNamespace;
function FormGetParent_GetHtml ()
{
// create an empty DIV container with the form item attributes
m_sNamespace = m_oAddInfo.Namespace;
return "<DIV id='" + m_sNamespace + "' " +

m_oAddInfo.definition[FORMCELL_ITEMATTR] + "></DIV>";
}
function FormGetParent_ClientRequest (oCommand, bComplete)
{
// called every time the dynamic FUNC parameter changes
if (bComplete)
{
// if all open parameters are filled we need table caption and record
id
// of the linked record
var aRecord = oCommand[0].split (".");
var sParentInfoArea = oCommand[1];
var oRecord = new RecordControl(m_elCallerWindow, sParentInfoArea);
oRecord.SetFields (['$TableCaption']);
oRecord.SetLinkInfo ([[aRecord[0], aRecord[1]]]);
oRecord.Load (true);
if (IsValidRecordId(oRecord.GetRecordId()))
{
// record found
m_oAddInfo.value = sParentInfoArea + "." + oRecord.GetRecordId();
m_elCallerWindow.document.all[m_sNamespace].innerHTML = "<b><u>"
+ oRecord.GetFieldValues()[0].htmlEncode() + "</b></u>";
}
else
{
// record not found – clear control
m_oAddInfo.value = "";
m_elCallerWindow.document.all[m_sNamespace].innerHTML = "";
}
}
else
{
// request not complete – clear control
m_oAddInfo.value = "";
m_elCallerWindow.document.all[m_sNamespace].innerHTML = "";
}
m_oForm._OnChangeHandler (m_oAddInfo); // update depending cells
return []; // no server request
}
}
6. Create a Treeview Control cell that displays the tree view of the linked company
and a Details Control cell that displays the details for the linked person:
7. The generic form should now work as intended.
Parent Cell Notification

Form Cells within a form are loosely coupled, that means that there only interaction
is by receiving the output of other cells as input. In some cases a cell might need
more input from its parents or my need to notify a parent – to implement this, the
AddInfo objects has a array proper ty ParentObjects that contains the parent objects
of each par t of the FUNC argument.
This feature is used by standard generic controls in the following situations:

• The Generic List Control asks the Generic Tree about the current filter if
“InheritsFilter” is set.
• The Generic List Control sends a new current record to the Generic Tree if
“DblclickNotify” is set.
• The Generic Details Control in New Mode sends a new record to the Generic Tree
to be selected.
• In Tree / List / Details scenarios these controls may have the Multiplexer as parent
– and the Multiplexer control understands these callback functions and calls the
same function for its parent.
If you want a cell to notify its parent, you must:
1. Implement a notification function on the parent addinfo object:
function child_notification (some_arguments);
{ […] }
oAddInfo.MyNotificationFunction = child_notification;
2. If the event to notified occurs, call this function:

if (oAddInfo.ParentObjects && oAddInfo.ParentObjects[nFuncArgumentNr] &&
oAddInfo.ParentObjects[nFuncArgumentNr].MyNotificationFunction)
oAddInfo.ParentObjects[nFuncArgumentNr].MyNotificationFunction (arguments);
Sub Analysis Controls

Sub Analysis Controls display the result of another Analysis Control with different
output values, different view state, differenct categories or additional filters. This
controls requires a Root Analysis control on the form and this Analysis control should
be invisible as the sub analysis control uses it to compute its analysis. More than
one SubAnalysis Control may share a Root Analysis Control.
All Sub Analysis control have their own StatControl object and all options that work
on analysis controls will automatically work on SubAnalysis controls.
The first argument par t of the FUNC cell always is the name of the parent analysis
object.
This section describes the out-of-the-box StandardSubAnalysis control and the

interface that has to be implemented for own sub analysis controls – configure this
control with the following cell entries:
• The first argument par t of the FUNC cell is the name of the parent analysis (as
with any sub analysis control type)
• The second argument defines an alternate category in format
“<infoarea>,<uniquefieldid>” (or, if the multiple occurrences of one infoarea you
may use “<infoarea>,<occurrence>,<uniquefieldid>”).
• The third and subsequent argument par ts define alternative value columns in
format “<type>,<valuename>” (for additional values) or
“<type>,<infoarea>,<uniquefieldid>” for query result values
The output behavior (list or char t view or both, type of char t) may be defined using
the OPTIONS cell as with normal analysis controls.
If you want to implement your own SubAnalysis control your control must imple-
ment some or all of the following interface functions:
MySubAnalysis.GetH- As with Generic Controls, this returns the display html
tml () representation of the sub analysis control.
MySubAnalysis.Be- This function is called before the Create method is called
foreCreate () on the StatControl (and that is after the OnCreated function
which is called after the DOM is created) As typically sub
analyses will have the autostar t feature enabled, this is the
last chance to influence the StatControl before it becomes
visible. You may access the StatControl object by the
StatControl proper ty of the AddInfo object.
MySubAnalysis.Get- This function is called to build the Data Request (FUNC cell)
DataRequestCommand command – if you want to dynamically change the FUNC
() argument, you should implement this function.
This function is called before the computation is star ted on
MySubAnalysis.Before-
Computation (oRoot- the root analysis object. In this function you should save
Analysis) settings from the root analysis and change that to the values
needed – in the standard SubAnalysis control the category
and different value column are applied to the root analysis.
MySubAnalysis.After- This function is called after the computation is finished and
Computation () may be used to restore original settings from the root
analysis.
Analysis Input Controls

Analysis Input Controls are controls that (normally) have a visible state and apply
additional filters to sub analyses – this section describes the sample implementation
of an analysis category combo control and the interface that has to be implemented
for own Analysis Input Controls.
The Analysis Category Combo displays a combo box with catalog values (all values
that can be loaded from the server into a normal combo box are possible) and if the
user selects a value within the combo box the value is used in a filter that is applied
to one or more SubAnalysis controls.
The FUNC argument configures the Analysis Category Combo:
• The first argument par t of the analysis input control contains a comma-separated
list of the name of all subanalysis controls (or the name of the control if there is
only one) that receive the additional filter (same for all analysis input controls)
• The second argument par t defines which values have to be displayed and follows
the same syntax as normal combo boxes in the FUNC argument – but with commas
instead of semicolons. Possible values are “CAT,<infoarea>,<fieldid>” for a catalog
or “ANALYSISCAT,<vir tualcategoryname>” for vir tual categories.
• The third argument par t specifies which filter shall be applied to the sub analysis.
It is comma- separated in format “<infoarea>,<uniquefieldid>,<comparer>” – for
vir tual categories the format is
“<infoarea>,<uniquefieldid>,<comparer>,<vir tualcategoryname>”.
Sample: If you want to add a country criteria to a sub analysis you may use
“CAT,FI,5” as second argument par t to display the country catalog, and “FI,5,=” as
third argument par t to define the appropriate filter.
As long as the combobox has no value the depending SubAnalyses are not displayed.
To implement your own Analysis Input Control you must implement some or all
function of the following interface:
As with Generic Controls, this returns the display
MyInputControl.GetH- html
tml() representation of the sub analysis control.
MyInputControl.On- This function is called when the HTML text returned by
Created() method GetHtml was already placed into the DOM and you
may apply changes that cannot be directly applied with HTML
text.
MyInputControl.Get- This function is called to build the Data Request (FUNC cell)
DataRequestCom- command – if you want to dynamically change the FUNC
mand() argument, you should implement this function. The
AnalysisCategoryCombo control extracts the second argument
par t and replaces commas with semicolons which forces the
form control to automatically load needed data from the
server.
MyInputCon- Returns data from the server request – the
AnalysisCategoryCombo fills
trol.DataToMask(aDa- the combobox in this method
ta)
MyInputControl.De- This function is called when the dependencies between

pendenciesInitial- analysis objects are built and may be inspected with the
ized() AddInfo objects of the analysis controls. AnalysisInputControls
have the DependentAnalyses array proper ty that contains the

AddInfo objects of all dependent (sub) analyses – and all
subanalysis that are dependent to input controls have there
parent controls addinfo in array proper ty InputControls.
MyInputControl.Add- This function is called immediately before execution when
Criteria(oRootAnal- the object is requested to add the criteria to the root analysis.
ysis) If this function returns false execution of the analysis is
stopped, so you may prevent depending sub analyses from
being executed and displayed (e.g. if the control has no
current filter value)
If the output value of your Analysis Input Control changes you should notify the form
(as with other cell types) and you also may force redraw of dependent analyses –
a sample implementation would be the onchange handler of the AnalysisCatego-
ryCombo control:
function AnalysisCategoryComboControl_OnChange ()
{
m_oAddInfo.value = m_oCombo.value; // the new value
if (m_oAddInfo.DependentAnalyses)
{
for (var i in m_oAddInfo.DependentAnalyses)
m_oForm.ComputeAnalysis (m_oAddInfo.DependentAnalyses[i]);
}
m_oForm._OnChangeHandler (m_oAddInfo);
}
Client Code within Wizards

The following chapter provides you with some information on how you can perform
custom actions in JavaScript code within wizards. To jump into a JavaScript function
within a wizard, configure the JScriptCall page or the JScriptCallLocal page within
the wizard. While the JScriptCall page jumps to a function in the Controller, the
JScriptCallLocal function jumps to a function that is local on the wizard page. It is
recommended to load JavaScript Files dynamically. The Chapter 3.1 describes the
required steps.
In your JScriptCall you may fill the following querystring parameters:
1. The Function Name is the name of the JavaScript function that is called
2. You may pass one record with info area and record id which would be the first
two parameters of your function if you do so
3. You may enter the following Additional token to get the corresponding values in
the same order as listed, star ting with the first parameter (with no record) or the
third parameter:
Global Functions
CurrentWindow, src or window The worker window that contains the

wizard frame
WizardStep The JavaScript array that defines the
current wizard step.
inargs Array of input arguments for the current
wizard step
outargs Array of output arguments from the sub-
step of this wizard step.
The inargs argument (and outargs argument, if the wizard step has a substep) is
an array with inargs[0] being the first input argument of the wizard step, inargs[1]
the second and so on.
The arguments itself are normally record arguments, that is an array with three
elements, that is the info area, the record id and the table caption if available.
A special form argument type is produced by Generic Forms listing key-value-pairs
in the following manner:
[javascript]
var arg = inargs[argnr];
arg[0] // "ARRAY"
arg[1][0…n] // Key-Value-Pairs
arg[1][n][0] // Key #n
arg[1][n][1] // Value #n
In your function you may do some synchronous or asynchronous tasks (like using
the Record control) and at the end you should call the following methods:
[javascript]
WizardEvent (0, -1); // signals that the page is loaded
WizardEvent (EventNr, EventParameter);
The first call with event number 0 signals that the current page (that is the JScriptCall
page) is loaded enables firing of events, the second call fires and event to the
server giving back the control flow to the wizard engine. You may provide the wizard
with an Event Parameter in the same structures as an input argument.
Global Functions
Theses sections provides you with information about the usability of other public
controls / functions and some mechanisms from the controller window that may be
used in your code.
Navigating to Pages
If you want to navigate to another page in the work frame, you can use one of the
following functions (defined in the Controller):
1. Function NavigateToPage (pageName, parameters, options) navigates the work
frame to another page defined by its page name (as defined in Aurea CRM
Designer. The Parameters contain values for the page parameters, and the Options
allow to open the page in a new tab with a defined title:
[javascript]
Controller.Navigation.NavigateToPage("QueryRun",
"QueryName=myQuery&LinkInfoArea=FI&LinkRecID=23",
{CreateNewTab:{Title:"My Tab Title"}});
2. Function NavigateToMenu (menuActionName, options) executes the provided

menu action. The Options argument is an object which can contain InfoAreaId,
RecordId, LinkInfoAreaId, LinkRecordId, RecordSetProvider and a parameter for
the optional creation of the page in a new tab with a defined title:
[javascript]
Controller.Navigation.NavigateToMenu("A_MyMenuAction",
{InfoAreaId:FI, RecordId:23,
CreateNewTab:{Title:"My Tab Title"}});
3. Function NavigateToStar tPage() navigates to the Star tpage set in the current
configuration.
[javascript]
Controller.Navigation.NavigateToStartPage();
4. Function NavigateToUrl (pageFileName, parameters) navigates the work frame

to another page defined an absolute URL. You can use the parameters to
automatically add a Query String to the URL.
[javascript]
Controller.Navigation.NavigateToUrl
("http://mydomain.com/mypage.aspx", "param1=1&param2=2");
//will navigate to http://mydomain.com/mypage.aspx?param1=1&param2=2
Note: Function ContextNavigateTo is obsolete - use

Controller.Navigation.NavigateToUrl instead!
Note: Do not use NavigateToUrl for your custom created aspx pages. Register
them in the webdesigner and use NavigateToPage instead.
5. Function ExecuteDefaultAction (infoAreaId,recordId) navigates the work frame to

the page specified in the default action in Aurea CRM designer.
[javascript]
Controller.ExecuteDefaultAction ("FI", "23");
Global Functions
Using ExecuteDefaultAction(…) ensures that the navigation behavior is consistent

throughout the application (and thus foreseeable for a user), and is designed to
replace the deprecated function ContextNavigateToByName (PageName, Parame-
ters) .
6. Function goBack() navigates the work frame to the previous page; within wizard
pages the function goBackWizard() navigates back to the page that was displayed
before the wizard was invoked.
Within wizards should be implemented by throwing events and reacting to them
in the wizard definition. However, it is possible to navigate to another page within
the wizard without throwing an event by calling function WizardNavigateTo
(pageFileName, parameters, formParameters, callFlags, wizardStep). Page-
FileName and Parameters work as with ContextNavigateTo, FormParameters al-
lows to add parameters to the query string via a form parameter, CallFlags should
be 0 (a value of 1 navigates the work frame ending the wizard), and WizardStep
ist the number of the current wizard step as passed to the original page via the
WizardStep querystring argument. The called page must fulfill all requirements
for wizard pages.
Info Area Functions

Info areas are either identified by their 2 or 4-character-id (called “name” in the
following utility functions) and their index. Besides that there is a language-dependent
singular and plural display text for each info area.
By default, the two display texts per info area come from the Aurea CRM database
and as Aurea CRM itself currently does not suppor t singular and plural name, are
the same. You may overrule the singular and / or plural display name of an info area
with the Infoarea-Names section of the Aurea CRM Designer.
The following JavaScript utility functions are implemented in the Controller to allow
conversions between these fields:
• InfoAreaNameToIndex (InfoAreaName) conver ts the 2 or 4-char-name into the
info area index
• InfoAreaIndexToName (InfoAreaIndex) conver ts the info area index into the 2
or 4-char name
• InfoAreaIndexToLabel (InfoAreaIndex) conver ts the info area index into the
singular language- dependent name
• InfoAreaIndexToLabelPlural (InfoAreaIndex) conver ts the info area index into
the plural name of the infoarea
• InfoAreaNameToLabel (InfoAreaName) conver ts the 2 or 4-char name to the
singular name
• InfoAreaNameToLabelPlural (InfoAreaName) conver ts the 2 or 4-char name to
the plural name
Client Caching
If you want to cache data in the controller, you may use the client caching mechanism
implemented with the following functions:
• CachePut (key, object) puts object into the cache with cache-key key.
• CacheGet (key) returns the object that is stored in the cache with cache-key key.
• Cache_ResetCache () empties the cache.
Only objects that may be reconstructed if not in cache should be placed into the
cache as it is not guaranteed that objects placed into the cache are not deleted
later by a cache-reset called by another component.
Conversion Functions
The following conversion function implemented in the Aurea CRM Web help conver t-
ing values of specific datatypes between their display modes:
• Convert2GUIDate (mmdate) is obsolete, use DateTimeFormats.FormatDate instead.
• DateTimeFormats.FormatDate (mmdate) conver ts an 8-char-date in Aurea CRM
format (“ YYYYMMSS ”) into a display date.
• Number_FromMMString (mmstring, fDefault) is obsolete, use NumberFor-
mats.ParseNumeric instead.
• NumberFormats.ParseNumeric (mmstring, fDefault) conver ts a number in display

format (with decimal and thousand seperator) into a floating point value. If mmstring
is empty, fDefault is returned
• Number_ToMMString is obsolete, use NumberFormats.FormatNumeric instead.
• NumberFormats.FormatNumeric (fNumber, nDecimalDigits) conver ts a float
variable into the Aurea CRM number display format (with nDecimalDigits digits
after the decimal separator)
• ConvertJavaDate2GUIDate (oJavaDateObject) is obsolete, use DateTimeFor-
mats.FormatDate instead.
• DateTimeFormats.FormatDate (oJavaDateObject) conver ts a date given by a

JavaScript Date object into the display date string.
Image Handling
If you want to display an image registered by name in the Aurea CRM Designer you
may use the following functions to determine the filename of the image and its display
label if needed:
• image_getFilename (sImageName) returns the filename of an image
• image_getLabel (sImageName) returns the display label of the image
Global Functions
Due to a bug in the Internet Explorer (or exactly the WinINet component below), the
Internet Explorer may hang when too many image sources are set directly and
synchronously. Microsoft recommends to just create the <IMG> elements and set
the image sources asynchronously.
The controller provides you with some function to easily workaround this problem:
• image_RegisterObject (oIMGElement, sIMGSrc, sIMGBackground, CallerWindow)
registers sIMGSrc as source for the IMG element in oIMGElement, with is placed
in CallerWindow. The image source may be provided absolute or without the path,
in this case the image has to be placed in the style images directory.
• image_RegisterHTML (sIMGElementId, sIMGSrc, sIMGBackground, CallerWindow)
does the same but with the id of the IMG element instead of the element itself
• image_CreateHTML (sIMGSrc, CallerWindow, sAdditionalAttributes, sImageId)
returns the html code for an image and registers the image source. It is impor tant
to synchronously place this html code onto the window after a call to this function
for the image display to work properly. The optional sAdditionalAttributes are
applied to the IMG element, and you may explicitly set the image id (with
sImageId), if not, a unique id is created.
With these functions the SRC proper ty of the IMG element is not directly set – they
will be set asynchronously after a call to image_SetSources:
• image_SetSources (fCallbackFunction, oCallbackParameter) sets a timeout to
asynchronously set the image sources of all registered images. This function
returns immediately without the images being set – if you want to react on the
image loading being completed you may set a callback function with an optional
parameter and this function is called upon completion.
Select Functions
A select function allows fields to be filled with values from a record of another info
area using either Selectors.SelectRecord for reference fields or Selectors.Show-
ContextMenu for generic link fields. These Select Functions define which related
records can be selected, and how the relation is set after selecting a record.
It is also possible to specify a FormatSelect function, or functions for picking an
info area and field.
Note: Reference fields that are marked read-only in the data model definition or
in the designer via a field detail never display a record select icon in masks. However,
he administrator can override this default behavior by explicitly specifying a record
selector for such a reference field.
If a record selector function is defined and the Web Configuration parameter ShowS-
electorIfPresent is set, it is always displayed in the web (independent whether
the data model field attribute NOEDIT or the designer Field Detail Read Only is de-
fined).
In these cases, it is the administrator’s responsibility to ensure that the select

function “makes sense” and fills the appropriate (key) fields. This possibility increases
the web’s flexibility and could e.g. even be used to let users re-assign parent records
if required.
Note: User’s rights settings are only checked for that field where the Select-Function
is defined (not for the fields contained in the function).
The Selectors.SelectRecord Function

Selectors.SelectRecord provides the user with the possibility to select a record
that is then linked to the current record.
Selectors.SelectRecord(<RecordSelectorOptions>) … syntax and parameters
described below
Selectors.SelectRecord() combines the possibilities that the deprecated record
select functions RecordSelect and RecordSelectEx offered, and also provides ex-
tended functionality.
Note: The functions RecordSelect and RecordSelectEx continue to work for reasons
of backwards compatibility, but it is not recommended to use these functions for
new projects (also because they do not provide the full feature set of the new record
selector).
The proper ties of the objects passed as parameters to Selectors.SelectRecord() are
described in the following table. Note that the parameters need to be specified in
JSON (Java Script Object Notation) syntax – for more information,
see http://www.json.org.
SelectRecord Syntax Selectors.SelectRecord(<RecordSelec-

torOptions>)
RecordSelectorOptions Syntax <RecordSelectorOptions>={key1:value,

key2:value,…}
available RecordSelectorOptions
InfoArea: <InfoAreaId> optional: the info area of the details

mask.
Global Functions
LinkInfoArea: <InfoAreaId> optional: the info area to select a record

from.
Note: Either LinkInfoArea or Search-

FieldGroup must be specified.
SearchFieldGroup:<FieldgroupName> optional: name of the field group used for

the search control.
Note: If not specified, the value

of LinkInfoArea will be used as the field
group name.
AddLink: <true|false> OR optional: if set to true, the selected record

will be a new link record of the record
{LinkIds: [id1, id2]}
displayed in the mask view (default:
false).
To add more than one link, specify all
desired link IDs separated by comma,
e.g. AddLink: {LinkIds: [0, 1]}
DetailsMapping: <FieldMapping> optional: defines the fields to be copied

from the selected record to the record
viewed in the mask.
<FieldMapping> = { <TargetFieldIdOr-
Name> :<SourceFieldIdOrName> }
SearchMapping: <FieldMapping> optional: allows to copy initial search

criteria from the mask view into the
search control.
FixedSearchMapping:<FieldMapping> optional: enforce search criteria by

copying field values from the mask view
into the search control.
AutoStart: <true|false> optional: if set to true, the search will be

star ted automatically (default: false).
DisableFilter: <true|false> optional: if set to true, users can not se-

lect a filter in the search control.
DefaultFilter: <FilterName> optional: applies a filter in the search

control (can be changed by user)
FixedFilter: <FilterName> optional: enforces a filter in the search

control (can not be changed by user).
RelationName: <RelationName> optional: name of a relation used when

searching records.
Note: This proper ty requires a parent

record to work. The parent record can
either be specified trough proper ty 'Par-
entRecord' (see below), or the record
currently displayed in the mask view will
be used as parent record. If no existing
record is currently displayed the mask
view (e.g. when creating a new record),
the link record of the mask view will be
used.
ParentRecord: <ParentRecord> optional: a record to be used as a parent

record for the search control. If provided,
only records linked to this record will be
found.
<ParentRecord> = { InfoArea: <In-
foAreaId>,RecID:<RecordId>,Relation-
Name: <RelationName> }
Examples (to improve readability, some statements are wrapped into multiple lines):
1. Linking an activity record to an appointment:
Global Functions
Selectors.SelectRecord({ LinkInfoArea: "AK", AddLink: true });
2. Selecting a city for a company (and copying the values for ZIP, city, country and
area code into the corresponding fields 5, 6, 8, 15 of the company record):
Selectors.SelectRecord({ SearchFieldGroup: "OR-Link",
DetailsMapping: {5:0, 6:2, 8:5, 15:6},
SearchMapping: {5:0, 6:[2,4]}});
3. FS ver tical version - Selecting a bank account for a product (only bank accounts
linked to the same company as the product can be selected):
Selectors.SelectRecord({ DetailsMapping:
{
"SortCode": "SortCode",
"Institute":"Institute",
"Branch":"Branch",
"AcNo":"AcNo",
"BankDetailsStatNo":"StatNo",
"BankDetailsSeqNo":"SeqNo"
},
RelationName: "$Link[FI]",
AddLink: true
});
If you want to copy the text value of a catalog, prefix the field number with a ‘T’.
Important: Please note that fields used in the Select function need to be included
in the details mask i.e. you can not use fields in a Select-Function which are not
present in the mask, otherwise this function will not work correctly.
Note: For both functions the reference text is inser ted into the field before the
user saves. The reference texts for an info area are defined in Aurea CRM win in
the Configuration table (MC) - section “Data Model”, option “Reference Text” - for
more information see the Aurea CRM win Administrator manual.
The Selectors.ShowContextMenu Function

Selectors.ShowContextMenu provides the user with a context menu where s/he can
select the info area s/he wants to pick a link record from. That way, users of Aurea
CRM Web can create links (like e.g. exist in To-Dos or Tasks) from one record to
another also if the links are defined as Generic Links in the data model.
Used for generic links only: Selectors.ShowContextMenu(<ContextMenuName>) … to
call a menu. In this menu, the menu actions must be a “JScriptCall” PageCall.
The JScriptCall has to be configured as followed:
• Additional: src,{<RecordSelectorOptions> described for SelectRecord below}
• FunctionName: Selectors.SelectRecordViaMenu()
Examples:
1. Select an appointment as the generic link in a To-Do record:
a. Create a context menu (named M_MyContextMenu in this example).
b. Set the field detail Select Function of field “Link” as follows:
Selectors.ShowContextMenu("M_MyContextMenu");
c. Add a menu action with a “JScriptCall” page call to the context menu and apply
the following parameters:
Additional Parameters:
src, {LinkInfoArea: "MA", DetailsMapping:{ Link:"$TableCaption", Sub-
ject: "Subject" },
AddLink:true} to use the table caption or

src, {LinkInfoArea: "MA", DetailsMapping:{ Link:"$Reference ", Subject:
"Subject" }, AddLink:true} to use the reference string defined in Aurea CRM
win (default is DetailsMapping is omitted).
Name of the Function: Selectors.SelectRecordViaMenu
d. Repeat step 3 to let the user choose to link records from different info areas.
2. Provide a context menu offering to link a campaign or a ticket to a task:
Global Functions
The FormatSelect Function

FormatSelect provides the user with the possibility to select a format (e.g. selection,
query, default values, …).
• FormatSelect(sInfoArea, nFieldIndex, nFormatType, bCurrentRepOnly,
bAddPrivate, sFilter);
Parameter Description
sInfoArea The 2 or 4-letter name of the InfoArea
displayed in the details control.
nFieldIndex The index of the field to which the format
name is copied.
nFormatType The number which represents the type of
Format.
bCurrentRepOnly If true, only formats for the current Rep
can be selected.
bAddPrivate If true, the private formats for the current
Rep will also be display.
sFilter An optional filter which can be applied to
the format search.
• The function FormatSelectMultiple allows the selection of more than one format
(the selected formats are joins in a ; separated string) and is used e.g. for selecting
a rep’s phone profiles. The function accepts the same parameters as FormatSelect ,
plus an additional last parameter: if ‘%fieldValue%’ is specified, the currently
selected formats are automatically selected in the format selection dialog. Example
for the Rep (ID) field “phone profile”: FormatSelectMulti-
ple('ID',102,48,false,true,'','%fieldValue%')
• The function FilteredFormatSelect is also available: it accepts the same

parameters as FormatSelect , plus an additional last parameter where you can
specify the number of the field that contains an info area abbreviation. Only
formats defined for that info area will be available. This is used in
UPDATE_DEFAULT for selecting the default format in questions (F2).
Info Area & Field Selection Functions

Two functions provide the possibility for users to select an info area and then a field
from this info area. For this functionality, two fields with different selectors are
necessary:
• PickInfoAreaId(InfoArea, FieldNumber) allows the user to select an info area
and writes the result to the field FieldNumber in InfoArea .
• PickFieldId(InfoArea, FieldNumber, FieldNumber_containing_InfoArea) allows
selecting a field from FieldNumber_containing_InfoArea afterwards, which is
stored in FieldNumber .
Deprecated Functions
The functions RecordSelect and RecordSelectEx have been replaced by Selec-
tors.SelectRecord in SP3 and higher. RecordSelect and RecordSelectEx still work,
but update highly recommends using Selectors.SelectRecord when defining a
record select function. Translating existing functions to the new syntax is also easy:
• Translating RecordSelect(...) to Selectors.SelectRecord(...)
RecordSelect(<InfoArea>, <LinkInfoArea>, <FieldIds>, <LinkFieldIds>,
<RelationName>,
<AddLink>, <Options>);
can be written as
Selectors.SelectRecord({
InfoArea: <InfoArea>,
LinkInfoArea: <LinkInfoArea>,
DetailsMapping: {<FieldIds[0]>:<LinkFieldIds[0]>,
<FieldIds[1],<LinkFieldIds[1]>, …},
RelationName: <RelationName>,
AddLink: <AddLink>
});
The proper ties contained in parameter <Options> (if used) have to be merged
into the object passed to Selectors.SelectRecord(...) .
• Translating RecordSelectEx(...) to Selectors.SelectRecord(...)
RecordSelectEx(<InfoArea>, <SearchFieldGroup>, <SearchMapping>,
<DetailsMapping>, <Options>);
can be written as
Selectors.SelectRecord({
InfoArea: <InfoArea>,
SearchFieldGroup: <SearchFieldGroup>,
SearchMapping: <SearchMapping>,
DetailsMapping: <DetailsMapping>
});
The proper ties contained in parameter <Options> (if used) have to be merged into
the object passed to Selectors.SelectRecord(...) .
The RecordSelect Function

The RecordSelect is a JavaScript function used as a possible value for the field
detail "Select-Function".
Global Functions
If the field detail "Select-Function" is specified, an icon ( ) will appear right to the
field. Clicking this icon will - in case of the RecordSelect function - display a popup
dialog containing a SearchAndList page.
As soon as the search has been star ted, a record can be selected from the results
list.
The popup dialog will be closed and an arbitrary set of fields will be copied from
the selected record into the record display by the calling details control.
For this to work you need to pass the following parameters to the RecordSelect func-
tion:
RecordSelect( sInfoArea, sLinkInfoArea, aFieldIndices, aLinkFieldIndices,
bAddLink, oOptions);
sInfoArea The 2 or 4-letter name of the info area displayed in the details
control.
sLinkInfoArea The 2 or 4-letter name of the info area from which a record
should be selected.
Note: If this parameter is left empty, it is assumed that the field
is a reference field. The reference info area defined within the
data model will be used as the value for parameter "sLinkIn-
foArea".
aFieldIndices An array of field indices of the target fields in info area "sIn-
foArea".
aLinkFieldIndices An array of field indices of the source fields in info area

"sLinkInfoArea"
sRelationName An optional relation name defining a relationship between the

two info areas involved.
You can pass "" (empty string) or null if no custom relation is
to be used.
bAddLink Set this to true in order to link the selected record with the
record displayed in the details control.
Note: This only works if a link is defined in the Aurea CRM data
model!
oOptions An optional object containing additional parameters.
As the optional parameter "oOptions" you may pass a javascript object. Following
is a list of proper ties currently suppor ted for this object.
FixedFieldIndices An array of field indices of the info area specified by

parameter "sLinkInfoArea".
This field can be used to pre-set search criteria for the
SearchAndList criteria. These search criteria cannot
be changed by the user.
FixedDetailsFieldIndices An array of field indices defining the source fields for

the fields defined by proper ty "FixedFieldIndices".
Example:
RecordSelect(
'FI', 'KP',
[60,61], [2,3],
null,
false,
{FixedFieldIndices:[19], FixedDetailsFieldIndices: [5] });
This example will show a popup dialog that allows the user to select a person (info
area "KP"). From the selected person the fields 2 (=Lastname) and 3 (=Firstname)
will be copied into fields 60 (=FreiC1) and 61 (=FreiC2) of the company (info area
"FI") record.
In addition the user will only be able to select persons having the field 19 (=country)
set to the same value as field 5 (=country) of the company record.
The RecordSelectEx Function
The RecordSelectEx is a JavaScript function used as a possible value for the field
detail "Select-Function".
If RecordSelectEx is specified in the field detail "Select-Function", an icon ( ) will

appear to the right of the field. Clicking this icon will display a popup dialog contain-
ing a SearchAndList page.
A record can be selected from the results list and the dialog will be closed and a
defined set of fields will be copied from the selected record into specific fields of
the calling details control.
For this to work you need to pass the following parameters to the RecordSe-
lectEx function:
RecordSelectEx(sInfoArea, sSearchAndListConfig, oSearchMapping,
oDetailsMapping, sOptions)
Global Functions
sInfoArea The 2 or 4-letter name of the InfoArea displayed in the de-

tails control.
sSearchAndListConfig The name of the Search & List configuration which is used
to Search for and then List the records from which the se-
lected data will be copied. (Please note: the Search and
List group control is reference by Search & List configura-
tion)
oSearchMapping Defines the mapping of values from the details control to

the search control.
oDetailsMapping Defines the mapping of values from the selected record to

the details control.
sOptions Options for the SearchAndList page.

Valid values, which can be separated by semicolon, are:
1. AutoStart : The search star ts as soon as the page is
loaded.
2. DisableFilter : Disables the ability to select filters for
the search.
3. DefaultFilter=<Name> : Sets a default filter (only if Dis-
ableFilter is not specified).
4. FixedFilter=<Name> : Sets a fixed filter which is applied

to the search, but is not visible to the user.
Example: the following sample is used to copy fields from a City (OR) record to
Company (FI) related to City, Country, Area Code and Zip Code.
RecordSelectEx('FI','OR-Link',{5:0,7:[2,4]},{5:0,7:2,8:5,14:6})
When the icon is clicked a dialog containing a search and list control, defined by
the Search & List configuration "OR-Link" is opened. The details control values of
the fields "Country" (5) and "Zip/PC" (7) are copied to the search mask fields
"Country" (0) and "From PC" (2) and "To PC" (4) (the same value to both).
After a City is selected the values from fields "Country" (0), "From PC" (2), "City"
(5) and "Tel. Prefix" (6) are copied to the Company details control fields "Country"
(5), "Zip/PC" (7), "City" (8) and "Tel. Prefix" (14).
If specified as
RecordSelectEx('FI','OR-Link',{5:0,7:[2,4]},{5:0,7:2,8:5,14:6},'AutoStart;DisableFilter')
the search star ts automatically and users can not select filters.
MessageBox Functions
Four functions allow the programmer to give direct feedback to the user via a mes-
sage box:
MessageBox_ShowInfo(elCallerWindow, sMessage, sButtons, fnCallback,
bFireDefaultActionOnClose, oAdditionalOptions)
MessageBox_ShowWaring(elCallerWindow, sMessage, sButtons, fnCallback,
MessageBox_ShowError( elCallerWindow, sMessage, sButtons, fnCallback,
MessageBox_ShowQuestion(elWindow, sMessage, sButtons, fnCallback,
elCallerWindow The current Window object.
sMessage The text that should be displayed in the message box;

alternatively, a text from the the designer can be
specified using the syntax TextGroup-
Name.TXT_TextGroupName_Index .
sButtons The buttons that should be displayed - available but-

tons are: Ok, Yes, No, Cancel, Abort, Retry, Ig-
nore, Settings, Delete .
fnCallback The callback function allowing you to react according

to which button was pressed.
Global Functions
bFireDefaultActionOnClose Executes the default action of fnCallback when the

dialog is closed using the top-right .
oAdditionalOptions An optional JSON structure of comma-separated

key/value pairs. Can contain
e.g. ID of the dialog’s caption text {Caption-
TextgroupId:"id"} , the dialog’s dimensions
via {Height:"size in px", Width:"size in px"} , or
the alignment of the buttons using {ButtonsAlign-
ment:"<align>"} with the possible values left , cen-
ter , and right for <align>, or the Caption us-
ing{CaptionTextgroupId:"<TextGroupId>"} using the
syntax TextGroupName.TXT_TextGroupName_Index for
<TextGroupId> .
MessageBox_ShowInfo MessageBox_ShowWaring
MessageBox_ShowError MessageBox_ShowQuestion
Example displaying an informational message box with the text “Hello World!” like
in the top-left-most screenshot:
function Sample_MessageBoxControl(element)
{
// display an information message
MessageBox_ShowInfo(element.document.parentWindow, "Hello World!", "Ok,Cancel",
Sample_MessageBoxControl_Callback, false);
// same usage for MessageBox_ShowWarnung and MessageBox_ShowError, // with the
same parameters, the only difference is the displayed icon
}
function Sample_MessageBoxControl_Callback(oDialogResult)
{
if (oDialogResult.CommandName === "Ok")
{
// Ok Button was pressed
}
else if (oDialogResult.CommandName === "Cancel")
{
// Cancel Button was pressed

}
}
Calling Custom Code Before/After Sending E-Mails

Using events, you can call custom code before and/or after an e-mail is set. To do
so, you need to attach to a global event in a global script, e.g.
Controller.Email.OnBeforeSend.Add(MyFunction_OnBeforeSend);
Controller.Email.OnAfterSend.Add(MyFunction_OnAfterSend);
function MyFunction_OnBeforeSend(oObject, oArgs) {...}
function MyFunction_OnAfterSend(oObject, oArgs) {...}
Example showing how to hook event "Controller.Emails.OnAfterSend"

To try out this example, you need to create a direct button or context menu entry
using the page call JScriptCall in addition to the JavaScript code below. Provide
the following values in the respective parameters of this page call: additional =
"CurrentWindow", functionname = "MyNamespace.SendEmailAppointment", infoarea
= "Record", and infoarea2 = "no value"
MyNamespace = {}; // create a sample namespace
MyNamespace.IsAlreadyListeningForEvent = false;
// Sample function to be bound to a direct button or a context menu entry.
MyNamespace.SendEmailAppointment = function(sInfoAreaId, sRecordId, elWindow)
{
// make sure the "Emails" type is loaded
Controller.ClassFactory.LoadType("Emails", function()
{
if (!MyNamespace.IsAlreadyListeningForEvent)
{
// add a listener to event "Emails.OnAfterSend"
MyNamespace.IsAlreadyListeningForEvent = true;
Controller.Emails.OnAfterSend.Add( function(sender, args)
{
MyNamespace.OnEmailSent(sInfoAreaId,sRecordId,elWindow,args.EmailMessage);
});
}
// send the e-mail
Controller.Emails.SendAsEmailClick(sInfoAreaId, sRecordId, elWindow);
});
};
// This method will be called whenever an e-mail has been sent.
MyNamespace.OnEmailSent = function(sInfoAreaId, sRecordId, elWindow, oEmailMessage)
{
alert ("The e-mail has been sent!");
};
JScriptCall Pages
JScriptCall Pages
The JScriptCall Pages are dummy pages which can be used to execute various
types of JavaScript functions.
• JScriptCall: allows the user to call a JavaScript method which is within the
controller.
• JScriptCallLocal: allows the user to call a JavaScript method which is on the local
page.
• JScriptCallObject: allow the user to call a JavaScript method which is a member
of the given object.
The JScriptCall’s can be used from Application and Context Menus and Direct But-
tons.
The JScriptCall’s arguments are:
• FunctionName, the name the JavaScript function to be called, this argument is
required.
• InfoArea, the record which is passed to the function as the InfoArea Id and the
record Id, can be the current record, the linked record or have no value.
• InfoArea2, a second record which is passed to the function.
• RecordSet, fills record in a list where it will be stored for later use the options for
the recordset Provider:
• all
• visible
• selected
the control where the which contains the call must contain a RecordSetProvider
only JScriptCall and JScriptCallLocal contains the RecordSet argument.
• Additional, the following additional parameters can also be passed to function.
• src, the DOM element which initiated the call.
• CurrentObject, the Object from which the call was made.
• MenuObject, the Menu from which the call was made. (Menu only)
• CurrentWindow, the current Window DOM element.
• currentFrame, the current Frame DOM element.
• control, the Header Object which contains the button. (Direct Button only)
• buttonname, the name of the button clicked. (Direct Button only)
Other Controls
This section provides you with information about additional documented controls.
The Generic List

Aurea CRM Web uses to kinds of lists – the List Control and the Generic List Control.
While the List Control is bound to Aurea CRM data structures and implements inline
edit, the Generic List Control allows to display all kinds of data that can be presented
in a two-dimensional array.
In the standard implementation of Aurea CRM Web the Generic List is used to display
query results, analysis details, sub info areas on the dashboard view, for the par tic-
ipation list for contacts and for the event list.
To use a generic list, execute the following steps:
1. Place a DIV element with an unique id onto the page where you want the generic
list to be displayed:
<DIV id="myGenericListDiv"></DIV>
2. Create the generic list and initialize it with the id of the DIV element
var genericList = new GenericList (window, "myGenericListDiv");
3. Set the headlines of the columns, the widths and the data you want to display by
calling the SetData method.
var headlines = ["Column1Header", "Column2Header", "Column3Header"]; var width
= [50,30,20];
var data = [['Row1', 3, 5], ['Row2', 6, 8], ['Row3', 7, 9], ['Row4', 1, 1]];
genericList.SetData (data, width, headlines);
4. If these data are Aurea CRM record bound, you may call the SetMenuData method
to set the info areas and record ids (if you want to display a fixed menu, use
method SetMenu instead):
var infoAreas = ['FI', 'KP'];
var recordIds = [[1,2],[6,3],[7,12],[4,9]];
genericList.SetMenuData (infoAreas, recordIds);
5. Call the Fill method to display the generic list.

genericList.Fill();
To get the data you want to display you may either place them directly onto your
custom page with server-side code or you implement your own channel to request
the data asynchronously.
Other Controls
The Tree View

This section describes the tree view classes which are used for the Tree View Page,
the Interests Page and the Rep Picker. You may use the tree to display custom data
in a tree structure.
To implement a custom tree view you actually need to know about three classes:
1. The TreeControl class itself defines the whole tree
2. Each instance of a TreeElement defines one node of the tree.
3. Each instance belongs to a node type, and for each node type one instance of
class TreeNodeType exists within the tree. The node type instance is a template
for the elements.
To create a custom tree, execute the following steps:
1. Place a DIV element with an unique id onto the page where you want the generic
list to be displayed:
<DIV id="myTreeDiv"></DIV>
2. Do tests in inner function to avoid polution in the global namespace, place the
declaration on top of the function
var treeTypeChild1, treeTypeChild2;
3. Create a TreeControl instance and initialize it with the id of the DIV container:
var treeControl = new TreeControl ("myTreeDiv", window);
4. Create TreeNodeType instances for each node type that is displayed within the
tree, and set its proper ties and event callback functions (see below for details on
class TreeNodeType):
var treeTypeRoot = treeControl.CreateNodeType ("RootType");
treeTypeRoot.ImmediateExpand = true;
treeTypeChild1 = treeControl.CreateNodeType ("Child1");
treeTypeChild2 = treeControl.CreateNodeType ("Child2");
treeTypeRoot.OnExpand = root_expand;
treeTypeChild1.OnExpand = child1_expand;
treeTypeChild2.OnExpand = child2_expand;
5. Create an instance for the root tree element, set its proper ties and assign it to
the tree instance (the constructor needs the parent element – which is null for
the root element – the tree node type and the id of the element)
var treeElement = new TreeElement (null, treeTypeRoot, "RootElement");
treeElement.SetLabel("Root Element");
treeControl.SetRootElement (treeElement);
6. Call the Draw method to display the tree:

treeControl.Draw ();
The TreeNodeType instance defines the look of each assigned tree element with
these proper ties:
• HasMenu defines whether elements of this type have a menu (true) or not (false).
If this value is set to true, you may change the menu image from the standard
“ico_popupMenu.gif ” by changing the proper ty MenuImage.
• CanBeSelected defines whether elements of this type may be selected by the
user (true) or not (false).
• CanBeChecked defines whether elements of this type have a check box (true)
or not (false).
• Image defines the image when the element is collapsed; ImageExpanded defines
the image for the expanded mode.
• ImmediateExpand defines if the Node is expanded after the creation of the tree
The following event handler functions are called when an event occurs – with the
signature and their default implementation:
• OnExpand is called when the user first expands a node (the default implementation
removes the expand/ compress image signalling that this element has no children).
If the OnExpand function returns true, the element is set to be expanded and the
element is redrawn; if you don’t want this node to be expanded at the moment,
return false instead.
function TreeNodeType_OnExpand (treeElement)
{
if (!treeElement.HasChildren() || !treeElement.GetInitialExpand())
treeElement.AddChild (null);
return true;
}
• OnMenu is called when the node type has a menu (proper ty HasMenu) and the
user clicks the menu item
function TreeNodeType_OnMenu (treeElement, clickedObject)
{
return false;
}
• OnSelect is called when the node element is selected and its node type has
proper ty CanBeSelected set to true
function TreeNodeType_OnSelect (treeElement, clickedObject)
{
return false;
}
• OnCheck is called when the check box of the node element is clicked
function TreeNodeType_OnCheck (treeElement, clickedObject)
{
return false;
}

Other Controls
For each handler function you get the involved TreeElement instance - to get the
TreeControl instance, call the GetTreeControl method of the element, to get the
tree node type, call the GetTreeNodeType method. For all handlers but OnExpand
you also get the clicked DOM item what you may you for placing objects (like menus)
on the screen.
If your tree is not guaranteed to be small, child nodes should always be expanded
on demand in the OnExpand method – as with the standard Treeview page, where
child records are loaded from the server via a channel when the user first expands
a node.
To add elements use method AddChild as in the following example, that adds two
elements to the parent element:
function child1_expand (treeNode)
{
var treeElement = new TreeElement (treeNode, treeTypeChild2, treeNode.GetId()
+ "_0");
treeElement.SetLabel("Node: " + treeNode.GetId() + "_0");
treeNode.AddChild (treeElement);
treeElement = new TreeElement (treeNode, treeTypeChild2, treeNode.GetId() +
"_1");
treeElement.SetLabel("Node: " + treeNode.GetId() + "_1");
treeNode.AddChild (treeElement);
return true;
}
The TreeControl also suppor ts additional information columns – a feature that is

used with the par ticipants list of appointment records – the tree is displayed at the
left and each row may have additional information in columns align at the right side
of the tree. You may define the widths of the additional information columns by the
tree controls SetWidths method. Default values for additional infos of a node type
may be defined by setting the AddCellValues proper ty of the TreeNodeType instance
an array of values. The values of a single element may be defined by calling
the SetAddCellValues method of the TreeElement instance.
Please refer to the Aurea CRM Web Administration Guide for all features of the tree
control.
Implementing a Custom Organisational Hierarchy Chart

If you want to display your own custom organizational hierarchy based on project-
specific business logic, the provider class ( RepOrgChartControl ) used in For-
mOrgTreeControl in the Generic Form Org Char t needs to be replaced. You can
specify your own class using the ClassName Option in the FormOrgTreeControls
cell.
The Interface of the provider class must look as follows:
If the provider class is set using ClassName, its constructor receives 2 parameters
– the CallerWindow and the Namespace (if the class is used only within JavaScript
code, the signature of the constructor is arbitrary).
SetOptions(oOptions) – allows setting generic options e.g. DisableChildren, Dis-
ableParent, CheckChildren, CheckParent.

HasExpandUp() –must return true if navigation upwards should be suppor ted by the
control, otherwise false.
GetParent(oCurrentElement) – returns the parent object of the current object (or
null).
GetChildren(oCurrentElement) – returns an array of child elements of the current
node (or null).
GetObject(sId) – returns the object matching the provided ID (this method is typi-
cally used as entry point).
GetId(oCurrentElement) – returns the ID of the current element.
HasParent(oCurrentElement) – returns true if the current element has a parent ele-
ment, otherwise false.
HasChildren(oCurrentElement) – returns true if the current element has at least
one child element, otherwise false.
OnWrite(oTreeElement, oFunctions, oCurrentElement, elTD) –is called when the
current element should be displayed in the organisational tree. You need to set the
HTML content in the TableCell element passed in elTD. oTreeElement is the corre-
sponding element class of the TreeControl, oFunctions contains the JavaScript text
for the possible functions on the element (the oFunctions element always contains
the members DoubleClick and ExpandClick and, if suppor ted, also Select, Menu,
Check and LabelClick).
Implementing a Custom Match-Up

Star ting with SP4, the results of a match-up can be customized to suit the customer’s
requirements: existing options can be removed; project-specific options (e.g. the
creation of an identity relationship) can be added.
Customizing is performed using the Controller.Matchup.Data JavaScript object.
Note: If you want to add new options, you must not replace any of the standard
options (even if you don’t need them, in which case you can deactivate them)
because the standard options implement cer tain standard behaviors.

Calling an External Address Check
The structure of Controller.Matchup.Data is as follows:

Controller.Matchup.Data = {
Options : {
Option1: { id:1, text1: "Textgroups.MatchupTexts.TXT_MatchupTexts_2",
text2: "Textgroups.MatchupTexts.TXT_MatchupTexts_3", active:true, },
text2: "Textgroups.MatchupTexts.TXT_MatchupTexts_5", active:true },
text2: "Textgroups.MatchupTexts.TXT_MatchupTexts_11", active: true },
text2: "", active:true, requiresSelectedRecord:false }
},
InitiallyCheckedOption : 1,
TextGroups : ["MatchupTexts","net_mask_text"],
Dialog: {Height:450,Width:680},
EventHandler: null
};
requiresSelectedRecord controls whether the user needs to select a record for this
option (default: true ). If requiresSelectedRecord is set to false and the user has
not selected a record, the Event-Handler is not fired (but the message is directly
displayed in the info box).
Example for deactivating an existing option and adding a new option:
Controller.Matchup.Data.Options.Option1.active = false; // do not display 1st
option
// set dialog’s width & heigth
Controller.Matchup.Data.Dialog.Height = 500;
Controller.Matchup.Data.Dialog.Width = 700;
// 7th option checked by default
Controller.Matchup.Data.InitiallyCheckedOption = 7;
// text of 7th option using custom textgroup
Controller.Matchup.Data.TextGroups.push("myOwnTextGroup");
Controller.Matchup.Data.Options.Option7 = { id:7,
text1:"Textgroups.myOwnTextGroup.TXT_myOwnTextGroup_30", text2: "", active:true};
// custom event handler
Controller.Matchup.Data.EventHandler = MatchupSampleEventHandler;
// matchupData consists of: matchupData.InfoArea, matchupData.RecordId,
matchupData.MatchupOption
function MatchupSampleEventHandler(matchupObject, matchupData) {
if (matchupData.MatchupOption == 7)
{
// my custom matchup action occured }
}
Calling an External Address Check

Analogous to the interface for performing an external match-up, you can check
whether address data entered by the user is valid before saving a record. For details
on how to configure an external address check, see the Aurea CRM Web Adminis-
trator Guide.

When using add-on programming to call the address check, you need to know that
the address check functionality is controlled by the Save Header button code and
not the actual Save function. Thus, you need to initialize the address checker and
then perform the check itself (passing an array containing the indices of the fields
that have been changed):
// do an address check if required
if (m_oAddressCheck === null)
m_oAddressCheck = Controller.AddressCheck.Init(m_sInfoAreaId, m_sRecordId ||
"");
if (m_oAddressCheck && m_oAddressCheck.Check(arrOfIndicesChanged))
return;
Opening a Mask Configuration Dialog

For details on the functionality of the mask configuration dialog, see the Aurea CRM
Web Administrator Guide. This snippet illustrates activating the customization dialog
via JavaScript:
var maskDesigner = new MaskDesigner (parentControl, parentWindow);
maskDesigner.SetContext (fieldgroupName, controlName, options);
maskDesigner.Create (function (changed)
{
if (changed)
{
alert ('refresh');
}
});
To modify a currently loaded control, you can alternatively also use detailsCon-
trol.MaskDesigner();
Displaying Contact Times in Day & Week Planning

To make especially visit planning easier, it is possible to display the contact times
of the selected company or person in the calendar of the Day & Week Planning
page. For other info areas, the contact times of the parent person or company can
be displayed.

Displaying Contact Times in Day & Week Planning
Since contact times are stored very differently at each customer, there is no out-of-
the-box implementation but an Event Handler needs to be implemented in the project.
When the user selects a company, person (or a record that has either as a parent)
from the search results, an event is fired which allows you to determine the contact
times. If no record in the list is selected, the calendar is displayed without contact
times.
Times that are NOT specified as contact times will be displayed in a darker color
in the calendar (using the CSS style td.calDayBarContactTime , beige in the
screenshot); times where a customer may be contacted will remain unchanged (white
in the screenshot).
You need to perform the following steps to display contact times in the day & week
planning:
1. Register the static OnCreating event handler using Controller.DayWeekPlan-
ning.OnCreating.Add(EventHandler);
2. In the event handler, which has the arguments (oSender, oArgs) , you get the
DayWeekPlanning Control (in oSender ) in which you need to register the Con-
tactViewChanged handler. If the selected record in the search result list changes,
the event ContactViewChanged is now notified about that change.
3. Implement a function which determines and returns the contact times (based on
FI/KP, the selected record, and the requested days as input arguments).
Use SetContactTime(oContactTime) to set the determined contact time of the
customer in the JSON object oContactTime (outlined in the code sketch below).
4. Last but not least, de-register ContactViewChanged in OnDisposing .
Code sketch:
function _OnDayWeekPlanningCreating(oDayWeekPlanning, oArgs)
{
oDayWeekPlanning.OnContactViewChanged.Add(_ContactViewChanged);

oDayWeekPlanning.OnDisposing.Add(_DayWeekPlanningDisposing);
};
function _DayWeekPlanningDisposing(oDayWeekPlanning, oArgs)
{
oDayWeekPlanning.OnContactViewChanged.Remove(_ContactViewChanged);
oDayWeekPlanning.OnDisposing.Remove(_DayWeekPlanningDisposing);
};
function _ContactViewChanged(oDayWeekPlanning, oArgs)
{
// oArgs:
// {
// Infoarea: "FI/KP",
// RecordId: "ValidRecordId",
// }
// ==> Custom Code to retreive the actual contact times
var oContactTime = GetContactTimeFor(oArgs.InfoArea, oArgs.RecordId);
//<== Custom Code
// oContactTime:
// {
// Monday:[{from: Controller.Collaboration.GetContactTime(9,0),
// to: Controller.Collaboration.GetContactTime(10, 0)},
// {from: Controller.Collaboration.GetContactTime(11, 0),
// to: Controller.Collaboration.GetContactTime(18, 0)}],
// Tuesday:[{from: Controller.Collaboration.GetContactTime(10, 0),
// to: Controller.Collaboration.GetContactTime(12, 0)}],
// Wednesday:[{from: Controller.Collaboration.GetContactTime(9, 0),
// to: Controller.Collaboration.GetContactTime(22, 0)
//}
oDayWeekPlanning.SetContactTime(oContactTime);
};
// hook the static "OnCreating" event of the DayWeekPlanning
//
Controller.Collaboration.DayWeekPlanning_OnCreating.Add(_OnDayWeekPlanningCreating);
OTC | Using the Serial Entry in a Generic Form

You can integrate the serial entry of the OTC ver tical into a Generic Form from SP4
on. Thus, you can e.g. create a page for easier visit documentation in your project
by combining an appointment plus the serial entries for Meeting CP and Sample.
The following steps are necessary to use the serial entry in a generic form (note:
the example provided relates to the Samples serial entry):
1. Create a JavaScript File with the initialization code.
// hook function called by the generic form
function InitSE(nMessage, nParam, elWindow, oForm)
{
if (nMessage == 0)
{
var oSE = new SerialEntryControl(elWindow)
var oParameters = {};
oParameters.DataPage = "bc.chSampleSerialEntry";
oParameters.LinkInfoArea = oForm.GetInfoArea();
oParameters.LinkRecordId = oForm.GetRecordId();
// same parameters as specified in the 'A_Sample' menu action for Samples
// for Meeting CP, use parameters from 'A_MeetingSPP'

oParameters.LinkId = -1;
oParameters.HasSubList = true;
oParameters.SearchId = "AR";

OTC | Using the Serial Entry in a Generic Form
oParameters.AutoSearch = false;
oParameters.HeaderType = "SerialEntry";
oParameters.HeaderName = "MUSerialEntry";
oParameters.MenuName = "M_Sample";
oParameters.FormName = "Sample";
oParameters.ShowSearch = true;
oParameters.SaveHandler = elWindow.SampleSerialEntry.OnSave;
oParameters.SelectChangeHandler =
elWindow.SampleSerialEntry.OnSelectChange;
oParameters.ListCustomData = "FilterType@+#Sample@+#SortOrder@+#None";
oSE.SetParameters(oParameters)
// add serial entry to DIV element (in this example named SETest)
var elContainer = elWindow.document.getElementById
(oForm.GetAddInfo(oForm.GetIdOfValueName("SETest")).Namespace);
oSE.Create(elContainer);
}
}
2. Add your JavaScript file to the controller scripts (either globally or – preferred –
using code).
3. Create a Generic Form (named SETest in this example), and call your initialization
function in the form’s Hook-Function: GetController().<Functionname e.g.
InitSE>(msg,param,window,form); . Add a DIV element to a form row, and adding
the Valuename used in the JavaScript code (in this example SETest ).
4. Add a menu action using the “ShowForm” page call where you call your newly
designed form. Make sure to include the file containing the serial entry Save
handler which is specified in the ‘Scripts’ parameter of the A_Sample menu action
for Samples (or the A_MeetingSPP menu action for Meeting CP) - Pages/bc/Sam-
pleSaveHandler.js (or Pages/bc/MeetingSPPSaveHandler.js ) - in the Scripts
parameter.

Conditional Formatting for Tree Views

The RecordTree provides an event OnNewTreeElement that is called for each node
before it is inser ted into the tree. This event allows you to modify labels, images
etc.
If you call the method SetReadFields for the RecordTree before creation, the server
returns the table caption and the fields read (i.e. the fields are available in the
event). Thus you can apply styles based on individual fields.
Using a hook for a client-side OnLoad event, you can also add these calls to the
standard TreeViewPage. There you can access the RecordTree control using tree-
ViewerObject.GetRecordTreeControl(); .
Example: The following steps are necessary if you want to display planned appoint-
ments in bold and missed appointments in grey italic font for an tree view that con-
tains appointments:
1. Create a file tree_test.js and copy it to the /ClientScripts folder.
2. Add the Javascript file to the parameter “Scripts” of the menu action’s A_Ex-
pandTree TreeViewPage page call.
3. Code the following in tree_test.js:

function OnControlBuilderFinished (controlBuilder, success)
{
tree = TreeViewerObject.GetRecordTreeControl();
tree.SetReadFields(true);
tree.OnNewTreeElement.Add(MyHandlerOnNewTreeElement);
function MyHandlerOnNewTreeElement(tree, args)

Conditional Formatting for Tree Views
{
if( args.TreeElement.InfoArea=="MA")
{
var record = new Controller.RecordControl (window,
args.TreeElement.InfoArea);
record.SetRecordId (args.TreeElement.RecId);
var statusFieldId=1;
record.SetFieldIndices([statusFieldId]);
/* Field 1 == "Status" */
record.Load(true);
var values= record.GetFieldValues();
if(values)
{
var statusValue = values[0];
if (statusValue==0)
/* scheduled */
args.TreeElement.SetHtmlLabel("<b>"+args.TreeElement.GetLabel()+"</b>");
else
if (statusValue==2)
/* missed */
args.TreeElement.CssClassCell="Tab_Must";
}
}
}
}
4. Check the results in the web.

Generalization/Specialization aka Virtual Info

Areas
Vir tual info areas may be used in client-created queries and filters, and with the
Record Control.
• Controller.g_oInfoAreas.ToGeneralInfoAreaId (infoAreaId) returns the physical
info area id
• Controller.g_oInfoAreas.EqualGeneralInfoAreas (infoAreaId1, infoAreaId2) returns
true if both info area ids belong to the same physical info area

4
Server-Side Programming Concepts
Introduction
The server par t of the application consists of several components, which are located
in different assemblies:
Component Description
name
mmObjects Contains the core Aurea CRM business logic including user han-
dling, database access, rights and more. It has no dependency
on the Aurea CRM Web component and has no access to the Aurea
CRM Designer database.
mmObjectsXX XX stands for BB, FS or BC and represents the ver tical implemen-
tation of mmObjects which it’s derived from.
mmUtilities Common utilities which can be used for all different kind of prob-
lems.
mmChannels Handles the channel output from the server to the client.
mmConfig Handles the access to the Aurea CRM Designer database.
update.web The web application itself. It uses all the above components.
While not mandatory, update advises you to use C# as the language of choice simply
because all the following server samples are written in C#. The next chapters intro-
duce the basic access the data via the business object, interpreting data from the
client and sending results to the client and later ways to customize your application
are described.
Note: mmSOI is also included in the SDK reference, but you can not use that with
Aurea CRM Web.

Chapter 4: Server-Side Programming Concepts
Including Custom Code in Aurea CRM Web

There are several ways to include server-side code in your custom Aurea CRM Web
solution:
• Include own ASPX pages either with C# code directly on the page or in code
behind. ASPX pages should be derived from base class update.web.Frame-
work.BaseWorkPage defined in the defined in the App_Code.dll - see Adding ASPX
Pages to Aurea CRM Web on page 131.
• Define your custom mmObjects sub assembly derived from the ver tical dependent
mmObjectsXX.dll, override its class factory and define your business object
extensions. Your assembly is made active by an entry in the Configuration xml –
this possibility is described in section Deriving Business Objects and Core on
page 122.
• Define custom fields by just modifying the custom fields xml (see section Custom
Fields on page 121)
• Define custom links by modifying the custom links xml – or extend mmObjects
business logic to implement complex custom links (see section Custom Links on
page 122)
• Define your own channel assembly, override Aurea CRM Webs standard channel
factory and add your own server channels. Your channel assembly is also activated
with an entry in the Configuration xml (see section Creating Custom Channels on
page 128).
The mmObjects assembly

This assembly is the core object for all business logic and communicates with the
Aurea CRM business logic code base in DLLs. So the main goal of the mmObjects
class library is to provide the existing business logic in an object oriented way. For
each ver tical there is a ver tical-dependent sub assembly – mmObjectsBB.dll,
mmObjectsFS.dll and mmObjectsBC.dll.
The most impor tant classes and interfaces of the mmObjects assembly are:
• The mmCore class is the root class of the mmObjects assembly holding
information about the data model and contains the business object factory. For
each application only one instance of this class should be created. Each ver tical
assembly has its own derived mmCore subclass – mmCoreBB, mmCoreBC and
mmCoreFS - all containing their own business object factory.
• The mmICoreContext interface (implemented by class mmCoreContext): The
core context is user- specific (and session-specific) interface to core functions –

you must have a valid login with a user name and password to get an instance
of mmICoreContext (the “core context”).
• The mmBusinessObject class is the base class for all business objects – it has
a fixed info area and either defines a template to query for data (having no record
id) or it defines exactly one record (having a record id). Instances of this class
are not created directly but from the object factory of the mmCore instance called
by the core context so that you get the corresponding subclass for the requested
info area.
• Instances of the mmCondition class define criteria to filter records. mmCondition
are created from an mmBusinessObject and have an internal tree structure defining
the filter that shall be applied when querying for data.
• The mmContainer class combines several mmBusinessObject instances with
defined relations to build a complex query.
In the following sections you will find detailed descriptions of these classes and
code samples how to use them.
Core and CoreContext

The mmCore object is main factory for the business objects – and there should only
be one mmCore object per application:
[C#]
mmCore oCoreInstance = new mmCoreBB();
XmlNode xmlNodeConfig=[…];
// get the mmCore configuration node
oCoreInstance.Initialize(xmlNodeConfig);
Note: Aurea CRM Web does not explicitly instance one subclass of update.web -
which subclass is used is defined by the configuration.xml (the type attribute of the
mmCore node). This subclass is created by the mmActivator class and Aurea CRM
Web passes the mmCore node of the configuration.xml file to the Initialize function:
<mmCore type="update.bb.mmObjects.mmCoreBB,update.mmObjectsBB">
[… configuration information …]
</mmCore>
Initializing the mmCore class is a rather costly operation, because it initializes some
data model information and does some consistency checks – if one of these checks
fails, the Initialize function will throw an exception – these initialization tasks are:
1. Initializing the log file
2. Initialize settings from the passed xml
3. Initialize possible error texts
4. Initialize the wrapper for the business logic DLLs – there is one wrapper per
ver tical and per database (Oracle and SQL).
5. Loads the meta info and checks its consistency.

6. Loads special needed user accounts from the configured UserData xml file – the
WWW user and the super user – and creates core contexts for those users (this
step will fail if the users do not exist in the Aurea CRM database or are not
correctly configured, or if the password information is incorrect. This file has to
be an encrypted and can be generated with the mmObjectsConfig utility which is
provided by update.
7. Initializes the custom fields defined by the custom fields xml
8. Initializes the custom links defined by the custom links xml
9. Creates the business object map and logs it to the logfile
10.Sets Logon Filters to customize the application logon process
11.Sets Event Handlers
If the configuration does not contain configuration data, default values are applied.
The CoreContext is a session-specific (and user-specific) interface to the mmCore
functions. To be able to access data you have to create a CoreContext. This object
ties all action with a user.
[C#]
mmICoreContext oCoreContext = mmPortal.Current.Core.CreateCoreContextInstance();
oCoreContext.Login("MyUser","
MyPassword",mmLanguages.Code.eng,LoginOptions.FullLogin);
…
oCoreContext.Logout();
Checking a User’s Credentials

If you want to perform an ad-hoc check of a user’s credentials (without going through
a complete log-in process), you can use the function
[C#]
// when using update.net.core
bool ISession.IsLoggedIn(Username,Password);
OR
// when using mmObjects
bool mmICoreContext.IsAuthenticated(Username,Password);
You can either supply the Aurea CRM user namer in Username (and the corresponding
password in Password ), or you can specify mmCore.AutoSignInUserPrefix+<Window-
sUserName> in Username and provide the user’s Wondows Domain in Password .
Note: To retrieve the record ID of a rep, use mmICoreContext.User.Representa-

tiveID .
If you want to call the credentials check via JavaScript, you can do so using the
following syntax:
[JavaScript]
var response = Controller.Xml.InvokeServerMethod("chAdministration", "IsLoggedIn",
{ userName:"<Name>", passWord:"<Pwd>" });
if (response.Success)
{

// ...
}
Business Objects and Conditions

An mmBusinessObject has two main functions: Either to represent exactly one record
from an Aurea CRM InfoArea or to act as a template for querying to database. All
mmBusinessObjects have a fixed InfoArea and are identified by their 64bit RecordId.
If you want to read data from the database you have to specify which fields you
want to get. This is achieved by setting the fields visible as shown in the next exam-
ple, which loads some data fields:
[C#]
using update.bb.mmObjects.BusinessObjects;
…
mmICoreContext oCoreContext = this.CurrentSession.CoreContext;
mmBusinessObject boCompany =
oCoreContext.CreateObject(InfoAreaIds.Company) as mmBusinessObject;
boCompany.RecordId = RecordId.FromInt64(1);
boCompany.SetVisible(mmCompany.FieldIds.Company);
boCompany.Read();
The field “Company” from the company with record id 1 was read. The content value
can now be accessed with the GetData and SetData methods.
The Update method modifies data of this record in the database:
[C#]
string sCompanyName = boCompany.GetData(mmCompany.FieldIds.Company);
if (sCompanyName=="update")
{
boCompany.SetData(mmCompany.FieldIds.Company,"New name of update");
boCompany.Update();
}
All values in the fields are strings; you can use some mmUtilities methods to get
the proper representation before storing into the database.
In some cases you will not have the id of the record for which you need data, so
you will need to use the mmBusinessObject instance with its second meaning – as
template for a query with some conditions.
The class mmCondition offers a simple solution to extend the mmBusinessObject
and using it as a template for searching. An mmCondition is tied to an InfoArea and
can only be used in conjunction with an mmBusinessObject of the corresponding
InfoArea. Basically an mmCondition compares a field to a value like “Last-
Name=Smith”.
[C#]
mmCondition oCondition = boPerson.CreateCondition(mmPerson.FieldIds.Lastname,
mmCompareOperator.Equal,"Smith
");
Use the Find method to get a collection with matching results. The found business
objects have those fields read, which were set visible in the template.
mmCollection aResults = boPerson.Find(10,0);

The variable aResults contains the first 10 matching companies (or less if there are
less than 10 matches).
[C#]
mmBusinessObject boFirstCompany = aResult[0] as mmBusinessObject;
Each business object in the result set has its RecordId set. Hence each result can
be used for fur ther actions.
If there are more results, you can specify the result set window by using the second
parameter of Find: nSkipRecords. This parameter tells Find to skip a number of re-
sults. To query the results 11 to 25 simply use the following statement:
[C#]
mmCondition oFirstCondition = boPerson.CreateCondition(mmPerson.FieldIds.FirstName,
mmCompareOperator.Equal,"John");
mmCondition oSecondCondition = boPerson.CreateCondition(mmPerson.FieldIds.LastName,
mmCompareOperator.Equal,"Smith");
mmCondition oCombinedCondition = mmCondition.LinkCondition(mmLinkOperator.And,
FirstCondition,oSecondCondition);
boCompany.SetCondition(oCombinedCondition);
mmCollection aResults = boCompany.Find(10,0);
As a condition retrieved from a business object only comparing a single field, it is

possible to combine two conditions resulting in a new more complex condition.
[C#]
mmCondition oCombinedCondition = oFirstCondition & oSecondCondition;
An alternate way to combine mmCondition instances is with operators “|” (for OR)
and “&” (for AND):
[C#]
mmBusinessObject boPerson =
oCoreContext.CreateObject(InfoAreaIds.Person) as mmBusinessObject;
boPerson.SetVisible(mmPerson.FieldIds.FirstName,mmPerson.FieldIds.LastName);
mmCollection aResults = boPerson.Find(mmBusinessObjectLink.From(boCompany),10,0);
Thus complex conditions can be create and applied to query the needed results.
Another way to get data is to use the build in data model. The data model describes
how business objects are linked to each other. For example persons are always
linked to one company. In other words there’s a 1:N relation between company and
person. To get the persons of a company the following code can be used:
[C#]
mmCondition oCondition = boPerson.CreateCondition(mmPerson.FieldIds.LastName,
mmCompareOperator.Equal,"A*");
boPerson.SetCondition(oCondition);
This query gets the first ten persons (first name and surname) of the company with
record id 1. It is possible to use both the template and the link in combination. So
getting the first ten person having a surname star ting with an A and are linked to
the company with record id 1 looks like:
[C#]

mmCondition oCondition = boPerson.CreateCondition(mmPerson.FieldIds.LastName,
mmCompareOperator.Equal,"A*");
It is also possible to use the link in the opposite direction to get the company of a
given person.
[C#]
boPerson.RecordId = RecordId.FromInt64(1);
mmCollection aResults = boCompany.Find(mmBusinessObjectLink.From(boPerson),1,0);
mmBusinessObject boCompanyOfPerson = aResults[0] as mmBusinessObject;
The link between two business objects can also be use for creating records, like
adding a person to a company:
[C#]
boPerson.SetData(mmPerson.FieldIds.FirstName,"Joe");
boPerson.SetData(mmPerson.FieldIds.LastName,"Average");
boCompany.NewChild(boPerson);
If you want to definie conditions on hierarchical catalogs, there are two possiblities:
[C#]
Prequisites:
int nParentCatalogId = ..., nChildCatalogFieldId = ...;
int nParentCatalogValue = ..., nChildCatalogValue = ...;
mmBusinessObject bo = ....;
Method 1:
bo.CatalogsAreNumeric = true;
bo.SetData(nParentCatalogFieldId, nParentCatalogValue.ToString());
mmCondition oCondProd = bo.CreateCondition(nChildCatalogFieldId,
mmCompareOperator.Equal,
mmCondition.FormatCatalogConditionValue(nChildCatalogValue));
Method 2:
mmCondition oCondProd = bo.CreateCondition(nChildCatalogFieldId,
mmCompareOperator.Equal,
mmCondition.FormatCatalogConditionValue(nChildCatalogValue,
nParentCatalogValue));

Containers
Even though the mechanisms of links and conditions already allow very complex
queries, it is sometimes necessary to operate with results containing different In-
foAreas like getting all persons who are working in a company with a revenue about
100k and haven’t been contacted this year. As this query can not be implemented
in one step with the introduced methods, mmObjects offers the mmContainer class
for complex queries with heterogeneous results.
In the previous section conditions were introduced and how to get homogeneous
results. If business object are linked they can be joined in a single query. For example
if you seek companies with revenue greater than 100k your code would look like
this:
[C#]
boCompany.SetVisible(mmCompany.FieldIds.Company, mmCompany.FieldIds.Country,
mmCompany.FieldIds.City);
mmCondition oCondition = boCompany.CreateCondition(mmCompany.FieldIds.Revenue,
mmCompareOperator.Greater,"10000);
boCompany.SetCondition(oCondition);
mmCollection aResults = boCompany.Find(10,0);
And if you need persons who were not contacted this year use the following code:
[C#]
mmCondition oCondition = boPerson.CreateCondition(mmPerson.FieldIds.LastContact,
mmCompareOperator.Less,"20040101");
mmCollection aResults = boPerson.Find(10,0);
Now it is possible to combine these two queries into a single one which returns the
persons not contacted this year and are from a company with more than 100k rev-
enue:
[C#]
boCompany.SetVisible(mmCompany.FieldIds.Company,mmCompany.FieldIds.Country,
mmCompany.FieldIds.City);
mmCondition oCondition = boCompany.CreateCondition(mmCompany.FieldIds.Revenue,
mmCompareOperator.Greater,"100000");
boCompany.SetCondition(oCondition);
mmCondition oCondition = boPerson.CreateCondition(mmPerson.FieldIds.LastContact,
mmCompareOperator.Less,"20040101");
mmContainer oContainer = mmContainer.With(oCoreContext,boCompany,boPerson);
mmCollection aResults = oContainer.Find(10,0);
Each item in the result set represents a result line containing business objects. The
first pair of this example can be retrieved in the following manner:
[C#]
mmCollection aFirstResultLine = aResults[0] as mmCollection;
mmBusinessObject boFirstCompany = aFirstResultLine[0] as mmBusinessObject;
mmBusinessObject boFirstPerson = aFirstResultLine[1] as mmBusinessObject;

Note that in this example a company may be found several times in the result as
each result line always contains a complete set of business object. The result can
be seen as a table.
While the example showed a container with two business objects, the container is
not limited by the number of business objects. It is not only possible to combine a
container with a business object but also join two containers. This offers a vast
number of all kinds of queries, which can executed with mmObjects.
Note: If the field ID’s are not defined they can be replaced with the index number
of the field (e.g. mmPerson.FieldIds.FirstName, 3). A list of the field numbers for
all info areas can be found in the Field Groups section of each info area in the de-
signer.
Dedicated Business Objects

All previous examples used the same mmBusinessObject interface, which is common
for all InfoAreas.
Some features are exclusive for one InfoArea, these are implemented in derived
classes like mmPerson. It contains methods like FindCurrent or ReadInterests which
are tied to this InfoArea. There are also differences between the ver tical versions,
so some InfoAreas are version dependent. In most cases the field indices vary.
Business Object Events

One of the key elements of customizing the applications to fit your own needs is
the possibility to alter the behavior of the business objects. mmObjects offers an
event driven mechanism to manipulate the data in cer tain occasions. The following
events are currently defined:
• PreUpdate
• PostUpdate
• PreRead
• PostRead
• PreFind
• PostFind
• PreNew
• PostNew
• PreDelete
• PostDelete
• ResolveRelation

To use one of these events you have to create a class which implements the
mmIBusinessObjectEventsHandlerV7 interface. The interface contains only two
methods:
[C#]
void RegisterEvents(XmlNode oNode, mmIBusinessObjectEventsV7 oEvents);
void UnregisterEvents(mmIBusinessObjectEventsV7 oEvents);
Use these to register and unregister your events like in this example:
[C#]
public class MyEventHandler : mmIBusinessObjectEventHandlerV7
{
public MyEventHandler()
{
}
public void RegisterEvents(XmlNode oNode, mmIBusinessObjectEventsV7 oEvents)
{
oEvents.PostRead +=
new EventHandler<mmBusinessObjectChangeEventArgs>(OnPostRead);
}
public void UnregisterEvents(mmIBusinessObjectEventsV7 oEvents)
{
oEvents.PostRead -=
new EventHandler<mmBusinessObjectChangeEventArgs>(OnPostRead);
}
public void OnPostRead(object sender, mmBusinessObjectChangeEventArgs args)
{
… Do something after Reading the object
}
}
The registered function has to match the following template:

[C#]
public void OnSomeAction(object sender, mmBusinessObjectChangeEventArgs args)
The args variable contains the business object on which the action is being carried
out and it can be manipulated as the user requires. It can be access using code
similar to the following:
[C#]
public void OnPostRead(object sender, mmBusinessObjectChangeEventArgs args)
{
mmCompany boCompany = (mmCompany)args.BusinessObject;
// set field Email1 to contain a new value
boCompany.SetData( mmCompany.FieldIds.E_mail1, “any_email@some_domain.com”);
}
So far no connection between the handler and the business object has been estab-
lished. The easiest way to accomplish this is to add a simple entry into the configu-
ration XML in the mmCore section.
<EventHandler>
…
<Event type="MyNamespace.MyEventHandler, MyAssembly" infoArea="FI" />
</EventHandler>
This entry automatically registers the event handler for the InfoArea Company during
the initialization of mmObjects.
Please remember that while simple and powerful, some events like PostRead for
Company or Person are raised very often and can cause performance issues if used
improperly.

Custom Fields
You can add custom fields to any InfoArea, should the free fields are not sufficient
enough. They behave like normal fields with the exception that they’re ignored when
loading or saving and that rights cannot be changed at runtime.
Note: Aurea CRM will log a warning if a field name in an infoarea is duplicated.
The warning will be in the following format:
Duplicated field name is found on info area 'XX'. Field name is 'XX' and field id is
'XX'. Please use unique xml names in your info area model.
Again adding a custom field is simply nothing more that inser ting a section into the
CustomFields XML.
<class name="KP">
<customfield index="305001" name="SpecialName">
<length>30</length>
<fieldtype>C</fieldtype>
<label>Spezieller Name</label>
<label language="1">Special Name</label>
<mustfield>false</mustfield>
<catalognumber>-1</catalognumber>
<catalogparentfield>-1</catalogparentfield>
<viewright>true</viewright>
<newright>false</newright>
<updateright>false</updateright>
<deleteright>false</deleteright>
<newcatalogright>false</newcatalogright>
</customfield>
</class>
Note: The following types are suppor ted:

• Character ('C')
• Shor t ('S')
• Long ('L')
• Float ('F')
• Date ('D')
• Time ('T')
• Boolean ('B')
You can use the Business Object Events on page 119 to read and store the values
of custom field in foreign databases or other applications.

Deriving Business Objects and Core

This section describes how you may build a derived class from mmCore and mm-
BusinessObject to extend business logic functionality of mmObjects and its base
DLLs. Depending on which ver tical solution you use derive a class from either
mmBBCore or mmBCCore or mmFSCore. Your class must override method Regis-
terObjects which defines which class shall be instanced for each info area.
Note: RegisterObjects is valid for V7 SP1, previously CreateObjectTypesMap was

used.
[C#]
public class MyCore : mmCoreBB
{
protected override void RegisterObjects()
{
base. RegisterObjects();
RegisterObject(InfoAreaIds.Person, typeof(MyPerson));
}
}
If an application instances class myCore instead of mmCoreBB, the framework will

use MyPerson instead of mmBBPerson for business objects of type Person, therefore
you can take full control over the person business object. MyPerson must implement
the whole interface of mmBBPerson so it should be derived from mmPerson:
[C#]
public class MyPerson : mmBBPerson
{
protected MyPerson(mmICoreContext oCoreContext,String sDefaultsName)
: base(oCoreContext,sDefaultsName)
{
}
// place your Business logic here
}
If you derive your business object class from a less specific parent class (like mm-
Person or even mmBusinessObject for persons), you will deactivate any business
logic that was and will be implemented in the standard implementation; so although
that is not forbidden – at least for the moment – it is highly recommended to derive
your business object classes from the most specific available parent class.
Custom Links
Important: As of Aurea CRM the preferred method of creating a Custom Link

between two info areas is using the generic data model for Aurea CRM. See the
Aurea CRM win Supervisor manuals for fur ther information.
Custom Links are a method of linking info areas together where no actual link exists
in the database model. This feature is used in the standard BTB version to implement
project hierarchies (where OJ records are put in a parent-child relation), but they
may also be used to define additional links between different info areas.

There are two ways to implement custom links:

1. Simple custom links that are defined by an amount of fields of one info area that
is copied to another, you can implement such generic links by changing the
CustomLinks.xml file.
2. Complex links may be implemented in a derived mmBusinessObject class.
The following example links an MA records as children to records of info area X3 –
that means that an X3 record may have several linked MA records (this custom re-
lation will have the name “$RelatedMA”) and each MA record may have one X3
record as parent (this relation will have the name “$ParentX3”). To implement this
link in the Aurea CRM database, we will copy the X3 key fields (4 and 5) to fields
37 and 38 of the MA record.
The definitions for this link in CustomLinks.xml would be as follows:
<update.net>
<infoArea infoAreaId="X3">
<customLink name="$RelatedMA" destinationInfoAreaId="MA">
<fieldMap sourceFieldIndex="4" destinationFieldIndex="37" />
</customLink>
</infoArea>
<infoArea infoAreaId="MA">
<customLink name="$ParentX3" destinationInfoAreaId="X3">
</customLink>
</infoArea>
</update.net>
To implement this link as complex link in derived subclasses of the mmBusinessOb-

ject class you have to implement and integrate your own mmObjects sub-assembly
as described in Deriving Business Objects and Core on page 122. You have to imple-
ment your own sub class for appointments implementing the parent link, and a sub-
class for X3 records implementing the child relation.
In the appointment sub-class you have to override the GetRelatedBusinessOb-
ject method that is responsible for custom links returning one related record defined
by an mmBusinessObject instance with a valid RecordId :
[C#]
public override mmBusinessObject GetRelatedBusinessObject(string sRelation)
{
if (sRelation == "$ParentX3")
{
int[] MAFields = new int[]{37,38};
int[] X3Fields = new int[]{4,5};
// read the values of the link fields from the child record
mmBusinessObject boAppointment = (mmBusinessObject) CreateInstance();
boAppointment.RecordId = RecordId;
boAppointment.SetVisible(MAFields);
if (boAppointment.Read())
{
// create a destination record with a condition defining the parent record

mmBusinessObject oDestinationRecord =
oCoreContext.CreateObject(InfoAreaIds.Info3) as mmBusinessObject;
mmCondition oCondition = oDestinationRecord.CreateCondition
(X3Fields[0],mmCompareOperator.Equal,boAppointment.GetData(MAFields[0]))
& DestinationRecord.CreateCondition(X3Fields[1],mmCompareOperator.Equal,

boAppointment.GetData(MAFields[1]));
DestinationRecord.SetCondition(condition);
// read all parent records (should be just one)
mmCollection colResult = DestinationRecord.Find(1,0);
if (null == colResult || 0 >= colResult.Count) return null;
// returning the resulting business object
if (colResult[0] is mmCollection)
return ((mmCollection)colResult[0])[0] as mmBusinessObject;
else
return colResult[0] as mmBusinessObject;
}
else return null;
}
return base.GetRelatedBusinessObject(sRelation);
}
In the X3 sub-class the child relation link has to be implemented by overriding

method GetRelatedBusinessObjectTemplate that returns a template business object
defining all related objects:
[C#]
public override mmBusinessObject GetRelatedBusinessObjectTemplate(string sRelation)
{
if (sRelation == "$RelatedMA")
{
// read the key field values of the source record
mmBusinessObject boX3 = CreateInstance() as mmBusinessObject;
boX3.RecordId = RecordId;
In the X3 sub-class
boX3.SetVisible(4);
boX3.SetVisible(5);
if (boX3.Read ())
{
// create the business object template

mmBusinessObject templateMA = oCoreContext.CreateObject(InfoAreaIds.Contact)
as mmBusinessObject;
mmCondition oCondition =
templateMA.CreateCondition(37,mmCompareOperator.Equal,boX3.GetData(4)) &
templateMA.CreateCondition(38,mmCompareOperator.Equal,boX3.GetData(5));
templateMA.SetCondition(oCondition);
return templateMA;
}
}
return base.GetRelatedBusinessObjectTemplate(sRelation);
Note: Please be aware that both types of links are only available within mmObjects
– and therefore are not available in most other applications of update as they are
not based on mmObjects. They will also NOT be available with Impor t/Expor t and
for the migration, so you should use these links only if you reviewed the business
case behind that and consider them really necessary. As these limitations are by
design, they will also exist with future versions.
However, you may configure Aurea CRM Web to create records that are custom-
linked (this is not done by a mmObjects feature but by the configuration of the New
page with Copy Fields), to configure parent (Expand Page) and child (Search-And-
List) navigation in context menus, to display this relation in tree views and dash-
boards, and to display this relation in sub lists of the Expand Page and the Search-
And-List page.

The mmConfig Assembly
The mmConfig Assembly

The mmConfig.dll may be used to access data from the designer database. The dll
consists of the following classes:
• The mmConfigurationConfig class that defines the designer configuration for
which data may be accessed – the configuration consists of the ver tical id (which
is fixed for a specific installation and defined in the Configuration.xml), the
configuration id (determined when the user logs on) and the language id.
An initialized instance of this class with the configuration for the current session
can be found in the session object:
[C#]
mmConfigurationConfig oConfiguration = this.CurrentSession.Configuration;
• The mmDesignerDBAccess class is the base class for all classes that have
ADO.net access to the web.designer database. This class contains static
connection information that is initialized from the settings in the Configuration.xml
file when the application star ts. The connection information consists of the
database type (Oracle ODP or SQL Server), an ADO connection string, an optional
file path with the information whether all xml configuration files shall be written
to this path (which slows down the application but is impor tant for tracing
information) or not, and the information whether data shall be loaded from the
database or from the file path.
• Several Xml loader classes which implement a method to load data from the
designer database and return an XmlDocument object. These loader classes are
internal and therefore inaccessible.
• The config class mmQueryConfig. This class uses the mmXmlLoader classes to
load data from the designer database into an xml structure and interpret this xml
to transform the data into a native structure.
If you want to load a Query from the database, you may just instantiate an mm-
QueryConfig class:
[C#]
mmQueryConfig oQueryConfig = new mmQueryConfig(sQueryName, sInfoArea,
nFormatType, oConfiguration);

This is not the recommended way to access such objects within the Aurea CRM
Web application because this would always result in an access to the designer
database – the recommended way is to use the get functions implemented in
the mmPor tal object. These functions use the standard application cache to cache
those objects so if a requested object was already loaded before, it is returned
from the application cache without any database access:
[C#]
mmQueryConfig oQueryConfig = mmPortal.Current.ConfigurationCore.GetQueryConfig
(sQueryName, sInfoArea, nFormatType, oConfiguration);
• The modification classes, all derived from the abstract base class mmDBModify.
Theses classes provide write access to some areas of the designer database
(List configuration with class mmDBModifyField, queries and filters with class
mmDBModifyQuery, analyses with class mmDBModifyAnalysis, Web Configuration
parameters with class mmDBModifyWebConfig and default user settings with
class mmDBModifyDefaultUserSettings). These classes automatically create sub
configurations on the demand if defined and invalidate par ts of the application
cache so that changes are immediately applied (at least as long as they are not
cached at client-side).
[C#]
string sExportType = oConfiguration["ExportType"];
To access Web Configuration parameters at the server there is no need to directly

use the mmConfig classes – there is a direct access via the mmConfigurationConfig
object which you can access via the session object (see above):
Aurea CRM Web Assembly and mmChannels

Assembly
This section describes possible extensions to the Aurea CRM Web assembly con-
taining the code behind for standard ASPX pages and suppor ting classes, and the
mmChannels assembly that implements the standard channels.
Both assemblies use the mmObjects assembly to access data from the Aurea CRM
database as well as the mmConfig assembly to access configuration information
from the designer database.
Aurea CRM Web uses server channels to communicate with clients. Server channels
are classes deriving from mmServierChannel. Even though Aurea CRM Web provides
a large number of predefined server channels it still may be required to
• Alter the behavior of an existing server channel using channel events.
• Create a custom channel.

Aurea CRM Web Assembly and mmChannels Assembly
Using Channel Events

Some channels offer hooks that allow custom code to monitor and/or alter parameters
and data transferred to and from the client. The hooks are implemented as .Net
Framework events. The following events are available:
Channel Event Name Description
chDetails PreRead Called before a record is read using its Id.
PostRead Called after a record has been read using its Id.
chList PostRead Called after the list data has been retrieved.
chRead- PreRead Called before a set of records is read using their Ids.
List
PostRead Called after a set of records is read using their Ids.
Channel events are similar to the events available in mmObjects. The main difference
is that mmObjects events are called on a lower tier and are therefore often not aware
of the context in which the application calls them. Channel hooks on the other hand
are raised at very specific locations within the application and therefore can leverage
all the information available at these locations.
Depending on what you are trying to achieve, both channel hooks and mmObjects
events may provide viable solutions. But keep in mind that mmObjects events are
usually called more frequently and therefore may be subject to performance problems.
The following code snippet shows how to hook event chDetails.PostRead:
[C#]
… // hook the channel event
chDetails.PostRead += chDetails_OnPostRead
…
void chDetails_OnPostRead(object sender, chDetailsEventArguments args)
{
…
}

Creating Custom Channels

In order to add a custom channel you need to create an assembly containing at
least the following 2 classes:
1. A class implementing the custom channel (see Implementing a Custom Match-
Up on page 102).
2. A class acting as a plug-in to Aurea CRM Web (see Creating a Plug-In to Register
Custom Channels on page 129).
Note: Previous versions of Aurea CRM Web provided another approach for
integrating custom. This approach involved the creation of a custom channel factory.
Due to the fact that Aurea CRM Web suppor ts only one channel factory, a race
condition can emerge from multiple plug-ins each requiring its own channel factory!
Whereas this approach is still available, we do not recommend using it for new
implementations.
Implementing a Custom Channel

In order to implement a custom channel you need to create a class derived from
mmServerChannel. The operations the channel should perform have to be added
as methods of this class having the attribute [ChannelMethod]:
[C#]
public class MyChannel : mmServerChannel
{
//[ChannelMethod]
public void SayHello(mmIChannelFeedWriter oWriter)
{
// use the writer to emit data from the channel
oWriter.Write("Say", "Hello, world!"
}
}
Channel methods can also have parameters:

[C#]
{
[ChannelMethod]
public void SayHelloTo(mmIChannelFeedWriter oWriter, string sName)
{
oWriter.Write("Say", string.Format("Hello, {0}!", sName));
}
}
On the client-side you can call this channel using the following javascript snippet:
[javascript]
XmlRequest.BeginInvoke(
"MyChannel.SayHelloTo",
// [channel name].[channel method name]
{ sName: "John Doe" },
// Parameters function(sender, args) { alert(args.Response.Say); });

Aurea CRM Web Assembly and mmChannels Assembly
If your channel method requires many or a variable number of parameters you may
also access the parameters using mmServerChannel’s proper ty “Params”:
[C#]
{
[ChannelMethod]
public void SayHelloTo(mmIChannelFeedWriter oWriter)
{
string sName = this.Params["Name"];
oWriter.Write("Salute", string.Format("Hello, {0}!", sName)}
}
}
As an alternative to attributing methods with [ChannelMethod] you can override

method OnFeed, which gets called every time a client requests data from the
channel:
[C#]
{
protected override void OnFeed(mmIChannelFeedWriter oWriter)
{
oWriter.Write("Say ", “Hello, world!”}
}
}
Clients can call channels overriding “OnFeed” using the following JavaScript snippet:
//[javascript]
var oChannel = OpenChannel(window);
oChannel.SetData("Name", "John Doe");
oChannel.Submit(OnComplete, "MyChannel", null);
...
function OnComplete(elWindow, oChannel)
{
var oResponse = oChannel.GetResponse();
alert(oResponse.Say);
}
Creating a Plug-In to Register Custom Channels

Before a custom channel can be used by clients, it has to be registered with the
channel factory. Registration of custom channels can be performed during the ini-
tialization phase of plug-ins.
To create a plug-in you need to create a class that implements interface up-
date.web.Framework.mmIPluginEx .
//[C#] using update.web.Framework;
...
class MyPlugIn : mmIPluginEx
{
public void Load(mmPortal portal, XmlNode nodeConfig)
{
// this method gets called by the framework during the early stages
// of the startup, therefore most of the properties on "portal" are // not yet
initialized (e.g. property "ServerChannelFactory" has not // been initialized yet
but is null)
// note: nodeConfig points to XML element <PlugIn />
}
public void Unload()
{ … }
}

In order to have your plug-in loaded during the star tup of Aurea CRM Web, you have
to register it in the <Plugins> section of the <mmPortal> section in Configuration.xml
using the syntax <PlugIn type="TypeName,AssemblyName"/> :
...
<mmPortal>
...
<Plugins>
...
<Plugin type="MyPlugInNamespace.MyPlugIn,MyPlugInAssembly"/>
...
</Plugins>
...
</mmPortal>
...
Once configured, Aurea CRM Web will attempt to load the plug-in and call its method
“Load”. At the time Aurea CRM Web calls method “Load” the channel factory has
not been created yet, therefore we need to defer the registration of the custom
channel to the time when Aurea CRM Web has been fully initialized. This can be
done by registering an event handler for mmPor tal’s “Initialized” event as shown
below:
//[C#]
using update.web.Framework;
...
class MyPlugin : mmIPluginEx
{
public void Load(mmPortal portal, XmlNode nodeConfig)
{
// This method gets called by the framework during the early stages // of the
startup, therefore most of the properties on "portal" are // not yet initialized
portal.Initialized += OnPortalInitialized;
// note: nodeConfig points to XML element <PlugIn />
}
...
private void OnPortalInitialized(object oSender, EventArgs oArgs)
{
// Now that mmPortal is fully initialized, you are able to // register your
custom channel(s)
mmPortal portal = (mmPortal)oSender;
// portal’s property "ServerChannelFactory" now points to the // channel factory
// register your channel(s)

portal.ServerChannelFactory.RegisterChannel( “myChannel”, typeof(myChannel);)
portal.ServerChannelFactory.RegisterChannel( “chSomeOtherChannel”,
typeof(SomeOtherChannel);)
// note: registering a channel with an existing name will replace // its
implementation.
...
}
}
You can register as many channels you want. If you choose to register a custom
channel with the same name as an existing channel, your channel will replace the
existing channel.
Note: The class mmServerChannelFactory also provides the events "ResolveName"

and "ResolvingName" that can be used to replace/add custom server channels.

Adding ASPX Pages to Aurea CRM Web
Adding ASPX Pages to Aurea CRM Web

To integrate your own server pages you have to add it in the Aurea CRM Designer
using the Page Designer. If you want to use the infrastructure of Aurea CRM Web,
the page class should be derived from class BaseWorkPage. It checks the login,
offers access to the mmSession and the mmPor tal instance. You can use the param-
eter conversion tools as well:
//[C#]
[PageParametersAttribute]
public class MyPage : BaseWorkPage
{
[PageParameterAttribute (Name="MyStringParameter")]
protected string _myStringParameter;
…
}
Please refer to the Developer Reference for Details on class BaseWorkPage and
underlying suppor t classes of the Aurea CRM Web assembly and the mmObjects
assembly.
Generalization/Specialization aka Virtual Info

Areas
For details on the concept of vir tual info areas, see the Aurea CRM Web Adminis-
trator Guide. Available functions in mmICoreContext :
• GetGeneralInfoAreaId (string vir tualInfoAreaId): returns the physical info area id.
• GetSpecialInfoAreaId (string physicalInfoAreaId, RecordId recordId): returns the
vir tual info area id of the current record (equal to the physicalInfoAreaId if no
vir tual data model is defined).
Available functions in mmBusinessObject :
• InfoAreaId now always returns the special info area of the current record (except
if the content is built in the code and not by a read process), and InfoAreaIndex is
a table index > 10000 (if InfoAreaId is a vir tual info area).
• If the proper ty DynamicResultInfoArea is set to true (default) on container business
objects, the result business objects will have their actual info area; if set to false,
they will have the explicitly specified info area.
• The static function mmBusinessObject.ToPhysicalInfoArea(bo) returns a clone
of the business object
• bo with the physical info area (no condition, but with visible fields).
• PhysicalInfoAreaId and PhysicalInfoAreaIndex always return the physical info
area.

A vir tual info area is by default mapped to the same type as its physical info area.
That means that a vir tual info area based on “FI” is mapped to mmBBCompany , not
to mmBusinessObject . It is possible to define an explicit subclass of mmBusinessOb-
ject for vir tual info areas.

5
Other Programming Concepts
This chapter provides you with information of some special customisation and de-
velopment topics.
Creating a Custom Cascading Style Sheet

In order to change the color schema of Aurea CRM Web you need to create new
cascading stylesheets (CSS).
The colour schema provided out of the box with Aurea CRM Web is called "update"
and consists of the following files:
A set of CSS files located in "web\styles\update\*.css" A set of images located in
"web\images\update\*.gif"
To star t with your own color schema we recommend creating a copy of the "update"
schema.
e.g. to create a new colour schema named "gold" you would create two new direc-
tories "web\styles\gold" and "web\images\gold" and copy the contents of the existing
directories "web\styles\update" and "web\images\update " into them.
After that you could star t modifying the copied CSS files in order to match you cor-
porate identity. However you should be careful when changing font sizes, since this
can easily break the layout of Aurea CRM Web!
For changing the images software capable of editing GIF images is required. You
could change the contents of the images to whatever you like, but again we do not
recommend changing their dimensions.
Finally, to enable your new colour schema you will need switch to Aurea CRM De-
signer. There you will have to
• Add the name of your new colour schema to the textgroup "styles_text".
• Add the stylesheet to the list in "Modify Styles" (located in section "Customize").
After invalidating the Aurea CRM Designer cache in Aurea CRM Web, users should
be able to select the new color schema as a display style in their user configuration
settings.

Chapter 5: Other Programming Concepts
XML Exports & Reporting

The Aurea CRM Web repor ting engine uses XSL transformations together with the
existing XML expor t functionality of Aurea CRM Web to provide flexible repor ting
functionality.
Aurea CRM Web knows three different types of XML expor ts each with its own XML
schema:
• List … a list of records (usually the result of a search & list page or a query)
• Details … details about a single record (based on a field group)
• Tree … a hierarchy containing the table captions for a set of linked record (based
on a tree view configuration)
In addition lists can be expor ted using two different XML schemata
• Aurea CRM Web schema (default)
• Aurea CRM win schema (aka fat client compatible)
For PDF repor ts, the KB ar ticle "HOWTO use the repor ting PDF plug-in" at
https://suppor t.aurea.com provides fur ther information on the PDF plug-in’s features
and usages, including information about transformations and configuration.
Notes on Generated XML Output

The tag <LocaleVersion/> containing the current regional settings (like data format,
decimal separator, time zone etc.) are always emitted in the beginning of the XML
document (with SP4 or later) to make processing and formatting of values easier.
The value of date, time, Boolean, shor t, long and float fields is emitted in invariant
format (in the attribute
value ) as well as in display format.
Note: If EmitNativeFormat is specified, the output has changed with SP4: fields of
type date will no longer contain a time por tion, fields of type time will no longer
contain a date por tion, and Boolean fields are now emitted as “t” and “f ” instead of
“true” and “false”.
Empty fields are emitted as <field…/> .

Catalog fields contain the numerical value (in the attribute catval ) as well as the
text value e.g. <field tableshort="FI" fieldno="5" fid="5" catval="20">Aus-
tria</field>

Export Options Reference
Export.Encoding
UTF-8 … the expor t will be encoded using UTF-8.
UTF-16 … the expor t will be encoded using UTF-16.
Note: The name of any encoding suppor ted by the .NET framework can be used
here.
Export.ContentDisposition
inline …Microsoft Internet Explorer will try to display the repor t results in the current
browser window.
Note: Not all content types can be displayed inline
attachment (default)… Microsoft Internet Explorer will ask the user to save the repor t
results or open them in a separate window.
Export.Xml.FatClientCompatible
true … XML Expor t uses an Aurea CRM win compatible schema.
false (default) … XML Expor t uses the Aurea CRM Web schema.
Export.Xml.EmitConfiguration
true … the XML element <Configuration/> containing the configuration (e.g. of the
Field Group or the Tree View) will be included with the XML expor t. This allows
formatting a repor t’s output based on the Field Details in the field group.
false (default) … no configuration data will be included with the XML expor t.
Export.Xml.EmitNativeFormat
true … all expor ted field values will be formatted in an XML compliant format:
Field type Formatting
Date YYYY-MM-DD
Time HH:MM
Time (with seconds) HH:MM:SS
Time (with milliseconds) HH:MM:SS.TTT

Boolean t or f
Other field types No special formatting will be applied.
false (default) … all expor ted field values will be formatted according to the users'
locale settings (stored as Web Configuration Parameters in the user’s configuration).
Export.Xml.EmitInvariantFormat
true … all expor ted field values will be formatted using Aurea CRM’s internal culture
invariant representation.
Field type Formatting
Date YYYYMMDD
Time HHMM
Time (with seconds) HHMMSS
Time (with milliseconds) HHMMSSTTT
Boolean 1 or 0
Other field types No special formatting will be applied.
false (default) … all expor ted field values will be formatted according to the users
locale settings (stored as Web Configuration Parameters in the users configuration).
Export.Xml.EmitCatalogs
true … the XML elements <Catalogues/> and <Languages /> will be included with
the XML expor t.
<Catalogues> contains all values of all catalogs used in the expor ted data. The
catalog values will be included in 2 languages: the user’s catalog language and the
catalog base language. The core catalog IDs are also emitted.
Information about the fixed catalogs used in a repor t is emitted in an XML node
analogous to variable catalogs (with the difference that values of fixed catalogs are
output only in the current language).
false (default) … no catalogs will be included with the XML expor t.
Export.Xml.EmitConditions
true … when expor ting query results, this options will include the conditions (=filters)
used when executing the query. The filters will be emitted in XML element <Condi-
tions/> . Variable conditions like $curDay, $curRep etc. are replaced with their ac-
tual value.

false (default) … no conditions will be included with the XML expor t.
Export.Xml.EmitLinks
true … for every record, a hyperlink and a title for this link will be included with
the XML expor t. The titles are formatted using the default Table Caption for the
record’s info area, e.g.
<field_link tableshort="FI">http://.../ </field_link>
<field_ref tableshort="FI">update Software AG</field_ref>
Note: Expor ting hyperlinks for a large number of records can significantly increase
the amount of time your repor t requires for processing. update thus suggests only
using this option if it is really required.
false (default)… no hyperlinks will be included with the XML expor t.
Export.Xml.NamesOption
Short … the emitted XML will contain shor ter XML-attribute and –tag names. If your
repor ts get very large, this options helps to reduce the document size (but has the
disadvantage that the XML is much less readable).
Every other value than Short will result in the default names being used.
Important: The standard XSL transformations delivered with Aurea CRM web
do not work when this option is enabled.
Default Name Short Name Default Name Short Name
tables ts extKey e
table t catalogs cs
tableshor t tsr catalog c
prefix p parCatVal pcv
recid ri parCatNo pcn
tablename tn langid li
fields fs field_link fl
field f field_ref fr
fid fi value v

Default Name Short Name Default Name Short Name
fieldname fnm type t
fieldlength fl mnr mnr
fieldtype ft fieldlabel fl
catNo cn tablelabel tl
catVal cv sor tnr sn
Export.Xml.Variables
true … the XML element <Variables/> will be included with the XML expor t. <Vari-
ables> contains all the variables that are valid for the currently logged in user.
false (default) … no variables will be included with the XML expor t.
Export.Xml.EmitCoreFieldIndices
true … an attribute fidcore (shor t notation: fic ) containing the “core” field number
is emitted in the XML for the <row/> and <fields/> tags. The “core” catalog ids are
emitted as well. The “core” info area shor tcuts tableshortcore are also emitted to
allow the creation of core repor ts.
Export.Xml.EmitOnlyCoreFields
true … only fields having a “core” id will included in the XML. The “core” info area
shor tcuts
tableshortcore are also emitted to allow the creation of core repor ts.
Export.Xml.EmitPhysicalInfoAreaIds
Relevant if you use Generalization/Specialization aka Vir tual Info Areas
true … the expor ted XML always contains the physical info area id.
false (default) … the expor ted XML contains the actual info area id, which would
be the vir tual info area id if applicable.
Example for EmitPhysicalInfoAreaIds false (default XML expor t):
<field tableshort="VDOC" tablename="Doctor" fieldno="2" fieldname="Company"
…>
Example for EmitPhysicalInfoAreaIds true:

<field tableshort="FI" tablename="Company" fieldno="2" fieldname="Company"
…>

Note: If you want the same settings for all repor ts, but do not want to specify this
parameter every time, you can also create a Web Configuration parameter of type
“character” named Export.Xml.EmitPhysicalInfoAreaIds and define its value
as true.
Note: Not every combination of options presented here is actually meaningful -

e.g. expor ting catalogs for a tree view does not make sense, because a tree expor t
contains table captions only and no catalog fields.
5.2.2.1 Export option availability

The following matrix shows which expor t options are available for the various expor t
types:
How to Set Export Options

Repor ts and expor ts are star ted using a direct button configured in Aurea CRM
Designer or using JavaScript code.
Setting Export Options using Direct Buttons
For expor t you have to create a direct button whose name star ts with “Direct Expor t”,
for repor ts your direct button’s name has to star t with “Direct XslRepor t”.

You have to select a page call of type “Custom” for the direct button. This page call
has one parameter named Custom which will contain all your expor t options.
For XML expor ts, the options are to be formatted as a comma separated list of
key/value pairs using the syntax
Key=Value, e.g. Export.Xml.FatClientCompatible=true,Export.Xml.EmitCata-
logs=true
For XML repor ts, the options have to be enclosed in square brackets and the Custom
field star ts with the name of the XSL transformation, e.g. ExportListHtml[Export.En-
coding=UTF-16] .
Note: If the button “Direct XslRepor t Excel” is used and it contains the
parameter EmitXmlNativeFormat=true , data types are correctly mapped from Aurea
CRM to Microsoft Excel: numerical fields (long, shor t, float) are mapped to ‘Number’
in Excel, date fields to ‘DateTime’ and logical fields to ‘Boolean’. All other types of
fields are passed as strings (also time fields, since Excel’s XML format does not
suppor t time without date).
The “Custom” page call, which can be used to generate a parameterized repor t from
the QueryRun page, also suppor ts the complete repor t object instead of just the
repor t name, for example
{XslTransforms: "ExportCSV", Caption: "some heading text", ExportFatClient-
Compatible: true, ContentDisposition: "inline", Target: "WorkFrame"} .
The XSL transformations are - by default - stored in the web installation’s directory
in /Data/Reports/XSLT/ .
The location of the directory can be changed by adding the following elements
(marked bold) to your
<update.net>
...
<mmPortal>
...

<mmReports>
...
<XSLTPath>Data/Reports/XSLT</XSLTPath>
...
</mmReports>
...

By default the XSL transformations will be loaded on first use and cached from then
on. While developing new XSL transformations this can become cumbersome, be-
cause Aurea CRM Web would have to be restar ted for each change to the XSL
transformation. Therefore the XSL transformation cache can be turned off using the
following element (again marked bold and located in "Configuration.xml"):
<update.net>
...
<mmPortal>
...

<mmReports>
...

<CacheXslTransforms>False</CacheXslTransforms>
...
</mmReports>
...
There are no constraints on the XSL transformations you create for XSL repor ting,
as long as they are valid transformations according to the W3C XSL Transformations
(XSLT) Version 1.0 recommendation located at http://www.w3.org/TR/xslt
However, you should add a "media-type" attribute to your <xsl:output> element.
Aurea CRM Web will look for this attribute and modify the content-type of the HTTP-
Stream sent to the client (Microsoft Internet Explorer). Without setting the media-
type the OS on the client-computer will not be able to determine the correct applica-
tion for opening the repor t.
<xsl:output method="xml" encoding="UTF-8" media-type="application/msword" />
Note: The media-type will also be used to alter the file extension of the filename
transferred to the client. For security reasons the client-application (Microsoft Internet
Explorer) will use the file extension rather than the HTTP content-type to determine
the application used to open a file. As a result all content-types and file extensions
must be known (hence entered into the registry) to your Aurea CRM Web server.
Setting Export Options using JavaScript Code

Similar to setting custom repor t options for direct buttons, these options can also
be set when creating repor ts using custom code.
Repor ts can be executed using method Export provided by the QueryControl ob-
ject. Export takes an object as its first parameter – this object is used to specify
all aspects involved in executing a repor t (including repor t name, maximum number
of records, etc.). The attribute Action of this object can be used to specify the repor t
options formatted as <OptionName>=<OptionValue>,<OptionName>=<OptionVal-
ue>,... e.g. Export.Xml.FatClientCompatible=True

The following code sample sketches how to execute a repor t named “MyCustomRe-
por t” on data returned by the public query “MyQuery”. Please note that the repor t
option FatClientCompatible is set to True using attribute Action .
var oQuery = new Controller.QueryControl(...);
oQuery.SetQueryName("MyQuery", false /* false for public queries */);
// load the query using LoadQueryDefinition(...)
// skipped for clarity
// prepare the report options
var oExport =
{
MaxResults: -1 // include **ALL** records in the result
,Export: { Type: "XML" // the export should emit XML
,Params: { XslTransforms: "MyCustomReport" } }
// we want fat-client-compatible XML export format
,Action: "Export.Xml.FatClientCompatible=True"
};
// finally execute the report
oQuery.Export(oExport);
Depending of what you want to expor t (search & list, query, details, tree view), the
JavaScript code required to perform the expor t differs.
The Aurea CRM Web SP4+ installation includes a sample page samples/ex-
port.html that demonstrates how the various types of expor ts can be initiated using
JavaScript code.
How to Create Reports from Multiple Queries

This section outlines how to execute multiple queries and create a repor t from the
results using an XSLT transformation.
First you will have to create a custom server channel that roughly performs the fol-
lowing actions:
// execute all queries /* for each query you want to include in the report */
{
/* Load the Query */
result[i] = /* Execute the Query */
}
// create the XML
XPathDocument doc = new XPathDocument();
using( XmlWriter writer = doc.CreateNavigator().AppendChild() )
{
writer.WriteStartElement("MyReport");
/* for each query result */
{
/* Write result[i] to writer; */
}
writer.WriteEndElement();
}
// transform the XML and write the response to the HTTP response stream
XslCompiledTransform transform = /* Load XSLT; */
transform.Transform(doc.CreateNavigator(), null, httpResponse.Output);
// note: you might want to set the content type on the httpResponse so that
// the browser knows what to do with it!
On the client-side you call the channel as usual, with one simple twist (the additional
call of SetAutoClose):
var channel = Controller.OpenChannel(window);
channel.SetData(....) channel.SetAutoClose(true);
// tell the channel to leave result processing to the browser
channel.Submit(null, "chMyReport", null);

Directly Calling a Report for a Query

There are two methods for opening a repor t for a query directly without the need to
display the results data first:
1. Use the JScriptCall page call with the method QueryControl.Report or QueryCon-
trol.ReportLinked .
You can specify the following in the „Additional Parameters“ (values except
Booleans need to be enclosed by double quotes, values are separated by colon):
• queryName
• isPrivateQuery (true or false)
• repor tName
• contentDisposition (optional)
• target (optional)
• expor tFatClientCompatible (true or false) (optional)
• tableCaption (optional)
Example: To call a MS Word repor t from a company that contains all persons of
the company plus their main interest, you’d use:
Function QueryControl.ReportLinked, InfoArea Record,
Additional Parameters "KPs_in_FI",true,"ExportListWordml"
2. You can influence the text and behavior of the “Execute” button for parameterized
queries:
• In the „QueryRun“ Page Call, specify the name of the desired Direct Button in
the AlternateExecuteDirectButton parameter (e.g. Direct XslReport Excel to
directly star t an MS Excel expor t when the user clicks on “Execute”)
• In Generic Forms, provide the name of the desired Direct Button by
providing ExecuteButton(<button name>) in the “Option” column (e.g. Execute-
Button(Direct XslReport Excel) ).

Note: This setting is ignored for queries that do not contain parameters (i.e. such
queries are simply executed ‘as normal’ and the results list displayed).
Displaying win Reports & Diagrams in web

When calling a win repor t or a diagram in web, the corresponding XML is generated
by the core logic of Aurea CRM, but any transformations with style sheets are done
by Aurea CRM Web. Thus it is necessary that all required style sheets - including
XSL files stored as Aurea CRM documents - are available in the Data\Re-
ports\XSLT\ directory on the web server (i.e. you need to manually copy the files
there).
The page call for executing win repor ts and diagrams is ExecuteReport. You can
specify the following parameters:
• Name (mandatory): the name of the repor t or diagram format
• InfoArea (optional): allow you to specify an input record for the repor t/diagram
(note: you need to set InfoArea even if you have already defined that your repor t
needs an input record in the format itself).
• Parameters (optional): additional parameters passed to the repor t in a JSON
structure (see below for details)
• Flags : provide 0 for a global format (default), 1 for a private format.
Examples for valid parameters are
• {XslTransforms: '<transformation name>'} to apply an additional transformation
at the end (after a transformation defined in the format was performed)
• Only the Target, ContentDisposition and FileName expor t parameters known
from web repor ts are suppor ted (options like EmitConditions need to be set directly
in the format); use e.g . {ExportParams:{Target: 'myIFrame'}} to open the repor t
in the provided Iframe.
• By default, the following parameters are passed from Aurea CRM Web to the XSL:
• Style (“update“)
• Stylesheet (“ update.css “)
• Stylesheet (full URL to the repor t style sheet e.g. “ http://my-
web.com/web/styles/update/report.css ”)
• ImagePath (the web’s image path: “../images/update/”)

• imagepath (full URL to web images e.g. “http://myweb.com/web/images/update/”.)
• ImageFolder (full path to XSLT\images e.g. “ c:\my web Installation\web\Da-
ta\XSLT\Images ”)

Displaying win Reports & Diagrams in web
These parameters cannot be modified directly in the XSL, but can be overridden by
the format definition or by parameters of the page call e.g. by providing {stylesheet:
'<style sheet name>'} . Parameters provided via the page call always take prece-
dence over parameters defined in the XSL or in the format.
Note: If your repor t format has the “Output link” option checked, you need to make
sure that the Configuration (MC) entry for “Links | web URL” is filled accordingly.
You can control whether a repor t is generated only in memory or as a file (in
web.data\session\repor t.xml) by defining these Web Configuration parameters:
• ReportMemoryThreshold (type: Character): defines the maximum size in KB that
is used for in-memory generation (default: 256 KB)
• ReportAlwaysInMemory (type: Boolean): if checked, a repor t is never generated
as a file (and when a repor t exceeds the limit specified in ReportMemoryThreshold ,
the repor t creation is abor ted with an error message).
Compared to repor ts running in Aurea CRM win, the following restrictions apply in
Aurea CRM Web:
• The placeholders $userdir and $installDir cannot be used.
• The style sheets always need to be located in Data\Repor ts\XSLT.
• You cannot use variable conditions in the transfer field format.
• The “Save as file” option is not suppor ted (repor ts in web are always executed
synchronously and the displayed).
• The “Save transformation to file” options are not suppor ted.
• The “Transfer to spreadsheet” options are not suppor ted.
• The creation of PDF repor ts as described in the Aurea CRM win User manual
(chapter “PDF Repor t”) is not suppor ted.
• If the XslTransforms parameter is set in the page call, the provided transformation
is always applied last.
The ExportParams parameter does not suppor t any EmitXX options, these need to
be set directly in the format.

AureaCRM - Web DeveloperGuide 13.3

Uploaded by

Copyright:

Available Formats

You might also like

AureaCRM - Web DeveloperGuide 13.3

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

AureaCRM - Web DeveloperGuide 13.3

Uploaded by

Copyright:

Available Formats

CRM Web Developer Guide

Chapter 2: Advanced designer Customizations.....................................10

Chapter 3: Client-Side Programming Concepts.....................................32

Chapter 4: Server-Side Programming Concepts..................................111

Chapter 5: Other Programming Concepts.............................................133

• About this documentation

About this documentation

[ ] Brackets enclose optional arguments.

Aurea global support

Each Generic Form has the following attributes:

Note: “Steps (Tabbed)” is currently not implemented in Aurea CRM web.

• Description: A description of the form, visible only in Aurea CRM designer.

• MenuLink to display a link that executes a menu action.

• SubAnalysis for a special Generic Control displaying an analysis that is dependent

Form Cell Attributes

Note: Repetitive forms are not implemented in Aurea CRM web.

The autostar t(<0|1) parameter defines whether the query is automatically

• For Analysis, nocontroller suppresses the display of an analysis controller which

If not explicitly defined, autostar t is turned off in case a controller is displayed.

Combo Box Values / Combo-Data-Functions

• Combo-Data-Functions returning Formats:

• Combo-Data-Functions returning Data Model Information:

• Combo-Data-Functions returning Web Configuration Parameters (used to display

• Combo-Data-Functions returning XML data:

Dependent Catalogs using Combo Boxes

Value Name Func parameter

Value Name Func parameter

RowGroup and TabGroup

• A TabGroup displays a tab control. Each of the following rows is placed in a

Generic Form definition:

Using Forms within Wizards

Generic Form Controls

corresponding Web Configuration parameter in the "Func" column. By default,

The following settings can be defined in the “Options” columns of FormOrgTreeCon-

• DisableCheckChildren : If false , the check whether the rep has subordinates is

The frameset contains the following 3 frames:

The JavaScript code for implementing a request might look as follows:

function MyCallbackFunction(elCallerWindow, oChannel)

Adding Client Code to the Application

Client Code Structure

Controls and the Control Builder

2. Let the Control Builder build the controls automatically.

Hook for client-side OnLoad Event

Example for testing these functions:

For another example using OnControlBuilderFinished , see also Conditional Format-

Information about Application, Session and Current User

g_sCurrentRepID … the Id of the current representative.

Information about Formatting

Information about Web Configuration Values

Information about Page Definitions

Information about Info Areas

Information about Images

Language Dependent Texts

update software AG | Operngasse 17 - 21 | A-1040 Wien | Austria Page 26

Controls for Accessing Server Data

Create a New Record

Load Data from an Existing Record

Update an Existing Record