Overview

Skill Level: Intermediate

Requires knowledge of Javascript/HTML

This recipe will provide an example of using a coach view to programatically implement html form based data submission (important for integration with systems that use form based input) including the attachment of BPM business data.

Ingredients

  • BPM with BPMUI toolkit [formerly¬†known as SparkUI]¬† ¬†
  • (not required, but example utilizes¬†components such as the onclick configuration property, which are unique to this toolkit)

Step-by-step

  1. Create some buttons

    To submit the data we are going to need to trigger some kind of event. The easiest way to do that … make a button. Doesn’t have to be this color, doesn’t have to be this shape, but just drag and drop some BPMUI buttons into the coach. In our example we will be configuring the “OK” button.

     

    a

  2. Write the code

    The majority of the code we will be writing is inside the properties of the “OK” button (Properties > Events > On click)

     

    A lot of that code will need to be described later in the example, but for now focus on the key piece starting on line 6.

     

    b

  3. Creating the form

    In line 6 we see the creation of the “form” object. This is just a run of the mill empty HTML form saved to a javascript variable (but not yet added to the screen).

    We set its method (POST), we set its action (the url we want to post to), and set the target to “_blank” so it opens up in a new tab if you would like (it’s HTML black magic, for more information see¬†https://stackoverflow.com/questions/5709590/submit-a-form-in-a-new-tab)

    This sets the foundation for the form, concluding with its submission on lines 18-19 (adding the form to the document, submitting it, and removing it)

    To actually add data into the form, we need to attach some HTML input objects to the form object we created previously. The primary attributes of the input object we need to set are type, name and value. The type is set to hidden so we never have to see it.

    In the example above I used a for loop to iterate over 2 arrays of data (one for the names and one for the values) but that was just for simplicity. Just remember to append the input objects you create onto the form once they are created.

    Lines 1-4 are the actual creation of those data arrays. Line 1 is simple enough, we just add a bunch of strings for the names.

    But what about lines 2-5?

  4. Integrating with static BPM business data

    The easiest way to grab business data is when the coach loads, using the BPM javascript “{{}}” notation.

    Add a “Custom HTML Object” to your coach and click on it to edit its HTML

     

    d

     

    Here we set up some javascript tags (<script> </script>), and define some global functions.

    It’s as simple as it looks. BPM replaces the sections in blue above with the corresponding business data when the page loads (as strings)

     

    The very important downside though is: this happens when the page loads

     

    That is why this section is titled integrating with static business data. Once BPM perfoms the replacement at page load, it is set in stone until a new coach is loaded to replace it. For those who know PHP, it’s kind of like that.

    Assuming the business data is not going to change until the user loads a different coach though, this isn’t a problem at all. But if we want to work with user input that is likely to change client-side, the process is a little more complicated….

  5. Integrating with dynamic BPM business data

    BPM client-side coaches have an interesting quirk. All the the business data is on the server side, but all the HTML/Javascript is being rendered client side.¬†By default, they can’t talk to each other.

    Coach views deal¬†with this by making you “bind” business data, one by one, to coach views in process designer; and then they make a bunch of complicated ajax calls in the background to get/update the data when things change.

    But that sounds hard, so instead lets make those coach views do the hard work for us:

    Lets go ahead and add some more elements to our coach. I would recommend using BPMUI output text coach views because it will let us bind to a string, and we can easily set its visibility to “None”¬†if you don’t want to look at it when the coach renders. Essentially these will just act as placeholders for all the data we want to add to the form later.

    Below you see the 2 new coach views I added (element1 and element2). I bound them to some business data (also conveniently named element1 and element 2)

     c

     

    Once the business data is bound to the object. We can programmatically target those elements to get their stored information, even if it was changed after the page loaded!

    We target BPMUI coach view elements using: page.ui.get(“<Element ID>”).getText()

    If “page” sounds new, you are correct. It is defined by BPMUI internally. For more information see (https://salientprocess.zendesk.com/hc/en-us/articles/211965868-Control-Addressing-)

  6. Putting it all together

    So looking back at the code we wrote previously it should all make sense now:

    Line 1 defines the list of form data names

    Line 2 returns an array of static business data (defined in a custom html coach view) (step 4)

    lines 3-4 appends 2 more values to it (step 5)

    Line 5 gets the url target using the same method that we used to get static business data on line 2 (step 4)

    Lines 6-9 creates and configures the form object

    Lines 10-17 create input objects and append them to the form

    Line 18 adds the form to the coach

    Line 19 (which is really 2 lines of code) submits the form (opening it in a new tab), and then removes the form from the coach to cleanup.

    b

  7. Next steps

    For more information regarding BPMUI (or SparkUI as it was originally known), I recommend the book linked below: “Deliver Modern UI for IBM BPM with the Coach Framework and Other Approaches”,¬†specifically chapter 4 starting on page 153

    http://www.redbooks.ibm.com/redbooks/pdfs/sg248355.pdf

     

     

Join The Discussion