Preliminary research into tracked item APIs

mackhowell-nava commented 1 month ago

Things we know about:

BGS SOAP API (see tracked items - knowledge gathering)
BIP/BIE Events Service -- in development -- claim evidence, development items -- see Megan's slack message in #bip-support-ext-vro
Note: Megan also shared with us an alternative events service we could potentially leverage for "enterprise" events - https://department-of-veterans-affairs.github.io/ves-event-bus-developer-portal/

Things we've seen:

On code.va.gov -- "Bip Trackeditem Api" (same as the BIP/BIE events?)
On code.va.gov -- "Tracked Item Service"
On confluence -- "Tracked Item API" -- https://confluence.devops.va.gov/display/VAExternal/Tracked+Item+API
On confluence -- "Evidence API" -- https://confluence.devops.va.gov/display/VAExternal/Evidence+API
On confluence -- "Tracked Item API (bip-trackeditem-api)" -- https://confluence.devops.va.gov/pages/viewpage.action?pageId=48088773
On confluence -- Random reference found to VBMS calling "the tracked item API" -- https://confluence.devops.va.gov/display/VAExternal/CEST+Research?preview=/48089095/48736749/Tracked%20items.docx

See also:

On confluence -- Standard Development Actions -- data mapping between BGS <> VBMS <> Corp DB

Potential product task: Reach out to Nathan Jolly.

nanotone commented 1 month ago

Results from investigating the feasibility of using BGS for working with tracked items:

bgs-ext, the Ruby gem that vets-api uses for making BGS calls, has a tracked_items service which supports one method, find_tracked_items (by claim ID). In vets-api staging, this can be invoked like

fs = Form526Submission.find(1366)  # VFN 796378881 has results on claim 600442578
key = fs.form['form526']['form526']['veteran']['emailAddress'].first(39)
ti = BGS::Services.new(external_uid: fs.user_account.icn, external_key: key).tracked_items
ti.find_tracked_items(fs.submitted_claim_id)

which returns a data structure that looks like

{:benefit_claim=>
  {:name=>"BenefitClaim",
   :dvlpmt_items=>
    [{:jrn_dt=>Wed, 17 Jul 2024 12:37:27 -0500,
      :name=>"DevelopmentItem",
      :claim_id=>"600527334",
      :create_dt=>Wed, 17 Jul 2024 12:37:26 -0500,
      :create_ptcpnt_id=>"601227029",
      :create_stn_num=>"322",
      :docid=>"1130103",
      :dvlpmt_item_id=>"499228",
      :dvlpmt_tc=>"CLMNTRQST",
      :req_dt=>Wed, 17 Jul 2024 00:00:00 -0500,
      :short_nm=>"Claim for a Specific Evaluation",
      :std_devactn_id=>"38976",
      :suspns_dt=>Wed, 17 Jul 2024 00:00:00 -0500},
     {:jrn_dt=>Wed, 17 Jul 2024 12:36:28 -0500,
      :name=>"DevelopmentItem",
      :claim_id=>"600527334",
...

Other documented methods on the TrackedItemService can be invoked by directly calling the SOAP method:

response = ti.send(:request, :find_tracked_items_by_file_number, "fileNumber": fs.birls_id)
response.body[:find_tracked_items_by_file_number_response]

This should presumably apply to write methods as well, including ManageTrackedItems and deleteTrackedItems, although we don't have documentation on the business rule governing when these operations would be allowed.

nanotone commented 1 month ago

Working understanding of the data structure resulting from find_tracked_items:

dvlpmt_items contains a list of tracked item objects, with the following business-relevant fields:

name - this is always "DevelopmentItem"
claim_id
create_dt - when the tracked item was created
create_ptcpnt_id - participant ID of the user who created it
create_stn_num - station number of the user who created it
docid - ID of the document (letter) that this is tracking
dvlpmt_item_id - ID of the underlying development item record (this might be usable as a primary key?)
dvlpmt_tc - describes what this tracked item is. CLMNTRQST is "claimant request".
req_dt - ?
suspns_dt - calendar date the tracked item's suspense period is expected to be complete
short_nm - short name
std_devactn_id - ID of the standard development action that defines this development item

The response also includes a list of letters, each with these fields:

clm_id
docid
dvlpmt_tc - CLMNTRQST
file_stt_tc - status code, e.g. DONEDVLPMT, INDVLPMT
incld_enclsr_ind - whether to include or exclude enclosures when printing the outgoing document
outdcmt_tc - outgoing document type code; seems to always be DV
print_dt - print date; when the letter was printed and sent out
ptcpnt_dcmnt_tn - describes participant document type; seems to always be Receiver
ptcpnt_id
templat_tc - letter template type code, e.g. VSC, VSCNP, VNP

nanotone commented 1 month ago

I should also mention that the Ruby gem also supports a separate BGS service DocumentService, which to my knowledge is currently used by Caseflow to generate letters and associated tracked items for HigherLevelReviews.

mackhowell-nava commented 1 month ago

From Nathan Jolly in Slack in response to if he knows of any more APIs or resources:

Right now the only "live" service is the legacy soap service
the tracked item api was created by VBMS and is just a wrapper of the soap
in the future the BEP team will be making a restful service or taking over the VBMS one to make it a direct call instead of a wrapper
as far as short cycling a tracked item suspense, you can do that no issue by setting the received date

Do you know if the received date is set for all tracked items, of is that used conditionally?

its set for all if data received... there are several date fields though so if things like the suspense date is reached a different field is filled and it is moved on
there are in-error fields for closure of inappropriate

department-of-veterans-affairs / abd-vro

Preliminary research into tracked item APIs #3207