Skip to Content

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.

    Warning

    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 Save to complete enabling the feature.

Warning

Disclaimer

Sample Code included in this section are for your use only, and are not included or covered by the BMC Services Maintenance and Support Agreement nor are they supported by the BMC Support group.  You use this at your own risk and BMC shall have no liability to you or any other party for damages in connection with your use and/or distribution of this sample code.  BMC 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 issues 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 the MSDN .NET Framework Class Library Encoding Class article). 

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.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*

FootPrints Service Core Online Help 11.6