Purpose Use the GuiXT OData API to access SAP data via OData Services
With InputAssistant and GuiXT Controls, you have a convenient way to use SAP OData services in GuiXT. SAP has implemented numerous OData services, particularly in newer SAP systems; these also form the basis of the Fiori apps. GuiXT supports the currently used OData versions v2 and v4.
SAP has already integrated all necessary authorization checks into the services, so there is no risk of displaying data to a user, or allowing them to modify data, for which they are not authorized. SAP provides a catalog of all OData services on the "SAP Business Accelerator Hub" website. In addition to the standard SAP OData services, you can also access services you have developed yourself. In GuiXT, all OData "CRUD" operations (Create, Read, Update, Delete) are supported.
Additionally, there are the following functions: Logon, Logoff, Execute and ConvertValues, and for batch processing: CreateBatch, RequestBatch, FetchBatchResult, FetchAllBatchResults, DeleteBatch.
It consists of the ICF path prefix ("sap/opu/odata/sap"), the technical service name ("API_MAINTENANCEORDER") and the entity set ("MaintenanceOrder").
2 result Default: ""
The name of a
GuiXT structure or table variable which will receive the data read. Its column names must be a subset of the OData properties of the service.
Only the specified columns are requested. All column names that begin with an underscore and do not contain any uppercase letters - for example, "_countryname" - are omitted.
In conjunction with the "expand" parameter, "result" specifies a comma separated list of GuiXT variables: one additional GuiXT table variable for each navigation property. See below for the details.
3 key Default: ""
The name of a GuiXT string or structure variable which contains the OData key for single entity access. If it is a structure, the key condition is built up using the structure component names and values.
4 filter Default: ""
OData filter string in v4 format. GuiXT automatically converts the format to v2 if needed.
5 top Default: ""
Maximum entity number to read, e.g. 1000.
6 skip Default: ""
Entity number to be skipped.
7 orderby Default: ""
The service orders the result by the specified columns. Each column name can be followed by "asc" or "desc" for indicating ascending (default) or descending order.
8 expand Default: ""
A comma separated list of navigation properties of the service, e.g. "to_MaintenanceOrderOperation,to_MaintOrderOpRelationship".
For each navigation property, the result list must contain the name of a GuiXT table variable. The columns of the table variable must be a subset of the OData properties of the corresponding OData entity. Only the specified columns are read.
9 options Default: ""
Various options, separated by at least one space character:
-keepOutputFormat No format conversions are applied to the returned data. For example, a date is returned in a special OData-v2 format if service of version v2 is called. Without this flag, GuiXT reformats the output according to the user settings (dateformat, decimal separator,...).
-isoDateOutput All dates are returned in the ISO format yyyy-MM-dd
-dbDateOutput All dates are returned in the SAP database format yyyyMMdd
-decimalPointOutput Decimal numbers are formatted using a point as decimal separator and a comma as group separator
-decimalCommaOutput Decimal numbers are formatted using a comma as decimal separator and a point as group separator
-keepOutputFormat.PROPERTYNAME For each property value with the given property name no format conversions are applied.
conversionExitOutput.PROPERTYNAME=EXITNAME For the given property, the GuiXT "process" function with the given name is executed to format the value for display. Instead of a process function name, one of the following predefined exits can be specified:
alpha strips leading zeros if the value is purely numeric
alpha:n pads the value with leading zeros to length n if it is purely numeric
template:MASK formats a value according to a template mask, where # is a digit placeholder (filled right-to-left)
and all other characters are literal, e.g. template:##-###-##
date:short / date:long / date:verbose formats a date value, e.g. 15.01.23 / 15.01.2023 / 15. Januar 2023
round rounds to an integer
round:n rounds to n decimal places
scale:n divides the value by n and rounds to an integer, e.g. scale:1000 to display values in thousands
scale:n:d divides the value by n and rounds to d decimal places, e.g. scale:1000:1
-expandOrdered The returned tables corresponding to the "expand" list are ordered from left to right according to the GuiXT table definition.
-expandDistinct Duplicate entries in returned tables corresponding to the "expand" list are removed. This option implies the -expandOrdered option.
-expandDistinctIgnoreCase Duplicate entries in returned tables corresponding to the "expand" list are removed, ignoring the case in the duplicate detection. This option implies the -expandOrdered option.
10 urloptions Default: ""
Additional options which GuiXT appends to the generated URL.
They are only interpreted by the service, not by GuiXT.
11 headervariables Default: ""
The name of a GuiXT structure or table variable which contains additional request header variables (name/value pairs). If it is a structure variable, the header variables are built up using the structure component names and values. If it is a table variable, a header variable is added for each table row, using the components "name" and "value".
12 cache Default: ""
Activates GuiXT caching of the service results. Possible values are:
transaction A cache that is cleared by GuiXT for each new transaction call
session A cache kept during the whole session (SAP GUI mode) for all transactions
file A permanent cache kept in the local file system. If you use the VersionNumber command in the session script, the file cache is cleared when the version number is changed
You may use the ClearCallCache command to reset the cache.
13 message Default: ""
The name of the GuiXT structure variable which receives the resulting message, e.g. an error message. The components of the structure are the following, or a subset of them:
code Technical SAP message code
message Message text in the session language
severity Message severity. SAP uses "error", "warning", "info", "success"
target Name of a property related to the message
type Message type 'E', 'W', 'I', 'S'. Derived from severity.
System variables set by OData.Read
V[_odatalasturl] The final URL built up by GuiXT
V[_odataversion] The OData version, v2 and v4, determined from the service path
V[_odatacount] Number of entities returned (top-level only, e.g. number of maintenance orders but not of the order items)
V[_odatarequests] Total number of entities returned and total run time of the request. Example: "5627 rows in 1087 ms". Since OData services may return the requested data in several chunks, the number of entities and the runtime of each single internal http requests is also shown in such a case.
V[_odatahttpstatuscode] Final HTTP status code (number and text)
V[_odataetag] The "ETag" used in updating service requests. SAP uses the ETag for optimistic locking of entities.
Example: Read a maintenance order, including its operations
Parameters
1 service
OData service path of the entity set to create the new entity in, e.g. "sap/opu/odata/sap/API_MAINTENANCEORDER/MaintenanceOrder".
2 values Default: ""
The name of a GuiXT structure variable containing the field values of the entity to be created. All column names that begin with an underscore and do not contain any uppercase letters - for example, "_countryname" - are omitted.
In conjunction with the "navigation" parameter, "values" specifies a comma separated list of GuiXT variables: the first variable is the header structure, followed by one additional GuiXT table variable for each navigation property, to perform a "deep insert" (header and dependent items in a single call).
3 headervariables Default: ""
The name of a GuiXT structure or table variable which contains additional request header variables (name/value pairs). If it is a structure variable, the header variables are built up using the structure component names and values. If it is a table variable, a header variable is added for each table row, using the components "name" and "value".
4 etag Default: ""
The "ETag" sent as "If-Match" header. Only relevant if the target entity set requires it; for a plain CREATE this is usually left empty.
5 navigation Default: ""
A comma separated list of navigation properties of the service for a deep insert, e.g. "to_MaintenanceOrderOperation". For each navigation property, the "values" list must contain the name of a GuiXT table variable with the item data. The "values" list must always contain exactly one element more than "navigation" (the header).
6 message Default: ""
The name of the GuiXT structure variable which receives the resulting message, e.g. an error message. Same structure as described for OData.Read.
7 options Default: ""
Various options, separated by at least one space character, controlling the conversion of the supplied "values":
-keepInputFormat No format conversions are applied to the supplied values; they are sent to the service unchanged.
-isoDateInput Dates in the supplied values are expected in the ISO format yyyy-MM-dd
-dbDateInput Dates in the supplied values are expected in the SAP database format yyyyMMdd
-decimalPointInput Decimal numbers in the supplied values use a point as decimal separator and a comma as group separator
-decimalCommaInput Decimal numbers in the supplied values use a comma as decimal separator and a point as group separator
-keepInputFormat.PROPERTYNAME For the given property, no format conversion is applied
-isDate.PROPERTYNAME / -isTime.PROPERTYNAME / -isDecimal.PROPERTYNAME Declares the type of the given property, since GuiXT does not evaluate the service metadata
conversionExitInput.PROPERTYNAME=EXITNAME
For the given property, the GuiXT "process" function with the given name is executed to convert the value before sending it to the service. Instead of a process function name, alpha:n can be specified, where n is the internal field length: the value is right-justified and padded with leading zeros up to length n if it is purely numeric (matching SAP's ALPHA conversion routine, commonly used for document, order, and material numbers). If the value already exceeds length n, leading zeros are stripped first; if it is still too long afterwards, or if it is not purely numeric, the value is passed through unchanged.
Scope of these conversions: All settings above apply not only to the values passed via values, but equally to headervariables, key, and parameters: The same property-based rules (keepInputFormat.PROPERTYNAME, isDate.PROPERTYNAME, conversionExitInput.PROPERTYNAME, including alpha:n) are evaluated by property name in each of these.
Note: for an unnamed (plain string) key value, no property name is available, so no conversion can be applied. Use a named key structure instead if conversion is required.
8 result Default: ""
The name of a GuiXT structure variable which receives the data of the newly created entity, as returned by the service (HTTP status 201).
System variables set by OData.Create
V[_odatalasturl] The final URL built up by GuiXT
V[_odataversion] The OData version, v2 and v4, determined from the service path
V[_odatajson] The JSON body sent to the service
V[_odatahttpstatuscode] Final HTTP status code (number and text)
V[_odataetag] The "ETag" of the newly created entity, if returned by the service
Parameters
1 service
OData service path of the entity to update, including its key, e.g. "sap/opu/odata/sap/API_SALES_ORDER_SRV/A_SalesOrder('12345')".
2 key Default: ""
The name of a GuiXT string or structure variable which contains the OData key for single entity access. If it is a structure, the key condition is built up using the structure component names and values.
3 values Default: ""
The name of a GuiXT structure variable containing only the field values to be changed (partial update / PATCH semantics). As with OData.Create, can be combined with "navigation" for a deep update. All column names that begin with an underscore and do not contain any uppercase letters - for example, "_countryname" - are omitted.
4 headervariables Default: ""
The name of a GuiXT structure or table variable which contains additional request header variables (name/value pairs). If it is a structure variable, the header variables are built up using the structure component names and values. If it is a table variable, a header variable is added for each table row, using the components "name" and "value".
5 etag Default: "" The "ETag" used for optimistic locking (sent as "If-Match" header). If not specified, GuiXT uses the ETag from the last OData.Read or update/create call for the same entity, if available; if none is available, "*" is sent.
6 navigation Default: ""
Same meaning as described for OData.Create.
7 message Default: ""
The name of the GuiXT structure variable which receives the resulting message, e.g. an error message. Same structure as described for OData.Read.
8 options Default: ""
Same input conversion options as described for OData.Create.
9 result Default: ""
The name of a GuiXT structure variable which receives the entity data returned by the service, if any. Many services return no body (204 No Content) on a successful update, in which case the result variable is left empty.
System variables set by OData.Update
V[_odatalasturl] The final URL built up by GuiXT
V[_odataversion] The OData version, v2 and v4, determined from the service path
V[_odatajson] The JSON body sent to the service
V[_odatahttpstatuscode] Final HTTP status code (number and text)
V[_odataetag] The updated "ETag" of the entity, if returned by the service
Parameters
1 service
OData service path of the entity to delete, including its key, e.g. "sap/opu/odata/sap/API_SALES_ORDER_SRV/A_SalesOrder('12345')".
2 key Default: ""
The name of a GuiXT string or structure variable which contains the OData key for single entity access. If it is a structure, the key condition is built up using the structure component names and values.
3 headervariables Default: ""
The name of a GuiXT structure or table variable which contains additional request header variables (name/value pairs). If it is a structure variable, the header variables are built up using the structure component names and values. If it is a table variable, a header variable is added for each table row, using the components "name" and "value".
4 etag Default: ""
The "ETag" used for optimistic locking (sent as "If-Match" header). If not specified, GuiXT uses the ETag from the last OData.Read call for the same entity, if available; if none is available, "*" is sent.
5 message Default: ""
The name of the GuiXT structure variable which receives the resulting message, e.g. an error message. Same structure as described for OData.Read.
6 options Default: ""
Same input conversion options as described for OData.Create (rarely relevant for DELETE, since no values are sent).
System variables set by OData.Delete
V[_odatalasturl] The final URL built up by GuiXT
V[_odataversion] The OData version, v2 and v4, determined from the service path
V[_odatahttpstatuscode] Final HTTP status code (number and text, typically 204 No Content on success)
Establishes a session with the SAP system (authentication, CSRF token, user format settings). Calling OData.Logon explicitly is optional: OData.Read, OData.Create, OData.Update, OData.Delete and OData.Execute perform an implicit logon with default settings if no session exists yet. Use OData.Logon explicitly if you need a non-default authentication mode, user, password or ticket.
GuiXT
CallVB guinet.odata.logon
Parameters
1 server Default: "*"
Server name (host, optionally "host:port"). With the default "*", GuiXT determines the server from its own configuration. "http://" or "https://" is added automatically if not already present (default "https://").
You can append " authmode=sso" to the server name as a shortcut to select Single Sign-On without using the separate "authmode" parameter.
2 service Default: "sap/opu/odata"
ICF path used for the initial logon request (to obtain the CSRF token and user settings). Normally the default is fine; only relevant if your ICF configuration deviates from the standard path.
3 authmode Default: ""
Authentication method. With the default "", GuiXT uses "basic". Possible values:
basic Basic Authentication with "user" / "password"
sso Single Sign-On (Windows integrated authentication / Kerberos / SPNEGO, and client certificates, if configured in the current user's certificate store)
ticket SAP Logon Ticket (MYSAPSSO2 cookie), supplied via the "ticket" parameter
anonymous No credentials are set (e.g. for services that don't require authentication)
4 user Default: "*"
SAP user name, used with authmode "basic". With the default "*", GuiXT uses the current GuiXT session user (GuiXT variable "_user").
5 password Default: "*"
Password, used with authmode "basic". With the default "*", GuiXT uses the password already known from the current SAP GUI logon, if available. If no password can be determined this way, GuiXT prompts the user for the password in a dialog.
6 ticket Default: ""
SAP Logon Ticket value, used with authmode "ticket".
7 headervariables Default: ""
The name of a GuiXT structure or table variable which contains additional request header variables (name/value pairs). If it is a structure variable, the header variables are built up using the structure component names and values. If it is a table variable, a header variable is added for each table row, using the components "name" and "value".
8 message Default: ""
The name of the GuiXT structure variable which receives the resulting message, e.g. an error message. Same structure as described for OData.Read.
9 timeoutseconds Default: 300
The request timeout for each OData request in this session.
System variables set by OData.Logon
V[_odatalasturl] The final URL built up by GuiXT for the logon request
V[_odatahttpstatuscode] Final HTTP status code (number and text)
V[_odatacsrftoken] The CSRF token retrieved from the service, used automatically by GuiXT for subsequent Create/Update/Delete/Execute calls
Calls an OData FunctionImport or Action (a named, RPC-style operation) - as opposed to OData.Read, which is limited to entity set queries. "$filter", "$top", "$skip", "$orderby", "$expand" and automatic paging are not supported.
GuiXT
CallVB guinet.odata.execute
Parameters
1 service
Path of the FunctionImport / Action, e.g. "sap/opu/odata/sap/API_XXX/SomeFunctionImport".
2 result Default: ""
The name of a GuiXT structure or table variable which receives the returned data, if any.
3 parameters Default: ""
The name of a GuiXT structure or table variable which contains the parameters for the called function, e.g. "CustomerID='4711'&Simulate=true". If it is a structure variable, the parameters are built up using the structure component names and values. If it is a table variable, a parameter is added for each table row, using the components "name" and "value".
4 values Default: ""
For a state-changing Action (method "POST"): the name of a GuiXT structure variable with the input parameters, sent as a JSON body - handled exactly like "values" in OData.Create / OData.Update (same conversion options, can be combined with "navigation" for a nested structure).
5 headervariables Default: ""
The name of a GuiXT structure or table variable which contains additional request header variables (name/value pairs). If it is a structure variable, the header variables are built up using the structure component names and values. If it is a table variable, a header variable is added for each table row, using the components "name" and "value".
6 navigation Default: ""
Same meaning as described for OData.Create, used together with "values".
7 method Default: "GET"
HTTP method to use. Must be specified explicitly, since it depends on the FunctionImport / Action definition: "GET" for a side-effect-free Function, "POST" for a state-changing Action (requires the CSRF token, like Create/Update/Delete).
8 message Default: ""
The name of the GuiXT structure variable which receives the resulting message, e.g. an error message. Same structure as described for OData.Read.
9 options Default: ""
Same input/output conversion options as described for OData.Create / OData.Read, applied to "values" (input) and "result" (output).
10 cache Default: ""
Same caching mechanism as described for OData.Read ("transaction", "session", "file"). If "values" is used, a hash of the JSON body is folded into the cache key, so calls with the same URL but different body content don't collide in the cache.
11 fromFile Default: ""
Name of a file to upload
12 toFile Default: ""
Name of a file to download.
13 toTempFile Default: ""
Name of a GuiXT variable which receives the name of a temporary file containing the downloaded file. The file extension matches the attachment type. Do not specify toFile= together with toTempFile=.
14 key Default: ""
The name of a GuiXT string or structure variable which contains the OData key for single entity access. If it is a structure, the key condition is built up using the structure component names and values.
System variables set by OData.Execute
V[_odatalasturl] The final URL built up by GuiXT
V[_odataversion] The OData version, v2 and v4, determined from the service path
V[_odatajson] The JSON body sent to the service, if "values" was used
V[_odatahttpstatuscode] Final HTTP status code (number and text)
Example: Add a notification attachment
// business object key for attachment upload
CreateStructure V[obj] BusinessObjectTypeName LinkedSAPObjectKey
// set key
Set V[obj.BusinessObjectTypeName] "BUS2038"
Set V[obj.LinkedSAPObjectKey] "000010000073"
// upload attachment
CallVB guinet.odata.execute _
service:="sap/opu/odata/sap/API_CV_ATTACHMENT_SRV/AttachmentContentSet" _
headervariables:="obj" _
method:="POST" _
fromFile:="G:\warehousedamages\parcel.png"
Converts the values of a GuiXT structure or table variable according to the conversion options.
GuiXT
CallVB guinet.odata.ConvertValues
Parameters 1 values Default: ""
The name of a GuiXT structure or table variable containing the field values to be converted.
2 result
The name of a GuiXT structure or table variable which receives the returned data
3 options Default: ""
Same input/output conversion options as described for OData.Create / OData.Read, applied to "values" (input) and "result" (output).
4 direction Default: "both"
Possible values: "input", "output", "both". The input conversions or output conversions or both are applied.
5 odataVersion Default: "v2"
Possible values: "v2", "v4". Date and time values use the v2 or v4 format.
Starts a new batch. Subsequent OData requests are collected and sent to the server together as a single batch request.
GuiXT
CallVB guinet.odata.CreateBatch
Parameters
1 service
Path of the
service, without the entity set, e.g. "sap/opu/odata/sap/API_SALES_ORDER_SRV".
Please observe:
All OData requests within one batch must use the same service, but may request different entities.
GET requests (reading data) and POST requests (changing data) cannot be mixed.
File upload and download are not supported within a batch request.
2 transactional Default: "X"
For services which change data: "X" means that the data changes are committed for the whole batch; if one request fails, all others are rolled back. "N" means that the changes are committed individually.
Typical usage
// 1. Start a new batch. This call clears any previous batch results.
CallVB guinet.odata.createBatch _
service:="..."
// 2. Queue individual OData calls; these are collected, not yet sent
CallVB guinet.odata.read _
service:="..." _
key:="key1" _
result:="myresult"
CallVB guinet.odata.read _
service:="..." _
key:="key2" _
result:="myresult"
CallVB guinet.odata.read _
service:="..." _
key:="key3" _
result:="myresult"
// 3. Send the whole batch to the server in a single request
CallVB guinet.odata.requestBatch
// 4. Results are now available individually,
// as if each call had run standalone
CallVB guinet.odata.fetchBatchResult 1
...
CallVB guinet.odata.fetchBatchResult 2
...
CallVB guinet.odata.fetchBatchResult 3
...
// 5. Optional: explicitly free the batch results
// if no longer needed
CallVB guinet.odata.deleteBatch
Sends the accumulated batch requests to the server. After the call, the results of each individual request can be retrieved separately. Subsequent single OData calls do not overwrite the batch results; these remain available until the next OData.CreateBatch call or an explicit OData.DeleteBatch.
GuiXT
CallVB guinet.odata.RequestBatch
Parameters
1 message Default: ""
The name of the GuiXT structure variable which receives the resulting message, e.g. an error message. Same structure as described for OData.Read.
2 returnstatus Default: ""
The name of the GuiXT table variable which receives a result status table, one row for each request in the batch. The following components are filled:
index 1,2,3...
url Relative url of the request
httpstatus Returned HTTP status of the request
success True or False
3 returnrequestbody Default: ""
The name of a GuiXT variable which receives the generated batch request body. Mainly used for testing purposes.