Conference Offers and Management API Samples

This API sample illustrates the rapid creation of data processing systems and a modern microservices architecture.
lac42
The following video demonstrates how to build a complete conference offer management system, which includes database creation, customizing a user interface (UI) using Data Explorer, and defining the business logic. These sample APIs illustrate the following systems integration:
  • Conference Offers:
     Partners extend offers to participate in conferences (talks and exhibits) by posting these offers to the Conference Offers microservice.
  • Conference Management:
     When managers approve conference participation, 
    CA Live API Creator
     sends a message to the Conference Management microservice.
You can explore these API samples in API Creator. On the APIs page, click the 
Learning Center - Example
 tile, then click the 
Example
 tab in the Learning Center. The high-level steps illustrate creating a microservice, starting from design to outcome.
The 
Conference Offers
 and 
Conference Management
 API samples illustrate the following capabilities:
Requirement
Shown By
Solution - Low Code Microservices
Business: Rapid creation of data processing systems
 
The 
Conference Offers
 processes the conference participation offers it receives from partners. It is created, from scratch, in under 20 minutes. Watch the video.
Low Code:
  • Automatic UI, using Data Explorer
  • Point-and-click API
  • Reactive business logic
Technical: Modern Microservices architecture
The 
Conference Management
 microservice illustrates a typical pattern of autonomous messaging service for message subscription and processing.
Microservice:
  • APIs
  • Kafka and MQTT messages
The 
Publish and subscribe to messages
 use case is demonstrated in this example.
For more information about this use case, see API Creator Overview.
In this article:
3
Business Requirement
The following roles do business with your company:
  •  
    Partners
     put on conferences, which consist of talks and exhibits. Partners extend offers to participate in conferences by posting these offers to the 
    Conference Offers
     API, providing a location and talk and exhibit options. The conferences include costs that the system must capture and persist.
  •  
    Organizers
     select talk or exhibit conference options, subject to a budget with the UI that is shown in the previous image.
  •  
    Managers
     approve conference participation, which alerts the conference management by way of an MQTT message, and sends a confirmation back to the partner. 
As part of the application economy, your company receives discounts if your interaction is digital. Also as part of the application economy, you needed the system yesterday.
Solution
The following diagram illustrates the solution that this sample provides:
  1. Partners post conference participation offers to the Conference Offers microservice (URL fragment: 
    conf-offer
    ). 
  2. Managers approve the conference participation (talk or exhibit) that organizers select using Data Explorer. 
  3. The 
    Alert Management - JSON Message
     event rule alerts the Conference Management microservice (URL fragment: 
    conf-management
    ) by way of MQTT messages.
  4. The Conference Management microservice includes a messaging service that subscribes to the MQTT messages and then processes them. Approved conference participation offers cause charges to be incurred. This microservice also optionally sends a confirmation message back to the originating partner.
    ConfOfferDiagram.png  
Install the Samples and Configure the Connections
 
CA Live API Creator
 includes the ConfManagement and ConfOffer databases. These databases are empty. Data is added as part of the validation process of this sample.
The 
Conference Offers
 and 
Conference Management
 API samples are included with the single-user demonstration package of 
CA Live API Creator
 that is based on Jetty and with the 
CA Live API Creator
 Docker container installation. No additional steps are required to load these APIs.
You can also load these API samples if you have installed 
CA Live API Creator
 on another Java container.
 
Click to expand steps...
 
Activate the Connections
 
For message operation, activate the connections for the API samples.
 
 
Configure the MQTT Connections
 
The samples run with a public MQTT broker. You can reconfigure the 
PublishManagementConnection
 and the 
ManagementConnection
 MQTT connections to use a different MQTT broker (for example, a locally installed broker).
 
Follow these steps:
 
  1. With the 
    Conference Offers
     API sample open, in the Manage section, click 
    Listeners
    .
  2. Click the 
    Connections 
    tab.
  3. Select the 
    PublishManagementConnection
     MQTT connection, select the 
    Active
     checkbox, and then save your changes.
  4. Click the 
    Parameters
     tab.
  5. If necessary, update the value for the 
    broker
     parameter to a different MQTT broker, for example, 
    tcp://<brokername>:1883
    , and then click 
    Save Parameters
    .
  6. Click 
    Reconnect
    .
    Your changes to the broker name are applied to the connection and your connection is restarted.
  7. Confirm that the connection is in the "Open" status.
  8. Repeat steps 1 through 7 for the 
    ManagementConnection
     MQTT connection that is in the 
    Conference Management
     API sample.
Your MQTT connections are configured.
Database Schemas
The Conference Offer Management system includes the ConfOffer and ConfManagement Derby databases.
ConfOffer
Sends message to
ConfManagement
  mktConfOffer.png  
Approval
==>
mktMgmt.png  
You can build these databases with your usual tools. Alternatively, you can "paint" your business idea using Data Explorer, which creates your application and your database. The following image illustrates how you can manage the content in a data source for a managed database (tables and fields) using Data Explorer in Author Mode:
  managed data.png  
For more information about how to create databases using Data Explorer, see Database Creation.
Conference Offers Microservice
As is typical for applications today, services must:
  • Process APIs (in the 
    Conference Offers
     API sample, process conference participation offers that partners post).
  • Persist the data with associated business logic.
  • Interact with other systems through messaging (in the 
    Conference Offers
     API sample, the 
    Alert Management - JSON Message
     event rule).
Partner Integration - Process Partner Posts
Define the 
PartnerPost
 resource for the 
Conference Offers
 API sample. The API definition chooses and renames the columns that match the API agreement. The following image shows the details for the 
Exhibits_List
 subresource:
  PartnerPost.png  
The 
PartnerPost
 resource saves the request payload for auditing and error-retry purposes by way of extended properties. The following code snippet shows the code for the extended properties for this resource:
{
"PersistTo": "PartnerPostAudit"
}
The 
ProcessPayloadOnRequest
 request event handler determines which resource to persist the payload by accessing the extended properties for the 
PartnerPost
 resource.
For more information:
Business Logic
The 
Conference Offers
 API sample uses the following reactive logic, which provides the behavior to roll up costs and check budget:
  ConfOffersRules.png  
Application Integration - Alert Management
Microservices architecture recommends that systems be autonomous, with decreased dependencies on other systems. This internal communication is by way of a message (rather than an API), so that the Conference Offers microservice functions even while Conference Management microservice is down.
The 
Alert Management - JSON Message 
event rule in the 
Conference Offers
 API sample implements this communication using MQTT messaging, as shown in the following code snippet:
if (row.Approved === true && row.Approved !== oldRow.Approved) {
var msgContent = logicContext.transformCurrentRow('ManagementAlert');
var result = SysUtility.publishMessage("PublishManagementConnection","MarketingCost", msgContent, null);
msgContent = logicContext.transformCurrentRow('PartnerConfirmation');
if (row.PartnerURL === null) {
print("No Partner URL, not sending this: " + msgContent);
} else {
SysUtility.restPost(row.PartnerURL, {}, row.PartnerAuth, msgContent); }
}
This code creates a message that is formatted for accounting using the 
logicContext.transformCurrentRow()
 method. It sends the message by way of an MQTT connection using the 
SysUtility.publishMessage()
 method.
The 
Conference Offers
 API sample includes the following versions of the alert accounting event rule:
  • The 
    Alert Management - XML Message
     event rule: Illustrates how to send JSON. It contains comments showing how to send XML, instead.
  • The 
    Alert Management - API
     event rule: Illustrates how to send using an API instead of a message.
Activate only 
one
 of the event rules.
You can explore the listener code in the 
Conference Management
 API sample.
Data Integration - Multi-database Logic
The previous code snippet also POSTs a message back to the partner, confirming conference participation. The request content is formatted by using the 
PartnerConfirmation
 table-based resource for mapping and transformation.
This resource integrates multiple databases. The 
MarketingProgram
 subresource is joined by a virtual foreign key, as illustrated in the following image:
  PartnerConfirmResource.png  
 
CA Live API Creator
 also uses this virtual foreign key to validate the marketing program. Further, this system defines 
conditional referential integrity 
(only required for approved conference participation offers), as illustrated in the following image of the 
Approval requires Marketing Program
 validation rule in the 
Conference Offers
 API sample:
  Screen Shot 2018-05-16 at 7.19.55 AM.png  
Validate the Conference Offers API Sample
 
Click to expand the steps...
 
Post Conference Data to an API endpoint 
 
As a partner, you want to post your conference data to the Conference Offers microservice. You can load sample conference data by posting it using a resource.
 
Follow these steps:
 
  1. With the 
    Conference Offers
     API sample open, in the Execute section, click 
    REST Lab
    .
  2. Select 
    Resource 
    as the endpoint, and then select the 
    PartnerPost
     resource.
  3. Enter data into the 
    Request Area
    .
    You can use the sample data that is in the Learning Center in API Creator. Go to the Learning Center, click the 
    Example
     tab, and then click the 
    Post Data
     step that is in the workflow. You might need to scroll down the page.
  4. Click 
    POST
    .
  5. Verify that the response received contains the 
    statusCode 201
     message.
    This message confirms that the data is posted.
 
View and Update Conference Selections
 
As an organizer, you want to select the talk or exhibit options that you want to attend for a given conference.
 
Follow these steps:
 
  1. In the Execute section, click 
    Data Explorer
    .
    Data Explorer opens in a new browser tab.
  2. Log in to Data Explorer.
    On the toolbar, 
    Entities
     is selected as the endpoint type in the endpoint type drop-down by default.
  3. Verify that you can see conference, talks, and exhibits posted to the Conference Offers microservice.
  4. On the toolbar, select 
    main:Conferences
     as the entity you want to view in the Main Grid from the endpoints drop-down.
    The Talks and Exhibits child tables are displayed as tabs in the Child Grid.
  5. Select the 
    App Economy World
     conference by clicking the conference row in the Main Grid.
  6. In the Form, update the 
    Budget
     field to 10,000, and then click 
    Save
    .
  7. With the 
    App Economy World
     conference selected, in the Child Grid, select the talk or exhibit options that you want to attend by selecting the 
    Use
     checkbox for those talks or exhibits, and then click 
    Save
    .
Observe the following:
  • The two sum rules that are defined for the Conferences table calculate the accrued costs in the 
    Exhibit Costs 
    and 
    Talk Costs 
    fields in the Form are calculated.
  • The 
    Budget Check
     commit validation rule ensures that the sum of exhibits cost and talks cost do not exceed the budget for the conference.
 
CA Live API Creator
 automatically invokes this reactive logic.
 
Approve Conferences
 
As a manager, you want to approve the talk or exhibit options that the organizers select.
 
Follow these steps:
 
  1. In Data Explorer, on the toolbar, select 
    Conferences
     as the entity that you want to view in the Main Grid from the endpoints drop-down.
  2. In the Main Grid, select the 
    App Economy World
     conference as the row for which you want to call the 
    Approve
     function.
  3. Approve a conference by completing 
    one
     of the following:
    • In the Main Grid, select the 
      Approved
       checkbox, and then click 
      Save
      .  
    • In the Form, call the 
      Approve
       function on the 
      Conferences
       table by selecting the 
      Approve
       function from the functions drop-down.
       This drop-down is located on the upper right of the Form. For more information about this drop-down, see Data Explorer.
Observe that the 
Alert Management - JSON Message
 event rule fires with the approved value change. 
CA Live API Creator
 automatically invokes this reactive logic.
Conference Management Microservice
Process Messages
The Conference Management microservice processes the messages that the Conference Offers microservice publishes. The 
Conference Management
 API sample illustrates a common pattern in message processing. The following image shows the message processing. The steps are explained in the table that follows:
The numbered steps in the following diagram indicate steps that the JavaScript code executes. 
CA Live API Creator
 automatically executes steps 2 and 3.
  Screen Shot 2018-08-06 at 5.06.31 PM.png  
 
CA Live API Creator
 system components process MQTT messages using the following workflow:
Connection
Approach
  1. Incoming message
Create a connection and the 
ManagementCostListener
 listener using the following JavaScript code:
var title = "conf-management Listener (1): ";
try { // persist payload (also see ProcessCharges Extended Properties)
var postPayloadResponse = listenerUtil.restPost(Config.settings.resourceURL + "/ProcessCharges",
{}, Config.settings.authHeader, message.toString());
print(title + "Payload Processed, postPayloadResponse: " + postPayloadResponse + "\n\n");
} catch(e) {
print (title + "post exception: " + e);
throw title + "post exception: " + e;
}
2. Request event resource processing
Preserve request data if you get errors during processing by persisting the incoming payload to the 
PersistCharges
 resource. You can do this in a generic way. To make this resource-driven, persist the payload to the resource using the extended properties for a resource. To make this table-driven, persist the payload to the resource within the 
ProcessPayloadOnRequest
 request event handler.
The following code snippet shows the code for the 
ProcessPayloadOnRequest
 request event handler. This code determines which table to persist the payload by accessing the extended properties for the 
PersistCharges
 resource by way of calling the 
SysUtility.getExtendedPropertiesFor()
 method:
...
if(req.verb == 'POST') { // ProcessCharges ExtProp: { "PersistTo": "PersistCharges"}
var title = "conf-management - ProcessPayload Request Event (2): ";
var extProps = null;
try {
extProps = SysUtility.getExtendedPropertiesFor(req.resourceName);
} catch(e) {
// occurs for non-resources, etc
}
if (extProps && 'object' === typeof extProps && ! Array.isArray(extProps) && extProps.hasOwnProperty('PersistTo') ) {
var persistToResponse = SysUtility.restPost(Config.settings.resourceURL + "/" + extProps.PersistTo, {}, Config.settings.authHeader, {msgContent: req.json});
}
}
As an alternate design, this sample also illustrates how you can persist the payload by accessing the 
Config
 variable (defined in the
ConfManagementLib
JavaScript library).
For more information:
3.
Messages
resource processing - mapping
Create the 
ProcessCharges
 resource in API Creator and define the resource/row mapping. 
CA Live API Creator
 automatically does the processing (persistence, mapping, and business rules). You do not have to code.
The 
ProcessCharges
 resource is mapped to the underlying 
Charges
 and 
EventTalks
 tables. You do not have to code.
4. Logic execution
The system executes the logic that is associated with the underlying tables. But what if, for example, the update violates a rule, such as the 
Active Marketing Program
 rule? We want to enable business users to correct the situation (for example, define a marketing program), then set the 
ProcessedStatus
 row to retry the transaction. The following step, step 5, illustrates the solution.
Error Processing
As noted in step 4, we want to enable business users to correct errors. After, for example, adding the missing Marketing Program, they can use an application (for example, Data Explorer) to set the 
ProcessedStatus
 row that is on 
MessageAudits
 table. This action is not synchronous with message processing. The action might be several days later.
Changing 
ProcessedStatus
 activates the logic that is shown in the following table:
Connection
Approach
5. Business logic
The 
MessageAudits
 row contains the JSON or XML payload in the 
MsgContent
 column. 
CA Live API Creator
 automatically invokes the logic that is defined for the 
MessageAudits
 table.
The 
Process Payload to underlying tables
 table event posts the payload data to the 
Charges
 resource using the following JavaScript code:
if (row.ProcessedStatus != oldRow.ProcessedStatus) {
var title = "conf-management Retry Process Payload (6): ";
logicContext.logDebug (title + "Running***");
var resourceURL = req.localFullBaseURL + 'ProcessCharges'; // mapping and transformation defined by Custom Resource
if (messageContent.startsWith("<"))
settings.headers["Content-Type"] = "application/xml"; // not required if strictly JSON
var postResponse = SysUtility.restPost(resourceURL, {}, Config.settings.authHeader, row.msgContent);
logicContext.logDebug(title + "Post Response: " + postResponse);
// built using Examples (Persist Payload) and Control-Space
}
 You can make the original message XML-encoded by activating the 
Alert Management - XML
 event rule in the 
Conference Offers
 API sample. 
CA Live API Creator
 automatically converts the XML into JSON.
Activate only 
one
 of the alert management event rules.
The code uses Content-Type headers to indicate that the content type is XML, not the default JSON. 
CA Live API Creator
 performs the XML/JSON conversion automatically, providing a convenient programming model for JavaScript code.
6.
ProcssCharges
resource
The
Charges
resource decomposes the charge and talk data into the underlying tables. As in the previous code, this resource invokes mapping logic and any logic on the underlying tables.
Service Map View
We recommend that you plan implementations using the service map that is in API Creator. The previous implementation maps onto the service map as follows:
  Process Messages.png  
You can view the service map on the Creating Services tab in the Learning Center in API Creator. To view the Learning Center, with your API open, in the Favorites section, click 
Learning Center
, and then click the 
Creating Services
 tab.
Outboarded Constants using Property Files
In step 2 of the process MQTT messages workflow, request event resource processing, note the use of the 
Config
 variable. This variable is defined in the
ConfManagementLib
JavaScript library so that constants are defined once and not embedded in the code. Further, the values are loaded from a properties file using the 
ConfManagementStartup
 startup listener.
For more information about how to access Java system properties, see Access Java System Properties from JavaScript Code.
Validate the Conference Management API Sample
 
Click to expand the steps...
Verify Message Received
The Conference Offers microservice publishes approved conferences as MQTT messages to the Conference Management microservice. You can check that the message is successfully received using API Creator.
 
Follow these steps:
 
  1. With the 
    Conference Management
     API sample open, in the Manage section, click 
    REST Lab
    .
  2. Select 
    main:MessageAudits
     as the table endpoint, and then click 
    GET
    .
  3. Verify that the received message is posted to this table.
Verify Conference Charges Posted
You can check that the message is posted to the 
ProcessCharges
 resource using API Creator.
 
Follow these steps:
 
  1. In the REST Lab, select 
    Charges
     as the resource endpoint, and then click 
    GET
    .
  2. Verify that the charge and talk data have posted to this table.