Quick Links to this Easelly series : Part One / Part Two / Part Three
So, in this part of the Easelly series we will look at how to integrate Easelly with Oracle Intelligent Advisor. For this integration demonstration we chose to use the legacy PHP Custom Control concept. In today’s Oracle Policy Automation, most of the customization of the user experience is driven through the JavaScript Extensions – which we regularly demonstrate on this site.
But there are situations where the Custom Control concept which originates from the pre-August 2016 versions, is still a good choice. In this case, we need a Custom Label, with a link. But the link is to be displayed once the server-side has generated a PDF file. So it is a good choice at the moment. For the language, PHP is easy to use, has thousands of examples, and can handle both XML and JSON.
Let’s look at the code then walk through it step by step. The code is also in the shop, for free, because this code viewer does not do a very good job of handling all the characters in the file.
// Copyright Intelligent-Advisor.com
// For entertainment and education purposes only
// Example step by step PHP Custom Control and integration with Easelly Infographic
// Requires Easelly API Key
// Thanks to Johanna and Vernon at Easelly easel.ly
//Set up a few key variables
$url = "https://www.easel.ly/pages/generatePDF";
// This is your API Key
$api_key = "XXXXXXX";
// This is the URL of your base infographic in Easelly
$canvas_id = "https://XXXX/easel.ly/all_easels/XXX/XXX";
// OPA data is passed into the PHP file as a urlencoded XML post header. Decode it
$myOPAData = $_POST["opa-session"];
$decodedOPA = urldecode ($myOPAData);
// Now we can manipulate it as XML
$final = new SimpleXMLElement($decodedOPA);
// Get the XML Nodes that represent our OPA Attributes using XPath queries
$account_name = $final->xpath("//*[@id='account_name']");
$product_one_name = $final->xpath("//*[@id='product_one_name']");
$product_one_avail = $final->xpath("//*[@id='product_one_avail']");
$product_one_margin = $final->xpath("//*[@id='product_one_margin']");
$product_one_trans_lost = $final->xpath("//*[@id='product_one_trans_lost']");
// Get Text of each OPA Attribute
$account_name = strip_tags($account_name[0]->asXML());
// Some Product Names have & in them so convert the characters properly
$product_one_name = htmlspecialchars_decode ((strip_tags($product_one_name[0]->asXML())));
$product_one_avail = strip_tags($product_one_avail[0]->asXML()) . "%";
$product_one_margin = strip_tags($product_one_margin[0]->asXML());
$product_one_trans_lost = strip_tags($product_one_trans_lost[0]->asXML());
// Build Object Array for the Easelly REST API. Each object represents an Easelly tagged item, mapped to an OPA attribute.
$myJSONdata = new stdClass();
$myJSONdata->id = "https://XXXXX/easel.ly/all_easels/XXXXX/XXXXX";
$myJSONdata->objects = array();
$myobjectfinal = new stdClass();
$myobjectfinal->tag = "account_name";
$myobjectfinal->type = "textbox";
$myobjectfinal->text = $account_name;
$myobjectfinal->fill = "#f9d423";
array_push($myJSONdata->objects, $myobjectfinal);
$myobjectfinal = new stdClass();
$myobjectfinal->tag = "product_one_name";
$myobjectfinal->type = "textbox";
$myobjectfinal->text = $product_one_name;
$myobjectfinal->fill = "#6bb38e";
array_push($myJSONdata->objects, $myobjectfinal);
$myobjectfinal = new stdClass();
$myobjectfinal->tag = "product_one_avail";
$myobjectfinal->type = "textbox";
$myobjectfinal->text = $product_one_avail;
$myobjectfinal->fill = "#f9d423";
array_push($myJSONdata->objects, $myobjectfinal);
$myobjectfinal = new stdClass();
$myobjectfinal->;ag = "product_one_margin";
$myobjectfinal->type = "textbox";
$myobjectfinal->text = $product_one_margin;
$myobjectfinal->ill = "#ffffff";
array_push($myJSONdata->objects, $myobjectfinal);
$myobjectfinal = new stdClass();
$myobjectfinal->tag = "product_one_trans_lost";
$myobjectfinal->type = "textbox";
$myobjectfinal->text = $product_one_trans_lost;
$myobjectfinal->fill = "#ffffff";
array_push($myJSONdata->objects, $myobjectfinal);
// Convert the Object to JSON
$myJSONdataobject = json_encode($myJSONdata);
//Call Easelly with our JSON Object and Get Response
$context = stream_context_create(array(
'http' =>array(
'method' =>'POST',
'header' => "apiKey: {$api_key}\r\n".
"Content-Type: application/json\r\n",
"Accept' : application/json\r\n",
'content' =>$myJSONdataobject)));
$response = file_get_contents($url, FALSE, $context);
// Check Output
if ($response === FALSE) {
echo("\r\n");
die('An Error Occurred');
}
// Use a timestamp as the filename
$time = time();
$fileoutputname = $time . ".pdf";
file_put_contents($fileoutputname , $response);
// Show the Link to the User for clicking to access the generated file
?>
<a target="_blank" href="https://intelligent-advisor.com/main/external/<?php echo $fileoutputname ?>"
>Click Here</a>Walk Through
The Easelly code has been broken down into it’s constituent parts – for learning purposes. Of course there are many areas that would be rewritten in a professional example, but this will help non-coders understand what is going on.
- 1-15, Set up some basic stuff like the URL to your infographic. In the final part of this series, I’ll show you how to build a graphic and tag it correctly with the OPA attribute.
- 17-25 The Oracle Policy Automation Custom Control integration passes the session data (your attributes and their values) into the PHP page as a series of XML nodes. So we need to get that XML and make sure we can read the parts we are interested in.
- 29-25 We strip the attribute values out of the XML, and in one case, because the OPA attributes contain special characters like “&” we make sure they display properly.
- 38-80 Overly simplified for the purposes of demonstration, we build a JSON object using standard objects and arrays, to create the JSON structure that Easelly is looking for. In the next part of this series I will show you where to get it.
- 84 Convert the Object into a JSON Object
- 88-106 Call Easelly with our API Key and JSON Object
- 107 – End Process the output and draw the Easelly link for the user
Summary
So you can see the integration is fairly simple in this case – the PDF is generated before the user reaches the link, so the link should respond straight away. And we chose PDF but Easelly also can generate PNG for example, if you wanted to embed it directly as an image.
In the third part of this series, we will show you how to get Easelly to tag your infographic so you can use it in an Oracle Policy Automation integration.