Web Services API

The Web Services API provides functions for both regular FootPrints Issues and CMDB, as follows:

• FootPrints Issues
• search—Searching the FootPrints database (using queries for Issue, Address Book, History data, etc.)  This search can be more complex than the built-in searching functions of the FootPrints interface, since users can, for example, build combinations of AND and OR queries.
• getIssueDetails—Retrieve the details of an Issue.
• createIssue—Create an Issue.
• editIssue—Edit an Issue.
• linkIssues—Create dynamic or static link between Issues.
• createContact—Create a new contact in the Address Book.
• editContact—Edit an existing contact in the Address Book.
• createOrEditContact—Create a new or edit an existing contact in the Address Book.
• CMDB
• createCI—Create a CI.
• editCI—Edit a CI.
• createCIRelation—Define a relationship between CIs. This does not mean that you create the relationship, but that you sue an existing relationship to relate one CI to another.
• createCIContactLink—Link a contact to a CI.
• createCIIssueLink—Link an Issue to a CI.

If an error occurs in any of these functions, they will return a fault string containing a description of the error, including identifying where in the code the error has occurred.

The functionality is limited in that the programmatic interface to FootPrints cannot alter the database structure.  For instance, the user (or program) could not remove a database column.

The Web Services API also has the following characteristics/limitations:

• Users are not formally logged in, thereby allowing multiple web services to run simultaneously.
• Authentication is done on a subroutine by subroutine basis rather than authenticating and passing around a token.  Therefore, each subroutine requires a username and password.
• The authentication username can be an administrator or agent.

NOTE

An additional fixed license is not required for this particular system administrator username.

• A system preference determines if web services are used and, by default, is set to OFF.

Footprints uses a Perl module, SOAP::Lite, to implement it's back-end web services, which allows for efficient implementation and code re-use.  However, it does not fully support interoperability with C# web services.  When complex data needs to be returned (i.e., data which is not a single string), web services returns an XML string.  This comprises self-describing arrays and hashes defined by the following DTD:

<!ELEMENT array (item*)>

<!ELEMENT map (item*)>

<!ELEMENT item (#PCDATA|array|map)*>

<!ATTLIST item

key CDATA #REQUIRED

defined CDATA #IMPLIED>

<!ELEMENT data (array|map)*>

The Web Services API can be called from any programming language that supports an XML/SOAP client.  FootPrints Web Services has been tested with Perl, C#, and Java clients and examples of these calls are included in this document.  Some C# and Java clients call FootPrints with the extraInfo parameter, which is an extension point to allow extra parameters to be passed into web services without changing their definitions.  Currently, it is used to allow .NET and JAVA clients to request results as a single XML string.  Refer to the sample code for additional information.   Perl clients always use an empty string for this parameter.

This feature must be enabled by selecting Administration | System | Web Services from the FootPrints Toolbar and then selecting the Enabled radio button.  Enter your password and then click GO to complete enabling the feature.

DISCLAIMER

Sample Code included in this section are for your use only, and are not included or covered by the Numara Software Services Maintenance and Support Agreement nor are they supported by the Numara Software Support group.  You use this at your own risk and Numara Software shall have no liability to you or any other party for damages in connection with your use and/or distribution of this sample code.  Numara Software is not responsible for errors or defects in the software, any use of the software or inability to use the Software, or incidental or consequential damages arising out of use of Sample Code.

Issues with International Characters

It is possible that you might not be able to add international characters correctly to tickets when using web services.  Should this be the case, convert all the arguments to UTF-8 using a Perl module. An easy way to do this is as follows:

use Encode;

$argument = encode_utf8($argument);

There is no difference when you do this using either UTF-8 encoding for FootPrints or local encoding, but your results may differ.  If you are using .NET, similar encoding can take place with System.Text.Encoding from the .Net Framework (refer to http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfsystemtextencodingclasstopic.asp).  Other languages have similar functionality available.

When reading the data using web services, you must do the opposite.  In Perl, use:

use Encode;

$returnValue = decode_utf8($returnValue);

As already mentioned, .NET could use System.Text.Encoding from the .NET Framework.

Special Considerations 

If you are using the FootPrints Perl for your SOAP client to connect,it does not support an HTTPS connection unlessyou have the appropriate modules. This is because, due to U.S. export regulations governing cryptography, the following module(s) have not been included in your distribution:

• Net-SSLeay
• Crypt-SSLeay

Instructions for obtaining the modules for a Windows system follow. Please contact Numara Software Support for further information on the acquisition of any required module for a UNIX system.

Windows

To obtain the module(s) on your own, do the following from your server:

1. From the command prompt, change your working directory to:

D:\FootPrints\FPSQL\\bin\Perl\bin

2. From the prompt, type:

ppm install http://theoryx5.uwinnipeg.ca/ppms/Net-SSLeay.ppd

3. Now type:

ppm install http://theoryx5.uwinnipeg.ca/ppms/Crypt-SSLeay.ppd