1. Home
  2. Utility API sandbox
  3. SAP IS-U mock server

Solution

SAP IS-U mock server for testing OData integrations

Last updated

This free SAP IS-U-style mock server behaves like an OData v2 billing service. It has $metadata, $top, $skip and $filter, __next paging and a CSRF token handshake on writes. It accepts device replacements and meter reading uploads, and rejects bad data the way an IS-U system would: implausible readings, readings outside the installation period, and oversized uploads. No SAP licence or test tenant is needed.

What it's for

Most SAP IS-U integration problems show up in the details: the client that reads only the first page, the POST that fails because nobody fetched a CSRF token, the reading upload rejected because the value is lower than the last one. This mock lets you hit those cases before you have access to a real IS-U test system. It's one of the three surfaces of the utility API sandbox.

Get started

Create a workspace, then call the service with HTTP Basic (SBX_USER / Sandbox#1) or an OAuth 2.0 bearer token from /oauth/token in your workspace:

curl -X POST https://sandbox.piebench.com/workspaces
curl -u 'SBX_USER:Sandbox#1' "https://sandbox.piebench.com/ws_…/sap/opu/odata/sap/ZPB_UTILITIES_SRV/\$metadata"

Entity sets

Entity setKeyHolds
ServicePointsServicePointContract account, business partner name, address, rate category, coordinates, installed device
DevicesDeviceDevice category, status (In-Stock, Installed, Removed), installation and removal dates
WorkOrdersWorkOrderExchange work orders: service point, removed and installed device, status
MeterReadingsMeterReadingDocumentDevice, value, date, reading reason (01 periodic, 21 installation, 22 removal)

Read one record with the OData key syntax, for example Devices('OLD0001').

Paging and queries

Pages hold 20 records. When more remain, the response carries d.__next with a $skiptoken. Keep following it until it's gone. A client that stops at the first page reads 20 of the 60 service points, which is the most common paging bug this mock exposes.

curl -u 'SBX_USER:Sandbox#1' "https://sandbox.piebench.com/ws_…/sap/opu/odata/sap/ZPB_UTILITIES_SRV/ServicePoints?\$inlinecount=allpages"
  • $top and $skip work as in OData v2.
  • $inlinecount=allpages returns __count.
  • $filter supports Field eq 'value' joined with and, up to 500 characters.

Dates use the OData v2 JSON form /Date(1731628800000)/, milliseconds since 1970 in UTC.

Writes need a CSRF token

As on an SAP Gateway service, a POST without a valid token gets HTTP 403 with x-csrf-token: Required. Fetch the token with a GET, keep the session cookie, then send both:

curl -c jar -u 'SBX_USER:Sandbox#1' -H "x-csrf-token: Fetch" -D - "https://sandbox.piebench.com/ws_…/sap/opu/odata/sap/ZPB_UTILITIES_SRV/" -o /dev/null
# copy the x-csrf-token response header, then:
curl -b jar -u 'SBX_USER:Sandbox#1' -H "x-csrf-token: <token>" -H "Content-Type: application/json" \
  -d '{"WorkOrder":"WO0001","RemovedDevice":"OLD0001","RemovalReading":"9000.000","InstalledDevice":"NEW0001","InstallationReading":"0.000"}' \
  "https://sandbox.piebench.com/ws_…/sap/opu/odata/sap/ZPB_UTILITIES_SRV/DeviceReplacements"

The token is bound to the session cookie. Sending the token without the cookie also returns 403.

Device replacement

POST DeviceReplacements closes an exchange work order. It removes the old device with its final reading, installs the new one, confirms the initial reading and, unless the desync_same_day switch is on, notifies the head-end. The response says whether it did (HeadEndNotified). ActivityDate is optional and defaults to now. It can't be in the future.

Meter reading upload

POST MeterReadingUploads takes {"Readings": [{"Device", "ReadingValue", "ReadingDate"}]}. POST MeterReadings takes a single reading. An upload is all-or-nothing: if one reading fails, none are saved.

Errors you will see

Errors use the OData v2 error envelope: error.code, error.message.value and innererror.errordetails. The message numbers echo the SAP IS-U messages integrators search for most, but the texts are the sandbox's own:

CodeWhen
EL/533Reading is lower than the previous reading (implausible)
EL/418No register is installed on the device on that date
EL/429Upload holds more than 600 readings
ZSBX/010Removed device isn't the one installed at the service point
ZSBX/011New device isn't in stock
ZSBX/020Work order is already completed
ZSBX/021Work order doesn't exist

What it doesn't do

It's a simulator, not SAP software. There's no $batch, no $expand, no BAPI or IDoc interface, and no billing calculation. Names and codes are illustrative, and PIEBENCH isn't affiliated with SAP. For how a field app connects to a real IS-U system, see SAP IS-U field service integration.

Built to integrate with your systems

HES, MDM, SAP IS-U, Oracle CC&B and billing systems, over REST, OAuth or a direct SQL connection. How integrations work

Questions buyers ask

Can I test an SAP IS-U integration without an SAP system?

You can test the behaviour your client depends on: OData paging, CSRF handshakes, date formats and error handling for device replacement and meter reading upload. You still need the utility's real IS-U test system for final acceptance. Real IS-U objects and customising differ per utility.

Why does my POST return 403 "CSRF token validation failed"?

SAP Gateway-style services require a CSRF token on writes. Send a GET with the header x-csrf-token: Fetch, keep the session cookie it sets, then send the token and the cookie with the POST. This mock enforces the same handshake.

What does EL/533 mean in this mock?

The reading you sent is lower than the previous reading for that device, so it is rejected as implausible. In real IS-U systems, implausibility rules are configured per utility. The mock uses a simple "not lower than the last reading" rule.

Why do I only get 20 records?

Each page holds 20 records. Follow the d.__next link, which carries a $skiptoken, until the response no longer has one. You can also use $top and $skip yourself.

Does the mock support $batch or $expand?

No. It supports $metadata, $top, $skip, $skiptoken, $inlinecount and simple $filter equality. Requests for other features return an error or are ignored.

Sources

Free trial · no card

See it with your own crew

Start a free trial, or ask us for a walkthrough of your rollout.

Related