AR Server REST API architecture and overview - Start here

Version 57
    Share This:

    This document contains official content from the BMC Software Knowledge Base. It is automatically updated when the knowledge article is modified.


    Remedy AR System Server


    AR server 9x with REST API




    AR server has a Jetty server that will receive REST API calls. AR server will need one or 2 more ports to receive http /https requests.  
    The Jetty server used in AR server is an embedded version, hence it is trimmed down to the bare minimal to address these requests.Once Jetty receives a request it will translate into an API Call (create Entry, set entry, etc). Filters on AR server will trigger in the same way as with any other API call  
      User-added image 
    The authentication mechanism requires a single step to gather a token that will time out (no matter what).This token should be retrieved to be able to make subsequent requests  
    eg. Authenticate, get token, then create entry using the token.  
    Login process depicted here: 
    For a broader description of architecture and features 

    Some login process details

     A single JWT token is valid for about an hour (variable AR_SERVER_INFO_EA_SYNC_TIMEOUT controls this) Therefore if you have a token you can attempt a call and if that call returns an error 623 you would need a new token.  
    A single token can also be used across multiple AR servers that are in the same AR server group.  
    In order to decode a token just use a base64 decoder and some information will be visible such as  
    Sample token: eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJDVEZZXC9aN2ZyYTRRRUZydFRNUG5WOWFtXC9yZlpzRDhtckw2K1BhYkgycjBIYzVCbkl3cXVrbHdaSjdySGNBTkU3WWs5ODhqT1B3QWJWbnFXRDBRK0psdjJqcHdWeGZYQ3VNb29nRXluNXl0TXB2eUxuS0J4VXc9PSIsIm5iZiI6MTUyMjY5MDkyMCwiaXNzIjoiY2xtLWF1cy0wMjIzMDcuYm1jLmNvbSIsImV4cCI6MTUyMjY5NDY0MCwiX2NhY2hlSWQiOjY4NTYsImlhdCI6MTUyMjY5MTA0MCwianRpIjoiSURHQUE1VjBHRVFDQUFQR0s5WDJQRk5ZRFI3Q1ZaIn0.BtZtaYwmF4pgjT8zOQCEuV1juzRGkcZsYpJZ88pOObE  
    once decoded from base64  
    "alg":"HS256"} {"sub":"CTFY\/Z7fra4QEFrtTMPnV9am\/rfZsD8mrL6+PabH2r0Hc5BnIwquklwZJ7rHcANE7Yk988jOPwAbVnqWD0Q+Jlv2jpwVxfXCuMoogEyn5ytMpvyLnKBxUw==","nbf":1522690920,"iss":"","exp":1522694640,"_cacheId":6856,"iat":1522691040,"jti":"IDGAA5V0GEQCAAPGK9X2PFNYDR7CVZ"} The expiration is exp field and it is in epoch 

    How to enable rest api

      By default the initial configuration would not work (prior to 9104), changes are required.The basic change would be to use the attached sample configuration It includes a self signed certificate, and a jetty-selector.xml file that will open both http and https ports. Note that valid certificates should be created for production usage as this certificate was created for a BMC testing machine  
    Manual procedure is located here: 
    Manual process depicted on video here 
    Using the sample configuration will save some steps  
    To use the sample https configuration and keystore 
    For AR server 9x prior to 9104 
    1. Make a backup of jetty-selector.xml
    3. Copy the zip file contents into C:\Program Files\BMC Software\ARSystem\jetty\etc
    5. Restart AR Server
      For AR server 9104 (if you want to enable http nothing is required, port 8008 is opened by installer configuration. The following steps are required for https)   
    1. Make a backup of jetty/etc folder
    3. Copy the zip file contents from 9104 sample into C:\Program Files\BMC Software\ARSystem\jetty\etc
    5. Restart AR Server
    7. The sample files will open port 9443 this can be changed in files etc\jetty-http.xml and etc\jetty.xml

    What is postman

      Postman is an http client focused on building and executing REST API calls in JSON format. BMC uses it heavily to demonstrate features, but it is just a testing / debugging client. 

    Besides being a client for testing are there any best practices while using postman?

      Yes, the main recommendation is to use "environments" and "collections", environments will save variables for reuse like: jwt tokens, server names, ports.  "Collections" will save request which can get complex.  
    KB How to use Collections and Environments on postman:  000128813

    Can postman do every operation supported by REST API on AR server ?
    No, uploading attachments is the major limitation. Java, javascript and other sample codes are available to perform this task  
      KB How to send attachments via the Remedy REST API: 

    How to gather evidence on REST API activity


    How to enable a separate log for REST API, what will be displayed (including API SQL and filter logs) ? 


    KB How to create REST API and Jetty specific log


    Is jetty opening ports?


    On any browser access http://arserver:unsecureRESTPort/ and https://arserver:secureRESTPort/
    In both cases browser would display a 404 error . that means the port is open and listening
    Further reference:


    Frequent Questions


    Can AR server consume 3rd party REST API services?
    No, for the time being only publishing form AR server is in the product scope

    How can I consume AR server REST API from browser code? 
    There are 2 current options
    a. Install an http proxy like j2ep  Setting a proxy in tomcat, that will bypass the CORS problem
    b. Install an http server on jetty 
    Both options work but are unsupported.

    Either of these options will remove the CROSS-Origin problem (browser security feature) and then you can use this KB to call AR server REST API from eg: midtier

    When a vulnerability is found on REST APi ports, how can I change or configure Ciphers?
    The jetty-selector.xml file attached to this article has been reviewed (Aug 23rd) to comply with OWASP recommendations.
    for other jetty-selector rules
    This sample configuration adds 

                    <Set name="ExcludeCipherSuites">
                        <Array type="java.lang.String">       




    For further REST API material



    Article Number:


    Article Type:

    Product/Service Description

      Looking for additional information?    Search BMC Support  or  Browse Knowledge Articles