This page will detail the common use cases of the trouble ticket API using python3. If another language is being used, there is an option to export code examples from the API specification documentation.
Contents:
Create a comment and attach a file.
Get details of a trouble ticket
Getting Access
Before using the trouble ticket API, you need to have a valid access token. To see how to generate this, go to the Auth API documentation (available here).
Creating a Trouble Ticket
The requirements to create a trouble ticket are:
- Provide a valid access token – this is retrieved from the Auth API.
- Provide all required fields in request (Details on required fields found in the API specification).
-
relatedParty.RSP.email must have a domain name that your access token has access to. Domain names are mapped to RSP codes in Enables IAM platform.
- As an example: ESL is mapped to Enable Services Limited.
Python code example:
import requests
import json
url = "https://staging.apis.enable.net.nz/troubleTicket/v1/troubleTicket"
payload = json.dumps({
"description": "This is a basic example.",
"externalId": "12345",
"urgency": "Standard",
"comment": {
"author": {
"email": "{insert an email address}",
"name": "Bob"
},
"text": "Testing the ETT API!"
},
"relatedEntity": {
"service": {
"serviceID": "12345",
"ONTSerialNumber": "12345",
"SVID": "10",
"CVID": "22",
"RGWMACAddress": "12-12-12-12-12-12",
"handoverID": "123456",
"circuitActivationDate": "2020-08-20",
"servicesImpacted": "Other",
"otherServicesImpacted": "OTS",
"address": "Lvl 3, 93 Cambridge Terrace, Christchurch",
"medicalDependency": True,
"medicalDependencyDetails": "The end user has a medical pendant."
},
"ONT": {
"powerLight": "Off",
"PONLight": "On",
"LOSLight": "Flashing",
"LAN1Light": "On",
"LANPortConnected": "1"
},
"troubleShootingQuestions": {
"hasThisServiceEverWorked": True,
"hasALineTestBeenCompleted": True,
"hasAnIsolationTestBeenCompleted": False,
"reasonForNotCompletingIsolationTest": "The ONT is offline and we cannot complete the test.",
"detailsOfTroubleshootingActionsTaken": "The ONT is offline and we cannot complete the test.",
"additionalInformation": "The end user may have hit the fibre cable when gardening but didn't pierce it."
}
},
"relatedParty": {
"RSP": {
"name": "Bob",
"phoneNumber": "+6425555555",
"email": "{Email address under your domain}",
},
"endUser": {
"name": "Mary",
"phoneNumber": "+64225555555",
"email": "{insert an email address}",
"type": "Business",
"businessName": "Enable Networks",
"businessSiteHours": "9am - 5pm"
}
}
})
headers = {
'X-Transaction-ID': '{Your unique UUID}',
'Authorization': 'Bearer {Insert your access token}',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
Create a trouble ticket and attach a file.
To attach a file, create two API requests - as below:
- Request to the create attachment endpoint
- Request to the create comment endpoint. Using an ID returned by attachment endpoint; to connect the attachment to the comment.
To start with, you will need to upload your file. The requirements before you can do this are:
- Provide a valid access token – retrieved from the Auth API.
- Provide all required fields in request body (details on required fields found in the API specification).
- Filetype must be an approved file type:
- .png
- .jpg, .jpeg
- .gif
- .webp
- .doc, .docx
- .odt
- .xlsx, .xls
- .msg
Python code example:
import requests
url = "https://staging.apis.enable.net.nz/troubleTicket/v1/troubleTicket/attachment"
payload={'filename': '{name of your file}'}
files=[
('file',('{name of your file}',open('{file path}','rb'),'{file mime type (i.e “image/png”')))
]
headers = {
'X-Transaction-ID': '{Your unique UUID}',
'Authorization': 'Bearer {Insert your access token}'
}
response = requests.request("POST", url, headers=headers, data=payload, files=files)
print(response.text)
Once you have made a successful request, you will receive a response that looks like this:
{
'id': '1234',
'attachment_token': 'gbdafgfdasgdfsag'
}
You will use the attachment token in the next request – to append the attachment to the comment.
Next, create the ticket with the attachment specified in the request
The requirements to create a trouble ticket with the attachment are:
- Provide a valid access token.
- Provide all required fields in request (details on required fields found in API specification).
- relatedParty.RSP.email must have a domain name that your access token has access to. Domain names are mapped to RSP codes in Enable’s IAM platform.
- Provide the “attachment_token” value from the previous request.
Python code example:
import requests
import json
url = "https://staging.apis.enable.net.nz/troubleTicket/v1/troubleTicket"
payload = json.dumps({
"description": "The ONT is not providing a service yet it is online.",
"externalId": "12345",
"urgency": "Standard",
"comment": {
"author": {
"email": "{insert an email address}",
"name": "Bob"
},
"text": "Last I checked the ONT was online?",
"attachment_tokens": ["{Insert your attachment_token}"]
},
"relatedEntity": {
"service": {
"serviceID": "12345",
"ONTSerialNumber": "12345",
"SVID": "98",
"CVID": "22",
"RGWMACAddress": "12-12-12-12-12-12"
"handoverID": "123456",
"circuitActivationDate": "2020-08-20",
"servicesImpacted": "Other",
"otherServicesImpacted": "OTS",
"address": "Lvl 3, 93 Cambridge Terrace, Christchurch",
"medicalDependency": True,
"medicalDependencyDetails": "The end user has a medical pendant."
},
"ONT": {
"powerLight": "Off",
"PONLight": "On",
"LOSLight": "Flashing",
"LAN1Light": "On",
"LANPortConnected": "1"
},
"troubleShootingQuestions": {
"hasThisServiceEverWorked": True,
"hasALineTestBeenCompleted": True,
"hasAnIsolationTestBeenCompleted": False,
"reasonForNotCompletingIsolationTest": "The ONT is offline and we cannot complete the test.",
"detailsOfTroubleshootingActionsTaken": "The ONT is offline and we cannot complete the test.",
"additionalInformation": "The end user may have hit the fibre cable when gardening but didn't pierce it."
}
},
"relatedParty": {
"RSP": {
"name": "Bob",
"phoneNumber": "+64225555555",
"email": "{Email address under your domain}",
},
"endUser": {
"name": "Mary",
"phoneNumber": "+64225555555",
"email": "{insert an email address}",
"type": "Business",
"businessName": "Enable Networks",
"businessSiteHours": "9am - 5pm"
}
}
})
headers = {
'X-Transaction-ID': '{Insert your uuid}',
'Authorization': 'Bearer {Insert your access token}',
'Content-Type': 'application/json'
}
response = requests.request(
method="POST",
url=url,
headers=headers, data=payload)
print(response.text)
Create a comment and attach a file.
To create a comment on an existing ticket and attach a file, create two API requests. (Note: if wanting to create a comment without a file, ignore step one. Don’t include “attachment_tokens” in create comment request.)
First, you need to upload your file, the requirements before you can do this are:
- Provide a valid access token.
- Provide all required fields in request (details on required fields found in API specification).
Python code example:
import requests
url = https://staging.apis.enable.net.nz/troubleTicket/v1/troubleTicket/attachment
payload={'filename': '{name of your file}'}
files=[
('file',('{name of your file}',open('{file path}','rb'),'{file mime type (i.e “image/png”')))
]
headers = {
'X-Transaction-ID': '{Your unique uuid}',
'Authorization': 'Bearer {Insert your access token}'
}
response = requests.request("POST", url, headers=headers, data=payload, files=files)
print(response.text)
Once you have made a successful request, you will receive a response that looks like this:
{
'id': '1234',
'attachment_token': 'gbdafgfdasgdfsag'
}
You will use the attachment token in the next request.
Next, to create a comment you must meet the following requirements:
- Provide a valid access token.
- Provide all required fields in request (details on required fields found in API specification).
- Be the owner of the ticket (tickets are owned by organizations).
- Have already created a ticket and know its ID.
Python code example:
import requests
import json
url = "https://staging.apis.enable.net.nz/troubleTicket/v1/troubleTicket/{insert your ticket ID}/comment"
payload = json.dumps({
"author": {
"email": "{Insert an email address}",
"name": "Bob"
},
"text": "This is a comment!",
"attachment_tokens": [
"{Insert attachment_token}"
]
})
headers = {
'X-Transaction-ID': '{Insert your uuid}',
'Authorization': 'Bearer {Insert your access token}',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
Search for a trouble ticket
The trouble ticket search endpoint allows you to search for your trouble ticket with a small set of search parameters. To search for tickets you must meet the following requirements:
- Provide a valid access token.
Python code example:
import requests
url = "https://staging.apis.enable.net.nz/troubleTicket/v1/troubleTicket?externalId={Insert your externalId}"
payload={}
headers = {
'X-Transaction-ID': '{Insert your uuid}',
'Authorization': 'Bearer {Insert your access token}'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
Get details of a trouble ticket
If you know the ID of a trouble ticket you can search for its details, but to do this you must meet the following requirements:
- Provide a valid access token.
- Own the ticket you are requesting details for.
Python code example:
import requests
url = "https://staging.apis.enable.net.nz/troubleTicket/v1/troubleTicket/{Insert your ticket id}"
payload={}
headers = {
'X-Transaction-ID': '{Insert your UUID}',
'Authorization': 'Bearer {Insert your access token}'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
Authorization & Permissions
This section will cover off how to create and manage trouble tickets with sub brands (organizations with multiple RSP codes).
Some RSPs have multiple RSP codes to distinguish different retailers under the same organization. The trouble ticket API allows the client to specify which RSP code to assign to the ticket, which means only clients with access to that RSP code can access the ticket.
To get access to an RSP code, your user that generates the access token in the Auth API must be part of that RSP codes Okta groups. For example if you want “UNA” rsp code, you must be in the “ENA_UNA_API_RO_Prod” group.
In Enables ticketing platform, there is an “Organization” for each RSP code which adds an authorization layer to tickets. These organizations are configured by Enable and contain the RSP code and email domain names, if you want to check what domain names are configured or you think there is a mistake, please contact Enable via API support.
Below is information on how the authorization/permissions function in each API endpoint.
Create a trouble ticket.
When you create a trouble ticket, you must pass a rsp code in a field called “rspCode” that you have access to in your access token. This specifies what “Organization” the ticket belongs to in Enables ticketing platform when its created.
You must also set the “relatedParty.RSP.email” field in the request to an email address which has an email domain that is assigned to the organization. This is to prevent trouble tickets being created under email addresses that do not belong to the client.
Search for a trouble ticket
Searching for a trouble ticket will use the RSP codes your access token has access to and return an array of tickets that are assigned to the organizations with the RSP codes. This means if your access token has multiple RSP codes, multiple organizations will be used to search for the tickets.
Get a trouble ticket by ID
Like searching for a trouble ticket, getting a trouble ticket by id will use the RSP codes your access token has access to and return the ticket if it is assigned to the organizations with the RSP codes. This means your access token has multiple RSP codes, you will have access to more trouble tickets.
Create a comment.
You can only comment on a trouble ticket if your access token has the RSP code that is associated with the ticket.