SAP Data API

SAP Data API allows to upload and download data from SAP. The API is available for Evolve and Studio Manager. API exposes JSON payload and other details (i.e. SAP, Run Settings etc.) for posting data to the SAP. ROI will be synced for all the environments (Development, QA and Production) but the billing will be done only for the production system .

Note:

SAP Data API does not support chained and multi script. The SAP Data API supports only single transaction. Evolve web and service worker do not support GUI script based Transaction so it is also not supported for SAP Data API. Query with IN criteria using dynamic file path for fixed or user defined is not supported.

Prerequisites

Following are the two prerequisites to use this feature.

SAP Data API license must be activated on the Evolve system.
Value for the key SapIntegrationAPIEnable should be set True.

Once the license is activated successfully, application will also configure the system variable SapIntegrationAPIEnable and set it to true automatically on advanced settings ( Administration → System → Advanced Settings ). To disable the SAP feature, set this value to false.

Only Global Administrators are allowed to Add and Manage license. SAP Integration License is the required license for SAP Data API; Type can be Subscription (Tiered -tier band) or Subscription (Volume - Volume band). Advanced settings key SapIntegrationAPIEnable can only be enabled if user has a valid SAP Integration License SKU type. SapIntegrationApi is secured with API gateway and its supported authentication mechanism.

You can access SAP Data API from Evolve. For details about saving solutions of SAP Data APIs on Evolve, SAP API Approval Settings, and adding and updating SAP API from Solutions tab, see SAP Data API with Evolve.

You can create scripts for SAP Data API and submit the scripts to Evolve using Studio. See SAP Data API with Studio for more details.

Note:

Use "ErrorCode" from the API response, instead of field "Message". As for some error codes the data in Message field may be in English and for some in user's default language.
As per JSON standard, "\" is not valid string as JSON validator fails to support "\" character. Hence, you need to add "\\" to recognize "\" data.
For any escape character support for JSON, you need to use "\" before the escape character.

For example: "\n" and "\t" will pass through JSON validator, but this will be replaced by blank. So, you need to again add \\n and \\t character.

For accessing any API, Route Prefix would be required. Route Prefix is combination of Evolve URL and specific keywords.

For Evolve URL, user has to provide the Port number unless it is not the default Port number. For example if we have an Evolve site at default Port 80 then we can use both of the below evolve URLs for accessing API.

http://cha-de-vstpnx1.wsdt.local:80/svr/api/v1/Processextn/GetAllAssignments
http://cha-de-vstpnx1.wsdt.local/svr/api/v1/Processextn/GetAllAssignments.

For the three security options there are following route prefixes that need to be used to hit the API:

Client Secret : “<Evolve URL>/svr”

Secure Token : “<Evolve URL>/svr”

Certificate : “<Evolve URL>/svrc”

Note:

For SAP Data API, when user selects a solution to view SAP Data API solution URL is visible as “<BaseURL/GatewayURL>/api/v1/SAPIS”

BaseURL/GatewayURL is RoutePrefix.

BaseURL : Evolve URL

GatewayURL : “svr” for Client Secret & Secure Token and “svrc” for Certificate.

Request and Response Body

To upload and download data from SAP using the SAP Data API, the structure of Request and Response body will be as follows:

Request:

The Request Body contains the following:


Name	Type	Restriction	Description
SolutionDetail	JObject	Required	Information about solution with following parameters: SolutionName : Name of SAP Data API Solution. Type : String. Restriction: Required. LibraryName : Library name of SAP Data API Solution. Type : String. Restriction: Required. AppName: App Name of SAP Data API Solution. Type : String. Restriction: Required.
RunParameter	JObject	Required	Defines the data that is to be validated/posted on SAP. Refer to Input Payload Sample for field Details. Data to be defined depends on each specific run.
SapDetails	JObject	Required	Contains information about solution with following parameters: ConnectionName: SAP Connection Name on which API run is to be executed. Type : String. Restriction: Required. EvolveUser: UserName of the user who will be running SAP Data API. Evolve user must have Originator Role. Type : String. Restriction: Required. Example: wse\\username (wse is domain, username is name of the user.) SAPUser: SAP User name for making SAP connection. Type : String Restriction: Optional SAPPassword: Password for SAPUser. Type : String. Restriction: Optional. SAPLanguage : SAP Language value to be sent along while establishing SAP connection in a particular language. Type : String. Restriction: Optional. WindowsCredentials : User name and password for windows authentication, if authentication needs to be done with Windows Credentials. Type : JObject of UserName and Password. Refer to Input payload Sample. Restriction: Optional. It is advised to save SAP Credentials or Windows Credentials on Evolve against Evolve User; to prevent plain text password to traverse on network call while executing API through third party client.
RequestParameter	JObject	-	This contains information about following parameter: Validate: This value is set to true If data is only required to be validated (data not to be posted to SAP). Type : Boolean. Restriction: optional.

Response:

The Response Body contains the following:


Name	Type	Restriction	Description
RunResponse	JObject	-	Contains information about executed Run with following parameters: Success : Returns true if run is successful, else returns false. Type : Boolean. LogField : This LogField Information is similar to the details that we get in Log field after run from Studio client. Type : String. RunResult: Json Object which contains fields returned from SAP which are mapped as Download Fields. Refer to output Payload Example for details. Type : JObject (This field changes values according to Run result returned).

Error:

The Error body contains the following:


Name	Type	Restriction	Description
Fixed Array for error specifications	Jarray	-	Contains information about executed Run with following parameters: ErrorCode : Returns error code in case of run failure. Type : String. Message : Returns message corresponding to ErrorCode returned. Type : String. errorParameters: If exception has any other details which are not part of “Message”, those details are part of errorParameters. Otherwise null will be returned. Type : String Array.

Request and Response Sample

API specification for Transaction

The payload shows combined list of Input, Output, and Error payload.

Date and Number format

ISO date format is selected as it is well known and widely used. It is used across different languages and well suited to convert it into SAP user profile format.

The following date and number format is passed in SAP API payload. The date and number format is validated.

Date Format ("yyyy-MM-dd"), example (2021-06-09)

Decimal format (99999999.999), example (12345.678)

Input and Output payload usage: For Transaction and BAPI, user needs to pick Input payload for posting the data to SAP and Output payload to download the data from SAP.

Error payload is common for Transaction/BAPI/Query and it shows error to the user.

Request Sample:

Request Payload

{
"SolutionDetail": {
"SolutionName": "string",
"LibraryName": "string",
"AppName": "string"
},
"RunParameter": {
"Material_Number": "string",
"Material_Description__Short_Text_": "string",
"Gross_Weight": "0.0",
"Net_Weight": "0.0"
} ,
"SapDetails": {
"ConnectionName": "string",
"EvolveUser": "string",
"SAPUser": "string",
"SAPPassword": "string",
"SAPLanguage": "string",
"WindowsCredentials": {
"UserName": "string",
"Password": "string"
}
},
"RequestParameter": {
"Validate": "bool"
}
}

Response Sample:

Response Payload

{
"RunResponse":{
"Success": "bool",
"LogField": "string",
"RunResult": {
"Base_Unit_of_Measure": "string",
"Material_Group": "string",
"Weight_Unit": "string"
}
}
}

Error Sample:

Error Payload

[
{
"ErrorCode": "string",
"Message": "string",
"errorPrameters": [{"string"}]
}
]

API specification for Query

The payload shows combined list of Input, Output, and Error payload.

Input and Output payload usage: For Query, user needs to pick Input payload to pass the clause builder criteria fields and Output payload will be used to download data from SAP.

Error payload is common for Transaction/BAPI/Query and it shows error to the user.

Request Sample:

Request Payload

{
"SolutionDetail": {
"SolutionName": "string",
"LibraryName": "string",
"AppName": "string"
},
"RunParameter": {
"MAKT_Language_Key": {
"EqualToOp1": "string"
}
},
"SapDetails": {
"ConnectionName": "string",
"EvolveUser": "string",
"SAPUser": "string",
"SAPPassword": "string",
"SAPLanguage": "string",
"WindowsCredentials": {
"UserName": "string",
"Password": "string"
}
},
"RequestParameter": {
"RecordCount": "0",
"GetRecordsCountOnly": "bool"
}
}

Response Sample:

Respose Payload

{
"RunResponse":{
"Success": "bool",
"LogField": "string",
"RecordCount": "0",
"RunResult": [{
"MARA_Material_Number": "string",
"MAKT_Language_Key": "string",
"MAKT_Material_Description__Short_Text_": "string",
"MARA_Gross_Weight": "string",
"MARA_Net_Weight": "string"
}]
}
}

Error Sample:

Error Payload

[
{
"ErrorCode": "string",
"Message": "string",
"errorPrameters": [{"string"}]
}
]