Note

 

This documentation supports the 20.16.01 version of BMC Remedyforce.

To view the latest or an earlier version, select the version from the Product version menu.

Remedyforce REST API

Web services use REST APIs to send and receive information. This topic provides information on the Remedyforce REST APIs that you can use.

REST APIs

The Representational State Transfer (REST) is a software architecture style that consists of guidelines and best practices for creating scalable web services. RESTful systems typically communicate over the Hypertext Transfer Protocol (HTTP) with the same HTTP verbs (GET, POST, PUT, DELETE, etc.) that are used by web browsers to retrieve web pages and send data to remote servers. The advantage of REST is having a limited number of operations for the interactions between clients and services.

An Application Programming Interface (API) is a web service that conforms to the architectural principles of REST. Each API is called by issuing a standard HTTP request method (POST, GET, PUT, or DELETE), more commonly known as the CRUD operations (Create, Read, Update, and Delete).

The client creates new instances by issuing POST requests. The details of an individual instance or list of instances is retrieved using a GET request. The client issues PUT requests to modify an instance object. When an instance object is no longer needed, the client issues a DELETE request to remove an instance.

Base URI for REST Resources

A REST API uses the following base URL for calling the REST services:

http://domain/services/apexrest/BMCServiceDesk/

In the above URL, domain is the fully qualified Salesforce instance name URL (na1.salesforce.com).

The URL that is used to call REST services is http://na1.salesforce.com/services/apexrest/BMCServiceDesk/{ACTION}

In the above URL, ACTION can be any one of the URI values from the following table of APIs that are used in BMC Remedyforce.

Note

The current available API version is 1.0. Replace instances of x.x in the table with the one in the URI when you call the REST services.

Prerequisites for calling APIs

A Session ID is required to successfully call any of the Salesforce or Remedyforce REST APIs. To obtain the Salesforce Session ID that uses username and password, you must use Salesforce SOAP API.

The following table provides the SOAP APIs:

Endpoint URLIf you are integrating with the Salesforce Production organization, Endpoint for login call is https://login.salesforce.com/services/Soap/u/35.0 and when you are integrating with the Salesforce Sandbox organization, the Endpoint for login call is https://test.salesforce.com/services/Soap/u/35.0
Body

<?xml version="1.0" encoding="utf-8" ?>

<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema"

    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

    xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">

  <env:Body>

    <n1:login xmlns:n1="urn:partner.soap.sforce.com">

      <n1:username>your_username</n1:username>

      <n1:password>your_password</n1:password>

    </n1:login>

  </env:Body>

</env:Envelope>

SoapActionLogin
Content-TypeText/xml

While making the REST API calls, the Request header needs to be set for Authorization: Bearer {sessionId}.

REST APIs provided by BMC Remedyforce

Details of the APIs provided by Remedyforce such as URI, description, HTTP method, parameters to be used, and the data types of the REST APIs are given below. A sample for each API is also provided.

Resource Name

URI

Description

Version

/x.x/ServiceUtil/Version

Used to get the version of the installed Remedyforce package.

User detail

/x.x/ServiceUtil/UserDetail

Used to get information about the logged-in user.

Categories

/x.x/Category

Used to provide the Remedyforce category list.

Create incident

/x.x/Incident

Used to create an incident.

Queues

/x.x/Queue/{Sobject}

Used to get all queues for the Sobject.

Queue details

/x.x/Queue/{id}

Used to get information of a particular queue.

Knowledge search

/x.x/KnowledgeSearch

Used to provide the search feature for knowledge articles.

All knowledge articles

/x.x/KnowledgeArticle

Used to get all knowledge articles.

Knowledge article details

/x.x/KnowledgeArticle/{Id}

Used to get details of the specific knowledge article with ID.

Get all service requests

/x.x/ServiceRequest

Used to get all service request operations.

Get service request details

/x.x/ServiceRequest/{id}

Used to get details of a specific service request with ID.

Query service request

/x.x/ServiceRequest?query={query}&date={date}
&batchSize={batchsize}

Used to get a service request as per the queries.

Query service request by array of IDs

/x.x/ServiceRequest/Query

Used to get service request details by array of IDs.

Create service request/x.x/ServiceRequestUsed to create a service request.
Add attachment to a service request/x.x/ServiceRequest/{id}?filename={filename}Used to create a new attachment to a service request.
/x.x/ServiceRequest/{id}/clientnoteUsed to create a new client note to a service request.
Get pending approval request/x.x/ApprovalUsed to get a pending approval request for the current user.

/services/data/v30.0/process/approvals

Used to approve a pending approval record.

Reject pending approval request/services/data/v30.0/process/approvalsUsed to reject a pending approval record.
Reassign pending approval request/services/data/v30.0/sobjects/
ProcessInstanceWorkitem/{id}
Used to reassign a pending approval record.

Version

Description

This API is used to get the version of installed BMC Remedyforce package.

URI

/x.x/ServiceUtil/Version

HTTP Method

GET

Parameters

Not required

Data Types

Response

  • Success (Type: Boolean) – Result of an operation
  • Result (Type: String) – A JSON string
  • ErrorMessage (Type: String) – An error and exception message that is shown if there is a failure
  • ErrorCode (Type: String) – Reserved for future use

Sample

Example request body

Not required

Example response body

{

    "Success": ,

    "Result": "{"Version":"201501.14.0"}",

    "ErrorMessage": "null",

    "ErrorCode": "null"

}

Back to top

User detail

Description

This API is used to get the details of the logged-in user. It returns information if the logged-in user is either a System Administrator or if Remedyforce Administrator check box is checked for user or not.

URI

/x.x/ServiceUtil/UserDetail

HTTP Method

GET

Parameters

None required

Data Types

Response

  • Success (Type: Boolean) – Result of an operation
  • Result (Type: String) – JSON string
  • ErrorMessage (Type: String) – An error and exception message that is shown if there is a failure
  • ErrorCode (Type: String) – Reserved for future use

Sample

Example request body

Not required

Example response body

{

    "Success": "true",

    "Result":"{"IsAdminUser":"true"}",

    "ErrorMessage":"null",

    "ErrorCode":"null"

}

Back to top

Categories

Description

This API is used to get BMC Remedyforce categories. It returns an array of categories. It returns only the active categories that are available for the service catalog or have children that are available for the service catalog.

URI

/x.x/Category

HTTP Method

GET

Parameters

None required

Data Types

Response

  • Success (Type: Boolean) – Result of an operation
  • Result (Type: {Category[ ]) – JSON array of type Category
  • ErrorMessage (Type: String) – An error and an exception message that is shown if there is a failure
  • ErrorCode (Type: String) – Reserved for future use

Sample

Example request body

Not required

Example response body

{

    "Success": "true",

    "ErrorCode": "",

    "ErrorMessage": "",

    "Result":

    [

        {

            "Id": "a2c90000002A7pe",

            "ParentId": "a2c90000001c7pe",

            "Name": "Test Category"

        }

    ]

}

Back to top

Create incident

Description

This API is used to create a BMC Remedyforce incident.

URI

/x.x/Incident

HTTP Method

POST

Parameters

Not required

Data Types

Request

  • Description (Type: String) – Description of an incident
  • OpenDateTime (Type: DateTime) – JSON DateTime for opened date of an incident
  • DueDateTime (Type: String) – JSON DateTime for due date of an incident
  • ClientId (Type: String) – Reserved for future use

Response

  • Success (Type: Boolean) – Result of an operation
  • Result (Type: IncidentInfo[ ]) – JSON array of type Category
  • ErrorMessage (Type: String) – An error and an exception message that is shown if there is a failure
  • ErrorCode (Type: String) – Reserved for future use

Sample

Example request body

{

    "Description": "Test Incident",

    "OpenDateTime": "",

    "DueDateTime": "",

    "ClientId":  "",

    "IncidentSource": "Source"

}

Example response body

{

    "Success": "true",

    "ErrorCode": "",

    "ErrorMessage": ""

    "Result": {

        "Id": "a2c90000002A7pe",

        "Number": "00078973"

    }

}

Back to top

Queues

Description

This API is used to get queues related to specific Salesforce object type.

URI

/x.x/Queue/{SObject}

HTTP Method

GET

Parameters

{SObject} – The API Name of a Salesforce object.

Data Types

Response

  • Success (Type: Boolean) – Result of an operation
  • Result (Type: Queue[ ]) – JSON array of type Queue
  • ErrorMessage (Type: String) – An error and an exception message that is shown if there is a failure
  • ErrorCode (Type: String) – Reserved for future use

Sample

Example request body

Not required

Example response body

{

  "Success": "true",

  "Result": [

    {

      "Organization": "null",

      "Name": "Test Incident",

      "ModifiedDate": "2013-06-26 13:33:06",

      "Id": "00G90000001FN8YEAW",

      "CreatedDate": "2013-06-26 13:33:06",

      "Company": "null"

    }

  ],

  "ErrorMessage": "null",

  "ErrorCode": "null"

}

Back to top

Queue details

Description

This API is used to get details of the queue.

URI

/x.x/Queue/{Id}

HTTP Method

GET

Parameters

{Id} – The Salesforce ID of a Queue record

Data Types

Response

  • Success (Type: Boolean) – Result of an operation
  • Result (Type: Queue) – Information of type Queue
  • ErrorMessage (Type: String) – An error and an exception message that is shown if there is a failure
  • ErrorCode (Type: String) – Reserved for future use

Sample

Example request body

Not required

Example response body

{

    "Success": "true",

    "Result": {

    "Organization": "null",

    "Name": "Test Incident",

    "ModifiedDate": "2013-06-26 13:33:06",

    "Id": "00G90000001FN8YEAW",

    "CreatedDate": "2013-06-26 13:33:06",

    "Company": "null"

    },

    "ErrorMessage": "null",

    "ErrorCode": "null"

}

Back to top

Knowledge search

Description

This API is used to search BMC Remedyforce knowledge articles and service request definitions with a search string. Only those knowledge articles that are visible in Self Service are published and returned. The service requests that are checked for mobile are returned.

URI

/x.x/knowledgesearch

HTTP Method

POST

Parameters

None required

Data Types

Request

  • SearchString (Type: String) – Keywords used to search information in the knowledge articles

Response

  • Success (Type: Boolean) – Result of an operation
  • Result (Type: Map) – A map with two values, KAList and SRDList. KAList is an array of KA object type and SRDList is an array of SRD object type.
  • ErrorMessage (Type: String) – An error and an exception message that is shown if there is a failure
  • ErrorCode (Type: String) – Reserved for future use

Sample

Example request body

{

    "SearchString" : <String>

}

Example response body

{

  "Success": "true",

  "Result": {

    "SRDList": [

      {

        "Name": "New Hire Request",

        "Id": "a3290000000GzECAA0",

        "CategoryName": "Account Administration",

        "CategoryId": "a1z90000000LdZyAAK"

      }

    ],

    "KAList": [

      {

        "Title": "Sent: Tue, 3 Sep 2013 02:29:17",

        "ID": "a2O90000000PSZzEAO",

        "CategoryName": "Applications",

        "CategoryId": "a1z90000000LdZzAAK",

        "ArticleType": "FAQ"

      }

    ]

  },

  "ErrorMessage": "null",

  "ErrorCode": "null"

}

Back to top

All knowledge articles

Description

It is used to get all knowledge articles. Only knowledge articles that are visible in Self Service are published. Account-specific settings that are configured in BMC Remedyforce are fulfilled.

URI

/x.x/KnowledgeArticle

HTTP Method

GET

Parameters

None required

Data Types

Response

  • Success (Type: Boolean) – Result of an operation
  • Result (Type: KnowledgeArticle[ ]) – An array of type Knowledge Articles
  • ErrorMessage (Type: String) – An error and an exception message that is shown if there is a failure
  • ErrorCode (Type: String) – Reserved for future use

Sample

Example request body

Not Required

Example response body

{

  "Success": "true",

  "Result": [

    {

      "Title": "Sent: Tue, 3 Sep 2013 02:29:17",

      "ID": "a2O90000000PSaFEAW",

      "CategoryName": "Applications",

      "CategoryId": "a1z90000000LdZzAAK",

      "ArticleType": "Problem Solution"

    },

    {

      "Title": "Sent: Tue, 3 Sep 2013 02:29:17",

      "ID": "a2O90000000PSZzEAO",

      "CategoryName": "Applications",

      "CategoryId": "a1z90000000LdZzAAK",

      "ArticleType": "FAQ"

    }

  ],

  "ErrorMessage": "null",

  "ErrorCode": "null"

}

Back to top

Knowledge article details

Description

It is used to get the knowledge article details by its ID. Details are returned only if knowledge articles are visible in Self Service and are published.

URI

/x.x/KnowledgeArticle/{Id}

HTTP Method

GET

Parameters

{Id} – The Salesforce ID of a Knowledge Article record

Data Types

Response

  • Success (Type: Boolean) – Result of an operation.
  • Result (Type: KnowledgeArticleDetail[ ]) – An instance of Knowledge Article Detail
  • ErrorMessage (Type: String) – An error and an exception message that is shown if there is a failure
  • ErrorCode (Type: String) – Reserved for future use

Sample

Example request body

Not Required

Example response body

{

    "Success": "true",

    "Result": {

        "Title": add actual sample data from OOTB

        "Solution": <string>,

        "Problem": <string>,

        "ID": "a2O90000000PSaFEAW",

        "CategoryName": "Applications",

        "CategoryId": "a1z90000000LdZzAAK",

        "ArticleType": "Problem Solution"

    },

    "ErrorMessage": "null",

    "ErrorCode": "null"

}

Back to top

Get all service requests

Description

This API is used to get the latest 200 service requests. It returns only those service requests that are ordered by the date they are created.

URI

/x.x/ServiceRequest

HTTP Method

GET

Parameters

Not required

Data Types

Response

  • Success (Type: Boolean) – Result of an operation
  • Result (Type: ServiceRequest[ ]) – An array of type ServiceRequest
  • ErrorMessage (Type: String) – An error and an exception message that is shown if there is a failure
  • ErrorCode (Type: String) – Reserved for future use

Sample

Example request body

Not Required

Example response body

{

    "Success": "true",

    "ErrorCode": "null",

    "ErrorMessage": "null",

    "Result":

    [

        {

            "Id": "a2c90000002A7pe",

            "CategoryId" : "a9k90000002A7pe",

            "Name": "Service Request",

            "SRDId": "a2490000002A7pe",

            "Fields":

            [

                {

                    "Name": "Unit__c",

                    "Type": "Number",

                    "Value": "2",

                    "Editable": "false"

                }

            ],

            "Answers":

            [

                {

                    "Id": "a289000002A7pe"

                    "QuestionId": "a29900000980spe"

                    "Type": "Text",

                    "Values": "Test"

                }

            ]

            "LastModifiedDate": "2015-10-09 09:11:12", "CreatedDate" : "2015-10-08 08:13:10"

        }

    ]

}

Back to top

Get service request details

Description

This API is used to get details of a particular service request.

URI

/x.x/servicerequest/{Id}

HTTP Method

GET

Parameters

{Id} – The Salesforce ID of a knowledge article record

Data Types

Response

  • Success (Type: Boolean) – Result of an operation
  • Result (Type: ServiceRequest[ ]) – An array of type ServiceRequest
  • ErrorMessage (Type: String) – An error and an exception message that is shown if there is a failure
  • ErrorCode (Type: String) – Reserved for future use

Sample

Example request body

Not Required

Example response body

{

  "Success": "true",

  "ErrorCode": "null",

  "ErrorMessage": "null",

  "Result":

    {

      "Id": "a2c90000002A7pe",

      "CategoryId": "a9k90000002A7pe",

      "Name": "ServiceRequest",

      "SRDId": "a2490000002A7pe",

      "Fields": [

        {

          "Name": "Unit__c",

          "Type": "Number",

          "Value": "2",

          "Editable": "false"

        }

      ],

      "Answers": [

        {

          "Id": "a289000002A7pe",

          "QuestionId": "a29900000980spe",

          "Type": "Text",

          "Values": "Test",

          "LastModifiedDate": "2015-10-09 09:11:12",

          "CreatedDate": "2015-10-08 08:13:10"

        }

      ]

    }

}

Back to top

Query service request

Description

This API is used to get the latest 200 service requests. It returns only those service requests that are linked with active incidents ordered by the date they are created and fulfill the additional query parameters.

URI

/x.x/ServiceRequest?query={query}&date={date}&batchSize={batchsize}

HTTP Method

GET

Parameters

{query}  MYIT_ALL_SRS_CREATED_BEFORE | MYIT_ALL_SRS_MODIFIED_BEFORE | MYIT_ALL_SRS_MODIFIED_AFTER <{date}> value

{date} – Provides the date value for the query parameter format: yyyy-MM-dd HH:mm:ss GMT

{batchsize} – The number of records to be returned (maximum value is 200)

Data Types

Response

  • Success (Type: Boolean) – Result of an operation
  • Result (Type: ServiceRequest[ ]) – An array of type ServiceRequest
  • ErrorMessage (Type: String) – An error and an exception message that is shown if there is a failure
  • ErrorCode (Type: String) – Reserved for future use

Sample

Example request body

Not Required

Example response body

{

  "Success": "true",

  "ErrorCode": "null",

  "ErrorMessage": "null",

  "Result": [

    {

      "Id": "a2c90000002A7pe",

      "CategoryId": "a9k90000002A7pe",

      "Name": "ServiceRequest",

      "SRDId": "a2490000002A7pe",

      "Fields": [

        {

          "Name": "Unit__c",

          "Type": "Number",

          "Value": "2",

          "Editable": "false"

        }

      ],

      "Answers": [

        {

          "Id": "a289000002A7pe",

          "QuestionId": "a29900000980spe",

          "Type": "Text",

          "Values": "Test",

          "LastModifiedDate": "2015-10-09 09:11:12",

          "CreatedDate": "2015-10-08 08:13:10"

        }

      ]

    }

  ]

}

Back to top

Query service request by array of IDs

Description

This API is used to get a service request as an array of IDs.

URI

/x.x/ServiceRequest/Query

HTTP Method

POST

Parameters

None required

Data Types

Request

  • SRIds (Type: String[ ]) – An array of IDs for incidents of type ServiceRequest

Response

  • Success (Type: Boolean) – Result of an operation
  • Result (Type: ServiceRequest[ ]) – An array of type ServiceRequest
  • ErrorMessage (Type: String) – An error and an exception message that is shown if there is a failure
  • ErrorCode (Type: String) – Reserved for future use

Sample

Example request body

{

    "SRids":

    [

        "a2M90000001dJVr",

        "a2M90000001OIyf"

    ]

}

 Example response body

{

  "Success": "true",

  "Result": [

    {

      "ActivityLog": [

      ],

      "Id": "a2M90000001dJVrEAM",

      "Answers": [

        {

          "QuestionId": "a2y90000000Gs1VAAS",

          "Id": "a3390000000Qd6GAAS",

          "LastModifiedDate": "2014-12-11 12:18:06",

          "CreatedDate": "2014-12-11 12:18:06",

          "Type": "textfield",

          "QuestionText": "Location",

          "Text": "Pune",

          "Values": "Pune"

        },

        {

          "QuestionId": "a2y90000000HBsYAAW",

          "Id": "a3390000000Qd6HAAS",

          "LastModifiedDate": "2014-12-11 12:18:06",

          "CreatedDate": "2014-12-11 12:18:06",

          "Type": "number",

          "QuestionText": "Extension",

          "Text": "1234",

          "Values": "1234"

        },

        {

          "QuestionId": "a2y90000000PN3fAAG",

          "Id": "a3390000000Qd6IAAS",

          "LastModifiedDate": "2014-12-11 12:18:06",

          "CreatedDate": "2014-12-11 12:18:06",

          "Type": "checkbox",

          "QuestionText": "Test Checkbox",

          "Text": "true",

          "Values": "true"

        },

        {

          "QuestionId": "a2y90000000POVbAAO",

          "Id": "a3390000000Qd6JAAS",

          "LastModifiedDate": "2014-12-11 12:18:06",

          "CreatedDate": "2014-12-11 12:18:06",

          "Type": "picklist",

          "QuestionText": "Picklist",

          "Text": "One",

          "Values": "1"

        },

        {

          "QuestionId": "a2y90000000POVgAAO",

          "Id": "a3390000000Qd6KAAS",

          "LastModifiedDate": "2014-12-11 12:18:06",

          "CreatedDate": "2014-12-11 12:18:06",

          "Type": "radiobutton",

          "QuestionText": "Radio Button",

          "Text": "2",

          "Values": "Two"

        }

      ],

      "SRDId": "a3290000000GzECAA0",

      "Fields": [

        {

          "Type": "textfield",

          "Value": "1234567891",

          "Editable": "false",

          "Name": "phone"

        },

        {

          "Type": "textfield",

          "Value": "null",

          "Editable": "false",

          "Name": "dateRequired"

        },

        {

          "Type": "date\/time",

          "Value": "2014-12-11 12:17:44",

          "Editable": "false",

          "Name": "dateExpected"

        },

        {

          "Type": "textfield",

          "Value": "prasanna_deshpande@bmc.com",

          "Editable": "false",

          "Name": "email"

      ],

      "CategoryId": "a1z90000000LdZyAAK",

      "Name": "00010818"

    },

    {

      "ActivityLog": [

        {

          "WorkInfoType": "null",

          "ViewAccess": "null",

          "Summary": "Client Note",

          "Submitter": "Prasu Deshpande",

          "srId": "a2M90000001OIyfEAG",

          "Notes": "null",

          "ModifiedDate": "2014-12-31 07:43:20",

          "Id": "a2G90000000MAEUEA4",

          "CreatedDate": "2014-12-31 07:43:20"

        },

        {

          "WorkInfoType": "null",

          "ViewAccess": "null",

          "Summary": "Notes",

          "Submitter": "Prasu Deshpande",

          "srId": "a2M90000001OIyfEAG",

          "Notes": "test",

          "ModifiedDate": "2014-12-31 07:42:58",

          "Id": "a2G90000000MAEPEA4",

          "CreatedDate": "2014-12-31 07:42:56"

        }

      ],

      "Id": "a2M90000001OIyfEAG",

      "Answers": [

        {

          "QuestionId": "a2y90000000Gs1VAAS",

          "Id": "a3390000000QFbMAAW",

          "LastModifiedDate": "2014-10-27 09:06:46",

          "CreatedDate": "2014-10-27 09:06:46",

          "Type": "textfield",

          "QuestionText": "Location",

          "Text": "London",

          "Values": "London"

        },

        {

          "QuestionId": "a2y90000000HBsYAAW",

          "Id": "a3390000000QFbNAAW",

          "LastModifiedDate": "2014-10-27 09:06:46",

          "CreatedDate": "2014-10-27 09:06:46",

          "Type": "number",

          "QuestionText": "Extension",

          "Text": "234",

          "Values": "234"

        },

        {

          "QuestionId": "a2y90000000PN3fAAG",

          "Id": "a3390000000QFbOAAW",

          "LastModifiedDate": "2014-10-27 09:06:46",

          "CreatedDate": "2014-10-27 09:06:46",

          "Type": "checkbox",

          "QuestionText": "Test Checkbox",

          "Text": "true",

          "Values": "true"

        }

      ],

      "SRDId": "a3290000000GzECAA0",

      "Fields": [

        {

          "Type": "textfield",

          "Value": "1234567891",

          "Editable": "false",

          "Name": "phone"

        },

        {

          "Type": "textfield",

          "Value": "2014-10-31 09:05:00",

          "Editable": "false",

          "Name": "dateRequired"

        },

        {

          "Type": "date\/time",

          "Value": "2014-10-27 09:06:59",

          "Editable": "false",

          "Name": "dateExpected"

        },

        {

          "Type": "textfield",

          "Value": "prasanna_deshpande@bmc.com",

          "Editable": "false",

          "Name": "email"

        },

        {

          "Type": "textfield",

          "Value": "Prasu Deshpande",

          "Editable": "false",

          "Name": "requestedBy"

        }       

      ],

      "CategoryId": "a1z90000000LdZyAAK",

      "Name": "00010816"

    }

  ],

  "ErrorMessage": "null",

  "ErrorCode": "null"

}

Back to top

Create service request

Description

This API is used to create a service request.

URI

/x.x/ServiceRequest

HTTP Method

POST

Parameters

None required

Data Types

Request

  • Body (Type: Map) – A map with two values—Fields and Answers. Fields is an array of Field object type and Answers is an array of Answer object type.

Response

  • Success (Type: Boolean) – Result of an operation
  • Result (Type: ServiceRequestInformation) – Information of a service request
  • ErrorMessage (Type: String) – An error and an exception message that is shown if there is a failure
  • ErrorCode (Type: String) – Reserved for future use

Sample

Example request body

{

  "Fields": [

    {

      "Name": "requestDefinitionId",

      "Value": "a3290000000Cmg9AAC"

    }

  ],

  "Answers": [

    {

      "QuestionId": "a3290000000Cmg9AAC",

      "Values": [ "test" ]

    }

  ]

}

Example response body

{

    "Success" : "true"

    "ErrorCode" : "",

    "ErrorMessage" : ""

    "Result" : {

        "Id": "a2O90000000PSaFEAW",

        "Number": "0005674"

    }

}

Back to top

Add attachment to a service request

Description

This API is used to create a new attachment to a service request.

URI

/x.x/ServiceRequest/{id}?filename={filename}

HTTP Method

PUT

Parameters

{id} –  Salesforce ID of an incident record.

{filename} – Name of a file to be attached.

Data Types

Request

  • Body (Type: BLOB value) – These are the contents of the file to be attached.

Response

  • (Type: String) – This is an attachment added to the record with an ID

Sample

Example request body

{

    Blob value

}

Example response body

{

    "Attachment added"

}

Back to top

Add client note to a service request

Description

This API is used to create a new client note for a service request.

URI

/x.x/ServiceRequest/{id}/clientnote

HTTP Method

POST

Parameters

{id} – Salesforce ID of an incident record.

Data Types

Request

  • Body (Type: map) – A map containing ActivityLog. ActivityLog has an array of ActivityLog object type as value.

Response

  • Success (Type: Boolean) – Result of an operation
  • Result (Type: Note Info) – Information of a note
  • ErrorMessage (Type: String) – An error and exception message that is shown if there is a failure
  • ErrorCode (Type: String) – Reserved for future use

Sample

Example request body

{

    "ActivityLog":

    [

        {

            "Summary": "Client Note",

            "Notes": "This is test note"          

        }

    ]

}

Example response body

{

    "Success": "true"

    "ErrorCode": "",

    "ErrorMessage": ""

    "Result":

    {

        "ActivityLog":

        [

            "WorkInfoType": "null"

            "ViewAccess":"null"

            "Summary": "Client Note"

            "Submitter":" Abhishek Kulkarni"

            "srId": "a2O90000000k3xBEAQ"

            "Notes": "this is test note via REST API"

            "ModifiedDate": "2015-04-09 14:16:03"

            "Id": "a2H90000000LlpCEAS"

            "CreatedDate": "2015-04-09 14:16:03"

        ]

    }

}

Back to top

Get pending approval request

Description

This API is used to get a pending approval request for the current user.

URI

/x.x/Approval

HTTP Method

GET

Parameters

None required

Data Types

Response

  • Success (Type: Boolean) – Result of an operation.
  • Result (Type: ProcessInstanceWorkitem[ ]) – An array of type ProcessInstanceWorkitem.
  • ErrorMessage (Type: String) – An error and exception message that is shown if there is a failure.
  • ErrorCode (Type: String) – Reserved for future use.

Sample

{
    "Success":"true"
    "ErrorCode":"",
    "ErrorMessage":""
    "Result":
    [        
        {
            "RelatedRecordLink": "https://ap1.salesforce.com/a2O90000000k52oEAA",
            "Submitter":"Abhishek Kulkarni",
            "AssignedTo":"abhi1 kulk",
            "Id": "04i90000007Y6fyAAC",
            "Type":"Incident",
            "RelatedId":"a2O90000000k52oEAA",
            "Submitted Date":"2015-04-06 11:55:41",
            "RelatedTo":"00078287",
            "Status":"Pending"               
        }
    ]
}

Back to top

Approve pending approval request

Description

This API is used to approve a pending approval record.

URI

/services/data/v30.0/process/approvals

HTTP Method

POST

Parameters

None required

Data Types

Request

  • Body (Type: Map) – A map containing approval requests with Action type as Approve and contextId as approval record Id(s). The fields, nextApproverIds and comments are optional.

Response

  • Success (Type: Boolean) – Result of an operation
  • instanceId (Type: ID) – Record ID to which the approval is related
  • instanceStatus (Type: String) – Status of the current instance

Sample

Example request body

{

    "requests":

    [

        {

            "actionType":"Approve",

            "contextId":"04iD0000000Cw6SIAS",

            "nextApproverIds":["005D00000015rY9"],

            "comments":"This record is approved"

        }

    ]

}

Example response body

[

    {

        "actorIds": "null",

        "entityId": "001D000000I8mImIAJ",

        "errors": "null",

        "instanceId": "04gD0000000CvmAIAS",

        "instanceStatus": "Approved",

        "newWorkitemIds": [ ],

        "success": "true"

    }

]

Back to top

Reject pending approval request

Description

This API is used to reject a pending approval record.

URI

/services/data/v30.0/process/approvals

HTTP Method

POST

Parameters

None required

Data Types

Request

  • Body (Type: Map) – A map containing approval requests with action type as reject and contextId as approval record Id(s). The fields, nextApproverIds and comments are optional.

Response

  • Success (Type: Boolean) – Result of an operation
  • instanceId (Type: ID) – Record ID to which the approval is related
  • instanceStatus (Type: String) – Status of the current instance

Sample

Example request body

{

    "requests":

    [

        {

            "actionType":"Reject",

            "contextId":"04iD0000000Cw6cIAC",

            "comments":"This record is rejected"

        }

    ]

}

Example response body

[

    {

        "actorIds": "null",

        "entityId": "001D000000I8mImIAJ",

        "errors": "null",

        "instanceId": "04gD0000000CvmAIAS",

        "instanceStatus": "Rejected",

        "newWorkitemIds": [ ],

        "success": "true"

    }

]

Back to top

Reassign pending approval request

Description

This API is used to reassign a pending approval record.

URI

/services/data/v30.0/sobjects/ProcessInstanceWorkitem/{id}

HTTP Method

PATCH

Parameters

{Id} – Salesforce ID of a ProcessInstanceWorkitem record.

Data Types

Request

  • Body (Type: Map) – A map containing ActorId. ActorId has the UserId of a user to whom the approval request has to be assigned as a value.

Response

Not Required

Sample

Example request body

{

    "ActorId" : "00590000002GijH"

}

Example response body

Not Required

Back to top

Complex data types

The following table categorizes and describes the complex data types that are used to exchange information using the APIs:

NameDate typeDescription
Service request information
IdSalesforce IDThis is the Salesforce ID of a newly created request.
NumberStringThis is the incident or the service request number.
Fields
NameStringThis is the field name.
TypeStringThis is the data type of the field.
ValueStringThis is the field value.
EditableBooleanThis indicates whether the field is editable or not.
Answers
IdSalesforce IDThis is the Salesforce ID of a fulfillment input answer record.
Question IdSalesforce IDThis is the Salesforce ID of a fulfillment input.
TypeString

This is the type of input.

The supported types are:

  • checkbox
  • textarea
  • textfield (same as string)
  • radiobutton
  • date
  • date/time
  • number
  • picklist

Values

String

These are answers.

CreatedDate

DateTime

This is the date of creation of the record.

LastModifiedDate

DateTime

This is the last modified date of the record.

Service request

Id

Salesforce ID

This is the Salesforce ID for a service request or an incident.

Name

String

This is the service request or incident number.

CategoryID

Salesforce ID

This is the ID of a category of a service request or an incident.

SRDid

Salesforce ID

This is the Salesforce ID of a service request definition.

Fields

Field[ ]

This is the array of fields related to a service request or an incident.

Answers

Answer[ ]

This is the array of fulfillment input for a service request or an incident.

Category

Id

Salesforce ID

This is the Salesforce ID of a category.

Name

String

This is the name of a category

ParentId

Salesforce ID

This is the ID of a category of an incident.

Description

String

This is the description of a category.
Queue

Organization

String

This is reserved for future use.

Name

String

This is a name of a queue

ModifiedDate

DateTime

This is the last modified date of a queue.

CreatedDate

DateTime

This is the date a queue is created.

Company

String

This is reserved for future use.

Id

Salesforce ID

This is the Salesforce ID of a queue.

Service request definition

Name

String

This is the name of a service request definition.

Id

Salesforce ID

This is the Salesforce ID of a service request definition.

CategoryName

String

This is the name of category of a service request definition.

CategoryId

Salesforce ID

This is the Salesforce ID of a category.

Name

Name

String

This is the name of a service request definition.

Id

Salesforce ID

This is the Salesforce ID of a service request definition.

CategoryName

String

This is the name of category of a service request definition.

CategoryId

Salesforce ID

This is the Salesforce ID of a category.

Knowledge article

Title

String

This is the title of a knowledge article.

Id

Salesforce ID

This is the Salesforce ID of a knowledge article.

CategoryName

String

This is the name of category of a service request definition.

CategoryId

Salesforce ID

This is the Salesforce ID of a category.

ArticleType

String

This is the type of a knowledge article.
Knowledge article detail

Title

String

This is the title of a knowledge article.

Id

Salesforce ID

This is the Salesforce ID of a knowledge article.

CategoryName

String

This is the name of category of a service request definition.

CategoryId

Salesforce ID

This is the Salesforce ID of a category.

ArticleType

String

This is the type of a knowledge article.

Problem

String

This is the problem related to a knowledge article.

Solution

String

This is the solution to the problem related to a knowledge article.

Activity log

Summary

String

This is a summary of a client note.

Notes

String

This is a note for a client.

Back to top

Was this page helpful? Yes No Submitting... Thank you

Comments