OTRS Soap Interface

Disclaimer: This are my first trys with the Soap Interface. If you’ve got better information just send it to me or post a comment, I will gladly update this documentation. I just wrote this article because there is almost no information about the OTRS Soap-Interface on the web. Perhaps it helps someone.

At first it is necessary to set the Soap user and password:

  1. - Login into your existing OTRS Installation as Admin
  2. - in the Menu under “Admin”->”Sysconfig” set Group to “Framework” and click “show”
  3. - In the list of subgroups click “Core::SOAP”
  4. - Check the boxes for SOAP::User: and SOAP::Password: and enter the values you like
  5. - click update

Now you can use the OTRS Functions over SOAP.

At my test installation the Setting of the username and password over the admin-interface didn’t work at all. I had to enter it manually in the rpc.pl, but normally I think it should work.

You find a documentation of the OTRS-Modules/Functions you can use here:

http://dev.otrs.org/

The invocation of a Module/Function works like follows:

$RPC->Dispatch($User, $Pw, 'Module','Function', Parameter);

A good start is the rpc-example.pl, which you find in the folder scripts of your OTRS-Install. I modified the example a bit to create a ticket. No guarantee that this doesn’t crash your database, so don’t try on a live system.

scripts/rpc-example.pl

use SOAP::Lite('autodispatch', proxy => 'http://localhost/otrs/rpc.pl');
my $User = 'exampleuser';
my $Pw = 'examplepass';
my $RPC = Core->new();
# create a new ticket number
my $TicketNumber = $RPC->Dispatch($User, $Pw, 'TicketObject','TicketCreateNumber');
print "RPC: New Ticketnumer created: ".$TicketNumber."\n";
my $TicketId = $RPC->Dispatch($User, $Pw, 'TicketObject', 'TicketCreate',
       TN => $TicketNumber,
       Title => 'Test Ticket',
       Queue => 'Raw',                # or QueueID => 123,
       Lock => 'unlock',
       PriorityID => 2,         # or PriorityID => 2,
       State => 'open',                # or StateID => 5,
       CustomerUser => 'customer at example.com',
       OwnerID => 1, # new owner
       ResponsibleID => 1, # new responsible
       UserID => 1,
);
print "RPC: New Ticket id is: $TicketId\n";
my $ArticleID =$RPC->Dispatch($User, $Pw, 'TicketObject', 'ArticleSend',
        TicketID         => $TicketId,
        ArticleType      => 'email-external',                   # email-external|email-internal|phone|fax|...
        SenderType       => 'agent',                           # agent|system|customer
        From             => 'root',  # not required but useful
        To               => 'customer', # not required but useful
        Cc               => '', # not required but useful
        ReplyTo          => '', # not required
        Subject          => 'Test Ticket',          # required
        Body             => "Test Body",                # required
        MessageID        => '',     # not required but useful
        Charset          => 'ISO-8859-15',
        HistoryType      => 'EmailCustomer',                     # EmailCustomer|Move|AddNote|PriorityUpdate|WebRequestCustomer|...
        HistoryComment   => 'Some free text!',
        UserID           => 1,
        NoAgentNotify    => 0,                                 # if you don't want to send agent notifications
        Type             => 'text/plain',
        Loop             => 0,                       # auto reject|auto follow up|auto follow up|auto remove
    );

Of course this works in PHP too. The task i wanted to do is send an e-mail to a user and simultaneously create a ticket in otrs. This is the ticket creation process in otrs:

  • create a new ticketnumber
  • create a new ticket with that number
  • attach a message (called article) to the ticket, which at once is sent out per mail

Of course the last step can vary. if you don’t want to send an e-mail for example.

# WARNING: This could destroy your OTRS-Database, please use only for testing and as a starting point for your own developments

$user = "testuser";
$pass = "testpass";
$url = "http://localhost/otrs/rpc.pl"  # replace with your own otrs url

# initialising soap client
$soapclient = new SoapClient(null, array('location'  => $url,
                             'uri'       => "Core",
                             'trace'     => 1,
                             'login'     => $user,
                             'password'  => $pass,
                             'style'     => SOAP_RPC,
                             'use'       => SOAP_ENCODED));
 
# creating a ticket number
$ticketnr = $soapclient->__soapCall("Dispatch", array($user, $pass, "TicketObject", "TicketCreateNumber"));
 
#php changes long numbers to 123E+10 notation to prevent this screwing up our ticketnumbers we convert notation
#it into normal plain numbers. but only if not string, because sometimes you have a string addition like XY123 on your
#ticket numbers
if(! is_string($ticketnr) ) $ticketnr = number_format($ticketnr,0, '.', '');
 
# create the new ticket
$title = "some test title";
$queue = "support";
$customerid = "1234567";
$customeruser = "John Doe";
$userid = 3;   # your OTRS-Userid, varies of course in every installation

$ticketid = $soapclient->__soapCall("Dispatch", array($user, $pass, "TicketObject", "TicketCreate",
									       "TN", $ticketnr,
									       "Title", "[ Ticket#: ".$ticketnr." ] ".$title,
									       "Queue", $queue,
									       "Lock" , "unlock",
									       "PriorityID", 5,
									       "State" , "closed successful",
									       "CustomerId", $customerid,
									       "CustomerUser", $customeruser,
									       "OwnerID" , $userid,
									       "UserID", $userid
									       ));
 
#create the new e-mail message, which is send out and attached to the ticket automatically

$from = "support@example.com";
$to = "janedoe@example.com";
$message = "pay your bills";
 
$articleid = $soapclient->__soapCall("Dispatch", array($user, $pass, "TicketObject", "ArticleSend",
				    "TicketID"         , $ticketid,
			        "ArticleType"      , "email-external",
			        "SenderType"      , "agent",
			        "From"             , $from,
			        "To"               , $to,
			        "ReplyTo"          , "",
			        "Subject"          , "[ Ticket#: ".$ticketnr." ] ".$subject,
			        "Body"             , $message,
			        "ContentType"      , "text/plain; charset=utf-8",
			        "Charset"          , "utf-8",
			        "HistoryType"      , "EmailCustomer",
			        "HistoryComment"   , "generated by OTRSInterface-Class",
			        "UserID"           , $userid,
			        "NoAgentNotify"    , 0,
			        "MimeType"             , "text/plain",
			        "Loop"             , 0
			    	));

Of course this is just a very basic example. You can really use any OTRS-Class over the SOAP-Interface, just read the API. I realized, that some of the Objects are not created correctly in rpc.pl. So just add the additonal ones you need:

use Kernel::System::Group;
use Kernel::System::Queue;   # this one I added by myself
use Kernel::System::Ticket;
 
# ... some more code
 
$CommonObject{GroupObject} = Kernel::System::Group->new(%CommonObject);
$CommonObject{QueueObject} = Kernel::System::Queue->new(%CommonObject);  # you have to add this too
$CommonObject{TicketObject} = Kernel::System::Ticket->new(%CommonObject);

If you have still some questions, just ask.

pixelstats trackingpixel

Comments (14)

johpieMay 9th, 2009 at %I:%M %p

Some Calls need an Array in an Array for example ArticleSend with Sign, Attachment and so on. How can I realise this with PHP?

adminMay 9th, 2009 at %I:%M %p

Good question. I didn’t try it yet, but on monday I’ll do some tests and further investigation. If meanwhile you already found the solution please post it here, too.

johpieMay 9th, 2009 at %I:%M %p

I don’t know my mistake at first time, but it is very simple. For example:

“OrigHeader”, array(
‘From’ => $customerMail,
‘To’ => $toAdress,
‘Subject’ => $title,
‘Body’ => $body
)

Btw. you need to set OrigHeader when you want to use the auto-replay function of OTRS.

SebastianJune 30th, 2009 at %I:%M %p

Hi,
netter Artikel, allerdings habe ich Probleme mit sonderzeichen. Egal in welchem Encoding ich Strings übertrage, OTRS quittiert mit diese nur mit Salat. Gibt es Erfahrungen mit UTF-8?

Grüße!

adminJune 30th, 2009 at %I:%M %p

Also wichtig war bei uns, dass OTRS und e-mail das gleiche Charset haben. z.B. bei dem Perl-Beispiel ist als Mail-Charset ISO-8859-15 eingestellt, bei dem php-Beispiel ist es utf-8, also da evtl. vorsichtig sein. Anfangs hatte es bei mir mit den Umlauten auch nicht geklappt, da unser OTRS auf utf-8 lief, ich die Mail aber in iso versendet hatte. Nach einer kleinen Umstellung auf Mail-Charset utf-8 funktionierte alles perfekt.

AndréSeptember 9th, 2009 at %I:%M %p

Hi.

Ich habe gerade mal den Perl Part für den Article unter OTRS 2.4.4 probiert, indem ich es der rpc-example.pl hinzugefügt habe.

Es wird zwar ein Ticket angelegt aber kein Article erzeugt.

Hast du ne Idee warum?

Danke im Voraus.

MfG
André

AndréSeptember 9th, 2009 at %I:%M %p

“Type” muss in “MimeType” umebnannt werden, dann gehts….

LingaJune 3rd, 2010 at %I:%M %p

what ever the things u hav said is all perfect in rpc-example.pl and rpc.pl… stii if i run the php code i get an error
“Fatal error: Uncaught SoapFault exception: [soap:Client] Application failed during request deserialization: no element found at line 1, column 0, byte -1 at /usr/lib/perl5/XML/Parser.pm line 187 in /var/www/lp/soap2.php:30 Stack trace: #0 /var/www/lp/soap2.php(30): SoapClient->__soapCall(‘Dispatch’, Array) #1 {main} thrown in /var/www/lp/soap2.php on line 30″

adminJune 22nd, 2010 at %I:%M %p

Linga: I read a forum-thread you posted in another forum, and they gave you this link

http://wiki.anothergeek.ca/tiki-index.php?page=PHPOTRSSOAP

Did this solve your problem? Would be nice if you leave some comment, perhaps someone else has the same problem.

BorisJune 24th, 2010 at %I:%M %p

I get this error in PHP
“Fatal error: Class ‘SoapClient’ not found …”
What should I include within PHP script to get it work?

adminJune 24th, 2010 at %I:%M %p

You have to install the soapclient libraries for PHP, they have to be in your Standard-PHP-Classpath, then it should work.

for example under debian something like this should be sufficent:
apt-get install php-soap

BorisJune 25th, 2010 at %I:%M %p

Thanks! It works!

Bijal BhavsarJuly 31st, 2010 at %I:%M %p

Hello,

Hello I m new to using Web services like soap. I have to integrate OTRs in magento , when we enter contact us details .. that details we have to pass in OTRS to create ticket.

I have question regarding rcp.pl file.. where we have to place that file and “Dispatch” function definition – i can’t understand where this function is created.Is that function is in OTRS system or we have to create in php.

I am getting error “No operation Dispatch in WSDL”
I have used code from this link :: “http://wiki.otrs.org/index.php?title=Create_a_ticket_in_OTRS_from_PHP_via_RPC”

Awaiting for your reply… Plz help me to solve this issue.

Thanks,
Bijal Bhavsar

adminAugust 4th, 2010 at %I:%M %p

The file rpc.pl is part of otrs and is the SOAP-Interface to OTRS. It is important, that you enter the correct URL to the rpc.pl file. Perhaps you can post your php code snippet. I’m pretty sure you put a wrong URL here:

$url = “http://example.com/otrs/rpc.pl”;

This has to be replaced to the file in your OTRS-Installation

Leave a comment

Your comment

Security Code: