Tech Spotlight: Best-Practices for IT Service Management (ITSM) Application Integrations

Companies like Uber, Grubhub, Airbnb, and others have disrupted their industries, transformed customer experiences, and achieved massive valuations over a very short time—using teams that are a fraction of the size of their well-established competitors. You might be wondering, “Good for them, but how did they do it with limited resources? How can I apply their strategy to my own company?”

The answer is simple. They did not code their entire applications from scratch; they tapped into existing data resources to create new and innovative solutions using an Application Program Interface (API). But before you jump right into development mode, you need to understand that API integrations often become a tug of war between technical limitations and “pie-in-the-sky” functionality that non-technical stakeholders would like to see in their business toolkits.

The rapid fragmentation of the software market is accelerating the demand for seamless connectivity between web-based applications. With improved end-user experiences (UX) in mobile banking, efficiencies gained through Amazon’s 1-click purchasing, and other advances on the consumer side, business clients are raising their expectations as well. They want the ability to move data bi-directionally from one platform to another in real-time, through an engaging user experience.

However, implementing API integrations into your company’s business-critical applications on an ad-hoc basis can end up wasting your organization’s valuable resources. Without a well-thought-out plan, your developers may decide (on their own) to pursue functionality that is not feasible or may not be relevant to your business model at any given time. Consequently, it is extremely important to have an API integration strategy that is proactive, as well as reactive. Knowing what needs to be done before, during, and after you integrate third-party applications with ChangeGear is essential to the success of your integration project.

NOTE: From this point forward, we are assuming you (the reader) have a basic understanding of software development, Web services, and the ChangeGear user interface. The next few sections provide an introduction to the RESTful API, which facilitates a connection between two web-based applications. After that, things get a bit more technical as we dive into endpoints, authentication, URL syntax, parameters, and methods. If you are not comfortable (or not interested) in learning about these technical details, we recommend you skip Steps 1 and 2 and continue reading at Step 3—Perform System Integration Testing.

Step 1 – Conduct Pre-Integration Research

An Application Program Interface (API) integration is a connection between two disparate applications that allows data to flow back and forth seamlessly and without manual intervention. An API defines the types of calls (i.e., interactions) that a program can make, how it can make them, the data formats it can use, the conventions it must follow, and much more. API integrations allow businesses to run processes that keep data in sync, enhance productivity, drive revenue, and execute many other tasks ranging from general to specialized.

The REST API provides access to ChangeGear services, which allows you (via your own program) to interact with entities using simple Hypertext Transfer Protocol (HTTP) requests. The REST API opens the possibility to programmatically access and modify functionality using scripts, custom commands, and third-party services. “REST,” also known as “RESTful,” is one of the most popular types of API. While Representational State Transfer (REST) APIs were designed to be used over almost any protocol, they utilize HTTP or HTTPS to communicate between web-based applications. For optimal performance, we strongly recommend using SSL to secure the communications to and from your ChangeGear server.

The CGWebAPI service is used to create and update certain entities (e.g., Incident, Problem, and Change) and trigger workflow actions in ChangeGear. The CGWebAPI Web service also allows you to create new attachments as part of the Create and Update operations. This simplified API was created to ease the most common integration scenarios, such as create, update, and trigger a workflow action from a third-party system. To ensure a successful integration, you should complete the following pre-integration work:

• Define user stories. User stories are centered on the result and the benefit of the task you are describing, whereas use cases (explained below) can be more granular and describe how your system will behave. A user story is a note that captures what a user does or needs to do as part of their work. For example, a user might say something like, “I don’t have enough time to switch between web applications. Is there any way you can streamline our process for creating new service tickets?”
• Identify possible use cases. A use case is a methodology that identifies, clarifies, and organizes system requirements. A use case is made up of a set of possible sequences of interactions between systems and users in a particular environment that are related to a particular goal. The user story described above, for example, might be expanded into a use case as follows: “The support team will have the ability to open new service tickets via Microsoft Teams. ChangeGear will automatically create a new service ticket, based on information that a technician enters in Teams Chat.”

Step 2 – Build Your Application Integration

Once you have completed the pre-integration research described above, it is time to start building your application integration. Using the ChangeGear REST API requires basic familiarity with software development, web services, and the ChangeGear user interface.

Resources are the Building Blocks of Web-Based Applications

Resources are the fundamental building blocks of web-based applications. A resource is anything that is available via the Internet, ranging from a document or video clip to a business process or device. From an end-user’s point of view, a resource is anything that the user can interact with while moving toward some final goal. For example, a company’s Service Desk becomes a web resource simply by making the information associated with it (i.e., knowledge base articles) available and accessible on the Web. In this example, an end-user’s goal might be to find a quick and easy solution to a technical problem they are experiencing.

Uniform Resource Identifiers (URI) vs Uniform Resource Locators (URL)

In order to use a web resource, you need to be able to identify it on the network (Internet) and have some way to manipulate it. The Web provides something called a Uniform Resource Identifier (URI), which is used to uniquely identify a web resource and make it addressable. Together, these two characteristics make a URI capable of being manipulated using application conventions such as HTTP and HTTPS—the data transfer protocols used on the World Wide Web (www).

Resources define the items or entities in ChangeGear that are affected by an HTTP or HTTPS (secure) request. ChangeGear resources are exposed through the REST API using Uniform Resource Identifiers (URI), which specify the logical locations of resources on the server. The client needs to know the URI in order to access the correct resource. There is often confusion between a Uniform Resource Identifier (URI) and a Uniform Resource Locator (URL). A URI defines the location of a resource, but it does not necessarily need to specify the protocol used to access that resource. A URL is a type of URI that specifies where a resource exists (i.e., location) and the mechanism for retrieving it (i.e., protocol). Technically, the REST API uses URLs, since you need to specify either the HTTP or HTTPS protocol when accessing a resource.

Here are just a few key points that you should consider before building your application integration:

• Select the appropriate integration endpoints: When a REST API interacts with ChangeGear, the touchpoints of this communication are called “endpoints.” Endpoints specify where resources can be accessed by the API and play a key role in guaranteeing the correct functionality of the software that interacts with it. The ChangeGear REST API consists of multiple smaller APIs that expose different features of the program. These features are made available through endpoints, which are URLs that accept requests. For example, ChangeGear’s Login API contains two separate endpoints: one for creating a user session and one for ending a session. Once logged in, your custom application can use the “Create an Item” endpoint to automatically generate a new service ticket.
• Use a secure authentication method: The CGWebAPI Web service can be used with both integrated and ChangeGear authentication. For integrated authentication, the user identity is that of the logged-in Windows user. No additional configuration needs to be made in order to use the Web service with integrated authentication. To use ChangeGear authentication, the username and password needs to be sent via the SOAP headers. The SOAP header “AuthInfo” has the following properties: username and password. These values are sent over to the Web service, which then uses these credentials to login the user. The information sent via the headers is not encrypted, so we strongly recommend that SSL be used when accessing this Web service to prevent attacks such as eavesdropping and man-in-the-middle.
• Format the URL correctly: Consider the following example when constructing your URL:

https://changegear-server/CGRestAPI/api/entity/IncidentRequest/4
The base URL (e.g., https://changegear-server/CGRestAPI/api) defines where the REST API is located. An entity specifier (e.g., Entity) is required when using the GET or DELETE methods. The type (e.g., IncidentRequest) of entity or resource that is being accessed needs to be designated next. Finally, the unique identifier (e.g., 4) of the entity or resource being accessed is designated at the end of the URL.

• Pass parameters and filters in the API request: Some REST API calls require you to specify parameters as part of the URL. Parameters are additional values appended to the URL that further identify the resource being requested. In the example URL shown above, IncidentTicket and 4 are parameters that designate the type and the unique identifier of the entity being retrieved. Other parameters allow you to retrieve more detailed information about a resource, pass data values, and even filter the contents of the server’s response. The type of parameters or filters that are passed are crucial in determining the volume of data that gets pulled. Keep in mind that lower data volume means better performance.

• Use methods to define the action to perform on the resource: The REST API supports four methods: GET to retrieve information about a specific resource, POST to create a new resource, PUT to update an existing resource, and DELETE to remove a resource.

Remember that the “key points” listed above represent just a few of the steps needed to successfully complete your REST API integration project. More detailed information regarding REST API Integrations is available in the ChangeGear Desktop Client Guide.

Step 3 – Perform System Integration Testing

Once you have completed building your application integration, you are halfway to the finish line. We say only “halfway” because there are still so many unanswered questions. In any software development project, things get very interesting when we connect all the moving parts together and watch what happens.

A software deployment is like turning the key (or pressing the button) to start your car. Just because the engine runs, it does not guarantee that your car will drive properly. You might be sitting on a flat tire, the timing belt might be ready to snap, the transmission might be leaking fluid, or a myriad of other potential issues may be lurking under the hood. You may be sitting in the driver seat wondering, “Are the gears properly meshing (functionality)? Can the parts survive normal torque (reliability)? How fast does the transmission shift in response to the engine’s revolutions per minute (performance)? Are there any loose parts that may cause the entire system to overheat (security)? These are some very important questions that need to be answered before deploying your integration project to a live/production environment.

Application Programming Interface (API) testing is a type of software testing that performs verification directly at the API level. It is part of System Integration Testing (SIT), which determines whether the API meets your expectations for functionality, reliability, performance, and security. Effective testing requires you to:

• Have a clear understanding of the requirements of the REST API.
• Specify the API output status that you want to verify.
• Focus on testing one API per test case.
• Organize API endpoints into categories to help you manage them better.
• Choose a good automation tool that supports testing REST API services.
• Leverage automation as much as possible—and as early as possible.
• Choose a suitable verification method for the REST API.
• Create positive test cases to verify that the REST API receives input and returns the expected output. Negative test cases should be created and used to verify that the API returns an appropriate response when the expected output does not exist.
• Develop a comprehensive test plan and follow it!

Step 4 – Implement a Long-Term Strategy for Scalability

At one time or another, we have all been frustrated when a web-based application crashed and the only clue you received was a very general “500 Internal Server Error.” This error means something went wrong, but the server could not provide you with any specific details. The key to the long-term scalability of your application integration is to make testing part of a continuous feedback cycle. If an API component fails to function properly within its larger system, you should have a monitoring tool in place to notify you of the problem as soon as it happens. That way, when an unannounced update to a third-party application’s endpoint “breaks” your system, you should have enough information to address the problem.