PO Management (Utilities) - Administrator Guide

Purpose

The purpose of this Administrator Guide is to provide information about Utilities packaged Purchase Orders. The intended audience for this document is System Administrators/Payroll Users. If your Org does not have access to the Purchase Order object, you will need to contact 2cloudnine to discuss the suitability of installing the 2cloudnine Utilities Extension Package.

Overview

The new custom object Purchase Order serves as the primary record to capture important details related to a Client’s Purchase Order. After creating the Purchase Order records, they are linked to an Assignment using a Purchase Order Junction record. To learn more, please refer to the QRG Creating Purchase Orders and QRG Creating Purchase Order Junctions.

Assignment Setup

The following relates to the configuration of Timesheet Assignments and related Assignment Rates when utilising PO Management. This is based on using the ‘Process PO Allocation’ logic, which is designed with the assumption of Assignments defining if a Purchase Order is required, and that Pay Transactions cannot be invoiced until they have a Purchase Order. Exceptions to this include the Invoice without PO Depletion Rule (refer to QRG Create a Purchase Order - Utilities) and Assignment Rates > Pay Codes that can be invoiced without a Purchase Order. IMPORTANT: If using an alternative Process PO Allocation logic, this step may not be required based on your defined process logic. Assignment Requires Purchase Order To enable Purchase Order Management for an Assignment, you must select the checkbox Requires Purchase Order. Populating the ‘To Be Invoiced?’ field on Assignment Rates To ensure Pay Transactions that require Purchase Orders are not invoiced before being assigned a Purchase Order, the Pay Transactions must ensure the field ‘To Be Invoiced?’ is ‘No’ upon creation. The ‘To Be Invoiced?’ field on the Pay Transaction is defaulted from the ‘To Be Invoiced’ field on the related Assignment Rate. For this, it is required that any Assignments and related Assignment Rate > Pay Codes that require a Purchase Order, you must ensure the ‘To Be Invoiced’ field on the related Assignment Rates is not updated to Yes.

Important Notes(To Be Invoiced field)It is essential to recognise that the To Be Invoiced field is labelled differently in various records. On Pay Transaction records, it is labelled as “To Be Invoiced?”, whereas on the Assignment Rates records, it is simply labelled “To be Invoiced”.

Failure to populate the To Be Invoiced field on the Assignment correctly will result in Pay Transactions being generated with To Be Invoiced? Field as TRUE, causing the default Process PO Allocation to be FALSE, and the Pay Transactions will not be processed by the PO Management process. To ensure Pay Transactions that require Purchase Orders are correctly processed, we recommend one of the following approaches:

Flow (Recommended) Utilising two record-triggered Flows is a simplistic and recommended solution for this requirement: The first Flow should run on the creation or update of Assignment Rates using the following criteria:

Assignment Rate > Assignment > ‘Requires Purchase Order’ = TRUE.
Assignment Rate > Pay Code > PO Allocation Type != NULL The second Flow runs on the update of an Assignment where Requires Purchase Order is set to TRUE. This Flow will then find all Active or Pending Assignment Rates where the Assignment Rate > Pay Code > PO Allocation Type != NULL, and update the Assignment Rate field ‘To Be Invoiced’ to ‘No’. IMPORTANT: This approach has been previously delivered for Customers and can be deployed into another Org upon request to 2cloudnine.

Important Notes(Updating Purchase Order Required)If updating Assignment Rates related to existing Pay Transactions (e.g. An Active Assignment is updated to now requiring a Purchase Order), you will be unable to change ‘To Be Invoiced?’ to ‘No’, due to Product validations preventing this. In this scenario, new Assignment Rates need creation or the use of Validation Overrides to enable this.

Defaulting ‘To Be Invoiced?’ as ‘No’. This solution applies a standardised approach by defaulting the field ‘To Be Invoiced’ to ‘No’ for all Timesheet Assignment Rates. This means all Pay Transactions cannot be invoiced until this field is updated. Where there are Pay Transactions that do not require a Purchase Order, a Purchase Order related to the Assignment Rate is still configured, but with a Depletion Rule of Invoice without PO, and the PO Allocation Type set to those Pay Transactions that do not require a Purchase Order. Whilst this approach is simpler in terms of configuration, it creates an administrative overhead, as every Assignment that does not require a Purchase Order still goes through the PO Management process before being invoiced.

Process PO Allocation on Pay Transactions

To utilise the PO Management functionality, Pay Transactions must be flagged for PO processing. There are two ways to determine which Pay Transactions should be processed: Default Process PO Allocation The PO Management functionality includes a default formula field on the Pay Transaction named Process PO Allocation. This formula field returns TRUE when the following criteria are met:

Assignment > Requires Purchase Order = TRUE
Invoice Rate != 0
Invoice Item = NULL
Purchase Order = NULL
To Be Invoiced? = FALSE

These conditions ensure that only Pay Transactions not yet invoiced or updated with a Purchase Order are processed by PO Management. Custom Process PO Allocation Alternatively, use a Custom Formula Field to determine which Pay Transactions are processed by PO Management. For example, a Customer may request only processing Pay Transactions that have been payrolled. In this case, the existing formula logic could be copied with an additional AND statement added to include this criteria. Refer to Update Pay Codes for detailed instructions to enable this functionality. When creating a separate Custom Process PO Allocation field, it is highly recommended to include the following criteria in an AND statement:

Assignment > Requires Purchase Order = TRUE
Invoice Item = NULL
Purchase Order = NULL

Failure to include this logic can result in undesired outcomes, such as:

Non-payment Pay Transactions (e.g. Superannuation transactions) being processed.
Purchase Orders being overridden on Pay Transactions already invoiced.

IMPORTANT: If utilising a Custom Process PO Allocation formula, the Screen Flow ‘2c9 Utilities - Process PO Allocation’ will need to be updated to reference the Custom Field instead of the default ‘Process PO Allocation’ field. Please consult 2cloudnine if you require assistance to make this update.

Important Notes(Alternate Custom Method)Purchase Order Management can be processed using an alternate custom method by invoking the global Apex Class ‘apex-SkiePurchaseOrderManagementInvocable’.This field should return FALSE at the conclusion of the PO Allocation. The Custom Formula Field must contain ‘PURCHASE ORDER = NULL’ to ensure that once the Purchase Order has been applied, it is not processed again.

Update Pay Codes

In order for Pay Transactions to be correctly processed, all Payment, Allowance, and Expense Pay Codes must have the field PO Allocation Type populated. The Global Value Set PO Allocation Types contains by default, the options for Payment, Allowance & Expense, but can be updated to include any Customer requirements, allowing for granular allocation of Pay Transactions to Purchase Orders.

Important Notes(PO Allocation Type on Pay Codes)Any Pay Transactions related to Pay Codes that do not have a PO Allocation Type defined, will not be processed. An error message will be displayed on the Pay Transaction > PO Allocation Notes fields, detailing no allocation type was found.

Pay Transaction Trigger

To aggregate the value of processed Pay Transactions against their related Purchase Orders, a Trigger named Trg_PayTxn_Staffing has been implemented on the Pay Transaction. This Trigger runs on the following events: after insert, after update, before delete, and after undelete. Its purpose is to ensure that the Invoice Total Ex. Tax value from a Pay Transaction is accurately reflected in the Current Spend field of the associated Purchase Order. When a Pay Transaction is linked to a Purchase Order, it adds the value of Invoice Total Ex. Tax to the Purchase Order’s Current Spend. If the Purchase Order is removed from the Pay Transaction, or the Pay Transaction is deleted, the trigger subtracts the corresponding value from the Current Spend. In the case of an undeleted Pay Transaction, the value is added back to the related Purchase Order. This ensures that the Current Spend on each Purchase Order remains accurately updated based on the total of all associated Pay Transactions.

Include PO in Invoice Grouping

Purchase Order Management allows you to automatically append the Purchase Order ID to the Invoice Group By ID of processed Pay Transactions, ensuring Invoices are uniquely grouped by Purchase Order. Without this setting, even though Purchase Order Numbers are applied to Pay Transactions, the resulting Invoices may include multiple Purchase Orders in a single document. For clients who require one Purchase Order per Invoice, this feature eliminates the need for custom logic. This can be configured per Customer via the Invoice Setting record using the Include PO in Invoice Grouping field:

If set to Yes, the Purchase Order ID will be appended to the Invoice Group By ID of each processed Pay Transaction.
If set to No or left blank, the Purchase Order will still be applied to the Pay Transaction, but it will not affect Invoice Grouping.

There is an additional field ‘Include PO in Invoice Grouping’ within the Utilities Package, which can be used for the invoice grouping to include these custom Purchase Orders.

Project Code Allocation

The PO Management functionality also supports the allocation of Purchase Orders to Project Codes. This optional functionality can be used for project-based Purchase Order allocation. Only Assignment Level Project Codes can be related to a Purchase Order, allowing for a single Project Code to be assigned to a single Purchase Order. When an Assignment Level Project Code is updated with a Purchase Order, during the PO Allocation process, the Flow checks if the Pay Transaction > Project Code > Purchase Order matches the found Junction > Purchase Order. If found, the Purchase Order will be allocated to the Pay Transaction. If it does NOT match the found Junction > Purchase Order, the Purchase Order will not be allocated to the Pay Transaction and will continue with the PO Allocation Process.

PO Management and Timesheet Adjustments

When using both the PO Management and Timesheet Adjustment functionality together, it is critical to understand the impact Timesheet Adjustments have on Pay Transactions assigned to Purchase Orders. When a Timesheet Adjustment is processed, the original Pay Transactions will remain linked to the Purchase Order. However, the newly created reversal (negative) Pay Transactions will not. This is intentional, as the negative Pay Transactions need to be picked up by the PO Management process to correctly reapply the negative amount back to the Purchase Order. IMPORTANT : By default, reversal Pay Transactions created by the Timesheet Adjustment process have the ‘To Be Invoiced?’ field set to TRUE. If left unchanged, when running the standard Process PO Allocation, these reversal Pay Transactions will not be assigned to a Purchase Order — meaning the negative value will not be reapplied. To address this, we recommend using a fast action Record-Triggered Flow on the Pay Transaction. This Flow should automatically set ‘To Be Invoiced?’ to FALSE on the reversal Pay Transactions if the related Original Pay Transaction is linked to a Purchase Order. This ensures the negative value is correctly returned to the Purchase Order when both PO Management and Timesheet Adjustment functionalities are in use.

Process PO Allocation Setup

To accommodate the many variables between clients and their timings, as well as impacts on downstream invoicing, there are two options for triggering the PO Allocation Process. Both options can be used together, offering maximum flexibility in determining when Purchase Orders should be processed. Scheduled Batch Job The first option is to schedule a Batch Job that allocates Pay Transactions to Purchase Orders at defined intervals. The key consideration is timing — if invoicing occurs shortly after Pay Transactions are generated, ensure the Batch Job runs frequently enough to avoid delays (i.e. hourly). In typical Orgs, scheduling hourly or even daily is sufficient, as invoicing generally occurs after Payroll is complete. To run the script hourly :

Copy the block of script to be run.
Select Setup > Developer Console .
Debug > Open Execute Anonymous Window .
Delete or comment out any code that is in the window.
Paste in the copied script from below.
Click the Execute button.

Script

//script for hourly purchase order management

System.schedule('PurchaseOrderManagement 00', '0 00 * * * ?', new
tc9_util.PurchaseOrderManagementInvocable());

The Apex Jobs will now be scheduled. Please confirm they are set up correctly by going to Setup Scheduled Jobs Run the Batch Job Instantly Alternatively, the Batch Job can also be run instantly by using the following script, using the previous Steps 1-6 above in Dev Console:

Script

//script for instant purchase order management

new tc9_util.PurchaseOrderManagementInvocable().execute(null);

Screen Flow The 2cloudnine Utilities Package also includes a Flow Template called ‘2c9 Utilities – Process PO Allocation’ (see page 1), which can be used to manually run the PO Allocation Process. This Screen Flow can be used alongside the Scheduled Batch Job. For example, you might schedule the Batch Job to run hourly while also providing the Flow to allow Middle Office Users to process PO Allocation instantly when needed. Prior to using this Flow, you must first activate it: Go to Setup - Flows - 2c9 Utilities - Process PO Allocation

Select Activate .

Important Notes(Process PO Allocation)This Flow is considered optional and is used to support the PO Management process. Without this Flow, the PO Management can still be used but will require other methods to run the PO Management Apex Class.

Add ‘PO Management - Process PO Allocation’ to Utility Bar The PO Management process is run using the Screen Flow 2c9 Utilities - Process PO Allocation. Whilst it is possible to run Screen Flows from multiple pages within Salesforce, we recommend making it available in the Users Utility Bar. To add the 2c9 Utilities - Process PO Allocation Flow to the Utility Bar: Go to Setup - App Manager

Select your desired app and select Edit using the drop-down.
Select Utility Items .
Select Add Utility Item .
Search for and select Flow .
Complete all fields and ensure in the Flow lookup you select 2c9 Utilities - Process PO Allocation .
Select Save .

Important Notes(Flow within Utility Bar)If using a Managed Package App, it is not possible to add a Utility Bar. You must either create a new App or utilise an App Record Page to host the ‘2c9 Utilities - Process PO Allocation’ Flow.

Update Custom Settings (Optional)

The PO Management functionality uses a Custom Setting 2c9 - PO Management Settings to define certain variable data. There are two optional settings available to be updated. ApexClass Id This setting must be populated if you are using the Process PO Allocation. Failure to provide the Apex Class Id will result in the Flow failing to successfully complete. To populate the Custom Setting: Go to Setup - Developer Console

Select the Query Editor tab near the bottom.
Paste the following text and then select the Execute button:

SELECT Id, Name FROM ApexClass WHERE Name = 'PurchaseOrderManagementInvocable'

Copy the value in the ID field.
Go to Setup > Custom Settings > 2c9 - PO Management Settings > Manage
Select the New button in the top half of the page.
Enter the copied Apex Class ID into the Apexclass Id field.
Select Save.

Custom Process PO Allocation Enter the API name of a Custom Boolean Field on the Pay Transaction Object to override the standard Process PO Allocation field. If specified, this field’s value will be used to determine which Pay Transactions to process instead of the Standard Field. Go to Setup - Custom Settings - 2c9 Utilities - Process PO Allocation - Manage

Select Edit or the New button from the top half of the page (if not done in other configuration).
Enter the API name of the Custom Boolean Field into the Custom Process PO Allocation field.
Select Save .

Important Notes(Custom Field on Process PO Allocation)_You must ensure you append “_c” to the API Name of the Custom Field. Failure to do this will result in an Apex error during the PO Allocation process.

Update Custom Metadata Types (Conditionally Compulsory)

If Customers will be utilising the function to automatically include the Purchase Order Id into the Invoice Group By ID (see Include PO in Invoice Grouping), this step is required. The purpose of this is to allow the Purchase Order Number and Invoice Group By ID fields to be overwritten from the PO Management process. Failure to configure this step will result in the Product triggers overwriting these Fields. To update the Custom Metadata Types: Go to Setup - Custom Metadata Types - T2P Pay Transaction Override Setting - Manage Records

Select the New button.
Enter the following details:
1. Label = Purchase Order Number
2. T2P Pay Transaction Override Setting Name = Purchase_Order_Number
3. Pay Transaction Field API Name = tc9_et__Purchase_Order_Number__c
4. Override on Insert = Yes
5. Override on Update = Yes
Select Save .
Select the New button again.
Enter the following details:
1. Label = Invoice Group By ID
2. T2P Pay Transaction Override Setting Name = Invoice_Group_By_ID
3. Pay Transaction Field API Name = tc9_et__Invoice_Group_By_ID__c
4. Override on Insert = Yes
5. Override on Update = Yes
6. Select Save .

Mapping

During the allocation of a Purchase Order to a Pay Transaction, the PO Management process will utilise the following mapping:

Pay Transaction Field	Purchase Order Junction Field	Purchase Order Field
Entry Date	Greater than or equal to the Effective Date AND Less than or equal to the Expiry Date OR Expiry Date is NULL.	N/A
Pay Code > PO Allocation Type	Allocation Type	N/A
Invoice Total Ex Tax*	Depletion Rule	Remaining Spend
Status	N/A	Active
N/A	Sort Order (used when 2 Purchase Order Junctions exist with matching criteria, then the lower is used first)	N/A

Important Notes(Current Spend field)This uses a combination of the Depletion Rule and Remaining Spend when determining which Purchase Order to allocate. If the Invoice Total Ex Tax was $1000, then the Pay Transaction could be allocated to a PO Junction with a Depletion Rule of ‘Overspend’ and a Remaining Spend below $1,000. If the Purchase Order Junction has a Depletion Rule of ‘Hold Off’, then it would NOT allocate to that Purchase Order and instead look for the next available one.

Further Information

Document	Document Type	Description
Configuration Guide to 2cloudnine Payroll Suite	Configuration Guide	Configuration Guide for the implementation of 2cloudnine Payroll.
Configuration Guide To 2cloudnine Utilities	Configuration Guide	Configuration Guide for the implementation of 2cloudnine Utilities.
QRG Create Purchase Orders	Task Instructions	How to create a Purchase Order
QRG Allocate Purchase Orders	Task Instructions	How to allocate Purchase Orders
QRG Create Purchase Order Junctions	Task Instructions	How to create Purchase Order Junctions
QRG Create an Assignment - Temp	Task Instructions	How to create an Assignment - Temp Record Type

​Purpose

​Overview

​Assignment Setup

​Process PO Allocation on Pay Transactions

​Update Pay Codes

​Pay Transaction Trigger

​Include PO in Invoice Grouping

​Project Code Allocation

​PO Management and Timesheet Adjustments

​Process PO Allocation Setup

​Update Custom Settings (Optional)

​Update Custom Metadata Types (Conditionally Compulsory)

​Mapping

​Further Information

Purpose

Overview

Assignment Setup

Process PO Allocation on Pay Transactions

Update Pay Codes

Pay Transaction Trigger

Include PO in Invoice Grouping

Project Code Allocation

PO Management and Timesheet Adjustments

Process PO Allocation Setup

Update Custom Settings (Optional)

Update Custom Metadata Types (Conditionally Compulsory)

Mapping

Further Information