To login with your TM Forum account please click on the Login button below

Don't have an account? You can register by clicking here:

Operation on Entities

Uniform API Operation

Description

Query Entities

GET Resource

GET must be used to retrieve a representation of a resource.

Create Entity

POST Resource

POST must be used to create a new resource

Partial Update of an Entity

PATCH Resource

PATCH must be used to partially update a resource

Complete Update of an Entity

PUT Resource

PUT must be used to completely update a resource identified by its resource URI

Remove an Entity

DELETE Resource

DELETE must be used to remove a resource

Execute an Action on an Entity

POST on TASK Resource

POST must be used to execute Task Resources

Other Request Methods

POST on TASK Resource

GET and POST must not be used to tunnel other request methods.


Filtering and attribute selection rules are described in the TMF REST Design Guidelines.
Notifications are also described in a subsequent section.

GET /API/troubleTicket/{ID}}/?{fields=attributes}&{filtering expression}

This Uniform Contract operation is used to retrieve the representation of a ticket.
Note that collections can be retrieved via GET /API/troubleTicket/ with no {ID}
Filtering is allowed on all attributes. See example below. Attribute selection is possible for all attributes. See example below.

REQUEST

GET /api/troubleTicket
Accept: application/json

RESPONSE

200
Content-Type: application/json

[
{
"id": "1",
"correlationId": "TT53482",
"description": "Customer complaint over last invoice.",
"severity": "Urgent",
"type": "Bills, charges or payment",
"creationDate": "2013-07-23T08:16:39.0Z",
"targetResolutionDate": "2013-07-30T10:20:01.0Z",
"status": "In Progress",
"subStatus": "Held",
"statusChangeReason": "Waiting for invoicing expert.",
"statusChangeDate": "2013-07-24T08:55:12.0Z",
"relatedParty": [
{
"href": "/customer/1234",
"role": "Originator"
},
{
"href": "/operator/1234",
"role": "Owner"
},
{
"href": "Roger Collins",
"role": "Reviser"
}
],
"relatedObject": [
{
"involvement": "Disputed",
"reference": "/invoice/1234"
},
{
"involvement": "Adjusted",
"reference": "/invoice/5678"
}
],
"note": [
{
"date": "2013-07-24T09:55:30.0Z",
"author": "Arthur Evans",
"text": "Already called the expert"
},
{
"date": "2013-07-25T08:55:12.0Z",
"author": "Arthur Evans",
"text": "Informed the originator"
}
]
},
{
"id": "2",
"correlationId": "",
"description": "Customer asks for information about upgrading products.",
"severity": "Low",
"type": "Products and Services",
"creationDate": "2013-07-25T08:16:00.0Z",
"targetResolutionDate": "2013-07-28T00:00:00.0Z",
"status": "",
"subStatus": "",
"statusChangeReason": "",
"statusChangeDate": "2013-07-25T08:16:00.0Z",
"resolutionDate": "",
"relatedParty": [
{
"href": "/customer/4567",
"role": "Originator"
}
],
"relatedObject": [
],
"note": [
]
}
]


Retrieving all tickets – returns an array/ a list of tickets:

  • GET /api/ticket

Retrieving all tickets which were closed after 2013-05-01:

  • GET /api/ticket?status=Close&statusResolutionDate.gt=2013-05-01

Retrieve ticket with specified ID – only one ticket is returned:

  • GET /api/ticket/1

Retrieve ticket with ID but only the attributes status and statusChangeReason in the response, separator for attributes is comma:

  • GET /api/ticket/1/status,statusChangeReason

PUT API/troubleTicket/{ID}

Description :

  • This Uniform Contract operation is used to completely update the representation of a ticket.
  • Resource represents a managed entity.

Behavior :

  • Returns HTTP/1.1 status code 201 if the request was successful.
  • Returns HTTP/1.1 status code 400 (Bad request) if content is invalid (missing required attributes, …).

Updating the whole ticket – if you try to change the ticket ID itself an exception is returned. All fields with different values will be changed. If the request contains the same values like the current ticket representation, nothing is changed. If an element is empty in the request, the value of the element will be deleted. If it is a required element, an exception is returned.

REQUEST

PUT API/ troubleTicket/1
Content-type: application/json

{
"id": "1",
"correlationId": "TT53482",
"description": "Customer complaint over last invoice.",
"severity": "Urgent",
"type": "Bills, charges or payment",
"creationDate": "2013-07-23T08:16:39.0Z",
"targetResolutionDate": "2013-07-30T10:20:01.0Z",
"status": "In Progress",
"subStatus": "Held",
"statusChangeReason": "Waiting for invoicing expert.",
"statusChangeDate": "2013-07-24T08:55:12.0Z",
"relatedParty": [
{
"href": "/customer/1234",
"role": "Originator"
},
{
"href": "/operator/1234",
"role": "Owner"
},
{
"href": "Roger Collins",
"role": "Reviser"
}
],
"relatedObject": [
{
"involvement": "Disputed",
"reference": "/invoice/1234"
},
{
"involvement": "Adjusted",
"reference": "/invoice/5678"
}
],
"note": [
{
"date": "2013-07-24T09:55:30.0Z",
"author": "Arthur Evans",
"text": "Already called the expert"
},
{
"date": "2013-07-25T08:55:12.0Z",
"author": "Arthur Evans",
"text": "Informed the originator"
}
]
}

RESPONSE

201
Content-Type: application/json

{
"id": "1",
"correlationId": "TT53482",
"description": "Customer complaint over last invoice.",
"severity": "Urgent",
"type": "Bills, charges or payment",
"creationDate": "2013-07-23T08:16:39.0Z",
"targetResolutionDate": "2013-07-30T10:20:01.0Z",
"status": "In Progress",
"subStatus": "Held",
"statusChangeReason": "Waiting for invoicing expert.",
"statusChangeDate": "2013-07-24T08:55:12.0Z",
"relatedParty": [
{
"href": "/customer/1234",
"role": "Originator"
},
{
"href": "/operator/1234",
"role": "Owner"
},
{
"href": "Roger Collins",
"role": "Reviser"
}
],
"relatedObject": [
{
"involvement": "Disputed",
"reference": "/invoice/1234"
},
{
"involvement": "Adjusted",
"reference": "/invoice/5678"
}
],
"note": [
{
"date": "2013-07-24T09:55:30.0Z",
"author": "Arthur Evans",
"text": "Already called the expert"
},
{
"date": "2013-07-25T08:55:12.0Z",
"author": "Arthur Evans",
"text": "Informed the originator"
}
]
}


Example see TMF REST Design Guidelines.

PATCH API/troubleTicket/{ID}

Description :

  • This Uniform Contract operation is used to partially update the representation of a ticket.
  • Resource represents a managed entity.

Behavior :
Patching of status is only allowed to transition :

  • from "resolved" to "closed",
  • from "created", "acknowledged" or "in progress" to "cancelled"

Patching of relatedParties[], relatedObjects[] or notes[] replaces previous value set.

Attribute name

Patchable

Rule

id

N

 

correlationId

N

 

description

Y

 

severity

Y

 

type

Y

 

creationDate

N

 

targetResolutionDate

Y

 

status

Y

 

subStatus

Y

 

statusChangeReason

Y

 

statusChangeDate

Y

 

resolutionDate

Y

 

relatedParty

Y

 

relatedObject

Y

 

note

Y

 


Further document any rules that must be implemented when patching attributes.

Rule name

Rule/Pre Condition/Side Effects/Post Conditons

To be completed

To be completed

REQUEST

PATCH API/ troubleTicket /{ID}
Content-type: application/json

{
"status": "Close",
"statusChangeReason": "Dispute has been resolved in favor of the customer."
}

RESPONSE

201
Content-Type: application/json

{
"id": "1",
"correlationId": "TT53482",
"description": "Customer complaint over last invoice.",
"severity": "Urgent",
"type": "Bills, charges or payment",
"creationDate": "2013-07-23T08:16:39.0Z",
"targetResolutionDate": "2013-07-30T10:20:01.0Z",
"status": " Closed ",
"subStatus": "",
"statusChangeReason": " Dispute has been resolved in favor of the customer. ",
"statusChangeDate": "2013-07-24T08:55:12.0Z",
"relatedParty": [
{
"href": "/customer/1234",
"role": "Originator"
},
{
"href": "/operator/1234",
"role": "Owner"
},
{
"href": "Roger Collins",
"role": "Reviser"
}
],
"relatedObject": [
{
"involvement": "Disputed",
"reference": "/invoice/1234"
},
{
"involvement": "Adjusted",
"reference": "/invoice/5678"
}
],
"note": [
{
"date": "2013-07-24T09:55:30.0Z",
"author": "Arthur Evans",
"text": "Already called the expert"
},
{
"date": "2013-07-25T08:55:12.0Z",
"author": "Arthur Evans",
"text": "Informed the originator"
}
]
}

POST API/ticket

Description :

  • This Uniform Contract operation is used to create a ticket.
  • Resource represents a managed entity.
  • Mandatory attributes that must be provided when you create the ticket :

Description, severity, type
Behavior :

  • Returns HTTP/1.1 status code 201 if the request was successful.
  • Returns HTTP/1.1 status code 400 (Bad request) if content is invalid (missing required attributes, …).

 

Attribute name

Mandatory

Default

Rule

Id

N

 

Initialized by TT handler

correlationId

N

 

 

description

Y

 

 

severity

Y

 

 

type

Y

 

 

creationDate

N

Date of the day

Initialized by TT handler

targetResolutionDate

N

 

 

status

N

Created

Initialized by TT handler

subStatus

N

 

 

statusChangeReason

N

 

 

statusChangeDate

N

Date of the day

 

resolutionDate

N

 

 

relatedParty

N

 

 

relatedObject

N

 

 

Note

N

 

 


Further specify any rules on the creation of the entity

Rule name

Rule

To be completed

To be completed


The requester should not provide an id – it is generated automatically by the TT handler. A correlationId can be provided, but is not mandatory.
Create a ticket only with mandatory attributes:

REQUEST

POST API/ troubleTicket
Content-type: application/json

{
"description": "Customer complaint over last invoice.",
"severity": "Urgent",
"type": "Bills, charges or payment"
}

RESPONSE

201
Content-Type: application/json
{
"id": "1",
"correlationId": "TT53482",
"description": "Customer complaint over last invoice.",
"severity": "Urgent",
"type": "Bills, charges or payment",
"creationDate": "2013-07-23T08:16:39.0Z",
"targetResolutionDate": "2013-07-30T10:20:01.0Z",
"status": "Created",
"subStatus": "",
"statusChangeReason": "",
"statusChangeDate": "2013-07-24T08:55:12.0Z",
"resolutionDate": "",
"relatedParty": [
],
"relatedObject": [
],
"note": [
]
}

 

© TM Forum 2015. All Rights Reserved