From c66a7515aa6fc0483de92f519bd6b540dc417099 Mon Sep 17 00:00:00 2001 From: Vishwas Babu AJ Date: Wed, 13 Feb 2013 03:09:34 +0530 Subject: [PATCH] wip: documentation stubs prior to refactoring --- api-docs/apiLive.htm | 1037 ++++++++++++++++- .../guarantor/api/GuarantorsApiResource.java | 2 +- .../guarantor/command/GuarantorCommand.java | 6 +- ...arantorCommandFromApiJsonDeserializer.java | 3 +- 4 files changed, 1028 insertions(+), 20 deletions(-) diff --git a/api-docs/apiLive.htm b/api-docs/apiLive.htm index ee038427c..13b9b1446 100644 --- a/api-docs/apiLive.htm +++ b/api-docs/apiLive.htm @@ -294,11 +294,11 @@ - + Guarantors loans/{loanId}/guarantors - Create a Guarantor + Create a Guarantor - List Guarantors + List Guarantors @@ -307,11 +307,11 @@ loans/{loanId}/guarantors/{guarantorId} - Retrieve a Guarantor + Retrieve a Guarantor - Update a Guarantor + Update a Guarantor - Delete a Guarantor + Delete a Guarantor @@ -1101,7 +1101,7 @@ Delete an Accounting Closure - Journal Entries + Journal Entries journalentries Create Journal Entries List Journal Entries @@ -1112,7 +1112,7 @@ journalentries/{entryId} - Retrieve a Journal Entry + Retrieve a single Entry @@ -2851,6 +2851,323 @@ Request Body: + +   +
+
+

Guarantors

+

A person who guarantees to pay for someone else's debt + if he or she should default on a loan obligation. A guarantor acts as a co-signor of sorts. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field Descriptions
guarantorType
Identifies if the guarantor is + an existing Client, Staff member or an external + individual
+ Refer Retrieve + Guarantor Details Template for complete + details +
entityId
The identifier for guarantors + who are an existing Client of Staff member. +
firstname
Guarantors first name +
lastname
Guarantors last name +
officeName
Name of the office with which the internal guarantors are associated +
addressLine1, addressLine2, city, state, zip, + country, mobileNumber, housePhoneNumber, comment, + dob
Address, contact and date of + birth details of an external guarantor +
+
+
+ +   +
+
+

List Guarantors

+

Example Requests:

+
loans/1/guarantors
+
+
+
loans/1/guarantors?fields=firstname,lastname
+
+
+ +GET https://DomainName/api/v1/loans/{loanId}/guarantors + + +[ + { + "id": 1, + "loanId": 1, + "guarantorType": { + "id": 1, + "code": "guarantor.existing.customer", + "value": "CUSTOMER" + }, + "firstname": "Declan", + "lastname": "Browne", + "officeName": "Head Office", + "joinedDate": [ + 2009, + 1, + 4 + ] + } +] + +
+
+ +   +
+
+

Retrieve Guarantors Details Template

+

This is a convenience resource. It can be useful when + building maintenance user interface screens for client + applications. The template data returned consists of any or all + of: +

    +
  • Field Defaults
    • +
  • Allowed Value Lists
    • +
+

+

Example Request:

+
loans/1/guarantors/template
+
+
+ +GET https://DomainName/api/v1/loans/{loanId}/guarantors/template + + +{ + "guarantorType": { + "id": 1, + "code": "guarantor.existing.customer", + "value": "CUSTOMER" + }, + "guarantorTypeOptions": [ + { + "id": 1, + "code": "guarantor.existing.customer", + "value": "CUSTOMER" + }, + { + "id": 2, + "code": "guarantor.staff", + "value": "STAFF" + }, + { + "id": 3, + "code": "guarantor.external", + "value": "EXTERNAL" + } + ] +} + +
+
+ +   +
+
+

Retrieve a Guarantor

+

Example Requests:

+
/loans/1/guarantors/1
+
+
+
/loans/1/guarantors/1
+
+
+
/loans/1/guarantors/1?fields=firstname
+
+
+ +GET https://DomainName/api/v1/loans/{loanId}/guarantors/{guarantorId} + + +{ + "id": 1, + "loanId": 1, + "guarantorType": { + "id": 1, + "code": "guarantor.existing.customer", + "value": "CUSTOMER" + }, + "firstname": "Declan", + "officeName": "Head Office", + "joinedDate": [ + 2009, + 1, + 4 + ] +} + +
+
+ +   +
+
+

Create a Guarantor

+

+ Note: You may associate any number of Guarantors + to a Loan. The mandatory fields would vary based + on the "guarantorType"
+

+ + + + + + + + + + + + + +
Mandatory Fields + for "internal" guarantors
guarantorTypeId, entityId
Mandatory Fields for "external" guarantors
guarantorTypeId, firstname, lastname
+
+
+ +POST https://DomainName/api/v1//loans/{loanId}}/guarantors + + +POST /loans/1/guarantors +Content-Type: application/json +Request Body: +{ + guarantorTypeId:3, + firstname:Lyndon, + lastname:Johnson +} + + +{ + "officeId": 2, + "loanId": 1, + "resourceId": 9 +} + + +POST /loans/1/guarantors +Content-Type: application/json +Request Body: +{ + guarantorTypeId:1, + entityId:2 +} + + +{ + "officeId": 2, + "loanId": 1, + "resourceId": 10 +} + +
+
+ +   +
+
+

Update a Guarantor

+
+
+ +PUT https://DomainName/api/v1/loans/{loanId}/guarantors/{guarantorId} + + +PUT loans/1/guarantors/1 +Content-Type: application/json +Request Body: +{ + entityId:1 +} + + +{ + "officeId": 1, + "resourceId": 1, + "changes": { + "entityId": 1 + } +} + +
+
+ +   +
+
+

Remove a Guarantor

+

+ Note: A guarantor can be removed only from loans that are not yet approved. +

+
+
+ +DELETE https://DomainName/api/v1/loans/{loanId}/guarantors/{guarantorId} + + +DELETE loans/1/guarantors/1 +Content-Type: application/json +No Request Body: + + +{ + "officeId": 2, + "loanId": 1, + "resourceId": 1 +} + +
+
+   @@ -8571,7 +8888,7 @@ GET https://DomainName/api/v1/glaccounts/{glaccountsId}
-POST https://DomainName/api/v1/glaccounts_update +POST https://DomainName/api/v1/glaccounts POST glaccounts @@ -8613,7 +8930,22 @@ Request Body: { - "resourceId": 1, + "resourceId": 1 +} + +
+
+ +PUT glaccounts/1 +Content-Type: application/json +Request Body: +{ + "disabled": true +} + + +{ + "resourceId": 1 }
@@ -8645,11 +8977,692 @@ No Request Body: +   +
+
+

Accounting Closure

+

An accounting closure indicates that no more journal + entries may be logged or reversed in the system + (either manually or via the portfolio) prior to the closure date +

+ + + + + + + + + + + + + + + + + + + + + + +
Field Descriptions
closingDate
The date for which the + accounting closure is defined
officeId
The identifer of the branch for + which accounting has been closed
comments
Description associated with an + Accounting closure
+
+
- +   +
+
+

List Accounting closures

+

Example Requests:

+
glclosures
+
+
+
+
+ +GET https://DomainName/api/v1/glclosures + + +[ + { + "id": 7, + "officeId": 1, + "officeName": "Head Office", + "closingDate": [ + 2013, + 1, + 2 + ], + "deleted": false, + "createdDate": [ + 2013, + 1, + 3 + ], + "lastUpdatedDate": [ + 2013, + 1, + 3 + ], + "createdByUserId": 1, + "createdByUsername": "mifos", + "lastUpdatedByUserId": 1, + "lastUpdatedByUsername": "mifos", + "comments": "closed", + "allowedOffices": [] + }, + { + "id": 6, + "officeId": 1, + "officeName": "Head Office", + "closingDate": [ + 2012, + 12, + 13 + ], + "deleted": false, + "createdDate": [ + 2012, + 12, + 14 + ], + "lastUpdatedDate": [ + 2012, + 12, + 14 + ], + "createdByUserId": 1, + "createdByUsername": "mifos", + "lastUpdatedByUserId": 1, + "lastUpdatedByUsername": "mifos", + "comments": "hello", + "allowedOffices": [] + } +] + +
+
+ +   +
+
+

Retrieve an Accounting Closure

+

Example Requests:

+
glclosures/1
+
+
+
/glclosures/1?fields=officeName,closingDate
+
+
+ +GET https://DomainName/api/v1/glclosures/{glclosureId} + + +{ + "id": 7, + "officeId": 1, + "officeName": "Head Office", + "closingDate": [ + 2013, + 1, + 2 + ], + "deleted": false, + "createdDate": [ + 2013, + 1, + 3 + ], + "lastUpdatedDate": [ + 2013, + 1, + 3 + ], + "createdByUserId": 1, + "createdByUsername": "mifos", + "lastUpdatedByUserId": 1, + "lastUpdatedByUsername": "mifos", + "comments": "closed", + "allowedOffices": [] +} + +
+
+ +   +
+
+

Create an Accounting Closure

+ + + + + + + +
Mandatory Fields
officeId,closingDate +
+
+
+ +POST https://DomainName/api/v1/glclosures + + +POST glclosures +Content-Type: application/json +Request Body: +{ + "officeId": 1, + "closingDate": "06 December 2012", + "comments": "The accountants are heading for a carribean vacation" + "locale": "en" , + "dateFormat": "dd MMMM yyyy" +} + + +{ + "resourceId": 1 +} + +
+
+ +   +
+
+

Update an Accounting closure

+

Once an accounting closure is created, only the comment associated with it can be edited +

+
+
+ +PUT https://DomainName/api/v1/glclosures/{glclosureId} + + +PUT glclosures/1 +Content-Type: application/json +Request Body: +{ + "comments": "All transactions verified by Johnny Cash" +} + + +{ + "resourceId": 1 +} + +
+
+ +PUT glclosures/1 +Content-Type: application/json +Request Body: +{ + "disabled": true +} + + +{ + "resourceId": 1 +} + +
+
+ +   +
+
+

Delete An accounting closure

+

+ Note: Only the latest accounting closure + associated with a branch may be closed. +

+
+
+ +DELETE https://DomainName/api/v1/glclosures/{glclosureId} + + +DELETE glclosures/1 +Content-Type: application/json +No Request Body: + + +{ + "resourceId": 1 +} + +
+
+ +   +
+
+

Journal Entries

+

A journal entry refers to the logging of + transactions against general ledger accounts. A journal + entry can consist of several line items, each of which is either a "debit" or a "credit". The total amount of the + debits must equal the total amount of the credits or the + journal entry is said to be "unbalanced"

+ A journal entry directly changes the account balances on + the general ledger +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field Descriptions
officeId
The identifier of the office ( + cost center) at which the financial activity + occured
glAccountId
The identifier of the account ( + Ledger Account) against which this journal entry + was made +
entryDate
The target date for which this + entry was recorded
amount
The Monetary amount associated + with this entry +
comments
A description associated with + this entry
entryType
Either a Credit(1) or a Debit(2)
transactionId
A unique Identifier for a set + of related Credit and Debit entries that make up a "balanced" jounral Entry. + For a manual entry, this feild is a unique string.
+ For a system generated entry, the combination + of transactionId and entityId is unique +
entryType
Either a Credit(1) or a Debit(2)
portfolioGenerated
Flag determines if an entry is + generated by the portfolio (posted automatically by + the system during lifecycle of loan and saving + products) or manually created by using the Create (Balanced) Journal + Entries API +
reversed
Flag determines if this manual + journal entry has been reversed using the Reverse a Journal Entry API.
+ Note: A journal entry is reversed by logging debits + for all credits that make up the Journal entry and + vice-versa +
+
+
+ +   +
+
+

List Journal Entries

+
Arguments
+
+
officeId
+
+ Integer optional +
+
glAccountId
+
+ Integer optional +
+
portfolioGenerated
+
+ Boolean optional +
+
Flag determines if portfolio generated Journal + Entries (posted automatically by the system + during lifecycle of loan and saving products) + shall also be returned
+ Set to "True" by default if not passed in explicity +
+
fromDate
+
+ Date (yyyy-MM-dd)optional +
+
Filters for Journal entries whose entry Date + is greater than or equal to the passed in Date +
+
toDate
+
+ Date (yyyy-MM-dd)optional +
+
Filters for Journal entries whose entry Date + is lesser than or equal to the passed in Date +
+
transactionId
+
+ String optional +
+
+

Example Requests:

+
journalentries?transactionId=PB37X8Y21EQUY4S
+
+
+
journalentries?officeId=1&glAccountId=17&portfolioGenerated=false&fromDate=2012-01-01&toDate=2013-01-01
+
+
+ +GET https://DomainName/api/v1/journalentries?transactionId=PB37X8Y21EQUY4S + + +[ + { + "id": 81, + "officeId": 1, + "officeName": "Head Office", + "glAccountName": "Something totally else", + "glAccountId": 17, + "glAccountCode": "340098", + "glAccountClassification": { + "id": 3, + "code": "accountType.equity", + "value": "EQUITY" + }, + "entryDate": [ + 2012, + 12, + 12 + ], + "entryType": { + "id": 2, + "code": "journalEntrytType.debit", + "value": "DEBIT" + }, + "amount": 120, + "transactionId": "PB37X8Y21EQUY4S", + "portfolioGenerated": false, + "createdByUserId": 1, + "createdDate": [ + 2012, + 12, + 13 + ], + "createdByUserName": "mifos", + "reversed": true + }, + { + "id": 82, + "officeId": 1, + "officeName": "Head Office", + "glAccountName": "Something else", + "glAccountId": 19, + "glAccountCode": "560050", + "glAccountClassification": { + "id": 3, + "code": "accountType.equity", + "value": "EQUITY" + }, + "entryDate": [ + 2012, + 12, + 12 + ], + "entryType": { + "id": 1, + "code": "journalEntryType.credit", + "value": "CREDIT" + }, + "amount": 120, + "transactionId": "PB37X8Y21EQUY4S", + "portfolioGenerated": false, + "createdByUserId": 1, + "createdDate": [ + 2012, + 12, + 13 + ], + "createdByUserName": "mifos", + "reversed": true + } +] + +
+
+ +   +
+
+

Create "Balanced" Journal Entries

+

+ Note: A Balanced (simple) Journal entry would + have atleast one "Debit" and one "Credit" entry whose + amounts are equal
+ Compound Journal entries may have "n" debits and "m" + credits where both "m" and "n" are greater than 0 + and the sum or all debits and all credits are equal +
+

+ + + + + + + + + + + + + + + + + + + + + + +
Mandatory Fields
officeId, entryDate +
credits
Details of the credits contained + in the journal entry. Each credit entry contains + the following items
+ glAccountId: Identifier of the general ledger + account against which credit entry shall be + made
+ amount: Amount of money involved in the credit +
+ comments: Optional description associated with + a credit entry + . +
debits
Details of the debits contained + in the journal entry. Each debit entry contains the following items
+ glAccountId: Identifier of the general ledger account against which the debit entry shall be + made
+ amount: Amount of money involved in the debit +
+ comments: Optional description associated with + a debit entry + . +
+
+
+ +POST https://DomainName/api/v1/journalentries + + +POST journalentries +Content-Type: application/json +Request Body: +{ +"officeId": 1, +"entryDate": "06 December 2012", +"comments": "Gifts for staff", +"locale": "en" , +"dateFormat": "dd MMMM yyyy", +"credits":[{"glAccountId":1, + "amount":5000}, + {"glAccountId":2, + "amount":5000} + ], +"debits":[{"glAccountId":3, + "amount":5000}, + {"glAccountId":4, + "amount":5000} + ] +} + + +{ + "resourceId": C1MAE935K0IAEYA +} + +
+
+ +   +
+
+

Retrieve a single Entry

+

Example Requests:

+
journalentries/1
+
+
+
+
journalentries/1?fields=officeName,glAccountId,entryType,amount
+
+
+ +GET https://DomainName/api/v1/journalentries/{entryId} + + +{ + "id": 22, + "officeId": 2, + "officeName": "sub branch 1", + "glAccountName": "Income from interest", + "glAccountId": 14, + "glAccountCode": "400001", + "glAccountClassification": { + "id": 4, + "code": "accountType.income", + "value": "INCOME" + }, + "entryDate": [ + 2012, + 11, + 2 + ], + "entryType": { + "id": 1, + "code": "journalEntryType.credit", + "value": "CREDIT" + }, + "amount": 900, + "transactionId": "13", + "portfolioGenerated": true, + "createdByUserId": 1, + "createdDate": [ + 2012, + 11, + 2 + ], + "createdByUserName": "mifos", + "reversed": false +} + +
+
+ +   +
+
+

Reverse a Journal Entry

+

+ Note: A journal entry is reversed by logging debits + for all credits that constitute the Journal entry and + vice-versa +

+
Arguments
+
+
command
+
+ String Mandatory, case-insensitive +
+
'reverse' : Reverse the Journal Entry
+
+
+
+ +GET https://DomainName/api/v1/journalentries/{transactionId} + + +POST journalentries/C1MAE935K0IAEYA?command=reverse +Content-Type: application/json + + +{ + "resourceId": C1MAE935K0IAEYA +} + +
+
+ + + + + -  

diff --git a/mifosng-provider/src/main/java/org/mifosplatform/portfolio/loanaccount/guarantor/api/GuarantorsApiResource.java b/mifosng-provider/src/main/java/org/mifosplatform/portfolio/loanaccount/guarantor/api/GuarantorsApiResource.java index ff095372d..105d5a2c0 100644 --- a/mifosng-provider/src/main/java/org/mifosplatform/portfolio/loanaccount/guarantor/api/GuarantorsApiResource.java +++ b/mifosng-provider/src/main/java/org/mifosplatform/portfolio/loanaccount/guarantor/api/GuarantorsApiResource.java @@ -39,7 +39,7 @@ import org.springframework.stereotype.Component; @Scope("singleton") public class GuarantorsApiResource { - private static final Set RESPONSE_DATA_PARAMETERS = new HashSet(Arrays.asList("guarantorTypeId", "entityId", + private static final Set RESPONSE_DATA_PARAMETERS = new HashSet(Arrays.asList("guarantorType", "entityId", "firstname", "lastname", "addressLine1", "addressLine2", "city", "state", "zip", "country", "mobileNumber", "housePhoneNumber", "comment", "dob")); diff --git a/mifosng-provider/src/main/java/org/mifosplatform/portfolio/loanaccount/guarantor/command/GuarantorCommand.java b/mifosng-provider/src/main/java/org/mifosplatform/portfolio/loanaccount/guarantor/command/GuarantorCommand.java index bf2464f9e..750e768af 100644 --- a/mifosng-provider/src/main/java/org/mifosplatform/portfolio/loanaccount/guarantor/command/GuarantorCommand.java +++ b/mifosng-provider/src/main/java/org/mifosplatform/portfolio/loanaccount/guarantor/command/GuarantorCommand.java @@ -17,7 +17,6 @@ import org.mifosplatform.portfolio.loanaccount.guarantor.domain.GuarantorType; public class GuarantorCommand { /*** Fields for current customers serving as guarantors **/ - private final Long loanId; private final Integer guarantorTypeId; private final Long entityId; @@ -35,11 +34,10 @@ public class GuarantorCommand { private final String comment; private final LocalDate dob; - public GuarantorCommand(final Long loanId, final Integer guarantorTypeId, final Long entityId, final String firstname, + public GuarantorCommand(final Integer guarantorTypeId, final Long entityId, final String firstname, final String lastname, final String addressLine1, final String addressLine2, final String city, final String state, final String zip, final String country, final String mobileNumber, final String housePhoneNumber, final String comment, final LocalDate dob) { - this.loanId = loanId; /*** Fields for current entities serving as guarantors **/ this.guarantorTypeId = guarantorTypeId; this.entityId = entityId; @@ -73,8 +71,6 @@ public class GuarantorCommand { DataValidatorBuilder baseDataValidator = getDataValidator(dataValidationErrors); - baseDataValidator.reset().parameter(GUARANTOR_JSON_INPUT_PARAMS.LOAN_ID.getValue()).value(this.loanId).notNull() - .integerGreaterThanZero(); baseDataValidator.reset().parameter(GUARANTOR_JSON_INPUT_PARAMS.GUARANTOR_TYPE_ID.getValue()).value(this.guarantorTypeId).notNull() .inMinMaxRange(GuarantorType.getMinValue(), GuarantorType.getMaxValue()); diff --git a/mifosng-provider/src/main/java/org/mifosplatform/portfolio/loanaccount/guarantor/serialization/GuarantorCommandFromApiJsonDeserializer.java b/mifosng-provider/src/main/java/org/mifosplatform/portfolio/loanaccount/guarantor/serialization/GuarantorCommandFromApiJsonDeserializer.java index e49e672f3..45a2ca6be 100755 --- a/mifosng-provider/src/main/java/org/mifosplatform/portfolio/loanaccount/guarantor/serialization/GuarantorCommandFromApiJsonDeserializer.java +++ b/mifosng-provider/src/main/java/org/mifosplatform/portfolio/loanaccount/guarantor/serialization/GuarantorCommandFromApiJsonDeserializer.java @@ -44,7 +44,6 @@ public final class GuarantorCommandFromApiJsonDeserializer extends AbstractFromA final JsonElement element = fromApiJsonHelper.parse(json); - Long loanId = fromApiJsonHelper.extractLongNamed(GUARANTOR_JSON_INPUT_PARAMS.LOAN_ID.getValue(), element); Integer guarantorTypeId = fromApiJsonHelper.extractIntegerSansLocaleNamed(GUARANTOR_JSON_INPUT_PARAMS.GUARANTOR_TYPE_ID.getValue(), element); Long entityId = fromApiJsonHelper.extractLongNamed(GUARANTOR_JSON_INPUT_PARAMS.ENTITY_ID.getValue(), element); @@ -61,7 +60,7 @@ public final class GuarantorCommandFromApiJsonDeserializer extends AbstractFromA String comment = fromApiJsonHelper.extractStringNamed(GUARANTOR_JSON_INPUT_PARAMS.COMMENT.getValue(), element); LocalDate dob = fromApiJsonHelper.extractLocalDateNamed(GUARANTOR_JSON_INPUT_PARAMS.DATE_OF_BIRTH.getValue(), element); - return new GuarantorCommand(loanId, guarantorTypeId, entityId, firstname, lastname, addressLine1, addressLine2, city, state, zip, + return new GuarantorCommand(guarantorTypeId, entityId, firstname, lastname, addressLine1, addressLine2, city, state, zip, country, mobileNumber, housePhoneNumber, comment, dob); } } \ No newline at end of file