Ekran System API Bridge

1. What is the API Bridge?

The Ekran System Ticketing System Integration feature allows you to require users to provide ticket numbers to log in to Client computers. For further details, see Integration with Ticketing Systems.

The design had to resolve the following issue: The general scheme shown has one major design flaw, in that it is difficult to maintain many different ticketing systems as they all have different APIs, and each time a new ticketing system is added, a new adapter must be written to work with each specific API.

This requires the maintenance of different ticketing systems, since all the code that works with these systems is located inside the product. This is far from optimal, as ticketing systems may sometimes change their interface, move to a different type of API, and some are just custom-made and don't provide sufficient information to implement them. Also, adding a new ticketing system requires shipping a new version of the product.

The solution that we came up with is called the API Bridge - which has been developed to resolve all the issues outlined above.

The main idea of this system is that we specify the interface that we require, and provide a very simple version of the service that will implement the required interface. We provide the source code of this service, and the main point is that anyone can change this service by adding any integration that is required by the target ticketing system, no matter whether it's the custom-written ticketing system or any well-known product such as SysAid or ServiceNow. There is also no need to ship a new version of Ekran System to add support for the new ticketing system - you just change the API Bridge in a way that matches the new requirements. Furthermore, we no longer depend on a specific language or code - as long as the required interface is implemented, you can run your own API Bridge.

The API Bridge service is a service that you run as a third-party REST service.

The API Bridge should implement the specific REST interface. As long as this requirement holds, you can change your version of the API Bridge in any way you want, to support any ticketing systems that you have available.

2. The REST Interface

This is the interface that is required by the system:

CODE

openapi: 3.0.0
info:
  version: "0"
  title: "EkranSystem Ticketing System Integration API Bridge"
paths:
  /connect:
    post:
      summary: Request sessionID.
      tags:
        - bridge
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                connectionString:
                  type: string
      responses:
        '200':
          description: A JSON object, including ticket ID and status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  sessionId:
                    type:   string
        '422':
          description: Unprocessable Entity (wrong connection string).
        default:
          description: Unexpected error.
         
  /ticket-status:
    get:
      summary: Get the ticket status.
      description: Used to validate that ticket exists and not closed.
      tags:
        - bridge
      parameters:
        - name: sessionId
          in: query
          required: true
          schema:
            type: string
        - name: ticketId
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A JSON object, including ticket ID and status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ticketId:
                    type: string
                  status:
                    type: number
        '401':
          description: Unauthorized (Invalid session).
        '404':
          description: A ticket with the specified ID was not found.
        default:
          description: Unexpected error.
  /add-ticket-comment:
    post:
      summary: Add a comment to the ticket.
      description: Used to add a comment with a link to the specific place in the monitoring results on the Management tool site.
      tags:
        - bridge
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sessionId:
                  type: string
                ticketId:
                  type: string
                ticketComment:
                  type: string
              required:
                - sessionId
                - ticketId
                - ticketComment
      responses:
        '201':
          description: Ok.
        '401':
          description: Unauthorized (Invalid session).
        '404':
          description: A ticket with the specified ID was not found.
        default:
          description: Unexpected error.

This code basically describes the REST API interface that should be supported by the API Bridge.

For example, in the "/connect" section:

/connect means that if your REST service has the address http://127.0.0.1/, then there should be the path http://127.0.0.1/connect which we can send POST requests to.

This section also contains:

requestBody:

required: false

This means that this POST request may have an optional requestBody parameter.

The current communication flow between the API Bridge and Ekran Service is as follows:

This interface is in the OpenAPI format. Further details about this format are available here.

3. How to Use the API Bridge

You can implement the service on your own, using any language that suits your infrastructure.

There is even a free service called Swagger (https://swagger.io/) which, having the OpenAPI specification, will generate the simple service for you, using the language of your choice.

We provide an example of the service that is written in ASP.NET Core.

You can either compile it from the source code, if suitable, or you can run a prebuilt executable that we provide.

NOTE: This sample service is not a production-ready solution, It is designed for test purposes only, and may be used as a hint or as a base skeleton that will assist in implementation of the ticketing system integration.

If you choose to use an executable to check how it works, we also provide a simple json file that has a basic set of ticket numbers that will help you to do a quick check of the bridge system. While testing, you should put it in the wwwroot folder.

You can find this json file in the archive, along with the sample code.

To use the sample service, do the following:

1. Unpack the APIBridgePackage archive.

2. Move the json file to the wwwroot folder.

3. Edit the json file using any text editor (e.g. Notepad):

• In the Sessions section, define the user credentials of your ticketing system.

• In the Tickets session, define the name of the ticket that the user must enter while logging in to the Client computer.

NOTE: By default, there are three types of ticket statuses: 0 – means that a ticket is not found; 1 – means that a ticket is active; 2 – means that a ticket is closed.

4. In the APIBridgeSampleBinaries folder, run IO.Swagger.

5. In the console window that opens, specify the port to be used for Ekran System and the ticketing system connection, and press Enter.

NOTE: This port must be specified in the Management Tool during the configuration of the ticketing system integration.

6. The ticketing system URL is displayed in the console window.

4. How to Set Up the API Bridge in the Management Tool

To see how to set up the credentials in the Management Tool, please refer to Defining Ticketing System Integration Settings.

Table of Contents

1. What is the API Bridge?

2. The REST Interface

3. How to Use the API Bridge

4. How to Set Up the API Bridge in the Management Tool