Articles in this section

Integration Options for Validate Account Code (Budget Check) Integration

Justin Gillion
  • Updated

Overview

The Unimarket Validate Account Code integration is a 2-way synchronous integration point triggered during the checkout process to tell the user if the account(s) they are using on their requisition are valid and/or have budget. It can be used to check all or some of the following:

  • if a user is eligible to purchase against the account codes specified on their requisition
  • the validity of account code combinations
  • if there is budget in the accounts specified on their requisition

Process

When the user clicks 'checkout' the integration is triggered to check the accounting and budget in the customer's ERP solution. The ERP then responds back with the required information and a 'valid',  'invalid' or 'warning' response. The ERP can also optionally provide a Message if the customer wants specific information displayed to the user.

Integration Details

The Validate Account Code integration point is an XML based integration. Details and examples of the Request/Response message can be downloaded below. Customers can either integrate directly with the XML integration point or use middleware like the Unimarket Connector to manage the integration (see below).

https://help.unimarket.com/hc/en-us/articles/219379047-Webservice-Integration-Technical-Documentation-Examples 

 

Using the Connector to Handle Validate Account Code (Budget Check) Integration

If the Unimarket Connector is used the manage customer integration then the following are examples of how the Connector can be configured to retrieve account code and budget information from the ERP solution.

Note: The specification for each customer is specific based on the options required. Below are examples to illustrate possible approaches.

 

Option: Calling a Stored Procedure (SP)

The Connector is used to called a customer stored procedure which will provide the connector with the required account code / budget information.

 

INPUT to the SP: (minimum required) (example as JSON array)

[ 
 {"line_number": 1, "account": 123-4567-10, "amount": 123.12},
 {"line_number": 2, "account": 123-4567-11, "amount": 200.00},
 {"line_number": 3, "account": 123-4567-12, "amount": 738.50},
 {"line_number": 4, "account": 123-4567-13, "amount": 120.15},
 {"line_number": 5, "account": 123-4567-14, "amount": 23.12}
]

line_number : Integer - line number of items in the checkout
account : String - the account code for the line item
amount : numeric - the value to checkout for the line item

Optional Values

The following optional values can be used:

username: The user trying to purchase against the account code. Used to determine if they have permission to purchase against the account.

organisation unit: The user's organisation unit. Used to determine if they have permission to purchase against the account.

finance year: The Financial Year of the transaction used to validate the correct budget year. Only applicable if the community has FY's setup.

 

OUTPUT after SP call: 

[
 {"line_number": 1, "status": "Valid", "message": ""},
 {"line_number": 2, "status": "Invalid", "message": "Some message"},
 {"line_number": 3, "status": "Invalid", "message": "Some message"},
 {"line_number": 4, "status": "Warning", "message": ""},
 {"line_number": 5, "status": "Valid", "message": ""}
]

line_number : Integer - line number of items in the checkout
statue : String - "valid": all good to go; "invalid": hard stop; "warning": soft stop, allow checkout to proceed, but with some message displayed(low on budget etc)
message : String - optional string to be display if invalid or warning

 

Pros:

  • More "real-time", each checkout will call the budget-check SP
  • Customer has total control of their business logic
  • The actual budget is hidden (as it maybe sensitive information)

Cons:

  • Will need to deal with complex data type and message format
  • More implement effort at customer side

 

Option: Reading a Budget Table

The Connector is used to read a customer 'budget table' which will provide the connector with the required account code / budget information.


Minimum table structure required: 

"ACCOUNT CODE", "BUDGET"
4740-14100-10, 46.33
4740-14100-11, -114.5
4740-14100-12, 500.32


The table would only need two columns: "ACCOUNT CODE" and "BUDGET" as minimum required.

If needs other business logic , more columns can be added, such as financial year, organisation unit etc (see notes on these option values above).

  • "ACCOUNT CODE" - String (e.g. 1234-2345-AD7644)
  • "BUDGET" - numeric
  • The table should only contain valid account codes, any purchasing account not found in the table would be "invalid" and rejected
  • A previously valid account code will need to be removed from table if it becomes invalid
  • The table data would need to be updated regularly (the frequency depends, we have customers doing daily, most commonly hourly)

Pros

  • Solution is simple to implement on the customer side

Cons 

  • The account's budget is exposed
  • Less "real-time"
  • Validation logic is implemented by Unimarket, changes later would involve us for update (cost of time and material). For example any Messages for display to the user will be hardcoded on the connector. 

Related articles