Tuesday, April 30, 2013

Cast Iron Version

Cast Iron Version

IBM has released a new version of CIOS version was released on 04/30/2013.  See the Release Notes for more information.

What do you need to know about this Release?

This is a FixPack release, it rolls up the prior iFix releases including several fixes for security vulnerabilities as well as numerous runtime and studio bug fixes.

You can get the new release here.  For more information on minor version upgrades see this post.

Monday, April 29, 2013

QT010: Using the IfThen Activity in Cast Iron Studio

Quick Tip #010: Using the If..Then Activity in Cast Iron Studio

Most Cast Iron developers are probably already familiar with the If..Then Activity however there may be some things that you didn't know about it.  The If..Then activity allows you to incorporate conditional logic in your orchestration and only execute certain activities under certain conditions.  When you drag an If..Then activity into your orchestration you can place activities that should only be executed under certain conditions inside the If branch of the If..Then activity.  You may also place activities that should only be executed if the condition is false into the Else branch of the If..Then activity.

Manipulating the Branches

An If..Then activity can have multiple branches each with their own logical test for execution, you may add a branch to an If..Then activity by right clicking in the outer gray box and choosing the add if branch.  You can delete branches by right clicking the if (or else) icon and choosing delete.  (Note if you delete the else branch you may add it back by right clicking inside the gray box and choosing add else)  The logic of each branch behaves like an if(){} else if() {} C or Java statement, not like a switch or case statement.  That is to say that each condition is evaluated from the top down and the branch with the first condition to evaluate to true is executed and processing continues after the If..Then activity.  If none of the conditional expressions are true, then the Else branch is executed (if one exists). You may reorder branches by right clicking on the If icon for the branch and choosing Go Up or Go Down to move the chosen branch up or down in the order of precedence.

Add a branch to an If..Then by right clicking inside the outer gray box and selecting Add "If"

Defining the Logic for If..Then Branches

The logic for an If branch is essentially defined using XPath syntax.  You may use the builder to define your logic or you may click the Advanced button and define the logic as a free form string.  Note that switching back and forth may cause issues because you can create expressions in advanced mode that cannot be expressed with the builder.  Note: if you need to define the order of operations you can use advanced mode and use parens around your expressions to define how the expression should be evaluated.

An example of using advanced mode and parens to change the order of operations.

Using the Builder

The builder allows you to create a set of boolean expressions tied together with the AND and OR logical operators.  Each expression contains a left hand side an equality operator and a right hand side.  Both the left hand side and the right hand side allow you to click an elipses button to choose a field from a variable defined in your orchestration or you may set a static expression.  If you set a static expression, if the expression is a string type be sure to encapsulated it in single quotes.  If it is a boolean use the true() or false() XPath functions to ensure that it is properly evaluated.  You may also use other XPath functions and constructs in your expressions for example a common pattern to determine whether or not an element is null you may want to ensure that the tag is present and that the value is not the empty string.  To do this use a count function to count the number of instances whether the value is not equal to the empty string such as: 
The above example uses both an XPath function (count) and an XPath predicate to determine whether or not an element is null.  You can use other functions such as starts-with, substring, etc to build even more complex expressions.

There are several equality operators available via the drop down.
You can add multiple conditions tied together with AND/OR logical operators.

Monday, April 15, 2013

QT009: Using Shared Variables in CIOS

Quick Tip #009: Using Shared Variables in CIOS

What is a Shared Variable?

In CIOS a shared variable is a variable that is "Shared" across all jobs for a given orchestration.  By assigning a value to a shared variable in the right side of a map, that value will be accessible by all other jobs of that orchestration.  Like all variables in CIOS shared variables are persisted in the event of power loss.  Shared variables are only cleared when an orchestration is stopped via the WMC.

Run Orchestration Jobs Sequentially

When using a shared variable in an Orchestration, the option to run all jobs in a single instance is automatically checked.  (In prior versions this option was called Run Orchestration Jobs Sequentially)   It is not possible to read and write a variable simultaneously, therefore running jobs in a single instance will ensure the consistency of your shared variables because there is no simultaneous access.

Why Use Shared Variables?

Shared variables are a powerful concept and enable numerous use cases, we'll highlight a few of the most common:

Sequence Numbers

You can use shared variables to generate sequence numbers for files, database records, etc.  By simply creating a shared variable and incrementing it each time you need a new value you can easily generate sequence numbers.
Tip: It is important to make sure that you have a way to initialize your sequence number by reading the highest existing value, using a configuration property or by some other means because you may need to reset the sequence or advance it.

Last Updated Date

If you are polling for changes in a resource and for any reason are not using one of the polling connectors, you may need to keep track of the last record that was successfully processed.  A shared variable is a good way to keep track of such values.  Again, you will want to make sure that you have a way to manually set this date on startup or change the data in order to reprocess records.


Shared variables can also be used to cache values such as a session key for a web api.  You can cache any xml document so its possible to cache complex structures such as a lookup table.  Note that jobs will run sequentially for performance reasons you should be careful when to use this option vs caching values in a database or external system.

Monday, April 1, 2013

QT008: Quick References for Mapping with JavaScript

Quick Tip #008: Quick References for Mapping with JavaScript

JavaScript is a simple scripting language that uses a syntax that is derived from the Java Programming Language.  Because of its simplicity and pervasiveness, JavaScript is commonly used for mapping data in middleware platforms such as IBM Cast Iron and Boomi.  In this post we will run through a quick example in CIOS provide a couple of resources from around the web for more in depth study of JavaScript.

A Quick Example: Parsing Email Addresses

In this example, we will present a brief example for parsing the first email address out of a given string in Cast Iron.  Cast Iron provides a number of built in custom functions for performing numerous tasks.  These functions are available in the functions tab and can be dragged into any map to translate inputs from the source side to outputs on the target side.  If there is no suitable built in function you may write a custom function using JavaScript.  To do so, click the Add New Custom Function . . . link at the bottom of the functions tab.

There are two tabs, the first allows you to configure the name and return type as well as the input parameters for your custom JavaScript function.  For this example the return type will be a string and we only require one string input, which we will call input.  Click next to define the body of your custom function.

In Cast Iron, you define the body of a custom JavaScript function.  You can pass an arbitrary number of string, boolean, or number parameters to your function, but you may only return a single value.  Because of the nature of JavaScript functions, it is actually possible to nest functions within your function should you need to get creative.  See some of the tutorials discussed below for other advanced features of the JavaScript language.  In this example we will use the string function match() to apply a regular expression to the input string.  The match function applies a regular expression to a string and returns an array of all matches to the regular expression.  We create a variable to store this array and test to see if it contains at least one value.  If it does we return the first match, otherwise we return null.  It is as simple as that.  You may use your custom function in any map as you would use any of the built in functions.


Mozilla - The source for JavaScript, JavaScript was originally included in the Netscape Browser which became the the Mozilla Project.  Mozilla is the authoritative source for JavaScript and contains numerous resources including documentation and tutorials.
W3 Schools - W3 Schools provides tools and documentation for web technologies such as CSS, HTML, and of course JavaScript.
regular-expressions.info - One of the best guides on the web for working with and learning about regular expressions.