JSON Explained

User should prepare the JSON with right set of values of the keys/nodes. A sample JSON is depicted below in the Figure3.1. The JSON is set with sample values for a mutual fund holdings functionality under payments. As part of the explanation, some of the JSON nodes or fields or keys may differ from the sample JSON provided (It has been done to explain functionalities which cannot be covered using just sample JSON) . Each and every key/node of the JSON is explained below:

• domainName(*): User has to input the name of the domain entity which represents one business use case. e.g Holdings i.e. mutual fund holdings is a domain( a business use case under payment transactions)
• moduleName(*): User should provide the name of the module to which this domain functionality belongs to.eg. Holdings domain belongs to “mutualfund” module.

• subModuleName: It is common to have module constituting of sub-modules. User should set the appropriate name of the sub-module (depending upon the domain functionality).

• moduleCode(*): It is basically an abbreviated unique identifier of the module to which the service belongs . It is formed by taking the initials of the module name. “moduleCode” has to be decided by the user.

For Example:

Here “MF” is formed by taking initials of the “mutualfund” module.

• uri(*): It is the path of the REST resource. It is the path exposed to the end user, of the product channel(as REST API). In the example of deal booking functionality, the path exposed is shown below:

This is the URI which will appear in the swagger JSON created using the tool.

• methods(*): User should provide the methods which are expected in the domain. A combination of “name” and “operationType” nodes uniquely defines a method. The “methods” node is an array of methods defined in the domain. Part of the JSON depicting methods is presented below:

• name(*): User should provide the name of the methods. A method name depicts the operation that the user wants to perform by calling this method. For example
• operationType(*) : Operation type is synonymous to REST operation type. So the method with operationType ‘CREATE’ will result in creation of a new resource at the specified URL (similar to what REST “POST” operation does). User must provide the functionality the method is going to perform. It should be one of the following list of strings: ‘CREATE’, ‘READ’, ‘UPDATE’. If the method performs creation task it should have operation type as “CREATE”.
• methodAttributes: Method or Operation defined in the application carries various properties which defines its behavior. For example an operation or a method can go for approval. In order to ensure that the declared method has the property to go through approval process the task aspects of the task attribute must have a value “approval”. These properties which attaches various behaviors to the application, facilitates various application requirements such as swagger UI generation, etc are taken as input by the Toolkit in the form of “methodAttributes” . It has various attributes such as ‘task’, ‘entitlements’, ‘swaggerAnnotations’, ‘allocation’. User should provide various attributes of the methods such as tasks associated with them, entitlements allocated to them and swagger details.

• task: User should provide the details of the task associated with the method

For example:

• taskName: User should declare name of the task associated with the current method
• accountTypes: User should provide the supported account types by the current transacting method. The set of all possible values that a user can provide are given below in the table with its description:

For detailed values to be input in the “accountTypes” please refer Appendix A

Sr.No	Account Types	Description
1	CSA	“CSA" refers current and savings accounts
2	LON	"LON" refers loan accounts
3	TRD	"TRD" refers term Deposits
4	CCA	"CCA" refers Credit card accounts

• taskType: User should provide the type of the transaction that this method will be using. It can be a maintenance transaction or can be an auth-admin transaction, etc. The set of possible values that a user can provide is given below in the table

Sr.No	taskType	Description
1	FINANCIAL TRANSACTION	Transactions involving account and amount i.e. monetary transactions
2	NONFINANCIAL TRANSACTION	Transactions involving no monetary value. For e.g. Request a cheque book
3	INQUIRY	Inquiry of transactions
4	ADMINISTRATION	ADMINISTRATION
5	MAINTENANCE	MAINTENANCE
6	COMMON	COMMON

• taskAspects: User should provide the details of the aspects of the transaction associated with the current method. An aspect of the transaction defines a feature inherently provided by the framework. For example “approval” is feature of the transaction which it is going to need while execution. Similarly there are various features like limit, two-factor authentication(2fa), audit, etc which the transaction can be dependent upon (based on use case of the transaction).The set of possible values that taskAspects can carry are :

Sr.No	TaskAspects	Description
1	limit	Applicability of limits for a transaction
2	account-access	Applicability of access for a transaction
3	approval	Applicability of approval rules for a transaction
4	working-window	Applicability of working window i.e. cutoff for a transaction
5	blackout	Applicability of blackout or outage for a transaction
6	2fa	Applicability of two factor authentication for a transaction
7	audit	Applicability of audit log for a transaction
8	grace-period	Applicability of grace period for a transaction
9	eReceipt	Applicability of e-Receipt for a transaction
10	purpose-mapping	Applicability of purpose mapping to transaction
11	currency-config	Applicability of currency mapping to transaction
12	account-relationship	Applicability of access on the basis of account relationships

moduleType: User should provide the type of the module

Sr.No	moduleType	Description
1	TD Term Deposit is a deposit accepted by bank, for a fixed term, from customers. A term deposit is a liability of a bank with fixed maturity period.	TERM_DEPOSIT
2	CH	CASA Current Account or Savings Accounts are operative accounts through which account holders perform day to day operations such as deposits and withdrawal of money.
3	PI	PARTY
4	LN	LOAN
5	OR	ORIGINATION
6	PC	PAYMENTS
7	AT	CHANNELS
8	CC	CREDIT_CARD
9	SMS	SMS
10	FL	FINANCIAL_LIMITS
11	WA	WALLET
12	BO	BACK_OFFICE
13	FU	FILE_UPLOAD
14	AP	APPROVALS
15	NM	NOMINEE
16	AL	ALERTS
17	PFM	PFM
18	RT	REPORTS
19	LC	LETTEROFCREDIT
20	BL	BILL
21	CM	COMMON
22	BM	BENEFICIARYMAINTAINANCE
23	GR	GENERICREST
24	MT	ADMIN_MAINTENANCE
25	FX	FOREXDEAL
26	MB Mobile Banking	MOBILE

• entitlements:

Entitlements are meant to group transactions. Transactions can be grouped into categories and further into sub-categories.

For example a user onboarding transaction can be grouped into “Admin Maintenance” category and further into “User Management” sub-category. User should provide the details of category into which the currently executing method can be grouped with a further sub-category level grouping. e.g

There is a list of groups and sub groups provided in the table below

Sr.No	moduleType	Description
1	MT	Entitlement Category constant for 'ADMIN MAINTENANCE'
2	RP	Entitlement Category constant for 'REPORTS'
3	CS	Entitlement Category constant for 'CUSTOMER SERVICING'.
4	CASA	Entitlement Category constant for 'CURRENT SAVING ACCOUNT'
5	TD	Entitlement Category constant for 'TERM DEPOSIT'
6	LN	Entitlement Category constant for 'LOAN'
7	PC	Entitlement Category constant for 'PAYMENTS'
8	FU	Entitlement Category constant for 'FILE UPLOAD
9	TF	Entitlement Category constant for 'CREDIT CARDS'
10	CC	Entitlement Category constant for 'CREDIT CARDS'
11	PFM	Entitlement Category constant for 'PERSONAL FIANANCE MANAGEMENT'
12	FX	Entitlement Category constant for 'FOREX'.
13	EBP	Entitlement Category constant for 'ELECTRONIC BILL PAYMENT'
14	MB	Entitlement Category constant for 'MOBILE APP MAINTENANCE'
15	PRL	Entitlement Category constant for 'PRE LOGIN'
16	OR	Entitilement Category constant for 'Originations'
17	ENUMP	Entitlement Category constant for 'ENUMERATION'
18	AUTH	Entitlement Category constant for Authentication

If there are no groups or sub-groups into which the current transaction can be put then the user needs to add a new category and sub-category.

Sr.No	Entitlement Sub Category	Description
1	SC	System Configuration
2	SR A Service Request is a user request for information or advice, or for a standard change.	System Rules Rules are set of application instructions to form the logic and basis of calculation across various modules. Multiple conditions can be set in a single Rule ID. These rules are used across modules to calculate interest rates, service charges, and so on.
3	LMD	Limits Definition
4	UL	User Limits
5	LMP	Limits Package
6	TG	Task Group
7	SPC	Spend Category
8	SPCM	Spend Category Maintenance
9	GOC	Goal Category
10	PYP	Payment Purpose
11	PYR	Payee Restrictions
12	BCM	Bill Category Maintenance
13	BCMUBS	Bill Category Maintenance UBS
14	UM	User Management
15	MOB	Merchant Onboarding
16	AUTH	Authentication
17	MSS	Manage Security Settings
18	PPL	Password Policy
19	TXB	Transaction Blackout
20	WW	Working Window
21	UGSM	User Group Subject Mapping
22	UGM	User Group Management
23	ALM	Alert Maintenance
24	BR	Brand Management
25	DSHBD	Dashboard Management
26	AL	Audit Log
27	AUL	Audit Logging
28	ABM	ATM Automated Teller Machine terminal allows customers having an ATM or debit card to perform several banking transactions such as cash withdrawal, balance inquiry, funds transfer, and so on. Branch Maintenance
29	PDM	Product A product is created based on the bank's business requirements and has certain typical parameters that describe its attributes or characteristics. Every product is defined under Product Class and Product Group. For example, a product 'Fixed rate home loan' is defined under product group 'Home Loan' and product class 'Loans'. Mapping
30	ML	Mailers
31	MGB	Manage Brands
32	TXA	Transaction Aspects
33	PPI	Password Print Information
34	OWC	Origination WorkFlow Configuration
35	PL	Party A party is any individual or business entity having a banking relationship with the bank. to Party Linkage
36	PAC	Party Account Access
37	UAC	User Account Access
38	LUAC	Linked User Account Access
39	LPAC	Linked Party Account Access
40	FIM	File Identifier Maintenance
41	UFIM	User FI Mapping
42	AWC	Approvals Workflow Configuration
43	SVR	Service Request
44	PP	Party Preference
45	RM	Rule Management
46	URM	User Report Mapping
47	RPM	Reports
48	RPV	Reports View
49	RPC	Corp Admin Reports
50	RPU	User Reports
51	MN	Mailbox Notifications
52	MAIL	Mails
53	ALT	Alerts
54	NO	Notification
55	PF	Profile
56	SS	Session Summary
57	LOC	ATM Branch Locator
58	SCS	Security Setting
59	HELP	Help
60	CSAAD	CASA Account Details
61	CSASM	CASA Statement
62	CBR	Cheque Book
63	DC	Debit Card
64	CSACA	CASA Calculators
65	TDAD	TD Account Details
66	TDSM	TD Statement
67	TDTSN	TD Transactions
68	TDCA	TD Calculators
69	LNAD	Loan Account Details
70	LNSM	Loan Statement
71	LNTXN	Loan Transactions
72	LNCA	Loan Calculators
73	CCAD	CC Account Details
74	CCSM	CC Statement
75	CCTXN	CC Transactions
76	PYT	Payments Transfers
77	ADPY	Adhoc Payment
78	IntPaye	Internal Payee
79	DP	Domestic Payee
80	DPR	Domestic Payer
81	IP	International Payee
82	DDP	Demand Draft Payee
83	BM	Biller Maintainance
84	CBM	Customer Biller Maintainance
85	DD Direct Debit	Demand Draft
86	BP	Bill Payment
87	RMT	Remittance
88	UP	Upcoming Payments
89	RF	Request Funds
90	FT	Favorite Transactions
91	PPP	Peer To Peer Payee
92	GO	Goal
93	SP	Spends
94	BD	Budget
95	AS	Alert Subscription
96	TPC	Third Party Consent
97	LM	Limits
98	FUTXN	File upload transactions
99	FUT	File Uploads
100	FUA	File Upload
101	TFLOC	Letter Of Credit
102	TFLOCA	Letter Of Credit Amendment
103	BAC	Bills And Collection
104	OWG	Outward Guarantee
105	OWGA	Outward Guarantee Amendment
106	GL General Ledger is bank’s accounting records. The formal ledger contains all details of financial accounts with records of debits and offset credits.	General
107	ACL Australian Credit License	Activity log
108	PLT	Pre Login Transactions
109	SRFB	Service Request - Form Builder Sub Category, under category 'Admin Maintenance'.
110	FDM	Feedback Maintenance sub category under category 'Admin Maintenance'
111	NM	Nominee sub category under category Customer Servicing.
112	FXDB	Forex Foreign Exchange Currency deal booking sub category under category 'Forex'.
113	PMNT	Payment maintenance sub category
114	RTM	Role Transaction Mapping sub category under category 'Admin Maintenence'.
115	EBR	Favorites sub category of EBPP under category 'Electronic Bill Payment'.
116	EBL	Bills sub category of EBPP under category 'Electronic Bill Payment'.
117	AGR	Favorites sub category of Account Aggregate under category 'Account Aggeregation'.
118	EPY	Manage Billers sub category of EBPP under category 'Electronic Bill Payment
119	MCL	Mobile Client suub category under category 'Mobile Application'
120	BFM	Manage Billers sub category of EBPP under category 'Electronic Bill Payment'
121	MSWPIN	Manage Sweep-in sub category under category 'Customer Servicing'.
122	FXDM	Forex Deal Maintenance sub category under category 'Admin Maintenance'.
123	ARM Adjustable Rate Mortgage is an installment type where the loan is repaid in multiple installments with varying interest rates, over the tenure of the loan. The repayment schedule is split into term based slabs and multiple EPIs are arrived based on the interest rate applicable to that specific tenure.	Account Relationship Relationship signifies the relationship between parties and accounts whenever the relationship is mapped to account. Mapping sub category under category 'Admin Maintenance'.
124	FAM	2 factor task auth maintenance.
125	ORP	Origination products sub category under category 'Pre-Login'
126	ANN	Account Nick name sub category under category 'CUSTOMER_SERVICING'.
127	BU Business Unit	Business entities sub category under category 'CUSTOMER_SERVICING'.
128	ACPU	Access Point sub category under category 'CUSTOMER_SERVICING'.
129	FR	Fund Request sub category under category 'PAYMENTS'.
130	ANUM	Enumeration sub category under category Enumeration.
131	FCL	FATCA Compliance sub category under category 'CUSTOMER_SERVICING'
132	FDB	Feedback sub category under category 'CUSTOMER_SERVICING'.
133	SAD	Service_Advisor sub category under category 'CUSTOMER_SERVICING'
134	ORC	Origination sub category under category 'Originations'.
135	AP	Approvals sub category under category 'CUSTOMER_SERVICING'.
136	ACPM	Access Point Maintenance sub category under category 'CUSTOMER_SERVICING'.
137	HDS	Help Desk Session sub category under category 'Admin Maintenance'.
138	APA	Access Point Account Access under category 'CUSTOMER_SERVICING'.
139	SECQUE	Security Quesiton
140	TASK	Task
141	SB	SMS_Banking
142	SRFL	Service Request - Form Listing Sub Category, under category 'Customer Servicing'.
143	UPS	Preferences of the user.
144	BC	Base Configuration
145	FUFT	File Upload Funds Transfer.
146	FUP	File Upload Payee
147	GR	Generic Rest

If there are no groups or sub-groups into which the current transaction can be put then the user needs to add the new category and sub-category. Guide to add new categories and sub-categories can be found here.

• swaggerAnnotations:

User should provide the details required for the swagger specification. In swagger documentation for each path(@path Annotation in REST) multiple operations(HTTP methods) can be defined

Swagger defines a unique operation as a combination of a path and an HTTP method. For each operation(HTTP method) there is a summary section and details section in the documentation. On clicking the operation box in swagger one can get details section. The details section consists of description, parameters, request body and responses. Further swagger details can be found here.

“swaggerAnnotations” takes the values relevant for generating the required swagger document. It takes summary, description, tags and API responses.

For example:

• summary: The value input in this field appears in the operation summary of the swagger documentation. The required content in the summary section for the current method(i.e REST resource or REST URL + ) should be provided here.
• description: User should provide the description of the method(i.e REST resource).
• tags: Swagger uses tags to group the displayed operations. User should provide the relevant details of grouping and its description.
• apiResponses: For the current API operation all the possible responses are listed here.

For example:

• responseCode: Response code or HTTP status code of the REST response should be provided by the user.

e.g”201” - if the request has been fulfilled and has resulted in one or more new resources being created. “400” – if the server cannot or will not process the request due to something that is perceived to be a client error.

• description: Description of the http response should be provided here.
• content: It consists of mainly two things mediaType and schema.
• MediaType: User should provide what media type the REST resource produces.

For example:

“application/json” for JSON,

“application/xml” for XML.

The “content” node of the input JSON is depicted below in the image:

• schema: It is used to describe the REST response body of the respective method. It can define an object or a primitive data type (for plain text responses) or a file. For the object or primitive data type in the response user must provide its packageName and className.
• allocationTiers: User should provide the details of the tiers (REST, SERVICE, DOMAIN, REPOSITORY) in which the method should be present. It is not a mandatory field. By default the method is created in all of the tiers.

For example:

• fields(*):

All the variables which user intends to declare in the domain are taken care of by this node/key. This node/key stands for the Java type (i.e Class or Interface or enumeration) or variables or fields to be used in the domain (here ForexDeal) and its required details. This node has further child nodes “type” i.e Java type for variable, “attrs” for attributes of the Java type or variable or field and “detailsDTO” for other details of the Java type or variables or fields. Other details are provided in case the field is in itself is a type containing further fields. Part of the JSON carrying the sample values of this node is depicted below:

HelloWorld Fields:

• type(*):

“type” here is the Java type(Class or Interface or enumeration) which takes the qualified name (i.e package name and class name) as input. It consists of further child nodes depicted below:

• packageName: User should provide the package name of the variable to be declared. It must be left empty if the variable is a domain key (can be seen in 2nd fig 7.2.1.1)
• className: User must provide the class name of the variable to be declared.
• enumeration: This key is a Boolean. If this variable is an enumeration then user must provide “true” value to this JSON node. It is not a mandatory field. If user doesn’t provide any value the tool assumes it to be a Java type other than enumeration.
• name(*): User should provide the reference of the variable at this node/key as can be seen in the figure.

• custom: A declared field can be a Java type (Class or Interface) which is not a class of existing Java packages instead are defined by the user. Those user defined fields are custom fields. e.g String class is a class of existing Java package java.lang so String fields are not custom fileds but com.example.Student is a user defined Class (hence custom filed).

This node is a Boolean which takes values depending upon the variable declared is a class of an API or it is a user defined class. If this key carries “true” it means the class is user defined class.

• exists: This is also a Boolean which takes values depending upon the variable declared in the domain is an existing domain or it is new domain at all.

If user provides this value as “false” then a completely new domain is created by the tool. User should provide this as “true” in case the domain already exists.

• key: In a domain there is key which is a unique identifier for each domain object. User must provide this key value as “true” if this field is the key of the domain and “false” in case it is a normal variable.

A key can be a composite key i.e. multiple fields combined together to form key. In case of composite key user must provide the “key” attributes as true for all those fields which forms the composite key.

• detailsDTO: If the user is going to declare a variable which in itself is a domain or is another class (e.g enumeration) carrying fields then user must provide the details of the variables to be declared in that domain or class. Part of the JSON with sample values of this node are depicted below:

Here user should provide the details of the fields to be declared in this new domain field. It is same as the field (parent node) . It asks for type, name, attrs, mock value and further details of the field.

• name: User should provide the details of the variable to be declared in the new class or enumeration.
• mockValue: Same as mockValue of the fields node of the parent
• mockValue: Mock value must be provided in case of enumeration. The user should provide the value to be obtained in each constant declared in the enumeration. It can be seen in the detailsDTO node of the child.

For example:

• genericType

The below snippet demonstrates creation of fields pertaining to classes supporting generics.

The most frequently encountered example being list , let’s see how to have a list of strings as a field in a domain.

Within the “type” of the field provide a generic type JSON array where each element of the array provides the package name and the class name of the parameterized types. In the example above the parameterized type is a String class of Java.

FAQs

How do I specify which field is used for READ operation?

To specify a field to be used in the READ operation the user must provide the value of the “key” of the “attributes” of the particular field in the input JSON as true. Please refer “fields” in the section 5 JSON explained.

Can we edit the generated source code?

Yes, one can import the generated source code (after running gradle task “gradle eclipse”) from <APITOOLKIT_HOME>/output folder. Make sure the next tasks “gradle build” , “gradle thirdpartygen” are executed after it.

Where are the EARs for the deployment generated?

One can get the built EARs after running respective gradle tasks(“gradle build” and “gradle thirdpartygen”) at <APITOOLKIT_HOME>/ output/deployables.

Can I run the gradle tasks at any windows location?

No, User must run the gradle tasks at the <APITOOLKIT_HOME>.

Is it mandatory to execute gradle thirdpartygen task?

The task thirdpartygen generates xml with mock values only for simulation purpose of third party setup. It further packages these xml into ExtxfaceSimulatorMDB.ear which is deployed only in a simulation environment. In environments interacting with actual hosts this is not needed.

Where are the sql scripts generated?

At <APITOOLKIT_HOME>/ output/seed/oracle.

Can I generate two different services in the same module?

Yes, user just need to place the two JSONs for respective services at <APITOOLKIT_HOME>/input/json.

Can I generate two different services in two different modules?

Yes, user just need to write two different JSONs with the required moduleNames in each JSON.Place the two JSONs for respective services at <APITOOLKIT_HOME>/input/json.That’s it.

Back