mockups

https://drive.google.com/drive/folders/1DR0ownDKS14PxhCrHWy14TD8sJA1mnbK

mod-invoice/mod-invoice-storage

Schemas

invoice

Add the batchGroupId field.
Add enclosureNeeded field

NOTE: We'll need a UI story to add this to the various invoice forms/views

Property	Type	Default	Required	Notes
batchGroupId	string	NA	Yes	UUID of the batchGroup (aka exportGroup) to associate with this invoice and corresponding voucher
enclosureNeeded	boolean	false	No	Indicates that an enclosure is needed for the check - only if payment method is check.

voucher

Add the batchGroupId field.
Remove the batchNumber field - no longer needed.

Copied over from invoice->batchGroupId

Property	Type	Default	Required	Notes
batchGroupId	string	NA	Yes	UUID of the batchGroup (aka exportGroup) to associate with this invoice and corresponding voucher

adjustment

add exportToAccounting

Property	Type	Default	Required	Notes
exportToAccounting	boolean	false	Yes	Whether or not to show this adjustment in batchedVoucherLines

batch_voucher_export

This record describes an batch voucher export job - metadata about the process which generates and uploads the batch voucher

Property	Type	Default	Required	Notes
id	string	NA	No	UUID of this export - System generated if not specified.
status	string	Pending	Yes	enum: Pending, Generated, Uploaded, Error
message	string	NA	No	Field for capturing additional context of status, e.g. an error message
batchGroupId	string	NA	Yes	UUID of the batch (aka exportGroup)
start	datetime	NA	Yes	This export is for all vouchers between start and end
end	datetime	NA	Yes	This export is for all vouchers between start and end
batchVoucherId	string	NA	No	UUID of the batch voucher if one exists yet
metadata	metadata	NA	No	System generated record metadata

batch_voucher

XML and JSON schemas/bindings are needed for this.

Immutable.

Potentially quite large.

Stored as json, but XML and JSON schemas/bindings are needed for this.

XML schema should favor elements over attributes as seen in the abbreviated example below.

High Level Example

{
"batchGroup": "LAWLIB",
"start": "2020-01-26T00:00:00Z",
"end": "2020-01-27T00:00:00Z",
"created": "2020-01-27T00:01:23Z",
"batchedVouchers": [
{
...
batchedVoucherLines: [
{
"fundCodes": [ "HIST", "CANHIST" ],
...
}, ...
]
}, ...
]
}

<batchVoucher>
<batchGroup>LAWLIB</batchGroup>
<start>2020-01-26T00:00:00Z</start>
<end>2020-01-27T00:00:00Z</end>
<created>2020-01-27T00:01:23Z</created>
<batchedVouchers>
<batchedVoucher>
...
<batchedVoucherLines>
<batchedVoucherLine>
...
</batchedVoucherLine>
</batchedVoucherLines>
</batchedVoucher>
...
</batchedVouchers>
</batchVoucher>

Property	Type	Default	Required	Notes
id	string	NA	N	UUID for the batch voucher - System generated if not provided.
batchGroup	string	NA	Y	lookup batchGroup→name using invoice.batchGroupId
start	datetime	NA	Y	from batch_voucher_export→start
end	datetime	NA	Y	from batch_voucher_export→end
created	datetime	NA	Y	System generated - when the batch voucher was generated
batchedVouchers	collection<batched_voucher>	NA	Y	array of batch_voucher
totalRecords	integer	NA	Y	total number of records in the array

batched_voucher

Property	Type	Default	Required	Notes
voucherNumber	string	NA	Y	from voucher → voucherNo
vendorInvoiceNo	string	NA	Y	from voucher → invoiceId; dereference to invoice → vendorInvoiceNo
folioInvoiceNo	string	NA	Y	from voucher → invoiceId; dereference to invoice → folioInvoiceNo
accountingCode	string	NA	Y	from voucher → accountingCode
voucherDate	datetime	NA	Y	from voucher → voucherDate
type	string	NA	Y	enum. from voucher → type
status	string	NA	Y	enum. from voucher → status
amount	number	NA	Y	from voucher → amount
systemCurrency	string	NA	Y
invoiceCurrency	string	NA	Y
exchangeRate	number	NA	N
invoiceNote	string	NA	N
vendorName	string	NA	Y
disbursementNumber	string	NA	N
disbursementDate	datetime	NA	N	Required if disbursementNumber is specified
disbursementAmount	number	NA	N
enclosureNeeded	boolean	false	N	Indicates that an enclosure is needed for the check - only if payment method is check.
batchedVoucherLines	collection<batched_voucher_line>	NA	Y

batched_voucher_line

Property	Type	Default	Required	Notes
externalAccountNumber	string	NA	Y	from voucher-line→externalAccountNumber
amount	number	NA	Y	from voucher-line→amount
fundCodes	collection<string>	NA	Y	from voucher-line→ fundDistributions; dereferenced to fund → code
adjustments	collection<adjustment>	NA	N	need to see: description relationToTotal - excluding separateFrom amount or percentage

export_configuration

Configuration information for a voucher export - there's only one of these for a given batchGroup

Property	Type	Default	Required	Notes
id	string	NA	Yes	UUID of the configuration record - this is the batchGroupId that this configuration is associated with. - Foreign Key
startTime	string	00:00	No	The time of day to trigger an export if enableScheduledExport == true. Use pattern to restrict to HH:MM
weekdays	collection<string>	NA	No	An array of weekdays (enum: Sunday, Monday, etc.) indicating which days to trigger exports on. If empty, indicates daily exports. Duplicates are not allowed.
enableScheduledExport	boolean	false	No	Whether or not to enable scheduled batch voucher exports
format	string	Application/json	No	enum: Application/json, Application/xml (desired format of the batch voucher)
uploadURI	string	NA	No	URI (ftp://host:port/path) batch vouchers should be uploaded to - use pattern to restrict to FTP URIs for now.
metadata	metadata	NA	No	System generated record metadata

credentials

Credentials used to upload batch vouchers. Part of the voucher export configuration, but separated for security reasons (separate permission to access, allows for show/hide button, etc.)

Property	Type	Default	Required	Notes
id	string	NA	No	UUID of this record - System generated if not provided
exportConfigId	string	NA	Yes	UUID of the export configuration these credentials are associated with, which is also the batchGroupId that the configuration is associated with. - Foreign Key
username	string	NA	Yes	username
password	string	NA	No	password
metadata	metadata	NA	No	System generated record metadata

batch_group

Controlled vocabulary. This is used when querying vouchers to be included in a batch voucher, e.g. GET /batch-voucher-storage/vouchers?query=invoice.batchGroupId==XYZ and voucherDate>=ABC and voucherDate<DEF

Need a system value that's ALWAYS there - so not reference or sample data...

{
  "id": "2a2cb998-1437-41d1-88ad-01930aaeadd5",
  "name": "FOLIO",
  "description": "default batch identifier for voucher export"
}

NOTE: We'll need a mockup and UI story for adding a settings area for this.

Property	Type	Default	Required	Notes
id	string	NA	No	UUID for this record - system generated if not specified
name	string	NA	Yes	Human readable name, e.g. "Ongoing orders" - Unique Index
description	string	NA	No	Free form description of this batch identifier
metadata	metadata	NA	No	System generated record metadata

APIs

batch-voucher-export-configurations

CRUD export configurations on a per-batchGroup basis
- batchGroupId
- startTime
- enableDailyExport (boolean)
- format (enum)
- ftp location (host/port/path)
- username/password

batch-voucher-exports

On-demand export of vouchers between start/end date/times
- Get all vouchers for the specified time period
- For each
  - Get all voucher lines
  - Pull out relevant info
  - Dereference UUIDs as needed (API lookups likely required)
- Build batch_voucher with the vouchers that have the specified batchGroupId and voucherDate between the specified start/end date/times.
- Persist batch_voucher
- Update voucher_export status as the export progresses (Pending, Generating, Generated, Uploading, Uploaded, Error)
- Return batch voucher in desired format
- Optionally - Upload to FTP server
  - connects to FTP using provided credentials
  - uploads the batch voucher
  - updates batch voucher export (e.g. status = uploaded)
- Only include vouchers for invoices w/ exportToAccounting=true

_timer

calls POST /batch-voucher/batch-voucher-exports/scheduled
runs every 5 (?) minutes

mod-invoice

Interface	Method	Path	Request	Response	Description	Notes
batch-voucher-exports	POST	/batch-voucher/batch-voucher-exports/scheduled	NA	202 batch_voucher_export 204	Conditionally create a batch voucher export	checks configuration, either returns w/ 204 or call POST /vouchers/export and returns results
batch-voucher-exports	POST	/batch-voucher/batch-voucher-exports	Query args: start (dateTime) end (dateTime) batchGroupId upload (true/false)	batch_voucher_export	Create a batch voucher export for the specified period	if upload == true, and ftp details exist in the export settings for this batchGroupId, upload the resulting batch voucher as the configured format/MIME type (conversion may be needed)
batch-voucher-exports	POST	/batch-voucher/batch-voucher-exports/<id>/upload	NA	202 batch_voucher_export	(Re)upload the batch voucher associated with this voucher export to the configured URI, using the configured credentials
batch-voucher-exports	GET	/batch-voucher/batch-voucher-exports	CQL Query	collection<batch_voucher_export>	List/search voucher exports
batch-voucher-exports	GET	/batch-voucher/batch-voucher-exports/<id>	NA	batch_voucher_export	Get a particular voucher export (data and metadata)
batch-voucher-exports	PUT	/batch-voucher/batch-voucher-exports/<id>	batch_voucher_export	204	Update a voucher export	probably only needed to update status
batch-vouchers	GET	/batch-voucher/batch-vouchers/<id>	NA	batch_voucher	Get a batch voucher by id	Honors accept header
batch-voucher.export-configurations	POST	/batch-voucher/export-configurations	export_configuration	export_configuration	Create a voucher export configuration	Proxy to storage module
batch-voucher.export-configurations	GET	/batch-voucher/export-configurations	CQL Query	collection<export_configuration>	List/search voucher export configs	Proxy to storage module
batch-voucher.export-configurations	GET	/batch-voucher/export-configurations/<id>	NA	export_configuration	Get a voucher export configuration by id	Proxy to storage module
batch-voucher.export-configurations	PUT	/batch-voucher/export-configurations/<id>	export_configuration	204	Edit a voucher export configuration	Proxy to storage module
batch-voucher.export-configurations	DELETE	/batch-voucher/export-configurations/<id>	NA	204	Delete a voucher export configuration	Proxy to storage module.
batch-groups	POST	/batch-groups	batch_group	batch_group	Create a batch_group	Proxy to storage module
batch-groups	GET	/batch-groups	CQL Query	collection<batch_group>	List/search batch_groups	Proxy to storage module
batch-groups	GET	/batch-groups/<id>	NA	batch_group	Get a batch_group by id	Proxy to storage module
batch-groups	PUT	/batch-groups/<id>	batch_group	204	Edit a batch_group	Proxy to storage module
batch-groups	DELETE	/batch-groups/<id>	NA	204	Delete a batch_group	Proxy to storage module. Disallow if batchGroup is in use by any invoice
batch-voucher.export-configurations.credentials	POST	/batch-voucher/export-configurations/<id>/credentials	credentials	credentials	Create a credentials record	Proxy to storage module
batch-voucher.export-configurations.credentials	GET	/batch-voucher/export-configurations/<id>/credentials	NA	credentials	Get the credentials for the specified export_configuration	Proxy to storage module
batch-voucher.export-configurations.credentials	PUT	/batch-voucher/export-configurations/<id>/credentials	credentials	204	Edit a credentials record	Proxy to storage module
batch-voucher.export-configurations.credentials	POST	/batch-voucher/export-configurations/<id>/credentials/test	NA	200	Test that you can connect to and log into the uploadURI with the configured credentials

mod-invoice-storage

Interface	Method	Path	Request	Response	Description	Notes
batch-voucher-storage.batch-voucher-exports	POST	/batch-voucher-storage/batch-voucher-exports		batch_voucher_export	Create a batch voucher export for the specified period
batch-voucher-storage.batch-voucher-exports	GET	/batch-voucher-storage/batch-voucher-exports	CQL Query	collection<batch_voucher_export>	List/search batch voucher exports
batch-voucher-storage.batch-voucher-exports	GET	/batch-voucher-storage/batch-voucher-exports/<id>	NA	batch_voucher_export	Get a particular batch voucher export (data and metadata)
batch-voucher-storage.batch-voucher-exports	DELETE	/batch-voucher-storage/batch-voucher-exports/<id>	NA	204	Delete a batch voucher export by id	Deletion also removes related batch-voucher if one exists
batch-voucher-storage.batch-voucher-exports	PUT	/batch-voucher-storage/batch-voucher-exports/<id>	batch_voucher_export	204	Update a batch voucher export	probably only needed to update status
batch-voucher-storage.batch-vouchers	POST	/batch-voucher-storage/batch-vouchers	batch_voucher	batch_voucher	Create a batch voucher
batch-voucher-storage.batch-vouchers	GET	/batch-voucher-storage/batch-vouchers/<id>	NA	batch_voucher	Get a batch voucher by id
batch-voucher-storage.batch-vouchers	DELETE	/batch-voucher-storage/batch-vouchers/<id>	NA	204	Delete a batch voucher by id	Deletion removes reference from related export record
batch-voucher-storage.export-configurations	POST	/batch-voucher-storage/export-configurations	export_configuration	export_configuration	Create a voucher export configuration
batch-voucher-storage.export-configurations	GET	/batch-voucher-storage/export-configurations	CQL Query	collection<export_configuration>	List/search voucher export configs
batch-voucher-storage.export-configurations	GET	/batch-voucher-storage/export-configurations/<id>	NA	export_configuration	Get a voucher export configuration by id
batch-voucher-storage.export-configurations	PUT	/batch-voucher-storage/export-configurations/<id>	export_configuration	204	Edit a voucher export configuration
batch-voucher-storage.export-configurations	DELETE	/batch-voucher-storage/export-configurations/<id>	NA	204	Delete a voucher export configuration	Removal also results in removal of the associated credentials record in a db transaction
batch-group-storage.batch-groups	POST	/batch-group-storage/batch-groups	batch_group	batch_group	Create a batch_group
batch-group-storage.batch-groups	GET	/batch-group-storage/batch-groups	CQL Query	collection<batch_group>	List/search batch_groups
batch-group-storage.batch-groups	GET	/batch-group-storage/batch-groups/<id>	NA	batch_group	Get a batch_group by id
batch-group-storage.batch-groups	PUT	/batch-group-storage/batch-groups/<id>	batch_group	204	Edit a batch_group
batch-group-storage.batch-groups	DELETE	/batch-group-storage/batch-groups/<id>	NA	204	Delete a batch_group
batch-voucher-storage.export-configurations.credentials	POST	/batch-voucher-storage/export-configurations/<id>/credentials	credentials	credentials	Create a credentials record
batch-voucher-storage.export-configurations.credentials	GET	/batch-voucher-storage/export-configurations/<id>/credentials	NA	credentials	Get the credentials for the specified export_configuration
batch-voucher-storage.export-configurations.credentials	PUT	/batch-voucher-storage/export-configurations/<id>/credentials	credentials	204	Edit a credentials record
batch-voucher-storage.export-configurations.credentials	DELETE	/batch-voucher-storage/export-configurations/<id>/credentials	NA	204	Delete a credentials record

Batch Voucher Generation

Batch voucher generation happens in a background task/job and is triggered via the POST /batch-voucher/batch-voucher-exports endpoint.

Query vouchers
- exportToAccount=true
- invoice.batchGroupId=specified batchGroupId
- voucherDate >= start
- voucherDate <= end
Dereference fields as needed - instead of including UUIDs, retreive those records and use their code/name/etc. in the batchVoucher. Details TBD

edge-voucher (WIP)

New edge module built upon edge-common

APIs

edge-batch-vouchers

Honor Accept header
take start/end date/times as params
Make this synchronous so the AP system only needs to make a single call.

Interface

Method

Path

Request

Response

Description

Notes

edge-batch-vouchers

POST

/batch-vouchers

Query args:

apiKey
start (dateTime)
end (dateTime)
batchGroup

batch_voucher

Create a voucher export for the specified period and return the resulting batch voucher

Parses API key

Looks up institutional user credentials

Logs into OKAPI

Looks up batchGroupId using batchGroup

Makes a call to POST /batch-voucher/exports

Wait for the batch voucher to be available

Return the batch voucher

Honors Accept header

Stories

mod-invoice-storage

MODINVOSTO-48 - Getting issue details... STATUS
MODINVOSTO-50 - Getting issue details... STATUS
MODINVOSTO-51 - Getting issue details... STATUS
MODINVOSTO-52 - Getting issue details... STATUS
MODINVOSTO-53 - Getting issue details... STATUS
MODINVOSTO-54 - Getting issue details... STATUS

mod-invoice

MODINVOICE-126 - Getting issue details... STATUS
MODINVOICE-127 - Getting issue details... STATUS
MODINVOICE-128 - Getting issue details... STATUS
MODINVOICE-129 - Getting issue details... STATUS
MODINVOICE-130 - Getting issue details... STATUS
MODINVOICE-131 - Getting issue details... STATUS
MODINVOICE-132 - Getting issue details... STATUS
MODINVOICE-133 - Getting issue details... STATUS
MODINVOICE-134 - Getting issue details... STATUS

edge-batch-voucher

Project setup
Create batch-voucher-export API

Notes

Need to add batchGroupId to invoice and voucher
Ability to export vouchers between start and end date/time
- Get all vouchers for the specified time period
- For each
  - Get all voucher lines
  - Pull out relevant info
  - Dereference UUIDs as needed (API lookups likely required)
- Build report in json (new schema, details tbd)
- Persist report
- Return report in desired format
API for composite voucher ? Might not be needed
Edge API that generates returns voucher report
- Honor Accept header
- take start/end date/times as params
Need API to store export settings on a per-batchGroup basis
- batchGroupId
- startTime
- enableDailyExport (boolean)
- format (enum)
- ftp location (host/port/path)
- username/password
Need API to store generated reports
- can be downloaded again
- can be re-sent (ftp) if configured
- have status and metadata, maybe indicator of whether they were manually generated or from daily export
Need Timer task for each voucher export configuration w/ enableDailyExport = true
- runs at startTime
- calls API to generate report
- connects to FTP using provided credentials
- uploads the report
- updates report metadata (e.g. status = uploaded)

Browser not supported