FreeDESK - User contributions [en-gb]

FreeDESK User Guide

2012-08-27T21:37:31Z

Dave:

= Introduction =

FreeDESK is a free service desk/helpdesk system by David Cutting.

The system revolves around the idea of 'requests for service' which are raised and then managed by FreeDESK.

= Logging In =

To login go to the web page provided by your system administrator and select the 'Analyst' link. Now enter your provided username and password then click to login.

If you are using a mobile device you will be automatically redirected to a mobile-optimized version of the interface.

= Desktop Interface =

== Navigation ==

Once logged in you will see three distinct areas, the team list (left hand side), request list (right hand side) and menu bar (top of the page).

You can view requests assigned to individual teams or users (if you have permission) by selecting the team/user from the menu on the left hand side.

Once selected the requests assigned to that user or team will be displayed on the right.

To sort requests in a list click on the field at the top of the list. Fields can be turned on or off for display by selecting "Options" at the top-right of the list.

To open a request for full view or modification click on the request number.

You can see other options and pages within the system, as setup by your administrator, from menu bar options at the top of the screen. From this menu you can also log off or switch to the mobile interface.

At any point you can select "My Requests" under the Home menu to view all the requests assigned to your specific user.

== Requests ==

=== Updating Requests ===

Once a request is opened a new window will be displayed with the full history of the request.

To update the request click on the update tab from which you can add additional information, change the status of the request (for example close it), and also assign it to a different team or user (depending on the permissions you are allowed).

When you update a request, if the option is enabled by your administrator, a checkbox to email the customer will be present. If this box is checked a new email window will open with the details of the update to be sent to the customer.

=== Opening Requests ===

To open a request select that option under the 'Requests' menu on the main screen. Your administrator may have setup different types of requests for different scenarios.

A new request window is then opened. You can search for the customer by entering some or all of the customer information in the fields provided then clicking search. If a single customer matches the results they will be selected otherwise a list of matching customers will be displayed and can be selected. If no customer is found or you need to create a new customer then select 'New Customer' from the Entity menu on the main screen (if your administrator has allowed you this permission).

After selecting a customer you enter details of the update, select other information such as the priority and assignment of the request and then open it. As with an update there will be an option to send an email to the customer, which will open in a new window if selected.

= Mobile Interface =

The mobile interface (auto detected or selected manually from the System menu) is a mobile-optimized limited version.

From this interface you can view all your assigned requests and update them.

Features such as email or new request logging are unavailable through the mobile interface.

FreeDESK User Guide

2012-08-27T21:28:39Z

Dave: Created page with "= Introduction = FreeDESK is a free service desk/helpdesk system by David Cutting. The system revolves around the idea of 'requests for service' which are raised and then ma..."

MediaWiki:Lastmodifiedat

2012-08-27T21:26:33Z

Dave:

FreeDESK is Free Software under the GNU GPL v3 Licence

MediaWiki:Lastmodifiedat

2012-08-27T21:26:00Z

Dave: Created page with "."

MediaWiki:Common.css

2012-08-27T21:23:13Z

Dave: Created page with "/* CSS placed here will be applied to all skins */ #ca-history { display: none; }"

/* CSS placed here will be applied to all skins */
#ca-history { display: none; }

Event Handling

2012-08-22T00:04:27Z

Dave: Created page with "Events are handled by PIMs. A PIM will register to handle an event by calling PluginManager::RegisterPIMEvent()."

Events are handled by PIMs. A PIM will register to handle an event by calling PluginManager::RegisterPIMEvent().

Custom Requests

2012-08-22T00:03:29Z

Dave: Created page with "Custom request modules are the concrete classes which can be used for configured request types as the "concrete class method". Requests classes are derived from the RequestBa..."

Custom request modules are the concrete classes which can be used for configured request types as the "concrete class method".

Requests classes are derived from the RequestBase class and this, along with the standard request implementation, are included below.

== RequestBase class ==
<source lang="php">

<?php
/* -------------------------------------------------------------
This file is part of FreeDESK

FreeDESK is (C) Copyright 2012 David Cutting

FreeDESK is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

FreeDESK is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with FreeDESK. If not, see www.gnu.org/licenses

For more information see www.purplepixie.org/freedesk/
-------------------------------------------------------------- */

/**
* Abstract Request base class for all request classes
**/
abstract class RequestBase
{
/**
* Current FreeDESK instance
**/
protected $DESK = null;

/**
* Current Request ID
**/
var $ID = 0;

/**
* Entity Data
**/
protected $Entity = null;

/**
* Updates
**/
protected $Updates = null;

/**
* Constructor
* @param mixed &$freeDESK Current FreeDESK instance
**/
function RequestBase(&$freeDESK)
{
$this->DESK = &$freeDESK;
}

/**
* Create a request
* @param int $customer Customer ID
* @param string $update Initial Update
* @param int $class Request Class
* @param int $status Request status
* @param int $priority Priority Code (optional, default 0)
* @param int $group Request Group (optional, default 0)
* @param string $assign Assigned user (optional, default "")
* @return string Request ID
**/
abstract function Create($customer, $update, $class, $status, $priority=0, $group=0, $assign="");

/**
* Update a request
* @param string $update Update text
* @param bool $public Public update (optional, default false)
**/
abstract function Update($update, $public=false);

/**
* Change a request status
* @param int $status New status
* @param bool $public Public update (optional, default false)
**/
abstract function Status($status, $public=false);

/**
* Assign a request
* @param int $group Group ID
* @param string $username Username (optional, default "")
* @param bool $public Public update (optional, default false)
**/
abstract function Assign($group, $username="", $public=false);

/**
* Attach a file
* @param int $fileid File ID
* @param bool $public Public update (optional, default false)
**/
abstract function Attach($fileid, $public=false);

/**
* Output XML
* @return string xml output
* @param bool $header Put XML header on output (optional, default false)
**/
abstract function XML($header=false);

/**
* Set an entity value
* @param string $field Field ID
* @param string $value Value
**/
function Set($field, $value)
{
if ($this->Entity == null)
$this->Entity = new Entity($this->DESK);
$this->Entity->Set($field, $value);
}

/**
* Get an entity value
* @param string $field Field ID
* @return mixed Value
**/
function Get($field)
{
$data = $this->Entity->GetData();
if (isset($data[$field]))
return $data[$field];
else
return false;
}

/**
* Load updates for our ID
**/
function LoadUpdates()
{
$q="SELECT * FROM ".$this->DESK->Database->Table("update")." WHERE ";
$q.=$this->DESK->Database->Field("requestid")."=".$this->DESK->Database->Safe($this->ID)." ";
$q.="ORDER BY ".$this->DESK->Database->Field("updateid")." DESC";

$this->Updates = array();

$r=$this->DESK->Database->Query($q);

while ($row=$this->DESK->Database->FetchAssoc($r))
$this->Updates[] = $row;

$this->DESK->Database->Free($r);
}

/**
* Get updates
* @return array Updates
**/
function GetUpdates()
{
if ($this->Updates == null)
$this->LoadUpdates();
return $this->Updates;
}

}
?>
</source>

== Inbuilt Standard Request Class ==
<source lang="php">

<?php
/* -------------------------------------------------------------
This file is part of FreeDESK

FreeDESK is (C) Copyright 2012 David Cutting

FreeDESK is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

FreeDESK is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with FreeDESK. If not, see www.gnu.org/licenses

For more information see www.purplepixie.org/freedesk/
-------------------------------------------------------------- */

/**
* Request class for all standard requests
**/
class Request extends RequestBase
{

/**
* Constructor
* @param mixed &$freeDESK Current FreeDESK instance
**/
function Request(&$freeDESK)
{
parent::RequestBase($freeDESK);
}

/**
* Create a request
* @param int $customer Customer ID
* @param string $update Initial Update
* @param int $class Request Class
* @param int $status Initial request status
* @param int $priority Priority code (optional, default 0)
* @param int $group Request Group (optional, default 0)
* @param string $assign Assigned user (optional, default "")
* @return string Request ID
**/
function Create($customer, $update, $class, $status, $priority=0, $group=0, $assign="")
{
if (!is_numeric($class))
$class=1;
$q="INSERT INTO ".$this->DESK->Database->Table("request");
$q.="(".$this->DESK->Database->Field("customer").",";
$q.=$this->DESK->Database->Field("assignteam").",";
$q.=$this->DESK->Database->Field("assignuser").",";
$q.=$this->DESK->Database->Field("class").",";
$q.=$this->DESK->Database->Field("openeddt").",";
$q.=$this->DESK->Database->Field("priority").",";
$q.=$this->DESK->Database->Field("status").") ";
$q.="VALUES(";
$q.=$this->DESK->Database->Safe($customer).",";
$q.=$this->DESK->Database->SafeQuote($group).",";
$q.=$this->DESK->Database->SafeQuote($assign).",";
$q.=$this->DESK->Database->SafeQuote($class).",";
$q.="NOW(),";
$q.=$this->DESK->Database->Safe($priority).",";
$q.=$this->DESK->Database->Safe($status).")";

$this->DESK->Database->Query($q);

$this->ID = $this->DESK->Database->InsertID();

$this->Update($update, true);

return $this->ID;
}

/**
* Update a request
* @param string $update Update text
* @param bool $public Public update (optional, default false)
**/
function Update($update, $public=false)
{
if ($this->ID <= 0)
return false;
if ($this->DESK->ContextManager->Session == null)
return false;

$q="INSERT INTO ".$this->DESK->Database->Table("update")."(";
$q.=$this->DESK->Database->Field("requestid").",";
$q.=$this->DESK->Database->Field("update").",";
$q.=$this->DESK->Database->Field("public").",";
$q.=$this->DESK->Database->Field("updateby").",";
$q.=$this->DESK->Database->Field("updatedt").") ";
$q.="VALUES(";
$q.=$this->DESK->Database->Safe($this->ID).",";
$q.=$this->DESK->Database->SafeQuote($update).",";
if ($public)
$p=1;
else
$p=0;
$q.=$p.",";
$q.="\"".$this->DESK->ContextManager->Session->NiceName()."\",";
$q.="NOW())";

$this->DESK->Database->Query($q);
}

/**
* Change a request status
* @param int $status New status
* @param bool $public Public update (optional, default false)
**/
function Status($status, $public=false)
{
$list = $this->DESK->RequestManager->StatusList();

if (isset($list[$status]))
{
$q="UPDATE ".$this->DESK->Database->Table("request")." SET ";
$q.=$this->DESK->Database->Field("status")."=".$this->DESK->Database->Safe($status);
if ($status == 0)
$q.=",".$this->DESK->Database->Field("closeddt")."=NOW()";
$q.=" WHERE ".$this->DESK->Database->Field("requestid")."=".$this->DESK->Database->Safe($this->ID);
$this->DESK->Database->Query($q);

$update="Status changed to ".$list[$status];
$this->Update($update, $public);
}
}

/**
* Assign a request
* @param int $group Group ID
* @param string $username Username (optional, default "")
* @param bool $public Public update (optional, default false)
**/
function Assign($group, $username="", $public=false)
{
$q="UPDATE ".$this->DESK->Database->Table("request")." SET ";
$q.=$this->DESK->Database->Field("assignteam")."=".$this->DESK->Database->Safe($group).",";
$q.=$this->DESK->Database->Field("assignuser")."=".$this->DESK->Database->SafeQuote($username)." WHERE ";
$q.=$this->DESK->Database->Field("requestid")."=".$this->DESK->Database->Safe($this->ID);
$this->DESK->Database->Query($q);

$teams = $this->DESK->RequestManager->TeamList();
$users = $this->DESK->RequestManager->UserList();
$assign = "";

if (isset($teams[$group]))
$assign.=$teams[$group];
else if ($group == 0)
$assign.=$this->DESK->Lang->Get("unassigned");

if ($username != "" && isset($users[$username]))
{
if ($assign != "")
$assign.=" > ";
$assign.=$users[$username];
}

$update = $this->DESK->Lang->Get("assigned_to")." ".$assign;

$this->Update($update, $public);
}

/**
* Attach a file
* @param int $fileid File ID
* @param bool $public Public update (optional, default false)
**/
function Attach($fileid, $public=false)
{
//
}

/**
* Output XML
* @return string xml output
* @param bool $header Put XML header on output (optional, default false)
**/
function XML($header=false)
{
$data = $this->Entity->GetData();
$xml = new xmlCreate();
$xml->startElement("request");
$xml->xmlArray($data);
$xml->endElement("request");
return $xml->getXML($header);
}

}
?>
</source>

Logging Module

2012-08-22T00:01:23Z

Dave: Created page with "Logging modules provide a method for the FreeDESK log (syslog) to be outputted and stored. The default method uses a database table (syslog). All logging modules must be deri..."

Logging modules provide a method for the FreeDESK log (syslog) to be outputted and stored. The default method uses a database table (syslog).

All logging modules must be derived from the base class LogMethodBase.

The inbuilt method logging to a database table as an example is as follows:

<source lang="php">

<?php
/* -------------------------------------------------------------
This file is part of FreeDESK

FreeDESK is (C) Copyright 2012 David Cutting

FreeDESK is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

FreeDESK is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with FreeDESK. If not, see www.gnu.org/licenses

For more information see www.purplepixie.org/freedesk/
-------------------------------------------------------------- */

/**
* LogMethodDB implements database-level logging
**/
class LogMethodDB extends LogMethodBase
{
/**
* FreeDESK instance
**/
private $DESK = null;

/**
* Constructor
* @param mixed $freeDESK FreeDESK instance
**/
function LogMethodDB(&$freeDESK)
{
$this->DESK = &$freeDESK;
$this->DESK->PluginManager->Register(new Plugin(
"Core Database Logging", "0.01", "Log", "Database", "LogMethodDB" ));
}

/**
* Log an event
* @param string $event Event description
* @param string $class Event class
* @param string $type Event type (optional, default "")
* @param int $level Event level (0 = fatal, 10 = low priority info only) (optional, default 10)
**/
function Log($event, $class, $type="", $level=10)
{
if (strlen($event)>254)
$event=substr($event,0,251)."...";
$q="INSERT INTO ".$this->DESK->Database->Table("syslog")."(".$this->DESK->Database->Field("event_dt").",";
$q.=$this->DESK->Database->Field("event").",".$this->DESK->Database->Field("event_class").",";
$q.=$this->DESK->Database->Field("event_type").",".$this->DESK->Database->Field("event_level").") ";
$q.="VALUES(NOW(),\"".$this->DESK->Database->Safe($event)."\",\"".$this->DESK->Database->Safe($class)."\",";
$q.="\"".$this->DESK->Database->Safe($type)."\",".$this->DESK->Database->Safe($level).")";

// Log into DB ensure report flag is false to avoid infinite loop if SQL error in this method
$this->DESK->Database->Query($q, false);
}

}

?>
</source>

Database Module

2012-08-21T23:59:42Z

Dave: Created page with "Database modules provide the ability for different underlying databases to be used. They handle the connection, escaping and some other functionality. The default shipped mod..."

Database modules provide the ability for different underlying databases to be used. They handle the connection, escaping and some other functionality.

The default shipped module supports MySQL and any alternatives must be derived from DatabaseBase. The base class and MySQL implementation are included below.

The DatabaseBase also includes the QueryBuilder class which can be used anywhere in the system to build SQL queries easily (the database implementation must therefore support QueryBuilder objects for SQL construction).

== DatabaseBase Base Class ==

<source lang="php">

<?php
/* -------------------------------------------------------------
This file is part of FreeDESK

FreeDESK is (C) Copyright 2012 David Cutting

FreeDESK is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

FreeDESK is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with FreeDESK. If not, see www.gnu.org/licenses

For more information see www.purplepixie.org/freedesk/
-------------------------------------------------------------- */
/**
* Database Query Type
**/
abstract class QueryType
{
const Equal = 0;
const Like = 1;
const MoreThan = 2;
const MoreThanEqual = 3;
const LessThan = 4;
const LessThanEqual = 5;
const NotEqual = 6;

const OpenBracket = 100;
const CloseBracket = 101;

const opAND = 200;
const opOR = 201;
}

/**
* Query Builder Class
**/
class QueryBuilder
{
/**
* Query items array
**/
var $items = array();

/**
* Limit Flag
**/
var $limit = false;

/**
* Start (for limit)
**/
var $start = 0;

/**
* Entries (for limit)
**/
var $entries = 30;

/**
* Order Flag
**/
var $order = false;

/**
* Order fields
**/
var $orderlist = array();

/**
* Add item
* @param string $field Field
* @param mixed $type QueryType const
* @param mixed $value Value
**/
function Add($field, $type, $value)
{
$this->items[] = array(
"field" => $field,
"type" => $type,
"value" => $value );
}

/**
* Add an order field
* @param string $field Field
* @param bool $asc Ascending (optional, default true) - false is descending
**/
function AddOrder($field, $asc = true)
{
if (!$this->order)
$this->order = true;
$this->orderlist[$field]=$asc;
}

/**
* Open bracket
**/
function OpenBracket()
{
$this->items[] = array("type" => QueryType::OpenBracket);
}

/**
* Close bracket
**/
function CloseBracket()
{
$this->items[] = array("type" => QueryType::CloseBracket);
}

/**
* Add operation
* @param mixed $operation Op of type QueryType
**/
function AddOperation($operation)
{
$this->items[] = array("type" => $operation);
}
}

/**
* DatabaseBase is the abstract base class for database system implementations
**/

abstract class DatabaseBase
{
/**
* Constructor
* @param object $freeDESK FreeDESK instance
**/
//abstract function DatabaseBase(&$freekDESK);

/**
* Connect
* @param string $server Database server
* @param string $username Database username
* @param string $password Database password
* @param string $database Database name
* @param string $prefix Database table prefix (optonal, default "")
* @return bool Successful connection or not
**/
abstract function Connect($server, $username, $password,
$database, $prefix="");

/**
* Disconnect
**/
abstract function Disconnect();

/**
* Return table name with correct prefix and escaping
* @param string $table table un-prefixed
* @return string table with prefix and escape
**/
abstract function Table($table);

/**
* Sanitise user-input using correct escaping
* @param string $input user input
* @return string Sanitised output
**/
abstract function Safe($input);

/**
* Sanitise user-input string and quote
* @param string $input user input
* @return string Sanitised quoted output
**/
abstract function SafeQuote($input);

/**
* Contain a field correctly
* @param string $field The field name
* @return string Escaped field
**/
abstract function Field($field);

/**
* Escape and contain a field correctly
* @param string $value The value of the field
* @return string Escaped and prefixed+suffixed data
**/
function FieldSafe($value)
{
return $this->Field($this->Safe($value));
}

/**
* Perform a query
* @param string $query SQL query
* @param bool $report Record any errors using LoggingEngine (optonal, default true)
* @return mixed Results of query
**/
abstract function Query($query, $report=true);

/**
* Number of rows affected by last query
* @return int number of rows affected
**/
abstract function RowsAffected();

/**
* Number of rows in a result set
* @param mixed $result Result set
* @return int number of rows in the set
**/
abstract function NumRows(&$result);

/**
* Fetch next associated array from result set
* @param mixed $result Result Set
* @return array Assocative Array of Results
**/
abstract function FetchAssoc(&$result);

/**
* Free a result set
* @param mixed $result Result Set
**/
abstract function Free(&$result);

/**
* Return an error flag
* @return bool Experienced error on last command
**/
abstract function Error();

/**
* Last error code
* @return int Error code
**/
abstract function ErrorCode();

/**
* Last error description
* @return string Error description
**/
abstract function ErrorDescription();

/**
* Details of the last error
* @return string Code and error description
**/
function LastError()
{
return $this->ErrorCode().": ".$this->ErrorDescription();
}

/**
* The last inserted ID
* @return mixed Last inserted ID
**/
abstract function InsertID();

/**
* Generate a clause from a QueryBuilder object
* @param object &$query QueryBuilder object
* @return string query string
**/
abstract function Clause(&$query);

}

?>
</source>

== MySQL Database Implementation ==

<source lang="php">

<?php
/* -------------------------------------------------------------
This file is part of FreeDESK

FreeDESK is (C) Copyright 2012 David Cutting

FreeDESK is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

FreeDESK is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with FreeDESK. If not, see www.gnu.org/licenses

For more information see www.purplepixie.org/freedesk/
-------------------------------------------------------------- */

/**
* MySQL concrete implementation of DatabaseBase
**/

class MySQL extends DatabaseBase
{
/**
* Pointer to the FreeDESK instance
**/
private $DESK = null;
/**
* MySQL data connection
**/
private $connection = null;

/**
* Table prefix
**/
var $prefix = "";

/**
* Constructor
* @param object $freeDESK FreeDESK instance
**/
function MySQL(&$freeDESK)
{
$this->DESK = &$freeDESK;

$this->DESK->PluginManager->Register(new Plugin(
"MySQL Database Engine","0.01","Core","DB" ));
}

/**
* Connect
* @param string $server Database server
* @param string $username Database username
* @param string $password Database password
* @param string $database Database name
* @param string $prefix Database table prefix (optonal, default "")
* @return bool Successful connection or not
**/
function Connect($server, $username, $password,
$database, $prefix="")
{
$this->prefix = $prefix;

$this->connection = mysql_connect($server, $username, $password);
if ($this->connection <= 0) return false;

if (!mysql_select_db($database, $this->connection))
return false;

return true;
}

/**
* Disconnect
**/
function Disconnect()
{
mysql_close($this->connection);
}

/**
* Return table name with correct prefix and escaping
* @param string $table table un-prefixed
* @return string table with prefix and escape
**/
function Table($table)
{
return "`".$this->prefix.$table."`";
}

/**
* Sanitise user-input using correct escaping
* @param string $input user input
* @return string Sanitised output
**/
function Safe($input)
{
return mysql_real_escape_string($input, $this->connection);
}

/**
* Sanitise user-input string and quote
* @param string $input user input
* @return string Sanitised quoted output
**/
function SafeQuote($input)
{
return "\"".$this->Safe($input)."\"";
}

/**
* Contain a field correctly
* @param string $field The field name
* @return string Escaped field
**/
function Field($field)
{
return "`".$field."`";
}

/**
* Escape and contain a field correctly
* @param string $value The value of the field
* @return string Escaped and prefixed+suffixed data
**/
function FieldSafe($value)
{
return $this->Field($this->Safe($value));
}

/**
* Perform a query
* @param string $query SQL query
* @param bool $report Record any errors using LoggingEngine (optonal, default true)
* @return mixed Results of query
**/
function Query($query, $report=true)
{
$result=mysql_query($query, $this->connection);

if ($report && $this->Error()) // has an error and to be reported
{
$err="Query Failed: ".$query;
$error="SQL Error: ".$this->LastError();
$this->DESK->LoggingEngine->Log($err, "SQL", "Fail", 1);
$this->DESK->LoggingEngine->Log($error, "SQL", "Error", 1);
}

return $result;
}

/**
* Number of rows affected by last query
* @return int number of rows affected
**/
function RowsAffected()
{
return mysql_affected_rows($this->connection);
}

/**
* Number of rows in a result set
* @param mixed $result Result set
* @return int number of rows in the set
**/
function NumRows(&$result)
{
return mysql_num_rows($result);
}

/**
* Fetch next associated array from result set
* @param mixed $result Result Set
* @return array Assocative Array of Results
**/
function FetchAssoc(&$result)
{
return mysql_fetch_assoc($result);
}

/**
* Free a result set
* @param mixed $result Result Set
**/
function Free(&$result)
{
mysql_free_result($result);
}

/**
* Return an error flag
* @return bool Experienced error on last command
**/
function Error()
{
if (mysql_errno($this->connection)>0)
return true;
return false;
}

/**
* Last error code
* @return int Error code
**/
function ErrorCode()
{
return mysql_errno($this->connection);
}

/**
* Last error description
* @return string Error description
**/
function ErrorDescription()
{
return mysql_error($this->connection);
}

/**
* The last inserted ID
* @return mixed Last inserted ID
**/
function InsertID()
{
return mysql_insert_id($this->connection);
}

/**
* Generate a clause from a QueryBuilder object
* @param object &$query QueryBuilder object
* @return string query string
**/
function Clause(&$query)
{
$c = "";
foreach($query->items as $item)
{
if (isset($item['field']))
{
if ($c!="")
$c.=" ";
$c.=$this->Field($item['field']);

switch($item['type'])
{
case QueryType::Equal:
$c.="=";
break;
case QueryType::Like:
$c.=" LIKE ";
break;
case QueryType::MoreThan:
$c.=" > ";
break;
case QueryType::MoreThanEqual:
$c.=" >= ";
break;
case QueryType::LessThan:
$c.=" < ";
break;
case QueryType::LessThanEqual:
$c.=" <= ";
break;
case QueryType::NotEqual;
$c.=" != ";
break;
}

$c.=$item['value'];
}
else
{
switch($item['type'])
{
case QueryType::OpenBracket:
$c.=" ( ";
break;
case QueryType::CloseBracket:
$c.=" ) ";
break;
case QueryType::opAND:
$c.=" AND ";
break;
case QueryType::opOR:
$c.=" OR ";
break;
}
}
}

if ($c=="")
$c="1";

return $c;
}
}

?>
</source>

Authentication Modules

2012-08-21T23:55:57Z

Dave: Created page with "Authentication modules provide an alternative authentication method for analyst users. The following are the base class (that must be extended for an authentication class) an..."

Authentication modules provide an alternative authentication method for analyst users.

The following are the base class (that must be extended for an authentication class) and the included standard authentication class as an example.

== Authentication Base Class ==

<source lang="php">

<?php
/* -------------------------------------------------------------
This file is part of FreeDESK

FreeDESK is (C) Copyright 2012 David Cutting

FreeDESK is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

FreeDESK is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with FreeDESK. If not, see www.gnu.org/licenses

For more information see www.purplepixie.org/freedesk/
-------------------------------------------------------------- */

/**
* AuthMethodBase is the abstract base class for authentication methods
**/
abstract class AuthMethodBase extends FreeDESK_PIM
{
/**
* AuthMethodBase Constructor
* @param mixed $freeDESK FreeDESK instance
**/
function AuthMethodBase(&$freeDESK)
{
parent::FreeDESK_PIM(&$freeDESK, "", "", 0);
}

/**
* Authenticate a user/customer session
* @param int $type Type of Context (ContextType)
* @param string $username Username provided
* @param string $password Password provided
* @return bool True on success or false on failure
**/
abstract function Authenticate($type, $username, $password);
}
?>
</source>

== Inbuilt Standard Authentication ==

<source lang="php">

<?php
/* -------------------------------------------------------------
This file is part of FreeDESK

FreeDESK is (C) Copyright 2012 David Cutting

FreeDESK is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

FreeDESK is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with FreeDESK. If not, see www.gnu.org/licenses

For more information see www.purplepixie.org/freedesk/
-------------------------------------------------------------- */

/**
* AuthMethodStandard is the standard (database-based) authentication method
**/
class AuthMethodStandard extends AuthMethodBase
{
/**
* AuthMethodStandard Constructor
* @param mixed $freeDESK FreeDESK instance
**/
function AuthMethodStandard(&$freeDESK)
{
parent::AuthMethodBase($freeDESK);
}

/**
* Authenticate a user/customer session
* @param int $type Type of Context (ContextType)
* @param string $username Username provided
* @param string $password Password provided
* @return bool True on success or false on failure
**/
function Authenticate($type, $username, $password)
{
$valid=false; // default to failed

if ($type == ContextType::User)
{
$password=$this->DESK->BaseConfig->pwd_Hash.$password; // add the hash to the password
$q="SELECT * FROM ".$this->DESK->Database->Table("user")." WHERE ";
$q.=$this->DESK->Database->Field("username")."=\"".$this->DESK->Database->Safe($username)."\" AND ";
$q.=$this->DESK->Database->Field("password")."=MD5(\"".$this->DESK->Database->Safe($password)."\") ";
$q.="LIMIT 0,1";

$r=$this->DESK->Database->Query($q);

if ($user = $this->DESK->Database->FetchAssoc($r))
$valid=true;

$this->DESK->Database->Free($r);
}

// TODO: Customer Authentication

return $valid;
}

/**
* Set a standard user password - note no security here and that this is NOT a AutoMethodBase overrided function
* @param string $username Username
* @param string $password Password
**/
function SetPassword($username, $password)
{
$password=$this->DESK->BaseConfig->pwd_Hash.$password;
$q="UPDATE ".$this->DESK->Database->Table("user")." SET ";
$q.=$this->DESK->Database->Field("password")."=MD5(\"".$this->DESK->Database->Safe($password)."\") ";
$q.="WHERE ".$this->DESK->Database->Field("username")."=\"".$this->DESK->Database->Safe($username)."\"";
$this->DESK->Database->Query($q);
}

/**
* Exec function (static)
* @param mixed $DESK Current FreeDESK instance
**/
static function Exec(&$DESK)
{
$plugin = new Plugin();
$plugin->name="Standard Authentication";
$plugin->version="0.01";
$plugin->type="Auth";
$plugin->subtype="standard";
$plugin->classname="AuthMethodStandard";
$DESK->PluginManager->Register($plugin);
}
}
?>
</source>

Developing Plugin Modules

2012-08-21T23:53:12Z

Dave:

Plugin modules are the heart of FreeDESK extensibility and are developed in PHP. All plugin modules extend the base class FreeDESK_PIM and provide some defined interfaces.

Plugins can register functionality they provide in the main system, register additional pages and menu options for display, register custom API modes and handle request events.

= Plugin Modules (PIMs) =

PIMs provide some or all of the functionality listed in the FreeDESK_PIM module. For a plugin to work it must be installed in a named directory within the plugin folder, have a main PHP file of the same name and the main PIM class within that file of the same name.

<source lang="php">

<?php
/* -------------------------------------------------------------
This file is part of FreeDESK

FreeDESK is (C) Copyright 2012 David Cutting

FreeDESK is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

FreeDESK is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with FreeDESK. If not, see www.gnu.org/licenses

For more information see www.purplepixie.org/freedesk/
-------------------------------------------------------------- */

/**
* FreeDESK_PIM is the abstacr base class for all PIM components
**/
abstract class FreeDESK_PIM
{
/**
* FreeDESK instance
**/
protected $DESK = null;

/**
* File path for PIM
**/
protected $filepath = "";

/**
* Web path for PIM
**/
protected $webpath = "";

/**
* ID for PIM
**/
protected $ID = 0;

/**
* Main Constructor
* @param mixed $freeDESK FreeDESK instance
* @param string $filepath Path to plugin directory (filebase)
* @param string $webpath Path to plugin directory (webpath)
* @param int $id Internal FreeDESK ID for PIM
**/
function FreeDESK_PIM(&$freeDESK, $filepath, $webpath, $id)
{
$this->DESK = &$freeDESK;
$this->filepath = $filepath;
$this->webpath = $webpath;
$this->ID = $id;
}

/**
* Start (when an instance is started from within the system and is installed - to be overriden
**/
function Start()
{
//
}

/**
* Install - to be overriden
**/
function Install()
{
//
}

/**
* Activate - to be overriden
**/
function Activate()
{
//
}

/**
* De-Activate - to be overriden
**/
function Deactivate()
{
//
}

/**
* Uninstall - to be overriden
**/
function Uninstall()
{
//
}

/**
* API Call - to be overriden
* @param string $mode API Mode
**/
function API($mode)
{
//
}

/**
* Event Call - to be overriden
* @param string $event Event
* @param mixed &$data Event data (dependent on the event)
**/
function Event($event, &$data)
{
//
}

/**
* Build any menu items needed - to be overriden
**/
function BuildMenu()
{
//
}

/**
* Page has been called for this plugin - to be overriden
* @param string $page Page identifier
**/
function Page($page)
{
//
}

/**
* Static exec/registration function to list provided interfaces
* @param mixed $DESK Reference to current FreeDESK instance
**/
static function Exec(&$DESK)
{
//
}

}
?>
</source>

The filepath, webpath and ID are provided by the system automatically on startup and can then be used within the PIM.

= Example =

The following provides a simple example of a plugin providing some workload reporting. It would be installed as follows:
* Folder: plugins/workload
* Main file: plugins/workload/workload.php
* Main class: plugins/workload/workload.php::workload

<source lang="php">

<?php
/* -------------------------------------------------------------
This file is part of FreeDESK

FreeDESK is (C) Copyright 2012 David Cutting

FreeDESK is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

FreeDESK is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with FreeDESK. If not, see www.gnu.org/licenses

For more information see www.purplepixie.org/freedesk/
-------------------------------------------------------------- */

// A new class for the PIM extending FreeDESK_PIM,
// named the same as the directory and filename
class workload extends FreeDESK_PIM
{
// The startup method - register functionalityh
function Start()
{
// Register ourselves as a plugin
$this->DESK->PluginManager->Register(new Plugin(
"Workload", "0.01", "Reporting" ));
// Register a page which will be displayed
$this->DESK->PluginManager->RegisterPIMPage("workload_page",
$this->ID);
// Register an API call for details
$this->DESK->PluginManager->RegisterPIMAPI("workload_api",
$this->ID);
// Add a permission for this action
$this->DESK->PermissionManager->Register("workload", false);
// Register a JS script (workload.js) in our directory for inclusion
// Note the file can be called anything we like or even not in the
// directory (unlike this PHP file)
$jspath = $this->webpath . "workload.js";
$this->DESK->PluginManager->RegisterScript($jspath);
// Register a CSS file (workload.css)
$csspath = $this->webpath . "workload.css";
$this->DESK->PluginManager->RegisterCSS($csspath);
}
// The method to add menu items
function BuildMenu()
{
// Check if the permission is allowed or don't show the menu
if ($this->DESK->ContextManager->Permission("workload"))
{
// Check if the reporting menu already exists, add if not
$currentItems = $this->DESK->ContextManager->MenuItems();
if (!isset($currentItems['reporting']))
{
$repmenu = new MenuItem();
$repmenu->tag = "reporting";
$repmenu->display = "Reporting";
$this->DESK->ContextManager->AddMenuItem
("reporting", $repmenu);
}

// Built the menu item for this plugin
$sReport = new MenuItem();
$sReport->tag="workload";
$sReport->display="Workload";
// Set the action for the click
// (show the page 'workload' registered above)
$sReport->onclick = "DESK.loadSubpage('workload_page');";
// Add the menu option to the reporting menu
$this->DESK->ContextManager->AddMenuItem("reporting",$sReport);
}
}
// Handle page requests (specifically the workload page)
function Page($page)
{
if ($page == "workload_page" // page is the workload page
&& // and permission for this page
$this->DESK->ContextManager->Permission("workload"))
{
// Page title
echo "<h3>Workload</h3>\n";
// Team and user list
$teamuser = $this->DESK->RequestManager->TeamUserList();
// Iterate through this list and display workload info
echo "<table>\n";
foreach($teamuser as $teamid => $teamdata)
{
// Counter for the team
$teamcount=0;
echo "<tr>\n";
echo "<td>\n";
echo "<b>".$teamdata['name']."</b>\n";
echo "</td>\n";
echo "<td><b>\n";
// Get the requests assigned to just the team
$requests = $this->DESK->RequestManager->FetchAssigned($teamid, "");
$reqcount = sizeof($requests);
echo $reqcount;
// Increment team counter
$teamcount += $reqcount;
echo "</b></td>";
// Detail link for the team
$js="Workload.Detail(".$teamid.",'');";
echo "<td>\n";
echo "<a href=\"#\" onclick=\"".$js."\">Detail</a>\n";
echo "</td>";
echo "</tr>";
// Detail row for the team
echo "<tr><td colspan=\"3\" id=\"detail_".$teamid."_\"></td></tr>\n";
// Iterate through the users in the team
foreach($teamdata['items'] as $user => $userdata)
{
echo "<tr>\n";
echo "<td>\n";
echo $userdata['realname'];
echo "</td>\n";
echo "<td>\n";
// Requests for this user and team
$requests = $this->DESK->RequestManager->FetchAssigned($teamid, $user);
$reqcount = sizeof($requests);
echo $reqcount;
// Increment team counter
$teamcount+=$reqcount;
echo "</td>\n";
// Detail link for the team and user
$js="Workload.Detail(".$teamid.",'".$user."');";
echo "<td>\n";
echo "<a href=\"#\" onclick=\"".$js."\">Detail</a>\n";
echo "</td>";
echo "</tr>\n";
// Detail row for the user
echo "<tr><td colspan=\"3\" id=\"detail_".$teamid."_".$user."\"></td></tr>\n";
}
// The team total
echo "<tr><td><b>Total</b></td><td><b>".$teamcount."</b></td></tr>\n";
// A spacer
echo "<tr><td colspan=\"3\"><hr class=\"workload\"></td></tr>\n";
}
echo "</table>\n";
}
}
// API Handler
function API($mode)
{
if ($mode == "workload_api" // Correct API Mode
&& // and permission for workload
$this->DESK->ContextManager->Permission("workload"))
{
// Get the team and user requested
$teamid = isset($_REQUEST['teamid']) ? $_REQUEST['teamid'] : 0;
$username = isset($_REQUEST['username']) ? $_REQUEST['username'] : "";
// Get the assigned requests
$reqs = $this->DESK->RequestManager->FetchAssigned($teamid,$username);
// Get the list of priorities
$pris = $this->DESK->RequestManager->GetPriorityList();
// Our output array with unknown default
$out = array(0=>array("name"=>"Unknown","total"=>0));
// Iterate through the requests
foreach($reqs as $req)
{
// Get the priority
$pri = $req->Get("priority");
// Check if exists and add to totals
if (isset($pris[$pri])) // valid
{
if (isset($out[$pri]))
$out[$pri]['total']++;
else
$out[$pri]=array(
"name"=>$pris[$pri]['priorityname'],
"total"=>1 );
}
else
$out[0]["total"]++;
}
// Build the HTML
$html = "";
// For each detail line
foreach($out as $line)
{
$html.=$line["name"].": ".$line["total"]."<br />";
}
// Create the XML output
// XML creation object
$xml = new xmlCreate();
// Add a char element with CDATA encoding
$xml->charElement(
"data",
$html,
0,
false,
true );
// Output the XML with the header
$xml->echoXML(true);
// Exit (ensure no other output)
exit();
}
}

}
?>
</source>

Additionally support Javascript and CSS files are used as follows:

<source lang="javascript">
//The PIM Function
function workloadPIM()
{
// Last detail items asked for
var teamid = 0;
var username = "";

// Get detail for the given team and user
this.Detail = function(teamid, username)
{
// Set last requested items
this.teamid = teamid;
this.username = username;

// Create a ServerRequest object
var sr = new ServerRequest();
// Build the URL to the API
var url = "api.php?";
// Add the mode
url += "mode=workload_api";
// And the team and user detail
url += "&teamid="+teamid+"&username="+username;
// And the SID from FreeDESK
url += "&sid="+DESK.sid;
// Define the callback
sr.callback = Workload.Callback;
// Set the URL
sr.url = url;
// Set to XML
sr.xmlrequest = true;
// Call the API
sr.Post();
}

// The callback method (API response)
this.Callback = function(xml, additional)
{
// Check if the API has returned an error
if (DESK.isError(xml))
{
// Display error
Alerts.add(DESK.getError(xml), 2, 10);
// Exit
return;
} // no error so continue
// Strip the response from the server
var data = xml.getElementsByTagName("data")[0]
.firstChild.nodeValue;
// Get the element to display it in
var eleID = 'detail_'
+Workload.teamid
+"_"+Workload.username;
var ele = document.getElementById(eleID);
// And display the data
ele.innerHTML = data;
}
}
// Instantiate the workloadPIM object
var Workload = new workloadPIM();
</source>

<source lang="css">
hr.workload
{
color: green;
background-color: green;
border: 0;
}
</source>

For more examples look at the provided example plugins with the system.

Developing Plugin Modules

2012-08-21T23:52:09Z

Dave:

Developing Plugin Modules

2012-08-21T23:47:08Z

Dave:

Developing Plugin Modules

2012-08-21T23:46:49Z

Dave: Created page with "Plugin modules are the heart of FreeDESK extensibility and are developed in PHP. All plugin modules extend the base class FreeDESK_PIM and provide some defined interfaces. Pl..."

Developer Overview

2012-08-21T23:42:14Z

Dave: Created page with "Development of extensions to FreeDESK consists of developing plugin modules of PHP code which can fulfil a specific function (replacing or providing an additional method for i..."

Development of extensions to FreeDESK consists of developing plugin modules of PHP code which can fulfil a specific function (replacing or providing an additional method for inbuilt functionality) or add new functionality to the system.

Plugins are wrapped within specifically-named directory and file structures which then become available for installation and activation through the system administration plugin options (under System - System Administration in the main interface).

For information on developing specific areas see the following documents:

* [[Developing Plugin Modules]]
* [[Authentication Modules]]
* [[Database Module]]
* [[Logging Module]]
* [[Custom Requests]]
* [[Entity Modules]]

System Configuration

2012-08-21T22:46:29Z

Dave: Created page with "The system configuration is accessed through the System menu in the main interface when users have system administration permissions."

The system configuration is accessed through the System menu in the main interface when users have system administration permissions.

Priorities

2012-08-21T22:45:59Z

Dave: Created page with "Priorities can be configured through the system administration interface. When creating or editing a priority a target resolution can be set in hours, minutes and seconds. Th..."

Priorities can be configured through the system administration interface.

When creating or editing a priority a target resolution can be set in hours, minutes and seconds. This allows reporting to analyse if requests are being resolved within the set targets for the priority.

Priorities are a useful way for service desk staff to distinguish relative importance of requests and are intended to be setup (and assigned against requests) based upon your internal processes.

Statuses

2012-08-21T22:44:15Z

Dave: Created page with "Requests are assigned statuses and these can be configured through the system administration menu. Once a status has been created requests can be set (either on creation or u..."

Requests are assigned statuses and these can be configured through the system administration menu.

Once a status has been created requests can be set (either on creation or update) to this status which is displayed within the system interface. This allows distinguishing between requests which are awaiting action by a third party or similar.

Once a request is complete it's status can be set to Closed (this is a system-made setting which cannot be deleted unlike other types) and it will no longer be visible in the normal request lists.

Configuring Request Types

2012-08-21T22:42:35Z

Dave: Created page with "Request types are configured through the System Administration interface under the heading "request classes". Different classes of request have different names to distinguish..."

Request types are configured through the System Administration interface under the heading "request classes".

Different classes of request have different names to distinguish them (once created they will appear under the New Request options) and an associated "concrete" class.

The "concrete" class is the actual PHP code underlying the request which can be created and customised by the user. By default all requests use the standard "concrete" class type which comes included with the system (and is sufficient for most needs). For information on the creation see the [[Custom Requests|custom request]] page.

Requests

2012-08-21T22:40:25Z

Dave:

Requests are the core of FreeDESK and someone with the relevant permissions (such as an administrator) can view and update all the requests logged within the system.

Different types (classes) of request can be configured within the system for easy categorisation and also allowing for different "concrete" definitions in code of these requests, with specific or custom properties as explained in [[Configuring Request Types|the request configuration]].

Requests

2012-08-21T22:38:51Z

Dave: Created page with "Requests are the core of FreeDESK and someone with the relevant permissions (such as an administrator) can view and update all the requests logged within the system."

Requests are the core of FreeDESK and someone with the relevant permissions (such as an administrator) can view and update all the requests logged within the system.

Permissions

2012-08-21T22:37:08Z

Dave: Created page with "Permissions in FreeDESK operate on a granular most-specific model. Each user can have permissions assigned to it directly or be a member of a permissions group for easy bulk ..."

Permissions in FreeDESK operate on a granular most-specific model.

Each user can have permissions assigned to it directly or be a member of a permissions group for easy bulk administration.

A wide variety of operations are assigned a permission (these are either coded within the system or added automatically by plugins once installed). These permissions can be explicitly set (allowed or denied) on a per-user or per-group basis. If a permission is undefined then the next level of specificity is tested (hence the most-specific model).

When a permission is requested it is determined as follows:

* Is the permission set specifically for the user (allowed or denied), in which case this is used.
* Does the user have a default permission (allowed or denied), in which case this is used.
If the user is a member of a permission group:
* Is the permission set specifically for the group (allowed or denied), in which case this is used
* Does the group have a default permission (allowed or denied), in which case this is used
If no matching permission is found:
* Permission Denied

= Examples =

== One ==

The permission "one" is set as denied for the permission group, the user has it and default undefined.

Permission is denied.

== Two ==

The permission "two" is set as denied for the permission group, the user has it undefined but default is allowed.

The permission is allowed.

Customer Access

2012-08-21T22:32:03Z

Dave: Created page with "Customer access is provided through the customer portal. Customers can login to the interface (accessed either directly or by clicking on the customer link on the main page) a..."

Customer access is provided through the customer portal. Customers can login to the interface (accessed either directly or by clicking on the customer link on the main page) and entering their email address or username and password. Customer usernames and passwords are managed from within the customer entity editor (under the Entity menu).

The customer portal allows customers to view their existing request (updating any which are still open) as well as opening new requests (which are assigned to the Unassigned group).

The customer portal can be easily customised or a specific portal created based upon the code contained in the customer folder of the FreeDESK interface, there is very little PHP code which can just be cut and pasted and the HTML/CSS customised as seen fit.

Standard Users

2012-08-21T22:29:03Z

Dave: Created page with "Standard (analyst) users are those able to access the analyst portal (and use the API). Users are managed through the System Administration option available to administra..."

Standard (analyst) users are those able to access the analyst portal (and use the [[API]]).

Users are managed through the System Administration option available to administrators under the System menu of the interface.

Once users have been created they can be joined to a Team and also assigned [[Permissions|permissions]] which control what access that user has.

When assigned to a team the user will appear listed on the interface and assignment lists for that team.

To reset a user password open the user in the administration interface, enter a new password and click Save.

Users and Groups

2012-08-21T21:40:12Z

Dave:

FreeDESK has two core types of users, "standard users" (analysts or administrators) and "customer" users which are the customers the Service Desk supports and access the system through the [[Customer Portal]].

* [[Standard Users]]
* [[Customer Access]]
* [[Permissions]]

Users and Groups

2012-08-21T21:39:14Z

Dave: Created page with "* Standard Users * Customer Access * Permissions"

* [[Standard Users]]
* [[Customer Access]]
* [[Permissions]]

API request create

2012-08-21T21:38:12Z

Dave: Created page with "{{Infobox API | name = Request Create | mode = request_create | description = Create a New Request | parameters = class, customer, assign, update, status, priority | returned ..."

{{Infobox API
| name = Request Create
| mode = request_create
| description = Create a New Request
| parameters = class, customer, assign, update, status, priority
| returned = XML request ID or error
}}
This article details a FreeDESK [[API]] call.
= Description =
This call will create a new request
= Using the Call =
Pass in the following parameters using GET or POST
* class : Request Class (blank will use default)
* customer : Customer ID
* assign : Composite assignment string in the form TEAMID/USERNAME (or just TEAMID) for assignment
* update : Textual Update
* status : Status Code
* priority : Priority Code
For example
api.php?mode=request_create&class=1&customer=1&assign=0&update=A+Request&status=1&priority=1
= Returned Data =
XML containing either a request ID (see below) or a [[API XML Error|FreeDESK error on failure]].

Format of created request response:
<source lang="xml">
<request>ID</request>
</source>

API request update

2012-08-21T21:34:46Z

Dave: Created page with "{{Infobox API | name = Request Update | mode = request_update | description = Update a Request | parameters = requestid, update, status, assign | returned = XML success or err..."

{{Infobox API
| name = Request Update
| mode = request_update
| description = Update a Request
| parameters = requestid, update, status, assign
| returned = XML success or error
}}
This article details a FreeDESK [[API]] call.
= Description =
This call will update a request
= Using the Call =
Pass in the following parameters using GET or POST
* requestid : Request ID
* update : Textual update to request (optional, call be null or blank)
* status : New status for request (optional, can be null or blank)
* assign : Composite assignment string in the form TEAMID/USERNAME (or just a numeric team ID) - optional can be blank or null
For example
api.php?mode=request_update&requestid=1&update=Hello+World&status=0
= Returned Data =
XML containing either a [[XML Operation Confirmation]] or a [[API XML Error|FreeDESK error on failure]].

API entity create

2012-08-21T21:32:04Z

Dave: Created page with "{{Infobox API | name = Entity Create | mode = entity_create | description = Create an entity record | parameters = entity, [fields] | returned = XML success or error }} This a..."

{{Infobox API
| name = Entity Create
| mode = entity_create
| description = Create an entity record
| parameters = entity, [fields]
| returned = XML success or error
}}
This article details a FreeDESK [[API]] call.
= Description =
This call will create a stored entity record
= Using the Call =
Pass in the following parameters using GET or POST
* entity : Entity name
* [fields] : Field list in the format fieldname=value
For example
api.php?mode=entity_create&entity=customer&firstname=David
= Returned Data =
XML containing either a [[XML Operation Confirmation]] or a [[API XML Error|FreeDESK error on failure]].

API entity save

2012-08-21T21:31:16Z

Dave: Created page with "{{Infobox API | name = Entity Save | mode = entity_save | description = Save an entity record | parameters = entity, [fields] | returned = XML success or error }} This article..."

{{Infobox API
| name = Entity Save
| mode = entity_save
| description = Save an entity record
| parameters = entity, [fields]
| returned = XML success or error
}}
This article details a FreeDESK [[API]] call.
= Description =
This call will update a stored entity record
= Using the Call =
Pass in the following parameters using GET or POST
* entity : Entity name
* [fields] : Field list in the format fieldname=value
For example
api.php?mode=entity_save&entity=customer&customerid=1&firstname=David
Please note that you 'must' pass the keyfield for the entity unmodified for the record to be successfully updated.
= Returned Data =
XML containing either a [[XML Operation Confirmation]] or a [[API XML Error|FreeDESK error on failure]].

XML Operation Confirmation

2012-08-21T21:28:02Z

Dave: Created page with "An XML operation confirmation is returned from the API when an operation (or set of operations) has succeeded but no specific information needs to be returned. In general..."

An XML operation confirmation is returned from the [[API]] when an operation (or set of operations) has succeeded but no specific information needs to be returned.

In general these are simple update operations that don't require anything like a UID of a newly created object being returned. Such operations will return either an [[API XML Error]] or this success message.

The operation success message is formatted as follows:

<source lang="xml">
<operation>1</operation>
</source>

API

2012-08-21T19:04:41Z

Dave:

The following is a list of API calls that can be made to the API via HTTP(S).

Data can be passed either in the query string (GET) or as POST data. Returned data will be in XML as described for each individual call. The type of call is specified with the mode parameter. For all calls other than login an SID must be passed of a valid session.

The API script is api.php so requests are made to <nowiki>http://your.freedesk.path/api.php</nowiki>

= HTTP API Calls =

* [[API login|login]] - open a user session to the system
* [[API logout|logout]] - close a current session
* [[API requests_assigned|requests_assigned]] - list of requests assigned to a specific user/team or combination
* [[API entity_search|entity_search]] - search a data entity
* [[API entity_save|entity_save]] - save an entity
* [[API entity_create|entity_create]] - create an entity
* [[API request_create|request_create]] - create a request
* [[API request_update|request_update]] - update a request

For other built-in modes consult the source code directly.

API

2012-08-21T19:04:03Z

Dave:

The following is a list of API calls that can be made to the API via HTTP(S).

Data can be passed either in the query string (GET) or as POST data. Returned data will be in XML as described for each individual call. The type of call i specified with the mode parameter.

The API script is api.php so requests are made to <nowiki>http://your.freedesk.path/api.php</nowiki>

= HTTP API Calls =

* [[API login|login]] - open a user session to the system
* [[API logout|logout]] - close a current session
* [[API requests_assigned|requests_assigned]] - list of requests assigned to a specific user/team or combination
* [[API entity_search|entity_search]] - search a data entity
* [[API entity_save|entity_save]] - save an entity
* [[API entity_create|entity_create]] - create an entity
* [[API request_create|request_create]] - create a request
* [[API request_update|request_update]] - update a request

For other built-in modes consult the source code directly.

API entity search

2012-08-21T19:02:23Z

Dave:

{{Infobox API
| name = Entity Search
| mode = entity_search
| description = Search an Entity
| parameters = entity, [fields], start, limit
| returned = XML login error or session data
}}
This article details a FreeDESK [[API]] call.
= Description =
The entity_search call will search a registered entity (with valid permissions) and return matches
= Using the Call =
Pass in the following parameters using GET or POST
* entity : Entity
* start : Start (0 for beginning)
* limit : Limit number of results (default 30)
* [fields] : In the form of:
fieldname=value
For example
api.php?mode=entity_search&entity=customer&firstname=david
Would search the customer entity for records with the firstname of david (starting at the beginning and returning a max of 30 results)
= Returned Data =
XML containing search results on success or a [[API XML Error]] on failure.

Example returned output on success:
<source lang="xml">
<search-results>
<meta>
<field-data>
<id>customerid</id>
<name>Customer ID</td>
</field-data>
<field-data>
<id>firstname</id>
<name>First Name</name>
</field-data>
<field-data>
<id>lastname</id>
<name>Last Name</name>
</field-data>
<keyfield>customerid</keyfield>
</meta>
<entity>
<field id="customerid">1</field>
<field id="firstname">David</field>
<field id="lastname">Cutting</field>
</entity>
</search-results>
</source>

API entity search

2012-08-21T18:58:55Z

Dave: Created page with "{{Infobox API | name = Entity Search | mode = entity_search | description = Search an Entity | parameters = entity, [fields], start, limit | returned = XML login error or sess..."

API requests assigned

2012-08-21T18:53:03Z

Dave: Created page with "{{Infobox API | name = Requests Assigned | mode = requests_assigned | description = Return Requests Assigned to Specific User/Team | parameters = teamid, username, sort, order..."

{{Infobox API
| name = Requests Assigned
| mode = requests_assigned
| description = Return Requests Assigned to Specific User/Team
| parameters = teamid, username, sort, order
| returned = XML request list
}}
This article details a FreeDESK [[API]] call.
= Description =
This call allows the fetching of sets of requests assigned to a specific team and/or user
= Using the Call =
Pass in the following parameters using GET or POST
* teamid : Team ID (null or 0 for no team)
* username : Username of analyst (null or blank for no user)
* sort : Field name on which to sort the results (blank or null for default)
* order : A for ASC or D for DESC (optional, defaults to ASC)
For example
api.php?mode=requests_assigned&teamid=3&username=someuser
Would return the requests assigned to someuser 'within' teamid 3
= Returned Data =
A request-list block of results

API login

2012-08-21T18:49:24Z

Dave:

{{Infobox API
| name = login
| mode = login
| description = Open a user session
| parameters = username, password
| returned = XML login error or session data
}}
This article details a FreeDESK [[API]] call.
= Description =
The login call allows the establishment of a ContextType::User session
= Using the Call =
Pass in the following parameters using GET or POST
* username : Analyst username
* password : Analyst password
For example
api.php?mode=login&username=someuser&password=theirpassword
= Returned Data =
XML containing either the SID on success or a [[API XML Error|FreeDESK error on failure]].

API logout

2012-08-21T18:48:48Z

Dave:

{{Infobox API
| name = logout
| mode = logout
| description = Destroy a user session
| parameters = sid
| returned = XML confirming logout
}}
This article details a FreeDESK [[API]] call.
= Description =
The login call allows the destruction of a ContextType::User session
= Using the Call =
Pass in the following parameters using GET or POST
* sid : Session ID
For example
api.php?mode=logout&sid=XYZ
= Returned Data =
Logout confirmation

API logout

2012-08-21T18:48:13Z

Dave: Created page with "{{Infobox API | name = logout | mode = logout | description = Destroy a user session | parameters = sid | returned = XML confirming logout }} = Description = The login call al..."

{{Infobox API
| name = logout
| mode = logout
| description = Destroy a user session
| parameters = sid
| returned = XML confirming logout
}}
= Description =
The login call allows the destruction of a ContextType::User session
= Using the Call =
Pass in the following parameters using GET or POST
* sid : Session ID
For example
api.php?mode=logout&sid=XYZ
= Returned Data =
Logout confirmation

API XML Error

2012-08-21T18:46:03Z

Dave:

A FreeDESK XML error will contain an error code and textual description.

== Example ==
<source lang="xml">
<error>
<code>XXXX</code>
<text>Textual Error Description</text>
</error>
</source>

== Error Codes ==
The following is a list of in-built error codes based upon the ErrorCode class. You may use your own error codes which can either be captured by your own receipt handling code or will be detected client-side with the DESK.isError(xml) call.

=== 101 ErrorCode::FailedLogin ===
Login has failed

=== 102 ErrorCode::SessionExpired ===
Attempt to validate client SID has failed as it has expired (or has been deleted, or is illegal)

=== 201 ErrorCode::UnknownMode ===
The API has been called with an unknown or unregistered mode

=== 300 ErrorCode::EntityError ===
An error has occurred when fetching/searching/writing an entity. The system logs will provide more information.

=== 403 ErrorCode::Forbidden ===
Current user context does not have access to the mode or resource requested

=== 404 ErrorCode::ResourceNotFound ===
A resource was asked for that does not exist or has not been registered

=== 406 ErrorCode::UnknownRequest ===
A request has been received of a type which is unknown or unregistered

=== 700 ErrorCode::OperationFailed ===
Generic failure, the operation requested has failed. Used to indicate a general call failure of an API call for some unknown reason.

== Creating Custom Errors ==
To create a custom error use the FreeDESK_Error class as follows:
<source lang="php">
// Our error information
$code = 999;
$text = "An Error";
// Create a FreeDESK_Error
$myError = new FreeDESK_Error($code, $text);
// Output the XML
echo $myError->XML();
// n.b. this will output XML without header
// $myError->XML(true) will include an XML header
</source>

API XML Error

2012-08-21T18:45:44Z

Dave:

A FreeDESK XML error will contain an error code and textual description.

== Example ==
<source lang="xml">
<error>
<code>XXXX</code>
<text>Textual Error Description</text>
</error>
</source>

== Error Codes ==
The following is a list of in-built error codes based upon the ErrorCode class. You may use your own error codes which can either be captured by your own receipt handling code or will be detected client-side with the DESK.isError(xml) call.

=== 101 ErrorCode::FailedLogin ===
Login has failed

=== 102 ErrorCode::SessionExpired ===
Attempt to validate client SID has failed as it has expired (or has been deleted, or is illegal)

=== 201 ErrorCode::UnknownMode ===
The API has been called with an unknown or unregistered mode

=== 300 ErrorCode::EntityError ===
An error has occurred when fetching/searching/writing an entity. The system logs will provide more information.

=== 403 ErrorCode::Forbidden ===
Current user context does not have access to the mode or resource requested

=== 404 ErrorCode::ResourceNotFound ===
A resource was asked for that does not exist or has not been registered

=== 406 ErrorCode::UnknownRequest ===
A request has been received of a type which is unknown or unregistered

=== 700 ErrorCode::OperationFailed ===
Generic failure, the operation requested has failed. Used to indicate a general call failure of an API call for some unknown reason.

== Creating Custom Errors ==
To create a custom error use the FreeDESK_Error class as follows:
<source lang="php">
// Our error information
$code = 999;
$text = "An Error";
// Create a FreeDESK_Error
$myError = new FreeDESK_Error($code, $text);
// Output the XML
echo $myError->XML();
// n.b. this will output XML without header $myError->XML(true) will include an XML header
</source>

API XML Error

2012-08-21T18:45:29Z

Dave:

A FreeDESK XML error will contain an error code and textual description.

== Example ==
<source lang="xml">
<error>
<code>XXXX</code>
<text>Textual Error Description</text>
</error>
</source>

== Error Codes ==
The following is a list of in-built error codes based upon the ErrorCode class. You may use your own error codes which can either be captured by your own receipt handling code or will be detected client-side with the DESK.isError(xml) call.

=== 101 ErrorCode::FailedLogin ===
Login has failed

=== 102 ErrorCode::SessionExpired ===
Attempt to validate client SID has failed as it has expired (or has been deleted, or is illegal)

=== 201 ErrorCode::UnknownMode ===
The API has been called with an unknown or unregistered mode

=== 300 ErrorCode::EntityError ===
An error has occurred when fetching/searching/writing an entity. The system logs will provide more information.

=== 403 ErrorCode::Forbidden ===
Current user context does not have access to the mode or resource requested

=== 404 ErrorCode::ResourceNotFound ===
A resource was asked for that does not exist or has not been registered

=== 406 ErrorCode::UnknownRequest ===
A request has been received of a type which is unknown or unregistered

=== 700 ErrorCode::OperationFailed ===
Generic failure, the operation requested has failed. Used to indicate a general call failure of an API call for some unknown reason.

== Creating Custom Errors ==
To create a custom error use the FreeDESK_Error class as follows:
<source lang="php5">
// Our error information
$code = 999;
$text = "An Error";
// Create a FreeDESK_Error
$myError = new FreeDESK_Error($code, $text);
// Output the XML
echo $myError->XML();
// n.b. this will output XML without header $myError->XML(true) will include an XML header
</source>

API XML Error

2012-08-21T18:32:44Z

Dave:

API XML Error

2012-08-21T18:31:21Z

Dave: Created page with "A FreeDESK XML error will contain an error code and textual description. == Example =="

A FreeDESK XML error will contain an error code and textual description.

== Example ==

API login

2012-08-21T18:29:32Z

Dave:

{{Infobox API
| name = login
| mode = login
| description = Open a user session
| parameters = username, password
| returned = XML login error or session data
}}
= Description =
The login call allows the establishment of a ContextType::User session
= Using the Call =
Pass in the following parameters using GET or POST
* username : Analyst username
* password : Analyst password
For example
api.php?username=someuser&password=theirpassword
= Returned Data =
XML containing either the SID on success or a [[API XML Error|FreeDESK error on failure]].

FreeDESK Administrators Guide

2012-08-21T18:18:45Z

Dave: Created page with "* Users and Groups ** Standard Users ** Customer Access ** Permissions * Requests ** Configuring Request Types * Statuses * Priorities * [[Syst..."

* [[Users and Groups]]
** [[Standard Users]]
** [[Customer Access]]
** [[Permissions]]
* [[Requests]]
** [[Configuring Request Types]]
* [[Statuses]]
* [[Priorities]]
* [[System Configuration]]
** [[System-Wide Configuration Settings]]

Installation Guide

2012-08-21T18:17:19Z

Dave:

= Installing FreeDESK =

== Download a Release ==

Download the latest recommended release from the [http://freedesk.purplepixie.org/download.php download page] in tarball or zip format.

Extract the release and copy the resultant folder/files to your web directory of choice.

== Initial Setup ==

Navigate in a browser to the installation directory, you will be redirected to the setup page.

Follow the on-screen instructions to create an initial configuration. This can be saved automatically if the config directory is writeable by the web server.

For example under Linux:
# chmod 777 config

If the directory is not writeable by the web server you will need to copy and paste the configuration data into the config/Config.php file.

Select to preform a fresh install.

Set an admin password of your choice.

== Logging In ==

Delete the setup.php file in the installation directory (if you don't do this it will automatically redirect to this file).

Now either click on the login link or point your browser again at the install directory.

Click on the analyst link and login as admin with the password you entered earliest.

= Setting up FreeDESK for First Use =

Once you are logged in you can do some initial setup for example setting up statuses for requests, users and teams.

These options are under the System - System Settings menu option. For more information see the [[FreeDESK Administrators Guide]].

= Using FreeDESK =

For more information please read the [[Introduction to Using FreeDESK]].

Main Page

2012-08-19T22:54:30Z

Dave:

'''Welcome to the FreeDESK Wiki'''

== Getting Started ==
* [[FreeDESK:About|About FreeDESK]]
* [[Installation Guide]]
* [[Introduction to Using FreeDESK]]

== Administration ==
* [[Users and Groups]]
** [[Standard Users]]
** [[Customer Access]]
** [[Permissions]]
* [[Requests]]
** [[Configuring Request Types]]
* [[Statuses]]
* [[Priorities]]
* [[System Configuration]]
** [[System-Wide Configuration Settings]]

== Interfacing with FreeDESK ==
* [[API]]

== Extending the System ==
* [[Developer Overview]]
* [[Plugin Modules]]
** [[Developing Plugin Modules]]
** [[Authentication Modules]]
** [[Database Module]]
** [[Logging Module]]
** [[Custom Requests]]
** [[Entity Modules]]
* [[Event Handling]]
* [[FreeDESK Javascript Support]]
* [[Skinning]]

== MediaWiki Help ==
* [//meta.wikimedia.org/wiki/Help:Contents User's Guide] Information on using the wiki software.
* [//www.mediawiki.org/wiki/Manual:Configuration_settings Configuration settings list]
* [//www.mediawiki.org/wiki/Manual:FAQ MediaWiki FAQ]
* [https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list]

Introduction to Using FreeDESK

2012-07-03T11:28:33Z

Dave: Created page with "= For Users = FreeDESK User Guide = For Administrators = FreeDESK Administrators Guide"

= For Users =

[[FreeDESK User Guide]]

= For Administrators =

[[FreeDESK Administrators Guide]]

Installation Guide

2012-07-03T00:30:03Z

Dave:

= Installing FreeDESK =

== Download a Release ==

Download the latest recommended release from the [http://freedesk.purplepixie.org/download.php download page] in tarball or zip format.

Extract the release and copy the resultant folder/files to your web directory of choice.

== Initial Setup ==

Navigate in a browser to the installation directory, you will be redirected to the setup page.

Follow the on-screen instructions to create an initial configuration. This can be saved automatically if the config directory is writeable by the web server.

For example under Linux:
# chmod 777 config

If the directory is not writeable by the web server you will need to copy and paste the configuration data into the config/Config.php file.

Select to preform a fresh install.

Set an admin password of your choice.

== Logging In ==

Delete the setup.php file in the installation directory (if you don't do this it will automatically redirect to this file).

Now either click on the login link or point your browser again at the install directory.

Click on the analyst link and login as admin with the password you entered earliest.

= Setting up FreeDESK for First Use =

Once you are logged in you can do some initial setup for example setting up statuses for requests, users and teams.

These options are under the System - System Settings menu option.

= Using FreeDESK =

For more information please read the [[Introduction to Using FreeDESK]].

Installation Guide

2012-07-03T00:29:25Z

Dave: Created page with "= Installing FreeDESK = == Download a Release == Download the latest recommended release from the [http://freedesk.purplepixie.org/download.php download page] in tarball or ..."