001 /*
002 * Copyright 2011 The Kuali Foundation.
003 *
004 * Licensed under the Educational Community License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.opensource.org/licenses/ecl2.php
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.kuali.kfs.module.purap.document.service;
017
018 import java.sql.Date;
019 import java.util.Collection;
020 import java.util.HashMap;
021 import java.util.Iterator;
022 import java.util.List;
023
024 import org.kuali.kfs.module.purap.document.PaymentRequestDocument;
025 import org.kuali.kfs.module.purap.document.PurchaseOrderDocument;
026 import org.kuali.kfs.module.purap.document.VendorCreditMemoDocument;
027 import org.kuali.kfs.module.purap.util.VendorGroupingHelper;
028 import org.kuali.kfs.vnd.businessobject.PaymentTermType;
029 import org.kuali.rice.kew.exception.WorkflowException;
030 import org.kuali.rice.kns.util.KualiDecimal;
031
032 /**
033 * Defines methods that must be implemented by a PaymentRequestService implementation.
034 */
035 public interface PaymentRequestService extends AccountsPayableDocumentSpecificService {
036
037 /**
038 * Obtains a list of payment request documents given the purchase order id.
039 *
040 * @param poDocId The purchase order id to be used to obtain a list of payment request documents.
041 * @return The List of payment request documents given the purchase order id.
042 */
043 public List<PaymentRequestDocument> getPaymentRequestsByPurchaseOrderId(Integer poDocId);
044
045 /**
046 * Obtains a list of payment request documents given the purchase order id, the invoice amount
047 * and the invoice date.
048 *
049 * @param poId The purchase order id used to obtain the payment request documents.
050 * @param invoiceAmount The invoice amount used to obtain the payment request documents.
051 * @param invoiceDate The invoice date used to obtain the payment request documents.
052 * @return The List of payment request documents that match the given criterias (purchase order id, invoice amount and invoice date).
053 */
054 public List getPaymentRequestsByPOIdInvoiceAmountInvoiceDate(Integer poId, KualiDecimal invoiceAmount, Date invoiceDate);
055
056 /**
057 * Obtains a list of payment request documents given the vendorHeaderGeneratedIdentifier, vendorDetailAssignedIdentifier and the invoice number.
058 *
059 * @param vendorHeaderGeneratedIdentifier The vendorHeaderGeneratedIdentifier used to obtain the payment request documents.
060 * @param vendorDetailAssignedIdentifier The vendorDetailAssignedIdentifier used to obtain the payment request documents.
061 * @return The List of payment request documents that match the given criterias.
062 */
063 public List getPaymentRequestsByVendorNumber(Integer vendorHeaderGeneratedIdentifier, Integer vendorDetailAssignedIdentifier);
064
065 /**
066 * Obtains a list of payment request documents given the vendorHeaderGeneratedIdentifier, vendorDetailAssignedIdentifier and the invoice number.
067 *
068 * @param vendorHeaderGeneratedIdentifier The vendorHeaderGeneratedIdentifier used to obtain the payment request documents.
069 * @param vendorDetailAssignedIdentifier The vendorDetailAssignedIdentifier used to obtain the payment request documents.
070 * @param invoiceNumber The invoice number used to obtain the payment request documents.
071 * @return The List of payment request documents that match the given criterias.
072 */
073 public List getPaymentRequestsByVendorNumberInvoiceNumber(Integer vendorHeaderGeneratedIdentifier, Integer vendorDetailAssignedIdentifier, String invoiceNumber);
074
075
076
077 /**
078 * Determines whether the invoice date is after today.
079 *
080 * @param invoiceDate The invoice date to be determined whether it's after today.
081 * @return boolean true if the given invoice date is after today.
082 */
083 public boolean isInvoiceDateAfterToday(Date invoiceDate);
084
085 /**
086 * Performs the processing to check whether the payment request is a duplicate and if so, adds
087 * the information about the type of duplication into the resulting HashMap to be returned by this method.
088 *
089 * @param document The payment request document to be processed/checked for duplicates.
090 * @return The HashMap containing "PREQDuplicateInvoice" as the key and the string
091 * describing the types of duplication as the value.
092 */
093 public HashMap<String, String> paymentRequestDuplicateMessages(PaymentRequestDocument document);
094
095 /**
096 * Calculate based on the terms and calculate a date 10 days from today. Pick the one that is the farthest out. We always
097 * calculate the discount date, if there is one.
098 *
099 * @param invoiceDate The invoice date to be used in the pay date calculation.
100 * @param terms The payment term type to be used in the pay date calculation.
101 * @return The resulting pay date given the invoice date and the terms.
102 */
103 public java.sql.Date calculatePayDate(Date invoiceDate, PaymentTermType terms);
104
105 /**
106 * Marks a payment request on hold.
107 *
108 * @param document The payment request document to be marked as on hold.
109 * @param note The note to be added to the payment request document while being marked as on hold.
110 * @return The PaymentRequestDocument with updated information.
111 * @throws Exception
112 */
113 public PaymentRequestDocument addHoldOnPaymentRequest(PaymentRequestDocument document, String note) throws Exception;
114
115 /**
116 * Removes a hold on a payment request.
117 *
118 * @param document The payment request document whose hold is to be removed.
119 * @param note The note to be added to the payment request document while its hold is being removed.
120 * @return The PaymentRequestDocument with updated information.
121 * @throws Exception
122 */
123 public PaymentRequestDocument removeHoldOnPaymentRequest(PaymentRequestDocument document, String note) throws Exception;
124
125 /**
126 * Obtains the payment request document given the purapDocumentIdentifier.
127 *
128 * @param poDocId The purapDocumentIdentifier of the payment request document to be obtained.
129 * @return The payment request document whose purapDocumentIdentifier matches with the input parameter.
130 */
131 public PaymentRequestDocument getPaymentRequestById(Integer poDocId);
132
133 /**
134 * Obtains the payment request document given the document number.
135 *
136 * @param documentNumber The document number to be used to obtain the payment request document.
137 * @return The payment request document whose document number matches with the given input parameter.
138 */
139 public PaymentRequestDocument getPaymentRequestByDocumentNumber(String documentNumber);
140
141 /**
142 * Marks a payment request as requested to be canceled.
143 *
144 * @param document The payment request document to be marked as requested to be canceled.
145 * @param note The note to be added to the payment request document while being marked as requested to be canceled.
146 * @throws Exception
147 */
148 public void requestCancelOnPaymentRequest(PaymentRequestDocument document, String note) throws Exception;
149
150 /**
151 * Returns true if the payment request has been extracted
152 *
153 * @param document The payment request document to be determined whether it is extracted.
154 * @return boolean true if the payment request document is extracted.
155 */
156 public boolean isExtracted(PaymentRequestDocument document);
157
158 /**
159 * Removes a request cancel on payment request.
160 *
161 * @param document The payment request document to be used for request cancel.
162 * @param note The note to be added to the payment request document upon the removal of the request cancel.
163 * @throws Exception
164 */
165 public void removeRequestCancelOnPaymentRequest(PaymentRequestDocument document, String note) throws Exception;
166
167 /**
168 * Resets a Payment Request that had an associated Payment Request or Credit Memo cancelled externally.
169 *
170 * @param paymentRequest The extracted payment request document to be resetted.
171 * @param note The note to be added to the payment request document upon its reset.
172 */
173 public void resetExtractedPaymentRequest(PaymentRequestDocument paymentRequest, String note);
174
175 /**
176 * Cancels a PREQ that has already been extracted if allowed.
177 *
178 * @param paymentRequest The extracted payment request document to be canceled.
179 * @param note The note to be added to the payment request document.
180 */
181 public void cancelExtractedPaymentRequest(PaymentRequestDocument paymentRequest, String note);
182
183 /**
184 * Get all the payment requests that are immediate and need to be extracted to PDP.
185 *
186 * @param chartCode The chart code to be used as one of the criterias to retrieve the payment request documents.
187 * @return The iterator of the list of the resulting payment request documents returned by the paymentRequestDao.
188 */
189 public Collection<PaymentRequestDocument> getImmediatePaymentRequestsToExtract(String chartCode);
190
191 /**
192 * Get all the payment requests that match a credit memo.
193 *
194 * @param cmd The credit memo document to be used to obtain the payment requests.
195 * @return The iterator of the resulting payment request documents returned by the paymentRequestDao.
196 */
197 public Iterator<PaymentRequestDocument> getPaymentRequestsToExtractByCM(String campusCode, VendorCreditMemoDocument cmd);
198
199 /**
200 * Get all the payment requests that match a vendor.
201 *
202 * @param vendor
203 * @param onOrBeforePaymentRequestPayDate only payment requests with a pay date on or before this date will be extracted
204 * @return Collection of the resulting payment request documents returned by the paymentRequestDao.
205 */
206 public Collection<PaymentRequestDocument> getPaymentRequestsToExtractByVendor(String campusCode, VendorGroupingHelper vendor, Date onOrBeforePaymentRequestPayDate);
207
208 /**
209 * Get all the payment requests that need to be extracted.
210 *
211 * @return The Collection of the resulting payment request documents returned by the paymentRequestDao.
212 */
213 public Collection<PaymentRequestDocument> getPaymentRequestsToExtract(Date onOrBeforePaymentRequestPayDate);
214
215 /**
216 * Get all the special payment requests for a single chart that need to be extracted.
217 *
218 * @param chartCode The chart code to be used as one of the criterias to retrieve the payment request documents.
219 * @return The Collection of the resulting payment request documents returned by the paymentRequestDao.
220 */
221 public Collection<PaymentRequestDocument> getPaymentRequestsToExtractSpecialPayments(String chartCode, Date onOrBeforePaymentRequestPayDate);
222
223 /**
224 * Get all the regular payment requests for a single campus.
225 *
226 * @param chartCode The chart code to be used as one of the criterias to retrieve the payment request documents.
227 * @return The collection of the resulting payment request documents returned by the paymentRequestDao.
228 */
229 public Collection<PaymentRequestDocument> getPaymentRequestToExtractByChart(String chartCode, Date onOrBeforePaymentRequestPayDate);
230
231 /**
232 * Recalculate the payment request.
233 *
234 * @param pr The payment request document to be calculated.
235 * @param updateDiscount boolean true if we also want to calculate the discount items for the payment request.
236 */
237 public void calculatePaymentRequest(PaymentRequestDocument pr, boolean updateDiscount);
238
239 /**
240 * Performs calculations on the tax edit area, generates and adds NRA tax charge items as below the line items, with their accounting lines;
241 * the calculation will activate updates on the account summary tab and the general ledger entries as well.
242 *
243 * The non-resident alien (NRA) tax lines consist of four possible sets of tax lines:
244 * - Federal tax lines
245 * - Federal Gross up tax lines
246 * - State tax lines
247 * - State Gross up tax lines
248 *
249 * Federal tax lines are generated if the federal tax rate in the payment request is not zero.
250 * State tax lines are generated if the state tax rate in the payment request is not zero.
251 * Gross up tax lines are generated if the tax gross up indicator is set on the payment request and the tax rate is not zero.
252 *
253 * @param preq The payment request the NRA tax lines will be added to.
254 *
255 */
256 public void calculateTaxArea(PaymentRequestDocument preq);
257
258 /**
259 * Populate payment request.
260 *
261 * @param preq The payment request document to be populated.
262 */
263 public void populatePaymentRequest(PaymentRequestDocument preq);
264
265 /**
266 * Populate and save payment request.
267 *
268 * @param preq The payment request document to be populated and saved.
269 */
270 public void populateAndSavePaymentRequest(PaymentRequestDocument preq) throws WorkflowException;
271
272 /**
273 * Retrieve a list of PREQs that aren't approved, check to see if they match specific requirements, then auto-approve them if
274 * possible.
275 *
276 * @return boolean true if the auto approval of payment requests has at least one error.
277 */
278 public boolean autoApprovePaymentRequests();
279 /**
280 * Checks whether the payment request document is eligible for auto approval. If so, then updates
281 * the status of the document to auto approved and calls the documentService to blanket approve
282 * the document, then returns false.
283 * If the document is not eligible for auto approval then returns true.
284 *
285 * @param docNumber The payment request document number (not the payment request ID) to be auto approved.
286 * @param defaultMinimumLimit The default minimum limit amount to be used in determining the eligibility of the document to be auto approved.
287 * @return boolean true if the payment request document is not eligible for auto approval.
288 * @throws RuntimeException To indicate to Spring transactional management that the transaction for this document should be rolled back
289 */
290 public boolean autoApprovePaymentRequest(String docNumber, KualiDecimal defaultMinimumLimit);
291
292 /**
293 * Checks whether the payment request document is eligible for auto approval. If so, then updates
294 * the status of the document to auto approved and calls the documentService to blanket approve
295 * the document, then returns false.
296 * If the document is not eligible for auto approval then returns true.
297 *
298 * @param doc The payment request document to be auto approved.
299 * @param defaultMinimumLimit The default minimum limit amount to be used in determining the eligibility of the document to be auto approved.
300 * @return boolean true if the payment request document is not eligible for auto approval.
301 * @throws RuntimeException To indicate to Spring transactional management that the transaction for this document should be rolled back
302 */
303 public boolean autoApprovePaymentRequest(PaymentRequestDocument doc, KualiDecimal defaultMinimumLimit);
304
305 /**
306 * Mark a payment request as being paid and set the payment request's paid date as the processDate.
307 *
308 * @param pr The payment request document to be marked as paid and paid date to be set.
309 * @param processDate The date to be set as the payment request's paid date.
310 */
311 public void markPaid(PaymentRequestDocument pr, Date processDate);
312
313 /**
314 * This method specifies whether the payment request document has a discount item.
315 *
316 * @param preq The payment request document to be verified whether it has a discount item.
317 * @return boolean true if the payment request document has at least one discount item.
318 */
319 public boolean hasDiscountItem(PaymentRequestDocument preq);
320
321 /**
322 * Changes the current vendor to the vendor passed in.
323 *
324 * @param preq
325 * @param headerId
326 * @param detailId
327 * @param primaryHeaderId
328 * @param primaryDetailId
329 */
330 public void changeVendor(PaymentRequestDocument preq, Integer headerId, Integer detailId);
331
332 /**
333 * A method to create the description for the payment request document.
334 *
335 * @param purchaseOrderIdentifier The purchase order identifier to be used as part of the description.
336 * @param vendorName The vendor name to be used as part of the description.
337 * @return The resulting description string for the payment request document.
338 */
339 public String createPreqDocumentDescription(Integer purchaseOrderIdentifier, String vendorName);
340
341 /**
342 * Determines if there are active payment requests for a purchase order.
343 *
344 * @param purchaseOrderIdentifier
345 * @return
346 */
347 public boolean hasActivePaymentRequestsForPurchaseOrder(Integer purchaseOrderIdentifier);
348
349 public void processPaymentRequestInReceivingStatus();
350
351 /**
352 * Payment Requests created in the previous fiscal year get backdated if we're at the beginning of the new fiscal year (i.e.
353 * prior to first closing)
354 *
355 * @param paymentRequestDocument
356 * @return
357 */
358 public boolean allowBackpost(PaymentRequestDocument paymentRequestDocument);
359
360 public boolean isPurchaseOrderValidForPaymentRequestDocumentCreation(PaymentRequestDocument paymentRequestDocument,PurchaseOrderDocument po);
361
362 /**
363 * Removes additional charge items that are not eligible on the payment request document.
364 *
365 * @param document
366 */
367 public void removeIneligibleAdditionalCharges(PaymentRequestDocument document);
368
369 public boolean encumberedItemExistsForInvoicing(PurchaseOrderDocument document);
370 }
371