Business to Business Example

This Business to Business (B2B) sample is a data integration example that illustrates a small but non-trivial system, built using 
CA Live API Creator
.
lac31
This Business to Business (B2B) sample is a data integration example that illustrates a small but non-trivial system, built using 
CA Live API Creator
. This article provides a high-level overview of 
CA Live API Creator
 and covers beginning concepts. The subpages provide additional logistics and training resources.
This article covers:
 
 
The B2B sample illustrates a typical API Server that processes inputs from multiple (omni-channel) sources:
  1. Processes omni-channel requests, such as a partner order.
     API Server accepts requests from multiple channels, such as mobile devices, partners, WebHooks, and web applications. The API definition is not the same as the B2B schema, providing mapping and transformation logic.
    For more information about WebHooks, see Integrate Systems and Data.
  2. Enforces business logic. 
    Business policy for logic and security includes internal processing such as credit checks, and external processing such as sending alerts to shippers, by posting a request in an agreed-upon API format. As in item 1, this API does not match the B2B schema.
  3. Integrates multiple databases, such as a shipper notification
    . Provides an API for a device that shows a supplier only their promotions, drawn from two different databases.
  4. Provides UI.
     Enables partners (shippers, suppliers) to view their information about a tablet, PC, etc.
The following diagram shows the flow for this system:
  CA Technologies  
These systems are complex and time-consuming to build, using traditional approaches based on interface documentation (for example, RAML), frameworks (for example, Jersey, Jackson, JPA, etc.), and integrated development environments (IDEs) to build a substantial amount of business logic. Use the B2B sample to explore the 
CA Live API Creator
 alternative, which requires about a dozen lines of JavaScript, a dozen rules, and five point-and-click resources. 
The complete implementation using 
CA Live API Creator
 consists of several rules, and a few lines of JavaScript. The B2B sample uses the Northwind Database (automatically installed in the single-user demonstration package) as the underlying database, to simplify installation.
For more information about the Northwind database, see Northwind API Project Sample.
The B2B sample is a key resource in understanding what 
CA Live API Creator
 can do and how to use it. The following resources are provided to help you ramp as quickly as possible:
  • Install the B2B Example
    The B2B sample is not included with the single-user demonstration package. Install the sample so that you can see what it is like to import APIs that were previously exported.
    For more information about how to install the B2B sample, see Install B2B.
  • Explore the B2B Samples (Fundamentals)
    Explore introductory 
    CA Live API Creator
     concepts such as API creation, logic, and extensibility in the "How it Works" section. The sample also illustrates deeper concepts that you will need for your own APIs.
  • Explore the B2B Samples (Intermediate)
     
    The samples also illustrate deeper CA Live API Creator concepts such as security, Data Explorer, and scripted API deployment, and custom endpoints that you will need for your own APIs.
    For more information about this intermediate functionality and concepts, see Explore B2B.
  • Readiness Lab
     
    After exploring, you can verify your readiness to use 
    CA Live API Creator
     using the set of labs built using this API. The labs are located in the 
    b2b/readinessLabs/
     
    readinessLabs/Readiness - CA Live API Creator.docx
     file (and in the PDF file), located in your install folder and (optionally) the unzipped B2B installation files.
    You have completed the first lab by installing the B2B sample and testing the API.
  • Other B2B Test Scripts
    A key strength of the API architecture is that you can call APIs in various ways, across languages and architectures. You can test the B2B API using most any program including the REST Lab, Data Explorer, scripts such as cURL or the Command Line Interface, or programs such as Node.js, Python, or PHP. Your API is therefore useful not only for integration, but web apps, scripting, and a host of other applications. Your install zip includes examples of each of the testing approaches.
    For more information about how to test the B2B API, see Other B2B Test Scripts.
Recap
Explore the B2B sample to see the code/rules used to create the B2B Derby NW API. The following is a review of some of the highlights. The post/verify programs execute the flow shown in the previous diagram:
  1. An order is posted through the resource named 
    PartnerOrder
    . This provides the mapping and transformation logic to process the order from a partner.
  2. The post activates the business logic. You can compute order totals with product-based discounts, adjust the customer balance, and ensure that the credit limit is not exceeded using about ten rules. One of these rules ( 
    Supplier Alert
     ) alerts the supplier Pavlov. This rule is a JavaScript event (about 12 lines) to check what was ordered, and if it is a product supplied by Pavlov, post an alert to the API 
    b2bderbypavlov
     (representing Pavlov). The 
    SupplierAlert
     custom resource is used for mapping and translation logic.
While this application contains only a few dozen lines of logic and code, it illustrates other patterns common to B2B systems. For example, the 
SupplierInfo
 resource integrates multiple databases and enforces row-level security that enables safe and direct access by partners to view their data.
For more information about the 
SupplierInfo
 resource, see the 
b2b/scs/projects/test/node/verifySupplier.js
 JavaScript source code file.
At the operational level, the install script illustrates a typical team development scenario. The 
scs
 folder mimics how you might maintain API Creator objects in a source control system. It includes loadable libraries used for extensibility. The installation scripts provide examples of command line scripting, and API access from Node, Python, and PHP programs, or test it in the REST Lab, as explained in the 
SupplierInfo
 resource comments.
For more information about team development, see Team Development.
How it Works
The B2B sample API illustrates key 
CA Live API Creator
 features. The B2B sample API provides an excellent study in creating an API back end. The B2B sample API typically follows a process like this:
  1.  Connect to your database for a default API–point-and-click customization–nested docs, aliases, etc. This addresses your SQL and REST handling.
  2.  Ensure the integrity of your data with spreadsheet-like reactive logic, extensible with server-side JavaScript.
  3. Security.
     Protect data security down to the row and column level by defining table permissions for a role. Integrate authentication with existing corporate security.
  4. Data Explorer.
     See/update your data with automatically created interfaces providing filtering, master/detail, navigation to related data, etc. Data Explorer is suited for testing, prototypes, and back-office data maintenance.
  5. Scripted API deployment.
     See how to save API definitions to a source control system and build scripts to recreate them.
Security, Data Explorer, scripted API deployment, custom endpoints, and code samples are intermediate topics. For more information about these intermediate topics, see Explore B2B.
API Creation and Customization
The first step is to create your API and customize ("shape") it as required. Swagger documentation is always available. Use it with various tools to generate objects in C#, Java, etc.
Connect to Create Default API
The B2B system connects to the database and creates endpoints for each table, view, and stored procedure. There is no code generation or deploy. The B2B system was created using the install scripts.
Resources: Mapping and Transformation
The following image shows the Create, Resources, Attributes tab:
  Screen Shot 2017-01-06 at 5.08.27 PM.png  
The default API is a good start, but it conforms to your schema. Usually, you will want to "shape" your API. For example, API agreements with partners typically do not match internal schema definitions. Custom resources provide key services to map API agreements onto your database and logic:
  • Choose/rename columns, which is a simple approach to mapping and transformation logic. In the previous image, 
    PartnerOrder.Order
    ID
     
     is aliased to 
    Order
    Number
     
    .
  • Specify resource nesting so that B2B requests can include multiple kinds of data, such as the Order and Items.
  • You can use non-persistent attributes (NPA) in resources. For example, in the 
    OrderSummary
     resource, the SalesRep's 
    fullName
     is an NPA.
  • You can combine parent subresources into the containing resource. For example, in the 
    OrderSummary
     resource, the 
    Product
     information appears with the 
    Order_DetailList
     properties.
  • Custom resources reuse the logic on the underlying tables.
For more information:
Metadata Tags for Parent Lookup
Examine the JSON in the Other B2B Test Scripts for inserting order details. It does not look like this:
"Items": [
{
"ProductNumber": 16,
"Quantity": 1
},
This would be a typical request, but how would a partner know 
ProductNumbers
 ? API Server supports requests that look like this:
"Items":[
{
"Product":{
"@metadata":{
"action":"LOOKUP",
"key":"ProductName"
},
"ProductName":"Pavlova"
},
"Quantity":1
}, ...
You can link child rows to parent rows by inserting @metadata action tags, without the requirement for the client to supply autonum identifiers (which they might not known) using services. For example, with the 
Lookup
 function, you can use Request Events 200 to automatically insert 
@metadata
 tags.
You can also designate that request rows can result in an update of an existing row or (if not present) the insertion of a new row using related services.
For more information:
  • About linking child rows to parent rows by inserting the @metadata action tags, see Complex Transaction Processing.
  • About the engine services for additional interaction, such as the 
    LogicContext
     object, see Quick Reference.
  • About the 
    Lookup
     metadata action, see LOOKUP Metadata Action Tag.
    In addition to lookup, you can also insert/update rows depending on whether they already exist. This works across relationships, for example, you can insert/update an 
    Employee
     , an 
    EmployeeSkill
     , and create a new 
    Skill
     , all in one transaction.
  • About the Request Events 200, see Extensibility.
Multi-database Resources
The resource 
SupplierInfo
 joins data from two different data sources. Explore the Data Sources page and observe the relationship 
nw:Suppliers -> promos:promotions
, based on tables in two different databases. You can test this in the REST Lab, as explained in the 
SupplierInfo
 resource comments.
Resources: Leverage with SysUtility
You can manipulate resources using 
SysUtility
 services. The Alert Pavlov event illustrates using this service.
For more information about how to manipulate resources using the 
SysUtility
 object, see The SysUtility Object.
Functions
In addition to custom resources, you can create functions as endpoints and functions that operate on resources. For example, you can provide a function to send an email to a designated employee. This example is shown in the following image of the Create, Function, Definition tab:
  Screen Shot 2016-11-21 at 7.20.56 PM.png  
Invoke the function using the following call (for example, in the REST Lab):
For more information about functions, see Manage Functions
Logic
Logic ensures the integrity of your data when update requests are made. For example, we want to:
  • Verify that orders do not exceed customers' credit limits.
  • Provide discounts for healthy orders.
  • Post requests to our supplier Pavlov when orders are received for their products.
The following sections illustrate how to perform such multi-table logic and integration with other systems. This is done by way of spreadsheet-like reactive logic and extended with server-side JavaScript.
Declarative Reactive Rules
Rules are spreadsheet-like expressions (coded in JavaScript) defined on tables and columns. API Server automatically applies them (reacts) to all submitted updates. You do not need to call them. The following executable rules apply to all custom resources. Rules can reduce server-side integrity enforcement by over an order of magnitude. Rules provide clear and concise user-readable logic instead of tedious code. The requirements are captured as topics (in the following image, as blue, green, and red boxes) and linked to the logic for traceability:
  Screen Shot 2016-12-26 at 5.28.11 PM.png  
The following rules ensure the following:
  • Check Credit.
     Rolls up items and orders to verify that the customer's credit limit is not exceeded (if a validation is exceeded, the request results in an exception and the transaction is rolled back).
  • Healthy Food Discount.
     Provides a discount to customers ordering things like fruits and fish.
  • Supplier Alert.
     When orders are detected for supplier Pavlov, our business agreement requires that we 
    post
     the order to Pavlov.
  • Shipper Alert.
     When orders have an assigned shipping company, alert them to order changes.
For more information:
  • About reactive logic rules, see the conceptual background of Logic.
  • About the reactive logic list of rules, see Quick Reference.
  • About non-persistent attributes, see the Healthy Food Discount logic in Non-persistent Attributes.
  • About generated key handling (for example, creating an order number and placing it into the order details), see Automatic Key Generation.
Extensibility: Table Events
Reactive logic is powerful. Extensibility is provided by server-side JavaScript, to ensure there are no limits.
For more information:
  • About viewing an example of Bill of Materials solved with a few rules, see the Reactive Logic Tutorial.
  • About a list of the JavaScript extension points, including their supplied context, see Quick Reference.
The following Orders commit event posts a WebHook to alert shippers of order changes. The following image shows the commit event on the Manage, Rules, By topic tab:
  CA Technologies  
Where the commit event code is:
var shipper = row.FK_Orders_Shippers;
if (shipper !== null) { // resource defines transform: cols, aliases, related objects
var transform = logicContext.transformCurrentRow("ShipperAPIDef");
B2B.sendToWebHook(transform, shipper.webHookURL);
}
This code posts an order and 
OrderDetails
 to the Suppliers WebHook. This illustrates several key patterns of B2B Integration:
  • Transformation logic.
     The format of the post is defined by the custom resource 
    ShipperAPIDef
    . A common integration pattern is to use resources for mapping and translation, leveraging their ability to choose/rename attributes and related objects.
  • Event handling. 
    Events are a powerful way to react to database changes, regardless of the execution path.
  • Posting.
     The post is done in 
    sendToWebHook
    .
  • WebHook target. 
    Shippers can register for WebHooks by way of self-service APIs that set 
    shipper.webHookURL.
    For more information about this pattern, see the "Security" section on Explore B2B.
For more information:
Extensibility: Loadable Libraries
If you detect patterns in your logic, you can provide reusable solutions that rules can invoke. The code in the following image provides a reusable function that implements a WebHook:
CA Technologies
Libraries are generic services. You can use your own applications to transform a table row into a business object (as defined by a resource) and post it to the registered WebHook (the supplier's URL). You can load logic libraries (such as 
transformToWebHook
 ).
For more information about how to load logic libraries, see Logic Libraries.