Teaching How to Build an Oracle Process Cloud Service to send Notifications

Recently I had to build a Human Workflow that sent SMS and Voice notifications using Oracle Process Cloud Services. The notifications are based on Twilio APIs exposed in Oracle Integration Cloud Service (ICS) and Oracle Application Container Cloud Service (ACCS). After 10 minutes I was done. I was amazed how quickly I managed to create this Business Process using Oracle Platform as a Service (PaaS), so I decided to blog it to show others who are in similar situations.

The diagram below is a quick snapshot of what I will be covering in this blog:

Big thanks to Alessia Sacchi for helping me understand Oracle Process Cloud Service and making possible writing this blog!

These are the functional requirements that I am going to cover in this blog:

  • Create a remotely accessible REST API that can trigger this process. This API will accept:
    • number
    • to be sent
    • whether it is SMS or Voice
  • Once the REST API is invoked, it will pass it on to an Oracle Process Cloud Service workflow as a new task that will require a human intervention
  • The Human intervention will either ACCEPT or REJECT the process task. It can also provide the ability to update:
    • The number of the notification
    • The to be sent
    • The to be used, i.e. whether to send an SMS or a Voice message (Text-to-Speech)
  • If the process task is accepted, it will then determine based on the if it is a “Voice” or “SMS” Notification
  • It will use a PCS Integration connector to invoke the right REST API
  • The target mobile number will either show the SMS or Ring and when the call is accepted, a configurable voice will read the message to the user.

Note: If you want to learn how to create the backend Twilio based APIs, refer to this other blog we made some time ago: https://solutionsanz.blog/2016/11/22/teaching-how-to-integrate-with-twilio-apis/ or feel free to contact any of the authors in Solutions ANZ.

Creating a Business Process using Oracle Process Cloud Service

  • Enter the name of your new “Space” and click on Create

  • Click on your new “Space” and click “Create” button again, but this time select “Application”. Enter a sensible name and description and then click on Create.

  • A brand-new Application landing-page will be displayed:

  • Let’s begin by creating a Business Object to be used for our notification. Business Objects are used to encapsulate canonical object that encapsulate the fields that define a specific business outcome. In this case, our notification. Click on “Business Type

  • Click on the big white plus icon and select the type as New
    Business Object. Enter the name of your Business Object and then click Next.

  • Create 3 new attributes by click on the blue plus icon. Your attributes should look like this:

  • Click on Finish. Your new Business object will be shown

  • Now, let’s create the form that we are going to use to let the Human intervention to either APPROVE or REJECT, as well as to update if needed the coming channel, to and message fields.
  • Click on the Form option in the left menu. An empty Form will appear.

  • Click on the white plus icon and select New Web Form. Enter a sensible name and Description and then click on Create.

  • A new JET based web form palette will be shown. You can drag and drop any action from the palette into the canvas.

  • You can also, use an existing Business Object and drag it into the canvas. This will allow you to create the form structure that will let the Human intervention to reset the entered fields (channel, to and message). Scroll to the bottom and find the Business Object type that you just created. It is under the section called Business Type Palette.
  • Drag and drop your business object into the centre of the page. Automatically, your Business object will generate a web form.

  • Select each element in the form and change the labels and other properties if required.

  • Once you are done, click on the Save button at the top.
  • Then let’s create the REST Integration connectors that will allow us to call the Twilio based backend services that ultimately send SMS or Voice calls.
  • Click on the Integrations option in the left menu.

  • At this point, you can create either SOAP or REST based web services and then simply reuse them as part of your process. For now, we want to consume REST APIs, so let’s select “Create a Rest Connector”

  • Enter the name of your REST Connector and the Base URL. Then click on Create.

    Notice that if the same base is shared across multiple REST APIs, you just have to create 1 REST Connector and then simply reuse it as many times as needed during your business process.

  • An empty REST Connector configuration will be displayed. Now it’s time to add the resources.

As mentioned at the beginning of this blog. If you have not created the backend Twilio based REST APIs that allow you to send SMS and Voice call (Text-to-speech), you can refer to this other blog that we wrote some time ago that explains how to build quick REST APIs exposing Twilio APIs. https://solutionsanz.blog/2016/11/22/teaching-how-to-integrate-with-twilio-apis/

  • Click on Add to create the first resource. Then click on the resource and give it a sensible name. Also define the specific path location for this REST resource. For example, in my case, this is my SMS resource and it will follow the structure: {baseUrl}/sms

  • Click on Add button to add a new Operation. Select the HTTP Method that is required by your REST API. In my case it is POST. Once it appears, click on it in order to configure the Request and Response payloads.

  • While still on the Request tab, click on the blue plus in front of Body to define the structure of the incoming request.
  • Give it a sensible name and enter a sample JSON payload for the request.

  • Now click on the Response tab and similarly, set the sample JSON payload for the response.

  • When you are done, click on Apply or you will lose your changes. You will be sent back to the Resources page.

  • Your first resource is available. Now repeat the same steps to create a second resource, but this time point to your “VoiceCall” REST API.
  • Your two resources should look like this:

  • Click on Save.
  • Now we are ready to create our Business Process. For this click on Process in the left menu of your application.

  • You have multiple templates to start from. Click on the white plus icon or the link to Start from scratch.

 

  • Enter a Name, Description and select Message as the Pattern. Then click on Create.

  • First let’s create the actual flow and then we can implement it. I prefer this approach, so that different teams can be involved in different phases. That is, while a less technical team, can be focused more on the actual business flow and then this can be given to an IT focussed-team to implement it.
  • This process is very simple, the actions from the Palette that we are going to use are the following:
    • A Message based trigger (already setup if you followed the last step)
    • Human Approve to either APPROVE or REJECT the business tasks
    • Exclusive Decision Point to determine if the Channel is set to SMS or Voicecall
    • Two Service invocations to call either the REST SMS API or the REST Voicecall API

  • Now, let’s implement each step. First click on the Start icon and the on the burger icon that appears next to it. Select Open Properties

  • Click on the pencil icon for Define Interface. Add three arguments: channel, to and message – All of them of type String.

  • Click on the Start icon again, burger icon and this time select Open Data Association. A new Data Mapping will be displayed.

  • We are going to create the mapping from the incoming Message attributes to a new Data Object, which type matches the Business Object that we created earlier.
  • Click on the blue plus icon on the top right corner. Enter a sensible name and select Business Type – Make sure to select the Business Object that we had created previously. Then click on Add.

  • Now we are going to match each of the attributes on the left to our new Data Object attributes on the right. Each time you drag and drop each side, a new line will drop allowing you to enter a new mapping.

  • At the end, your mapping should look like this:

  • Now, let’s implement the Human Task. Click on it and select the burger menu -> Open Properties.

  • The User task properties will open at the bottom of the page.
  • Click on the Form glass magnifier icon to search for the form that you created previously.

  • Configure anything else you need. Then click on Save.
  • Click the User task icon again and this time go to burger menu -> Data Association.
  • Once the Data association window opens, expand on the left the Process Data > myNotificationDO and on the right notificationApprovalWebForm > myNotificationBO

  • Similarly, as you mapped the Message trigger action. Map these fields accordingly. At the end you should see something like this:

  • Once you are done, remember to click on Apply.
  • Back in your Process flow, click on the Exclusive gateway link that goes from it into the Voicecall service call.
  • At the bottom click on the Condition pencil and set a rule that says if the channel is “voicecall”… Notice that you don’t have to type it. Simply expand your Data object (myNotificationDO) and click on Insert Into Expression. Then just type at the end the logical comparison.

    It should something like this:

  • Then click OK.

  • Click on the other flow after the Exclusive gateway. It is a non-conditional flow. You can identify it because it has a small backslash (\) on it. Being a non-conditional flow means that we don’t have to assess a condition, in other words, it is the “else” part of the condition (exclusive gateway) saying that if the channel was not voicecall, then it must be SMS.
  • Once you clicked on it, make sure to untick the Conditional Flow box in tits properties window.

  • Click on the VoiceCall service -> burger menu and click on Open Properties.

  • Down at the bottom, open the drop down menu under Type and select Service Call.

  • Then, click on the pencil icon to point to the Voicecall REST API that we implemented previously.
  • Select the option REST. Search for MyNotificationAPIs integration. Set the SendVoiceCalls Resource and postSendVoiceCalls as the Operation.

  • Then click OK. Your Voicecall configuration should look like this:

  • Click back on the Voicecall -> Burger menu -> Open Data Association this time. The Request Data Association will be displayed.
  • On the left tree, expand Process Data -> myNotificationDO and on the right tree, expand Voicecall -> body

  • Map the and fields accordingly.

  • Click on the Output tab at the left corner.

  • Expand the left tree to show the bodyOutput -> message. Then on the right as you can see you have not created any other Data Object that will host your result. Let’s create one by clicking on the blue plus icon next to Data Objects.
  • Call it responseDO and set it to type String.

  • Then do the data association.

  • Don’t forget to click Apply at the end or you will lose your changes. It will lead you back to the process flow.
  • Finally, click on the SMS action -> burger menu and click on Open Properties.
  • Similarly as you did previously, set the Implementation, but this time to the other SMS REST connector.

  • Your SMS Service call Properties should look like this:

  • Now, click again on the SMS action -> burger menu -> Open Data Association. Set the Request and Response Data association accordingly.
  • The Input should look like this:

  • The Output should look like this:

  • We are done with the process implementation. Before we publish it, click on the Validate button to ensure you don’t have any trouble.

  • Make sure you don’t get any error or warning. If you do, check the error and try to resolve it. If you have any trouble, feel free to contact the author of this blog for assistance.

  • Now, it’s time to save and publish your Application. Click on Save and Publish it, by clicking the buttons accordingly:

and

  • The Publishing option will open a window. Enter a sensible description and click on Publish.

  • Once your application is published, proceed to deploy it in the Cloud. You can simply click the Deploy button on the top right, but I want to show you another way to do it via the Management console, which is a link on the top right corner. Click on the Management link.
  • Under My Server section, click on the burger menu and select Deploy.

  • Select your Space, your Application and select “Last Published Version” when it asks you to Select a snapshot.

  • We don’t need to customise any SOAP endpoint, so simply click on Validate. Make sure the Validation is successful.

  • Click on Options. Enter a Revision Id and click on Deploy.

  • Click on Deploy.

  • Make sure you get a successful message. Then click on Finish.

  • Click on Configure.
  • In the left menu, under Organization select Manage Roles.

  • Search for your Application. You will find 3 instances of it: Analytics Viewer, Process Owner and Process Reviewer. As you can appreciate, only the Process Owner is associated with an account. Associate the other 2 as well.

  • Select MyNotificationApplication.Analytics Viewer. Then on the right panel, click on Add Member.
  • Select search based on Users and click Search. Find the user that you want to associate this role with. Select it and click OK.

  • Click on Save to save your change.
  • Repeat the same with MyNotificationApplication.Process Reviewer.
  • Make sure your 3 Application roles are associated with a user.

Testing your Oracle Process Cloud Service

In order to test a Business Process Application, normally you do it by triggering a business process workflow by initiating a web form. This time I want to teach you something different. I want to show you how to initiate a new Human workflow task by invoking the actual Administration APIs that come with Oracle Process Cloud Service. For more information, please refer to the Oracle PCS API reference: http://docs.oracle.com/cloud/latest/process_gs/CPRRA/

I am going to send a REST API using Postman. You can use your favourite REST client.

To send a REST API that triggers a new Workflow Task, we need to construct the JSON payload. For this, a simple way you can programmatically achieve this is by running APIs.:

  • Run a GET API towards the Process Cloud Service to retrieve the definition of all Applications. The API is as follows:

For example: https://oracleprocessc-[IDENTITY_DOMAIN].process.[AVAILABILITY_ZONE].oraclecloud.com/bpm/api/3.0/process-definitions

Remember to add the following Headers:

  • Content-type –> application/json
  • Authorization –> Base 64 (Basic Authentication) of your user name and password. Use your Oracle Process Cloud Service admin user account.

  • Check the result and search for your new Application definition

 

  • Now, based on this definition construct that you receive, build the following JSON payload:
{
“processDefId”:”ENTER_YOUR_PROCESS_DEF_ID“,
“serviceName”:”ENTER_SERVICE_NAME“,
“operation”:”start”,
“payload”:”<ENTER_YOUR_BUSINESS_OBJECT_NAME xmlns=’http://xmlns.oracle.com/bpm/bpmobject/BusinessData/ENTER_YOUR_BUSINESS_OBJECT_NAME‘>

<ENTER_ARGS_1>[sms|voicecall]ENTER_ARGS_1>

<ENTER_ARGS_2>+MOBILE_GOES_HEREENTER_ARGS_2>

<ENTER_ARGS_3>MESSAGE_GOES_HEREENTER_ARGS_3>

ENTER_YOUR_BUSINESS_OBJECT_NAME>”,
“action”:”Submit”
}

For example, in my case:

{
“processDefId”:”default~MyNotificationApplication!1.0~MyNotificationProcess”,
“serviceName”:”MyNotificationProcess.service”,
“operation”:”start”,
“payload”:”voicecall+61449588440Hello World from Oracle Cloud”,
“action”:”Submit”
}
  • When ready, POST this message to the following API:

API: https://oracleprocessc-[IDENTITY_DOMAIN].process.[AVAILABILITY_ZONE].oraclecloud.com/bpm/api/3.0/processes

Remember to add the following Headers:

  • Content-type –> application/json
  • Authorization –> Base 64 (Basic Authentication) of your user name and password. Use your Oracle Process Cloud Service admin user account.
  • After you send it, make sure to get a state set to OPEN. This means that there is a new Human workflow task ready for you to consume.

  • Go back to the Workspace console and click on Tasks at the top

  • You will find at the top the Task that you have created. Click on it.

  • The form will be displayed containing the 3 attributes that you sent.

  • Feel free to modify the To number or message. When you are done, click on APPROVE at the top.
  • You will notice that the “to” mobile used in the demo will ring and a voice will read the given text…

  • You can click on Tracking and validate that your instance was successful.

  • Try sending another message, but this time send sms as the channel. You will get a message like this:

  • Finally go to Tracking again and search for your task flow. You will notice that it went through the SMS channel.

I hope you found this blog useful. If you have any question or trouble, feel free to contact the author of this blog.

Thanks for your time.

Author: Carlos Rodriguez Iturria

I am extremely passionate about people, technology and the most effective ways to connect the two by sharing my knowledge and experience. Working collaboratively with customers and partners inspires and excites me, especially when the outcome is noticeable valuable to a business and results in true innovation. I enjoy learning and teaching, as I recognise that this is a critical aspect of remaining at the forefront of technology in the modern era. Over the past 10+ years, I have developed and defined solutions that are reliable, secure and scalable, working closely with a diverse range of stakeholders. I enjoy leading engagements and am very active in the technical communities – both internal and external. I have stood out as a noticeable mentor running technology events across major cities in Australia and New Zealand, including various technology areas such as, Enterprise Integrations, API Management, Cloud Integration, IaaS and PaaS adoption, DevOps, Continuous Integration, Continuous Automation among others. In recent years, I have shaped my role and directed my capabilities towards educating and architecting benefits for customers using Oracle and AWS Cloud technologies. I get especially excited when I am able to position both as a way to exceed my customers’ expectations. I hold a bachelor degree in Computer Science and certifications in Oracle and AWS Solutions Architecture.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s