Genius #SAPNetWeaver #BPM Expressions worth knowing
Last weekend I went to the Toulouse-Lautrec exhibition at the National Gallery of Australia. Every time I go to one of their exhibitions I am amazed at the variety and quality of expression of the many famous artists they exhibit, and the Toulouse-Lautrec show was no exception. Amazingly many of Toulouse-Lautrec’s masterful paintings and posters were created on cardboard. Not the usual support for painters at all. But then he was a genius! You’d have to be to do so much with so little.
So how does that bring me to BPM expressions? Well they’ve done it again! Every Teched our developers sneak in a few more mapping techniques hidden deep into the bowels of the hands-on workshop exercises, and Teched 2012 was no exception. With remarkably economic combinations we have a whole range of mapping options available to us. A little bit of genius! But of course not everyone is lucky enough to get to Teched and get their hands on the hands-on. So for those suffering a little #techedenvy – this blog’s for you!
Mapping techniques are used a lot in BPM:
- For output mappings between events and processes
- For input/output mappings between processes and their tasks
- For input mappings between processes and events
And the Expression Editor – the most powerful mapping tool – is also used:
- For assigning users, groups and roles to tasks
- For assigning conditions to gateways
- For inserting variables into inbox and email notification texts
This is a summary of mapping techniques I have discovered so far… [FYI all the examples shown here have been captured on a SAP NetWeaver Developer Studio 7.3 EHP 1 SP05.]
Left mouse drag: Simple copy and deep copy
Simple copies and deep copies is where everyone starts. Just click on the source element and drag it to the target element. This works for single elements, structured elements, and array elements. Provided of course the source and target have the same data type, or at least compatible data types, otherwise you’ll (usually) need to go to the Expression editor to sort out the difference. More on that later. With structured and array elements you’ll also see an expand/collapse icon that shows you exactly what has been mapped.
Multi-level mapping: N of M mapping
When you are mapping source and target structures (or arrays) that do NOT have the same data type – but that’s ok because you only want to map some of the sub-elements – you can use an “n of m” mapping. This works as follows:
Left mouse drag from the parent source element to the parent target element. At this stage you will see the expression error icon.
Now to complete the expression, left mouse drag from each child sub-element that you want to map to its matching target source sub-element. Remember that the data types of the mapped sub-elements will need to be compatible for a successful mapping.
Not sure which data types are compatible? Try the SAP Library Help:
Provided the sub-elements have been mapped successfully you should now see that the expression error icon at the parent level is now gone, replaced by an n:m icon, and all is fine.
Right mouse drag: Execute default matcher
Mind you, if you have a lot of sub elements to map this can get quite tedious. An alternative to speed things up is to use the automapping function that maps all source and target sub-elements with identical names.
[Optionally, you can start as before with the left mouse drag from parent source element to parent target element. This is handy if you want to do an append/merge/set option at the same time. More on that later.]
Now for the magic.
Click and right mouse drag from the parent source element to parent target element, and then choose Execute Default Matcher.
All identically named sub-elements will be mapped.
That’s just lovely, but even more impressive is that you can tailor the default matcher to use some more advanced options such as namepaths and leafs, adjust the mapping precision, and even use a dictionary to map based on synonyms and abbreviations, all by adjusting your NWDS preferences.
Read all about it in the SAP Library Help:
Right mouse click: Append, Merge and Set
When working with structures and arrays, it’s not always a simple move of like structures. For these there are some extra functions available when you use the context menu (right mouse click) on the target element.
Say you want to map a new row from your Source context and append it to a list of identical typed rows in your Target context:
- Start by mapping the source to the target element with a left mouse drag
- If the structures aren’t exactly the same, the map the sub-elements for a N of M mapping as per usual
- Now right click on the target element and you will see the options Append, Merge and Set
- Choose Append
BTW Set essentially means overwrite which is a quick way to initialize a table.
Merge I’ve found very handy for use with complex structures. For example if you have provided the same input to 2 or more different tasks, and then need to consolidate the results afterwards – especially if the tasks are changing different attributes of the same parent structure.
Double-click: Expression Editor access
Now when you have exhausted the left/right mouse click and drag options and still need to do some transformation, that’s when you’ll need to go into the
Expression editor. Double-click on the target element to enter the expression editor. You can do this whether you have already mapped something from the
source elements or not.
Expression editor. Double-click on the target element to enter the expression editor. You can do this whether you have already mapped something from the
source elements or not.
[Note that for a deep copy, you can only access the expression editor on the parent level, or else break the deep copy by right-clicking on the parent target element and selecting Switch to 1:1.]
Often what you want to do in the expression editor is to map a value from multiple source elements into one target element. If this is your intention you can get a bit of a head start by left dragging each source element to your target element before you go into the expression editor. By default, all of your source elements will be mapped to the target element using the built-in mapping function concatenate. More on built-in mapping functions later. You may not want to concatenate – but that’s ok as you can adjust that in the expression editor, and at least you have made a start by indicating what source context elements you want to use.
Press the ? icon at the bottom left of the Expression Editor to get access the NWDS help and background information on how to create expressions.
Expression editor: Simple constants
Let’s start at the very beginning, a very good place to start….
Sometimes, especially when prototyping, all you want to do is hardcode (at least temporarily) a set value in your target. Easy. Just open the Expression editor for the target element and enter your constant in the expression pane of the expression editor, and if it’s a string or character typed element, enter it in double quotes.
“My Constant Value”
Numbers can be expressed as numbers without quotes, e.g. 12, -10
Dates are expressed in YYYY-MM-DD format without quotes, e.g. 2013-02-28
Boolean values are expressed without quotes e.g., true, false
Expression editor: Task/Process Content
You can also use the expression editor to do simple or deep copies in the expression editor. Instead of doing a left mouse drag from source to target, you open the Expression editor on your target element, expand the source elements under Context in the Context, Rules and Functions pane, and click and drag them across to the main expression pane on the left. Having difficulty seeing your context? Just resize the expression editor and adjust the size of the panes the same as you would anywhere else in NWDS.
Expression editor: Simple mathematical formulas
A great one for quickly incrementing or decrementing counters is simple mathematical formulas. Like this one using a numeric typed context element called “counter”. Just enter your expression in the expression pane.
counter+1
You can use the usual mathematical formula operations such as addition (+), subtraction (-), multiplication (*), division (/), and div.
If you want to learn more about XPath operations you can find plenty of XPath tutorials and references on the web. This is one I came across recently that I
found helpful.
found helpful.
Expression editor: Built-in mapping functions
For slightly more challenging mappings, lots of pre-built mapping functions are provided. The first of these you are likely to notice is the concatenate function “concat”. When you drag multiple source elements onto the same target element and then open the expression editor, you can see that the default function applied is concat.
You can find the list of functions in the Rules and Functions folder in the right hand Context, Rules and Functions pane of the expression editor. There are lots of these, so they are organized into categories based on data types, and there are few special ones that work with any data type listed under the category Generic. Rest your cursor on the expression and you’ll get a little more information in a tooltip. Click into the tooltip to scroll around it.
To use the expression you can either type it in or just drag it from the right hand pane into the left and place it where you put your cursor.
When looking at the list of functions you will notice some functions are repeated but with different types for the parameters. That simply means that the function copes with all the listed types. For example you can use the function decimal( value ) to return a decimal typed value from a double, integer, long, or string input value.
Built-in functions I love to use include…
matches(string value, string value) – e.g. matches(myvariable,”ABC”) – great for getting a boolean true/false result when comparing two text values
isSet() – great for finding out if a field is empty (false) or filled (true)
if (condition) then value else value – the best option for conditional expressions, which is not to be confused with the older and deprecated IF(then, else)
current-dateTime() – today’s date in dateTime format
date-from-dateTime( dateTime value) – extract just the date part of a dateTime field
upper-case( string value, string locale) – e.g. upper-case (myvariable, “en_US”) – great for translating user entered fields to upper case before passing them to a background step which doesn’t like mixed case
More information on the provided functions can be found in the NWDS help or in the SAP Library help:
Expression editor: Expressions within expressions
Often you end up with compound expressions. These can usually be nested to as many levels as you need, e.g.
date-from-dateTime( current-dateTime() )
It’s worth noting that you can space your complex expression out as much as you want, to help with readability.
Nesting can get tricky so make sure you take advantage of the error/warning icon that shows just before the expression when things aren’t quite right. Rest your cursor on it and you will get a hint as to what is still not quite right. Too few parentheses? Not enough commas? These will show as parsing errors with an indication of where the problem was found.
More XPath help
There are lots of resources out there on the web, but these are a couple I’ve found helpful.
And of course don’t forget the relevant section in the SAP Library Help
Expression editor: Custom (e.g. EJB) functions
Any custom expression function you create shows up in the Rules and Functions folder in the Expression Editor, just like a built-in function but categorized under the project name. How do you create a custom function?
An oldie but a goodie blog on this ….
And the related SAP Library Help
Expression editor: Comments in expressions
Usually you can use // and just follow that with your comment wherever you need it to go.
// Your comments here
I have found however that in certain places where the expression editor is used, the return character may be reformatted out of your expression when you close it. So just to be on the safe side, I would suggest you put your comments at the end of your expression or use the other comment option which delimits the start and end of the comment as follows:
/* your comments here */
Expression editor: XPath namespaces and casting
Found a good looking function, but it just doesn’t quite return the data in the XSD data type you need? Add “cast as” to get you out of trouble. Cast as will convert it to the specified type.
Need that type to come from your own special namespace that you’ve loaded into your BPM project? No worries – just add the XML namespace reference using xmlns: as in this example.
The xmlns line indicates the namespace and gives it an alias.
Then the appropriate mapping function is performed. In this case loading an XML document (ok I’m sneaking that one in from Teched 2012’s Process Orchestration Claim Check example – with thanks to Volker Stiehl and Alex Bundschuh).
Finally the result of the function is cast by referencing the relevant datatype using the namespace alias.
Process Orchestration – extra genius!
If you are using BPM as part of Process Orchestration you have an extra option available to you, courtesy of the Process Integration part of Process Orchestration, called Operation Mappings. This is great if you want to reuse Message Mappings, XSLT mappings or Java mapping programs you’ve already set up in PI. But I will hand that over to the master Bill Li who has already covered it in his blog:
Have you found any others? Or a better XPath reference? Please let us know … and in the meantime enjoy expressing yourself ! 😉
Hi Jocelyn,
Thanks for this guide into BPM expressions and mapping techniques.
Brilliant in expressing yourself again!
Let's see if there will be more coming from the community 🙂
Cheers, Mariana
Thanks Mariana! Hoping it will be useful for lots of people as there have been quite a few forum posts looking for help with mapping BPM expressions. There are quite a few tricks of the trade that aren't immediately obvious but can save a lot of time and frustration once you know them.
Good stuffs, Jocelyn.
Thanks Bai - glad you enjoyed it!
Extra setting to graphical mapping in NWDS
http://scn.sap.com/community/pi-and-soa-middleware/blog/2013/02/15/graphical-mapping-support-in-nwds
Thanks a lot for this guide, Jocelyn. It was very helpful.
Is there any way to map elements[0..N] to complex types[0..N]?
Question of Timur is also interesting for me? How can I map such elements?
And how can I get flat structure from deep structure. I want to use reporting activity in bpm for "archiving" purposes but in reporting activity you can define only flat structure. Is it possible to flatten deep structure to map it into reporting activity?
To an extent you can with standard built-in functions - e.g. if your deep structure only holds one row - but again if you have a more complex scenario you may wish to create your own mapping expression to do this more easily.
I can imagine how to write such an expression - using lots of concatenates and gets, but is it possible to cycle over input structure - i didnt find any for or while expression. Is there any good manual or reference for SAP Implemented xpath?
Perhaps try the PI folks for that - XPATH is used in other areas and it should work the same in BPM is my understanding.
Hi Jocelyn,
Thanks a lot for this article. Very helpful. Special appreciation for the way you have expressed your satisfaction in writing this.
Excellent work. 🙂
Regards,
Sid
Superb one... will be handy one to go ahead... in BPM journry.. 🙂
Hi, Joceyln
Thanks for the blog. I am really struggling with the NWDS mapping when the datatypes are more complicated. Here is an example:
input_dt
records occurence 1...unbounded
pernr string occurence 1
plans string occurence 1
output_dt
pernr string occurence 1
plans string occurence1
I just want to get an element in the input_dt array and map it into output_dt. I couldn't figure out how to do it. I tried the following but it is giving me syntax error:
Please help. I am new to NWBPM but I found myself struggling with the tool on minimal complexity.
Thanks,
Jonathan.
Hello Jonathan,
You can click "CNTRL 1' to get the suggestion on how to fix the error. The error you might be facing can be fixed using 'Cast as' function.
Applying Quick Fixes in Data Mappings and Expressions - Composing Services - SAP Library
Thanks & Regards,
Dijesh Tanna
Agree - thanks Jonathan. We like "Cast as" a lot! 🙂
Hi VJ,
If you have questions relating to BPM generally please create a discussion post in the Business Process Management forum.
Rgds
Jocelyn
Jocelyn, many thanks for this article!
I am developing my first BPMs for process integration purposes.
This text is extremely useful.
Best regards,
Andrey
Late to the party here. We have tripped on an interesting "feature" and I cannot find documentation explaining what is happening and how to correct/work around it. We want the '#' to appear in a string.
We have a string data type (sVal). In the mapping we ideally want to append the string "1#" to the value. Except sometimes the sVal is NULL and concat fails. Here is a progression of what we've entered:
First off a plain and simple constant:
But we actually want to concatenate the "1#" to whatever is there, so we code this:
Ok, so we need to test if the sVal is NULL and respond accordingly.
The editor really does not like that first '#' character and erases the entry. After some hacking around, we currently are doing this, but don't like it:
What's special about the '#' character? And how can we insert it?
Very very very late to the party Alex I am afraid. I no longer work in this area and cannot assist. I would suggest ask your question separately on answers.sap.com and hopefully someone who is currently working in this space can suggest something.