Note

 

This documentation supports the 20.19.02 version of BMC Helix Remedyforce.

To view the latest documentation, click here

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.

Remedyforce provides certain REST APIs related to service requests, knowledge articles, approvals, categories, user details, queues and CMDB classes. For the entire list of available APIs, see REST APIs provided by BMC Remedyforce. If you want to create other Remedyforce object records like incidents or tasks, you can use the REST API provided by the Salesforce platform. For more information about the REST APIs provided by the Salesforce platform, see the Salesforce Help .

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.

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

The following image shows how to obtain a session ID by using your cerendials.


Once 

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

Base URI for REST Resources


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

http://<domain>/services/apexrest/BMCServiceDesk/

Where,

<domain> is the fully qualified Salesforce instance name URL (na1.salesforce.com).

The following URL is used to call REST services:

http://na1.salesforce.com/services/apexrest/BMCServiceDesk/<action>

Where,

 <actioncan 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.

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 a service request/x.x/ServiceRequestUsed to create a service request.
Add attachment to a service request

/services/apexrest/BMCServiceDesk/1.0/ServiceRequest/<id>

Or

/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.
Reassign pending approval request/services/data/v30.0/sobjects/
ProcessInstanceWorkitem/{id}
Used to reassign a pending approval record.
Get Attributes for child CMDB class and parent class(s)

/services/apexrest/BMCServiceDesk/1.0/cmdb/getClassAttributes/{className}/all 

U sed to get attributes and details of the CMDB class and super classes in the hierarchy.
Get Attributes for specific CMDB class/services/apexrest/BMCServiceDesk/1.0/cmdb/getClassAttributes/{className}/ specific Used to get attributes and details of specific CMDB class.

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) – You can use the Developer Console or Workbench to execute a SOQL query on the User object and add filter on the Name field to get the client ID of a specific client.

    Note

    Client ID is the ID of the user for whom you are creating an incident.


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 from REST API",
    "OpenDateTime": "2018-09-11 04:23:00",
    "DueDateTime": "2018-09-12 04:23:00",
    "ClientId":  "0050Y000003hI9HQAU",
    "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 name of the object for which you want to get the the queue list. For example, if you want to get the queue list for incidents, the SObject will be BMCServiceDesk__Incident__c.

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}

For example,

/x.x/Queue/00G0Y000004tGy2UAE

HTTP Method

GET

Parameters

{Id} – The Salesforce ID of the queue record. To get the queue ID:

  • Use the Queues REST API call and select the required queue ID from the response body.
  • Use Developer Console or Workbench to execute a SOQL query on the Group object and add filter on the Type field.

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": "IT Queue",

     "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" : "HARDWARE FAQ"
}

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": "Test suman254",
                    "Solution": "Salesforce Platform Encryption gives data a new layer of security while preserving critical platform functionality.
It enables customers to encrypt sensitive data at rest, and not just when transmitted over a network so companies
can confidently comply with privacy policies, regulatory requirements, and contractual obligations for handling private data.",
                    "Problem": "What is SF Platform Encryption",
                    "ID": "a2j0Y000001JdzPQAS",
                    "CategoryName": "Network",
                    "CategoryId": "a260Y00000EmAFeQAN",
                    "ArticleType": "FAQ",
                    "ArticleId": "0120Y000000ypa2QAA"
                  },
         "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}

For example,

/x.x/KnowledgeArticle/a2j0Y000001JdzPQAS

HTTP Method

GET

Parameters

{Id} – The Salesforce ID of a Knowledge Article record. To get the knowledge article ID:

  • Use the Knowledge Search REST API call and select the required knowledge article ID from the response body.
  • Use Developer Console or Workbench to execute a SOQL query on the BMCServiceDesk__KM_KnowledgeArticle__c object and add filter on the Title field to get the required Knowledge Article ID.

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}

For example,

/x.x/servicerequest/a2h1v000001RHBbAAO

HTTP Method

GET

Parameters

{Id} – The Salesforce ID of a service request record. To get the service request ID:

  • Use the Get all service requests REST API call and select the required service request ID from the response body.
  • Use Developer Console or Workbench to execute a SOQL query on the BMCServiceDesk__Incident__c object and add filter on the Name field to get the required service request ID.

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. This value is in milliseconds.

{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. To obtain the service request IDs:

    • Use the Get all service requests REST API call and select the required service request IDs from the response body.

    • Use Developer Console to execute a SOQL query on the BMCServiceDesk__Incident__c object and add filter on the Name field to get the required service request IDs.

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":
    [
        "a2h1v000001RHBbAAO",
        "a3g0Y000000hVABQA2",
        "a2h1v000001RHCPAA4",
        "a2h1v000001RHC0AAO"
    ]
}


 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 a 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.

The API requires the following types of IDs:

  • Request Definition ID
  • Client ID

    Note

    Client ID is the ID of the user for whom you are creating a service request.

  • Question IDs

To obtain the request definition ID, use Developer Console or Workbench to execute a SOQL query on the BMCServiceDesk__SRM_RequestDefinition__c object and add filter on the Name field to get the ID of the required request definition.

The question IDs are the IDs of the Request Inputs that are added in the Inputs tab of a request definition under Remedyforce Administration > Configure Application > Request Definitions. To obtain the question IDs, use the Developer Console or Workbench to execute a SOQL query on the BMCServiceDesk__SRM_FulfillmentInputs__c object and add filter on the BMCServiceDesk__FKRequestDefinition__c field and apply filter of the required request deifnition.

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

Notes:

  • For the lookup input, you must enter the seperator ф between the display value and the Lookup ID.
  • For the date input, use the YYYY-MM-DD format.
  • For the datetime input, use the YYYY-MM-DD HH:MM:SS format.

Sample

Example request body
{
  "Fields": [
    {
      "Name": "requestDefinitionId",
      "Value": "a3g0Y000000hV9cQAE"
    } 
    {
      "Name": "client",
      "Value": "a3290000000Cmg7DSE"
    }
  ],
  "Answers": [
    {
      "QuestionId": "a3c0Y000000YqBYQA0",
      "Values": [ "Below are the details for the request" ]
    },
    {
      "QuestionId": "a3c0Y000000YqnzQAC", 
      "Values": [ true ]
    },
            {
      "QuestionId": "a3c0Y000000Yqo4QAC", // Date Input
      "Values": [ "2018-09-10" ]
    },
            {
      "QuestionId": "a3c0Y000000Yqo9QAC", // Date time Input
      "Values": [ "2018-09-11 04:23:00" ]
    },
            {
      "QuestionId": "a3c0Y000000YqoJQAS",
      "Values": [ "a0M0Y00000IfHciUAF" ] 
    }
            ,
            {
      "QuestionId": "a3c0Y000000YqoOQAS", // Number Input
      "Values": [ 5 ]
    },
            {
      "QuestionId": "a3c0Y000000YqoTQAS",
      "Values": [ "device1" ]
    },
            {
      "QuestionId": "a3c0Y000000YqoYQAS",
      "Values": [ "val1" ]
    },
            {
      "QuestionId": "a3c0Y000000YqodQAC",
      "Values": [ "Rich Test Data" ]
    },
            {
      "QuestionId": "a3c0Y000000YqoiQAC",
      "Values": [ "Test Field Data" ]
    },
            {
      "QuestionId": "a3c0Y000000YrGWQA0",
      "Values": [ "0050Y000003hI9HQAU" ]
   },
    {
      "QuestionId": "a3E1P0000011bGlUAI", // Picklist Input
      "Values": [ "iPhone" ]
    }{
      "QuestionId": "a3E1P0000011bH0UAI", // Radio Button Input
      "Values": ["BlackBerryOS"]
    },
    {
      "QuestionId": "a3E1P0000011WzZUAU", // Look up Input
      "Values": ["<Display Name>ф<Lookup ID>"]
    }  ]
}

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

/services/apexrest/BMCServiceDesk/1.0/ServiceRequest/<id>

HTTP Method

PUT

URIParameters

{id} –  Salesforce ID of an incident record.

Sample

Example request body

{ "attachment":

{

"Body":"<Blob>",

"ContentType": "image/jpg",

"Name": "picture.jpg"

}
}

Example response body

{

    "Attachment added: <Salesforce ID of the attachement> "

}

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 

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 

Get Attributes for child CMDB class and parent class(s)

Description

The API is used to get attributes and details of the CMDB class and super classes in the hierarchy.

URI

/x.x/cmdb/getClassAttributes/{className}/all 

For example,

/x.x/cmdb/getClassAttributes/{className}/all 

HTTP Method

GET

Parameters

{className}

To get the class name, use Developer Console or Workbench to execute a SOQL query on the BMCServiceDesk__CMDB_Class__c object and get the CMDB class name from BMCServiceDesk__ClassName__c field.

Data Types

Request

  • Body (Type: Map) – A map containing the class information and the attributes of the CMDB classes.

Response

  • classinfo (Type: Map) – Contains classes and attributes

Sample

Example request body

{

"classinfo":{

"BMC_BaseElement":{

"attributes":{

"CITag":{

"limits":{

"max_length":254

},

"required":false,

"datatype":"STRING",

"name":"BMCServiceDesk__CITag__c"

},

"Name":{

"limits":{

"max_length":254

},

"required":true,

"datatype":"STRING",

"name":"BMCServiceDesk__Name__c"

}

},

"salesforceid":"<SalesforceId>",

"classtype":"Class",

"derivedfrom":"",

"classid":"BMC_ASSETBASE",

"name":"BMC_BaseElement"

}

}

}

Back to top 

Get Attributes for specific CMDB class

Description

The API is used to get attributes and details of specific CMDB class.

URI

/x.x/cmdb/getClassAttributes/{className}/specific

HTTP Method

GET

Parameters

{className}

To get the CMDB class name, use Developer Console or Workbench to execute a SOQL query on the BMCServiceDesk__CMDB_Class__c object and get the CMDB class name from the BMCServiceDesk__ClassName__c field.


Data Types

Response

  • classinfo (Type: Map) – Contains classes and attributes

Sample

Example response body

{

"classinfo":{

"BMC_BaseElement":{

"attributes":{

"CITag":{

"limits":{

"max_length":254

},

"required":false,

"datatype":"STRING",

"name":"BMCServiceDesk__CITag__c"

},

"Name":{

"limits":{

"max_length":254

},

"required":true,

"datatype":"STRING",

"name":"BMCServiceDesk__Name__c"

}

},

"salesforceid":"<SalesforceId>",

"classtype":"Class",

"derivedfrom":"",

"classid":"BMC_ASSETBASE",

"name":"BMC_BaseElement"

}

}

}

Back to top 


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

Comments