Setting up the API for FPSC 12

Version 4
    Share This:

    I have had several questions on how to setup and use the new Footprints Service Core 12 API. I created this guide to assist people to make SOAP calls. This document will walk people through generating sample SOAP calls with their existing environment. Developers can use this data to create SOAP calls in what ever language and IDE they wish. This is a first step.

     

    You can find additional information in the API Web service definitions.pdf document.

     

    1) We need to first enable the service by going to Administration-> Integration-> Web Services: Enable the Web Services then restart Tomcat.

    1.PNG

    2) We then need a service account to make the call. You can use a system administrator or create a new account. If you dont want to allow a system administrator then make sure to enable the API access in the system role. Administration-> Roles-> Select a System Role and click edit. System Administrations have this enabled by default. Enable "Can use Web Services".

    1_5.PNG

     

     

    3) Download, install, and launch SoapUI. I will use Soap UI for these example. Most modern IDEs have a way to pull in WSDLs and create SOAP requests.

     

    4) Right click on Projects and select New SOAP Project

    2.PNG

    5) Give it a project name and point he WSDL to http://server:8080/footprints/servicedesk/externalapisoap/ExternalApiServicePort?wsdl

    Change the URL to match your server. You can also use the wsdl at C:\Program Files\BMC Software\Footprints Service Core\conf\externalapiservices.wsdl.

    3.PNG

     

    Enter a System Administrator password when prompted.

    4.PNG

     

    6) Expand the list of available functions and navigate to the list ContainerDefinitions.  Double click on Request 1.

    5.PNG

     

    7) Remove these optional lines for now

    6.PNG

    8) In the bottom left, click Auth then add a new Basic Authorization

    7.PNG

     

    9) Add a System Administrator account (or any system role that has API access that we enabled in step 2)

    8.PNG

    10) Once your request is ready then click the green arrow button in the top left.

    9.PNG

     

    11)  You will get results in the right hand pane. We will use these values to make other calls. Look for the _definitionId of the containter you want to pull from.

    10.PNG

     

    12) Lets do the same steps for listItemDefinitions. Put the definitionId we got back into _containterDefinitionId. I used my Helpdesk Workspace as an example (1523).

    11.PNG

    13) This will return the itemId and a few other pieces of information.

    12.PNG

     

    14) We can do the same steps to get all the Ids for the individual fields with listFieldDefinitions

    14.PNG

     

    15) I also completed the same steps for the address book to get the contact record data

    15.PNG

     

    16) Once we have the Contact ID and the Ticket ID we can create a new incident using the createTicket function

    16.PNG

     

    17) We can then pull the information with getItemDetails

    17.1.PNG

     

     

    18) We can also see the same information in the interface

    17.PNG

    18.PNG

     

    Those are the basic steps you can use to get your API up and running.

     

    I also wanted to look at a few common errors people will get.

     

    HTTP Status 401 - This request requires HTTP authentication (). : You are missing a user in the Authorization. Try adding a system administrator to Auth (bottom left corner)

     

    Expected definition of type ItemDefinitionVersion but got of type ContainerDefinitionVersion by ID 13,220: The itemDefinitionId is incorrect. Try entering the value from step 13. I get this error if I put the value from step 11 instead of step 13.

     

    Unmarshalling Error: cvc-complex-type.2.4.a: Invalid content was found starting with element '_itemDefinid'. One of '{_itemDefinitionId}' is expected.: One of your arguments in the SOAP request is incorrect or malformed. Check the request you are sending into the API.

     

    I hope this helps people get started with our new API. Please feel free to leave questions and comments.