Update Account Code Format
Overview

The Update Account Code Format integration point is an inbound integration point used to receive the GL/Project account code format, values and descriptions from an external system like a customer ERP/Finance solution. It is used to populate Unimarket with the following data and is typically run periodically (e.g. nightly). It allows the GL master data held in the ERP/Finance package to be replicated into Unimarket.
- Account codes Part options (e.g. Organisation, Team, Account)
- Account code part type and dependancies
- Account code part data (codes and descriptions).
These are used to code the requisition lines during the checkout process.

Technical Documentation

Message examples relating to the integration can be found below:

Integration > General

Overview

The validate-account-code-request/response message is used by Unimarket to request an external system to validate the Account Code (FOPAL, ledger) information the buyer has entered on their requisition. The Account Code information is passed to the external system so that checks can be made around things such as the user's ability to purchase on that account, the account combination being used and if there is available budget. The external system responds back to Unimarket with a Yes, No, or Warning. This can then be used to stop the buyer from purchasing (if No) and/or display a warning or other related information such as the available budget (any message the external system provides).

This is a synchronous integration point that must respond while the user is waiting in the checkout process so a quick response time is key to avoid timeout.

Request

<user-ref identity="user" domain="UNIMARKET_USERNAME_DOMAIN"/>
<validate-account-code-request>
    <validate-account-code-line line-number="1" quantity="1" sku="productcode">
        <unit-price iso-currency-code="NZD">10.00</unit-price>
        <total iso-currency-code="NZD">10.00</total>
        <account-code distribution-percentage="60.0" format-ref="format" value="a-b">
            <part description="a description" part="a format">a</part>
            <part description="b description" part="b format">b</part>
        </account-code>
        <account-code distribution-percentage="40.0" format-ref="format" value="c-d">
            <part description="c description" part="c format">c</part>
            <part description="d description" part="d format">d</part>
        </account-code>
        <organisation-unit-ref code="orgunit" organisation-code="org" parent-code="org"/>
    </validate-account-code-line>
</validate-account-code-request>

Key Request Data

For each line on the requisition the following key data is passed to the ERP for validation:

Line Number
Quantity
Product Code
Currency
Unit Price
Total (excluding)
Account code (individual parts)
Account Code splits (if applicable)

Response

<?xml version="1.0" encoding="UTF-8"?>
<u1.1:validate-account-code-response xmlns:u1.1="http://www.unimarket.com/schema/unimarket-ws-1.1">
    <u1.1:response code="OK"/>
    <u1.1:account-code-validation line-number="1" result="VALID">
        <u1.1:account-code value="partA1-partA2-partA3-partA4" format-ref="formatcodea"/>
        <u1.1:message>
            partA1-partA2-partA3-partA4 is valid
        </u1.1:message>
    </u1.1:account-code-validation>
    <u1.1:account-code-validation line-number="1" result="VALID">
        <u1.1:account-code value="partB1-partB2-partB3-partB4" format-ref="formatcodea"/>
        <u1.1:message>
            partB1-partB2-partB3-partB4 is valid
        </u1.1:message>
    </u1.1:account-code-validation>
    <u1.1:account-code-validation line-number="2" result="INVALID">
        <u1.1:account-code value="partB1-partB2-partB3-partB4" format-ref="formatcodea"/>
        <u1.1:message>
            partB1-partB2-partB3-partB4 is invalid
        </u1.1:message>
    </u1.1:account-code-validation>
    <u1.1:account-code-validation line-number="3" result="INVALID">
        <u1.1:account-code value="partC1-partC2-partC3-partC4" format-ref="formatcodea"/>
        <u1.1:message>
            partC1-partC2-partC3-partC4 is invalid
        </u1.1:message>
    </u1.1:account-code-validation>
</u1.1:validate-account-code-response>

Key Response Data

For each line on the requisition the following data is will be required in the response from the ERP back to Unimarket:

Line Number
Result: Valid, Invalid, Warning
Account code: The accounting string
Message (Char limit of 255): ‘There are available Funds’ (whatever buyers should see - can include the $$ amount if provided).

Message Results

Note that there can be Valid, Invalid and Warning lines in the same response.

Valid: Line will pass. If all lines have this then the requisition will checkout as per normal without a budget message displaying.
Invalid: If any of the lines are Invalid the requisition will be stopped. This can be coupled with a message.
Warning: If any of the lines are Warning the requisition will be remain on the checkout page and display any provided messages to the user. If the user clicks checkout again they will be able to continue.

Technical Documentation

Technical details relating to the integration can be found below:

Integration > Technical Documentation Examples

Approval Request/Response
Overview

The Approval Request / Response messages provide 2-way integration that is used by Unimarket to request approver information from an ERP/Finance system as the approvals are being completed (in real time). When a requisition is created and routed for approval the integration is triggered so that Unimarket asks the external system for the next approver. This process continues until all the approvals are complete.

This integration can be used instead of the Approval Configuration Request if a customer does not want to load approval data into Unimarket or perhaps they have very complex rules in their ERP that they do not want to replicate.

Technical Documentation

Message examples relating to the integration can be found below:

Integration > General

Approval Integration (Approval-Configuration-Request)

Overview

Unimarket uses hierarchical approval chains containing approvers and their delegated approval limit. Chains are mapped to either account codes or an organization unit (see below). At checkout, when an account or organization is used, the correct chain (or chains) will be selected and the requisition is routed to a user or group in the chain with sufficient delegation.

Approval-configuration-request

Approval integration is used when you want to update Unimarket with approval chains, groups and financial delegations (limits) from an external system like your ERP. The update is typically triggered on a periodic basis such as once every night to ensure Unimarket and the external system are in sync.

The message used is the Approval-Configuration-Request. It contains a series of optional elements depending on what information you want to manage via the integration versus in the system.

It contains:

Global Configuration Options	Used to configure the general approval configuration options such as wait period and reminder period.	Optional element. Leave this element out of the message if you want to manage the configuration in the system.
Approval Levels	Levels are the dollar amounts allocated to approvers - their financial delegation. They have a Name and a $Limit. They must be unique.	Optional element. If this element is in the message the existing Levels in the system will be replaced. Leave this element out of the message if you want to manage Levels in the system.
Approver Groups	A chain contains a hierarchical list of users and/or groups. Groups should be used if you want a group of users at a point in a chain (any of the group can approve). Groups can also be used if you want the group to represent role occupied by a user so that the person occupying the role (group) only needs to change and not the chain itself e.g. 'CFO' Group names must be unique.	Optional element. If this element is in the message the existing Groups in the system will be replaced. Leave this element out of the message if you want to manage Groups in the system.
Approval Chains	Approval chains are the mechanism to route approvals up a hierarchical list of delegated approvers with financial delegations. Approval chains contain a list of approvers and/or approver groups. Their names must be unique. Each 'approver' element may contain a 'user-ref', 'approver-group-ref' or a 'user-detail-basic' element and also an existing (in the request or in Unimarket) approval level. The limit associated with each 'approver' element must always be the same or greater than the limit of the previous 'approver' element. Users may be auto-provisioned by providing 'user-detail-basic' elements.	Optional element. If this element is present in the message, any existing approval chains will be replaced. If this element is omitted from the message, any existing approval chains will be retained.
Organization Unit Mapping	Provides the ability to map chains to organization units so that the correct chain is selected when an organization unit is used.	Optional element. Only used if organization based approval configuration is required. If account code based approval routing is used then this element should be omitted.
Self Approval	Used to define user's self approval limits.	Optional element. If this element is present in the message, any other users' self approval level will be removed. If this element is omitted from the message, any existing self approval levels will be retained.

Technical Documentation

Technical details and example messages can be found here:

Integration > Technical Documentation Examples