ServiceNow Customer Connect

Introduction

The ServiceNow Customer Connect API allows you to manage your IT service management processes from one place. Use the API to log or update tickets for KPN products and services you use.

API specification

Test the API on SwaggerHub

Base URL

https://api-prd.kpn.com/network/kpn/servicenow

Conceptual model

Via this API Tickets in KPN ServiceNow can be created and updated. Updates made by KPN in KPN ServiceNow will be placed in a message-queue and can be retrieved via this API.

Prerequisites

You need to be a KPN business market customer and have a KPN service contract for the products and services bought from KPN.

Definitions

CI

A configuration item (CI) is any service component, infrastructure element, or other item that needs to be managed in order to ensure the successful delivery of services.

Ticket

A ticket is a log file of a reported request with a contracted KPN service or piece of KPN equipment. The ticket describes the situation, reports a contact person and is stored in the ServiceNow system.

Base64

Base64 is an encoding algorithm that allows you to transform any characters into an alphabet that consists of Latin letters, digits, plus and slash.

API workflow

Features and constraints

Features

• Create a new ticket in KPN ServiceNow.
• Comment to an existing ticket.
• Query for updates on the tickets.
• Attachments to tickets are supported.

Constraints

• CI type must be chosen from a predefined list of values.
• Attachments must be Base64 encoded.
• Maximum total size of attachments is 80MB.

Getting started

Make sure you've read What's in it for you for more info on how to register and start testing APIs.

Authentication

The API follows the KPN Store API Authentication Standard to secure the API. It includes the use of OAuth 2.0 client_id and client_secret to receive an access token.

Go to the Authentication tab on top of this page to find out how to:

• Authenticate to an API using cURL.
• Authenticate to an API on Swaggerhub.
• Import Open API Specifications (OAS), also called Swagger files into Postman.

How to...

Create a new ticket

The following endpoint creates a new ticket:

POST /Ticket

Request

You can send JSON content in the request body:

      Request example
      
        Code copied
        
            
      

{
  "ticket_type": "Incident",
  "customer_reference_number": "INC01234567",
  "short_description": "Win11 L schijf: Kan niet worden toegevoegd",
  "description": "Some extended description/nSecond line",
  "service": "Azure Managed Cloud",
  "ci": "GSEM01300",
  "contact": "jan.jansen@customer.com",
  "user": "truus.bakker@customer.com",
  "priority": "1 - Critical",
  "attachments": [
    {
      "name": "test.txt",
      "content": "IQ0KZW5hYmxlIHNlY3JldCBjaXNjbw0KIQ0KIQ0KIQ0KIQ0KIQ0KIQ0KIQ0Kbm8gaXAgc291cmNlLXJvdXRlDQohDQohDQohDQohDQohDQohDQohDQohDQoNCg0KIQ0KaXAgd1ZXVlIDEwMCBvdCiBwZXJtaXQgdWQogdHJhbnNwb3J0IGlucHV0IHRlbG5ldA0KIQ0KZW5k",
      "content_type": "text/plain"
    }
  ]
}

Fields

Response

The 200 response provides you with the kpn_ticket_number and the customer_reference_number of the created ticket. These fields are necessary to update the ticket.

      Response example
      
        Code copied
        
            
      

{
    "kpn_ticket_number": "INC#11252133",
    "customer_reference_number": "INC01234567",
    "note": "Incident INC#11252133 has been created;"
}

Update a ticket

The following endpoint updates a ticket:

PATCH /Ticket

Request

Send JSON content in the request body:

      Example request
      
        Code copied
        
            
      

{
  "action": "Comment",
  "comment": "New comment update",
  "status": "Success",
  "kpn_ticket_number": "INC#34567890",
  "customer_reference_number": "INC01234567",
  "attachments": [
    {
      "name": "test.txt",
      "content": "IQ0KZW5hYmxlIHNlY3JldCBjaXNjbw0KIQ0KIQ0KIQ0KIQ0KIQ0KIQ0KIQ0Kbm8gaXAgc291cmNlLXJvdXRlDQohDQohDQohDQohDQohDQohDQohDQohDQoNCg0KIQ0KaXAgd1ZXVlIDEwMCBvdCiBwZXJtaXQgdWQogdHJhbnNwb3J0IGlucHV0IHRlbG5ldA0KIQ0KZW5k",
      "content_type": "text/plain"
    }
  ]
}

Two actions are supported:

• Comment: The possibility to add comments and/or attachments to an existing ticket.
• Response: Used as response on a retrieved message. Mandatory for a message with action 'New' to return the customer_reference-number to KPN in case the ticket is created by KPN

Fields

Response

The 200 response provides you with the kpn_ticket_number and the customer_reference_number of the updated ticket.

      Example response
      
        Code copied
        
            
      

{
    "kpn_ticket_number": "INC#34567890",
    "customer_reference_number": "INC01234567",
    "note": "Incident INC#34567890 has been updated;"
}

Update Tasks

The following endpoint updates a task:

PATCH /Task

Request

Send JSON content in the request body:

      Example request
      
        Code copied
        
            
      

{
  "action": "Comment",
  "comment": "New comment update",
  "status": "Success",
  "kpn_ticket_number": "INTASK#34567890",
  "customer_reference_number": "TASK01234567",
  "attachments": [
    {
      "name": "test.txt",
      "content": "IQ0KZW5hYmxlIHNlY3JldCBjaXNjbw0KIQ0KIQ0KIQ0KIQ0KIQ0KIQ0KIQ0Kbm8gaXAgc291cmNlLXJvdXRlDQohDQohDQohDQohDQohDQohDQohDQohDQoNCg0KIQ0KaXAgd1ZXVlIDEwMCBvdCiBwZXJtaXQgdWQogdHJhbnNwb3J0IGlucHV0IHRlbG5ldA0KIQ0KZW5k",
      "content_type": "text/plain"
    }
  ]
}

Multiple actions are supported:

• Comment: The possibility to add comments and/or attachments to an existing task.
• Worknote: The possibility to add a worknote and/or attachments to an existing task
• In Progress: To inform KPN the task is In progress
• On Hold: To inform KPN the task is put in an On Hold state, th comment field will contain the reason why the task is put in this state
• Closed Complete: The task is closed successfull
• Closed Incomplete: The task is closed unsuccessfull
• Closed Skipped: The task is skipped
• Response: Used as response on a retrieved message. Mandatory for a message with action 'New' to return the customer_reference-number to KPN when the task is created by KPN

Fields

Response

The 200 response provides you with the kpn_ticket_number and the customer_reference_number of the updated ticket.

      Example response
      
        Code copied
        
            
      

{
    "kpn_ticket_number": "INTASK#34567890",
    "customer_reference_number": "TASK01234567",
    "note": "Task INTASK#34567890 has been updated;"
}

Retrieve ticket updates

This endpoint returns not yet retrieved ticket updates for all the tickets of the customer managed via the api. This should be checked on a regular base to get all the updates for active tickets.

Note: Advice is to use this operation maximum once per 5 minutes.

GET /TicketUpdates

Request

You don't need to provide any parameters.

Response

The 200 response will return an array with all active updates on the tickets. The updates will be removed from the queue after retrieval, all updates can be retrieved once. If there are no active updates an empty array will be returned.

      Response example
      
        Code copied
        
            
      

[
  {
    "message_datetime_utc": "2024-09-11T13:16:50.2099834Z",
    "ticket_type": "Incident",
    "transaction_id": "de082a10-d858-4f8b-9648-9b6c8b2fb517",
    "action": "Attachment",
    "kpn_ticket_number": "INC#11252428",
    "customer_reference_number": "INC01234567",
    "ticket_attributes": {
      "name": "Test Bijlage 1.txt",
      "size": "0.004",
      "link": "https://api-prd.kpn.com/network/kpn/servicenow/GetAttachment/abb6168e3ba81e10333b3f3a85e45a42",
      "file_action": "Add"
    }
  }
]

Note: The ticket update response can contain updates for multiple tickets. Each message can contain different information depending on the issue type and the status of the ticket. A complete overview of the possible ticket updates is available in a separate pdf document.

If a message is successful retrieved & processed expected is that via the PATCH /Ticket uperation a successful response is send using the transaction_id.

Retrieve attachements

This endpoint returns the attachments by calling the link provided in the TicketUpdate.

GET /GetAttachment

Request

You don't need to provide any parameters.

Response

The 200 response will return thne name, content_type and base64 encoded content of the attachment.

      Response example
      
        Code copied
        
            
      

{
    "name": "Test Bijlage 1.txt",
    "content_type": "text/plain",
    "content": "VGVzdA=="
}

Retrieve active tickets

This endpoint returns all active tickets that were issued by you.

GET /ListOpenTickets

Request

You don't need to provide any parameters.

Response

The 200 response will return an array with all active tickets.

      Response example
      
        Code copied
        
            
      


{
    "result": [
        {
            "customer_reference_number": "INC01234567",
            "short_description": "test1",
            "state": "On Hold",
            "kpn_ticket_number": "INC#11203614",
            "ticket_type": "Incident",
            "link": "https://api-prd.kpn.com/network/kpn/servicenow/Ticket?kpn_ticket_number=INC%2311203614"
        },
        {
            "customer_reference_number": "INC01234568",
            "short_description": "test2",
            "state": "New",
            "kpn_ticket_number": "INC#11203618",
            "ticket_type": "Incident",
            "link": "https://api-prd.kpn.com/network/kpn/servicenow/Ticket?kpn_ticket_number=INC%2311203618"
        },
        {
            "customer_reference_number": "INC01234569",
            "short_description": "test3",
            "state": "New",
            "kpn_ticket_number": "INC#11203619",
            "ticket_type": "Request for Information",
            "link": "https://api-prd.kpn.com/network/kpn/servicenow/Ticket?kpn_ticket_number=INC%2311203619"
        }
    ]
}

Retrieve single ticket

This endpoint returns all data of a single ticket:

GET /Ticket?kpn_ticket_number=INC%2311252428

Request

Send the url encode kpn_ticket_number as the query parameter.

Response

The 200 response returns all details of the ticket, including priority, impact, urgency, on_hold_reason and an array with all the comments.

      Response example
      
        Code copied
        
            
      

{
    "result": [
        {
            "category": "Incident",
            "ci": "2-3156425",
            "company": "Customer B.V.",
            "contact": "KPN",
            "description": "test",
            "impact": "1 - High",
            "on_hold_reason": "Awaiting User",
            "priority": "3 - Moderate",
            "customer_reference_number": "INC01234567",
            "resolution_code": null,
            "resolution_notes": "",
            "service": "Managed Cloudservices - KIS Uplink",
            "short_description": "test",
            "sla_due": "14-Aug-2024 12:18:32",
            "state": "On Hold",
            "kpn_ticket_number": "INC#11252428",
            "urgency": "3 - Low",
            "user": "jan.jansen@customer.nl",
            "comments": [
                {
                    "comment": "Looks fine. SNOW can be closed .Thank you.",
                    "date_time": "30-Aug-2024 09:05:36",
                    "user": "via integration"
                },
                {
                    "comment": "As you requested i restored the link for you please check details and let me know if any issue.",
                    "date_time": "30-Aug-2024 07:05:00",
                    "user": "KPN"
                }
            ]
        }
    ]
}

Error responses

In case of an error the API will return an error response:

• statusCode 500: Something went wrong technical: the system is temporarely not able to process the request: Please retry
• statusCode 400: Something is wrong with the message, see the error code and details for the error

      400 Response example
      
        Code copied
        
            
      

{
    "error": {
        "code": "1000",
        "message": "Received data not complete: Value (1 - Zeer hoog) for field priority is not correct. "
    }
}

Possible Error codes