Helpdesk Customization Guide

Transcription

1 Table of Contents Helpdesk Customization Guide Helpdesk Customization Guide... 1 Table of Contents... 1 A few words about customizing Helpdesk and best practices... 2 Customization use cases... 3 Should I override a command or the file alias of the template that implements the command?... 3 Overriding a command... 3 Overriding a file alias... 4 How to override a command... 5 Prerequisites... 5 Solution... 5 How to leverage existing functionality by overriding a template file alias... 6 Prerequisites... 6 Solution... 6 How to create your own custom console... 7 Prerequisites... 7 Solution... 7 Debug and Test your customizations... 9 How to add a scalar field... 9 Prerequisites... 9 Solution... 9 Debug and Test your customizations How to add lookup field Prerequisites Solution Debug and Test your customizations How to centralize all of your custom strings for ease of management and localization Prerequisites Solution Debug and Test your customizations Database Tables Views Stored Procedures... 19

2 A few words about customizing Helpdesk and best practices Helpdesk pages are developed using AppWeaver, an application development platform that provides a number of features designed to support very lightweight User Interface development with an eye toward easy customization and maintenance. AppWeaver provides services and controls that allow development of fairly complex pages with a minimum of markup and coding. AppWeaver basically extends the capabilities of ASP.NET, so a firm grasp of ASP.NET page fundamentals and how server-side web controls work is very important. We recommend finding a good book (Microsoft Press and Wrox both have a good selection) on developing for ASP.NET before attempting any serious customizations. Most AppWeaver controls are simply derived from standard ASP.NET controls. In addition to the standard properties provided by the base controls, AppWeaver controls also offer the following: Automatic localization. All display text (text, tooltips, labels, entries, etc.) is rendered in the current culture of the browser (assuming resource assemblies or custom XML string files have been provided for that culture code). Resource libraries can be searched in preferred order, allowing for easy string override. Cooperative layout. When contained within a Layout control, these controls negotiate for space (according to attributes set in the Layout control) and position themselves dynamically. This allows pages to specify controls in a flat markup stream without having to position them absolutely and inject new controls into the page where they will be dynamically integrated into the layout. Critical for Helpdesk s upcoming UI-based customization features. Takes care of labeling and column margins without having to spec them in markup. Two-way databinding. ASP.NET provides one-way databinding where data is moved from a datasource into form controls. Two-way databinding copies data out of the form controls and back into the original datasource where it can be immediately committed. Inherited data sources. Databound controls look up the ancestor hierarchy for data source specifications. Cleans up the markup by allowing datasource specifications to be made at a container level rather than on each control (explicit specification on any control always overrides any ancestor specifications). This is especially useful for property pages where multiple controls are bound to a single dataset. Inherited modality. Controls can be console modal or disabled on an entire page to simulate a modal console display. AppWeaver also has several custom controls that you will encounter in Helpdesk page templates. The Layout control (mentioned above), the MultiPage and PageView controls, and the WebGrid. Unlike most typical ASP.NET applications, Helpdesk utilizes a coding approach that can be called code in front (as opposed to the code-behind strategy used by most ASP.NET applications). This means that the pages that implement the Helpdesk User Interface are installed with their source-code exposed in the same template file with their markup (they are compiled by ASP.NET just in time ) and are therefore ideally suited for heavy customization. While these files can be edited directly to create customized behavior, it is actually not considered a best practice to do so. The Helpdesk install components maintain a running list of files that they are responsible for and ignore all others. This means that custom files can simply be dropped in place among the shipping files and will be left alone when Helpdesk is removed or upgraded. AppWeaver provides a file aliasing mechanism to allow you to override the shipping files and dynamically replace them with your own modified copies. As of HD 6.0 SP1 you can simply drop a custom.config file into the web in to customize the application. This custom.config file allows you to specify override definitions in the root of AeXHD or in an appropriate entry point (typically the worker folder it behaves like web.config in that definitions are inherited from parent directories). Overridden files are opened in place of the originals. The format of custom.config is as follows (unneeded definitions can be deleted):

3 <?xml version="1.0" encoding="utf-8"?> <custom.configuration> <consoles> <console id="conid"> <command id="existingornewcmdalias" moduleid="templatemodule" name="sidnamestring" description="siddescstring"> <commandparam name="template" value="overrideornewfilealias" /> </console> </consoles> <presentations path="~/existingorcustomfolder/"> <presentation name="existingornewpresname" file="overrideornewpresfile.ascx" /> </presentations> <files path="~/existingorcustomfolder/"> <file id="existingornewfilealias" file="overrideornewfile.ascx"/> </files> <imgfiles path="~/existingorcustomfolder/"> <imgfile id="existingornewimagealias" file="overrideornewimage.gif" width="100" height="100" alt="sidaltstring" /> </imgfiles> <resourcelibs> <resourcelib assembly="resources.assembly" base="resources.base" /> <resourcelib file="resources.xml" path="~/existingorcustomfolder/" /> </resourcelibs> <strings> <string id="sidexistingornewstringalias">overridden or new string!</string> </strings> </custom.configuration> The best practice technique is to make your override definitions right in this file (rather than in a copy of web.config in a new entry point as previously documented). When upgrades/reinstalls occur this file is left alone so that your overrides continue to be in force. New/overridden strings added directly to this file (as opposed to strings in new resource libs added to this file) are not localized. Resource libs added to this file follow the localization mechanism and can contain localized strings in culture-code-named subfolders (this is discussed in more detail below). Customization use cases Should I override a command or the file alias of the template that implements the command? This depends upon whether you will only be making modifications to a template, or whether you also need the template to be invoked with a different command context. A command s context is defined by its declaration in a web.config file and includes, but is not limited to: ID. The identifier of the command. Module ID. The module alias for the module,.net user control (.ascx file), that implements the UI and functionality of the command. Modality. Whether the command should be run modally or not. By convention most of the editors in Helpdesk are modal. This forces the user to accept or cancel the changes and prevents an inadvertent loss of data. Command Parameters. Static data (analogous to input parameters to a function or subroutine). Overriding a command The newitem and edititem commands of Helpdesk will help illustrate what is meant by a command s context. Both commands rely on the same template, WorkItemEdit, to provide their UI and functionality. The template behaves differently for the two commands because their context s are different. Below are the declarations of the newitem and edititem command as they appear in the ~/worker/web.config file.

4 web.confing <command id="edititem" moduleid="templatemodule" name="sidedititem" description="sidedititemdesc" modal="yes" privileges="privviewincidents,priveditincidents"> <commandparam name="template" value="workitemedit" /> <command id="newitem" moduleid="templatemodule" name="sidnewitem" description="sidnewitemdesc" modal="yes" pivileges="privcreateincidents"> <commandparam name="template" value="workitemedit" /> <commandparam name="action" value="new" /> The WorkItemEdit template can access the command context, in this case the commandparams, through the Command object provided by AppWeaver. WorkItemEdit.ascx code snippet If Command("action") = "new" Then [do something] Else [do something else] End if In summary, if you want to change a command s context then you will override the command. Overriding a file alias If the context is sufficient, and you just need to add some functionality to a template (perhaps you would like to expose a new field) then you will probably only need to override the file alias. In this scenario you would copy the WorkItemEdit.ascx to CustomWorkiItemEdit.ascx in a custom directory, make the necessary modifications, and then override the file alias so that it references your copy of the file. This can be made clear by looking at the file alias for the template commandparam (the same commandparam is used for both newitem and edititem) : <commandparam name="template" value="workitemedit" /> The alias WorkItemEdit is declared in the ~/web.config and is resolved by AppWeaver to an actual file in the web (in this case ~/templates/workitemedit.ascx): <files path="~/templates/"> <file id="workitemedit" file="workitemedit.ascx"/> <files /> Therefore by changing the file that is referenced by the alias you can tell the system to load and run CustomWorkItemEdit.ascx instead of the original template WorkItemEdits.ascx. For example, you might change the file alias as follows (this should be done using the custom.config file and not editing the web.config file directly): <files path="~/custom/"> <file id="workitemedit" file="customworkitemedit.ascx"/> <files /> IMPORTANT - Specific examples on overriding commands and file aliases will be given and will follow the best practice guidelines that we have established in order to ensure the greatest likelihood of success and to minimize the possibility that your customi zations will continue to work when Helpdesk is upgraded.

5 How to override a command This customization covers steps that can be taken to override a command. It involves creating a custom.config file and providing a command declaration to override an existing command from the worker console. In this example you will be overriding the viewitem command so that you can provide additional context by specifying custom data using a commandparam. Prerequisites You need a familiarity with customization integration using custom.config (see Helpdesk Integration document for additional information). You need a familiarity with XML Solution You will be creating a custom.config file and providing a command declaration that overrides an existing command from the web.config. Create a custom.config file and override the viewitem command Create a file named custom.config in the worker entry point (i.e. ~/worker) with the following contents: ~/custom.config <?xml version="1.0" encoding="utf-8"?> <custom.configuration> </custom.configuration> IMPORTANT - The file must specifically be named custom.config or AppWeaver will not pick up the changes. Add a console declaration to the custom.configuration section that has the same console id that is used in the ~/worker/ web.config: <?xml version="1.0" encoding="utf-8"?> <custom.configuration> <console id="conworker"> </console> </custom.configuration> Add a command override for the viewitem command that provides an additional commandparam for custom data. The easiest and safest way to do this is by copying over the command declaration from the web.config and then making modifications. The command in custom.config overrides the one in web.config because it uses the same id, viewitem, as a command in the web.config file. <custom.configuration> <console id="conworker"> <command id="viewitem" moduleid="templatemodule" name="sidviewitem" description="sidviewitemdesc" privileges="privviewincidents"> <commandparam name="template" value="workitemview" /> <commandparam name="customdata" value="[custom data]" /> </console> </custom.configuration> Notice that a new commandparam has been added whose name is customdata and whose value can be anything that you would like. The new data can be accessed within the template as follows: WorkItemView.ascx Dim customdata As String = Command("customdata")

6 Now, within the template the customdata variable can be used to access customized data that is passed to the command from the web.config file via a commandparam. In most situations where you override a command you will also override the file alias of the template that implements the command. See the section How to leverage existing functionality by overriding a template file alias for a description about how this should be done. How to leverage existing functionality by overriding a template file alias This customization covers steps that can be taken to leverage the functionality of an existing template (.ascx user control) by copying the template and specifying a custom.config file to override the template s file alias so that the alias points to the copy of the template. The template that implements the functionality for both the newitem and edititem commands, WorkItemEdit.ascx, will be used for this example. Prerequisites You need a familiarity with customization integration using custom.config (see Helpdesk Integration document for additional information). You need a familiarity with XML Solution There are two basic steps involved in this process. The first involves copying the template into a custom directory. The second involves integrating the new template into HD using a custom.config to override a file alias. A little background on the template and commands will p rovide a clearer understanding about what you will be accomplishing with this customization. The newitem and edititem commands both rely on the same template, WorkItemEdit.ascx, to provide their UI and functionality as indicated in their respective command declarations in the ~/worker/web.config file (notice that they both specify WorkItemEdit for the template commandparam). web.config (~/worker) <command id="edititem" moduleid="templatemodule" name="sidedititem" description="sidedititemdesc" modal="yes" privileges="privviewincidents,priveditincidents"> <commandparam name="template" value="workitemedit" /> <command id="newitem" moduleid="templatemodule" name="sidnewitem" description="sidnewitemdesc" modal="yes" privileges="privcreateincidents"> <commandparam name="template" value="workitemedit" /> <commandparam name="action" value="new" /> Notice that both commands specify the same module alias, TemplateModule, and both specify the same template alias, WorkItemEdit, for their template commandparam. TemplateModule is a special AppWeaver.NET module that acts as a template engine. This module requires that a template commandparam be specified whose value is a file alias. Given this information, we can override the WorkItemEdit file alias so that it references a customized copy of the original file. Copy the template into a custom directory in the web and rename it 1. If a custom directory does not exist, create one in the root of the web (e.g. ~/custom/). This directory can serve as a common repository for all custom files (i.e. templates, presentations, images, etc.).

7 2. Copy ~/templates/workitemedit.ascx to the directory that you created in step 1 (e.g. ~/custom/workitemedit.ascx). 3. Rename the file to CustomWorkItemEdit.ascx. This simply helps to avoid the confusion of having two files with the same name in the same web. Override the WorkItemEdit file alias Override the WorkItemEdit file alias from the web.config by creating the file ~/custom.config file with the following contents (a snippet of the web.config has been included for comparison purposes. custom.config <?xml version="1.0" encoding="utf-8"?> <custom.configuration> <files path="~/custom/"> <file id="workitemedit" file="customworkitemedit.ascx"/> </files> </custom.configuration> IMPORTANT - The file must specifically be named custom.config or AppWeaver will not pick up the changes. web.config <files path="~/templates/"> <file id="workitemedit" file="workitemedit.ascx"/> </files> Notice that WorkItemEdit will now resolve to ~/custom/customworkitemedit.ascx when the application is run. The alias defined in custom.config wins. How to create your own custom console You may have an application that requires a completely new console. That is, a different organization of the existing Helpdesk commands than those shipped. Start with an existing console and modify it by removing (and possibly adding) commands you want your users to have available in your new console. Prerequisites You need a familiarity with customization integration using custom.config (see Helpdesk Integration document for additional information). You need a familiarity with XML You need to understand HTML tables. Solution This customization creates a new console that only exposes a subset of the worker console s commands. This same approach can be extended to adding commands by copying commands from other consoles (e.g. winuser console) to make them available in your custom console. Declare a new console Declare a new console by creating the file ~/worker/custom.config. You can copy the existing console declaration from the ~/worker/web.config and make the necessary modifications. In the example below only six commands have been copied from the web.config. This console simply demonstrates the concept of declaring a new console. custom.config <?xml version="1.0" encoding="utf-8"?>

8 <custom.configuration> <consoles> <console id="concustom" defaultcommand="homeworker" defaultpresentation="standard"> <command id="homeworker" moduleid="templatemodule" name="sidhomeworker" description="sidhomeworkerdesc" privileges="privviewincidents"> <commandparam name="template" value="workerreport" /> <command id="newitem" moduleid="templatemodule" name="sidnewitem" description="sidnewitemdesc" modal="yes" licenserequired="yes" privileges="privcreateincidents"> <commandparam name="template" value="workitemedit" /> <commandparam name="action" value="new" /> <command id="viewitem" moduleid="templatemodule" name="sidviewitem" description="sidviewitemdesc" privileges="privviewincidents"> <commandparam name="template" value="workitemview" /> <command id="edititem" moduleid="templatemodule" name="sidedititem" description="sidedititemdesc" modal="yes" privileges="privviewincidents,priveditincidents"> <commandparam name="template" value="workitemedit" /> <command id="dashboard" moduleid="templatemodule" name="siddashboard" description="siddashboarddesc"> <commandparam name="template" value="dashboard" /> <command id="recents" moduleid="templatemodule" name="sidrecents" description="sidrecentsdesc"> <commandparam name="template" value="recents" /> </console> </consoles> </custom.configuration> Create a new web form for your custom console (XML and script modification) Access to an AppWeaver console is always through a web form page (aspx) which is ultimately derived from the AppWeaver Console class. The HelpdeskConsole extends the AppWeaver console and provides Helpdesk specific functionality. All of the HD consoles use the HelpdeskConsole class. The console page is made available to web browsers by placing it in a web directory or entry point. The following is an example of some page directives that will be found in most HD web forms : ~/worker/default.aspx (code snippet) <%@ Page SmartNavigation="false" Language="vb" Inherits="Altiris.Helpdesk.Web.HelpdeskConsole" %> <%@ Register TagPrefix="aw" Namespace="Altiris.AppWeaver" Assembly="Altiris.AppWeaver" %> Notice that the webform is derived from Altiris.Web.HelpdeskConsole. There can be multiple console forms (i.e. aspx pages) within the same directory. We can create a new entry point into our custom console by copying the existing one. Copy ~/worker/default.aspx to ~/worker/custom.aspx. Edit Custom.aspx and use that same id as the one you used to declare the console in the custom.config file in the previous section (in this case concustom). By convention we do this in the OnInit override: Custom.aspx Public Overrides Sub OnInit(ByVal e As EventArgs) Me.ID = "concustom" MyBase.OnInit(e) End Sub

9 Debug and Test your customizations Restart IIS and test your console by entering the URL to your console i.e. If you have errors confirm the custom.config file is syntactically correct by opening it with Internet Explorer. Create a new entry point for your custom console The previous section described how to create a new console page living in the same directory as the original console. As an alternative you may want to place your custom console in its own entry point. The advantage to placing a console in its own entry point is that it can be secured by web server permissions to allow access only to the subset of workers that need to use it and it can be wired to a different kind of Helpdesk credential (to allow workers to be authenticated by address rather than NT Id for example). To develop your custom console in its own entry point, follow the above steps but with a few modifications: first copy the ~/worker directory to a new ~/custom directory and set its web permissions as desired using the Internet Information Services administrative tool. Since this new custom directory is unknown to the Helpdesk upgrade components you do not have to worry about your modifications being lost when Helpdesk is upgraded. This means that you can edit the web.config and default.aspx files directly. If your console file is left with the name default.aspx you can simply access the new console through the URL How to add a scalar field This customization covers adding a scalar field, a field that is not a reference to a value in another table, to an incident. You will be adding a new Application field. Upon successful completion of the solution you will be able to type in the name of an Application when creating or editing an incident. This new field will be displayed on the incident properties page and in the incident editor. Prerequisites You need to be able to add a column, create an index, modify views, and run stored procedures using SQL Server Enterprise Manager and Query Analyzer. You need a familiarity with customization integration using custom.config (see Helpdesk Integration document for additional information). You need a familiarity with XML You need to understand HTML tables. Solution The first few sections of this solution describe changes that must be made to the Helpdesk database. The remaining sections discuss how to expose the new application field in the Helpdesk UI, which includes modification to Helpdesk templates. Each section must be completed successfully before the procedure in the next section is attempted to ensure a successful modification. Add application column to the workitem table Using SQL Server Query Analyzer run the following script against your Helpdesk database. ALTER TABLE workitem ADD application nvarchar(128) NOT NULL DEFAULT (N'') To confirm the field was created successfully run the following script against your Helpdesk database. SELECT application FROM workitem WHERE id = 0 You should see the following in the results window. application

10 application is the new field you just added. If you do not see this output in the results window an error has occurred. Check the spelling of the field in the Alter table statement and the Select statement. IMPORTANT: notice that for variable length character data the unicode nvarchar data type is used. ALL character data in Helpdesk must be nchar or nvarchar. Please see Transaction-SQL Reference for a description of nchar and nvarchar data types and their implications. IMPORTANT: NULL values are not permitted or supported for Helpdesk columns. Notice the NOT NULL clause of the ALTER TABLE statement above. IMPORTANT: all Helpdesk columns must contain a default value. All nchar and nvarchar defaults are prefixed with N as set forth in Transaction-SQL Reference when dealing with unicode data (e.g. N 0, N, N My Default ). Alternatively you could have modified the table directly using the Design table feature of SQL Server Enterprise Manager. Update the view_def table with information about the new column (database modification) The view_def table is very important to the installation/upgrade process of Helpdesk. This table must be updated so that the changes that you make will be preserved during the installation/upgrade process. Using SQL Server Query Analyzer run the following script against your Helpdesk database. EXEC sp_addviewdef N'workitem_only_view', N'workitem.application AS workitem_application', N'' This script will add a row to the view_def table. Notice that the second argument specified for stored procedure sp_addviewdef is an alias specification. By following the conventions that have been established in Helpdesk you will ensure that databinding will be much easier. If you view data in the view_def table the conventions are self-explanatory. Run the following script to verify the field was added to the view. SELECT * FROM view_def WHERE column_sql = N'workitem.application AS workitem_application' You should get one row returned with table_name = workitem_only_view and column_sql = workitem.application AS workitem_application Alternatively, you could have modified the view_def table directly using SQL Server Enterprise Manager. Drop and recreate the workitem_only_view (database modification) Using SQL Server Query Analyzer run the following script against your Helpdesk database. EXEC sp_createhddview 'workitem_only_view', 'workitem' EXEC sp_createhddview 'workitem_detail_view', 'workitem_only_view' go if exists (select * from sysobjects where id = object_id(n'[dbo].[workitem_current_view]') and OBJECTPROPERTY(id, N'IsView') = 1) drop view [dbo].[workitem_current_view]

11 CREATE VIEW dbo.workitem_current_view AS SELECT workitem_detail_view.* FROM workitem_detail_view WHERE (workitem_is_last = N'1') Run the following script to verify the field is present in the view. SELECT workitem_application FROM workitem_only_view WHERE workitem_id = 0 You should see the workitem_application field with no rows returned. Stored procedure sp_createhddview will drop the view for you before recreating it. The first parameter is the name of the view and the second parameter is the name of the table associated with the view. Copy the templates into a custom directory in the web and rename them 1. If a custom directory does not exist, create one in the root of the web (e.g. ~/custom/). This directory can serve as a common repository for all custom files (i.e. templates, presentations, images, etc.). 2. Copy ~/templates/workitemedit.ascx and ~/templates/workitemview.ascx to the directory that you created in step 1 (e.g. ~/custom/workitemedit.ascx). You will need to uncheck the Readonly attribute so that the files can be modified. 3. Rename the files by prefixing them with the word Custom (e.g. CustomWorkItemEdit.ascx). This simply helps to avoid the confusion of having two files with the same name in the same web. Override the WorkItemEdit and WorkItemView file aliases Override the WorkItemEdit and WorkItemView file aliases from the web.config by creating the file ~/custom.config with the following contents in the root of the web (a snippet of the web.config has been included to help illustrate the override). custom.config <?xml version="1.0" encoding="utf-8"?> <custom.configuration> <files path="~/custom/"> <file id="workitemedit" file="customworkitemedit.ascx"/> <file id="workitemview" file="customworkitemview.ascx"/> </files> </custom.configuration> IMPORTANT - The file must specifically be named custom.config or AppWeaver will not pick up the changes. web.config <files path="~/templates/"> <file id="workitemedit" file="workitemedit.ascx"/> <file id="workitemview" file="workitemview.ascx"/> </files> Notice that WorkItemEdit will now resolve to ~/custom/customworkitemedit.ascx and WorkItemView will resolve to ~/custom/customworkitemview.ascx (declarations from the custom.config win).

12 Modify the templates to enable editing and display of the application field (template modification) Edit ~/custom/customworkitemedit.ascx to enable application to be edited through the interface. Search for the line beginning with <aw:layout id="lopanels". Paste the following line immediately before it. <aw:textbox id="tbapplication" runat="server" Width="300px" ItemDataField="workitem_application" ColSpan="4" Label="Application:" ></aw:textbox> This line defines an AppWeaver TextBox control to contain the application value. The control has an id of tbapplication and can be any unique string (conventionally we prefix the id of aw:textbox controls with tb ). The control is databound to the data source WorkItem (case sensitive name defined in the MultiPage control as the ItemDataSourceName attribute and which can be inherited by its children) and data field workitem_application (the attribute ItemDataField of our TextBox). The data field workitem_application is the new view field created in a previous section. The control has a label called Application: to identify the text box on the page. The ItemDataSourceName could have been directly specified on our TextBox, but AppWeaver databinding will search up the control hierarchy if it is not specified. Now modify ~/custom/ CustomWorkItemView.ascx file in a similar way. Paste the following AppWeaver Label control on the line after the lblcreated label control. <aw:label id="lblapplication" runat="server" ItemDataField="workitem_application" label="application:"></aw:label> You can experiment with the location and label of the textbox and label controls on the pages. Debug and Test your customizations View the customizations by entering into the address bar of your browser. Edit an incident, look for the application field and enter an application name and save. Confirm that the incident properties has your application name. How to add lookup field This customization covers adding a new lookup id to an incident that is a field that is a reference to a value in another table. Upon successful completion of the solution, Helpdesk workers will be able to select an Application from a dropdown when creating or editing an incident, and the Application will be displayed on the incident report. Implementing Application as a lookup table rather than a scalar field offers several advantages. First, it will prevent redundant Applications from being entered into the database (e.g. Microsoft Word, MS Word, MS Office Word, etc.). Second, searching for incidents by Application could be simplified. For example, you could provide an Application dropdown on the Find command. Finally, you get all the benefits offered by Helpdesk s implementation of lookup tables: ability to choose a default, activate or inactive a value, and weight the values. Prerequisites You need to be able to add a column, create an index, modify views, and run stored procedures using SQL Server Enterprise Manager and Query Analyzer. You need a familiarity with customization integration using custom.config (see Helpdesk Integration document for additional information). You need a familiarity with XML You need to understand HTML tables.

13 Solution The first few sections of this solution describe changes that must be made to the Helpdesk database. The remaining sections discuss how to expose the new application field in the Helpdesk UI, which includes modification to Helpdesk templates. Each section must be completed successfully before the procedure in the next section is attempted to ensure a successful modification. Add a new workitem_application_lookup table and populate it with an initial set of values Using SQL Server Query Analyzer run the following script against your Helpdesk database. if not exists (select * from sysobjects where id = object_id(n'[dbo].[workitem_application _lookup]') and OBJECTPROPERTY(id, N'IsUserTable') = 1) begin CREATE TABLE [dbo].[workitem_application_lookup] ( [id] [int] NOT NULL PRIMARY KEY, [status] [nchar] (1) NOT NULL DEFAULT (N'a'), [value] [nvarchar] (255) NOT NULL DEFAULT (N''), [ordinal] [int] NOT NULL DEFAULT (0), [is_default] [nchar] (1) NOT NULL DEFAULT (N'0') ) ON [PRIMARY] end IMPORTANT: notice that for variable length character data you must use unicode nvarchar data type. ALL character data in Helpdesk must be nchar or nvarchar. Please see Transaction-SQL Reference for a description of nchar and nvarchar data types and their implications. IMPORTANT: NULL values are not permitted or supported for Helpdesk columns. Notice the NOT NULL clause in the CREATE TABLE script above. IMPORTANT: all Helpdesk columns must contain a default value. All nchar and nvarchar defaults are prefixed with N as set forth in Transaction-SQL Reference when dealing with unicode data (e.g. N 0, N, N My Default ). Using SQL Server Query Analyzer run the following script against your Helpdesk database. This will populate the lookup table with some Applications. insert into workitem_application_lookup (id,status,value,ordinal,is_default) values(100,'a','other',1,'1') insert into workitem_application_lookup (id,status,value,ordinal,is_default) values(200,'a','altiris express Web Administrator',2,'0') insert into workitem_application_lookup (id,status,value,ordinal,is_default) values(300,'a','altiris express Helpdesk',3,'0') insert into workitem_application_lookup (id,status,value,ordinal,is_default) values(400,'a','aliris express Notification Server',4,'0') insert into workitem_application_lookup (id,status,value,ordinal,is_default) values(500,'a','microsoft Office',5,'0') insert into workitem_application_lookup (id,status,value,ordinal,is_default) values(600,'a','microsoft System Management Server',6,'0') Alternatively you could have created the table directly using the New table feature of SQL Server Enterprise Manager. The script above adheres to the conventions that have been established for Helpdesk lookup tables. If you use the New table feature you should do the same. To verify your new lookup table was created and populated successfully run the following script. select * from workitem_application_lookup

14 You should see the following results: 100 a Other a Altiris express Web Administrator a Altiris express Helpdesk a Aliris express Notification Server a Microsoft Office a Microsoft System Management Server 6 0 Add application_lookup_id column to the workitem table Using SQL Server Query Analyzer run the following script against your Helpdesk database. int set nocount on = object_id(n'[dbo].[workitem]') if not exists( select * from syscolumns where name='application_lookup_id' and id=@id) begin ALTER TABLE workitem ADD application_lookup_id int NOT NULL CONSTRAINT [DF_workitem_application_lookup_id] DEFAULT (100) WITH VALUES CREATE INDEX [IX_workitem_application_lookup_id] ON [dbo].[workitem]([application_lookup_id]) ON [PRIMARY] end IMPORTANT - Notice that we have specified the DEFAULT keyword to specify a default value of 100 for the new field. In versions of HD after 6.0 SP1 this will not be necessary. The is_default column should determine the default. However, currently there is a bug for custom lookups that prevent the value marked as the default (is_default= 1 ) from being used as the default. Typical consideration should be placed on whether or not to index the column. You would remove the CREATE INDEX statement in the script above if you chose not to index the column. Update the view_def table with information about the new lookup (database modification) The view_def table is very important to the installation/upgrade process of Helpdesk. This table must be updated so that the changes you make will be preserved during the installation/upgrade process. Using SQL Server Query Analyzer run the following script against your Helpdesk database. exec sp_addviewdef N'workitem_only_view', N'workitem.application_lookup_id AS workitem_application_lookup_id', N'' exec sp_addviewdef N'workitem_detail_view', N'wal.value AS workitem_application_lookup_value', N'LEFT OUTER JOIN workitem_application_lookup wal ON workitem_application_lookup_id = wal.id' exec sp_addviewdef N'workitem_detail_view', N'wal.ordinal AS workitem_application_lookup_ordinal', N'' This script will add rows to the view_def table. Notice that the second argument specified for stored procedure sp_addviewdef is an alias specification. By following established conventions, you will ensure that databinding will be much easier. If you read in detail data in the view_def table, the conventions are self-explanatory. Alternatively you could have modified the view_def table directly using SQL Server Enterprise Manager.

15 Drop and recreate the workitem_only_view, workitem_detail_view and workitem_current_views (database modification) There are three different views that will need to be dropped and recreated so that data for the new application lookup will be included in the view. exec sp_createhddview 'workitem_only_view', 'workitem' exec sp_createhddview 'workitem_detail_view', 'workitem_only_view' go if exists (select * from sysobjects where id = object_id(n'[dbo].[workitem_current_view]') and OBJECTPROPERTY(id, N'IsView') = 1) drop view [dbo].[workitem_current_view] CREATE VIEW dbo.workitem_current_view AS SELECT workitem_detail_view.* FROM workitem_detail_view WHERE (workitem_is_last = N'1') IMPORTANT: the order in which the views are created is significant because of dependencies that exist. Stored procedure sp_createhddview will drop the view for you. The first parameter is the name of the view and the second parameter is the name of the table associated with the view. Insert a query that will retrieve data from the lookup table into the query table (database modification) You need to create a new query that will be used to retrieve Application lookup values. Using SQL Server Query Analyzer run the following script against your Helpdesk database. insert into query (name, expression, cache_results) values (N'ApplicationList', N'SELECT * FROM workitem_application_lookup where lower(status)=n''a'' order by ordinal', N'1') Note the name that you gave the query, ApplicationList, because it will be used later when you modify the template. Copy the templates into a custom directory in the web and rename them 4. If a custom directory does not exist, create one in the root of the web (e.g. ~/custom/). This directory can serve as a common repository for all custom files (i.e. templates, presentations, images, etc.). 5. Copy ~/templates/workitemedit.ascx and ~/templates/workitemview.ascx to the directory that you created in step 1 (e.g. ~/custom/workitemedit.ascx). You will need to uncheck the Readonly attribute so that the files can be modified. 6. Rename the files by prefixing them with Custom (e.g. CustomWorkItemEdit.ascx). This simply helps to avoid the confusion of having two files with the same name in the same web. Override the WorkItemEdit and WorkItemView file aliases Override the WorkItemEdit and WorkItemView file aliases from the web.config by creating the file ~/custom.config with the following contents in the root of the web (a snippet of the web.config has been included for to help illustrate the override). custom.config

16 <?xml version="1.0" encoding="utf-8"?> <custom.configuration> <files path="~/custom/"> <file id="workitemedit" file="customworkitemedit.ascx"/> <file id="workitemview" file="customworkitemview.ascx"/> </files> </custom.configuration> IMPORTANT - The file must specifically be named custom.config or AppWeaver will not pick up the changes. web.config <files path="~/templates/"> <file id="workitemedit" file="workitemedit.ascx"/> <file id="workitemview" file="workitemview.ascx"/> </files> Notice that WorkItemEdit will now resolve to ~/custom/customworkitemedit.ascx and WorkItemView will resolve to ~/custom/customworkitemview.ascx (definitions from the custom.config win). Modify the templates to enable editing and display of the application field (template modification) Add label control to the Incident properties page by modifying the CustomWorkItemView.ascx file. Paste the following AppWeaver Label control on the line after the lblcreated label control and before the "pnlnotifyrules" panel control. <aw:label id="lblapplication" runat="server" colspan="4" ItemDataField="workitem_application_lookup_value" label="application:"></aw:label> Notice the ItemDataField is the new field added to the workitem_detail_view in the section above. The control has a label on the page of Application: The strings for your customizations can be hardcoded like this or a string id can be used and a string resource file can be used. The string resource file can be localized if desired. Now edit CustomWorkItemEdit.ascx to enable the user to select the application to be associated with the incident. Near the top of the file is a subroutine called LoadDataSources. This is run once when the template is loaded. The data sources are all defined here. Find the set of lines that initialize the various data stores. They all begin with DataStore( SomeObject ). Add the following line to the end of the list to load the application lookup list into the data store. DataStore("Applications") = New ListDataSet("ApplicationList") Notice we specify the query we added above to query the lookup table for all the applications available. Now add a dropdown list of applications to the incident editor by adding an AppWeaver DropDownList control to the edit page. Again, add this just after the Created label and before the <aw:dropdownlist id="ddlapplication" runat="server" ItemDataField="workitem_application_lookup_id" Label="Application:" DataTextField="value" DataValueField="id" DataSourceName="Applications" currentvalue="true"></aw:dropdownlist> The ItemDataField attribute specifies which field will be updated by changes made in this control by the user. The DataTextField sets the field to display in the control. In our example value which is the text of the application lookup. The DataValueField specifies what you get from the control. In our example the id is returned. The DataSourceName attribute specifies the data source to use for this control. We use the Applications data source we added to the LoadDataSources subroutine. Our new dropdown list uses the Applications data source and displays the data in the value field and puts the id of the value selected by

17 the user into the workitem_application_lookup_id field of the WorkItem data store. Note this was specified by the ItemDataSourceName="WorkItem" attribute of the AppWeaver MultPage control aw:multipage at the top of the page. You can experiment with the location and label of the textbox and label controls on the pages. Debug and Test your customizations Restart IIS and view the customizations by entering default.aspx into the address bar of your browser. Edit an incident, look for the application field and enter an application name and save. Confirm that the incident properties page has your application name. How to centralize all of your custom strings for ease of management and localization In the previous earlier sections you hard coded strings were used for our control labels. This is fine for simple customizations with only one or two controls but what if there are numerous controls in several files or you need to localize your strings to support several languages? Then this section covers how custom strings can be specified. Prerequisites You need a familiarity with customization integration using custom.config (see Helpdesk Integration document for additional information). You need a familiarity with XML You need to understand HTML tables. Solution This solution takes you through creating an XML file to contain all your custom strings and how to refer to the strings in your templates. Finally you learn how to localize your strings. Creating a strings resource file A strings resource file is an XML file that can be created with any text editor. It must have the format below: <strings> <string id="csidstring1">custom String 1</string> <string id="csidstring2">custom String 2</string>... </strings> The root node is strings and can contain any number of string nodes. Each string node must have a unique id attribute. The text of the string is the inner text contained between the > delimiting the string node attributes and the < at the start of the closing string tag. The string id needs to be in quotes ( ) and must be unique within this file. It can be any combination of characters and numbers. We recommend devising a naming standard and sticking with it. The example above uses csid representing custom string id then the string name. Now create a string file for the application lookup field customization performed in the previous section. The view and edit page used a label attribute of label= Application:. For demonstration purposes lets use Application: for the view page and Software Application: for the edit page. Our strings file should look like this:

18 <strings> <string id="csidlblapplication">application:</string> <string id="csidlblsoftwareapplication">software Application:</string> </strings> Copy and paste this into Notepad (or any text editor) and save as ~/custom/ CustomStrings.xml. Now confirm the syntax of your file by opening it with Microsoft Internet Explorer. It should display your string resources correctly. If not it may show an error like tags do not match etc. and refer to the line and position of the offending character. Examine your file carefully and fix the error and repeat until the file can be opened without any errors. Declare a resourcelib for your custom string file Declare a resourcelib for your custom string file by creating the file ~/custom.config with the following contents in the root of the web. custom.config <?xml version="1.0" encoding="utf-8"?> <custom.configuration> <resourcelibs> <resourcelib file="customstrings.xml" path="~/custom/" /> </resourcelibs> </custom.configuration> IMPORTANT - The file must specifically be named custom.config or AppWeaver will not pick up the changes. Adding string ids in place of strings in templates Now add the string ids to the control label in the customized templates. Open the CustomWorkItemView.ascx file and find the lblapplication control. Replace the text in the label attribute with csidlblapplication, see example below: <aw:label id="lblapplication" colspan="4" runat="server" ItemDataField="workitem_application_lookup_value" label="csidlblapplication"></aw:label> Similarly, replace the label text in the WorkItemEdit.ascx file with the string id we defined above, "csidlblsoftwareapplication". <aw:dropdownlist id="ddlapplication" runat="server" ItemDataField="workitem_application_lookup_id" Label="csidLblSoftwareApplication" DataTextField="value" DataValueField="id" DataSourceName="Applications" currentvalue="true"></aw:dropdownlist> Save both files and test. You should see your strings appear in the incident properties and the incident editor. The incident properties should look exactly the same. That is Application: displayed for the control label. The incident editor will have Software Application: for the label. Localizing strings in your custom file You can localize your custom strings so the application will present the correct language based on the user s browser settings. To localize: create a subdirectory under the custom directory for each language that you wish to support. Name them using the 2 or 4 letter culture codes. The culture names follow the RFC 1766 standard in the format "<languagecode2>-<country/regioncode2>", where <languagecode2> is a lowercase two-letter code derived from ISO and <country/regioncode2> is an uppercase two-letter code derived from ISO For example, U.S. English is "en-us". For a complete list see the CultureInfo

19 class at Copy the localized CustomStrings.xml files into each directory. Restart IIS, and you re ready to go. Debug and Test your customizations Note the system tries to find the best language fit possible, so if you have a Swiss German localized file CustomStrings.xml it should be in the de-ch directory. A Germany German CustomStrings.xml file should be in the de subdirectory. If the browser settings are set to Swiss German the de-ch subdirectory will be searched first for a match for the string id, then the de subdirectory then the custom directory then the Helpdesk and AppWeaver resources. In this way string ids not found in the country or regioncode file will next be searched for in the languagecode file and if not found there searched for in the (default) CustomStrings.xml file in the custom directory and finally in the (localized) Helpdesk resource files. Note Helpdesk uses en-us as its default language. You may want to keep your default custom strings file in US English so there will be no confusion in the browser setting. This technique is the same one that.net uses and is nice because of the built in fall back capabilities inherent in the system. Database The following sections contain a list of the tables, views and stored procedures used in Helpdesk. Tables hdinstallreport schema_version view_def license audit_log bulletin workitem_category_routing workitem_category_tree contact contact_mo_join custom_processor _message lookup_tree managed_object managed_object_ns_unique_id managed_object_sms_unique_id managed_object_source managed_object_source_definition mo_source_join mo_workitem_history organization query tag tag_collection template_alias url_alias server_url_alias worker worker_hourly_rate worker_query workitem workitem_attachment workitem_next_number wu_custom_instance workitem_wuci_join managed_object_type_lookup workitem_priority_lookup workitem_status_lookup workitem_category_lookup workitem_type_lookup workitem_link_type_lookup standard_lookups default_tag Views asset_only_view asset_view bulletin_only_view bulletin_view contact_only_view contact_view managed_object_only_view managed_object_view mo_source_join_view organization_only_view organization_view tco_view worker_only_view worker_query_only_view worker_query_view worker_view workers_in_workitem_view workitem_current_view workitem_detail_view workitem_only_view workitem_wuci_join_view wu_custom_instance_view Stored Procedures sp_getschemaversion sp_checkschemaversion sp_updateschemaversion sp_createdtable sp_report sp_addurlalias sp_addserverurlalias sp_addviewdef sp_newtagcollectionid

20 sp_createhddview sp_addupdatequery sp_addaudit sp_addcontactassetassociation sp_addtag sp_addattachment sp_addupdatemanagedobjectsource sp_addworkerhourlyrate sp_addworkitemwuci sp_deleteallworkitemwucis sp_deletebulletin sp_deletesingletag sp_deletetags sp_deletesource sp_deleteworkerquery sp_deletewuci sp_deleteallworkitemcategorytree sp_deleteallworkitemcategoryrouting sp_getcontact sp_getdefaultattachment sp_getdefaultbulletin sp_getdefaultorganization sp_getdefaultcontact sp_getdefault message sp_getdefaultmanagedobject sp_getdefaultworker sp_getdefaultroutingworkerid sp_getautoroutingworkerid sp_getdefaultworkerquery sp_getdefaultworkitem sp_getdefaultwuci sp_get message sp_getguestworker sp_getmanagedobject sp_getmanagedobjectsource sp_getmosautoupdatelist sp_getmosourcejoinlist sp_getquerybyname sp_gettags sp_geturlalias sp_getserverurlalias sp_getworker sp_getworker addrs sp_getworkitemprevious sp_getworkitemwucilist sp_getworkitemhistorylist sp_newbulletin sp_newcontact sp_new message sp_newmanagedobject sp_neworganization sp_newworker sp_newworkerquery sp_newworkitem sp_newworkitemcategorytree sp_newworkitemcategoryrouting sp_newwuci sp_resolveurls sp_resolveserverurls sp_updatebulletin sp_updatecontact sp_update message sp_updatemanagedobject sp_updatemoslastautoupdate sp_updateorganization sp_updateworker sp_updateworkerquery sp_updateworkitem sp_updatewuci sp_updateworkitemnoincrement sp_importsmsresource sp_importnsresource sp_importnscontact sp_workerreportdata sp_adminreportdata sp_workitemstatuscount sp_workitemprioritycount sp_workitemstatuscountbyworkerid sp_workitemprioritycountbyworkerid sp_workerconsoledata sp_workitemlinkedby sp_deleteworkitembynumber sp_getdeleteworkitemcount sp_deleteassetsbyidlist sp_deletecontactsbyidlist sp_deleteallworkitemsbyquery sp_deletenonlinkedworkitemsbyquery sp_getdefaultinvisiblewuciids sp_insertdefaulttag sp_inserttag sp_updatesingletag sp_gettagvalue sp_verifyworkercontacttags sp_getrecentitems sp_getasset sp_getbulletin sp_getcontactbyid sp_getcontactbyntid sp_getcurrentworker sp_getcurrentworkerbyname sp_getcurrentworkerbyntid sp_getdefaultbulletin2 sp_getdefaultorganization2 sp_getdefaultcontact2 sp_getdefaultworkitemandwucis sp_getdefaultquery sp_getdefaultwuci2 sp_getorganization sp_getwuci sp_getguestworkerbycontactid sp_getgues tworkerbycontactntid sp_getguestworkerby address sp_getworkerbyname sp_getworkerbyntid sp_getworkitem sp_newcontact2 sp_updatecontact2 sp_getdefaultasset sp_newasset sp_updateasset sp_newbulletin2 sp_getstandardlookups sp_getworkerquery2 sp_getdefaultworkerquery2 sp_newworkerquery2 sp_updateworkerquery2 sp_retrievenextworkitemfromqueue sp_countrealworkers sp_checkorganization sp_setdefaultworkitemcategory sp_addupdatesource sp_updateworkitemcomment sp_importsmsresource2 sp_importnsresource2 sp_updateworkitemwuciids sp_new message2 sp_update message2 sp_newworker2 sp_updateworker2