Overview

The TMF621 API provides a standardized client interface to Trouble Ticket Management Systems for creating, tracking, and managing trouble tickets as a result of an issue or problem identified by a customer or another system. Following block diagram provides a high-level overview of how the various components are involved in handling TMF 621 API operations (GET, POST).

TMF621 Components

Consider you have purchased a new service. You can create a new ticket from an external system to log an issue (POST). You can also check the status of the created ticket or access all the tickets from the system (GET).

In general, we can consider the various use cases listed based on the operation you want to perform.

Starting from the Winter ’27 release, only the Direct Access option will be supported. The MuleSoft gateway option will be deprecated, and customers must update their integrations to use the Connect/Apex REST endpoints for continued access to the inbound APIs.

Important

Assumptions:

It is assumed that you have completed the following.

Enabling Access to Industry APIs
Ensuring that the required licenses and data packs are installed.

Sequence of Operations

Following block diagram provides a sequence of operations involved.

Sequence

NOTE:

For mandatory fields and resource mappings, refer TMF621 v5 Resource Mappings.

TMF621 v5 Use Cases

I want to	Request Type	Example URL
Retrieve and display details of a particular caseNumber.	GET by ID	{{orgendpoint}}/services/data/{{version}}/connect/comms/troubleticket/v5/troubleticket/{caseNumber} NOTE: For invalid case ID, you will receive HTTP 404 error.
List all the tickets present in the system.	GET List	{{orgendpoint}}/services/data/{{version}}/connect/comms/troubleticket/v5/troubleticket
List all the tickets present in the system based on the provided field values.	GET with Fields	{{orgendpoint}}/services/data/{{version}}/connect/comms/troubleticket/v5/troubleticket?fields=name,status,description,priority,ticketType NOTE: The requested fields will be part of output, if they have value.
List all the tickets present in the system based on the filter applied.	GET with Filters	{{orgendpoint}}/services/data/{{version}}/connect/comms/troubleticket/v5/troubleticket?status=Working&fields=priority,status,name,ticketType NOTE: The requested fields will be part of output, if they have value.
List tickets, limit the number of tickets to a maximum of specified limit, and display results from the page specified by offset.	GET with Pagination	{{orgendpoint}}/services/data/{{version}}/connect/comms/troubleticket/v5/troubleticket?pageLimit=1&offset=1
Create a new ticket by providing the required details.	POST	{{orgendpoint}}/services/data/{{version}}/connect/comms/troubleticket/v5/troubleticket
Delete a ticket.	DELETE	{{orgendpoint}}/services/data/{{version}}/connect/comms/troubleticket/v5/troubleticket/{caseNumber}

GET by ID

Consider you want to retrieve details of a particular case. For example, caseNumber = 00001022. NOTE: CaseNumber is the unique identifier.

Sample URL

https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/data/v62.0/connect/comms/troubleticket/v5/troubleticket/00001002

Sample Response

1200 OK
2{
3    "id": "00001002",
4    "href": "/connect/comms/troubleticket/v5/troubleticket/00001002",
5    "name": "Seeking guidance on electrical wiring installation for GC5060",
6    "ticketType": "Electrical",
7    "priority": "High",
8    "description": "Case description for testing",
9    "status": "Working",
10    "@type": "TroubleTicket",
11    "severity": "Major",
12    "creationDate": "Wed Jul 10 15:58:07 GMT 2024",
13    "lastUpdate": "Thu Jul 11 12:16:28 GMT 2024",
14    "externalIdentifier": [
15        {
16            "id": "External001",
17            "@type": "ExternalIdentifier"
18        }
19    ],
20    "channel": {
21        "name": "Web",
22        "id": "1",
23        "@type": "ChannelRef"
24    },
25    "statusChangeHistory": [
26        {
27            "status": "Working",
28            "statusChangeDate": "Thu Jul 11 08:30:59 GMT 2024",
29            "@type": "StatusChange"
30        }
31    ],
32    "note": [
33        {
34            "author": "005xx000001X7q9AAC",
35            "text": "CaseComment 1",
36            "@type": "CaseComment"
37        },
38        {
39            "author": "005xx000001X7q9AAC",
40            "text": "CaseComment 2",
41            "@type": "CaseComment"
42        }
43    ],
44    "troubleTicketRelationship": [
45        {
46            "id": "00001000",
47            "href": "/connect/comms/troubleticket/v5/troubleticket/00001000",
48            "name": "Starting generator after electrical failure",
49            "relationshipType": "Parent",
50            "@type": "TroubleTicketRelationship"
51        }
52    ],
53    "relatedParty": [
54        {
55            "role": "Customer - Direct",
56            "partyOrPartyRole": {
57                "id": "001xx000003GYiGAAW",
58                "href": "/services/data/v60.0/sobjects/Account/001xx000003GYiGAAW",
59                "name": "United Oil &amp; Gas Corp.",
60                "@type": "PartyRef",
61                "@referredType": "Account"
62            },
63            "@type": "RelatedPartyRefOrPartyRoleRef"
64        },
65        {
66            "role": "Contact",
67            "partyOrPartyRole": {
68                "id": "003xx000004WhFvAAK",
69                "href": "/services/data/v60.0/sobjects/Contact/003xx000004WhFvAAK",
70                "name": "Stella Pavlova",
71                "@type": "PartyRef",
72                "@referredType": "Contact"
73            },
74            "@type": "RelatedPartyRefOrPartyRoleRef"
75        }
76    ],
77    "relatedEntity": [
78        {
79            "role": "Asset",
80            "@type": "RelatedEntity",
81            "entity": {
82                "id": "02ixx0000004HHiAAM",
83                "href": "/services/data/v60.0/sobjects/Asset/02ixx0000004HHiAAM",
84                "name": "Test Asset",
85                "@type": "EntityRef",
86                "@referredType": "Asset"
87            }
88        }
89    ],
90    "attachment": [
91        {
92            "name": "export",
93            "id": "069xx0000004C92AAE",
94            "description": "sample description",
95            "attachmentType": "JSON",
96            "mimeType": "MimeType",
97            "url": "url",
98            "@type": "AttachmentRef"
99        }
100    ]
101}

GET List

Consider there are multiple tickets in the system and you want to list all of them.

Sample URL

https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/data/v62.0/connect/comms/troubleticket/v5/troubleticket

Sample Response

1200 OK
2
3[
4    {
5        "@type": "TroubleTicket",
6        "lastUpdate": "Wed Jul 10 15:58:07 GMT 2024",
7        "resolutionDate": "Wed May 24 18:59:51 GMT 2023",
8        "name": "Starting generator after electrical failure",
9        "description": "Case description for testing",
10        "severity": "Major",
11        "channel": {
12            "name": "Phone",
13            "id": "1",
14            "@type": "ChannelRef"
15        },
16        "ticketType": "Electrical",
17        "id": "00001000",
18        "href": "/connect/comms/troubleticket/v5/troubleticket/00001000",
19        "priority": "High",
20        "creationDate": "Wed Jul 10 15:58:07 GMT 2024",
21        "relatedParty": [
22            {
23                "role": "Customer - Direct",
24                "partyOrPartyRole": {
25                    "id": "001xx000003GYiBAAW",
26                    "href": "/services/data/v60.0/sobjects/Account/001xx000003GYiBAAW",
27                    "name": "Edge Communications",
28                    "@type": "PartyRef",
29                    "@referredType": "Account"
30                },
31                "@type": "RelatedPartyRefOrPartyRoleRef"
32            },
33            {
34                "role": "Contact",
35                "partyOrPartyRole": {
36                    "id": "003xx000004WhFoAAK",
37                    "href": "/services/data/v60.0/sobjects/Contact/003xx000004WhFoAAK",
38                    "name": "Rose Gonzalez",
39                    "@type": "PartyRef",
40                    "@referredType": "Contact"
41                },
42                "@type": "RelatedPartyRefOrPartyRoleRef"
43            }
44        ],
45        "status": "Closed"
46    },
47    {
48        "troubleTicketRelationship": [
49            {
50                "id": "00001000",
51                "href": "/connect/comms/troubleticket/v5/troubleticket/00001000",
52                "name": "Starting generator after electrical failure",
53                "relationshipType": "Parent",
54                "@type": "TroubleTicketRelationship"
55            }
56        ],
57        "@type": "TroubleTicket",
58        "resolutionDate": "Wed May 24 18:59:51 GMT 2023",
59        "description": "Case description for testing",
60        "severity": "Major",
61        "channel": {
62            "name": "Phone",
63            "id": "1",
64            "@type": "ChannelRef"
65        },
66        "ticketType": "Electrical",
67        "priority": "High",
68        "creationDate": "Wed Jul 10 15:58:07 GMT 2024",
69        "relatedParty": [
70            {
71                "role": "Customer - Direct",
72                "partyOrPartyRole": {
73                    "id": "001xx000003GYiGAAW",
74                    "href": "/services/data/v60.0/sobjects/Account/001xx000003GYiGAAW",
75                    "name": "United Oil &amp; Gas Corp.",
76                    "@type": "PartyRef",
77                    "@referredType": "Account"
78                },
79                "@type": "RelatedPartyRefOrPartyRoleRef"
80            },
81            {
82                "role": "Contact",
83                "partyOrPartyRole": {
84                    "id": "003xx000004WhG5AAK",
85                    "href": "/services/data/v60.0/sobjects/Contact/003xx000004WhG5AAK",
86                    "name": "Avi Green",
87                    "@type": "PartyRef",
88                    "@referredType": "Contact"
89                },
90                "@type": "RelatedPartyRefOrPartyRoleRef"
91            }
92        ],
93        "lastUpdate": "Thu Jul 11 09:34:13 GMT 2024",
94        "name": "Performance inadequate for second consecutive week",
95        "id": "00001001",
96        "href": "/connect/comms/troubleticket/v5/troubleticket/00001001",
97        "status": "Closed"
98    }
99]

GET with Fields

Consider you want to retrieve all the tickets by applying the requested fields. The requested fields will be part of output if they are have value. Following fields are available for selection.

name
status
description
priority
ticketType

Sample URL

https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/data/v62.0/connect/comms/troubleticket/v5/troubleticket?fields=name,status,description,priority,ticketType

Sample Response

The fields id, href, and @type are always present in the response.

1200 OK
2
3[
4    {
5        "@type": "TroubleTicket",
6        "name": "without relatedparty",
7        "description": "Case description for testing",
8        "ticketType": "Electrical",
9        "id": "00001083",
10        "href": "/connect/comms/troubleticket/v5/troubleticket/00001083",
11        "priority": "High",
12        "status": "Working"
13    },
14    {
15        "@type": "TroubleTicket",
16        "name": "without relatedparty",
17        "description": "Case description for testing",
18        "ticketType": "Electrical",
19        "id": "00001081",
20        "href": "/connect/comms/troubleticket/v5/troubleticket/00001081",
21        "priority": "High",
22        "status": "Working"
23    },
24    {
25        "@type": "TroubleTicket",
26        "name": "without relatedparty",
27        "description": "Case description for testing",
28        "ticketType": "Electrical",
29        "id": "00001084",
30        "href": "/connect/comms/troubleticket/v5/troubleticket/00001084",
31        "priority": "High",
32        "status": "Working"
33    },
34    {
35        "@type": "TroubleTicket",
36        "name": "without relatedparty",
37        "description": "Case description for testing",
38        "ticketType": "Electrical",
39        "id": "00001085",
40        "href": "/connect/comms/troubleticket/v5/troubleticket/00001085",
41        "priority": "High",
42        "status": "Working"
43    }
44]

GET with Filters

Consider you want to retrieve all the tickets present in the system with filtering supported for following fields.

status
priority
ticketType

Sample URL

https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/data/v62.0/connect/comms/troubleticket/v5/troubleticket?status=Working&fields=priority,status,name,ticketType

Sample Response

1200 OK
2
3[
4    {
5        "@type": "TroubleTicket",
6        "name": "Seeking guidance on electrical wiring installation for GC5060",
7        "ticketType": "Electrical",
8        "id": "00001002",
9        "href": "/connect/comms/troubleticket/v5/troubleticket/00001002",
10        "priority": "High",
11        "status": "Working"
12    },
13    {
14        "@type": "TroubleTicket",
15        "name": "summer",
16        "ticketType": "Electrical",
17        "id": "00001027",
18        "href": "/connect/comms/troubleticket/v5/troubleticket/00001027",
19        "priority": "High",
20        "status": "Working"
21    },
22    {
23        "@type": "TroubleTicket",
24        "name": "summer",
25        "ticketType": "Electrical",
26        "id": "00001028",
27        "href": "/connect/comms/troubleticket/v5/troubleticket/00001028",
28        "priority": "High",
29        "status": "Working"
30    }
31]

GET with Pagination

Consider you want to retrieve list of tickets and apply required pagination query.

Sample URL

https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/data/v62.0/connect/comms/troubleticket/v5/troubleticket?pageLimit=1&offset=2

NOTE: If the total tickets are 22, the above pagination query pageLimit=1&offset=2 will start display from page 3 by skipping 2 records and each page will contain 1 record.

Sample Response

1200 OK
2
3[
4    {
5        "channel": {
6            "@type": "Channel",
7            "name": "Phone"
8        },
9        "relatedParty": [
10            {
11                "@referredType": "Account",
12                "name": "Burlington Textiles Corp of America",
13                "id": "001RO000003zz9SYAQ"
14            },
15            {
16                "@referredType": "Contact",
17                "name": "Jack Rogers",
18                "id": "003RO00000366d5YAA"
19            }
20        ],
21        "statusChangeDate": "2022-09-21T05:24:40.000Z",
22        "name": "sample name from subject",
23        "id": "00001020",
24        "lastUpdate": "2022-09-21T05:24:40.000+0000",
25        "resolutionDate": "2021-08-03T18:59:51.000+0000",
26        "ticketType": "Electrical",
27        "status": "Closed",
28        "priority": "Medium",
29        "creationDate": "2022-09-21T05:24:40.000+0000",
30        "href": "/services/apexrest/vlocity_cmt/tmforum/troubleticket/v57.0/troubleticket/00001020"
31    },
32    {
33        "channel": {
34            "@type": "Channel",
35            "name": "Phone"
36        },
37        "relatedParty": [
38            {
39                "@referredType": "Account",
40                "name": "United Oil & Gas Corp.",
41                "id": "001RO000003zz9WYAQ"
42            },
43            {
44                "@referredType": "Contact",
45                "name": "Stella Pavlova",
46                "id": "003RO00000366dAYAQ"
47            }
48        ],
49        "statusChangeDate": "2022-09-21T05:24:40.000Z",
50        "name": "sample name from subject",
51        "id": "00001021",
52        "lastUpdate": "2022-09-21T05:24:40.000+0000",
53        "resolutionDate": "2021-08-03T18:59:51.000+0000",
54        "ticketType": "Structural",
55        "status": "Closed",
56        "priority": "High",
57        "creationDate": "2022-09-21T05:24:40.000+0000",
58        "href": "/services/apexrest/vlocity_cmt/tmforum/troubleticket/v57.0/troubleticket/00001021"
59    }
60 ]

POST

Consider you want to create a new ticket.

Prerequisites These are the prerequisites for the POST operation.

These are mandatory fields. You need to specify the values for the following the mandatory fields.
- description
- ticketType
- severity
Define picklist values for CaseTroubleTicket.Severity and for the fields ticketType, status, priority, and origin in Case entity. The values passed for these attributes in post payload must be present in the system. These will not be validated.
The field CaseNumber is the unique identifier.
For Account/Contact/Asset, reference is their Salesforce ID.
Enable FLS read/edit for all the Case resource fields for the User Profile.

Sample URL

https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/data/v62.0/connect/comms/troubleticket/v5/troubleticket

Sample Request

1{
2    "name": "summer",
3    "ticketType": "Electrical",
4    "priority": "High",
5    "description": "Case description for testing",
6    "status": "Working",
7    "severity": "Critical",
8    "@type" : "troubleticket",
9    "externalIdentifier": [
10        {
11            "id": "External001"
12        }
13    ],
14    "channel": {
15        "name": "Web",
16        "id": "1"
17    },
18    "note": [
19        {
20            "author": "005xx000001X7q9AAC",
21            "text": "CaseComment 1",
22            "@type": "CaseComment"
23        },
24        {
25            "author": "005xx000001X7q9AAC",
26            "text": "CaseComment 2"
27        }
28    ],
29    "troubleTicketRelationship": [
30        {
31            "id": "00001002"
32        }
33    ],
34    "relatedParty": [
35        {
36            "role": "Customer - Direct",
37            "partyOrPartyRole": {
38                "id" : "001xx000003GYiGAAW",
39                "name": "United Oil &amp; Gas Corp.",
40                "@type": "PartyRef",
41                "@referredType": "Account"
42            },
43            "@type": "RelatedPartyRefOrPartyRoleRef"
44        },
45        {
46            "role": "Contact",
47            "partyOrPartyRole": {
48                "id" : "003xx000004WhFoAAK",
49                "name": "Rosa",
50                "@type": "PartyRef",
51                "@referredType": "Contact"
52            },
53            "@type": "RelatedPartyRefOrPartyRoleRef"
54        }
55    ],
56    "relatedEntity": [
57        {
58        "role": "Asset",
59        "@type": "RelatedEntity",
60        "entity":{
61            "id": "02ixx0000004HHiAAM",
62            "name": "test asset",
63            "@type": "EntityRef",
64            "@referredType": "Asset"
65            }
66        }
67    ],
68    "attachment": [
69        {
70            "description": "Scanned disputed bill",
71            "attachmentType": "billCopy",
72            "mimeType": "image/png",
73            "name": "March Bill",
74            "url": "https://mycsp.com:7070/docloader?docnum=3534555",
75            "@type": "AttachmentRef"
76        }
77    ]
78}

Sample Response

1201 created
2{
3    "id": "00001094",
4    "href": "/connect/comms/troubleticket/v5/troubleticket/00001094",
5    "name": "summer",
6    "ticketType": "Electrical",
7    "priority": "High",
8    "description": "Case description for testing",
9    "status": "Working",
10    "@type": "TroubleTicket",
11    "severity": "Critical",
12    "creationDate": "Mon Jul 15 06:56:23 GMT 2024",
13    "lastUpdate": "Mon Jul 15 06:56:23 GMT 2024",
14    "externalIdentifier": [
15        {
16            "id": "External001",
17            "@type": "ExternalIdentifier"
18        }
19    ],
20    "channel": {
21        "name": "Web",
22        "id": "1",
23        "@type": "ChannelRef"
24    },
25    "note": [
26        {
27            "author": "005xx000001X7q9AAC",
28            "text": "CaseComment 1",
29            "@type": "CaseComment"
30        },
31        {
32            "author": "005xx000001X7q9AAC",
33            "text": "CaseComment 2",
34            "@type": "CaseComment"
35        }
36    ],
37    "troubleTicketRelationship": [
38        {
39            "id": "00001002",
40            "href": "/connect/comms/troubleticket/v5/troubleticket/00001002",
41            "name": "Seeking guidance on electrical wiring installation for GC5060",
42            "relationshipType": "Parent",
43            "@type": "TroubleTicketRelationship"
44        }
45    ],
46    "relatedParty": [
47        {
48            "role": "Customer - Direct",
49            "partyOrPartyRole": {
50                "id": "001xx000003GYiGAAW",
51                "href": "/services/data/v60.0/sobjects/Account/001xx000003GYiGAAW",
52                "name": "United Oil &amp; Gas Corp.",
53                "@type": "PartyRef",
54                "@referredType": "Account"
55            },
56            "@type": "RelatedPartyRefOrPartyRoleRef"
57        },
58        {
59            "role": "Contact",
60            "partyOrPartyRole": {
61                "id": "003xx000004WhFoAAK",
62                "href": "/services/data/v60.0/sobjects/Contact/003xx000004WhFoAAK",
63                "name": "Rose Gonzalez",
64                "@type": "PartyRef",
65                "@referredType": "Contact"
66            },
67            "@type": "RelatedPartyRefOrPartyRoleRef"
68        }
69    ],
70    "relatedEntity": [
71        {
72            "role": "Asset",
73            "@type": "RelatedEntity",
74            "entity": {
75                "id": "02ixx0000004HHiAAM",
76                "href": "/services/data/v60.0/sobjects/Asset/02ixx0000004HHiAAM",
77                "name": "Test Asset",
78                "@type": "EntityRef",
79                "@referredType": "Asset"
80            }
81        }
82    ],
83    "attachment": [
84        {
85            "name": "March Bill",
86            "id": "069xx0000004DBYAA2",
87            "description": "Scanned disputed bill",
88            "attachmentType": "LINK",
89            "mimeType": "MimeType",
90            "url": "https://mycsp.com:7070/docloader?docnum=3534555",
91            "@type": "AttachmentRef"
92        }
93    ]
94}

DELETE

Consider you want to delete details of a particular trouble ticket.

Sample URL

https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/data/v62.0/connect/comms/troubleticket/v5/troubleticket/00001002

Sample Request

No request body.

Sample Response

Status code 204 with no response body