Troubleshooting issues when publishing REST API services


You can publish REST services by using the AR System server REST API. The REST API uses dedicated Java Server Pages (JSP) Engine Jetty, which is integrated with AR System server as a single process.

All REST API calls must be authenticated by using JSON Web Token (JWT) or the BMC Helix Single Sign-On (RSSO) token. Clients such as curl, Postman, or BMC TestHttpClient can make calls to AR System server REST APIs.

Related topic

Contact support

Symptoms

  • The Jetty server is not accessible
  • REST API connection issues with RSSO are observed
  • The token is not generated
  • The logs are not generated
  • The incident is not created
  • Attachment related issues are observed
  • ARERR 9093 occurs
  • The attachments are not received by Salesforce (integration)

Scope

One or more users experience the problem.

Resolution

Perform the following steps to troubleshoot issues when publishing AR System server REST API:

Step

Task

Description

1

Download the client.

2

Ensure that the Jetty server is up and is running. 

By default, the Jetty server runs on port 8008(http) or 8443 (https). 

For information on troubleshooting Jetty startup issues, see Knowledge article 000253953.

3

Generate a token. 

AR System server performs the normal authentication mechanisms to validate the credentials. If the credentials are valid, the AR System server generates a JSON Web Token (JWT). For more information, see Access-and-authentication-for-the-REST-API.

For information about TestHTTPClient Tool, see an article on BMC Communities TestHttpClient - Command line tool to test HTTP(S) services.

For information about how to verify if the REST API is working, see an article on BMC Communities Remedy AR System - REST API: How to verify if it's working.

4

Make sure that the API is excluded in the rsso-agent.properties file.

RSSO Agent installed on AR System server is configured by default to filter REST calls received on Jetty. If you are fine, use RSSO to authenticate REST, if not follow the knowledge article to disable RSSO from interfering.

Knowledge article: REST API connection failed after RSSO 9.1.04 integration agent upgrade


5

Make sure that you are using the Interface forms to create an incident

The new incident ticket must be generated based on "HPD:IncidentInterface_Create", rather than "HPD:Help Desk" form.

 See the following knowledge articles for help with creating the incident:How to create new Incident ticket through REST APIUse REST API on HPD:IncidentInterface Form to update the assigned groupHow to add a task request to incident managmenet using rest API

6

If you are a non-admin user, make calls from a single client.

AR System server restricts all non-administrative users to have active login session only from one host/IP address.

For the AR System server integrations, which rely on REST API calls, to run without any errors, you must make sure that calls are made from a user with administrator rights. 

Knowledge article: When making REST API calls from multiple hosts using non admin user getting "User is currently connected from another machine or incompatible session." (ARERR 9093)

7

Collect network trace when you use third-party tools.


Use HttpFileClient Tool as it provides detail and control over what is sent in the network. This would help track the input and output. 

Knowledge article: TestHttpClient - Command line tool to test HTTP(S) services


8

Analyze the common scenarios.

  1. How to send attachments through the AR System serverREST API
    Knowledge article: How to send attachments into Remedy REST API

  2. Wrong query format with field names that contain parentheses
    Knowledge article: REST API Error 124 "Wrong query format cannot have nested parentheses" when querying with the fields option

  3. How to use Standalone Postman - SSL issues
    Knowledge article: How to use Standalone Postman - SSL issues

  4. How to enable SSL on Jetty - AR System server
    BMC Community document: How to Enable SSL on Jetty

8

Enable logs.

Enable jetty logs in debug mode. See How to turn logging on for REST API problems.

Important: If you use the second option (mentioned in the knowledge article) to enable logs, make sure to disable logs after you capture the behavior. Else, it creates a lot of information in arerror.log.

9

Create a case with BMC Support.

Collect and send logs with detailed information when creating a case with BMC Support:

  1. Provide the following information as part of your case:
    • Working and non working use case
    • A description of the behavior occurring or the problem actions
    • Details on who is affected by the problem.
    • Any error message received
  2. Gather the jetty logs enabled in step 8. 

  3. Attach the zip files to your case (up to 2 GB) or FTP the files to BMC. See Steps to send logs, files, screenshots, etc to BMC Support for a Remedy Product related case.

10

Analyze logs.

Review the logs to identify error messages or behaviors.

Use the table below to help identify possible symptoms and solutions

After you determine a specific symptom or error message, use the following table to identify the solution:

Symptom

Where

Action

Reference

The browser receives no response or connection error when accessing a URL pointing to REST API:

 http://server:port/api/


image2020-7-23_0-58-34.png

AR System 9x and above

Enable debug logs on jetty and create support case with logs and jetty/etc folder.

REST API call returns a CORS restriction message:

 "origin 'null' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource"

Browser accessing web application using REST API

Make sure you have configured the server to allow requests from specific domains (and methods)


If this fails. Capture a fiddler logs and create a support case


REST API is taking too long to respond and generate the 500 - Internal Server Error.

AR System 9x and above

  • For 9.0, 9.1 and 9.1.03 
    With AR System 9.1 SP4 the version of Jetty is 9.3.7 which has enhanced the stability and performance of REST API/Jetty. Hence, it's recommended to upgrade to AR System v9.1.04 version.
  • For 9.1.04 and higher
    Try to replicate the problem and share with us both the logs for analysis
    API+SQL+Filter and Jetty logs.

Timeout while submitting incident with attachment:


"messageType": "ERROR", "messageText": "Timeout during data retrieval due to busy server -- retry the operation",
"messageAppendedText": "",
"messageNumber": 93

AR System 9.x and above

Check if you can successfully submit any other request without attachments using postman.

If yes then there could be an issue with JSON payload, make sure you are not missing comma and bracket braces

    "z1D_Details":"Test Attachment",
    "z1D_WorklogDetails":"Test Details"
   "z2AF_Act_Attachment_1":"test.txt"

 

If it fails then collect jetty logs.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*