EI_Script_OD – OData script details

The EI_Script_OD worksheet contains script configuration based on Open Data Protocol (called OData, see https://www.odata.org/). The EI_Script_OD worksheet is only visible when OData script is chosen (see EI_Script_Name worksheet and ribbon menu) and configuration is not hidden. OData script can read data from or write data to an SAP system via calling network service compliant with OData standard. In the SAP S4HANA system many useful OData services are already prepared. All SAP FIori transactions use OData data access. On the EI_Script_OD worksheet Columns F-K describe the called OData service and columns P-Z contain additional data steering how the script will be executed.

Preparation of an OData script

Preparation of an OData script starts usually from gathering knowledge how the OData service works. One can test SAP OData services in the /n/IWFND/GW_CLIENT transaction.

When the OData service is known, one can start creating the OData script using EasyInput. The script creation could be done manually on EI_Script_OD worksheet, but much easier is to use automated script creation tool started with the ribbon button ”Add OData service ”.

EI_Script_OD – Ribbon button: Find OData service

The button „Find OData service” calls help popup window showing how to find and configure an OData service.

EI_Script_OD – Ribbon button: Add an OData service

When the OData service is well checked (e.g. already tested in /n/IWFND/GW_CLIENT) it can be added to EasyInput by selecting the “Add OData service” button. On the popup window „Selecting OData service” the most important OData service query data shall be filled in. After acknowledgement with „OK” button, EasyInput will try to connect to the selected service, call it once and generate the script taking into account the returned values from the service. The genarated script can be afterwards manually adjusted (and will in most cases be). In particular, the parameters passed to the OData service (WriteData in column L, for the URL and import part of the script IDATA, and ReadData for export part EDATA). The special string && is used to pass the parameter into the right place of the script.

See example of an simple OData service script:

Inactive	Param use	Parameter name	Parameter Field	Data type	Field value	Field desc	Transfer type	Read/write column
	OD	CCR
	TYPE	OD_SAP_V2
	METHOD	GET
	URI_PART0	&cprotocol&://&chost&:&cport&/
	URI_PART1	sap/opu/odata/
	URI_PART2	sap/FCOM_COSTCENTER_SRV/CostCenterSet?					AssignData	AA
	URI_PARTX
	FORMAT	$format=json
X	EDATA		BUKRS_TEXT	CHAR-25!--		Company Name
	EDATA		Kokrs	CHAR-4!--		Controlling Area	ReadData	AB
	EDATA		Kostl	CHAR-10!--		Cost Center	ReadData	AC
	ERC	error	code
	ERM	error	message
	ERM	error-message	value
	ERT	error	severity

Or another extract of odata script with filtering in URL (with the use of special replacement tag &&)

Inactive	Param use	Parameter name	Parameter Field	Data type	Field value	Field desc	Transfer type	Read/write column
	OD	SOR
	TYPE	OD_SAP_V2
	METHOD	GET
	URI_PART0	&cprotocol&://&chost&:&cport&/
	URI_PART1	sap/opu/odata/
	URI_PART2	sap/API_SALES_ORDER_SRV/A_SalesOrder&&?		CHAR-10!--		Sales Order	AssignData	AB
	URI_PARTX	$expand=to_Item,to_Partner&
	URI_PARTX	$filter=SalesOrganization eq '&&'		CHAR-4!TVKO-VKORG-		Sales Organization	WriteData	AA
	URI_PARTX	&$filter=SalesOrder ge '&&'		CHAR-10!--		Sales Order from	WriteData	AB
	URI_PARTX	and SalesOrder le '&&'&		CHAR-10!--		Sales Order to	WriteData	AC
	FORMAT	$format=json
	EDATA		SalesOrder	CHAR-10!--		Sales Order	ReadData	AD
	EDATA		SalesOrderType	CHAR-4!TVAK-AUART-		Sales Order Type	ReadData	AE
	EDATA		SalesOrganization	CHAR-4!TVKO-VKORG-		Sales Organization	ReadData	AF
	EDATA		DistributionChannel	CHAR-2!TVKOV-VTWEG-		Distribution Channel	ReadData	AG
	EDATA		OrganizationDivision	CHAR-2!TVTA-SPART-		Division	ReadData	AH
	EDATA		SalesGroup	CHAR-3!--		Sales group	ReadData	AI
	EDATA		SalesOffice	CHAR-4!--		Sales office	ReadData	AJ
	EDATA		SalesDistrict	CHAR-6!--		Sales District	ReadData	AK
	EDATA		SoldToParty	CHAR-10!KNA1-KUNNR-		Sold-To Party	ReadData	AL

The Param use column defines the meaning of the OData script row:

Param use	Param description
OD	Defines the beginning of the OData Script
TYPE	Defines type of the script (OD_SAP_V2, OD_SAP_V4, OD_NOT_SAP)
METHOD	Http call method. GET for data reading, PUT, POST, PATCH, DELETE for data change (whether cartain method can be used with OData service depands on implementation of OData service).
PREGETQUERY	Parameter used only for methods other than GET. Has value “X” if query with method GET should be called before query with method other than GET. This may be required for SAP services in order to fetch obligatory X-CSRF-Token. Additionally EasyInput may read from the GET query header ETAG and use it to create If-Match header (see SAP documentation)
URI_PART0	Defines service URL – protocol, host and port, np.: https://services.odata.org:443 Usually for SAP services, this is not given explicitly, but using special tags (&cprotocol&://&chost&:&cport&/ see special tags description below). This facilitates to use the same EasyInput OData script on various SAP systems. If special URL tags were used in URI_PART0, then before really calling the service these signs will be replaced with protocol, host, port taken from SAP system.
URI_PART1	Defines service path. E.g. for SAP OData V2 services, default path is „sap/opu/odata/”.
URI_PART2	Defines service (together with namespace/ version/ etc. ) and resource, e.g.: sap/FCOM_COSTCENTER_SRV/CostCenterSet?
URI_PARTX	Definas Optional additional URI parameters (e.g. filters, expanding, etc.). Important! One may add more than one line with URI_PARTX ! Important! When OData script is executed, then EasyInput concatenates strings from URI_PART0/PART1/PART2/PARTX. This concatenated string must represent a correct OData service call URI (e.g. strings URI_PART0/PART1/PART2/PARTX must be ended with the correct separation characters /,?,&). It is possible to use special replacenet tag && in URI_PART2 or URI_PARTX, that allows to make the service call more flexible (e.g. one can pass using && tag filter parameters). If substring tag && is given in Parameter name column, then the value from column J(Field value) or value from data sheet column (defined by columns L=WriteData & M) replaces the substring. In a rare case, when one would like to use substring && without replacement, then substring && should be used. Important! For GET method, if there is no WriteData clause in the script, one should assign to one of the uri rows transfer type AssignData and define read/write column. It is necessary because EasyInput scrip to run, must be initiated by a column on data worksheet. Assigning transfer type AssignData and filling any value on the data worksheet in the assigned colum (e.g. START), solves this problem.
FORMAT	Defines format for data returned from the service. Recommended value is $format=json. Unrecommended value, for services that does not support json is $format=xml. For correct query results reading when using XML formatone should set the configuratuion parameter (on worksheet EI_Config), EI_C_OD_MATCHING_LEVEL ResultMatchingLevel to value 1.
IHEADER	Parameter used only for methods other than GET. By default this parameter should have value application/json;charset=utf-8 , but if IDATA string is given as XML, then the parameter should have value application/xml;charset=utf-8
IDATA	Parameter used only for methods other than GET. Sting in JSON format (recommended) or in XML fromat, which will pass data to service. Usually, there is multiple IDATA rows (easier to read), which before service execution will be concatenated into one string. Similarly to URI, in IDATA rows, one may use special replacement tag &&. With the use of this tag, one can assign transfer type WriteData and the write column. This adds possibility to make the value passed to script dynamic (dependend on data on data sheet).
EDATA	List of parameters that can be returned by the OData service. Assignment to such row transfer type ReadData allows to read data from service and write it on data/ result worksheet. Important! By default all the EData script lines are deactivated. In order to read the parameter one has to remove the „X” value from the Inactive column. In columns parameter name/ parameter field one puts string (separated with “-“ sign) depicting data in Json query response. Elements „d” (starting element) and „results” (depicting table of data) are ommitted! This makes script easily readable.
ERC, ERCD, ERM, ERMD, ERT, ERTD, ERX, ERXD	Rows depicting error return reading from JSON/ XML string (or from sap-message header). By default these rows are filled automatically, but if the service returns errors in some not standard way, one can adjust them manually. The third parameter letter depicts what part of error is read: C-code, M-message text, T-type. Special X letter is reserved fro reading the V1, V2,V3,V4 message parameters from sap-message header.
HTTPUSER	Optional parameter, used sometimes form non-SAP ODATA services. It allows to pass user name to the service. Should be used together with HTTPPASS param.
HTTPPASS	Optional parameter, used sometimes form non-SAP ODATA services. It allows to pass user password to the service. Should be used together with HTTPUSER param.

Special signs in the script (replaced during the script execution)

Sign	Description
&&	Allows to pass dynamic parameters into the OData service. Defines the place in the script where the special value will be transferred. The value can be defined in column J (constant value) or via columns L(WriteData) and M(data column ID). If WriteData clause is used, then value in column J is not used. In rare case, when && substring should not be replaced one should put && instead.
&cprotocol&	Defines http protocol (http or https). If given then EasyInput checks if https protocol is defined on SAP Gateway if yes it uses https, if no it switches to http. Works only when EI_C_OD_READ_CONNECTION_DATA configuration parameter is switched to “X”.
&cserver&	Defines the SAP Gateway server. The server in the script can be given as constant or via this parameter. Using this parameter (recommended) allows to automatically refresh the system each time a change on SAP Logon worksheet will be executed. Automatic server finding requires SAP RFC access. Works only when EI_C_OD_READ_CONNECTION_DATA configuration parameter is switched to “X”.
&cport&	Defines the SAP Gateway port. The port of the service can handled automatically similarly to the server of the service. Works only when EI_C_OD_READ_CONNECTION_DATA configuration parameter is switched to “X”.

EI_Script_OD – Button Auto-fill read/write columns

In order to simplify assigning script rows to data sheet columns, the user can fill in only Transfer type in L column of the script, and let EasyInput assign columns (e.g. AA, AB, AC,…) automatically. This can be started by pressing the button “Auto-fill read/write columns”. After automatic column assignment, one can rearrange them using “Column tools” ribbon buttons.

EI_Script_OD – Button Create references in data sheet columns

After creating the script itself on the EI_Script_XX worksheet, the references to data sheet should be created for each row where column “L” has a value. This is an automatic task started by pressing the „Create references in data sheet columns” button on the ribbon.