$Csession_xml = GetSessionXML(); $Ssession_xml = RunXML($Csession_xml, 1);Once we have the session stored in XML we need to parse the XML to extract a session code that we can pass for future transactions:
$session = GetSessionArray($Ssession_xml);Note that this function returns an array whose contents contain the following:
Array
(
[session_key] => 1$rT$awFxz$xKMpeP9PRwZEMQJQXjUSl5.
[username] => joeuser
[status] => 0
[idle_exp_time] => 04/06/2006 10:39:36
[sess_exp_time] => 04/06/2006 10:39:36
)
We will pass this array to the next function that we call which
will extract the the session_key and username.
The GetSessionArray() function makes calls to functions in
the class-xml_api.php file. This file is a part of
ruQueue's API server and is included in this client
so that the XML can be handled the same way on both sides.
This file uses PHP's
DOM XML library
to parse the XML. Note that this example is based on
PHP4 (not 5).
if (count($session) > 0) {
...
}
The create ticket usecase shows the attributes we need. We
can define those attributes in an array:
$ticket_in = array(
'mode' => "create",
'queue' => "Test 2",
'subject' => "XML New Ticket" ,
'owner' => "joeuser",
'requester' => "joeuser@domain.tld",
'body' => "Testing"
);
and then pass this array and the session array to GetTicketXML():
$Cticket_xml = GetTicketXML($session, $ticket_in);$Cticket_xml should now contain XML like the one in the create ticket usecase but with your current session and ticket data. We then use the familiar pattern of running the client XML on the server, getting the server XML back, and then parsing the server XML to get an array of attributes:
$Sticket_xml = RunXML($Cticket_xml); $ticket_out = GetTicketArray($Sticket_xml);The example client then prints the contents of $ticket_out. Note that the id is the ticket number:
Array
(
[mode] => create
[queue] => Test 2
[subject] => XML New Ticket
[owner] => joeuser
[requester] => joeuser@domain.tld
[id] => 13
[status] => 0
)
You should now be able to extend the client to take this ticket number
and session to add a new comment to the ticket. You should also have
a basic idea of how to write a client based on the DTD.
HOST ruqueue.domain.tld PATH /api/xml_api.phpNote that the URL is a combination of the HOST and PATH. Your user will also want to know the SHARED_SECRET. This is a password that you will store in your database. We will discuss how to set this password shortly. The API expects the following table to exist:
CREATE TABLE api_users ( username varchar(15) NOT NULL default '', host varchar(255) NOT NULL default '', shared_key varchar(32) NOT NULL default '', PRIMARY KEY (username,host) ) TYPE=MyISAM;If the SQL command DESC api_users gives you an 1146 error about the api_users table not existing, execute the create table command above. Once you have have an api_users table you can setup an account for the API user. You will need to work out the values of the following with your API user:
INSERT INTO api_users VALUES ('$username','$host','$password');
Note that you must substitute the dollar-signed fields above
with the actual values.
To support multiple hosts for the same username and password
run the above query for each host. I.e. create multiple entries
in the api_users table with a single host in each entry.
Now that you have created the user for the API you need to
create the user for ruQueue. What the user of the API can do
in ruQueue can be controlled via the same set of rights that a user
can have when using the web-interface. See Appendix A of the
documentation to see what rights
are available. Then see chapter 3 (Setting Up Access To ruQueue) of
the documentation to use the
web-interface to add and grant rights for this user. Note that
you can set a password for this user if you are using local
authentication but the API user won't need this password.
If you don't follow this step users will be able to get a
session but will not be able to do much with it.
If you are troubleshooting the API it is handy to store what XML
came in and what XML was sent out as a response for each transaction.
This will help rule out if the XML did not make it to the server. To
do this edit web-interface/api/api_log.php and set the
logging variable to true. The top of this file also contains the
definition for the api_log table which you might need to create.
Each transaction will be stored in this table.
To summarize, you need to tell the API user: