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
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
{
"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:
|
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"
}
]
}
]
}
