Filtering for Item Report

[labradford]

Story

Item Reports should be able to receive filter params for the following:

• [x] Begin_Date* required
• [x] End_Date* required
• [x] Platform(?)
• ~[ ] Author~ moved to #721
• [x] Item ID
• [x] Access_Method (Regular or TDM - only regular users for now until we know if there are know data miners)
• ~[ ] Access Type (I think this is the item's visibility)~ moved to #725
• [x] Data_Type (this maps to the work resource_type)
• [x] Metric_Type (Searches_Platform, Total_Item_Investigations, Total_Item_Requests, Unique_Item_Investigations, Unique_Item_Requests)
• ~[ ] YOP (Year of publish)~ moved to #720

The following are listed in the SUSHI api docs but I do not see them in COUNTER. Not sure if they apply.

• Attributed(?)
• Country_Code(?)
• Subdivision_Code(?)

Acceptance Criteria

• [ ] Item report can be filtered on the above items.

Screenshots / Video

Testing Instructions and Sample Files

you can add the following params into the url one at a time, or all at once. each additional param must be proceeded by an &. the begin and end date are always required. passing an invalid parameter should return a descriptive error message.

• [ ] View the default Item report in browser at /api/sushi/r51/reports/ir?begin_date=2023-06&end_date=2023-06
• [ ] additional params (the specific values have only been tested against dev.commons-archive.org.) if you give invalid params, you'll receive a detailed error message on how to correct it.
  • item_id=0ba21f82-33cc-41df-948e-e7c68676ed41
  • platform=dev.commons-archive.org
  • access_method=regular
  • data_type=article
  • metric_type=Total_Item_Investigations

e.g.: /api/sushi/r51/reports/ir?begin_date=2023-06&end_date=2023-06&access_method=regular

Notes

[alishaevn]

blocked by #627

[alishaevn]

according to the below, I think we either need to not account for the access_type filter at this time, or add it to the hyrax::countermetric datatable. if we do the latter, I'm not sure that the item visibility actually maps to the allowed values. @labradford

---

https://countermetrics.stoplight.io/docs/counter-sushi-api/5a6e9f5ddae3e-ir-item-report access_type string

Optional Report_Filter. A list of Access_Types separated by the | character (URL encoded as %7C) to return usage for. Omit this parameter to include all Access_Types. Allowed values: Controlled Open Free_To_Read

[labradford]

@alishaevn can you bring this up in planning today because I think Crystal has context on this

[alishaevn]

we discussed this in planning. below are notes from prior meetings about this filter. however, jeremy brought up good reasons as to why we may not want to account for this parameter at all.

although these methods don't 1:1 map to visibility, even if they did the visibility of an item can change. in that case, do the historical metrics change?? would all past metrics for the item have to be updated to reflect the current visibility? if the metrics didn't change historically, that also presents a problem. what if the visibility is private for the first 14 days of the month, then public for the rest of the days? reports are shown in 1 month increments, so which visibility status would be recorded? how would a use search properly for that?

previous notes

**What access types will you have? How would we determine what was what?** For Access Types, our use case would be entirely within Other_Free_To_Read (and maybe OA_Gold). If others implement access restrictions, content which requires a login would be categorized as Controlled. There should be metadata backing to distinguish open resources between Other_Free_To_Read and OA_Gold, but quite honestly, a simpler approach might be to classify all open repository deposits as Other_Free_To_Read, as the OA

[ctgraham]

Tasha at COUNTER reports on 23 August:

In respect of reporting on content where the Access_Type changes mid-month, this isn’t a question that’s come up before. However, yes, we would want the provider to record usage of the content under the Access_Type which applied at the point of usage (e.g. both Controlled and Open if the item changed in mid-month). I’m going to raise this with the technical group to ask whether we can develop a fall-back position.

I've reached out again to Tasha today to see if the technical group has a recommendation.

[alishaevn]

thanks @ctgraham. when you hear back about the access type filter, can you update #725 instead? I'd like to keep/move all conversation related to that filter on that ticket.

please use this ticket to qa the Begin_Date, End_Date, Platform, Item_ID, Access_Method, Data_Type and Metric_Type filters on the Item report only. 🙂

[alishaevn]

@ctgraham I see you thumbs upped my message. does that mean you're approving this work? if so, can you move this ticket (and all others you've qa'd as successful) to the "deploy to production" column?

[ctgraham]

Pitt QA concerns

Error messages are not in SUSHI Exception format

Providing an invalid or unmatched filter returns a JSON error, but not in SUSHI Exception format. E.g. https://pittir.commons-archive.org/api/sushi/r51/reports/ir?begin_date=2023-06&end_date=2023-06&item_id=25f1326c-8dd0-4fbb-ac2f-68be8b952103|f08d0f8f-7768-46bb-b186-f7bbcc6b314c

{"error":"The given parameter `item_id=25f1326c-8dd0-4fbb-ac2f-68be8b952103|f08d0f8f-7768-46bb-b186-f7bbcc6b314c` is invalid. Please provide a valid item_id, or none at all."}

Expected:

{
  "Code": 3060,
  "Message": "Invalid ReportFilter Value",
  "Data": "The given parameter `item_id=25f1326c-8dd0-4fbb-ac2f-68be8b952103|f08d0f8f-7768-46bb-b186-f7bbcc6b314c` is invalid. Please provide a valid item_id, or none at all."
}

Unrecognized filters do not raise errors

Providing an invalid report filter should return an SUSHI 3050 Exception. E.g.: https://pittir.commons-archive.org/api/sushi/r51/reports/ir?begin_date=2023-06&end_date=2023-06&item=25f1326c-8dd0-4fbb-ac2f-68be8b952103

Expected:

{
  "Code": 3050,
  "Message": "Parameter Not Recognized in this Context",
  "Data": "The given parameter `item` is invalid."
}

[alishaevn]

@ctgraham this is ready for review again. re: 3050 exception.

[ctgraham]

Confirmed resolved from Pitt QA.