Investigation: Connection between POL, invoice lines and eholdings package/resource

Owned by Pavlo Smahin
Last updated: Dec 09, 2020
1 min read

MODKBEKBJ-530 - Getting issue details... STATUS

Goal:

Determine the connection between POL, invoice lines and package/resource via agreements

Connection via agreements app

  1. Get info about agreement lines that related to package or resource.
  2. For each agreement line get detail info about agreement.
  3. Extract order line (POL) ids from agreement.
  4. Get details about POLs and invoice lines.

Endpoints and responses details: 

Call endpointGET /erm/sas?filters=items.reference=<packageId/resourceId>
 Response

[
    {
        "id": "50e59412-46b2-49d8-ba23-e9a3d03efd7e",
        "name": "GO test 1",
        "orgs": [],
        "externalLicenseDocs": [],
        "outwardRelationships": [],
        "customProperties": {},
        "contacts": [],
        "tags": [
            {
                "id": 2,
                "normValue": "indexierung:in01",
                "value": "indexierung:in01"
            }
        ],
        "inwardRelationships": [],
        "linkedLicenses": [],
        "docs": [],
        "periods": [
            {
                "id": "1d0d54f6-d477-47df-817e-80976f4b9539",
                "startDate": "2020-12-01",
                "owner": {
                    "id": "50e59412-46b2-49d8-ba23-e9a3d03efd7e"
                }
            }
        ],
        "usageDataProviders": [],
        "agreementStatus": {
            "id": "2c91809a764001e9017640045dae003e",
            "value": "active",
            "label": "Active"
        },
        "supplementaryDocs": [],
        "currentPeriod": {
            "id": "1d0d54f6-d477-47df-817e-80976f4b9539",
            "startDate": "2020-12-01",
            "owner": {
                "id": "50e59412-46b2-49d8-ba23-e9a3d03efd7e"
            }
        },
        "startDate": "2020-12-01",
        "endDate": null,
        "cancellationDeadline": null,
        "items": [
            {
                "id": "9f88a6ed-8d38-4394-9db1-194661f1c89b"
            },
            {
                "id": "9ee79181-95db-45fa-8613-984e86a550a0"
            },
            {
                "id": "04b8220b-98dd-418d-adb4-ca2742e6ba2d"
            }
        ],
        "alternateNames": []
    }
]

Extract ids from response 

↓

Call endpointGET /erm/entitlements?filters=owner=<agreementId>
 Response

[
    {
        "id": "04b8220b-98dd-418d-adb4-ca2742e6ba2d",
        "type": "external",
        "description": null,
        "authority": "EKB-PACKAGE",
        "reference": "123355-3229805",
        "explanation": null,
        "startDate": null,
        "endDate": null,
        "activeFrom": null,
        "activeTo": null,
        "contentUpdated": null,
        "haveAccess": true,
        "suppressFromDiscovery": false,
        "note": null,
        "tags": [],
        "owner": {
            "id": "50e59412-46b2-49d8-ba23-e9a3d03efd7e",
            "name": "GO test 1",
            "orgs": [],
            "externalLicenseDocs": [],
            "outwardRelationships": [],
            "customProperties": {},
            "contacts": [],
            "tags": [
                {
                    "id": 2,
                    "normValue": "indexierung:in01",
                    "value": "indexierung:in01"
                }
            ],
            "inwardRelationships": [],
            "linkedLicenses": [],
            "docs": [],
            "periods": [
                {
                    "id": "1d0d54f6-d477-47df-817e-80976f4b9539",
                    "startDate": "2020-12-01",
                    "owner": {
                        "id": "50e59412-46b2-49d8-ba23-e9a3d03efd7e"
                    }
                }
            ],
            "usageDataProviders": [],
            "agreementStatus": {
                "id": "2c91809a764001e9017640045dae003e",
                "value": "active",
                "label": "Active"
            },
            "supplementaryDocs": [],
            "currentPeriod": {
                "id": "1d0d54f6-d477-47df-817e-80976f4b9539",
                "startDate": "2020-12-01",
                "owner": {
                    "id": "50e59412-46b2-49d8-ba23-e9a3d03efd7e"
                }
            },
            "startDate": "2020-12-01",
            "endDate": null,
            "cancellationDeadline": null,
            "items": [
                {
                    "id": "9ee79181-95db-45fa-8613-984e86a550a0"
                },
                {
                    "id": "04b8220b-98dd-418d-adb4-ca2742e6ba2d"
                },
                {
                    "id": "9f88a6ed-8d38-4394-9db1-194661f1c89b"
                }
            ],
            "alternateNames": []
        },
        "poLines": [
            {
                "id": "490015d7-4839-4f1e-ae07-bc654a9010a0",
                "poLineId": "647c1dca-b9bf-47af-8456-bfb6dfef9eee",
                "owner": {
                    "id": "04b8220b-98dd-418d-adb4-ca2742e6ba2d"
                }
            }
        ],
        "customCoverage": true,
        "coverage": [
            {
                "startDate": "2019-02-22",
                "endDate": "2025-02-19",
                "summary": "v*/i*/2019-02-22 - v*/i*/2025-02-19"
            }
        ],
        "reference_object": {
            "label": "ddd",
            "type": "Package",
            "provider": "API DEV CORPORATE CUSTOMER",
            "titleCount": 0,
            "selectedCount": 0,
            "contentType": "E-Book",
            "providerName": "API DEV CORPORATE CUSTOMER",
            "isSelected": true
        }
    }
]

Extract poLineIds from response 

↓

↓

Call endpointsGET /orders/order-lines?query=id==<poLineId1> or or id==<poLineIdN>
 Response
{
    "poLines": [
        {
            "id": "647c1dca-b9bf-47af-8456-bfb6dfef9eee",
            "edition": "First edition",
            "checkinItems": false,
            "agreementId": "0a79add6-f1a3-44f8-b75d-092c0b729286",
            "acquisitionMethod": "Purchase",
            "alerts": [],
            "cancellationRestriction": false,
            "cancellationRestrictionNote": "",
            "claims": [
                {
                    "claimed": false,
                    "grace": 0
                }
            ],
            "collection": false,
            "contributors": [
                {
                    "contributor": "Antoniou, Grigoris",
                    "contributorNameTypeId": "2b94c631-fca9-4892-a730-03ee529ffe2a"
                },
                {
                    "contributor": "Van Harmelen, Frank",
                    "contributorNameTypeId": "2b94c631-fca9-4892-a730-03ee529ffe2a"
                }
            ],
            "cost": {
                "listUnitPrice": 200.0,
                "listUnitPriceElectronic": 0.0,
                "currency": "USD",
                "additionalCost": 0.0,
                "discount": 21.0,
                "discountType": "percentage",
                "quantityPhysical": 2,
                "quantityElectronic": 0,
                "poLineEstimatedPrice": 316.0
            },
            "description": "",
            "details": {
                "receivingNote": "2 copies",
                "productIds": [
                    {
                        "productId": "0262012103",
                        "productIdType": "8261054f-be78-422d-bd51-4ed9f33c3422"
                    },
                    {
                        "productId": "9780262012102",
                        "productIdType": "8261054f-be78-422d-bd51-4ed9f33c3422",
                        "qualifier": "(hardcover)"
                    }
                ],
                "subscriptionInterval": 0
            },
            "donor": "",
            "fundDistribution": [
                {
                    "code": "USHIST",
                    "encumbrance": "eb506834-6c70-4239-8d1a-6414a5b08013",
                    "fundId": "65032151-39a5-4cef-8810-5350eb316300",
                    "distributionType": "percentage",
                    "value": 100.0
                }
            ],
            "isPackage": false,
            "locations": [
                {
                    "locationId": "b241764c-1466-4e1d-a028-1a3684a5da87",
                    "quantity": 2,
                    "quantityElectronic": 0,
                    "quantityPhysical": 2
                }
            ],
            "orderFormat": "Physical Resource",
            "paymentStatus": "Pending",
            "physical": {
                "createInventory": "Instance, Holding, Item",
                "materialType": "d9acad2f-2aac-4b48-9097-e6ab85906b25",
                "materialSupplier": "14fb6608-cdf1-11e8-a8d5-f2801f1b9fd1",
                "receiptDue": "2018-07-31T00:00:00.000+00:00",
                "volumes": [
                    "vol. 0"
                ]
            },
            "poLineDescription": "",
            "poLineNumber": "101125-1",
            "publicationDate": "2004",
            "publisher": "MIT Press",
            "purchaseOrderId": "9447d062-89ec-486e-a14b-572f3efb9f8c",
            "receiptStatus": "Pending",
            "reportingCodes": [],
            "requester": "",
            "rush": false,
            "selector": "",
            "source": "User",
            "tags": {
                "tagList": [
                    "giftsubscription",
                    "important"
                ]
            },
            "titleOrPackage": "A semantic web primer",
            "vendorDetail": {
                "instructions": "",
                "noteFromVendor": "",
                "vendorAccount": ""
            },
            "metadata": {
                "createdDate": "2020-12-08T01:42:11.950+00:00",
                "updatedDate": "2020-12-08T01:42:11.950+00:00"
            }
        }
    ],
    "totalRecords": 1
}
GET /invoice/invoice-lines?query=poLineId==<poLineId1>  or poLineId==<poLineIdN>
 Response

{
    "invoiceLines": [
        {
            "id": "bcf0c08a-bbea-4d1b-a385-aed498789ebd",
            "adjustments": [],
            "adjustmentsTotal": 0.0,
            "comment": "",
            "description": "A semantic web primer",
            "fundDistributions": [
                {
                    "code": "USHIST",
                    "encumbrance": "eb506834-6c70-4239-8d1a-6414a5b08013",
                    "fundId": "65032151-39a5-4cef-8810-5350eb316300",
                    "distributionType": "percentage",
                    "value": 100.0
                }
            ],
            "invoiceId": "2c5ab414-3fe4-4111-9e61-d49eaf063e68",
            "invoiceLineNumber": "10000-2",
            "invoiceLineStatus": "Open",
            "poLineId": "647c1dca-b9bf-47af-8456-bfb6dfef9eee",
            "quantity": 2,
            "releaseEncumbrance": true,
            "subTotal": 316.0,
            "total": 316.0,
            "metadata": {
                "createdDate": "2020-12-08T13:19:20.910+0000",
                "createdByUserId": "a0fc81b2-0f88-5624-aed3-3c7e0403e663",
                "updatedDate": "2020-12-08T13:19:20.910+0000",
                "updatedByUserId": "a0fc81b2-0f88-5624-aed3-3c7e0403e663"
            }
        }
    ],
    "totalRecords": 1
}

Questions and answers

QuestionAnswer
Will the current and future connections provide us the information we need to return cost and budget information? 

Current connection provide all needed info but it possible only if there are any agreement attached to package/resource.

Future direct connection to the orders app assumps more stable connection.

Is a direct connection to the Invoice Line needed rather than getting the POL then Invoice line? Invoice line could be retrieved if POL is known.
High level observations on performance? There are at least 4 requests needed to get info about POL and invoice lines. If there will be more than one agreement attached to the package/resource then more requests required. Performance should be analyzied after second investigation.
What challenges are we facing in getting this information? 
Via eholdings app should we offer a way to attach package/resource to a POL# or Invoice line number?