Free Internal vs Display Names for Departments

[Matthew]

This is a follow-up to the thread: "internal" display name and "external" (to clients) display name

Here's how to create a separate display name for each of your departments, that appears on the client-side department selection page. You also get a mouseover popup with a more detailed department description. See attached screenshot.

Why would you want to do this? A couple examples:

1. You have many departments, and you clients are easily confused as to which department they should submit an issue to. You want to make the display name a bit more descriptive than than the internal name seen in the Staff CP.
2. Your help desk routes tickets for multiple geographical sites. Each has their own template group for customizing interfaces elements, language, and access to knowledgebase/download items. Internally, you have departments that look like:

• Staff Support (Dubai)
• Staff Support (Jakarta)
• Staff Support (Hong Kong)
• etc.

The departments are staffed by different people of course, based in the different office locations. However, when company staff log into the web interface to issue a ticket, they should only need to see one department: Staff Support Services. So internal department names must be distinct, but the display names may be identical.

How To Do It

Warning: you need to modify your database and several core Kayako files. Do not attempt this unless you have experience with such. Don't ask me for help if you break something.

Backup these files:

• \locale\en-us\departments.php
• \modules\core\admin_departments.php
• \includes\functions_departments.php

Step 1: Modify your database

In table swdepartments, you need to add two more fields:

1. displaytitle (type=varchar, length=100, allow null=no, charset=utf8, collation=utf8_general_ci)
2. titledesc (type=varchar, length=255, allow null=yes, charset=utf8, collation=utf8_general_ci)

Step 2: Add the language strings

Insert the following strings into the array in \locale\en-us\departments:

PHP Code:

    // Department Display Name Mod by Matthew Arciniega
    'desc_departments' => 'Description', 
    'desc_depdescription' => 'This text will be displayed with departments listed on the client side. When you have many departments, use this text to help clients find the right one for their query.',   
    'depdisplaytitle' => 'Display Title', 
    'desc_depdisplaytitle' => 'This is the department title as seen by clients when submitting a ticket through the web interface. Normally it is the same as the internal title, but it does not have to be.', 
    // End Mod 


Step 3: Modify department functions

In \includes\functions_departments.php, make the following changes:

In function insertDepartment, replace the function declaration with:

PHP Code:

    function insertDepartment($title, $departmentmodule, $tgroupidlist, $type = "1", $displayorder = "1", $isdefault = false, $displaytitle, $titledesc = "") 


In the same function, find this line...

PHP Code:

$dbCore->query("INSERT INTO `". TABLE_PREFIX ."departments` (`title`, `departmenttype`, `departmentmodule`, `isdefault`, `displayorder`) VALUES ('". $dbCore->escape($title) ."', '". iif($type=="1", "public", "private") ."', '". $dbCore->escape($departmentmodule) ."', '". $dbCore->escape($nisdefault) ."', '". $dbCore->escape($displayorder) ."');"); 


...and replace with:

PHP Code:

        // Department Description Mod by Matthew Arciniega
        $dbCore->query("INSERT INTO `". TABLE_PREFIX ."departments` (`title`, `departmenttype`, `departmentmodule`, `isdefault`, `displayorder`, `displaytitle`, `titledesc`) VALUES ('". $dbCore->escape($title) ."', '". iif($type=="1", "public", "private") ."', '". $dbCore->escape($departmentmodule) ."', '". $dbCore->escape($nisdefault) ."', '". $dbCore->escape($displayorder) ."', '". $dbCore->escape($displaytitle) ."', '". $dbCore->escape($titledesc) ."');"); 


In function renderDepartmentForm, find this line...

PHP Code:

    printTextRow("title", $_SWIFT["language"]["deptitle"], $_SWIFT["language"]["desc_deptitle"], "text", $_POST["title"]); 


...and insert after it:

PHP Code:

    // Department Description Mod by Matthew Arciniega
    printTextRow("displaytitle", $_SWIFT["language"]["depdisplaytitle"], $_SWIFT["language"]["desc_depdisplaytitle"], "text", $_POST["displaytitle"]);
    printTextAreaRow("titledesc", $_SWIFT["language"]["desc_departments"], $_SWIFT["language"]["desc_depdescription"], $_POST["titledesc"] , "60", "4", false, "");
    // End Mod 


In function updateDepartment, replace the function declaration with:

PHP Code:

function updateDepartment($departmentid, $title, $departmentmodule, $tgroupidlist, $type = "1", $displayorder = "1", $isdefault = false, $displaytitle, $titledesc = "") 


In the same function, find this line...

PHP Code:

$dbCore->query("UPDATE `". TABLE_PREFIX ."departments` SET `title` = '". $dbCore->escape($title) ."', `departmenttype` = '". iif($type=="1", "public", "private") ."', `departmentmodule` = '". $dbCore->escape($departmentmodule) ."', `displayorder` = '". $dbCore->escape($displayorder) ."' WHERE `departmentid` = '". intval($departmentid) ."';"); 


...and replace with:

PHP Code:

    // Department Description Mod by Matthew Arciniega
    $dbCore->query("UPDATE `". TABLE_PREFIX ."departments` SET `title` = '". $dbCore->escape($title) ."', `departmenttype` = '". iif($type=="1", "public", "private") ."', `departmentmodule` = '". $dbCore->escape($departmentmodule) ."', `displayorder` = '". $dbCore->escape($displayorder) ."', `displaytitle` = '". $dbCore->escape($displaytitle) ."', `titledesc` = '". $dbCore->escape($titledesc) ."' WHERE `departmentid` = '". intval($departmentid) ."';"); 


Step 4: Modify department actions

In \modules\core\admin_departments.php, locate the first occurrence of this code...

PHP Code:

        if (trim($_POST["title"]) == "")
        {
            $errormessage = $_SWIFT["language"]["requiredfieldempty"]; 


...and insert after it:

PHP Code:

        // Department Description Mod by Matthew Arciniega
        } else if (trim($_POST["displaytitle"]) == "")
        {
            $errormessage = $_SWIFT["language"]["requiredfieldempty"];
        // End Mod 


In the same handler, find this code...

PHP Code:

$depid = $departments->insertDepartment($_POST["title"], $_POST["departmentmodule"], $_POST["tgroupid"], $_POST["type"], $_POST["displayorder"], $_POST["isdefault"]); 


...and replace it with:

PHP Code:

            // Department Description Mod by Matthew Arciniega
            $depid = $departments->insertDepartment($_POST["title"], $_POST["departmentmodule"], $_POST["tgroupid"], $_POST["type"], $_POST["displayorder"], $_POST["isdefault"], $_POST["displaytitle"], $_POST["titledesc"]); 


Now locate the second occurrence of this code...

PHP Code:

        if (trim($_POST["title"]) == "")
        {
            $errormessage = $_SWIFT["language"]["requiredfieldempty"]; 


...and insert after it:

PHP Code:

        // Department Description Mod by Matthew Arciniega
        } else if (trim($_POST["displaytitle"]) == "")
        {
            $errormessage = $_SWIFT["language"]["requiredfieldempty"];
        // End Mod 


Lastly, in the same handler, find this code...

PHP Code:

    // Department Description Mod by Matthew Arciniega
    $dbCore->query("UPDATE `". TABLE_PREFIX ."departments` SET `title` = '". $dbCore->escape($title) ."', `departmenttype` = '". iif($type=="1", "public", "private") ."', `departmentmodule` = '". $dbCore->escape($departmentmodule) ."', `displayorder` = '". $dbCore->escape($displayorder) ."', `displaytitle` = '". $dbCore->escape($displaytitle) ."', `titledesc` = '". $dbCore->escape($titledesc) ."' WHERE `departmentid` = '". intval($departmentid) ."';"); 


Step 5: Edit Your Departments

In Admin CP->Manage Departments, edit each of your departments. At minimum, you need to add a Display Title. For departments where you don't need a separate display name, just use the same name as the original Title. Here's an example of what I did (note the use of bold tags in the string):

Title: Desktop Support
Display Title: <b>Desktop Support</b> (staff email, networking, PC & software configuration)

Adding descriptions for each department is optional. These will appear in mousover text when you hover over a radio button on the department selection page in the client side.

Step 6: Edit the submitdepartmentlist Template

In Admin CP->Templates->Manage Templates, navigate to the template group you want to modify (if not default), and edit the Tickets->submitdepartmentlist template.

Locate code that looks like this:

<td width="1" align="left" valign="top" class="row2"><label for="departmentid[<{$item[departmentid]}>]"><input type="radio" name="departmentid" id="departmentid[<{$item[departmentid]}>]" value="<{$item[departmentid]}>"<{if $tgroup[departmentid] == $item[departmentid]}> checked<{/if}>></label></td>
        <td><span class="smalltext"><label for="departmentid[<{$item[departmentid]}>]" style="CURSOR: pointer;"><{$item[title]}></label></span></td> 

Replace it with:

<td width="1" align="left" valign="top" class="row2"><label for="departmentid[<{$item[departmentid]}>]"><input type="radio" name="departmentid" title="<{$item[titledesc]}>" id="departmentid[<{$item[departmentid]}>]" value="<{$item[departmentid]}>"<{if $tgroup[departmentid] == $item[departmentid]}> checked<{/if}>></label></td>
        <td><span class="smalltext"><label for="departmentid[<{$item[departmentid]}>]" style="CURSOR: pointer;"><{$item[displaytitle]}></label></span></td> 

Do this for every template group where you need this mod.

Now you are done!

[craigbrass]

Very nice Matthew! Thanks for sharing. This is one of the features I would like to see in the main distribution...