Category Archives: Articles

OCI Interface Integration into your eShop via Punch-Out from SAP/SRM

If it comes to integration of eShops like Magento, OXID or even your cusom made eShops into a corporate buying infrastructure using SAP, you need to deal with the SRM module (Supplier Relationship Management) using the OCI interface.

On the shop side we had a Gambio eShop in this case, which is a commercial fork of XT-Commerce. At first we checked if there where any affordable ready-to-use modules available. We found some for around 1500-2000EUR with additional (unclear) service cost. To be honest, what we found looked a bit outdated and after some contacts with the responsible sales people not even very trust worthy. After skipping over the documentation we decided to integrate OCI on our own – the custom hacked way. After all, it is just simple HTTP.

If you check the documentation and your first thought is, you could easily do it using cURL at the checkout, be warned – OCI does NOT work using a cURL call from a remote server! We did it this way and failed the first try as soon as we discovered how OCI mechanics really worked (see below). The documentation is a bit ambiguous in that respect.

The main problem is, that only your customers customer (!) with whom you have to co-operate closely and directly can help you through testing. People there are not that technical, even though their job title says so. They own the SRM testsystem (you don’t) and you always have to ask for a punch-out-click in order to find new insights integrating OCI into your eShop. It took us many weeks instead of a couple of minutes due to vacation and corporate politics and overhead. Finally we integrated an all-encompassing logging for each minor step and response to reduce the communication to ‘please click again’ – and bamm, 3 days later we had a bunch of logging information powering the next development step.

Here is a SVN diff showing all files we added or modified in the gambio release with a description what we modified:

Changed files in original Gambio distribution:
M  checkout_shipping.php (added optical info, we're in OCI-mode)
M  includes/configure.php (added a switch to work on live and development server)
A  includes/modules/oci/oci.php (Main functionality wrapped in a class)
A  includes/modules/oci/ociParameters.php (Configuration with additional parameters for SRM)
A  includes/modules/oci/logger.php (Own simple logger to see what happens during test calls)
A  oci_out.php (exit sending real hidden html form onLoad via JavaScript, redirecting to SRM)
M  admin/includes/configure.php (added a switch to work on live and development server)
A  oci.php (entry point for calling Punch-Out incl authentication)
M  checkout_confirmation.php (added optical info, we're in OCI-mode)
M  checkout_process.php (redirect to exit oci_out.php instead to successpage after checkout)
M  templates/EyeCandy/module/checkout_shipping.html (added optical info, we're in OCI-mode)
M  templates/EyeCandy/module/checkout_confirmation.html (added optical info, we're in OCI-mode)
M  templates/EyeCandy/module/checkout_success.html (added optical info, we're in OCI-mode)


OCI mechanics work like this:

At first the purchase department selects a supplier in their SRM. As soon as the order agent starts shopping, SRM performs a ‘Punch-Out’, which opens a browser window with a URL like this one:

http://your-php-eshop.com/oci.php?Z_EMAIL=ebp%40xxx%2ede&password=password&userid=8&BYPASS_INB_HANDLER=X&BYPASS_OUTB_HANDLER=X&OCI_VERSION=4%2e0&OPI_VERSION=1%2e0&returntarget=_top&HOOK_URL=https%3a%2f%2ftestsystem7%2esrm%2ede%2fsap%2fbc%2fnwbc%2fsrm%2f%3fsap-nwbc-action_url%3d%252fsap%252fbc%252fwebdynpro%252fsapsrm%252fwda_l_fpm_gaf%253bsap-ext-sid%253dKMDRyFbbH6pX0000mAWtxW–KMDRyVbbH6pX0000mAWtxW–%253fsap-ep-tstamp%253d20130419102708%2526sap-wd-tstamp%253d20130419102708%2526sap-ep-version%253d7%26NavigationTarget%3dportal_content%2fnwbc_back%26NavMode%3d3%26UsePost%3dTrue%26SAPSRM_RESUME_ID%3dSAPSRM_OCI%26sap-nwbc-has_post_params%3dX%26sap-client%3d010%26sap-language%3dDE%26sap-nwbc-node%3dresume_appl

This call goes to your /oci.php. It needs to do the following:

  • It checks if there is a customer/user in your eShop that can be authenticated with the userid, password and Z_EMAIL parameters. If so /oci.php logs the user in to the eShop. Of course you have created the customer maually before. Send the SRM owner the values of the parameters for their punch-out and test if auto-login works via punch-out.
  • /oci.php must remember the value of the parameter HOOK_URL in the session. It is only valid for this purchase and the contents of the shopping cart must be posted back to this URL – it is your value for your form’s action attribute. Remember: It can NOT be done via cURL.

The user is now navigating your eShop and fills his shopping cart and proceeds to the checkout and clicks the final checkout button. The purchase is saved in the shopping application by your eShop system. Instead of redirection to the shop-success page a hidden form is created (see OCI documentation for fieldnames and fixed field values necessary) with the shopping information for the SRM and it is sumbitted immedately by javascript. You need to intercept the redirection to the success page and redirect to your /oci_out.php instead providing this form. The action url has been handed over via the HOOK_URL parameter on punch-out.

The hidden form looks like this:

<!– OCI autosubmit –>
<script type=”text/javascript” language=”javascript”>
document.getElementById(“srm_form_submit”).click();
</script>

<form id=”srm_form” action=”https://testsystem.srm.customer.com/sap/bc/nwbc/srm/?sap-nwbc-action_url=%2fsap%2fbc%2fwebdynpro%2fsapsrm%2fwda_l_fpm_gaf%3bsap-ext-sid%3dKN2O27IP8fdX0000mAWtxW–KN2O2NIP8fdX0000mAWtxW–%3fsap-ep-tstamp%3d20130419104715%26sap-wd-tstamp%3d20130419104715%26sap-ep-version%3d7&NavigationTarget=portal_content/nwbc_back&NavMode=3&UsePost=True&SAPSRM_RESUME_ID=SAPSRM_OCI&sap-nwbc-has_post_params=X&sap-client=010&sap-language=DE&sap-nwbc-node=resume_appl” method=”POST”><code> <input name=”NEW_ITEM-LINE[1]” type=”hidden” value=”00001″ />
<input name=”NEW_ITEM-DESCRIPTION[1]” type=”hidden” value=”Herren Fleece-Jacke Langley Rot” />
<input name=”NEW_ITEM-LONGTEXT_1:132[]” type=”hidden” value=”Herren Fleece-Jacke Langley Rot” />
<input name=”NEW_ITEM-QUANTITY[1]” type=”hidden” value=”1″ />
<input name=”NEW_ITEM-UNIT[1]” type=”hidden” value=”C62″ />
<input name=”NEW_ITEM-PRICE[1]” type=”hidden” value=”41.87″ />
<input name=”NEW_ITEM-CURRENCY[1]” type=”hidden” value=”EUR” />
<input name=”NEW_ITEM-PRICEUNIT[1]” type=”hidden” value=”1″ />
<input name=”NEW_ITEM-LEADTIME[1]” type=”hidden” value=”21″ />
<input name=”NEW_ITEM-VENDOR[1]” type=”hidden” value=”16222″ />
<input name=”NEW_ITEM-VENDORMAT[1]” type=”hidden” value=”287{2}5{1}23{5}17″ />
<input name=”NEW_ITEM-MATGROUP[1]” type=”hidden” value=”41010000″ />
<input name=”NEW_ITEM-LINE[2]” type=”hidden” value=”00002″ />
<input name=”NEW_ITEM-DESCRIPTION[2]” type=”hidden” value=”Pique Polo Safran” />
<input name=”NEW_ITEM-LONGTEXT_2:132[]” type=”hidden” value=”Pique Polo Safran” />
<input name=”NEW_ITEM-QUANTITY[2]” type=”hidden” value=”1″ />
<input name=”NEW_ITEM-UNIT[2]” type=”hidden” value=”C62″ />
<input name=”NEW_ITEM-PRICE[2]” type=”hidden” value=”16.95″ />
<input name=”NEW_ITEM-CURRENCY[2]” type=”hidden” value=”EUR” />
<input name=”NEW_ITEM-PRICEUNIT[2]” type=”hidden” value=”1″ />
<input name=”NEW_ITEM-LEADTIME[2]” type=”hidden” value=”21″ />
<input name=”NEW_ITEM-VENDOR[2]” type=”hidden” value=”16222″ />
<input name=”NEW_ITEM-VENDORMAT[2]” type=”hidden” value=”112{2}4{1}1{5}16″ />
<input name=”NEW_ITEM-MATGROUP[2]” type=”hidden” value=”41010000″ />
<input id=”srm_form_submit” style=”display: none;” type=”submit” value=”Go” />
</code></form>

After this form has been submitted, SRM generates another page also including a hidden form, additional internal information and lots of JavaScript logic also with auto-submit. Please note: a) The array counter must start at 1 not at 0. And b) note the syntax of the longtext field.

The page is generated and ‘executed’ on the server side of the SRM system! This is the reason why it could not be done via cURL: The action to the HOOK_URL opens a page on the SRM server submitting another (!) form which finally writes the purchase to SRM – not your initial POST. It also closes the browser window for the order agent. If SRM can not close the browser window something went wrong.

Frameworks…

Find out interesting thoughts and experiences about the selection and usage of a frameworks for your projects in this set of slides ‘Living with Frameworks‘ by Stuart Herbert, Technical Manager at www.gradwell.com.

You will learn about:

  • How frameworks save you time (=money) and ensure quality but can also waste resources if applied in another way the framework was intended to be used.
  • The importance of the framework guru role.
  • That a chosen framework and architecture should be strategically introduced (top-down).
  • Introduction and proper use of a new framework has a steep learning curve.
  • Legacy code and the parallel maintenance hassle.
  • Refactor early, refactor often, perform regular code reviews with the framework guru.
  • Frameworks will not fix bad practice (specification, quality, no training).
  • Your framework should fit your overall development plan and practice.
  • Training your staff in your framework is a means of building your team.
  • Headcount on projects has increased, means more teamwork, organisation around needs to mature too.
  • Importance of upgrades and backward compatibility.

Planning Poker for better Estimates

There are many essays and articles on ‘Planning Poker’ out there. So I do not need to repeat the principles here. By checking out the recommended links (and folloups and others from your own research) you need to understand the following:

  • What a story point of a project looks like and how you generate those story points in advance. Remember, your estimation should include design, coding, testing and delivery. In Planning Poker it is your goal to come up with estimates to those those story points with your team.
  • The process of how one story point is estimated using the Planning Poker card deck and how to narrow down your team members’ estimates through discussion of the ‘played’ estimates.
  • The background of the card deck used and why there are such odd numers in it.
  • The effect all this will have to your project and the team.

The important thing is not the single estimate as such, but rather the open discussion among the the team members in advance, the mix of different perspectives and the collection of confidence in the team’s estimates. If the team is not able to get confident for an estimate you better recheck the user story in question and clarify it – possibly again with the customer. The more confident the team in one estimate is (=no big spread in single estimates of the team members), the less unclear ‘assumptions’ have been made in the estimate itself. This, in the end, reduces the overall risk (friction and interruptions) during the actual project and most importantly makes your customer happy.

Recommended articles and links:

The Dreyfus Model for Skills Acquisition

Inspired by an article at InfoQ (http://www.infoq.com/articles/better-best-practices) I discovered an interesting model, which explores the nature of learning in an interesting way: The Dreyfus Model for Skills Acquisition.

In essence it describes how people acquire skills over time, what supports them best in their progress and how they behave with their growing knowledge. Five levels are described:

  • Novice – Needs to be told exactly what to do. Has very little understanding of the context to base decisions on. Wants frequent quick wins, needs regular feedback and reassuring messages. Learns best by abstract and context-free rules.
  • Advanced beginner – Is familiar with the basic steps but still needs guidelines to follow. This is the stage at which a learner is most dangerous – he knows enough to think he knows a lot. Uses more sphisticated rules than a beginner. Treats all aspects with equal importance.
  • Competent – The learner begins to understand his tasks and starts seeing longer term consequences. He can figure out a sequence of tasks in order to accomplish a goal. Learns best when given hierarchical goal-based targets accompanied by some rules. *
  • Proficient – An ability to analyse a situation and seperate what is most important develops. The learner is experienced enough that solutions start to just appear and are seen in the wider context. The person can rely on his judgements. He follows higher-leveled maxims. Decision-making feels less labourous. Searches inspiration, loves challenges and is open to constant learning.
  • Expert – Works mainly on intuition and is rarely wrong. Involves critical reflection on his intuitions, rather than goal-based planning. Loves to meet and exchange thoughts with other experts. Best practices are seen as a necessary evil. Does not rely on rules and maxims. Has a vision of what is possible.

* Most people don’t get beyond the competent level at most skills. Progression from Novice to Competent is linear. The model points out that one can become competent at something just by doing enough repetitions, but learners who want to reach beyond this point need to develop and maintain an active will to become proficient. It takes many years of dedicated effort to become an expert in a particular field.

Here you will find an application of the Dreyfus Model to software development with Ruby on Rails: http://pragmaticstudio.com/dreyfus

Agile Version Control Mechanism

I came across a nice paper explaining best practices in using version control (Subversion) in multiple agile team projects. The lack of concept, clarity and existence of understandable rules often leads to confusion in teams I work in.

Branching
Regular merging down from the stable mainline (catch-up) and merge and copy up (publish) of stable features from develoment branches.

Here are some of the rules I found useful:

  • Each branch (even the trunk) has an owner and a policy.
  • Agree on a common definition of Done = releasable (means Unit tested and integration tested).
  • Trunk is the Done branch, it should contain releasable code at any time.
  • Branch policy = Unit tested code, new releasable features or bugfixes.
  • Don’t combine different release cycles on a single branch.
  • Create additional branches as seldom as possible. Only create a new branch when you have something you want to check in, and there is no existing branch that you can use without violating its branch policy.
  • Whoever touches the trunk is responsible for ensuring that the whole trunk stays releasable – including all previous functionality.
  • Synchronize your code with the work branch continuously (daily).
  • Code conflicts and integration problems should be discovered as soon as possible.
  • Resolve conflicts on the branch that is least stable. Whoever checks in first wins.
  • Merge from your work branch to the trunk on a regular basis, for example whenever a story is done. Don’t wait until the end of the sprint.
  • Merge down, copy up.

Revision flow
Flow of changes around the mainline of your project.

Taken from the paper “Agile version control with multiple teams” of Henrik Kniber which you should read if you are not already an expert in branching and tagging across teams.