-
Notifications
You must be signed in to change notification settings - Fork 4
Calls Code Examples
There are five methods for fetching call data and two helper methods associated with the Remedy call data.
####Search methods:
- Fetch a call by it's call ID number (callGet)
- Create a new call (callCreate)
- Update an existing call (callUpdate)
- Search calls with a specified query (callList)
- Search calls_cust with a specified query (callCustList)
####Helper Methods:
- Retrieve a call's solution (solutionGet)
- Retrieve a call's history entries (callHistoryList)
- Operating on call's attachments (See the Attachments Code Examples page)
<?php
/***************************************************************
*
* Example: Getting a Remedy call
*
***************************************************************/
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
$callId = "00000078";
try {
$result = $remedy->callGet($callId);
} catch (Ncstate_Service_Exception $e) {
die('An error occured while retrieving the call:' . $e->getMessage());
}
print('Retrieved call:') . "\n" . print_r($result);
?>
Calls are simply a collection of key => value pairs. Remedy expects certain keys to not have an empty or null value associated with them. The required fields that an application must submit to create a new Remedy call are:
impact - The impact of the call (Individual/Group/Site/Enterprise)
origin - The origin (Phone/Fax/V-mail/E-mail/Project/Self/Walk Up/WWW/Lab/IM)
priority - The priority of the call (Low/Medium/High/Critical/Emergency)
problem - The description of the problem
status - The beginning status of the call (New/Assigned/Owned/Active/Defect/Waiting/Closed/Solved)
workgroup_id or workgroup - The workgroup associated with this call (indicate one or the other)
Calls can also specify optional fields. These fields are not required for a new call but can be set with an insert or an update. Optional fields that can be attached to a Remedy call are:
action - action
comments - for history entry
customer_id - customer CID number
date_nextcontact - date-time field, call next-contact
on_site_visit - Yes/No/NULL
owner_id - owner id number
owner - call owner (Remedy login)
problem_text - first diary entry (unformated)
product_id - product id number
product - product name
solution_id - solution id number
time_spent - time spent, in seconds
The callCreate() method creates a new Remedy call. callCreate() accepts only one argument, the associative array that defines each of the new call's fields (required fields must be defined).
<?php
/***************************************************************
*
* Example: Creating a Remedy call
*
***************************************************************/
require_once 'Ncstate/Service/Remedy.php';
// create a new Remedy object
$remedy = new Ncstate_Service_Remedy($user, $pass);
// the most basic call
$call = array(
'impact' => 'Individual',
'origin' => 'WWW',
'priority' => 'Low',
'problem' => 'Not a real problem',
'status' => 'Assigned',
'workgroup' => 'TEST',
'problem_text' => "First diary entry\nline 2",
'comments' => 'Created by PHP API',
'customer_id' => '000005667',
'owner' => 'nlil',
'action' => 'Lets see some action'
);
try {
// Returns a stdOjbect
$result = $remedy->callCreate($call);
// Get the call Id out of the object
$callId = $result->call_id;
}
catch (Ncstate_Service_Exception $e) {
die('An error occured while creating the call:' . $e->getMessage());
}
print("Call has been created with call_id: " . $callId);
?>
The callUpdate() method updates a call. callUpdate() takes an associative array with the values to be changed defined as valid key => value pairs (exactly like callCreate()).
<?php
/***************************************************************
*
* Example: Updating a Remedy call
*
***************************************************************/
require_once 'Ncstate/Service/Remedy.php';
// create a new Remedy object
$remedy = new Ncstate_Service_Remedy($user, $pass);
// The call Id of the call we wish to update
$callId = "01697742";
// A possible update call.
$call = array(
'workgroup' => 'TRASH', // Move the call to the trash
'problem_text' => 'We fixed it!', // Update the call's diary
'status' => 'Solved', // Update the status
'solution_id' => '123' // Update the solution Id
);
try {
$remedy->callUpdate($callId, $call);
}
catch (Ncstate_Service_Exception $e) {
die('An error occured while updating the call:' . $e->getMessage());
}
print("Call has been updated successfully ");
?>
In the new Remedy API, all methods whose names end in -List are search methods. All search methods have the same structure for calling. The method has 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).
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.
<?php
/***************************************************************
*
* Example: Searching for Remedy calls using a search query
*
***************************************************************/
require_once 'Ncstate/Service/Remedy.php';
// create a new Remedy object
$remedy = new Ncstate_Service_Remedy($user, $pass);
// The search query
$qualification = "('datereported' >= \"12/21/11 12:01 am\" AND 'datereported' <= \"12/22/11 12:01 am\")";
// The start index
$startRecord = 0;
// The max number of entries returned
$maxLimit = 3;
try {
// Get the list of call Ids
$callList = $remedy->callList($qualification, $startRecord, $maxLimit);
$calls = array();
// check if the return value has any entries
if (isset($callList)) {
/*
* Single entry lists are structured
* differently than multiple entry objects. We must
* therefore check for multiplicity and handle both
* cases.
*/
if (count($callList->getListValues) > 1) {
foreach($callList->getListValues as $call) {
$calls[] = $call;
}
} else {
$calls[] = $callList;
}
}
} catch (Ncstate_Service_Exception $e) {
die("An error occured while searching the database:" . $e->getMessage());
}
print("Calls retrieved: " . $calls);
?>
The calls_cust form is a join form between the Calls form and the Customer form. This allows you to search using search terms from both forms and returns a combination of call data and customer data.
<?php
/***************************************************************
*
* Example: Searching the calls_cust form using a qualification
*
***************************************************************/
require_once 'Ncstate/Service/Remedy.php';
// create a new Remedy object
$remedy = new Ncstate_Service_Remedy($user, $pass);
// formulate the query
$qualification = "('username' = \"nlil\" AND 'Status' <= 5)";
$startRecord = 0;
$maxLimit = 0;
try {
$callList = $remedy->callCustList($qualification, $startRecord, $maxLimit);
}
catch (Ncstate_Service_Exception $e) {
die("An error occured while searching the calls:" . $e->getMessage());
}
$calls = array();
// check if the return value has any entries
if (isset($callList)) {
/*
* Single entry lists are structured
* differently than multiple entry objects. We must
* therefore check for multiplicity and handle both
* cases.
*/
if (count($callList->getListValues) > 1) {
foreach ($callList->getListValues as $call) {
$calls[] = $call;
}
} else {
$calls[] = $callList->getListValues;
}
}
print ("\nRetrieved ") . count($calls) . " calls:\n";
foreach ($calls as $call) {
print "$call->call_id\n";
}
// print_r($calls);
?>
<?php
/***************************************************************
*
* Example: Fetching a specific Remedy call from the Calls_Cust form
*
***************************************************************/
require_once 'Ncstate/Service/Remedy.php';
// create a new Remedy object
$remedy = new Ncstate_Service_Remedy($user, $pass);
$callId = "01690002";
try {
$result = $remedy->callCustGet($callId);
} catch (Ncstate_Service_Exception $e) {
die('An error occured while getting the call:' . $e->getMessage());
}
print "Retrieved call: \n";
print_r($result);
print "\nCustomer Login Name = $result->customer_login_name\n";
?>
action => string
agent => string
Assignee Group => string
Call-Id => string
callid => int
CustCall => string
datemodified => date-time
nextcontactdate => date-time
datereported => date-time
dateresolved => date-time
E911_phonenumb => string
emailcc => string
Email To => string
External Call ID => string
FirstContactSeconds => int
FirstContact => string
GUID => string
impact => Individual | Group | Site | Enterprise
initial_workgroup => string
Last-modified-by => string
msg_id => string
On-SiteVisit => Yes | No
origin => Phone | FAX | V-Mail | E-Mail | Project | Self | Walk Up | WWW | Lab | IM
ouc => string
ownercall => int
owner => string
priority => Low | Medium | High | Critical | Emergency
problemtext => string
problem => string
productcall => int
product_name => string
QC-ID => string
Sender Email => string
solutioncall => int
Status => New | Assigned | Owned | Active | Defect | Waiting | Closed | Solved
timespent => int (seconds)
TimeSpnt => string (formatted)
TimeToCloseSeconds => int
TimeToClose => string (formatted)
workgroupcall => int
workgroup => string
action => action field from the call record - string
agent => agent field from the call record - string
Assignee Group => Assignee Group field from the call record - string
Call-Id => call id field with leading zeros - string
callid => short version - int
class => class field from the customer record - string
curr => curriculum field from the customer record - string
CustCall => customer id number field from the call record - string
datemodified => date modified field from the call record - date-time
datereported => date reported field from the call record - date-time
dateresolved => date resolved field from the call record - date-time
dept => department field from the customer record - string
E911_phonenumb => E911 number field from the call record - string
email => email address field from the customer record - string
Email To => email to: address field from the call record - string
emailcc => email cc: address field from the call record - string
FirstContact => first contact date/time field from the call record - string
FirstContactSeconds => first contact seconds field from the call record - int
firstname => firstname field from the customer record - string
GUID => guid field from the call record - string
h_addr1 => home address field line one from the customer record - string
h_addr2 => home address field line two from the customer record - string
h_city => home city field from the customer record - string
home_phone => home phone field from the customer record - string
impact => impact field from the call record - Individual | Group | Site | Enterprise
initial_workgroup => initial workgroup field from the call workgroup - string
Last-modified-by => last modified by field from the call record - string
lastname => last name from the customer record - string
lastname => first name from the customer record - string
msg_id => msg_id field from the call record - string
nextcontactdate => nextcontactdate field from the call record - date-time
On-SiteVisit => On-SiteVisit field from the call record - Yes | No
origin => origin field from the call record - Phone | FAX | V-Mail | E-Mail | Project | Self | Walk Up | WWW | Lab | IM
ouc => ouc field from the call record - string
owner => owner field from the call record - string
ownercall => ownercall field from the call record - int
position => position field from the customer record - string
priority => priority field from the call record - Low | Medium | High | Critical | Emergency
privacy => privacy field from the customer record - character "P" | NULL
problem => problem field from the call record - string
problemtext => problem text field from the call record - string
product_name => product name field from the call record - string
productcall => product number field from the call record - int
Sender Email => sender email field from the call record - string
solutioncall => solution number field from the call record - int
Status => status field from the call record - New | Assigned | Owned | Active | Defect | Waiting | Closed | Solved
timespent => timespent field from the call record - int
TimeSpnt => timeSpnt field from the call record - string
TimeToClose => timetoclose field from the call record - string
TimeToCloseSeconds => timetocloseseconds field from the call record - int
username => user's login name from the customer record - string
w_addr1 => work address line one from the customer record - string
w_addr2 => work address line two from the customer record - string
w_city => work city from the customer record - string
work_fax => work fax from the customer record - string
work_phone => work phone from the customer record - string
workgroup => workgroup name from the call record - string
workgroupcall => workgroup number from the call record - int
Notes:
Date-time formats are expected to adhere to this format:
mm/dd/yy hh:ii am | pm
Field names in BOLD are indexed fields. Using these fields in your searches will improve performance significantly.
To speed things up, a call's history and associated solution are kept separate from the actual call. This also provides modularity in the case of solutions since one solution can be associated with many calls. The API, however, allows applications to query the history using information from the call or simply external information.
<?php
/***************************************************************
*
* Example: Retrieving a Remedy call's 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
$callId = '01697742';
try {
$call = $remedy->callGet($callId);
// check if the call's solution exists
if (isset($call->solution_id)) {
$solution = $remedy->solutionGet($call->solution_id);
print("Retrieved Solution: " . $solution->solution_id . "\n");
print_r($solution);
} else {
print("Call number $callId does not have a solution.");
}
}
catch (Ncstate_Service_Exception $e) {
die('An error occured while retrieving the call:' . $e->getMessage());
}
?>
Retrieving a call's history is more complex than it's solution. The call does not keep an explicit record of the history. Instead, the application must search for all history entries associated with the call Id.
<?php
/***************************************************************
*
* Example: Retrieving a Remedy call's history entries
*
***************************************************************/
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
$callId = '01697742';
try {
$history = $remedy->callHistoryList($callId);
$historyList = array();
// check if the return value has any entries
if (isset($history)) {
/*
* Single entry history objects are structured
* differently than multiple entry objects. We must
* therefore check for multiplicity and handle both
* cases.
*/
if (count($history->getListValues) > 1) {
foreach ($history->getListValues as $hist) {
$historyList[] = $hist;
}
} else {
$historyList[] = $history;
}
}
}
catch (Ncstate_Service_Exception $e) {
die("An error occured while getting the call's history:" . $e->getMessage());
}
$histCount = count($historyList);
print("Retrieved call's $histCount history entries\n");
print_r($historyList);
?>
See the Attachments Code Examples page.