VBCS: Calling a REST endpoint

Oracle Application Builder Cloud Service (ABCS) has been renamed to Visual Builder Cloud Service (VBCS), so this blog series about ABCS continues as a blog series about VBCS. In this blog I will explain how to call a REST endpoint and create a Business Object based on this REST Service. There are several ways to do this, but I will start with the most basic one. The data that we get from the REST service will only be presented (read-only), we will not send updates/posts to the REST endpoint.

To call the REST endpoint, we will use a template provided within VBCS that we are going to adjust just a little bit. We can do the editing of the 2 javascript files within VBCS itself. This is a temporary solution, Oracle is working on making these configurable and even more easy to use for users.

To give a speaker overview in our application, we have a REST service that returns a list of speakers speaking at the Tech17 Conference. Once again, this is just a demo service and a demo application. For the real Tech17 information (the Conference was held on June 15 & 16), visit www.tech17.nl. The REST endpoint we are using looks like this:

Now in the left hand side menu within VBCS we have to go to the Extensions, this is a submenu under Application Settings.

This will bring up the Extensions page, where we will create a new Business Object Provider (BOP).

We name this extension speakers and put it in the package nl.ogh.eventapp.

There are several templates to help you with some basic code that you can use. In this case we want to use the REST BOP example. The REST BOP example template will generate some javascript code in which we will make a few minor changes to call our REST endpoint.

The template generates an overview and some example code. Within the Sources tab, we need to open the REST Operation Provider. We need to configure the correct endpoint, this happens within the code. I adjusted the baseURL variable to point to the speakers REST endpoint.

After this we need to configure the RESTEntityProvider to enter the details about the data that gets returned by the REST service. As you can see, we need to enter a singular and plural name as well as a description of the service, after which we get an array of properties. These properties are the fields we are going to use on the page within VBCS.

I identified the ID fields as the KEY field and the other fields (Name, Country, Biography) as Text field.

Now that we have specified the BOP with the endpoint and the properties, we can go to the Data Designer to specify the Service based on this BOP.

After going to the Services page, we see there is no resource yet and create a new Service by clicking on the green ‘Add Service’ button.

We choose to define a service based on the Catalog, since we have the extension/BOP predefined.

Now a wizard will be opened. In the first step we can see the speakers BOP we provided, so we select it.

In the ‘Business Objects’ step, we need to select Speaker, after which we enter a Name and Description.

In the Fields step, we can decide which Available Fields we want to drag & drop to the Selected column, in this case all of them.

In the final Test step, you can select the resource on the left and it will call the REST Service. If correctly configured you will see the data displayed as below.

When done, you can see the result in the Data selection of your Data Object. It will display the data retrieved from the REST Service.

Now that we have our Data Object in place that communicates with the REST Service through the BOP, we can start using this data on our page. When going back to the page designer, I select the Speakers page in Edit mode, after which I drag & drop a Listview from the component palette on the left hand side into the main area of the Speakers Page.

As you can see a wizard is being started. In the first step I can select the Business Object for the Listview, which I want to be the Speakers Object we just created. In the next step we can select the layout, in this case a one column layout will be sufficient.

In the mapping selection we can drag and drop the Fields on the Page.

We only need to drag and drop the Fields in the first row. The Design mode of VBCS already shows you the result of this action within the several rows.

Now our Speakers page is created. To see the changes in the live version, we need to change the security of the speakers page to anonymous access and redeploy the application as version 1.4.

When checking the live page after redeployment, we can see the Speakers page within the application.

As you can see, it is quite easy to use read-only data within VBCS. The feature can still be improved with some configuration instead of letting the users edit the javascript files. However, this definitely is no rocket science either.

Jarvis Pizzeria: The Document Only Delivery Process

Let's have a look at the Delivery Process of the Jarvis Pizzeria. In this blog post, we will explain the functionality of the Delivery Process with the help of the Document Only feature when creating a new process.

When we create a new process we can select the option ‘Document Only’ in the Create Process popup.

Document Only processes are for descriptive use only and are not part of the working and running application. It is a good way to setup a process to discuss with your peers, users, architects or anyone else. One of the advantages of starting a document only process is that it will not check whether it is valid or not, since it is for descriptive purposes only.

In the Process Overview within the Application, we recognize the Document Only process with the subtle difference of having a dotted line within the thumbnail instead of a solid line.

The flow of the Delivery Process is as follows, we start with a service call to obtain the order information. The process will then decide whether it is a takeout or delivery order. When the order is a takeout, a Human Task will be generated to announce the order to the waiting customer.

In case the order needs to be delivered, we will use a decision model to determine what kind of vehicle to use for the order, then a Human Task will be generated to do the delivery.

While the customer is enjoying their pizza, the process continues. It will retrieve the customer info with a service call after which we will check if the customer is a regular at Jarvis Pizzeria. If so we will add points for the order to the customer account. If not, we will try to contact the customer with our amazing offers for regulars.

Last but not least we will wrap up the delivery, by sending some information back to the system about the delivery.

 

That’s quite the story, but luckily we can show this process in a picture as well. The Document Only Process of the Delivery Process looks like the following picture. As you can imagine, that is a lot easier to talk about than the describing text.

When we start to implement the process, we first need to uncheck the Document-Only checkbox. For this we need to go to the Process Properties within the Process Editor. On the tab Implementation, you can uncheck the Document-Only checkbox.

This will result in a changed thumbnail as well in the Process Overview within the Application.

The Document-Only feature is an effective way to describe a process and to share where we are working on among each other as well as with the audience. It takes over some of the functionalities from the on-premises BPM Composer, without the hassle of sharing your assets with PAM (Process Asset Manager).

Jarvis Pizzeria: Import the 12c On-Premises Preparation Process

In the Functional description of the Preparation process we stated that we would describe all steps required to migrate a sample 12c preparation process to PCS. So let’s get started.

As a starting point, we have the 12c on-premises preparation process as exported application. A picture of the BPM process is shown below.

The first attempt: directly import the exported file in PCS.

In the Composer select Import Model from the hamburger menu at the top left corner.

An intro appears. Click next to continue.

Now we need to specify the source type. As we exported the project from BPM Suite 12c we select Oracle BPM Project (exp)

Select the export file and then click ok

This results in an error message. The export is made with a version that is not supported.

So a direct import of the export file does not work. So where do we go from here?

Our second attempt: let’s try to import only the BPMN file from the export.

Before doing this, we unzip the export file to make it possible to select the BPMN file.

Then we go back to the Import (see the first attempt steps) and now select BPMN 2.0 (bpmn) as the source file type. Select the BPMN file (the process model) and click next.

Since the file contains only one process model the next page is not as relevant. Just make sure that the PizzaPreparationProcess is checked. Click next to continue the wizard.

Now we have to select the naming convention to use. So let's try the most comprehensive one (<file><page><pool>).

Oops, that results in the not so beautiful process name ‘PizzaPreparationProcess-PizzaPreparationProcess’ (E.g. <page> would have resulted in the original process name).

When opening the process in composer, we come to the conclusion that this is not the kind of import we want.

The formatting is not pretty, all the lines are numbered and roles are created, but everything is linked to the same role. However, this was to be expected because we only imported the bpmn file and not the process_documentation.XML. There is still a lot to do in PCS to get this imported process running. So let's try something else.

Attempt three: Find out what changes in the export file are required to make it importable.

We found out that Andre Boaventura also did something similar. For details see his blog post.
With this blog at hand we started. To work around the version incompatibility we changed the version number (in file ProjectInfo.xml, we update the projectVersion from 20120601 into 20140730).
A retry of the import results in a ‘successful’ import. How successful we will find out.
What has been imported? As we can see, the process and also the used xsd-schema are imported.

When the imported process contains unsupported elements like Scripttasks or Complex Gateways it is not possible to open the process. In that case the following error message appears.

But the process contains only supported components and so it can be opened.

And we are lucky :-), also the Business Types can be opened.

But to be honest, we have tweaked it a bit on the on-premises side. Initially we used the following xsd-schema.

The Size and Unit elements are both of type String restricted by an enumeration. But it seems that imports of such enumerations are not supported (yet?). The xsd-schema was not imported automatically. So after removing the enumeration the schema was imported.

Note: It is possible to manually import an xsd with enumerations, but the elements which are associated with enumerations cannot be used in task screens.

So we're almost there. The 12c export does not contain the ADF Human Task screens. This makes sense because the PCS task screens do not support ADF. To get things working we still need to develop the task screens. That, however, is outside the scope of this post. The picture below is one of the screens that we used.

After creating the task screens we also had to complete the data mappings between the process and the tasks. As the Oracle PaaS Summer Camps VII in Lisbon this year has the BPM to PCS migration tool as a topic in the Process Cloud Service track, there will be an addition to this blog available soon.

Jarvis Pizzeria: Functional description of the payment process

Before we start preparing our pizza the order needs to be paid. With the implementation of the payment process we try to answer the following questions:

• How do the business rules work in PCS and how do they differ from their on-premises counterpart?
• What types of gateways do we have at our disposal?
• Do we have multi-instance subprocesses?
• How do we implement correlation?
• And more…

The business process that would fit most of our purposes would look something like the image below:

We start our process without a message, i.e. the payment process will be a reusable subprocess, according to the blog ‘Setting up the Jarvis 1.0 process’ where we explained the setup of our main process.

After the start we are going to determine which payment options would be at the customer’s disposal. Interesting to see is to what extent the web based version of the business rule implementation will be a copy of the business rules editor we have at our disposal in the on-premises versions of the BPM suite. Although that implementation is quite intuitive and straightforward, it definitely leaves room for improvements. Let’s find out!

The second activity will be a multi-instance subprocess where we will use the outcome of the business rules to start the available payment options. Although it is not clear from the picture, we are intending to implement the subprocess as a multi-instance parallel embedded subprocess (see the image below).

After starting the several payment options we have to wait for a callback of one of the payment options confirming the order has been paid. Obviously the event-based gateway is the component to use for listening to the several callbacks.

The observant reader might have noticed that using a parallel subprocess to make several service calls and subsequently use a single callback setup looks counter intuitive. We agree, but let's see what PCS is up to :).

There is also a timer connected to the gateway as we don’t want to wait forever for the customer to pay. After a timeout of the payment we notify the admin, here we want to try out the notification task mechanism of PCS, and end the process by throwing an error end event which will be caught by the main process as we have seen in the blog ‘Setting up the Jarvis 1.0 process’ .

After the gateway construction we will notify all the instances that we have started (a combination of creditcard, debit and deferred payment based on the outcome of the business rules) that the payment has happened in one of the available manners. These services have to listen to the event we throw and end themselves peacefully. This way we don’t end up with a bunch of orphan processes and we can experiment with the usage of correlations.