Sender - Validate test files from Color

[BerniXiongA6]

Description coming --- placeholder for validating test files from Color (BX)

[BerniXiongA6]

Per the email exchange w/ Color:

That's excellent, Christina!

I'm copying in our engineer, Maurice Reeves, who will be able to assist with the next steps. He can explain things in further technical detail better than I can. Hey, Maurice, if you could help out Christina and the rest of the Color team, that would be fantastic.

Thanks, Berni

---

Bernadette Xiong (Agile Six) Delivery Manager, Onboarding & Operations Pandemic-Ready Interoperability Modernization Effort (PRIME) bxiong@cdc.gov

ReportStream is a product of the Center for Disease Control and Prevention (CDC) From: Christina Sheehan christina.sheehan@color.com Sent: Wednesday, August 31, 2022 2:17 PM To: Xiong, Bernadette (CDC/DDPHSS/OD/HITSSU) (CTR) rwe7@cdc.gov Cc: Report Stream (CDC) reportstream@cdc.gov; Public Health Reporting publichealthreporting@color.com; White, Sarah (CDC/DDPHSS/OD/HITSSU) tlk9@cdc.gov Subject: Re: Getting started with ReportStream

Hi Bernadette,

Great to e-meet you! Thank you so much for working with us to kick off this integration process. Our team has been in the process of reviewing the Programmer's Guide over the last few weeks and feel prepared to begin onboarding.

I have an HL7 test message with non-PII data ready for your review. Can we send this via email ahead of any connectivity with ReportStream for your review? The test message I have prepared will contain dummy data with Color's lab information as both the sending and performing facility. There are many cases in which Color partners with our lab partners to provide testing and, in turn, sends those results to reporting agencies. Please let me know if it would be helpful to have a list of these other performing labs, their CLIAs, and any other necessary information.

Best, Christina

Christina Sheehan (she/her)

Technical Relationship Manager

christina.sheehan@color.com

[BerniXiongA6]

Update 9/7/2022: Christina / Color is ready to send test files to @MauriceReeves-usds -- Mo, can you reply to Christina?

Hi Bernadette and Maurice,

Hope you had a good weekend. Thank you so much for the introduction. I look forward to working with you all on this project.

Whenever you are ready, we have prepared initial non-PII test messages. Could you please let us know how to best send them to you - would email work?

Best, Christina

[shy2cdc]

9/7 @ 6:42 PM Christina sent the below and attached the two files for review @MauriceReeves-usds

Hi Sharon,

Thank you so much!

The messages do not contain PII/PHI. Please find two test messages attached for your review. One of the messages (file ending in _3254) contains information that would reflect Color as both the sending facility and performing lab and the second message (file ending in _3269) contains an example of a message with one of our partner labs, Broad Institute, as the performing laboratory.

Best, Christina

[sliu1000]

User requesting update:

I wanted to check in with you on the test HL7 messages we sent over last week. Have you had a chance to review them and, if so, do you have any feedback for our team?

Thank you, Christina

[BerniXiongA6]

Leaving this note here for @MauriceReeves-usds -- I'll let the Color team know you have been working on this ticket and that we can reply to any questions they have through email. If it ends up being that their tech team needs to chat with us further, I'd be happy to schedule a call next week if need be. cc: @sliu1000 @sarahnw

[sliu1000]

Received Follow-up Questions from Color:

• Can you give us an idea of how many messages are being processed each day? And how many folks have adopted ReportStream?

• Can we generate a public / private key pair for JWT-based auth (and you'll store the public key on your end) ? Otherwise, if we need to use the shared API key method, can you generate this and share it with us in Keybase?

• When are you supposed to use individual vs asynchronous APIs? Is there a threshold?

• Are there plans to add other infectious diseases to ReportStream in the future? If this is a possibility, how would we hear about new diseases?

[shy2cdc]

Email below from Ruey:

Thank you for the quick response!

We have generated public & private keys today and you can find the public key attached. Hope we are able to begin sending dummy requests to ReportStream soon.

Follow-up Questions:

We’ve attached a PEM file containing our public key for the staging environment. Is this format okay for you?

We’re assuming we should generate a separate keypair for stage and production. Is this correct?

What client ID should we use in the client_credentials request?

Please let us know when you have an update about availability to schedule a Q&A meeting.

Ruey

[shy2cdc]

Email from Ruey: @sarahnw

Hi Sarah,

Happy Friday! We wanted to quickly check-in on if there's anything on our end that could help this along or if you have a sense of how long it takes to generate a client for us? We are waiting to begin development after we receive the client.

Please let us know if it would be possible for us to meet next week! We're very excited to be adopting ReportStream (it's incredibly valuable for reportable diseases).

Ruey

[shy2cdc]

From Christina

Hi ReportStream Team,

Hope you all are well! I wanted to extend appreciation again for the thoughtful answers you provided to our team's questions - really exciting to hear you may expand into other infectious diseases in the future!

Are there any updates you can share on the progress of our onboarding or any feedback on the test HL7 messages provided on Sept. 7th? We are eager to integrate with ReportStream and are happy to provide any additional information that may be helpful.

Thank you, Christina

[shy2cdc]

From Christina:

Hi @MauriceReeves-usds and @BerniXiongA6 ,

Happy Friday! We received the email about the new support ticketing system your team is using - congratulations on the launch!

Have you had a chance to review our test HL7 messages or could you assist us in creating an account for the support site so we can resubmit the test messages in a ticket for review?

Thank you for your help.

Best, Christina

[BerniXiongA6]

updates 9/30/2022: Sent a reply to all that we can follow up with Color on Monday when Mo and I are back. Also i let her know that she doesn’t need a new ticket number.

[shy2cdc]

Email from Ruey:

Hi @MauriceReeves-usds ,

We're trying to send a request with what we believe would be our client but are getting no response. Would you mind providing Color's client name?

Thanks!

[shy2cdc]

Email from Nick:

Hi @MauriceReeves-usds ,

Thanks for sending the KID. I'm the developer working on testing the staging connection. I believe I'm sending a proper request, but I seem to get no response. Here's my curl request taken from the programmers' guide. I'm omitting the token for security purposes, but will add the token contents below. curl -X POST -H "content-length:0" "https://staging.prime.cdc.gov/api/token?scope=color-labs.default.report&grant_type=client_credentials&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={{color_token}}" I verified that the token signature is correct using the public key we provided you. Here are the token contents, decoded:

headers - { "typ": "JWT", "alg": "RS256", "kid": "color-labs.default" }

payload - { "aud": "staging.prime.cdc.gov", "iss": "color-labs.default", "sub": "color-labs.default", "exp": 1664905840, "jti": "f3734fb4-c90a-4666-a182-8583d01c66ec" }

Please let me know if you see anything wrong with the request, or if you're able to see these requests on your end. When I send an incorrect scope format, like "fakelab.report", I do actually get a response from the API.

Best,

Nick

[shy2cdc]

Email from Nick:

Hi @MauriceReeves-usds ,

I'm able to get an access token now. Thanks for catching that!

In addition to the name, though, I also had to modify the scope I was requesting for. I was originally using color-labs.default.report because I was referencing page 11 of this doc https://reportstream.cdc.gov/assets/pdf/ReportStream-Programmers-Guide-v2.3-updated.pdf. It seems ".default.report" results in a 401. Should we always request for "color-labs..report"? Are there any other scopes we need to be aware of outside of the ones granted by requesting "..report" ?

Excited that this part of the integration is now working!

Best,

Nick

[shy2cdc]

@MauriceReeves-usds Email from Nick:

Hi Maurice,

I tried sending a couple messages just now and received the response below. I could easily be doing something wrong, but the error seems to indicate maybe you're missing a schema on your end for us? Regardless, the fact that we're able to connect to your API and get helpful error messages is great progress. Thanks for your continued support!

error response: { "id" : null, "submissionId" : 3218756, "overallStatus" : "Error", "timestamp" : "2022-10-06T21:30:15.880Z", "plannedCompletionAt" : null, "actualCompletionAt" : null, "sender" : "", "reportItemCount" : null, "errorCount" : 1, "warningCount" : 0, "httpStatus" : 400, "destinations" : [ ], "actionName" : "receive", "externalName" : "", "reportId" : null, "topic" : null, "errors" : [ { "scope" : "parameter", "message" : "'client:color-labs': unknown schema 'hl7/color-labs-covid-19'" } ], "warnings" : [ ], "destinationCount" : 0 }

Best,

Nick

[shy2cdc]

Email from Ruey:

Hi Team,

Thank you so much for taking the time to chat with us today. Meeting notes can be found in our meeting doc. A few action items & questions from our meeting below:

ReportStream

Sent message and received "errors" : [ {"scope" : "parameter","message" : "'client:color-labs': unknown schema 'hl7/color-labs-covid-19'"}]

ReportStream to complete Color’s setup so Color can begin testing in staging - question: do you know when folks might be able to finish setting up? We’d love to continue the process to integrate with ReportStream and are excited to adopt the product.

For confirmation - which fields in the payload are used to distribute the result to the corresponding state DPH?

Color

Will generate and send PROD keys to ReportStream

Thanks!

Ruey

[shy2cdc]

Email from Nick:

Hi Sharon,

Thanks for confirming receipt. I'm also attaching our production public key, another item from Ruey's meeting notes. We'd love it if someone could get this added to our client in prod in tandem with the investigation of the staging messaging issue highlighted above. This would greatly help us in our testing.

Best,

Nick

[sliu1000]

@MauriceReeves-usds

Color waiting for their production public key to their client in Prod.

Full communication below:

Hi Sharon,

Thanks for confirming receipt. I'm also attaching our production public key, another item from Ruey's meeting notes. We'd love it if someone could get this added to our client in prod in tandem with the investigation of the staging messaging issue highlighted above. This would greatly help us in our testing.

Best,

Nick

[sliu1000]

Update from Color on 10/24/2022 at 8:28 PM:

Thank you! We were able to connect to staging and will begin testing the API. Ruey Pham

[BerniXiongA6]

@GilmoreA6 is taking over the onboarding for Color moving forward. James, I'll forward any emails to you that I have so you know where we are in the process. cc: @sliu1000

[GilmoreA6]

Just wanted to check in and make sure I understand where we are in your onboarding process. It looks like Joel was able to solve the error for unknown schema that you were experiencing. Have you been able to send test data to staging yet or are you still encountering errors?

Thanks,

James

[GilmoreA6]

Hi All,

Thanks for meeting today. I was doing some thinking about the customizations you had mentioned for states and whether or not you should undo them to send to ReportStream. Let's actually leave that it place for now and if we can generate test messages for each of the unique customizations I can run them through and make sure they don't cause issues in ReportStream.

I was thinking about the ORC/OBR-2 issue you mentioned and we would just have to replace logic you already have with logic in ReportStream which doesn't make sense to do if we can avoid it. Sorry for immediately contradicting myself on this.

Let me know if you have any questions.

Thanks,

James

[GilmoreA6]

James,

That sounds good. We'll leave the customizations for now. Thanks again so much for answering all our questions yesterday. You've provided us with some great information to help us accelerate our integration with you.

As we discussed, here are 2 IDs for messages I submitted yesterday in stage that I was expecting to go to states that are not California - 82200a2f-9592-43d4-9bce-7f5769971f9f and 59fe2697-c896-490f-9dfb-3093602fc4bb. One was meant for Arkansas and the other North Carolina. Please let me know what you find about these messages/requests and if there's any more information you need from me. I can generate some fresh requests whenever necessary, including for different states.

Best,

Nick

[GilmoreA6]

Hi All,

Please see answers below in red. Let me know if you have any other questions.

Thanks

-James

James Gilmore (Agile Six) Senior HL7 Data Analyst Pandemic-Ready Interoperability Modernization Effort (PRIME) From: Ruey Pham ruey.pham@color.com Sent: Wednesday, November 16, 2022 2:06 PM To: Xiong, Bernadette (CDC/DDPHSS/OD/HITSSU) (CTR) rwe7@cdc.gov Cc: Gilmore, James (CDC/DDPHSS/OD/HITSSU) uaf6@cdc.gov; Report Stream (CDC) reportstream@cdc.gov; Nicholas Wheeler nicholas.wheeler@color.com; Christina Sheehan christina.sheehan@color.com; Public Health Reporting publichealthreporting@color.com; Brandon Canniff brandoncanniff@navapbc.com Subject: Re: Getting started with ReportStream

Hi!

We're currently working on the ReportStream integration and had a few questions come up (doc version here if it's easier to share and distribute).

Questions:

Patient address state and collection facility state is how the logic distro the reports. What are the exact fields used for routing? This will depend on how the particular public health jurisdiction has decided to filter their data. In general, most states accept data where either the patient address state (PID-11-4) or ordering facility state (ORC-22-4) are equal to that jurisdiction. County level public health entities also include a filter for that county (ORC-22-9)

When reporting results, the response body contains “id” and “submission_id”. One is a UUID and the other an integer.

Are both these values guaranteed to be unique with each submission/request? Yes

Is there a functional distinction between them? Yes, the submission_id is just the row number of that action in one of our database tables. The id (UUID) is what we use throughout reportstream as the unique identifier for that report.

Which is the preferred value to query the history API with? Both should work, so I would use whatever you find to be the most efficient. You may find the submission_id to return faster. Caveat here that the id (aka report id) is what we will ask for if we need to investigate something for you. It is more relevant for most troubleshooting processes.

We had asked about the partial batch success feature before and it sounded like it was on by default. It’ll be much more efficient for us if this feature is turned off.

Can we turn off partial batch message success? This is handled with a flag in the submission, it is not a configuration item. By default ReportStream will fail the entire batch unless the partial submission flag is included.

Is it possible to turn this off in the staging environment relatively soon, so it can be tested? see above, this should be the behavior you observe if not using the partial flag.

Some questions regarding your logic for routing records to destinations.

Could you describe this logic generally? Public Health Jurisdictions each provide ReportStream with their own criteria for what messages should be routed. In practice, this is almost universally patient address state (PID-11-4) or ordering facility state (ORC-22-4). Counties have additional logic to filter on only that specific county. Exceptions for a few states include CA, WA and NJ who also require each sender to have an onboarding process with them.

If it’s difficult to describe fully, could you provide us with the key fields being used to make these determinations? PID-11-4 or ORC-22-4

What happens to a record that should be routed to a state that doesn’t have a ReportStream integration? Is there a default destination or is it simply rejected or does something else happen? The message would not be rejected as ReportStream will by default send all data to the Federal Government's HHSProtect data hub (data is stripped of PHI/PII before being sent to HHSProtect).

[sliu1000]

Update from Sender:

Color would like to move forward with production onboarding.

Please see below communications:

Hello,

We’ve been working the last few weeks on our implementation for our integration with you. We’ve been testing against the staging environment and everything looks good on our end. We’d like to move forward with production onboarding.

We have already tested authorization in prod and everything works as expected. You should see some successful token requests on your end. We are yet to test submitting any hl7 messages to production, however.

Please let us know our next steps to continue testing with you. We’re happy to generate any test messages, special use cases, messages for varying states/territories, etc.

Whatever we can do to expedite production onboarding we are willing to do.

Best,

Nick

[Jcavallo7]

User update:

"James,

Thanks for the swift response. I'll get to work on the adjustments and let you know when they're finished.

Best,

Nick"

[sliu1000]

User Update:

Hi James,

Could you please check the 3 most recent messages I've submitted and confirm whether I've made the correct changes mentioned above? IDs for the messages are "c222b1fe-8e37-46d1-926e-ef2c293bb26c", "0954f533-f519-4c70-bec5-3be08ef5a16d", and "67137bfb-d822-4e81-bf1b-3644ae4b85d3".

Please let me know if you need any additional information.

Best,

Nick