Introduction

This is a list of issues that can happen in a FOLIO environment, and how to work around them. Often they have already been fixed in a later version of FOLIO, but the workarounds can be useful to resolve issues in a production environment before upgrading FOLIO. Whenever possible we should link to matching JIRA issues so that people can check the affected versions.

Encumbrance issues

Unreleased Encumbrance if Pending Payment and Payment transactions were removed before

Prerequisites

Pending Payment and Payment transactions were removed before

...

Introduction

This is a list of issues that can happen in a FOLIO environment, and how to work around them. Often they have already been fixed in a later version of FOLIO, but the workarounds can be useful to resolve issues in a production environment before upgrading FOLIO. Whenever possible we should link to matching JIRA issues so that people can check the affected versions.

Encumbrance issues

Unreleased Encumbrance for Open Order if Pending Payment and Payment transactions were removed before

Prerequisites

Pending Payment and Payment transactions were removed before

1. Get order transaction summary for order where we need to UnRelease encumbrance:

GET {{protocol}}://{{url}}:{{okapiport}}/finance-storage/order-transaction-summaries/{{orderId}}

Response sample:

{
    "id": "f2715f25-8504-4698-afd0-3025aa779ac6",
    "numTransactions": -1
}

Note : "orderId" possible to get from encumbrance "sourcePurchaseOrderId"

2. Update order transaction summary for order

PUT {{protocol}}://{{url}}:{{okapiport}}/finance-storage/order-transaction-summaries/{{orderId}}
Request sample:
{
    "id": "{{orderId}}",
    "numTransactions": 1
}
Note : Change only "numTransactions" : "Total number of encumbrances(transactions) expected to update for this order(for your case should be 1)

3. UnRelease encumbrance 

3.1 Set "status" to "Unreleased"

3.2 Set in the "amount" the same value as in "initialAmountEncumbered"

3.3 Set "amountExpended" and "amountAwaitingPayment" to ZERO

PUT {{protocol}}://{{url}}:{{okapiport}}/finance/release-encumbrance/{encumbranceId}

{
    "id": "fd65e1cf-6dd1-46e6-b491-034eb8acde7e",
    "amount": 54.65,
    "source": "PoLine",
    "currency": "USD"
    "fromFundId": "b8ee517d-e585-43ef-bb34-5e0fc999b8ca",
    "encumbrance": {
        "status": "Unreleased",
        "orderType": "One-Time",
        "reEncumber": true,
        "orderStatus": "Open",
        "subscription": false,
        "amountExpended": 0,
        "sourcePoLineId": "cad9474d-93d0-44f6-bd19-0bcae6a56137",
        "amountAwaitingPayment": 0,
        "sourcePurchaseOrderId": "021d67bb-b01d-42f4-8073-fd475a6c03de",
        "initialAmountEncumbered": 54.65
    },
    "fiscalYearId": "f28b758c-2bd8-480e-a5a3-eede648fdc34",
    "expenseClassId": "ba70820f-d8c9-4567-a8a8-1e3059d1e7ea",
    "transactionType": "Encumbrance"
}

4. Update Budget's amounts

Check that the encumbrance "amount" is not already included in the budget's "encumbered" amount.

If not then update budget's "encumbered" and "awaitingPayment" amounts :

1. New "encumbered" = Prev. budget's "encumbered" + encumbrance "amount"
2. New "awaitingPayment" = Prev. budget's "awaitingPayment" - encumbrance "amount"

PUT {{protocol}}://{{url}}:{{okapiport}}/finance/budgets/{{budgetId}}

{
  "id" : "{{budgetId}}",
  "_version" : 13,
  "name" : "ASIAHIST-FY2022",
  "budgetStatus" : "Active",
  "allowableEncumbrance" : 110.0,
  "allowableExpenditure" : 100.0,
  "allocated" : 23000.0,
  "awaitingPayment" : 0.0,
  "available" : 22850.0,
  "encumbered" : 54.65,
  "expenditures" : 0.0,
  "netTransfers" : 0.0,
  "unavailable" : 150.0,
  "overEncumbrance" : 0.0,
  "overExpended" : 0.0,
  "fundId" : "55f48dc6-efa7-4cfe-bc7c-4786efe493e3",
  "fiscalYearId" : "a06a95ef-5a96-4839-a2d9-ac484a25c261",
  "acqUnitIds" : [ ]
  "initialAllocation" : 23000.0,
  "allocationTo" : 0.0,
  "allocationFrom" : 0.0,
  "totalFunding" : 23000.0,
  "cashBalance" : 23000.0,
  "statusExpenseClasses" : [ ]
}

Unreleased Encumbrance for Closed Order if Pending Payment, Payment transactions and Invoice were removed before

Prerequisites

Pending Payment and Payment transactions were removed before

1 Save budgets information for further check and update

{{protocol}}://{{url}}:{{okapiport}}/finance/budgets?query=fundId=={{fundId}} 

Note : {{fundId}} please take from fund distributions

2. Reopen order

In scope of reopening status of the encumbrance will be set to "Unrelease", but amount of encumbrance and budget  are not always updated.

3. Check that encumbrance amount and budget amounts are updated if not go to item 4, 5, 6, 7 :

Encumbrance

• "status" to "Unreleased"
• "amount" the same value as in "initialAmountEncumbered"
• "amountExpended" and "amountAwaitingPayment" to ZERO

Budget

• New "encumbered" = Prev. budget's "encumbered" + encumbrance "amount"
• New "awaitingPayment" = Prev. budget's "awaitingPayment" - encumbrance "amount"

4. Get order transaction summary for order where we need to UnRelease encumbrance:

GET {{protocol}}://{{url}}:{{okapiport}}/finance-storage/order-transaction-summaries/{{orderId}}

Response sample:

{
    "id": "f2715f25-8504-4698-afd0-3025aa779ac6",
    "numTransactions": -1
}

Note : "orderId" possible to get from encumbrance "sourcePurchaseOrderId"

...

5. Update order transaction summary for order

PUT {{protocol}}://{{url}}:{{okapiport}}/finance-storage/order-transaction-summaries/{{orderId}}
Request sample:
{
    "id": "{{orderId}}",
    "numTransactions": 1
}
Note : Change only "numTransactions" : "Total number of encumbrances(transactions) expected to update for this order(for your case should be 1)

...

6. UnRelease encumbrance 

3.1 Set "status" to "Unreleased"

...

{
    "id": "fd65e1cf-6dd1-46e6-b491-034eb8acde7e",
    "amount": 54.65,
    "source": "PoLine",
    "currency": "USD"
    "fromFundId": "b8ee517d-e585-43ef-bb34-5e0fc999b8ca",
    "encumbrance": {
        "status": "Unreleased",
        "orderType": "One-Time",
        "reEncumber": true,
        "orderStatus": "Open",
        "subscription": false,
        "amountExpended": 0,
        "sourcePoLineId": "cad9474d-93d0-44f6-bd19-0bcae6a56137",
        "amountAwaitingPayment": 0,
        "sourcePurchaseOrderId": "021d67bb-b01d-42f4-8073-fd475a6c03de",
        "initialAmountEncumbered": 54.65
    },
    "fiscalYearId": "f28b758c-2bd8-480e-a5a3-eede648fdc34",
    "expenseClassId": "ba70820f-d8c9-4567-a8a8-1e3059d1e7ea",
    "transactionType": "Encumbrance"
}

...

7. Update Budget's amounts

Check that the encumbrance "amount" is not already included in the budget's "encumbered" amount.

If not then update budget's "encumbered" and "awaitingPayment" amounts :

1. New "encumbered" = Prev. budget's "encumbered" + encumbrance "amount"
2. New "awaitingPayment" = Prev. budget's "awaitingPayment" - encumbrance "amount"

PUT {{protocol}}://{{url}}:{{okapiport}}/finance/budgets/{{budgetId}}

{
  "id" : "{{budgetId}}",
  "_version" : 13,
  "name" : "ASIAHIST-FY2022",
  "budgetStatus" : "Active",
  "allowableEncumbrance" : 110.0,
  "allowableExpenditure" : 100.0,
  "allocated" : 23000.0,
  "awaitingPayment" : 0.0,
  "available" : 22850.0,
  "encumbered" : 54.65,
  "expenditures" : 0.0,
  "netTransfers" : 0.0,
  "unavailable" : 150.0,
  "overEncumbrance" : 0.0,
  "overExpended" : 0.0,
  "fundId" : "55f48dc6-efa7-4cfe-bc7c-4786efe493e3",
  "fiscalYearId" : "a06a95ef-5a96-4839-a2d9-ac484a25c261",
  "acqUnitIds" : [ ]
  "initialAllocation" : 23000.0,
  "allocationTo" : 0.0,
  "allocationFrom" : 0.0,
  "totalFunding" : 23000.0,
  "cashBalance" : 23000.0,
  "statusExpenseClasses" : [ ]
}

...

1. Get invoice transaction summary for invoice where need to update encumbrance reference:
GET {{protocol}}://{{url}}:{{okapiport}}/finance-storage/invoice-transaction-summaries/{{invoiceId}}

Response sample:
{
"id": "ae27a94f-6313-48c6-b887-2b703bafc25f",
"numPendingPayments": 1,
"numPaymentsCredits": 1
}

2. Get pending payments for invoice
GET all pending payments -> {{protocol}}://{{url}}:{{okapiport}}/finance-storage/transactions?query=sourceInvoiceLineId=={{invoiceLineId}}
Or
GET exact one pending payment where need to update encumbrance reference -> {{protocol}}://{{url}}:{{okapiport}}/finance-storage/transactions/{{pendingPaymentId}}

3. Update invoice transaction summary for invoice

PUT {{protocol}}://{{url}}:{{okapiport}}/finance-storage/invoice-transaction-summaries/{{invoiceId}}
Request sample:
{
"id": "{{invoiceId}}",
"numPendingPayments": 1,
"numPaymentsCredits": 1
}
Note : Change only "numPendingPayments" : "Total number of pending payments(transactions) expected to update for this invoice(for your case should be 1)
Don't update "numPaymentsCredits", because this is total number of payment transaction which will be created in invoice Pay time.
For your case I suppose body should be
{
"id": "{{invoiceId}}",
"numPendingPayments": 1,
"numPaymentsCredits": 15
}
4. Update pending payment with right encumbrance reference

PUT {{protocol}}://{{url}}:{{okapiport}}/finance-storage/transactions/{{pendingPaymentId}}
Request sample:
{
"id": "{{pendingPaymentId}}",
"amount": 4.6,
"awaitingPayment": {
"encumbranceId": "{{rightEncumbranceReference}}",
"releaseEncumbrance": true
},
"currency": "USD",
"fiscalYearId": "a06a95ef-5a96-4839-a2d9-ac484a25c261",
"fromFundId": "65032151-39a5-4cef-8810-5350eb316300",
"source": "Invoice",
"sourceInvoiceId": "ae27a94f-6313-48c6-b887-2b703bafc25f",
"sourceInvoiceLineId": "3e19f3c1-7a9f-4939-8083-06bf3afb4cae",
"transactionType": "Pending payment"
}
Success response : 204

...

1. Get order transaction summary for order where we need to release encumbrance:
GET {{protocol}}://{{url}}:{{okapiport}}/finance-storage/order-transaction-summaries/{{orderId}}

Response sample:

{
  "id": "f2715f25-8504-4698-afd0-3025aa779ac6",
  "numTransactions": -1
}

3. Update order transaction summary for order

PUT {{protocol}}://{{url}}:{{okapiport}}/finance-storage/order-transaction-summaries/{{orderId}}
Request sample:
{
"id": "{{orderId}}",
 "numTransactions": 1
}
Note : Change only "numTransactions" : "Total number of encumbrances(transactions) expected to update for this order(for your case should be 1) 

2. Release encumbrance for which duplication error occurs
POST {{protocol}}://{{url}}:{{okapiport}}/finance/release-encumbrance/{encumbranceId}

Request body is Empty

3. Remove "encumbranceId" from fund distributions

...