OTRS – Parsing Out the Variables in a SOAP Response

OTRS,Programming,Snippets,Web Services,Web Stuff — Jeff Eske on March 5, 2013 at 5:16 pm

Unlike some web services, the OTRS web services don’t return the values in specific xml tags; it uses generic “s-gensym” tags.  Also, it returns field name within a set of generic tags, followed by the field value in a set of generic tags.  Here’s part of the SOAP response:

<s-gensym1558 xsi:type="xsd:string">PriorityID</s-gensym1558>
<s-gensym1560 xsi:type="xsd:int">3</s-gensym1560>
<s-gensym1562 xsi:type="xsd:string">ServiceID</s-gensym1562>
<s-gensym1564 xsi:type="xsd:string" />
<s-gensym1566 xsi:type="xsd:string">Type</s-gensym1566>
<s-gensym1568 xsi:type="xsd:string">Failure</s-gensym1568>

Makes a lot of sense, doesn’t it?  Here’s an example of one that actually uses the field name as the enclosing tag name.  It makes it easier to understand:

<fusion:ServiceDown><fusion:v>false</fusion:v></fusion:ServiceDown>
<fusion:BusinessUnit><fusion:v>Some Business Unit</fusion:v></fusion:BusinessUnit>

In this example, you can see that the ServiceDown field(fusion:ServiceDown) has a value(fusion:v) of “false”.  With OTRS, every time you run your SOAP request, you some random-ass “s-gensym” field name for everything.

To actually pull the SOAP response data out, you can use a foreach() loop and dump the field names and values into a more useful array.  In addition to that, the array will be setup as a key/value pair, so you can actually get the field value by referring to the field name.  I’m sure that there’s a much better, more elegant method to do the same thing, but this way works.  First the code, then an explanation of what’s going on:

[code]
$ticketInfo = array();
$i = 0;
foreach ($TicketDetails as $name => $value){ 
 if (false !== strpos($name, "s-gensym")){
 $temp[$i] = $value; 
 $v = $temp[$i-1]; 
 if($i % 2 != 0){ 
 $ticketInfo[$v] = $value; 
 }
 $i++;
 }
}
[/code]

Basically, what this code does is take your SOAP response array ($ticketInfo) and run it through a foreach() loop.  The OTRS SOAP response includes to entries for each field.  The first entry is the field name and the second entry is the field value.  So, what I want to do is combine both entries into a key->value pair in an array.

The foreach() explodes the values of the s-gensym variables out and adds the value to 2 different arrays.  This is where the elegance is definitely lacking.  I’m first saving the value into the $temp[] array to refer back to it later.  Then, if the row is divisble by two – basically every other, or every second row, I grab the previous value from temp[] and write it to $ticketInfo[] as the key and write the current value as the value.  What I end up with in the end is an array ($ticketInfo[]) that has the field name as the key and the field value as the value.

You can then pull the desired value by referring to the appropriate key, such as:

$ticket_age = $ticketInfo[Age];
$ticket_title = $ticketInfo[Title];

A simple way to print out all of the values in your array is, again, with the foreach() loop.  All you need is this little piece of code:

[code]
foreach ($ticketInfo as $name => $value){
 echo "<b>".$name.":</b> ".$value."<br>";
}
[/code]

The foreach() will loop through the array and explode out the key/value pairs, then echo them out.  It can be handy for troubleshooting, to see what everything actually looks like in the array.

Jeff Eske

OTRS – Web Services Descriptions and Examples

OTRS,Web Services,Web Stuff — Jeff Eske on March 5, 2013 at 4:47 pm

The OTRS ticketing system comes with some basic web service functions included by default.  I’ve already done a post about using web services to create a new ticket via TicketCreate(), as well as a post about retrieving an existing ticket via TicketGet().  I’ve also created a page to allow you to search for a ticket using the TicketSearch() function, but I haven’t posted anything about that yet.  I’ve also posted a code snippet that actually helped me considerably when I was troubleshooting exactly what was going on.

What I’d like to do here is just note some observations that I’ve made while messing around trying to figure all of this out.  Hopefully it will be of some use to someone.  As with everything on this site, the Disclaimer holds here to – all I can guarantee is that this stuff worked for me.  What I have listed below is what I’ve determined from trial-and-error, so take it with a grain of salt.  This is almost more to document it for myself than anyone else.

===============

TicketCreate()
Purpose:
Used to create new tickets object (duh!).  Generally, you’ll want to do an ArticleCreate() also, to add some useful information to the ticket.
Required Input Values: TypeID(integer), QueueID(integer), LockID(integer), PriorityID(integer), State(text), CustomerUser(text), OwnerID(integer), UserID(integer).
Optional, but Recommended: Title(text). The title is required, but it seems logical to add one.
Returns: TicketID(integer)

[code]
// PHP code sample for TicketCreate().  Adjust the values as necessary
$TicketID = $client->__soapCall(
 "Dispatch",array($username, $password,
 "TicketObject", "TicketCreate",
 "Title", "Some Title",
 "TypeID", some_typeID_number,
 "QueueID",  some_queueID_number,
 "LockID", 1,
 "PriorityID", some_priorityID_number,
 "State", "new",
 "CustomerUser", "some_user@your_organization",
 "OwnerID", some_ownerID_number,
 "UserID", some_userID_number,
 )
 );
[/code]

===============

ArticleCreate()
Purpose: Add an article to a ticket.  The TicketCreate() function basically just creates a “wrapper” for articles.  The articles provide the content.
Required Input Values: TicketID(integer), ArticleType(text), SenderType(text), HistoryType(text), HistoryComment(text), ContentType(text), UserID(integer)
Optional, but Recommended: From(text), Subject(text), Body(text), Loop(integer), AutoRepsonseType(text), OrigHeader(array)
Returns: ArticleID(integer)

[code]
// PHP code sample for ArticleCreate().  Adjust the values as necessary
$ArticleID = $client->__soapCall("Dispatch", 
array($username, $password,
"TicketObject", "ArticleCreate",
"TicketID", some_ticketID_to_add_article_to,
"ArticleType", "webrequest",
"SenderType", "customer",
"HistoryType", "WebRequestCustomer",
"HistoryComment", "created from PHP",
"From", "some_customer@your_organization",
"Subject", "Some Subject",
"ContentType", "text/plain; charset=ISO-8859-1",
"Body", "Some Article Body text",
"UserID", some_userID_number,
"Loop", 0,
"AutoResponseType", 'auto reply',
"OrigHeader", array(
'From' => 'some_customer@your_organization',
'To' =>  'some_customer@your_organization',
'Subject' => 'Some Subject.  Probably the subject from above',
'Body' => 'Some Body text.  Probably the body from above'
),
)
);
[/code]

===============

TicketGet() 
Required Input Values: TicketID(integer)
Returns: Array of Age(integer), PriorityID(integer)ServiceID(integer), Type(text), Responsible(text), StateID(integer), ResponsibleID(integer), ChangeBy(integer), EscalationTime(integer), Changed(date/time), OwnerID(integer), RealTillTimeNotUsed(integer), GroupID(integer), Owner(text), CustomerID(text), TypeID(integer), Created(date/time), Priority(text), UntilTime(integer), EscalationUpdateTime(integer), QueueID(integer), Queue(text), State(text), Title(text), FirstLock(date/time), CreateBy(integer), TicketID(integer), StateType(text), EscalationResponseTime(integer), UnlockTimeout(integer), EscalationSolutionTime(integer), LockID(integer), TicketNumber(integer), ArchiveFlag(text), CreateTimeUnix(unixtime), Lock(text), SLAID(integer), CustomerUserID(text)

[code]
// PHP code sample for TicketGet().  Adjust the values as necessary
$TicketDetails = $client->__soapCall("Dispatch", 
array($username, $password,
"TicketObject", "TicketGet",
"TicketID", some_ticketID_number,
"Extended", 1,
));
[/code]

===============

TicketSearch()
Required Input Values: CustomerUserID(text)
Returns: Array of TicketID(integer), TicketNumber(integer)

[code]
// PHP code sample for TicketSearch().  Adjust the values as necessary
$TicketDetails = $client->__soapCall("Dispatch", 
array($username, $password,
"TicketObject", "TicketSearch",
"CustomerUserID", "some_customers_login",
));
[/code]

One additional thing to note.  Both of the last two functions return arrays of values, rather than a single value.  You might want to look at my post about how to parse the values into a usable array.

Jeff Eske

SEE ALSO:
OTRS – Simple Web Service Example Using PHP,

PHP Script to Display SOAP Requests and Responses,

OTRS – TicketGet() Web Service Example in PHP

OTRS – TicketGet() Web Service Example in PHP

OTRS,Web Services,Web Stuff — Jeff Eske on March 5, 2013 at 11:42 am

UPDATED:  I’ve changed employers and have moved on to other projects.  I no longer use OTRS, or have access to OTRS, so I won’t really be able to help you beyond what I’ve already posted here. 

Jeff

Continuing on with my studies of OTRS web services, I’ve created a page that will pull an OTRS ticket back when supplied with the ticket’s ID via GET.  Prior to this I posted how to create a ticket using the OTRS TicketCreate() SOAP function. Basically, you give the page the ticket ID via the URL – http://webserver/get_ticket.php?id=xx. I’ve included a complete ticketGet zip file at the end.  In addition to this example, I have another post explaining how to submit a ticket via web services.

Basically, all that’s required is passing one argument, the TicketID, and you can get back ALL of the ticket details.  It’s actually much more straightforward than I assumed that it would be.  One thing that I noticed is that reading through the OTRS dev documentation, the order that the ticket details are returned is different than what actually comes back.  That’s not really a big deal, since I moved everything into an array, with the various ticket details saved as a key/value pair.  More on that later.  The example that I have here only returns the ticket, but it is possible to return the associated articles also, but that will be for a later post.

The actual soapCall() function looks like this:

[code]
$TicketDetails = $client->__soapCall("Dispatch", 
array($username, $password,
"TicketObject", "TicketGet",
"TicketID", $TicketID,
));
[/code]

All I’m passing in is the SOAP username and password, along with the TicketID.  What it returns then is an XML-formatted response.  My page parses all of the returned values into an array, by using a foreach loop.  There are probably much more elegant solutions, but this works. Because of the way OTRS returns things, my foreach loop is a little janky.  Like I said, there’s probably a more elegant solution.

Without further ado, here’s the foreach loop:

[code]

$ticketInfo = array();
$i = 0;
foreach ($TicketDetails as $name => $value){
    if (false !== strpos($name, "s-gensym")){
        $temp[$i] = $value;
        $v = $temp[$i-1];
        //echo $value."<br>";
        if($i % 2 != 0){
            $ticketInfo[$v] = $value;
        }
        $i++;
    }
}
[/code]

As I said – a little janky.  Anyway, basically what OTRS does it returns the detail’s name as a variable, then the detail’s value as the NEXT variable like: “Age”, “123421”, “Title”, “This is my ticket title”, “TicketID”, “2”, so basically, you get the detail name, then the detail value.  To get these into a usable format, I’m basically creating 2 arrays, $temp[] and $ticketinfo[].  Since I’m simple-minded, the easiest thing for me to do was to create the $temp[] array so that I could basically use it as the “key” array when populating the $ticketinfo[] array.  Then what I’m doing is basically putting things into the $ticketinfo[] array as key/value pairs.  I take the current value – $value and put it in as the value and use the previously returned value, from $temp[], as the key.

I’ve included the complete commented code for the page below.  You can copy/paste it into a new, blank page, or you can download the zipped version of the file below.

[code]
<?PHP
error_reporting(E_ALL);
#### OTRS specific information ####
$url = "http://your_otrs_server/otrs/rpc.pl"; // URL for OTRS server
$username = "SOAP_username"; // SOAP username set in sysconfig
$password = "SOAP_password"; // SOAP password set in sysconfig
$TicketID = $_GET[id];
########################################################################
#### You don't have to change anything below here, although you can ####
########################################################################
#### Initialize new client session ####
$client = new SoapClient(
 null, 
 array(
 'location' => $url,
 'uri' => "Core",
 'trace' => 1,
 'login' => $username,
 'password' => $password,
 'style' => SOAP_RPC,
 'use' => SOAP_ENCODED
 )
);
#### Create and send the SOAP Function Call ####
$TicketDetails = $client->__soapCall("Dispatch", 
array($username, $password,
"TicketObject", "TicketGet",
"TicketID", $TicketID,
));
#### Get the SOAP response into an array as key/value pairs ####
# This is kind of janky, but what it does is parse out the #
# detail values in the SOAP response and writes them as a key/value #
# pair in the $ticketInfo[] array. #
$ticketInfo = array();
$i = 0;
foreach ($TicketDetails as $name => $value){ // explode the xml response
 if (false !== strpos($name, "s-gensym")){
 $temp[$i] = $value; 
 $v = $temp[$i-1]; 
 if($i % 2 != 0){ 
 $ticketInfo[$v] = $value; 
 }
 $i++;
 }
}
##############################################################################
#### The code below here is just to provide viewable proof that it worked ####
#### It can all be commented out or removed ####
##############################################################################
#### Return the SOAP request and response as xml-formatted text ####
print "<pre>\n"; 
print "Request :\n".htmlspecialchars($client->__getLastRequest()) ."\n"; 
print "Response:\n".htmlspecialchars($client->__getLastResponse())."\n"; 
print "</pre>";
echo"<hr width='200'>";
// Spew out the key/value pairs from the $ticketInfo[] array
foreach ($ticketInfo as $name => $value){
 echo "<b>".$name.":</b> ".$value."<br>";
}
?>
[/code]

Here’s the ticketGet zip file.  The formatting is obviously better in that version than what you see above.

Jeff Eske

 

PHP Script to Display SOAP Requests and Responses

Programming,Web Services,Web Stuff — Jeff Eske on March 5, 2013 at 10:15 am

Some time back, while working out web services on another project, I put together a janky little snippet of PHP code that’s actually pretty handy when dealing with SOAP-based web services.  For me, the hardest part of working with web services is trying to figure out exactly what the request needs to look like to work correctly.  The other thing is figuring out exactly what I got back!  This little snippet actually shows you what the xml-formatted SOAP request and SOAP response each look like.  The REALLY nice thing is that it only takes 4 lines of code.

Here’s what it looks like:

[code]
print "<pre>\n";
print "Request :\n".htmlspecialchars($client->__getLastRequest()) ."\n";
print "Response:\n".htmlspecialchars($client->__getLastResponse())."\n";
print "</pre>";
[/code]

Basically, all you do is plug this in after you’ve created your new SoapClient() object and performed the soapCall().  A basic example would look like the code below.  Please note, this isn’t a working piece of code, just an illustration of how it would look.

[code]
$client = new SoapClient(
 some client specifics here
);
$SomeSoap = $client->__soapCall(
  do some SOAP function
);
print "<pre>\n";
print "Request :\n".htmlspecialchars($client->__getLastRequest()) ."\n";
print "Response:\n".htmlspecialchars($client->__getLastResponse())."\n";
print "</pre>";

[code]

What this should get you, when you run the script, is two separate, preformatted lines of text.  The first line will be the XML-formatted request that PHP sent to the web service.  The second line should be the XML-formatted response returned.  Granted, this doesn’t necessarily give you the final format that you need, but it will get you names of all of the XML variables that have been returned.  With that information, you can proceed to find a way to extract the information that you need.

Stay tuned for more on this subject.

Jeff Eske

OTRS – Simple Web Service Example Using PHP

OTRS,Web Services,Web Stuff — Jeff Eske on July 27, 2012 at 10:54 am

UPDATED:  I’ve changed employers and have moved on to other projects.  I no longer use OTRS, or have access to OTRS, so I won’t really be able to help you beyond what I’ve already posted here. 

Jeff

A fair amount of my traffic seems to be people looking for information about using web services in OTRS.  I’ve written a couple of entries about this in the past.  One covers changes in the services from 3.1.2 to 3.1.4.  In the other entry, I briefly described how easy it is to create tickets via web services.  This time around, I’ll provide a basic example of how to actually create a ticket via web services, using PHP to make the TicketCreate() SOAP request.  I’m in the process of integrating this into a mobile front-end for OTRS.

UPDATE: 2013-2-25 – I’ve just tested this with version 3.2.1 and it still works, as is.

UPDATE: 2013-3-5 – I’ve added a post describing how to use the OTRS TicketGet() SOAP function also.

I’ve created a zip file that contains two files.

form.html
form.html is a VERY basic html page that has a form on it.  There are only 3 fields in the form – Customer Login ID, Title, Description.  You could very easily add, or even remove, fields in the form to allow more, or less, control by the end user.

add_ticket.php
add_ticket.php actually does the heavy lifting.  There’s a section towards the top where you’ll need to set some variables to match your implementation of OTRS.  I’ve commented the code, but I’ll go over the variable part below.

Here’s the section of add_ticket.php that will need to be updated to your specifics:

[CODE]

#######    PLEASE SET THESE VARIABLES TO MATCH YOUR SYSTEM     #########
#  You can set others in the code below, but these should be the main  #
#  things that you may want to adjust.                                 #
########################################################################

$url      = “http://your_otrs_server/otrs/rpc.pl”;  // URL for OTRS server
$username = “SOAPusername”;  // SOAP username set in sysconfig
$password = “SOAPpassword”;  // SOAP password set in sysconfig
$typeID = 2; // id from ticket_type table
$queueID = 2; // id from queue table
$priorityID = 1; // id from ticket_priority table
$ownerID = 2; // id from users table

[/CODE]

The first 3 – $url, $username, $password, are all pretty simple.  As the comment in the example above notes, and as Tomasz pointed out in his comment, you will need to set the SOAP username and password in the OTRS Admin interface at –

http://server/otrs/index.pl?Action=AdminSysConfig;Subaction=Edit;SysConfigSubGroup=Core::SOAP;SysConfigGroup=Framework;#

One thing to remember on the URL is that if you are using SSL on your server, you’ll need to change from http:// to https://.  The other 4 – $typeID, $queueID, $priorityID, and $ownerID,  will all need to be changed to ids from your system.

I use MySQL Query Browser to pull back this info but, due to the way OTRS works, you can gather that info directly from the application.  For instance, to find the id for the user that you want to use as the default owner, you can simply go in as an Admin and goto Admin > Agents.  Once you have the list of Agents, simply mouse over the Agent that you’d like to use.  When you mouse over, you should see the URL in the Status Bar of the browser.  If you look at the URL – https://otrs_server/otrs/index.pl?Action=AdminUser;Subaction=Change;UserID=2;Search=, you’ll see UserID=some number (bolded in the example).  This number is the id that you need.  Same with the other values.  You should be able to find places within OTRS with links to the things that you need.  Within the URLS, there will be an id=number.  That number should be the value that you need.

If you understand PHP, forms, and form processing, it’s really easy to expand the usefulness of forms.  Some examples would be:

1> Add form fields to collect specific information from the customer that is necessary for solving the problem but isn’t readily available otherwise.  You then take those bits and pieces and combine them into the description, via the add_ticket page.  This can get you a more complete description of the problem than possible with a simple text box where the customer is responsible for trying to figure out what needs to be added.

2> Add a Type dropdown to the form and pass that id over to add_ticket.  That would allow the customer to indicate if it was a failure, request, etc.

3> Add a Priority dropdown to the form and pass the id.  That would allow the customer to indicate what they think the priority is.  In my experience, most will mark it as High Priority, no matter how mundane the issue…

Generally, in my experience, the less choices that you give to the customer, the better off you are.

Anyway, have fun.

Jeff Eske

================================
Download the zip file – Simple Web Services example

OTRS – Web Services from 3.1.2 to 3.1.4+

OTRS,Web Services,Web Stuff — Jeff Eske on June 6, 2012 at 3:21 pm

UPDATE:  I’ve now created sample files and posted a quick run-through on what’s needed to use them.

When OTRS was upgraded from 3.1.2 to 3.1.4, it seemed that web services were broken.  After upgrading, my form-to-ticket processing page quit working.  I did some investigating within OTRS documentation, as well as looking at the included rpc-example.pl script to see if I could figure out what, if anything, had changed.  I went back out to their site and looked at the release notes for 3.1.4 to see if it could shed any light on the situation.  Well, in the release notes, it indicates that it fixes “Bug#8363 – SOAP Transport can’t send a value ‘0’”.   “OK then”, I say.  They did something with the web services and broke something else.  Since I knew 3.1.2 web services worked, and I needed them, I just stuck with 3.1.2.

It’s been a few weeks now and they’ve released 3.1.5 and 3.1.6 now.  I decided to download 3.1.6 and see if they “fixed” the web services problem.  Well, after upgrading my system to 3.1.6, web services STILL didn’t work!  Well, either they didn’t really care about web services, or I was missing something!

I started digging into things and found that, from what I can tell, there are now numerous other values that need to be passed in to successfully create a new ticket (not an article) via web services.  Also, as far as I can tell, the the rpc-example.pl script and the documentation haven’t been updated to indicate that.  Ive included “before” and “after” examples below.  I don’t remember for sure anymore, but I think that this blog post was my starting point for creating my original processing page.

Code that worked BEFORE 3.1.4

[CODE:]

$TicketID = $client->__soapCall(
“Dispatch”, array($username, $password,
“TicketObject”, “TicketCreate”,
“Title”,        $title,
“Queue”,        “Raw”,
“Lock”,         “Unlock”,
“PriorityID”,   1,
“State”,        “new”,
“CustomerUser”, $from,
“CustomerID”, “some ID”,
“OwnerID”,      1,
“UserID”,       1,
));

[/CODE:]

Code that works for 3.1.6 (I skipped 3.1.4 and 3.1.5, but I assume it works there also.  I’ll test to see):

[CODE:]

$TicketID = $client->__soapCall(
“Dispatch”, array($username, $password,
“TicketObject”, “TicketCreate”,
“Title”,        $title,
“TypeID”,    2,
“QueueID”,   2,
“LockID”,  1,
“PriorityID”,   2,
“State”,        “new”,
“CustomerUser”, $from,
“CustomerID”, “some ID”,
“OwnerID”,      1,
“UserID”,       1,
));

[/CODE:]

Note that I had to add TypeID, change Queue to QueueID and Lock to LockID, all with corresponding ids from the database.  Whether this is the ONLY solution or not, I don’t know, but it did get things back to where I can submit via web services again.

Jeff Eske

OTRS – Creating a Ticket Via Web Services

OTRS,Web Services,Web Stuff — Jeff Eske on June 5, 2012 at 9:53 am

UPDATE:  I’ve now created sample files and posted a quick run-through on what’s needed to use them.

The self-service page in OTRS works well for submitting tickets, but it can be made even simpler.  OTRS comes with web services capabilities that are really easy to take advantage of.  By using the web services, you can create a form with specific fields to be filled in, to help guide the customer through providing the information that you want to collect.

You could make a single-page form with all of the fields listed in one place, or you could create a “wizard” that walks the customer through a series of questions to get all of the desired information.  Once it’s all collected, you send it to a submission/processing page that associates the collected information with the appropriate field(s) within OTRS and submits it.  With my setup, I’m collecting information via several form fields, then basically combining them all and placing them in the ticket body.  I’m also determining which queue the ticket will end up in, based on the form name.  If it’s FORM1, it goes to this queue, with this priority.  If it’s FORM2, it goes to this queue, with that priority, etc.   This allows us to collect very specific information from the customer and have it sent to the correct people with no outside intervention.  It’s pretty handy.

Jeff Eske

OTRS – Web services appear to be broken in OTRS 3.1.4

OTRS,Web Services,Web Stuff — Jeff Eske on May 3, 2012 at 3:25 pm

I’ve upgraded my test machine to OTRS 3.1.4 and now my web services seem to have quit working.   They did a fix (Bug#8363 – SOAP Transport can’t send a value ‘0’. ) and now, that’s all I get!  I get no error message indicating that there’s a problem, but no ticket is created and it tells me that it created Ticket 0.  At least it can pass me that zero now…

UPDATE:  Well, it appears that the web services might not have been broken, but they changed some of what needs to be passed in to be successful – see Web services from 3.1.2 to 3.1.4+ for details.

Web Services – Slowly but surely…

ITSM,Web Services,Web Stuff — Jeff Eske on August 23, 2011 at 3:57 pm

Just figured out how to get a SOAP request to submit successfully in ITSM7, via soapUI.  Now to figure out how to do something constructive with it.

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 2.5 License. | Jeff's Blog