Users require the following permissions and roles to use the APIs:
Permissions required: Incident and Change Management permission.
Roles required: Incident management and Change Management roles.
Authentication: JWT authentication
Creates a new trouble ticket.
POST /api/com.bmc.dsm.netops-extensions/v1/troubleTicket
Required headers:
Content-Type:application/json
X-Requested-By:XMLHttpRequest
None
Fields description
| Name | Type | Description |
|---|
| fields | String | Optional. Returns only the specified fields for each ticket in the list. Example. fields=status,severity |
Request Body parameters
Fields description
| Name | Type | Description |
|---|
| name | (String) | Title or summary of the trouble ticket. |
| description | (String) | Detailed description of the issue. |
| severity | (String) | Severity level of the issue. |
| company | (String) | The company to which the ticket belongs. |
| ticketType | (String) | The type of the ticket (e.g., Incident, Request, etc.). |
| status | (String) | Current status of the ticket. |
| requestedResolutionDate | (Datetime - ISO 8601) | Expected resolution date/time in ISO 8601, in double quotes (e.g., "2025-04-15T16:49:50.154Z"). |
| channel | (Object) | Channel through which the ticket was raised. |
| ├─ id | (String) | Identifier of the channel. |
| └─ name | (String) | Name of the channel. |
| relatedEntity | (Array of objects) | Entities related to this ticket such as alarms, assets, etc. |
| ├─ role | (String) | Role of the related entity (e.g., "alarm", "asset", "Requested"). |
| ├─ @type | "RelatedEntity" | Type definition as per TMF621 model. |
| └─ entity | (Object) | Entity object with detailed attributes. Other attributes inside entity, such as name, href, alarmType, etc., are optional and may depend on the @referredType. |
| ├─ id | (String) | Unique identifier of the related entity. |
| ├─ name | (String) | Human-readable name of the entity. |
| └─ @referredType | (String) | Declares the type of entity being referred to. Supported values: "alarm", "asset", "sourceRequest". |
| relatedParty | (Array of objects) | Parties associated with the ticket. |
| ├─ role | (String) | Role of the party (e.g., "Business", "Technician"). |
| ├─ @type | "RelatedPartyRefOrPartyRoleRef" | TMF model-specific type. |
| └─ partyOrPartyRole | (Object) | Reference to party or party role. |
| ├─ id | (String) | Identifier of the person or group. |
| ├─ name | (String) | Name of the person or group. |
| ├─ @type | "PartyRef" | Declares the referenced object as a party. |
| └─ @referredType | (String) | Type of the referenced party. Supported values: "User", "Group". |
| note | (Array of objects) | Notes attached to the ticket. |
| ├─ date | (Datetime - ISO 8601) | Noted date/time in ISO 8601, in double quotes (e.g., "2025-04-15T16:49:50.154Z"). |
| ├─ author | (String) | Author of the note. |
| └─ text | (String) | Content of the note. |
Example request body
{
"name": "Petramco Simple Trouble ticket with all incident required fields",
"description": "Petramco Simple Trouble ticket with all incident required fields",
"severity": "Medium",
"company": "Petramco",
"ticketType": "Incident",
"status": "Pending",
"requestedResolutionDate": "2025-05-17T05:09:14.000Z",
"channel": {
"id": "501",
"name": "Channel A"
},
"relatedEntity": [
{
"role": "alarm",
"@type": "RelatedEntity",
"entity": {
"@referredType": "alarm",
"href": "alarm link",
"id": "1234",
"name": "Network 402",
"sourceSystemId": "Postman",
"alarmType": "communicationsAlarm",
"perceivedSeverity": "major",
"probableCause": "cause in network cabel",
"state": "Ack",
"alarmRaisedTime": "2025-05-18T09:48:48Z",
"alarmObjectType": "",
"alarmDetails": "Fault in network - new alarm",
"isRootCause": "Yes",
"plannedOutageIndicator": "not set",
"proposedRepairedActions": "check all wire connections",
"reportingSystemId": "",
"serviceAffecting": "Yes",
"specificProblem": "not identified",
"ackState": "",
"ackSystemId": "",
"ackUserId": "",
"alarmEscalation": "Yes",
"isPrimary": "True",
"alarmChangedTime": "",
"alarmClearedTime": "",
"alarmReportingTime": "2025-05-17T09:48:48Z",
"clearSystemId": "",
"clearUserId": ""
}
},
{
"role": "asset",
"@type": "RelatedEntity",
"entity": {
"id": "REGIIBOZBGFZTASMGHRQSMGHRQ3CYT",
"name": "Network 401",
"@type": "EntityRef",
"@referredType": "asset"
}
},
{
"role": "Requested",
"@type": "RelatedEntity",
"entity": {
"id": "90001",
"name": "Dummy Source Request",
"@type": "EntityRef",
"@referredType": "sourceRequest"
}
}
],
"relatedParty": [
{
"role": "Business",
"@type": "RelatedPartyRefOrPartyRoleRef",
"partyOrPartyRole": {
"id": "GPL000000000166",
"name": "Sammy Adams",
"@type": "PartyRef",
"@referredType": "User"
}
},
{
"role": "Business",
"@type": "RelatedPartyRefOrPartyRoleRef",
"partyOrPartyRole": {
"id": "GGP000000000020",
"name": "GB Support 3",
"@type": "PartyRef",
"@referredType": "Group"
}
}
],
"note": [
{
"date": "2025-05-08T22:41:49.000Z",
"author": "sadams",
"text": "A Test note for testing - 01"
}
]
}
Response example
{
"severity": "Medium",
"note": [
{
"date": "2025-05-08T22:41:49.000Z",
"author": "sadams",
"text": "A Test note for testing - 01"
},
{
"date": "2025-06-23T11:41:57.000Z",
"author": "ppan",
"text": "The Network 402 CI lookup process did not return any matches. Attach the correct instance of the CI to the request."
}
],
"@type": "TroubleTicket",
"relatedEntity": [
{
"entity": {
"name": "Dummy Source Request",
"@referredType": "SourceRequest",
"id": "90001",
"href": "/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASY1E7XSY1E7XHW70/sourceRequest/90001",
"@type": "EntityRef"
},
"@type": "RelatedEntity",
"role": "Requested"
},
{
"entity": {
"name": "Network 401",
"@referredType": "Asset",
"id": "REGIIBOZBGFZTASMGHRQSMGHRQ3CYT",
"href": "/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASY1E7XSY1E7XHW70/asset/REGIIBOZBGFZTASMGHRQSMGHRQ3CYT",
"@type": "EntityRef"
},
"@type": "RelatedEntity",
"role": "asset"
},
{
"entity": {
"name": "Network 402",
"@referredType": "Alarm",
"id": "1234",
"href": "/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASY1E7XSY1E7XHW70/alarm/1234",
"@type": "EntityRef"
},
"@type": "RelatedEntity",
"role": "alarm"
}
],
"channel": {
"@type": "ChannelRef",
"name": "Channel A",
"id": "501"
},
"description": "Petramco Simple Trouble ticket with all incident required fields",
"creationDate": "2025-06-23T11:41:57.000Z",
"relatedParty": [
{
"partyOrPartyRole": {
"@referredType": "User",
"name": "sadams",
"id": "GPL000000000166",
"href": "/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASY1E7XSY1E7XHW70/relatedParty/GPL000000000166"
},
"role": "Business",
"@type": "RelatedPartyRefOrPartyRoleRef"
},
{
"partyOrPartyRole": {
"@referredType": "Group",
"name": "GGP000000000020",
"id": "GGP000000000020",
"href": "/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASY1E7XSY1E7XHW70/relatedParty/GGP000000000020"
},
"role": "Business",
"@type": "RelatedPartyRefOrPartyRoleRef"
}
],
"lastUpdate": "2025-06-23T11:41:57.000Z",
"name": "Petramco Simple Trouble ticket with all incident requred fields",
"id": "AGGADGG8ECDC1ASY1E7XSY1E7XHW70",
"href": "https://is-hostname/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASY1E7XSY1E7XHW70",
"requestedResolutionDate": "2025-05-17T05:09:14.000Z",
"incidentNumber": "INC000000000003",
"status": "Assigned"
}
To add custom fields
You can use the TMF621 trouble ticket API (POST and GET operations) to include custom fields that reflect your organization’s operational needs. These fields enhance ticket metadata, enabling more effective automation, routing, and reporting.
- Define the required fields in the BMC Helix ITSM backend forms by using Developer Studio. Make sure these fields are available in Smart IT views.
Supported field types: - Map the defined fields to the appropriate record definitions in BMC Helix Innovation Studio to make sure they are available for API operations.
Available record definitions for Network Service Operations:| Mapping document | Record definition |
|---|
| TMF621 -V1- Trouble Ticket – Incident Field Mapping | Incident Field Mapping |
| TMF621 -V1- Related Party Mapping | RP-Related Party |
| TMF621 -V1- Related Entity Mapping – Source Request | SR-Source Request |
| TMF621 -V1- Related Entity Mapping – Alarm | AM-Alarm |
For more information, see the Adding a field in the BMC Helix Innovation Studio record definition to map a custom field in the BMC Helix Multi-Cloud Broker online documentation.
- Add the mapped fields to TMF621 API payloads.
After mapping, include the custom fields in the TMF621 REST API payloads.
WarningImportant
When you add custom fields via the TMF621 API, the GET operation will also retrieve the added custom fields.
GET Trouble Ticket(s)
Use the following endpoints to retrieve the information about trouble tickets and their related details.
Retrieve a Trouble Ticket by ID
Returns the details of a specific trouble ticket identified by its ID.
GET /api/com.bmc.dsm.netops-extensions/v1/troubleTicket/{id}
Required headers:
Content-Type:application/json
X-Requested-By:XMLHttpRequest
Path parameters
Fields description
| Name | Type | Description |
|---|
| id | String | Trouble Ticket Id |
Query parameters
Fields description
| Name | Type | Description |
|---|
| fields | String | Optional. Returns only the specified fields. Useful for partial responses. fields=id,status,relatedEntity |
| String | Optional. Related Entities page size. |
| (none) | (no query param) | If fields are not provided, the full Trouble Ticket is returned including all populated fields (sub-resources may be limited for performance). |
Request example
{{server}}/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC0ASVZS3FSVZS3F09Q3?fields=severity
Response
Response example
{
"severity": "Low",
"@type": "TroubleTicket",
"id": "AGGADGG8ECDC0ASVZS3FSVZS3F09Q3",
"href": "https://is-hostname/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC0ASVZS3FSVZS3F09Q3",
"incidentNumber": "INC000000000124"
}
Get a list of Trouble Tickets
Returns the list of trouble tickets.
GET /api/com.bmc.dsm.netops-extensions/v1/troubleTicket
Required headers:
Content-Type:application/json
X-Requested-By:XMLHttpRequest
Path parameters
None
Query parameters
Fields description
| Name | Type | Description |
|---|
| fields | String | Optional. Returns only the specified fields for each ticket in the list. Example. fields=status,severity |
| offset | String | Optional. Skips the first n results. Used for pagination. Example. offset=0 |
| limit | String | Optional. Limits the number of tickets returned. Example. limit=50 |
| attribute=value | String | Optional. Filters tickets by status. Attribute filtering applies to first-level fields. See "TMF630_REST_API_Design_Guidelines_Part1_v4", section 4.3. Query partial Resource representation or attribute selection for details. Example. severity=High |
WarningImportant
- Filtering is based on name=value query parameters.
- Multiple filters are ANDed together.
OR logic is supported by using the Comma-separated values: severity=High,Low
Request example - GET with Attribute filtering and pagination
{{server}}/api/com.bmc.dsm.netops-extensions/v1/troubleTicket?severity=High,Low&offset=0&limit=10
This request retrieves Trouble Tickets where the severity is either High or Low, and applies pagination by using offset and limit.
Response
Response example
[
{
"severity": "Low",
"note": [],
"@type": "TroubleTicket",
"description": "This is incident 2",
"creationDate": "2023-05-02T09:03:01.000Z",
"relatedParty": [],
"lastUpdate": "2023-05-10T12:11:04.000Z",
"name": "Outlook Web App connectivity (External) transaction failures.",
"company": "Petramco",
"id": "IDGDTQ9WI25NDARUAXENRUAXEN7GNE",
"href": "https://is-hostname/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/IDGDTQ9WI25NDARUAXENRUAXEN7GNE",
"incidentNumber": "INC999000000002",
"status": "acknowledged"
},
{
"severity": "High",
"note": [],
"@type": "TroubleTicket",
"channel": {
"@type": "ChannelRef",
"name": "Demo Channel",
"id": "666"
},
"description": "Includes related entities (alarm, asset, source request), related parties and notes",
"creationDate": "2025-05-07T12:59:57.000Z",
"relatedParty": [],
"lastUpdate": "2025-05-07T13:00:00.000Z",
"name": "Trouble ticket with all fields and array types",
"company": "Petramco",
"id": "AGGADGG8ECDC0ASVWGRXSVWGRXD6SX",
"href": "https://is-hostname/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC0ASVWGRXSVWGRXD6SX",
"incidentNumber": "INC000000000120",
"status": "acknowledged"
}
]
| | |
|---|
| | |
| content-type | | |
| X-Total-Count | 62 | The total number of matching records available on the server, regardless of how many were returned in the current response. |
| X-Result-Count | 2 | The number of items actually returned in the current API response. |
Returns the details about related parties associated with a trouble ticket.
GET /api/com.bmc.dsm.netops-extensions/v1/troubleTicket/{id}/relatedParty/{relatedPartyId}
Required headers:
Content-Type:application/json
X-Requested-By:XMLHttpRequest
Path parameters
Fields description
| Name | Type | Description |
|---|
| id | String | Trouble Ticket Id |
| relatedPartyId | String | Related Party Id |
Query parameters
None
Request example
{{server}}/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASY1E7XSY1E7XHW70/relatedParty/GGP000000000020
This request retrieves a Trouble Ticket Related Party.
Response
Response example
{
"partyOrPartyRole": {
"@referredType": "Group",
"name": "GGP000000000020",
"id": "GGP000000000020",
"href": "/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASY1E7XSY1E7XHW70/relatedParty/GGP000000000020"
},
"role": "Business",
"@type": "RelatedPartyRefOrPartyRoleRef"
}
Returns details of entities linked to a trouble ticket.
GET /api/com.bmc.dsm.netops-extensions/v1/troubleTicket/{id}/relatedEntity
Required headers:
Content-Type:application/json
X-Requested-By:XMLHttpRequest
Path parameters
Fields description
| Name | Type | Description |
|---|
| id | String | Trouble Ticket Id |
Query parameters
Fields description
| Name | Type | Description |
|---|
| entityType | String | Optional. The entityType query parameter can be used to filter related entities by their type. It supports multiple values, by using comma-separated format for OR filtering. Supported entity types: Alarm, Asset, SourceRequest Example. entityType=Alarm,Asset |
| offset | Integer | Optional. Skips the first n results. Used for pagination. Example. offset=0 |
| limit | Integer | Optional. Limits the number of tickets returned. Example. limit=50 |
Request example - GET with Attribute filtering and pagination
{{server}}/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASU9MHSSU9MHSS9V7/relatedEntity?offset=0&limit=5&entityType=Alarm,Asset,SourceRequest
This request retrieves a paged list of related entities linked to a specific Trouble Ticket, filtered by entity type, and applies pagination by using offset and limit.
Response
Response example
[
{
"severity": "Low",
"note": [],
"@type": "TroubleTicket",
"description": "This is incident 2",
"creationDate": "2023-05-02T09:03:01.000Z",
"relatedParty": [],
"lastUpdate": "2023-05-10T12:11:04.000Z",
"name": "Outlook Web App connectivity (External) transaction failures.",
"company": "Petramco",
"id": "IDGDTQ9WI25NDARUAXENRUAXEN7GNE",
"href": "https://is-hostname/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/IDGDTQ9WI25NDARUAXENRUAXEN7GNE",
"incidentNumber": "INC999000000002",
"status": "acknowledged"
},
{
"severity": "High",
"note": [],
"@type": "TroubleTicket",
"channel": {
"@type": "ChannelRef",
"name": "Demo Channel",
"id": "666"
},
"description": "Includes related entities (alarm, asset, source request), related parties and notes",
"creationDate": "2025-05-07T12:59:57.000Z",
"relatedParty": [],
"lastUpdate": "2025-05-07T13:00:00.000Z",
"name": "Trouble ticket with all fields and array types",
"company": "Petramco",
"id": "AGGADGG8ECDC0ASVWGRXSVWGRXD6SX",
"href": "https://is-hostname/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC0ASVWGRXSVWGRXD6SX",
"incidentNumber": "INC000000000120",
"status": "acknowledged"
}
]
| | |
|---|
| | |
| content-type | | |
| X-Total-Count | 62 | The total number of matching records available on the server, regardless of how many were returned in the current response. |
| X-Result-Count | 2 | The number of items actually returned in the current API response. |
Get Trouble Ticket notes
Returns notes or comments added to a trouble ticket.
GET /api/com.bmc.dsm.netops-extensions/v1/troubleTicket/{id}/note
Required headers:
Content-Type:application/json
X-Requested-By:XMLHttpRequest
Path parameters
Fields description
| Name | Type | Description |
|---|
| id | String | Trouble Ticket Id |
Query parameters
None
Request example
{{server}}/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASY1TK6SY1TK60J3U/note
This request retrieves Trouble Ticket notes.
Response
Response example
[
{
"date": "2025-05-08T22:41:49.000Z",
"author": "pbunyon",
"text": "A Test note for testing."
}
]
Get Trouble Ticket alarm
Returns alarm information associated with a trouble ticket.
GET /api/com.bmc.dsm.netops-extensions/v1/troubleTicket/{id}/alarm/{alarmId}
Required headers:
Content-Type:application/json
X-Requested-By:XMLHttpRequest
Path parameters
Fields description
| Name | Type | Description |
|---|
| id | String | Trouble Ticket Id |
| alarmId | String | Alarm Id |
Query parameters
None
Request example
{{server}}/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASY1BSGSY1BSGHM5W/alarm/1234
This request retrieves a Trouble Ticket alarm.
Response
Response example
{
"reportingSystemId": "",
"alarmRaisedTime": "2025-05-18T09:48:48Z",
"alarmClearedTime": "",
"@type": "Alarm",
"proposedRepairedActions": "check all wire connections",
"alarmReportingTime": "2025-05-17T09:48:48Z",
"alarmEscalation": false,
"alarmChangedTime": "",
"perceivedSeverity": "major",
"probableCause": "cause in network cabel",
"isPrimary": false,
"ackSystemId": "",
"state": "Ack",
"id": "1234",
"href": "/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASY1BSGSY1BSGHM5W/alarm/1234",
"clearSystemId": "",
"isRootCause": false,
"ackUserId": "",
"sourceSystemId": "Postman",
"serviceAffecting": false,
"clearUserId": "",
"ackState": "",
"alarmType": "communicationsAlarm",
"alarmObjectType": "",
"specificProblem": "not identified",
"name": "Network 402",
"plannedOutageIndicator": "not set",
"alarmDetails": "Fault in network - new alarm"
}
Get the Trouble Ticket source request
Returns the original request or event that triggered the creation of the trouble ticket.
GET /api/com.bmc.dsm.netops-extensions/v1/troubleTicket/{id}/sourceRequest/{sourceRequestId}
Required headers:
Content-Type:application/json
X-Requested-By:XMLHttpRequest
Path parameters
Fields description
| Name | Type | Description |
|---|
| id | String | Trouble Ticket Id |
| sourceRequestId | String | Source Request Id |
Query parameters
Fields description
| Name | Type | Description |
|---|
| fields | String | Optional. Returns only the specified fields for each ticket in the list. Example. fields=customField |
Request example
{{server}}/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASY1BNBSY1BNBHLRG/sourceRequest/REHAA5V0GQBORANBH63AI85CJ2JMLY
This request retrieves a Trouble Ticket source request.
Response
Response example
{
"@referredType": "SourceRequest",
"@type": "relatedEntity",
"name": "632XF1S",
"id": "REHAA5V0GQBORANBH63AI85CJ2JMLY",
"href": "/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASY1BNBSY1BNBHLRG/sourceRequest/REHAA5V0GQBORANBH63AI85CJ2JMLY"
}
Get the Trouble Ticket asset
Returns asset details related to a trouble ticket.
GET /api/com.bmc.dsm.netops-extensions/v1/troubleTicket/{id}/asset/{assetId}
Required headers:
Content-Type:application/json
X-Requested-By:XMLHttpRequest
Path parameters
Fields description
| Name | Type | Description |
|---|
| id | String | Trouble Ticket Id |
| assetId | String | Asset Id |
Query parameters
Fields description
| Name | Type | Description |
|---|
| fields | String | Optional. Returns only the specified fields for each ticket in the list. Example. fields=customField |
Request example
{{server}}/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASY1UVOSY1UVO03Z0/asset/REHAA5V0GQBORANBH631IKTA4IJMQ1
This request retrieves a Trouble Ticket asset.
Response
Response example
{
"role": "asset",
"type": "RelatedEntity",
"entity": {
"referredType": "Asset",
"createdDate": "2025-06-23T21:11:48.000Z",
"name": "1LLZ6BS",
"href": "/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASY1UVOSY1UVO03Z0/asset/REHAA5V0GQBORANBH631IKTA4IJMQ1",
"id": "REHAA5V0GQBORANBH631IKTA4IJMQ1",
"displayId": "000000000000025",
"type": "EntityRef"
}
}
PATCH Trouble Ticket
Adds an asset reference to an existing trouble ticket.
PATCH /api/com.bmc.dsm.netops-extensions/v1/troubleTicket/{id}
Required headers:
Content-Type:application/json-patch-query+json
X-Requested-By:XMLHttpRequest
Path parameters
Fields description
| Name | Type | Description |
|---|
| id | String | Trouble Ticket Id |
Request Body parameters
Fields description
| Name | Type | Description |
|---|
| op | "add" | Patch operation to add a new value. |
| path | "/relatedEntity" | Target path in the resource where the value will be added. |
| value | (Object) | The object to add — a RelatedEntity. |
| ├─role | (String) | Role of the entity (e.g., "asset", "alarm"). |
| ├─ @type | "RelatedEntity" | Declares the type of this object per TMF621 model. |
| └─ entity | (Object) | Reference to the actual entity being related. |
| ├─ id | (String) | Unique identifier of the related entity. |
| (String) | Reconciliation ID of the configuration item (CI) |
| ├─ @type | "EntityRef" | Declares this is a reference to another entity. |
| └─ @referredType | (String) | Type of the referenced entity (e.g., "asset", "sourceRequest", "alarm"). |
Example request body
[
{
"op": "add",
"path": "/relatedEntity",
"value": {
"role": "asset",
"@type": "RelatedEntity",
"entity": {
"id": "REHAA5V0GQBORANBH63AI85CJ2JMLY",
"reconId": "632XF1S",
"@type": "EntityRef",
"@referredType": "asset"
}
}
}
]
Response
| | |
|---|
| | |
| | |
| When a user attempts to add an asset with missing or invalid fields results in a validation error with below response value |
| HTTP code | 207 | - |
Response example including Sub-Messages
Click here to expand...
{
"message": "Ticket was updated successfully, but related issues were encountered",
"@type": "TroubleTicket",
"status": 200,
"subMessages": [
{
"message": "Error while creating Asset:[ERROR (245090): Failed to create asset relationships for the incident; Related Entity - Asset not created for incident: INC000000000121 , id or role field missing]",
"id": "0 - INC000000000121",
"@type": "TroubleTicket",
"status": 500
}
],
"data": {
"severity": "Low",
"note": [],
"@type": "TroubleTicket",
"resolutionDate": null,
"description": "Also incudes company (not part of TMF)",
"creationDate": "2025-05-09T10:08:20.000Z",
"relatedParty": [],
"lastUpdate": "2025-05-09T10:08:21.000Z",
"name": "Simple Trouble ticket with minum requred fields",
"company": "Petramco",
"id": "AGGADGG8ECDC0ASVZOFWSVZOFW00UT",
"href": "https://hostname/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC0ASVZOFWSVZOFW00UT",
"requestedResolutionDate": null,
"incidentNumber": "INC000000000121",
"status": "acknowledged"
}
}
Adds a source request reference to an existing trouble ticket.
PATCH /api/com.bmc.dsm.netops-extensions/v1/troubleTicket/{id}
Required headers:
Content-Type:application/json-patch-query+json
X-Requested-By:XMLHttpRequest
Path parameters
Fields description
| Name | Description | Type |
|---|
| id | Trouble Ticket Id | String |
Request Body parameters
Fields description
| Name | Type | Description |
|---|
| op | "add" | Operation type: add a new value. |
| path | "/relatedEntity" | Target array path for adding the related entity. |
| value | (Object) | The object being added — a RelatedEntity. |
| ├─ role | (String) | Role of the related entity (e.g., Billing, Asset, Alarm). |
| ├─ @type | "RelatedEntity" | Declares the type of the outer object as RelatedEntity. |
| └─ entity | (Object) | The referenced entity being associated with the Trouble Ticket. |
| ├─ id | (String) | Unique ID of the referenced sourceRequest. |
| ├─ name | (String) | Human-readable name of the referenced entity. |
| ├─ @type | "EntityRef" | Indicates this is a reference to another resource. |
| └─ @referredType | "SourceRequest" | Specifies the actual type of the referenced entity for polymorphic resolution. |
Example request body
[
{
"op": "add",
"path": "/relatedEntity",
"value": {
"role": "Billing",
"@type": "RelatedEntity",
"entity": {
"id": "0123456789",
"name": "Billing Source Request",
"@type": "EntityRef",
"@referredType": "SourceRequest"
}
}
}
]
Response
| | |
|---|
| | |
| | |
| When a user attempts to add a source request with an incorrect @referredType or a missing ID, it triggers an error. |
| HTTP code | 207 | -
Response example including Sub-Messages
Click here to expand...
{
"message": "Ticket was updated successfully, but related issues were encountered",
"@type": "TroubleTicket",
"status": 200,
"subMessages": [
{
"message": "Error while creating SourceRequest:[ERROR (245090): Failed to create asset relationships for the incident; Related Entity - Source Request not created for incident AGGADGG8ECDC0ASVZQC9SVZQC905FH, id or role field missing. Object: {\"@referredType\":\"SourceRequest\",\"role\":\"Billing\",\"@type\":\"EntityRef\",\"name\":\"Billing Source Request\"}]",
"id": "0 - AGGADGG8ECDC0ASVZQC9SVZQC905FH",
"@type": "TroubleTicket",
"status": 500
}
],
"data": {
"severity": "Low",
"note": [],
"@type": "TroubleTicket",
"resolutionDate": null,
"description": "Also incudes company (not part of TMF)",
"creationDate": "2025-05-09T10:49:31.000Z",
"relatedParty": [],
"lastUpdate": "2025-05-09T10:49:32.000Z",
"name": "Simple Trouble ticket with minum requred fields",
"company": "Petramco",
"id": "AGGADGG8ECDC0ASVZQC9SVZQC905FH",
"href": "https://hostname/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC0ASVZQC9SVZQC905FH",
"requestedResolutionDate": null,
"incidentNumber": "INC000000000122",
"status": "acknowledged"
}
} |
Adds an alarm reference to a trouble ticket, either as primary or secondary.
PATCH /api/com.bmc.dsm.netops-extensions/v1/troubleTicket/{id}
Required headers:
Content-Type:application/json-patch-query+json
X-Requested-By:XMLHttpRequest
Path parameters
Fields description
| Name | Type | Description |
|---|
| id | String | Trouble Ticket Id |
Request Body parameters
Fields description
| Parameter | Example Value (Generic) | Description |
| op | "add" | Operation type: add a new value. |
| path | "/relatedEntity" | Target array path for adding the related alarm entity. |
| value | (Object) | The object being added — a RelatedEntity. |
| └─ role | "alarm" | Role of the related entity (e.g., alarm, asset). |
| └─ @type | "RelatedEntity" | Declares the type of the outer object as RelatedEntity. |
| └─ entity | (Object) | The alarm object being related to the Trouble Ticket. |
| ├─ @type | "alarm" | Declares the specific type of this related entity. |
| ├─ @referredType | "alarm" | Type of the referenced resource, for resolution purposes. |
| ├─ href | (String) | URI or link to the alarm resource (if available). |
| ├─ id | (String) | Unique ID of the alarm. External Alarm Id. |
| ├─ name | (String) | The object or device affected. |
| ├─ alarmType | (String) | Type of the alarm (e.g., "communicationsAlarm"). |
| ├─ perceivedSeverity | (String) | Severity level (e.g., "Minor", "Major", "Critical"). |
| ├─ alarmRaisedTime | (Datetime - ISO 8601) | Timestamp when the alarm was raised (e.g., "2025-04-15T16:49:50.154Z"). |
| ├─ probableCause | (String) | Description of the likely root cause. |
| └─ sourceSystemId | (String) | Identifier of the system where the alarm originated. |
Example request body
[
{
"op": "add",
"path": "/relatedEntity",
"value": {
"role": "alarm",
"@type": "RelatedEntity",
"entity": {
"@type": "alarm",
"@referredType": "alarm",
"href": "alarm link",
"id": "347262",
"name": "632XF1S",
"alarmType": "communicationsAlarm",
"perceivedSeverity": "Major",
"alarmRaisedTime": "2024-04-21T23:50:44.390Z",
"probableCause": "Alarm Text Short",
"sourceSystemId": "Postman"
}
}
}
]
Response
Updates alarm attributes linked to a trouble ticket.
PATCH /api/com.bmc.dsm.netops-extensions/v1/troubleTicket/{id}
Required headers:
Content-Type:application/json-patch-query+json
X-Requested-By:XMLHttpRequest
Path parameters
Fields description
| Name | Type | Description |
|---|
| id | String | Trouble Ticket Id |
Request Body parameters
Fields description
| Name | Type | Description |
| op | "replace" | Operation type: replace an existing value. |
| path | "/relatedEntity?type=alarm&id=3476" | Custom (non-standard) path to identify the related entity to update. |
| value | (Object) | The object that will replace the current related entity. |
| ├─ role | "alarm" | Role of the related entity (e.g., alarm, asset). |
| ├─ @type | "RelatedEntity" | Declares the type of the outer object as RelatedEntity. |
| └─ entity | (Object) | Fields to update in the referenced alarm entity. |
| ├─ perceivedSeverity | "minor" | Updated severity level of the alarm (e.g., "minor", "major", "critical").
|
Example request body
[
{
"op": "replace",
"path": "/relatedEntity?type=alarm&id=3476",
"value": {
"role": "alarm",
"@type": "RelatedEntity",
"entity": {
"perceivedSeverity": "minor"
}
}
}
]
Response
Update Trouble Ticket fields
Updates existing fields of a trouble ticket, such as status, severity, or description.
PATCH /api/com.bmc.dsm.netops-extensions/v1/troubleTicket/{id}
Required headers:
Content-Type:application/json-patch-query+json
X-Requested-By:XMLHttpRequest
Path parameters
Fields description
| Name | Type | Description |
|---|
| id | String | Trouble Ticket Id |
Request Body parameters
Fields description
| Parameter | Location | Description |
|---|
| op | "replace" | Operation type. "replace" updates the value of an existing field. |
| path | "/<fieldName>" | Target field in the Trouble Ticket (e.g., /severity, /status). |
| value | "<newValue>" | New value to set for the given field. Can be any valid value for that field. |
Example request body
[
{
"op": "replace",
"path": "/severity",
"value": "Low"
},
{
"op": "replace",
"path": "/status",
"value": "acknowledged"
}
]
Response
Adds a person or group to the related party section of a trouble ticket.
PATCH /api/com.bmc.dsm.netops-extensions/v1/troubleTicket/{id}
Required headers:
Content-Type:application/json-patch-query+json
X-Requested-By:XMLHttpRequest
Path parameters
Fields description
| Name | Description | Type |
|---|
| id | Trouble Ticket Id | String |
Request Body parameters
Fields description
| Parameter | Location | Description |
|---|
| op | "add" | JSON Patch operation to add a new value to the specified path. |
| path | "/relatedParty" | JSON Pointer path to the relatedParty field in the Trouble Ticket resource. |
| value | (object) | The object to be added — here, a RelatedPartyRefOrPartyRoleRef object. |
| ├─ role | (string) | Role of the party in relation to the Trouble Ticket (e.g., requester, assignee, member, etc.). |
| ├─ partyOrPartyRole | (object) | Reference to the related person or role. |
| ├─ id | (string) | Unique ID of the party or party role. |
| ├─ href | (string) | Hyperlink reference (can be left blank or populated with party URI). |
| ├─ name | (string) | Login Id of the person or party. |
| ├─ @type | "PartyRef" | Type of referenced object — here, a reference to a Party. |
| └─ @referredType | (string) | Type of referenced resource, e.g., "User" or "Organization". |
| └─ @type | "RelatedPartyRefOrPartyRoleRef" | Declares the type of the outer object being added (as defined in TMF621 model). |
Example request body
[
{
"op": "add",
"path": "/relatedParty",
"value": {
"role": "member",
"partyOrPartyRole": {
"id": "9866",
"href": "",
"name": "hhaas",
"@type": "PartyRef",
"@referredType": "User"
},
"@type": "RelatedPartyRefOrPartyRoleRef"
}
}
]
Response
Add notes
Appends a note to the trouble ticket for tracking updates or technician comments.
PATCH /api/com.bmc.dsm.netops-extensions/v1/troubleTicket/{id}
Required headers:
Content-Type:application/json-patch-query+json
X-Requested-By:XMLHttpRequest
Path parameters
Fields description
| Name | Type | Description |
|---|
| id | String | Trouble Ticket Id |
Request Body parameters
Fields description
| Parameter | Example Value (Generic) | Description |
|---|
| op | "add" | Patch operation to add a new value. |
| path | "/note" | Target path in the resource (adds to the note array). |
| value | (object) | The object to add — a Note. |
| ├─ @type | "Note" | Declares this is a Note object (required by TMF621). |
| ├─ id | (string) | Unique identifier for the note. Often system-generated. |
| ├─ author | (string) | Name of the person adding the note. |
| ├─ text | (string) | Content of the note. |
| └─ date | (datetime - ISO 8601) | Timestamp of when the note was added (e.g., "2025-04-15T16:49:50.154Z"). |
Example request body
[
{
"op": "add",
"path": "/note",
"value": {
"@type": "Note",
"id": "77456",
"author": "Jack Smith",
"text": "This is quite important, please approach me as soon as possible",
"date": "2025-04-15T16:49:50.154Z"
}
}
]
Response
Example demonstrating multiple operations across different entities
Shows a PATCH request that updates ticket fields and adds alarms, assets, notes, and related parties in a single operation.
PATCH /api/com.bmc.dsm.netops-extensions/v1/troubleTicket/{id}
Required headers:
Content-Type:application/json-patch-query+json
X-Requested-By:XMLHttpRequest
Path parameters
Fields description
| Name | Type | Description |
|---|
| id | String | Trouble Ticket Id |
Request Body parameters
Fields description
| # | Operation | Path | Value Summary | Description |
|---|
| 1 | replace | /relatedEntity?type=alarm&id=1234 | Update perceivedSeverity to "major" | Replace of a related alarm entity by type and ID. (Note: query-style path is non-standard.) |
| 2 | replace | /severity | "Low" | Replace the severity field of the Trouble Ticket with a new value. |
| 3 | add | /relatedEntity | Full alarm entity (with details like id, severity) | Add a new related alarm entity with detailed alarm attributes (e.g., alarmType, sourceSystemId). |
| 4 | add | /note | Note from "Jack Smith" | Add a new note to the Trouble Ticket with text and metadata. |
| 5 | add | /relatedEntity | Entity of type sourceRequest with role Billing | Add a related entity referencing a billing source request. |
| 6 | add | /relatedEntity | Entity of type asset | Add a related asset to the Trouble Ticket. |
| 7 | add | /relatedParty | Party reference with role "member" | Add a related party (e.g., user or agent) involved in the Trouble Ticket. |
Example request body
[
{
"op": "replace",
"path": "/relatedEntity?type=alarm&id=1234",
"value": {
"role": "alarm",
"@type": "RelatedEntity",
"entity": {
"perceivedSeverity": "major"
}
}
},
{
"op": "replace",
"path": "/severity",
"value": "Low"
},
{
"op": "add",
"path": "/relatedEntity",
"value": {
"role": "alarm",
"@type": "RelatedEntity",
"entity": {
"@type": "alarm",
"@referredType": "alarm",
"href": "alarm link",
"id": "1234567890",
"name": "632XF1S",
"alarmType": "communicationsAlarm",
"perceivedSeverity": "Major",
"alarmRaisedTime": "2024-04-21T23:50:44.390Z",
"probableCause": "Alarm Text Short",
"sourceSystemId": "Postman"
}
}
},
{
"op": "add",
"path": "/note",
"value": {
"@type": "Note",
"id": "77456",
"author": "Jack Smith",
"text": "This is quite important, please approach me as soon as possible",
"date": null
}
},
{
"op": "add",
"path": "/relatedEntity",
"value": {
"role": "Billing",
"@type": "RelatedEntity",
"entity": {
"id": "1111222",
"name": "Billing Source Request",
"@type": "EntityRef",
"@referredType": "sourceRequest"
}
}
},
{
"op": "add",
"path": "/relatedEntity",
"value": {
"role": "asset",
"@type": "RelatedEntity",
"entity": {
"id": "REHAA5V0GQBORANBH63AI85CJ2JMLY",
"name": "632XF1S",
"@type": "EntityRef",
"@referredType": "asset"
}
}
},
{
"op": "add",
"path": "/relatedParty",
"value": {
"role": "member",
"partyOrPartyRole": {
"id": "9866",
"href": "",
"name": "hhaas",
"@type": "PartyRef",
"@referredType": "User"
},
"@type": "RelatedPartyRefOrPartyRoleRef"
}
}
]
Response
