Python BPL in preview
Tags: python, bpl, tutorial, programming
Published: 2024-04-24 16:24:05

<h2>BPL from 10,000 feet</h2>
<p>BPL stands for Business Process Language.<br>This is an XML format for describing complex information orchestration interactions between systems.<br>InterSystems Integration engine has for two decades, provided a visual designer to build, configure, and maintain, BPL using a graphical interface.<br>Think of it like drawing a <em>process flow</em> diagram that can be compiled and deployed.</p>
<h3>An example: Make a cup of tea</h3>

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/faqsir7q51c9x8cp64jw.png)
<p>BPL components are added to Integration productions like any other built-in or custom business component.</p>

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/l8i6gfg6msnvlhhis1x9.png)
<p>Test example input and output</p>

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ev2l29agk72at8cxqwrl.png)
<p>There can be a mixed reception to using BPL diagrams from developers, who sometimes favor code-only business processes.<br>However when the solution experience is opened up to other skill sets in a team ( Analysts, Project managers, Testing and Support ),&nbsp; these diagrams become more accessible and visually self-describing than code comments. Simply more people can read and understand a high level picture than follow code. It reduces need for developer time to explain an existing solution. A BPL diagram is the technical summary that is always up to date.<br>Visually:</p>
<ul>
<li>Evaluate what has been implemented</li>
<li>Understand how existing solutions could accommodate new business need</li>
<li>See testing collaboration dependencies, criteria, and scope</li>
<li>Remind and guide support intervention to deployed solutions</li>
</ul>
<p>A BPL diagram provides several important constructs:</p>
<table border="1" cellpadding="1" cellspacing="1" style="width: 500px;">
<tbody>
<tr>
<td>Request</td>
<td>An initial message type from an upstream Service or Process that initiates work. This could be for example an Admission message from a Hospital Information System</td>
</tr>
<tr>
<td>Response</td>
<td>An optional message type that can be populated during, to transmit to a final message to a downstream process on completion of other work.</td>
</tr>
<tr>
<td>Context</td>
<td>A collection of properties used to store state between logical activity steps within a BPL diagram</td>
</tr>
<tr>
<td>Activities</td>
<td>From assignment, running SQL, branching and decision logic to calling other production processes</td>
</tr>
</tbody></table>
<h3>Opening the designer from Management Portal</h3>

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/pr7yx6gr4os9u3zbg1qy.png)
<h2>Considerations for Python in BPL</h2>
<p>An essential principle for adding the new Python capability to BPL is:</p>
<div style="background: rgb(238, 238, 238); border: 1px solid rgb(204, 204, 204); padding: 5px 10px;"><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Empower existing BPL solutions to be incrementally enhanced with new Python functionality<br>&nbsp;</div>
<p>Consider a single BPL process that interacts with 5 different external systems. If a python only BPL approach had been taken, a complete existing BPL rewrite and retest would be unavoidable.</p>

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/klyk7vnq2y3dasbbl2bf.png)
<p>Even if a full BPL conversion from ObjectScript to Python was trivial, a full UAT retest of a solution may be challenging. This can be expensive in time and constrained by availability of upstream and downstream test systems and departmental domain specialists. So wholesale "converting to Python" may not be cost-effective to enhance existing BPL.<br>Therefore a Mixed-Language approach has been pursued.<br>Previously BPL could be implemented in only Object Script or Basic.<br>Now a BPL can have a top level Language of Object Script but within that is free to implement / configure specific activities in Python using language override. Facilitates access to available Python library capabilities for existing BPL.</p>

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/gqvojer7bmq9at0vtdy3.png)
<p>Language combinations:</p>
<table border="1" cellpadding="1" cellspacing="1" style="width: 500px;">
<tbody>
<tr>
<td>Main Language</td>
<td>Language Override</td>
<td>Comment</td>
</tr>
<tr>
<td>Object Script</td>
<td>&nbsp;-</td>
<td>&nbsp;</td>
</tr>
<tr>
<td>Basic</td>
<td>Not available</td>
<td>&nbsp;</td>
</tr>
<tr>
<td>Python</td>
<td>&nbsp;-</td>
<td>&nbsp;</td>
</tr>
<tr>
<td>Object Script</td>
<td>Python</td>
<td>Mixed</td>
</tr>
<tr>
<td>Python</td>
<td>Object Script</td>
<td>Mixed</td>
</tr>
</tbody></table>
<p>New main language option for Python</p>

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/x9o4ztpivafeubvi9yaa.png)
<p>New Language Override for Activities to mix Object Script and Python.</p>

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/xw2rsujc1ok0kdkve3h7.png)
<p>BPL diagrams now include a new Python Language Icon. A discrete but familiar hint&nbsp; where Python language is used by activities. Useful during incremental development, but also helps guide future enhancement / support queries. This icon will appear whenever the respective Activity Language Override is set to Python.</p>

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/1r6zpqzfcby153qmruzv.png)
<h2>Python Import statement reuse</h2>
<p>Expressions for Activities in the designer have limited space. For example:</p>

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/j7hn8z3tip5tweep9s8n.png)
<p>In Python the expectation is to leverage some library. However expressions and conditions have previously been short.<br>Therefore in the General Tab of the BPL, there is a new import section for python import statements.<br>Behind the scenes the imports are automatically federated to the context for each Python expression or code activity.</p>
<ul>
<li>So this is providing reuse by managing common import statements in one place</li>
<li>Keeps Python expressions short</li>
</ul>
<p>Additionally when code is deployed to a production system there is a chance that a custom or third party python library is not available. In that case a special error is written to the normal integration event log for the support team.<br>For example: import library missing in production</p>

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/s1lfaem1tmtwp0ggvjt1.png)

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8yzuditmmq96h55kemd1.png)

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/h28z3bxvgd34l4h7zcnd.png)
<p>When a Python library is missing, by default the business process will be terminated by integration engine. However the support team can find it useful to handle specific errors in a particular way, while a longer term remediation is provided. With this in mind, the Python Import has a specific error that can be handled by standard production settings. For example:</p>

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/cepcmkgawvw593rttrpp.png)
<p>This catches the import error and writes a warning to the integration event&nbsp; log. Keeps BPL process running in production.</p>

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/4kuotb3i7wcureme39ts.png)
<p>Reply Action "S", suspends the current message and moves on to next message. Keeps process running.</p>

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8bn1ovif4a1fgbfdvvk7.png)
<h2>&nbsp;</h2>
<h2>Code happens</h2>
<p>Instead of discouraging Python code activities, thought has gone into making Python code entry in the BPL designer more productive.<br>Behind the scenes, each Python code block is wrapped by a Python Try-Except that returns a specific integration error.<br>In a similar way to code imports, support can manage python runtime code errors by configuring reply code action E#2603.<br>This allows alerting reporting to differentiate between package import ( DevOps) and run time ( developer code ) errors, for support to engage the right second-line resource for resolution. ie:<br>Example: A Code Activity in Python that will throw a divide by zero error at runtime.</p>

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/35dx8wneee94xbci2qbw.png)
<p>Configure process to suspend message to handle when runtime error occurs:</p>

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ppc9b6k3d7fgad6s87wv.png)
<p>Example of error detail captured in Integration Event Log</p>

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/5d12t7v3lb57stt5g6mg.png)
<p>&nbsp;</p>
<h2>Code Indentation</h2>
<p>The BPL designer helps normalize the character used for indentation. This is necessary to wrap developer code in try-except blocks.<br>So if code is copied and pasted into the designer, the indentation character will be normalized to single whitespace, which keeps Python compilers happy.<br>The designer provides forward auto-indentation, as you type, to assist the entry of Python code.<br>For example the following code can be entered without using the space-bar key to indent.</p>

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/3lbr4ktypaltq1agjta0.png)
<p>If code indentation is incorrect, the designer validates during save and points out which code line has the problem.<br>This indentation validation is provided both in the Activity panel and the pop-out Value Editor.</p>

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/pt9dn6nlajymh99zff6c.png)
<p>The validation error shows:</p>
<ul>
<li>The source code line number with the problem</li>
<li>The actual source code</li>
<li>The Python syntax error</li>
</ul>
<p>&nbsp;</p>
<h2>Code switching ( Object Script to Python )</h2>
<p>Object Script uses a single "=" operator for both equality test and assignment.<br>Where as Python uses "=" for assignment and " == " for equality test.<br>To mitigate this kind of language context switching problem, the Python code is validated for well formed syntax so any helpful error guidance is displayed through the editor.<br>Example: Python suggests use of " == " instead of "=".</p>

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/vpwu73rxdc87re1pukyq.png)
<p>The error shows:</p>
<ul>
<li>The source code line number with the problem</li>
<li>The actual source code</li>
<li>The Python syntax error and possible remediation.</li>
</ul>
<h2>IRIS Classname and Method name spell check and hinting</h2>
<p>There is no intellisense prompting for Classname and Method names.<br>Therefore the editor validation has been extended to trap and suggest correct names when the Python code is saved.<br>This should reduce number of save / compile operations during development, reduce incremental testing and give more confidence in code quality.<br>The meaning of spell check in this context is to help with US versus UK common spelling differences.<br>For example consider the word "Color" in US is spelled "Colour" in the UK.<br>Class and method names are case sensitive and these are validated on save.<br>Example: Wrong capitalization in class name.</p>

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/l6w2ks26tp7279wnkrqm.png)
<p>Example: Using "s" instead of "z" in method name.</p>

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6dlrnb4j38f716v2nuf4.png)
<p>Substitution hint operations:</p>
<table border="1" cellpadding="1" cellspacing="1" style="width: 500px;">
<tbody>
<tr>
<td>Name sequence partial</td>
<td>Match hint suggestions</td>
</tr>
<tr>
<td>$ or _</td>
<td>%</td>
</tr>
<tr>
<td>ise</td>
<td>ize</td>
</tr>
<tr>
<td>tor</td>
<td>ter</td>
</tr>
<tr>
<td>cie</td>
<td>cei</td>
</tr>
<tr>
<td>our</td>
<td>or</td>
</tr>
<tr>
<td>1</td>
<td>l</td>
</tr>
</tbody></table>
<p>The detection of numeric "1" for substitution letter "l" is quite difficult to notice manually.<br>If IRIS classes or method are missing, these will be flagged.</p>
<p>This behavior works whether single or double quotes are used to specify Classnames in Python code.<br>The validation skipped for single and multiline comments, so it doesn't get in the way of code entry iteration.<br>Single line ignore:</p>

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ump9tyx23rq057jvheq8.png)
<p>Multiline ignore:</p>

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ao6rew6wgh7h4jht4q27.png)
<h2>Code activity variables</h2>
<p>The designer provides Context tab to configure the type for request, response and context base, and context properties.</p>

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/4ha88b2ybgeifc4itzi6.png)
<p>The following variables are in scope for Python to use in code and expressions:#</p>
<table border="1" cellpadding="1" cellspacing="1" style="width: 500px;">
<tbody>
<tr>
<td>Variable Name</td>
<td>Type</td>
</tr>
<tr>
<td>process</td>
<td>Ens.BusinessProcess</td>
</tr>
<tr>
<td>context</td>
<td>Ens.BP.Context or subclass</td>
</tr>
<tr>
<td>request</td>
<td>%Library.Persistent or subclass</td>
</tr>
<tr>
<td>response</td>
<td>%Library.Persistent or subclass</td>
</tr>
<tr>
<td>status</td>
<td>Ens.Util.PyByRef</td>
</tr>
</tbody></table>
<p>These can discovered in generated code and are used like any other embedded python method.<br>Note that methods may be generated on both the thread and context classes.</p>
<p>The status variable is backed by a new Integration type PyByRef. This allows status values to be passed back to the integration BPL handling code.<br>To manually set status to a new error message for example in Python code:</p>
<pre>status.value=iris.cls('%SYSTEM.Status').Error(5001,"My custom error message")</pre>
<p>Notice that "iris" package is availble in python code / expression without explicit import. This is provided automatically by integration BPL handling ie:</p>
<pre>import iris
import traceback</pre>
<p>Python capable BPL activities:</p>
<ul>
<li>Alert</li>
<li>Assign</li>
<li>Code</li>
<li>Trace</li>
<li>If</li>
<li>Case</li>
<li>Branch</li>
<li>Milestone</li>
<li>While</li>
<li>Until</li>
</ul>
<h2>Some change to be aware of</h2>
<p>The BPL schema now supports a new attribute for LanguageOverride</p>
<p>The web application csp static file for supporting the BPL designer have changed to support new Python editing and validation capability.</p>
<h2>Conclusions</h2>
<p>Whether object script or Python or a mix is chosen for integration implementation, BPL can make the solution more accessible and supportable to a mix of skill types and teams.<br>BPL is about delegating the container of code, that would normally be a class, to the integration engine in order to focus more on activities representing the business domain problem.<br>The Python import reuse helps simplify action expressions. This automatically gives error handling that helps to inform the support team and manage workarounds for missing Python dependencies in production.<br>The designer helps via validation on save, to enter quality Python code blocks and expressions by highlighting the location of detected problems and where possible provide a syntax or IRIS type name spelling code hint.This should reduce iterative testing and improve first draft code productivity during implementation.</p>
<p>To further explore Python BPL capabilities, check out the preview on <a href="http://containers.intersystems.com" target="_blank">containers.intersystems.com</a></p>

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/gnkjbnexuwnb6yamqznl.png)
<p>&nbsp;</p>