Table of Contents

Search

  1. Preface
  2. Overview, Downloading, and Installing
  3. Administration API
  4. Identity Service API
  5. Screenflow Programming and SDK
  6. ActiveVOS WSHT API
  7. Embedding Request Forms in Standalone Web Pages
  8. XML-JSON for Process Central

7. APIs, SDKs, and Services

7. APIs, SDKs, and Services

Process Request Forms

Process Request Forms

Process request forms are essentially HTML forms with JavaScript that are used to invoke a process. The skeleton markup of a request form shown below illustrates various elements used by the form. The actual form may be a little more detailed and is targeted for use with jQuery and jQueryUI.
<html> <head> <!-- header content --> </head> <body> <!-- Main DIV that contains all markup related to this request form UI --> <div id="processRequestForm$ID"> <!-- DIV that contains UI related request form and data entry --> <div id="processRequestForm$ID"> <div>Display Name UI</div> <!-- container for the form UI controls --> <div> <form id="loanApplicationInputForm$ID"> <!-- actual form content, for example: --> First Name: <input id="firstName$ID" name="firstName" value="" size="50" /> <br/> Last Name: <input id="lastName$ID" name="lastName" value="" size="50" /> <br/> </form> <!-- Send button --> <input type="button" id="sendRequest$ID" value="Send Request" /> </div> </div> <!-- DIV that contains html to show the results after submitting a form (invoking a process). Note this DIV is initially hidden, and only shown when response data needs to be displayed. --> <div id="responseContainer$ID" style="display: none;"> </div> </div> <!-- Script --> <script type="text/javascript"> // <![CDATA[ // JavaScript to implement JSON process invoke // ]]> </script> </body> </html>
All elements used in the form have an
id
attribute. The
id
attribute is used as the primary selector when you need to access various elements within the HTML document. Also note that the
id
attribute values that are generated end with the
$ID
suffix (for example
processRequestForm$ID
in
<div id="processRequestForm$ID">
).
In cases where Process Central needs to display the same form more than once, the element
id
attribute cannot be duplicated with the same values. When the forms are used with Process Central, the forms server automatically replaces the $ID suffix with a unique value. This allows the form to be cloned and used in the same HTML document. For example, at runtime Process Central may have two loan request form instances
<div id="processRequestForm_01">
and
<div id="processRequestForm_02">
(note that
$ID
has been replaced with
_01
and
_02
in this example).
The JavaScript that is generated with the HTML form (in the
<script />
block at the end of the form) is enclosed in a function for scoping and takes the general structure shown below:
// Function that encapsulates the form script. var AeRequestForm$ID = function() { // variable defining the name of service var mServiceName = "humantaskProcessDemoService"; // // internal functions: psuedo code shown below for brevity // // This function is called when the form is loaded. function documentReady() { // initialize and populate UI here. // code to bind the SendButton click event to invoke _submitRequest() function // also invoke _setupValidation(); } // function is called (by documentReady() ) function _setupValidation() { // optional code to setup and initialize your form data validation } // Function returns the JSON data structure for this operation function getInputRequest() { // code that creates JSON object. For example: // var json = { "loanProcessRequest": {...} }; // return json; } // function called when the Send Request button is pressed. function _submitRequest() { // 1. validate the form by calling avcform_validate(). // 2. var jsonReq = getInputRequest(); // 3. get form UI data and populate jsonReq object // 4. serviceUrl = AE_AJAX_SERVICE_UTIL.getActiveVOSServiceUrl("JSON/" + mServiceName); // 5. invoke json request via: // AE_REQUESTS_UTIL.postJSON(serviceUrl, jsonReq, _showResponseCallback, ....); // } // validate the form function avcform_validate() { // check form date and validate (e.g. verify required fields have data etc.) // return true if user submitted data is valid } // Called by postJSON(..) code in _submitRequest() function. function _showResponseCallback(aJsonResponse) { // called to display response from a json invoke } // Called by postJSON(..) code in _submitRequest() function. function _showFaultCallback(aJsonFault) { // handle fault } // Called by postJSON(..) code in _submitRequest() function. function _communicationErrorCallback(aStatusCode, aError) { // error handler code } } // The jQuery 'ready' event is fired once the page (form) is loaded // and ready for processing. $(document).ready(function() { // Create Request Form JavaScript object var requestForm = new AeRequestForm$ID(); // initialize form requestForm.documentReady(); });
When the form is downloaded by Process Central so that it can be displayed to the user, the browser renders the HTML form and begins to execute the JavaScript associated with the form (see
$(document).ready(..)
). The entry point is the
documentReady()
function in the form JavaScript object that is responsible for initializing and displaying the form.
Deploying Request Forms
The HTML forms are deployed to the Process Server resource catalog on the server and are accessible using the
http://host:port/active-bpel/avccatalog/FORM_LOCATION
URL where
FORM_LOCATION
is the location of the form with in the
caXStalog
. (for example,
project:/proj_name/form/request/loanform.html
). In order for Process Central to discover these forms, an
.avcconfig
(Process Central) configuration file must also be deployed to the catalog.
<ns:avosCentralConfiguration xmlns:ns="http://schemas.active-endpoints.com/avc/2009/07/avoscentral-config.xsd"> <!-- All Requests are defined in requestCategoryDefs element --> <ns:requestCategoryDefs> <!-- requestCategoryDef is represented as a Folder in Central. Add additional requestCategoryDef elements to add more 'Folders'. --> <ns:requestCategoryDef id="" name="Loan Applications"> <!-- A folder (category) can have one or more Requests (requestDef). Each requestDef has a unique id, display name, description and HTML form location. Central uses this location hint to download the actual form and display it. --> <avccom:requestDef id="loanapp" name="New Car Loans (&lt; $15K)"> <!-- You can restrict who sees this Request by specifying one more roles. The value should be a group name or a username. For example, this request is visible only to members of group 'group_A' and user 'jsmith'. --> <avccom:allowedRoles> <avccom:role>group_A</avccom:role> <avccom:role>jsmith</avccom:role> </avccom:allowedRoles> <avccom:description>Application for a small automobile loans (under US$15,000.00)</avccom:description> <avccom:formLocation>project:/LoanApproval/form/request/loanForm.html</avccom:formLocation> </avccom:requestDef> </ns:requestCategoryDef> </ns:requestCategoryDefs> </ns:avosCentralConfiguration>
When a user logs in, Process Central fetches an aggregate list of Request categories and requests that the user can access (based on
<avccom:allowedRoles>
) and displays the folders and requests.