Dartmouth API Developer Portal

General Ledger Transactions API

The GL Billing interface allows the caller to post transaction batches to the Dartmouth GL. This is a restricted service and is strictly limited to external system integrations. Application to use this service must be approved by the General Accounting office. Posted batches are monitored and audited by the General Accounting office on a daily basis. Unauthorized use or attempted use of this service will be considered a major violation of the Dartmouth Code of Conduct/and or possibly a criminal violation and be adjucated accordingly.

Compatibility Note

There are two versions of this API. The first version of this API used an Oracle background job manager to ansynchrounsly create the submitted batch. During the EBS Breakout project it was discovered that this underlying technology did not operate properly in all cases in a distributed environment. Therefore the processing was changed to synchronous execution. This works as long as the batch of transactions is small enough (the processing continues, but the API call will timeout in 30 seconds giving the consumer no link back to the final status of the job). A new version of the API is now available that supports asynchronous processing. The new version is based on our highly available write back worker technology that affords for interaction with the API even when the target system may not be available. It also shares a standard processing methodology among all our other write back APIs.

It is mandatory that new development use the V2 version.

• The new version will handle arbitrarily large inbound payloads.
• The new version works exactly like all other write back APIs that have been developed (uses a consistent single background architecture).
• If the GL moves to cloud hosting, or to an entirely new GL is adopted, only the V2 version is guaranteed to be forward supported.

Below you'll find that the old API allowed for Full and Incremental versions of posting batches. The new version only allows for Full batches. Through time and experience we have learned that the Full batch methodolgy is a more consistent and robust method to post transactions for the following reasons:

• the consumer must generate a full an entirely self consistent payload that can easily be tested in a REST API tool
• logging the full payload allows easier troubleshooting on the consumer side (e.g number of transactions can easily verified and checked)
• limits the number of http calls and therefore the possibility of network or connectivity errors that may interrupt the flow of calls

Rating V1

Rating V2

Notes on usage

There are two basic method options to call the GL Billing API.

1. The entire batch of transactions and associated header information is passed to the api in a single POST CALL. A return code of 202 (Accepted) is given, and a payload of information about the batch, including the ID of the batch that can be used in a subsequent GET call to inquire about the status of the batch. The number of transaction lines is not limited. NOTE: The V2 version of the API only works in this mode
2. The batch of transactions can be constructed with a sequence of calls inserting one batch transaction at a time.

Both methods result in a batch of transactions being created that are submitted to a background process that validates the batch through a backend GL service passing a series of checks such as valid chart strings and batch integrity. Only if the batch passes all integrity checks is it accepted for posting to the GL.

The optional descriptive flex fields dff_n can be used to annotate the transaction with additional metadata, such as details about the source.

NOTE: Amounts less than a dollar must start with a leading zero before the decimal point in order to conform with the relevant JSON standard

NOTE: Optional descriptive field dff_2 is usually reserved for internal Oracle transactions. Do not use this code unless instructed to by central accounting.

Checking Completion Status V1

The caller can check on the status of the background processing by calling the check status service, and passing in the ID of the batch resource that is returned on the initiating call to create the batch (the POST requests documented below).

COMPATIBILITY NOTE the "link" attribute returned on the post call must be followed to the status information. The format of the link may change in the future so this attribute should always be used rather than "assuming" the format of the URL.

Checking Completion Status V2

Similar to version V1 the caller uses the location header to return a link to the task container that is executing your request in the background. Below is a screenshot of an example of the Location header in a Postman request.

In either method a posting_type field is required that can have the values COMMIT or TRIAL. In TRIAL mode the batch is submitted for processing and goes through all the integrity checks. If the batch passes all these integrity checks, the batch is rolled back as if it never happened and a error flag in the status check payload is set indicating no errors. If the posting_type is COMMIT and the batch passes all integrity checks, the batch is sent to the GL for the next posting cycle. In this way, you can pre-flight check the batch for errors before sending it to the GL.

Transaction lines are used to create the transactions (see below for example and description). In mode 1 these transactions are passed to the posting process as an array in attributes "transactions". In mode 2, each line can be individually added. The payload attributes in either mode for a line transaction are the same.

The postings (history) service returns previously-submitted batch postings.

Method 1 Full Batch Request

Request

POST /api/general_ledger/postings/batches

Required Scope

urn:dartmouth:general_ledger:write.transaction

Parameters

None

Body

Batch request payload (see example below)

Returns

Sample Request V1

https://api.dartmouth.edu/api/general_ledger/postings/batches

Sample Request V2

https://api.dartmouth.edu/api/v2/general_ledger/postings/batches

NOTE: the inbound body on the POST call for versions V1 and V2 are the same

POST request with example body

{
    "billing_type":"GL",
    "posting_type":"TRIAL",
    "source_name":"SYSTEM_XYZ",
    "category_name":"BILLING_BATCH",
    "batch_name":"Monthly Billing for System XYZ",
    "accounting_date":"2018-02-01T04:00:00Z",
    "record_count":2,
    "total_dr_amount":1772.14,
    "total_cr_amount":1772.14,
    "transactions":[
        {
            "source_transaction_id":"818261",
            "source_transaction_date":"2017-06-30T04:00:00Z",
            "gl_account":"13.001.906350.810000.0000.5043",
            "amount":1772.14,
            "debit_credit_flag":"C",
            "line_desc":"Travel Expenses",
            "dff_1":"00323"
        },
        {
            "source_transaction_id":"818261",
            "source_transaction_date":"2017-06-30T04:00:00Z",
            "gl_account":"13.001.906350.810000.0000.5043",
            "amount":1772.14,
            "debit_credit_flag":"D",
            "line_desc":"Travel Expenses",
            "dff_1":"00323"
        }
    ]
}

Main Body attributes:

Line Attributes

Returns V1

{
    "id": "6806B629F89F22E0E0538801120A903F",
    "source_tracking_id": null,
    "source_name": null,
    "batch_name": null,
    "posting_type": null,
    "status": "Uploading",
    "message": null,
    "number_of_lines": null,
    "link": "https://api.dartmouth.edu/api/general_ledger/postings/6806B629F89F22E0E0538801120A903F",
    "is_completed": false,
    "is_error_free": false,
    "submit_time": "2018-03-22T19:57:03Z",
    "completion_time": null,
    "elapsed_minutes": 0,
    "line_errors": []
}

Returns V2

Sample Return

Location header:

/api/tasks/5deeb1c608a94008f54748b2

Body:

{
    "status": "accepted"
}

Notes on usage

After the POST, the calling app should poll the tasks API until the task is completed (indicated by status of either "complete" or "error").

Sample polling request:

https://api.dartmouth.edu/api/tasks/5deeb1c608a94008f54748b2

Sample return:

{
    "status": "complete",
    "path": null,
    "message": {
        "id": "9D729DC6DB170725E0538702120AB9BB",
        "source_tracking_id": 432293,
        "source_name": "EFS_DC",
        "batch_name": "POOL A71000 ASSOCIATED ENDOWMENT POOL #1 DISTRIBUTION FOR 6/30/2017",
        "posting_type": "TRIAL",
        "status": "Trial Success",
        "message": "Batch rolled back",
        "number_of_lines": 5,
        "is_completed": true,
        "is_error_free": true,
        "submit_time": "2020-01-31T16:45:57Z",
        "completion_time": "2020-01-31T16:45:57Z",
        "elapsed_minutes": "0",
        "line_errors": []
    },
    "id": "5e3459c5161b3d0931d02b16"
}

The message attribute will contain the details documented in the following section.

Get Batch Status V1

This call can be used at any time to get the current status of the batch. This call is available in either Full post mode or Incremental post mode.

Request

GET /api/general_ledger/postings/batches/{id}

Required Scope

urn:dartmouth:general_ledger:write.transaction

Parameters

Returns

Sample Request

GET https://api.dartmouth.edu/api/general_ledger/postings/batches/67EC1A30744A6B00E0538801120A0C4D

Sample Return with Line Errors

{
    "id": "6750FC837D2E118AE0538D01120A54D9",
    "source_tracking_id": 286938,
    "source_name": "SYSTEM_XYZ",
    "batch_name": "Monthly Billing for System XYZ",
    "posting_type": "TRIAL",
    "status": "Error",
    "message": "Batch of group ID  286938 aborted with error: ORA-20000: 4 Line errors occurred, batch cannot be created..",
    "number_of_lines": 8418,
    "link": "https://api-dev.dartmouth.edu/api/general_ledger/postings/6750FC837D2E118AE0538D01120A54D9",
    "is_completed": true,
    "is_error_free": false,
    "submit_time": "2018-03-13T19:08:40Z",
    "completion_time": "2018-03-13T19:11:35Z",
    "elapsed_minutes": 2.92,
    "line_errors": [
        {
            "line_number": 1877,
            "source_transaction_id": "818916",
            "chart_string": "20.377.761689.753002.0000.4302",
            "error_message": {
                "error_message": "ORA-20000: Value 377 has been disabled."
            }
        },
        {
            "line_number": 1877,
            "source_transaction_id": "818916",
            "chart_string": "20.377.761689.753002.0000.4302",
            "error_message": {
                "error_message": "ORA-20000: At line 1877, Source Transaction ID = 818916 Error = ORA-20000: Value 377 has been disabled."
            }
        },
        {
            "line_number": 2382,
            "source_transaction_id": "818977",
            "chart_string": "20.377.761669.754554.0000.4302",
            "error_message": {
                "error_message": "ORA-20000: Value 377 has been disabled."
            }
        },
        {
            "line_number": 2382,
            "source_transaction_id": "818977",
            "chart_string": "20.377.761669.754554.0000.4302",
            "error_message": {
                "error_message": "ORA-20000: At line 2382, Source Transaction ID = 818977 Error = ORA-20000: Value 377 has been disabled."
            }
        }
    ]
}

Method 2 Incremental Batch Request (V1 only)

Usage Notes:

Creating a posting batch incrementally involves three distinct steps. Each step is a POST request to the API service. Note that only after the batch is created will any integrity checking occur. The only check that happens during the calls is whether syntactically correct JSON is being handed to the API.

1. Begin the batch. This call establishes the batch, and returns the ID you will use on subsequent calls.
2. Add Lines. Each add line call adds a new line to the batch.
3. End the batch. This call ends the batch and hands off processing to the background processor.

Request

POST /api/general_ledger/postings/batches

Required Scope

urn:dartmouth:general_ledger:write.transaction

Parameters

None

Body

Batch request payload (see example below)

Returns

Sample Request

https://api.dartmouth.edu/api/general_ledger/postings/batches

POST request with example begin batch body

{
    "billing_type":"GL",
    "posting_type":"TRIAL",
    "source_name":"EFS_DC",
    "category_name":"SATELLITE_DEFAULT_DC",
    "batch_name":"POOL A71000 ASSOCIATED ENDOWMENT POOL #1 DISTRIBUTION FOR 6/30/2017",
    "accounting_date":"2018-02-01T04:00:00Z"
}

POST request with add line body:

{
    "source_transaction_id":"818261",
    "source_transaction_date":"2017-06-30T04:00:00Z",
    "gl_account":"13.001.906350.810000.0000.5043",
    "amount":1772.14,
    "debit_credit_flag":"C",
    "line_desc":"FRISBIE DOROTHY NUTRITION",
    "dff_1":"00323"
}

POST request with end batch body:

{
    "record_count":2,
    "total_dr_amount":1964.91,
    "total_cr_amount":1964.91

}

Get Postings History

This call can be used at any time to get status of previously-submitted batch postings. It returns both Full and Incremental mode postings.

Request

GET /api/general_ledger/postings/

Required Scope

(none)

Parameters

Returns

Sample Request

GET https://api.dartmouth.edu/api/general_ledger/postings?source_name=EFS_DC&submit_date=2018-07-04

Sample Return

[
    {
        "submit_time": "2018-07-04T23:55:48",
        "batch_id": "703985C52696B553E0538002120A1A2C",
        "current_status": "Error",
        "posting_type": "TRIAL",
        "message": "Batch of group ID   aborted with error: ORA-20000: Invalid period specified (or) period status is neither (open/future) for : 01-FEB-18.",
        "batch_name": "POOL A71000 ASSOCIATED ENDOWMENT POOL #1 DISTRIBUTION FOR 6/30/2017",
        "source_name": "EFS_DC"
    },
    {
        "submit_time": "2018-07-04T23:50:48",
        "batch_id": "703973E0B2DEAD05E0538002120AD0B4",
        "current_status": "Error",
        "posting_type": "TRIAL",
        "message": "Batch of group ID   aborted with error: ORA-20000: Invalid period specified (or) period status is neither (open/future) for : 01-FEB-18.",
        "batch_name": "POOL A71000 ASSOCIATED ENDOWMENT POOL #1 DISTRIBUTION FOR 6/30/2017",
        "source_name": "EFS_DC"
    }
]