An API to share an incident tickets between Remedy and ServiceNow.
swagger: "2.0"
info:
version: "v1.0"
title: ServiceNow - Remedy Incident synchronisation
description: An API to share an incident tickets between Remedy and ServiceNow
schemes:
- https
host: "api.mtn.com"
basePath: "/"
consumes:
- application/json
produces:
- application/json
securityDefinitions:
ApiKeyAuth:
type: "apiKey"
name: "X-API-Key"
in: "header"
OAuth2:
type: oauth2
flow: application
tokenUrl: https://api.mtn.com/v1/oauth/access_token
security:
- ApiKeyAuth: []
- OAuth2: []
paths:
/incident:
post:
tags:
- "Incident ticket"
summary: "Create a new ticket"
description: "Create a new ticket by specifying the 'originIncidentNumber'."
parameters:
- in: "body"
name: "body"
description: "Request body"
required: true
schema:
$ref: "#/definitions/newTicket"
responses:
201:
description: "Incident created"
schema:
$ref: "#/definitions/ticketResponse"
401:
description: "Not authenticated"
404:
description: "Not found"
407:
description: "Proxy system not authenticated"
500:
description: "Internal Server Error"
put:
tags:
- "Incident ticket"
summary: "Modify an existing ticket"
description: "This call is used to update a ticket that already exists by using the 'targetIncidentNumber'."
parameters:
- in: "body"
name: "body"
description: "Request body"
required: true
schema:
$ref: "#/definitions/updateTicket"
responses:
200:
description: "OK"
schema:
$ref: "#/definitions/ticketResponse"
401:
description: "Not authenticated"
404:
description: "Not found"
407:
description: "Proxy system not authenticated"
500:
description: "Internal Server Error"
get:
tags:
- "Track ticket"
summary: "Query ticket details based on msisdn"
description: "Fetch a ticket's details using the msisdn"
parameters:
- in: query
name: customerId
required: true
type: string
description: "MSISDN of the customer"
- in: query
type: string
name: startDate
description: This is the start date against which a search for the specified ticket number will be made e.g 20201101
- in: query
type: string
name: endDate
description: This is the end date against which a search for the specified ticket number will be made e.g 20201130
- in: query
name: targetSystem
required: true
type: string
enum:
- SERVICENOW
- CLM
- REMEDYSA
- in: query
type: number
name: numberOfTickets
description: This is the number of tickets to be fetched from backend system. If not passed then default configured number of tickets will be returned from backend.
responses:
200:
description: "Request successful"
schema:
$ref: "#/definitions/TicketTrackResponse"
401:
description: "Not authenticated"
404:
description: "Not found"
407:
description: "Proxy system not authenticated"
500:
description: "Internal Server Error"
/incident/{ticketId}:
get:
tags:
- "Track ticket"
summary: "Query ticket details"
description: "Fetch a ticket's details using the ticket Id"
parameters:
- in: path
name: ticketId
required: true
type: string
description: "This is the ticket Id received in the response when creating a ticket"
- in: query
type: string
name: startDate
description: This is the start date against which a search for the specified ticket number will be made e.g 20201101
- in: query
type: string
name: endDate
description: This is the end date against which a search for the specified ticket number will be made e.g 20201130
- in: query
name: targetSystem
required: true
type: string
enum:
- SERVICENOW
- CLM
- REMEDYSA
- in: query
type: string
name: customerId
description: MSISDN of the customer
responses:
200:
description: "Request successful"
schema:
$ref: "#/definitions/TicketTrackResponse"
401:
description: "Not authenticated"
404:
description: "Not found"
407:
description: "Proxy system not authenticated"
500:
description: "Internal Server Error"
definitions:
newTicket:
type: "object"
required:
- targetSystem
- originSystem
- transactionId
- callerId
- originIncidentNumber
- shortDescription
properties:
targetSystem:
type: "string"
description: "System receiving the request"
example: "REMEDYSA"
enum:
- "REMEDYSA"
- "SERVICENOW"
- "CLM"
originSystem:
type: "string"
description: "System originating the request"
example: "SERVICENOW"
enum:
- "REMEDYSA"
- "SERVICENOW"
transactionId:
type: "string"
description: "Transaction identifier used by client"
example: "123ABC"
callerId:
type: "string"
description: "User from calling system"
example: "a.gonzalez.bogaz@accenture.com"
originIncidentNumber:
type: "string"
description: "Origin ticket identifier, this is the id of the ticket at the originating system"
example: "INC0011558"
shortDescription:
type: "string"
description: "Brief description about the ticket"
example: "Superman is sick"
detailedDescription:
type: "string"
description: "More detailed description of the ticket"
example: "Superman is sick because he was exposed to Kryptonite"
impact:
type: "string"
description: "Level of impact"
example: "1"
enum:
- "1"
- "2"
- "3"
- "4"
urgency:
type : "string"
description : "Level of urgency"
example : "3"
enum:
- "1"
- "2"
- "3"
- "4"
interface:
type: "string"
description: "interface applicable to requests for RemedySA"
example: "interface"
signalName:
type: "string"
description: "signalName applicable to requests for RemedySA"
example: "signalName"
attachmentFilename:
type: "string"
description: "Name of file being attached"
example: "image1.png"
attachmentData:
type: "string"
format: "base64"
description: "Attachment data encoded in base64"
example: "fdgrdvh22dhv2dhtdt3h35th4"
customerId:
type: "string"
description: "Mobile number of the entity reporting the incident"
entityType:
type: string
description: Categorisation of the entity that has created the ticket. P -> Profile Level S -> Single Service Level I -> Individual Level
enum:
- "P"
- "S"
- "I"
ticketCategoryCode:
type: string
description: Represents code of the Trouble ticket Category created
destinationNumber:
type: string
description: Represents destination number
ticketCategory:
type: string
description: Ticket category
ticketSubCategory:
type: string
description: Ticket level 2 category
subscriberName:
type: string
description: Subscriber Name
contactMedium:
$ref: '#/definitions/ContactMedium'
ContactMedium:
type: object
description: Indicates the contact medium that could be used to contact the party.
properties:
mediumType:
type: string
description: >-
Type of the contact medium, such as: physicalAdress,postalAddress,contactPerson etc.
preferred:
type: boolean
description: 'If true, indicates that is the preferred contact medium'
characteristic:
$ref: '#/definitions/MediumCharacteristic'
description: Any additional characteristic(s) of this contact medium
'@baseType':
type: string
description: 'When sub-classing, this defines the super-class'
'@schemaLocation':
type: string
description: >-
A URI to a JSON-Schema file that defines additional attributes and
relationships
format: uri
'@type':
type: string
description: 'When sub-classing, this defines the sub-class entity name'
MediumCharacteristic:
type: object
description: >-
Describes the contact medium characteristics that could be used to contact a party (an individual or an organization)
properties:
contact:
type: string
description: Person's phone number or email
buildingNumber:
type: string
description: Building number
city:
type: string
description: The city
contactType:
type: string
description: >-
The type of contact, for example: phone number such as mobile, fixed home, fixed office. postal address such as shipping instalation…
addressType:
type: string
description: Type of address such as residential address, office address etc.
placeName:
type: string
description: Name of village or town or place etc.
sectorName:
type: string
description: Name of sector or relevant etc.
cellName:
type: string
description: Name of cell number or town or place etc.
districtName:
type: string
description: Name of village or town or place etc.
street1:
type: string
description: Describes the street
state:
type: string
region:
type: string
description: Region of the complainant
street:
type: string
street2:
type: string
postCode:
type: string
description: Postcode
stateOrProvince:
type: string
description: State or province
country:
type: string
description: The country
emailAddress:
type: string
description: Full email address in standard format
faxNumber:
type: string
description: The fax number of the contact
phoneNumber:
type: string
description: The primary phone number of the contact
alternateNumber:
type: array
items:
type: string
description: List of alternate phone/contact numbers of the customer
example: ["2507865432"]
socialNetworkId:
type: string
description: Identifier as a member of a social network
'@baseType':
type: string
description: 'When sub-classing, this defines the super-class'
'@schemaLocation':
type: string
description: >-
A URI to a JSON-Schema file that defines additional attributes and relationships
format: uri
'@type':
type: string
description: 'When sub-classing, this defines the sub-class entity name'
updateTicket:
type: "object"
required:
- transactionId
- originSystem
- targetSystem
- targetIncidentNumber
properties:
transactionId:
type: "string"
description: "Transaction identifier used by client"
example: "123ABC"
originSystem:
type: "string"
description: "System originating the request"
example: "SERVICENOW,REMEDYSA"
targetSystem:
type: "string"
description: "System receiving the request"
example: "REMEDYSA,SERVICENOW"
targetIncidentNumber:
type: "string"
description: "Incident number at the target system"
example: "INC0011964"
shortDescription:
type: "string"
description: "Brief description about the ticket"
example: "Superman is sick"
detailedDescription:
type: "string"
description: "More detailed description of the ticket"
example: "Superman is sick because he was exposed to Kryptonite"
impact:
type: "string"
description: "Level of impact"
example: "1"
enum:
- "1"
- "2"
- "3"
- "4"
urgency:
type : "string"
description : "Level of urgency"
example : "3"
enum:
- "1"
- "2"
- "3"
- "4"
attachmentFilename:
type: "string"
description: "Name of file being attached"
example: "image1.png"
attachmentData:
type: "string"
format: "base64"
description: "Attachment data encoded in base64"
example: "fdgrdvh22dhv2dhtdt3h35th4"
state:
type: "string"
description: "Only applicable for values 2,3,6,7,8. Value 1 is set when an incident is created. Value 2 can only be set if the ticket 'assignedTo' field was prevously set"
example: "3"
enum:
- "2"
- "3"
- "6"
- "7"
- "8"
assignedTo:
type: "string"
description: "Who the incident is assigned to"
example: "integration.mtn.sa.remedy"
closeCode:
type: "string"
description: "Applicable when setting 'state' to 6. This value is used to indicate the code for resolution."
enum:
- "Not Resolved – Not Reproducible"
- "Not Resolved – Problem Raised"
- "Not Resolved – Resolved by Vendor"
- "Resolved - Workaround Applied"
- "Resolved – Fixed by Caller"
- "Resolved – Fixed Without Action"
- "Resolved – Permanent Fix Applied"
example: "Resolved – Permanent Fix Applied"
closeNotes:
type: "string"
description: "Custom notes for closing ticket."
example: "All done!"
comments:
type: "string"
description: "Comments to incident"
example: "My comments"
workNotes:
type: "string"
description: "Work notes to incident"
example: "My notes"
subcategory:
type: "string"
description: "Incident category"
example: "database"
interface:
type: "string"
description: "interface applicable to requests for RemedySA"
example: "interface"
signalName:
type: "string"
description: "signalName applicable to requests for RemedySA"
example: "signalName"
summary:
type: "string"
description: "summary applicable to requests for RemedySA"
example: "summary"
detailedSummary:
type: "string"
description: "detailedSummary applicable to requests for RemedySA"
example: "detailedSummary"
status:
type: string
description: Status of the ticket
statusUpdateTime:
type: string
format: datetime
commentsUpdateTime:
type: string
format: datetime
description: Time when a new comment is being submitted
statusUpdateStaffCode:
type: string
description: Staff number of the individual submitting the update
commentsUpdateStaffCode:
type: string
description: Comment of the individual submitting the update
ticketResponse:
type: "object"
required:
- targetIncidentNumber
- statusCode
- statusMessage
- originTransactionId
- targetTransactionId
properties:
targetIncidentNumber:
type: string
description: "Target ticket identifier, this is the id of the ticket at the target system"
statusCode:
type: "string"
description: "Status code from target system to indicate transaction status"
statusMessage:
type: "string"
description: "Status response description"
example: "processed"
originTransactionId:
type: "string"
description: "Transaction identifier generated by system originating the request"
example: "MTN123456"
targetTransactionId:
type: "string"
description: "Transaction identifier generated by target"
example: "17af7d89db62885072fa83305b961972"
data:
$ref: '#/definitions/TicketCreateData'
TicketCreateData:
type: object
properties:
referenceNumber:
type: string
description: "Ticket reference number"
estimatedResolutionTime:
type: string
description: "Estimated resolition time for the ticket created"
urgency:
type: string
description: "Urgency / priority of the created ticket"
docketRefNumber:
type: string
incidentReopenCount:
type: number
description: Number of times the ticket has been re-opened
TicketTrackResponse:
type: object
properties:
statusCode:
type: string
example: '0000'
statusMessage:
type: string
example: Successful Request
transactionId:
type: string
description: Client or API generated Id to include for tracing requests
data:
$ref: '#/definitions/TicketTrackRecordList'
TicketTrackRecordList:
type: array
items:
$ref: '#/definitions/TicketTrackRecords'
TicketTrackRecords:
type: object
properties:
ticketLogDate:
type: string
description: Date when the incident was reported
status:
type: string
description: Status of the ticket
example: "CLOSED"
priority:
type: string
description: Priority of the created ticket
ticketIssueType:
type: string
description: This indicates the type of person that created the ticket.
example: "Complaint"
channel:
type: string
description: Channel through which the incident was created
assigneeName:
type: string
description: Name of the person or team asigned to the ticket
complaint:
type: string
description: Description of the incident that was created
workFlowId:
type: string
description: Workflow ID
respondedBy:
type: string
description: Name of the person that responded to the ticket
dateTicketResponded:
type: string
description: Date when the ticket was responded to
rowNum:
type: number
description: Row number for the ticket
transDate:
type: string
description: transaction date for the request
eventRefNo:
type: string
description: Event reference number for the request
notes:
type: string
description: Notes for the ticket
categoryDesc:
type: string
description: Category description for the ticket
msisdn:
type: string
description: mobile number for the request
subsName:
type: string
description: subscriber name
category1:
type: string
description: category tier 1
category2:
type: string
description: category tier 2
category3:
type: string
description: category tier 3
createdBy:
type: string
description: ticket created by
statusFrn:
type: string
description: status in French