Expose license terms over API (ERM-356)

[ERM-361] Support API for retrieving license terms based on a resource identifier Created: 24/Jun/19  Updated: 23/Jan/23  Resolved: 05/Dec/19

Status: Closed
Project: ERM Platform
Components: mod-agreements
Affects versions: None
Fix versions: None
Parent: Expose license terms over API

Type: Sub-task Priority: P3
Reporter: Jag Goraya Assignee: steve.osguthorpe
Resolution: Done Votes: 0
Labels: erm
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original estimate: Not Specified

Issue links:
Relates
relates to ERM-641 License custom property "note" field ... Closed
relates to ERM-2514 License terms are not displayed in Pu... Closed
Sprint: ERM Sprint 78, ERM Sprint 70, ERM Sprint 71, ERM Sprint 75, ERM Sprint 76, ERM Sprint 72, ERM Sprint 73, ERM Sprint 77
Development Team: Bienenvolk

 Description   

Support the ability to make an API and get a license JSON representation back for public facing properties. API should support requests by:

  • eHoldings titleID+packageID
    • Example: Harvard Business Review in the Academic ASAP package has ID: 18-34-32090 [34 = packageID] and [32090 = titleID].
  • Agreement resource ID
  • Resource Title identifier e.g. ISSN, ISBN (lower priority)

When a Request is made, relevant licenses should be identified by:

  • Identifying a resource
  • Finding all agreements which that resource is part of (either as an agreement line, or as part of a package which is part of an agreement via an agreement line) which also fulfil the criteria:
    • Agreement Status == Active AND agreement start date in the past AND (an end date in the future OR a blank end date)
    • Agreement Status == (Active OR Cancelled) AND Perpetual Access == Yes
  • Finding the Controlling license (if one exists) for the agreements

Once all relevant licenses have been identified the details of each relevant agreement+controlling license combination will be returned as the API response

Multiple Agreement+License maybe returned to a single API call. The structure of response will be specified by ERM-360 Closed



 Comments   
Comment by Jag Goraya [ 24/Jul/19 ]

Support the ability to make an API call to an "edge API" service and get a license JSON representation back for public facing properties

Owen Stephens is the "license JSON representation" the one defined in ERM-360 Closed ?

Comment by Owen Stephens [ 25/Jul/19 ]

Yes

Comment by Khalilah Gambrell [ 31/Jul/19 ]

Owen Stephens

  • What about this scenario Status = Cancelled AND Perpetual Access = Yes?
  • The eholdings resourceID = titleID+packageID?
  • What is the Agreement resource ID?
Comment by Owen Stephens [ 31/Jul/19 ]

> What about this scenario Status = Cancelled AND Perpetual Access = Yes?
Khalilah Gambrell I'm happy to add this to the criteria if that's your preference?

>The eholdings resourceID = titleID+packageID?
Khalilah Gambrell can you clarify with some examples of what IDs you'd want to be able to use and how they map to the IDs we can access in Agreements/eHoldings?

>What is the Agreement resource ID?
I had in mind this was a Folio UUID for a resource in the Agreement internal KB steve.osguthorpe does that make sense?

Comment by Khalilah Gambrell [ 02/Aug/19 ]

> What about this scenario Status = Cancelled AND Perpetual Access = Yes?
Khalilah Gambrell I'm happy to add this to the criteria if that's your preference?
Owen Stephens, proceed.

>The eholdings resourceID = titleID+packageID?
Khalilah Gambrell can you clarify with some examples of what IDs you'd want to be able to use and how they map to the IDs we can access in Agreements/eHoldings?
Example: Harvard Business Review in the Academic ASAP package - https://folio-snapshot.aws.indexdata.com/eholdings/resources/18-34-32090 [34 = packageID] and [32090 = titleID]. It would be great to retrieve by both IDs or at minimum the packageID.

>What is the Agreement resource ID?
I had in mind this was a Folio UUID for a resource in the Agreement internal KB Steve Osguthorpe does that make sense?

Comment by Owen Stephens [ 02/Aug/19 ]

Thanks Khalilah Gambrell have updated description based on this. One additional question:

It would be great to retrieve by both IDs or at minimum the packageID.

So if API were passed: 18-34-32090 (Harvard Business Review in the Academic ASAP package)

Should that (ideally) return Agreement+License for all Agreements containing HBR (titleID = 32090) or only for those that contain HBR as part of Academic ASAP (i.e. Agreement line for packageID = 34 OR Agreement line for packageID+titleID 34-32090) ?

My initial assumption had been only the latter - because if you are querying based on the package that will have specific licenses that apply. But happy to return more if we can (tbh we may have to explore exactly what's possible but at the moment just trying to understand the ideal from your perspective)

Comment by Jag Goraya [ 02/Dec/19 ]

steve.osguthorpe what's the url structure for calling this to test please? /cc Owen Stephens

Comment by Claudia Malzer [ 02/Dec/19 ]

I found a new erm/sas/publicLookup endpoint in Steves commits, no idea, if that's what you're looking for Jag Goraya, Owen Stephens

Comment by Owen Stephens [ 02/Dec/19 ]

Thanks Claudia Malzer - I saw that and was trying to use it, but couldn't get an expected response (JSON with license details in) - I was unclear where the resourceId or referenceId should go (part of the path? or a parameter?)

Comment by steve.osguthorpe [ 03/Dec/19 ]

Owen Stephens
the endpoint and full path is `erm/sas/publicLookup`

And the rule for nearly all our controllers is you can supply the following (all as encoded url parameters):
`term`
`match`
`filters`
`sort`
`offset` or `page`
`max` or `perPage`

`term`, `match`, `filters`, `sort` can only be used on the data stored in this module So you can not filter by license term from this endpoint.

Bu also for this one I added
`referenceId` and `resourceId` (which both just effectively prepoulate a load of filters for you)

You should be able to use a url like this for E-Holdings or other references should we add them:
`/erm/sas/publicLookup?referenceId=18-34-32090` find all agreements with that resource as part of it.
`/erm/sas/publicLookup?referenceId=18-34` find all agreements specifically with the package.

resourceId can be supplied for any of our resources that you can add to an agreement +titelInstance and it should do the correct joins.
`/erm/sas/publicLookup?resourceId=some-id-of-internal-resource`

Generated at Fri Feb 09 00:18:35 UTC 2024 using Jira 1001.0.0-SNAPSHOT#100246-sha1:7a5c50119eb0633d306e14180817ddef5e80c75d.