API menu

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

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

KPN ServiceNow 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
{ "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": "P1 - Critical", "attachments": [ { "name": "test.txt", "content": "IQ0KZW5hYmxlIHNlY3JldCBjaXNjbw0KIQ0KIQ0KIQ0KIQ0KIQ0KIQ0KIQ0Kbm8gaXAgc291cmNlLXJvdXRlDQohDQohDQohDQohDQohDQohDQohDQohDQoNCg0KIQ0KaXAgd1ZXVlIDEwMCBvdCiBwZXJtaXQgdWQogdHJhbnNwb3J0IGlucHV0IHRlbG5ldA0KIQ0KZW5k", "content_type": "text/plain" } ] }

Fields

Field Description Manditory/Optional
customer_reference_number unique reference-number from the source-system M
ticket_type Two possible values: 'incident' for incidents, 'request_for_information' M
short_description Short description of the incident M
description Details of the incident M
service service for which the incident is reported as known in KPN M
ci ci for which the incident is reported as known in KPN O
contact id of the contact (Reported by / Requested by) O
user Id of the user (Affected user / Requested for) O
priority P1 .. .. P5. This value will be mapped to the description of the ticket to indicate the required priority O
attachments Array containing the attachment information O
- name name of the attachment M for attachment
- content Attachment Payload. Base-64 encoded string. Maximum Message-size (including base64 encoded attachments): 80MB M for attachment
- content_type content_type of the attachment O for attachment

Response The 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
{ "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
{ "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

Field Description Mandatory/Optional
action action on the tiket, possible values: 'Comment', 'Response' M
customer_reference_number unique reference-number from the source-system M
kpn_ticket_number The number of the ticket in KPN ServiceNow , as returned by the POST message M
transaction_id transaction_id of the received ticket_update M for action = Response
status Status of the response, possible values:
  • 'success', if the received message is processes succcesfull,
  • 'failure', if there was an error, reason of error in comment field
M for action = Response
comment Comment to add to the ticket M for action = Comment
attachments Array containing the attachment information O
- name name of the attachment M for attachment
- content Attachment Payload. Base-64 encoded string. Maximum Message-size (including base64 encoded attachments): 80MB M for attachment
- content_type content_type of the attachment O for attachment

Response

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

Example response
{ "kpn_ticket_number": "INC#34567890", "customer_reference_number": "INC01234567", "note": "Incident INC#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 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
[ { "message_datetime_utc": "2024-09-11T13:16:50.2099834Z", "issue_type": "incident", "transaction_id": "de082a10-d858-4f8b-9648-9b6c8b2fb517", "action": "attachment", "kpn_ticket_number": "INC#11252428", "customer_reference_number": "INC01234567", "ticket_attributes": { "filename": "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 response will return thne name, content_type and base64 encoded content of the attachment.

Response example
{ "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 /Ticket

Request

You don't need to provide any parameters.

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

Response example
{ "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": "Incident", "link": "https://api-prd.kpn.com/network/kpn/servicenow/Ticket?kpn_ticket_number=INC%2311203619" } ] }

Retrieve single ticket (October 2024)

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 response returns all details of the ticket, including priority, impact, urgency, on_hold_reason and an array with all the comments.

Response example
{ "result": [ { "category": "Incident", "ci": "", "company": "Customer B.V.", "contact": "Unknown User", "description": "test", "impact": "1 - High", "on_hold_reason": "Awaiting User", "priority": "3 - Moderate", "customer_reference_number": "INC01234567", "resolution_code": null, "resolution_notes": "", "service": "Not contracted", "short_description": "test", "sla_due": "14-Aug-2024 12:18:32", "state": "On Hold", "kpn_ticket_number": "INC#11252428", "urgency": "3 - Low", "user": "Unknown User", "comments": [ { "comment": "Looks fine. SNOW can be closed .Thank you.", "date_time": "30-Aug-2024 09:05:36", "user": "KPNNL\\userx" }, { "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": "KPNNL\\usery" } ] } ] }