The script step and the Message object

Groovy is Cloud Integration's escape hatch. When a standard step or a graphical mapping can't express a rule, a Script step can. That power has a cost: SAP guarantees only its published script APIs, and you maintain your own code through every runtime upgrade. SAP's guideline is plain: don't use scripts for what standard steps already do, such as splitting or encoding, and prefer mappings and XPath in Content Modifiers over hand-written XML parsing.

At Contoso, Theo's team is moving the 64 integrated configurations off SAP Process Orchestration on XP1. Several of the 12 interfaces marked adapt carry Java user-defined functions or small Java mapping logic that has to become Groovy. This course teaches how to write that Groovy so it survives support, upgrades and audits.

Adding a script

In the palette, choose Message Transformers, then Script, then Groovy Script, and place the step. Create opens the editor with a default script. You can also upload a file, or assign a script from a Script Collection in the Global Resources tab (lesson 5). By default the runtime calls the function processData. If the file has several functions, the Script Function field names the one to call, without arguments.

The editor's Problems view shows an Upgrade Readiness Check (unsupported libraries and classes, unused or duplicate imports) and a General Script Check. Many findings offer Fix. You can still deploy with open findings, but Contoso's rule is to start every migrated script on version 2.0 with a clean Problems view.

The Message object

A script receives the message as an instance of com.sap.gateway.ip.core.customdev.util.Message and returns it. The skeleton is short: import com.sap.gateway.ip.core.customdev.util.Message
def Message processData(Message message) {
  // read, change, set
  return message
}

Headers or properties?

This is the most important design choice in a script. Headers travel with the message: data written to a header also becomes part of the outbound message to the receiver. Exchange properties stay inside the integration flow and are never handed to a receiver. SAP warns that HTTP receivers often reject large headers, typically somewhere between 4 and 16 KB. So pass values between steps as properties, and use headers only for what the receiver or an adapter should see.

Headers the adapters give you

Many values a script needs are already headers. The IDoc sender adapter sets SapIDocType, SapIDocTransferId (the sending system's IDoc number, DOCNUM), SapIDocDbId and SapMessageId. Read them instead of parsing the control record: def idocNo = message.getHeader('SapIDocTransferId', String). One caution from SAP: for a composite (bulk) IDoc message, SapIDocTransferId holds the first IDoc's number only, so read the payload when you need all of them.

Before writing any script, Theo's reviewers ask one question: could a standard step do this? Setting a property from an XPath, deleting headers before a receiver call, splitting a bulk message or converting XML to JSON all have standard steps. Of the scripts found in the 12 adapt interfaces, about half turned into Content Modifier entries during review. The rest became short, tested Groovy.