REST Calls

This section outlines the details of the mapping parameter used to call a REST service. It describes how to map the necessary parameters and how to handle errors or success cases.

Parameter Overview

The main parameter to specify the REST mapping.

Parameter	Mandatory	Type	Description
type	Yes	`string`	The connection type to be used for invoking SAP. Since this chapter describes REST calls, use the value `rest`.
sapFunctions	Yes	`Object`	The object specifying the request to the SAP system. Refer below to section Parameter sapFunctions.
success	Yes	`Object`	Handle the success case of the SAP return. Refer below to section Parameter success.
failure	Yes	`Object`	Handle the error case of the SAP return. Refer below to section Parameter failure.

Parameter sapFunctions

Specify the REST request made to the SAP system along with headers, body and response.

danger

Make sure the request itself and the response body are in JSON format.

Parameter	Mandatory	Type	Description
endpoint	Yes	`Object`	Defines the endpoint in the SAP system, including the method, URL, and parameter substitutions. Refer below to section Parameter endpoint.
headers	No	`List<Content Proptery>`	Set headers for the request. Refer below to section Content Property for syntax.
body	No	`List<Content Proptery>`	Set the body of the request for `POST` and `PUT` methods. Must be in JSON format! Refer below to section Content Property for syntax.
response	No	`List<Content Proptery>`	Specify the parameter mapping for parameter returned in the response of the request. If applicable, the response must be in JSON format! Refer below to section Content Property for syntax.

Parameter endpoint

Defines the endpoint in the SAP system, including the method, url, and parameter substitutions.

Parameter	Mandatory	Type	Description
method	Yes	`string`	Specify the method for the request. Supported values are `GET`, `POST` and `PUT`.
url	Yes	`string`	Enter the name of the REST service, for example: `API_PRODUCT_SRV/A_Product`. It uses the definition in sapConnection.yaml, which is referenced via the `sap` parameter of the current task. Placeholders can be used for substitution; therefore, use a name in curly brackets, e.g., `API_PRODUCT_SRV/A_Product({mySubstitution})`.
substitutions	No	`List<Content Proptery>`	List of all substitutions to be replaced if specified in the url. Substitutions will be replaced with their corresponding values before submitting the request. Refer below to section Content Property for syntax.

Parameter success

This property can be utilized to manage the return of the REST service call in case it was successful. For instance, it can be employed to establish an exclusion criterion that prevents subsequent task runs from reprocessing the same document. The generic example below sets the value of the existing property cmProp_TaskStatus in the content model to Success and the value of property cmProp_TaskMessage to No Error. Because both values are fixed, you must add constant: true (refer the section above on Content Property).

Example
success:
  - source: 'Success'
    constant: true
    target: 'cmProp_TaskStatus'
- source: 'No Error'
    constant: true
    target: 'cmProp_TaskMessage'

Parameter failure

Similar to the success parameter mentioned above, but it is used to handle any errors returned by the REST service call. The example below sets the value of the existing property cmProp_TaskStatus in the content model to Error.

info

Based on the REST service that is invoked, the possible errors that may be returned differ. Check the error handling section of the REST service and specify the error key you want to set as the value for the -source parameter, and store it in a property within the content model of the storage.

Example
failure:
  - source: 'Error'
    constant: true
    target: 'cmProp_TaskStatus'
- source: Error.Message // Error message key in JSON 
    constant: false
    target: 'cmProp_TaskMessage'

Content Property

Specification of the available content properties mentioned in the avove parameter descriptions.

Parameter	Mandatory	Type	Default	Description
source	Yes	String		Depending on the constant or script setting below, the value can either be a hardcoded or parsed/formatted by Javascript.
target	Yes	String		Same explanation as above.
constant	No	Boolean	`false`	Set `true` to return a constant value in source. Set `false` to return a value from the JSON result of the REST call.
script	No	String		Modify the value using JavaScript functionality before sending or after retrieving it. Refer to section Using script parameter below.
metricLabel	No	String		Available only for response! Set the label that can be evaluated by Prometheus. It must contain only lowercase letters and cannot contain whitespaces. Refer to the Metrics chapter in the installation section.

Using script parameter

Use the script parameter to modify the value using JavaScript functionality. This is beneficial when the value requires parsing and formatting to meet a specific format. Handling Date objects and Boolean values are examples of situations where this parameter can be effectively utilized.

The following properties will be passed to the script, allowing them to be accessed within it.

danger

Do not override the properties below!

Parameter	Description
logger	The logger instance. Can be used to log various activities within the script.
props	The properties of the current document being processed by the function module.
now	The current time.
nowUtc	The current time in UTC.
Parse	Function to parse the value to a date object. Example: `Parse("2006-01-02T15:04:05Z07:00", value)`. Refer to Reference Template section.
Format	Function to format the value to match the target format. Example: `Format("20060102", value)`. Refer to Reference Template section.
content	The content of the currently processed property in the configuration includes `target`, `content`, and, if present, `script` and `constant`.
value	The value of the `target` or `source` parameter that is passed to the script.

Example

The following example outlines the REST mapping explained above using a GET request. See the table below the example for descriptions.

Example
mapping:
  type: rest
  sapFunctions:
    - endpoint:
        method: GET
        url: API_PRODUCT_SRV/A_Product('{objectId}')?$format=json
        substitutions:
            - source: myContentModel:sapObjectId
              target: objectId
              script: value.replace(/^0+/, '')
      headers:
        - source: PostmanRuntime/7.37.3
          constant: true
          target: User-Agent
      body:
      response:
  success:
    - source: Success
      constant: true
      target: myContentModel:TaskStatus
    - source: No Error
      constant: true
      target: myContentModel:TaskMessage
  failure:
    - source: Error
      constant: true
      target: myContentModel:TaskStatus
    - source: Error.Message
      constant: false
      target: myContentModel:TaskMessage

Line Number	Description
5	Specify the HTTP method and make `GET` call.
6	Enter the service and the name to return a JSON response. It uses `{objectId}` as a placeholder for the substitution. he host, port, and authorization will be read from the relevant `sap` parameter of the current task configuration.
7 to 10	Substitute the `{objectId}` in the URL. Read the value from property `myContentModel:sapObjectId` and remove all leading zeros using the `script` parameter.
11 zo 14	Set the `User-Agent` header for the request. Because it is a constant value, the `constant` parameter must be set to `true`.
15	There is no request body for `GET`. Setting can be also removed.
16	Same for the response. As the REST service does not return a response, it can be also removed.
17 to 23	In case of success, set the `myContentModel:TaskStatus` of the storage to Success and the `myContentModel:TaskMessage` to No Error.
24 to 30	In case of failure, set the `myContentModel:TaskStatus` to Error and the `myContentModel:TaskMessage` to the value in key `Error.Message` returned by the REST service.

REST Calls

Parameter Overview​

Parameter sapFunctions​

Parameter endpoint​

Parameter success​

Parameter failure​

Content Property​

Using script parameter​

Example​