From SMTX Wiki
Jump to navigation Jump to search

SSP supports REST webservices with which JSON files are used to transfer data between 2 systems. This page contains some examples how to define REST webservices.

Call type INSERT

  • Make sure to select REST as the Type of the webservice
  • URL: Preferably make use of a connection string, in order to easily migrate your webservice to another environment
  • Call Type = Insert
  • Return Type: In case you are expecting a single value set this to SingleValue otherwise select data table
  • Request Format: Define in which format you'll be sending your data. Most probably, you'll send your request in JSON format
  • Response Format: Define what you are expecting as a return value. Most REST service reply with JSON format. Plain text is also possible in case the return value isn't really used further in SSP.
  • Input Json: Define the JSON structure you want to send into the other system. When you want to include variables that get provided to the webservice when being called, type your placeholders using capital letters and make sure to define each placeholder as a Input type Web Service Call Field. Add the text ||JSON behind a field to properly encode the content of the field. Example:
 "values": {
   "Person ID": #PERSONID||JSON#,
   "Description": #DESCRIPTION||JSON#,
   "Detailed_Decription": #DETAILEDDESCRIPTION||JSON#,
   "Impact": "4-Minor/Localized",
   "Urgency": "3-Medium",
   "Status": "Assigned"
  • NCalc function (only available in case response format is text): Here you can define a NCalc condition in order to retrieve data from the return value. The placeholder {0} contains the returnvalue from the called webservice and any of the NCalc functions can be used here.
  • Output Selector (only available in case response format is JSON): Define here which value from the returned JSON string should be selected. Make sure to match this with the defined output fields and the Return Type. Please use sources on the internet to find more information about JSON selectors. Example of output selector:
 $.entries|#|IncidentId||values.['Incident Number']|#|Status||values.Status|#|SspId||values.['Vendor Ticket Number']
 This example retrieves 3 field from the received JSON, under which the field Incident Number and returns it as IncidentId. Additionally the fields Status and SspId are returned
 Single Value
 From the returned JSON file a single value is returned from the field Id.
  • Default return value on 404: Type here the error message this webservice should return in case the targeted webservice can't be reached
  • Return value on error: In case the called webservice has been reached, but returns an error message, you can configure here how to use this error message. You can use the placeholder #ERRORMESSAGE# to return the error as received from the called webservice.
  • Enable cache: Enable this to improve performance for webservices that are always returning the same value for a similar call
  • Enable logs: When this option is enabled, an additional tab is displayed on the webservices page on which you can see the exact data sent to and received from the webservice (added in version 7.20.7).
  • Web Service Call Headers: Define the additional headers you would like to send to the web service. For Example:
 Content-Type: application/json
 Method: POST
  • Web Service Call Fields: Define here all input and output fields needed for the webservice to work properly. Define the fields used as placeholders in Input JSON here as Input fields. Casing is not important here, however in the Input Json field all fields should be in capital. Output fields can be used to further process the data received by the webservice within your workflow or form field. Fields defined as Output, need to be defined in the output selector.