Solutions Code Examples

There are two methods for fetching solution data and two helper methods associated with the Remedy solutions data.

####Search methods:

• Fetch a solution by it's solution ID number (solutionGet)
• Search solutions with a specified query (solutionList)

####Helper Methods:

• Increment solution's Web hit counters (solutionIncrement)
• Retrieve a list of the keywords associated with a solution (keywordList)

Retrieving a solution by it's Solution Id

The solutionGet method simply takes in the solution ID associated with a given solution. An object with the solution's information is returned. If the specified solution does not exist or the input is in the wrong format, an NCState_Service_Exception is thrown.

<?php

/***************************************************************
*
* Example: Retrieving a Remedy solution
*
***************************************************************/

require_once 'Ncstate/Service/Remedy.php';

// create a new Remedy object
$remedy = new Ncstate_Service_Remedy($user, $pass);

// specify the solution number
$solutionId = '306';

try {
    $solution = $remedy->solutionGet($solutionId);
    print("Retrieved Solution: " . $solution->solution_id . "\n");
    print_r($solution);  
} catch (Ncstate_Service_Exception $e) {
    die('An error occured while retrieving the solution:' . $e->getMessage());  
}  

?>

Retrieving solutions based on a query

The solutionList method has the same structure as all of the search methods. These methods have one required field -- the search query -- and two optional fields: a start offset, and a max limit. The offset is simply the index of the starting entry and the max limit will limit the returned list of Ids to the specified number. Search methods return only object Ids, instead of actual objects. To retrieve a list of actual objects, loop through the Ids, call a get method with the object's Id and add the returned object to a new list.

Note: the search method will return different objects depending on how many objects are returned. If there is just one object, the search method returns the object. If the number of objects returned is greater than 1, the object returned will contain all of the entries in a "getListValues" variable. In this case, you must iterate over getListValues to retrieve the object Ids (see below).

The solutionList method has an optional parameter which is used to indicate whether or not the search query includes solution keywords. This is the $withKeywords parameter and the default value is true. Examples are provided for both situations.

Queries

Remedy expects queries to have a very specific format. The overall format is the following:

'[label]' [operator] "[value]"

The label is a predefined keyword in the database (see the list below for expected labels and their value formats).
The value should correspond to the label format (i.e. dates formated correctly, etc.) The operator can be any of the following: =, !=, <, <=, >, >=, LIKE You can concatenate conditions using AND or OR operators between conditions.

A summary of the search terms allowed when searching for solutions can be found below.

###Searching with a qualification that includes solution keywords

<?php

/***************************************************************  
 *  
 * Example: Getting a list of solutions matching the specified query
 * when the query includes solution keywords.
 *  
 ***************************************************************/

require_once 'Ncstate/Service/Remedy.php';

// create a new Remedy object  
$remedy = new Ncstate_Service_Remedy($user, $pass);

// formulate the query which includes solution keywords
$qual = "('word' = \"remedy\" OR 'word' = \"email\" OR 'word' = \"update\") AND 'Workgroup' = \"REMEDY\"";

// qualification does include solution keywords
$withKeywords = true;

try {
    /*
     * The solutionList method searches a join form containing entries for solutions and their associated
     * keywords. Therefore, this method will return multiple entries for a solution if there are multiple
     * matching keywords.
     */
    $solnList = $remedy->solutionList($qual, 0, 0, $withKeywords);
}
catch (Ncstate_Service_Exception $e) {
    die('An error occured while searching the solutions:' . $e->getMessage());
}

$solns = array();
// check if the return value has any entries  
if (isset($solnList)) {
    /*  
     * Single entry lists are structured  
     * differently than multiple entry objects. We must  
     * therefore check for multiplicity and handle both  
     * cases.  
     */
    if (count($solnList->getListValues) > 1) {
        foreach ($solnList->getListValues as $soln) {
            /*
             * Make a single entry for each matching solution and keep track of how many of the specified
             * keywords matched this solution.
             */
            $solns[$soln->solution_id] = $solns[$soln->solution_id] + 1;
        }
    } else {
        $solns[$solnList->solution_id] = $solns[$solnList->solution_id] + 1;
    }
    // we got some results
    $solnCount = count($solns);
    // sort the returned solutions by the number of matching keywords
    print "Query returned $solnCount solutions\n";
    arsort($solns);
    foreach (array_keys($solns) as $solnId) {
        print "Solution $solnId matched " . $solns[$solnId] . " keywords\n";
    }
}

?>

###Searching with a qualification that does NOT include solution keywords

<?php

/***************************************************************  
 *  
 * Example: Getting a list of solutions matching the specified query
 * when the query qualification does NOT include solution keywords.
 *  
 ***************************************************************/

require_once 'Ncstate/Service/Remedy.php';

// create a new Remedy object  
$remedy = new Ncstate_Service_Remedy($user, $pass);

// formulate the query
$qual = "'Status' <= \"Published\" AND 'owner' = \"nlil\"";

// qualification does not include solution keywords
$withKeywords = false;

try {
    /*
     * The solutionListNoKWDS method searches the solutions form directly. This method
     * is the preferred method to use if your qualification does not include solution
     * keywords. This method returns results more quickly and there is no duplication
     * as there may be with the solutionList method.
     */
    $solnList = $remedy->solutionList($qual, 0, 0, $withKeywords);
}
catch (Ncstate_Service_Exception $e) {
    die('An error occured while searching the solutions:' . $e->getMessage());
}

$solns = array();
// check if the return value has any entries  
if (isset($solnList)) {
    /*  
     * Single entry lists are structured  
     * differently than multiple entry objects. We must  
     * therefore check for multiplicity and handle both  
     * cases.  
     */
    if (count($solnList->getListValues) > 1) {
        foreach ($solnList->getListValues as $soln) {
            $solns[] = $soln;
        }
    } else {
        $solns[] = $solnList->getListValues;
    }
}

$solnCount = count($solnList->getListValues);
print "Query returned $solnCount solutions.\n";
print "Solution Ids:\n";
foreach ($solns as $soln) {
    print $soln->solution_id . "\n";
}

?>

###Increment solution's Web hit counters

<?php

/***************************************************************
 *
 * Example: Incrementing a Remedy solution's hit counters
 *
 ***************************************************************/

require_once 'Ncstate/Service/Remedy.php';

// create a new Remedy object
$remedy = new Ncstate_Service_Remedy($user, $pass);

// solution number to update
$solutionId = '306';

// type of update to perform
$service = 'increment';

// field name to increment:  wwwaccess | wwwused
$fieldName = 'wwwaccess';

try {
    $results = $remedy->solutionIncrement($fieldName, $service, $solutionId);
}
catch (Ncstate_Service_Exception $e) {
    die('An error occured while incrementing the field:' . $e->getMessage());
}

print("New count for solution number " . $results->solution_id . " " . 
      $results->field_name . " is: " . $results->new_count . "\n");

?>

###Retrieve a list of the keywords associated with a specific Remedy solution

<?php

/***************************************************************  
 *  
 * Example: Retrieve a list of the keywords associated with a
 * specific Remedy solution.
 *  
 ***************************************************************/

require_once 'Ncstate/Service/Remedy.php';

// create a new Remedy object  
$remedy = new Ncstate_Service_Remedy($user, $pass);

// the call Id must be an 8 digit number  
$solutionId = '306';
$kwds       = array();

try {
    $kwdList = $remedy->keywordList($solutionId);
    // check if the return value has any entries  
    if (isset($kwdList)) {
        /*  
         * Single entry lists are structured  
         * differently than multiple entry objects. We must  
         * therefore check for multiplicity and handle both  
         * cases.  
         */
        if (count($kwdList->getListValues) > 1) {
            foreach ($kwdList->getListValues as $keywords) {
                $kwds[] = $keywords;
            }
        } else {
            $kwds[] = $kwdList->getListValues;
        }
    }
    
}
catch (Ncstate_Service_Exception $e) {
    die('An error occured while getting the keywords:' . $e->getMessage());
}

$kwdsCount = count($kwds);
asort($kwds);
print "Found $kwdsCount keywords for solution $solutionId:\n";
foreach ($kwds as $kwd) {
    print $kwd->word . "\n";
}

?>

Search terms for the Solutions form

content => Text | HTML | PS | RTF | man
distribution => All | NCSU Only | Internal
LastEdit => date-time
LastEditor => string
lastused => date-time
Modified-date => date-time
owner => string
probsummary => string
solnsummary => string
solution => int
Status => Draft | Reviewed | Published | Retired | Obsolete
text => string
word* => string
Workgroup => string
wwwaccess => int
wwwused => int

Note that the word search term can only be used with the solutionList method. The other search methods do not include this term.