The Smart Upload Manager is an additional feature for Kantata OX. For access, please contact Customer Success.
SMART UPLOAD MANAGER TRAINING COURSES
To assist you in learning more about the Smart Upload Manager, visit the Smart Upload Manager Training Courses.
Data Sets for Invoicing
Smart Upload Manager has four data sets related to managing invoices in Kantata OX:
- Invoice Additional Items
- Invoices Fixed Fee Items
- Invoice Payments
Invoices Data Set
The Invoices data set is responsible for setting the invoice header fields, like Purchase Order and Invoice Message. Billable time entries and expenses can also be added to invoices with this data set. If you do not provide an invoice number, the system will auto-number the invoice based on the last invoice number used. If an invoice date is not provided, invoices created will default to today’s date.
Details on all supported fields in the Invoices data set can be found in the links below:
Invoice Additional Items Data Set
The Invoice Additional Items data set is where additional items can be added to invoices. This is a dependent data set and must be on the same blueprint as an Invoices data set. An
external_invoice_id must be on each line in this data set to properly associate the additional item with the core invoice from the Invoices data set. Additional items must have a value in the
amount field, this number can be positive or negative and will increase or decrease the total invoice amount accordingly.
Details on all supported fields in the Invoice Additional Items data set can be found in the links below:
Invoice Fixed Fee Items Data Set
The Invoice Fixed Fee Items data allows fixed fee items to be added to invoices. Similar to the Invoice Additional Items data set, this data set is a dependent data set and must also be on the same blueprint as an Invoices data set. An
external_invoice_id must be on each line in this data set to properly associate the fixed fee item with the core invoice from the Invoices data set. Each line must reference a task by setting either the
external_story_id field. The task must be fixed fee and billable in order to be added to the invoice, and the fixed fee
amount must be positive.
Details on all supported fields in the Invoice Fixed Fee Items data set can be found in the links below:
Invoice Payments Data Set
Invoices can be marked as paid via the Invoice Payments data set. Invoice Payments are not a dependent data set and do not have to be on a blueprint with a related Invoices data set. The
workspace_id field is required for all lines when uploading a payment. If a payment does not have an
invoice_id, then the
amount_in_cents field is required. This will create a stand-alone invoice to the specified project, and this invoice cannot be updated or associated with any invoice after created. If an
invoice_id is provided, any value in
amount_in_cents will be ignored and the full amount of the specified invoice will be paid.
Details on all supported fields in the Invoice Payments data set can be found in the links below:
Creating Invoices in SUM
Creating an invoice uses the Invoices data set as a base, with the dependent data sets Invoice Additional Items and Invoice Fixed Fee as related and supplemental data sets. You cannot create an invoice using only the Invoice Additional Items or Invoice Fixed Fee Items data sets alone. The invoice created cannot have a negative total amount. The Invoices data set requires only one CSV row per invoice, the dependent data sets may have multiple CSV rows associated with the same invoice.
Creating the Invoice Header
The Invoice header contains the fields in the OX UI screenshot below. Only the
payment_schedule field is required when creating invoices via SUM. Acceptable values for
payment_schedule are 0, 15, 30, and 60.
Populate the desired invoice header fields for each row of the CSV file. Each of the above fields can be set only once per invoice.
Adding Time Entries and Expenses to Invoices
Time entries and expenses are contained within the Invoices data set. They are added by populating the
time_entry_ids and the
expense_ids fields. These fields support an array of IDs. The array must be comma separated and contained within square brackets. An example array is shown below.
Example Array of Time Entry or Expense IDs:
Time entries can alternately be supplied via the
external_time_entry_ids field if the time entries to be invoiced were uploaded via the Smart Upload Manager. The same is true for the
external_expense_ids for expenses uploaded via the Smart Upload Manager. If the time entries or expenses to be invoices do not have SUM external references, you will have to supply the system IDs. Time entry IDs and expense IDs—either system or external—cannot be combined into the same field.
Supplied time entries or expenses but be billable and not already on any other invoice. If they are tracked to a task, that task must be set as Time & Materials. Fixed Fee tasks do not allow time or expenses tracked to them to be invoices. If your company has time approvals or expense approvals enabled, then the time and/or expenses must be approved before they can be invoiced.
Adding Additional Items and Fixed Fee Items to Invoices
Invoices with Fixed Fee Items or Additional Items must have those items added via their respective dependent data sets. Each row of the data set must reference an invoice in the parent Invoices data set by setting the
Fixed Fee items must reference a valid task on the same project that the invoice is being created for. A valid task is unarchived and has a Fixed Fee task billing mode. Time and Materials type tasks cannot be invoiced as a Fixed Fee Item.
Multiple Additional Items and Fixed Fee Items can be added per invoice in their respective dependent data sets. Each line must contain the parent invoice’s
external_invoice_id that was set on the parent Invoices data set. The
amount value does not need to match the total budget of the fixed fee task, and can even exceed the associated task’s budget. This
amount value is in whole units (e.g. dollars) See example below:
The Invoice Fixed Fee Items data set above will link three fixed fee items (one per row) to two different invoices. The first two lines will add fixed fee items to the invoice with the external ID of invoice_1, and the third line will add one fixed fee item to the invoice with the external ID of invoice_2. You can see that all three rows are related to different tasks as determined by the values in the
external_story_id column. Note that the
workspace_id column and the
story_id are intentionally left blank in favor of the Smart Reference Keys references set in the last two columns.
Updating Invoices in SUM
To update an invoice in SUM, you must supply either the
external_invoice_id or the
id of the desired invoice(s) on the Invoices data set’s CSV. You can then populate the desired columns and fields for the updates you would like to make to the existing invoices.
Neither fixed fee items nor additional items can be updated via the API and therefore cannot be updated with SUM. New additional items and fixed fee items also cannot be added to existing invoices via API and therefore are not supported in SUM. Only the fields in the Invoices data set can be updated via SUM after initial invoice creation.
If you would like to add or update fixed fee items or additional items to already created invoices, this must be done through Kantata OX.
Creating Invoice Payments in SUM
SUM allows the bulk creation of payment objects. These objects can be associated to an invoice or only associated to a project. Payment amount values are in subunits—or cents—and is a different magnitude from the
amount field in the Fixed Fee Items and Additional Items data sets. Ex: 45075 = $450.75.
Creating a Payment to a Invoice
In SUM, create a blueprint with the Invoice Payment data set. This data set is not dependent and doesn't require an Invoices data set to be on the same blueprint. Input the ‘invoice_id’ or the
external_invoice_id of the invoice you’d like to pay. Input the
external_workspace_id to indicate which project. This project ID must match the project the invoice was created for.
amount_in_cents’field is ignored and the full invoice amount is paid.
Creating a Payment to a Project
Payments created to a project, cannot be associated or applied to invoices after creation. Project payments cannot be updated after creation.
Create a blueprint with the Invoice Payment data set. The Invoice Payment data set is not a dependent data set and does not require an Invoices data set to be on the same blueprint. Input the
amount_in_cents for the desired payment amount. Set the
external_workspace_id to indicate which project this payment will be created for. Make sure to leave the
external_invoice_id fields blank, as adding one will overwrite any amount given and apply the payment to an invoice instead of the project.