> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.2cloudnine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Warning>
  **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”.*
</Warning>

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:

1. **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.

<Warning>
  **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.*
</Warning>

1. **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.

<Note>
  **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.*
</Note>

## 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.

<Warning>
  **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.*
</Warning>

## 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** :

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

```apex Script theme={null}
//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:

```apex Script theme={null}
//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**

1. Select **Activate** .

<Note>
  **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.*
</Note>

**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**

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

<Note>
  **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.*
</Note>

## 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**

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

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

3. Copy the value in the ID field.
4. Go to **Setup > Custom Settings > 2c9 - PO Management Settings > Manage**
5. Select the **New** button in the top half of the page.
6. Enter the copied Apex Class ID into the **Apexclass Id** field.
7. 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**

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

<Warning>
  **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.*
</Warning>

## 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**

1. Select the **New** button.
2. 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
3. Select **Save** .
4. Select the **New** button again.
5. 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                  |

<Note>
  **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.*
</Note>

## 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                      |