using ca plex and cm hsynccmfirstgroup.com/wp-content/uploads/2017/12/publishrest... · 2017. 9....

9th CA 2E/CA Plex Worldwide Developer Conference

using CA Plex and CM HSync

1


Speaker

2

Andrew LeggettSoftware Consultant

CM First Group


Introduction

There are many benefits to opening up your applications and data via APIs. View your CA Plex application as

a set of valuable resources that can be shared with internal applications, partners, customers, other tools or

the rest of the world.

This presentation will show you how to use CM WebClient HSync to publish a RESTful API from your CA Plex

model.

3


Disclaimer

4

o HSync RESTful templates are still in development*

o Everything is subject to change

*May contain bugs


Agenda

5

o RESTful APIs• Principles• Examples

o Introduction to HSync• Basics• Templates

o Implementing REST in your model• Preparing your model• HSync RESTful Servlet

• Documentation


RESTful APIs

6


Interfacing with APIs

7

o Your software and data is a valuable resource

o APIs can share your resources with other tools, customers, partners etc.

o Move away from importing/exporting data files

o SOAP/XML once main Web Service option, now emphasis moving to simpler RESTful implementation


RESTful APIs

8

o REST is now the dominant Web Service approach


RESTful APIs

9

o Representational State Transfer (REST)

o Access and manipulate resources via HTTP and HTTPS verbs

o Create / Read / Update / Delete (CRUD) operations

o High performance and scalable

o Response in JSON, XML or HTML

o Simple to work with as a programmer

o REST is not a standard, more an approach, hence ‘RESTful’


RESTful Requests

10

o Every resource has a unique web address, which is its URL

o HTTP verbs define operation

o GET – Retrieve a specific resource or a collection of resources

o POST – Create a new resource

o PUT – Update resource details

o DELETE – Delete a resource


RESTful – Additional notes

11

o Security – can be secured by OAUTH and other frameworks

o Tokens used to identify users – allow access to resources and operations by user

o API can be versioned by URL or HTTP header

o Publisher responsible for providing documentation for developers


Examples – Retrieve a single resource (GET)

12

o Retrieve Sponsor with key ‘1’• GET https://api.com/sponsors/1

o Status 404 if not found

https://api.com/sponsors/1


Examples – Retrieve a collection (GET)

13

o Retrieve all sponsors (usually limited by count)• GET https://api.com/sponsors

https://api.com/sponsors


Optional parameters for GET

14

o URL query string parameters to limit result set

o Filtering – return resources matching conditions• e.g. /sessions?filter=SessionTitle CT training AND SessionDesc CT Plex

o Limit result set – request a maximum number of resources• e.g. /sessions?limit=10

o Expand resources – include results from related resources• HSync solution can expand ENT owned by ENT and ENT refers to ENT relationships

• e.g. /sessions/60?expand=rating


Examples – Create a resource (POST)

15

o Create a new Sponsor with key ‘1’

o Pass values via URL query string • POST https:/api.com/sponsors/1?SponsorName=CM

First&SponsorLink=cmfirstgroup.com

https://api.com/sponsors/1?SponsorName=CM First&SponsorLink=cmfirstgroup.com


Examples –Update a resource (PUT)

16

o Update the Sponsor with key ‘1’• PUT https://api.com/sponsors/1?SponsorName=CM First

Group&SponsorLink=cmfirstgroup.com

https://api.com/sponsors/1?SponsorName=CM First Group&SponsorLink=cmfirstgroup.com


Examples –Delete a resource (DELETE)

17

o Delete Sponsor with key ‘1’• DELETE https://api.com/sponsors/1

https://api.com/suppliers/NEW


Validation – Plex patterns

18

o HSync Solution uses Plex validation for Create, Update and Delete• e.g. not supplying mandatory attributes for Update


Validation - Custom

19

o Can add your own validation


Introduction to HSync

20


CM HSync

21

o Originally designed to generate offline mobile applications based on CA Plex model

o Used a set of templates to generate JavaScript

o Generated application allowed for entry, validation and data synchronization based on model definition


HSync – the power of templates

22

HSync interprets template files, inserts values from your Plex Model and generates output files

Templates Output Files

HSync Template Processor*

*Generated from your Plex Model


HSync Components

23

o HSync Group Model• Add as library to your model and inherit• Inherited functions contain meta-code to retrieve model information

o Template Processor• Generated from Plex model

• Reads template files and inserts information from Plex model

o Template files• Text files with special tags• Can be used to generate JavaScript, HTML, XML, JSON, Java and

any other text-based file type


HSync Model Concepts

24

o One Application is comprised of many Entities• Application is an Entity itself• Uses ENT comprises ENT triple to associate other Entities

o Can have many Applications per model

o Entities can belong to more than one Application

o Examples• Sales Application: Customer, Product, Order

• Delivery Application: Customer, Order, Addresses


HSync Templates

25

o Text files that contain tags• Tags indicate attributes, loops or conditions

o At generation time the output file is populated with Plex model values


HSync Templates

26

o Template file has either .atp or .etp extension• .atp = application template, one output file per application

• .etp = entity template, one output file per entity

o Can create text files of any type• e.g. *.txt, *.html, *.js, *.xml, *.sql, *.java

o e.g. index.html.atp creates output file index.html

o e.g. Info.txt.etp creates output files CustomerInfo.txt, SupplierInfo.txt, ProductInfo.txt etc.

o Non-template files copied to output folder


HSync Abilities

27

o Allows conditional generation of code based on Entity inheritance

/(if:/(entity.inherits:Ability.RetrieveAPI)==Y)

/* retrieval code goes here */

/(end.if)

o Developer can control how entities behave through inheritance


Implement REST in your model

28


HSync RESTful Solution

29

o Solution allows RESTful operations on Plex entities

o Plex Entities are REST resources

o Entities do not necessarily need a physical table

o All Entities have common ancestor Ability.APIResource

o REST typically refers to resources by plural, e.g. Sessions

o Can override resource name by editing message object ‘TemplateGeneration.Custom.PluralResourceName’

o If no override, HSync will just add an ‘s’ to the Entity name –doesn’t always end up well


HSync RESTful solution

30

o Each operation has a Plex function as an entry point• e.g. GET will call

Session.TemplateGeneration.CalledFunctions.API.Retrieve

o Entry point is Plex-generated Java

o Can call any Plex supported server platform• Java

• C# .NET

• RPG / RPGIV


HSync REST servlet

31

Retrieve

Create

Update

Delete

Plex Java Plex Server Functions

REST ServletClient

GET

POST

PUT

DELETE

Web Server


HSync RESTful Entities

32

o Inherit Ability Entities to determine resource operations

o Ability.RetrieveAPI – allows GET operation• Entry point - TemplateGeneration.CalledFunctions.API.Retrieve

• Calls SingleFetch if keys provided, or BlockFetchJSON• APIRetrieveAttributes view determines attributes to retrieve• Supports Virtual & Derived attributes

o Ability.FilterRetrieveAPI – allows GET with filter parameter• Inherits from Ability.RetrieveAPI • Uses dynamic SQL SELECT WHERE statement in BlockFetchJSON


HSync RESTful Entities

33

o Ability.CreateAPI – Allows POST operation• Entry point - TemplateGeneration.CalledFunctions.API.Create

• Calls Update.InsertRow

• APICreateAttributes view determines attributes to pass in

o Ability.UpdateAPI – Allows PUT operation• Entry point - TemplateGeneration.CalledFunctions.API.Update

• Calls Update.UpdateRow

• APIUpdateAttributes view determines attributes to pass in

o Ability.DeleteAPI – Allows DELETE operation• Entry point - TemplateGeneration.CalledFunctions.API.Delete• Calls Update.DeleteRow


HSync REST servlet templates

34

o Generates full Java Servlet application

o Generates classes for each Entity with calls to Plex functions

o Uses obusr.properties for Plex server runtime configuration

o Can be deployed as a standalone .WAR file


HSync RESTful templates

35

Template Folder Output Java


Documentation

36

o Publisher responsible for documenting API

o Developers need to know:• What resources are available

• What operations can be performed• What parameters can be used• How the results are formatted

• Error codes and what they mean

o Documentation should always be up-to-date


Documentation

37

o With HSync RESTful templates, all API documentation is generated automatically as HTML

o Always up-to-date

o Published with servlet

o Templates/html/index.html.atp

o Developer can provide additional information• For entities, edit TemplateGeneration.Custom.ResourceInfo message

object

• For fields, inherit Ability.APIField and edit APINote label


Documentation

38


Questions?

39


Contact

40

Phone: +1 512-264-4645

Email: [email protected]

Website: cmfirstgroup.com

using ca plex and cm hsynccmfirstgroup.com/wp-content/uploads/2017/12/publishrest... · 2017. 9....

Documents