footprintsapi 1.0.6

API wrapper for the BMC (Numara) Footprints SOAP API

FootprintsAPI

A better Python wrapper for Footprints SOAP API.

What is this wrapper for?

This wrapper integrates with Footprint's SOAP endpoints. What is Footprints? Check it out here.

Table of contents

• Quick Start
• Local Deploy Steps
• Notes
• API Endpoints
• SOAP UI Testing
• To Do

Quick start

• Download the repo.
• Clone the repo: https://github.com/Jesus-E-Rodriguez/footprintsapi.git

Add as a project dependency:

$ pip install footprintsapi

Local Deploy steps

Install the required dependencies:

    $ pip install -r requirements/local.txt

Notes

Footprints' internal architecture is as follows:

An object-oriented approach was taken with this project. As such, the SOAP endpoints are called through the use of a Footprints Object.

Instantiate the object with the following attributes:

from footprintsapi import Footprints
import env as settings

attributes = {
    "client_id": settings.CLIENT_ID,
    "client_secret": settings.CLIENT_SECRET,
    "base_url": settings.BASE_URL
}

fp = Footprints(**attributes)

Example settings:

CLIENT_ID = "Agent username"
CLIENT_SECRET = "Agent password"
BASE_URL = "https://{Your hostname here}/footprints/servicedesk/externalapisoap/ExternalApiServicePort?wsdl"

Additional attributes can also be passed in as needed. When the object is instantiated with optional parameters, the functions that require those same parameters will automatically use them if not passed in.

For testing purposes an example wsdl file has been included in tests/wsdl/. In order to get a deeper understanding of the Footprint's architecture the use of SOAP UI is recommended. More documentation can be found in the Web service definitions guide

If you'd like to set up a testing environment in SOAP UI with the included wsdl, please see [SOAP UI Testing] (#soap-ui-testing).

API Endpoints

Endpoint	Method	Parameters (Bolded are required)	Returns	Additional Notes
"createCI"	fp.create_ci(...)	cmdb_definition_id, cifields, status, submitter	CI ID	**

cmdb_definition_id** can be found using fp.list_container_definitions() "createContact" | fp.create_contact(...) | address_book_definition_id, ** contact_fields**, submitter | Contact ID | ** address_book_definition_id** can be found using fp.list_container_definitions() "createItem" | fp.create_item(...) | item_definition_id, ** item_fields**, quick_template_id, assignees, submitter | Contact ID | ** item_definition_id** can be fetched by using fp.list_container_definitions() "createOrEditContact" | fp.create_or_edit_contact(...) | address_book_definition_id, ** contact_fields**, contact_id, submitter | Contact ID | ** address_book_definition_id** can be found using fp.list_container_definitions() "createTicket" | fp.create_ticket(...) | ticket_definition_id, ** ticket_fields**, assignees, submitter, quick_template_id, contact_definition_id, select_contact | Ticket ID | ** ticket_definition_id** can be found using fp.list_item_definitions(container_definition_id). ** ticket_definition_id** is only optional when it has already been passed into the Footprints ticket object. | " createTicketAndLinkAssets" | fp.create_ticket_and_link_assets(...) | ticket_definition_id, ** ticket_fields**, assets_list, assignees, submitter | Ticket ID | See createTicket additional notes | "editCI" | fp.update_ci(...) | cmdb_definition_id, ci_id, ci_fields, status, submitter | CI ID | ** cmdb_definition_id** can be found using fp.list_container_definitions() "editContact" | fp.update_contact(...) | address_book_definition_id, contact_id, ** contact_fields**, submitter | Contact ID | See createContact additional notes "editItem" | fp.update_item(...) | item_definition_id, item_id, ** item_fields**, assignees, submitter | Item ID | See createItem additional notes "editTicket" | fp.update_ticket(...) | ticket_definition_id, ticket_id, ** ticket_fields** , contact_definition_id, select_contact, assignees, submitter | Ticket ID | "getContactAssociatedTickets" | fp.get_contact_associated_tickets(...) | contact_definition_id, ** primary_key_value**, submitter | Sea of Tickets | ** contact_definition_id** can be found using fp.get_container_definitions() typically the container definition id you are looking for will have a sub type name of Address Book. With the proper id, use fp.get_item_definitions(container_definition_id) which will display the contact_definition_id. "getItemDetails" | fp.get_item(...) | item_definition_id, ** item_id**, fields_to_retrieve, submitter | Item Object | "getItemId" | fp.get_item_id(...) | item_definition_id, ** item_number**, submitter | Item ID | The item id can optionally be prepended with your organizational prefix or left has a number. The organization prefix defaults to "SR-" upon object instantiation. "getTicketDetails" | fp.get_ticket(...) | item_definition_id, ** item_number**, item_id, submitter, fields_to_retrieve | Ticket Object | The ticket object has all the returned ticket fields as attributes. As such common fields like the ticket title can be accessed by:

print(
ticket.title)

You can modify the custom attributes that are included in the ticket object by modifying the CustomAttributesMixin found in:

from footprints.mixins.common import
CustomAttributesMixin

"linkItems" | fp.link_items(...) | first_item_definition_id, first_item_id, ** second_item_definition_id**, second_item_id, ** link_type_name**, submitter | Dynamic Item Link ID | No assumptions are made regarding the linking of items. Both item definition ids and their respective item ids must be passed in. The list of acceptable ** link_type_name**(s) can be found within the method documentation. "linkTickets" | fp.link_tickets(...) | first_ticket_definition_id, first_ticket_id, ** second_ticket_definition_id**, second_ticket_id, ** link_type_name**, submitter | Dynamic Item Link ID | See linkItems additional notes " listContainerDefinitions" | fp.get_container_definitions(...) | container_subtype_name, submitter | List of container dictionaries | Use this function to get the definition ids of various workspaces " listItemDefinitions" | fp.get_item_definitions(...) | item_definition_id, submitter | List of item dictionaries | Use this function to get the items within a workspace " listFieldDefinitions" | fp.get_field_definitions(...) | item_definition_id, submitter | List of field dictionaries | Use this function to get the fields relevant to an item "listQuickTemplates" | fp.get_quick_templates(...) | item_definition_id, submitter | List of dictionaries | " listSearches" | fp.get_searches(...) | item_type_name, submitter | List of dictionaries | You can use this parameter to retrieve item name only from the existing Saved Searches in the FootPrints application. " runSearch" | fp.get_search(...) | search_id, submitter | Dict | You can retrieve the item_type_name parameter to get the item ID to run the search query from the existing Saved Searches only. ** Note: You must create Saved Searches in the FootPrints application before using the web service to run the search queries. You cannot create Saved Searches by using the web services.**

SOAP UI Testing

The following guide goes over setting up the local wsdl and setting up mock responses. In order to test the get_ticket method, you will need to mock the getItemId and the getTicketDetails service.

Make sure your mock service is running. You will need the endpoint the mock service is running on. It will look similar to something like this: http://your-PC:8088/mockExternalApiServiceSoapBinding. For use as the base url in the Footprints object, you only need to append ?WSDL.

Also ensure you set up your mock responses.

An example getItemId mock return:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ext="http://externalapi.business.footprints.numarasoftware.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <ext:getItemIdResponse>
         <!--Optional:-->
         <return>9001</return>
      </ext:getItemIdResponse>
   </soapenv:Body>
</soapenv:Envelope>

And example getTicketDetails mock return:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ext="http://externalapi.business.footprints.numarasoftware.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <ext:getTicketDetailsResponse>
         <!--Optional:-->
         <return>
            <!--Optional:-->
            <_ticketNumber>SR-00001</_ticketNumber>
            <!--Optional:-->
            <_submitter>Jesus Rodriguez</_submitter>
            <!--Optional:-->
            <_createDate>07/05/21</_createDate>
            <!--Optional:-->
            <_createTime>10:00pm</_createTime>
            <!--Optional:-->
            <_title>Testing</_title>
            <!--Optional:-->
            <_status>Pending</_status>
            <!--Optional:-->
            <_priority>Low</_priority>
            <!--Optional:-->
            <_description>Something really bad happened!</_description>
         </return>
      </ext:getTicketDetailsResponse>
   </soapenv:Body>
</soapenv:Envelope>

Hence, a sample python script could be as follows:

from footprintsapi import Footprints

attributes = {
    "client_id": "Doesn't matter for mock response",
    "client_secret": "Doesn't matter for mock response",
    "base_url": "http://your-pc:8088/mockExternalApiServiceSoapBinding?WSDL",
}

fp = Footprints(**attributes)
# Passed attributes don't matter, the mocked responses will return regardless
print(fp.get_ticket("80001", "SR-0001"))
# Ticket(ticket_number='SR-00001', submitter='Jesus Rodriguez', create_date='07/05/21', create_time='10:00pm', title='Testing', status='Pending', priority='Low', description='Something really bad happened!')

In order to get a good testing case, ensure the items you mock are as close to your Footprints instance as possible. Or you know, you could always test in production... 🤡

To Do

Create functional tests.