Representing Consent-to-Share requests via API.

[Karl Fogel (OTS)]

Hi, everyone.  I'm wondering if anyone else has already developed a standard for representing Consent-to-Share requests in their HMIS API?

Dan Schultz and I have been drafting a standard -- search for "Consent-to-Share Record" in this page to see the basic idea:

  https://github.com/hmis-tools/hmis-api-server/blob/master/docs/API.md  [1]

Before we solidify this Consent-to-Share API spec and implement it, we'd like to know if anyone else has already thought this through.  Our preference is to implement something compatible with what's already out there.  Also, even if you haven't spec'd or implemented anything related to consent-to-share yet, we'd still appreciate feedback on the draft spec.

So, any thoughts?

Best regards,
-Karl

[1] Yes, by the way, that's the same API server software that formerly lived at https://github.com/PCNI/OpenHMIS -- the master development tree now lives under 'hmis-tools' on GitHub, with PCNI's helpful cooperation.

[Eric Jahn]

Thanks Karl and Dan for the update on your work!

Your timing is excellent, since we're starting to work on implementation of this functionality.  For the consent to share API, do you have an underlying logical or conceptual model for the underlying entity relations?  That's usually where I try to start when talking about APIs, since if the terms have different underlying meaning/relations, your API signatures might mean something else to you than to me.  With HMIS stuff, we have the HMIS logical model, but moving into this area is sort of undefined.  I'd be happy to help with a simple OWL ontology or something.  

I found some ontologies on this subject at: https://www.w3.org/ns/odrl/2/#term-consentingParty and at

https://github.com/ICO-ontology/ICO .  One approaches from a medical viewpoint, and the other from attribution/digital rights.  The provenance stuff that was pretty heavily worked on by W3C a few years ago is also useful I think, but that's less directly related.

It would also be useful, I think, to have a records request method (sort of the reverse/pull of client consent).

btw, I noticed in your pages you reference compatibility with the apis at https://github.com/hmis-api .  That's been unsupported now for almost 2 years, and all our current HMIS/CES API listings are posted here .  

--
You received this message because you are subscribed to the Google Groups "hmis-api" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hmis-api+u...@googlegroups.com.
To post to this group, send email to hmis...@googlegroups.com.
Visit this group at https://groups.google.com/group/hmis-api.
To view this discussion on the web visit https://groups.google.com/d/msgid/hmis-api/b28039ce-9e18-4e80-bfc7-26723ea74c2c%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Karl Fogel]

Eric Jahn <er...@alexandriaconsulting.com> writes:
>Thanks Karl and Dan for the update on your work!
>
>Your timing is excellent, since we're starting to work on
>implementation of this functionality.  For the consent to share API,
>do you have an underlying logical or conceptual model for the
>underlying entity relations?  That's usually where I try to start
>when talking about APIs, since if the terms have different underlying
>meaning/relations, your API signatures might mean something else to
>you than to me.  With HMIS stuff, we have the HMIS logical model, but
>moving into this area is sort of undefined.  I'd be happy to help
>with a simple OWL ontology or something.  
>
>I found some ontologies on this subject at: https://www.w3.org/ns/
>odrl/2/#term-consentingParty and at
>https://github.com/ICO-ontology/ICO .  One approaches from a medical
>viewpoint, and the other from attribution/digital rights.  The
>provenance stuff that was pretty heavily worked on by W3C a few years
>ago is also useful I think, but that's less directly related.

We're basically using terms and concents as per the HUD logical model, though we've coined the term "submitter" to refer to the user processing the consent request -- see below:

* "Client": Person receiving services. A client grants or denies consent to share their personal information.

* "Submitter": Person using the system, e.g, a caseworker registering a client.

* Continuum of Care: This is what HUD thinks it is.

* Organization: A member of a CoC. Typically, the Submitter is associated with an Organization, and that Organization is a member of a Continuum of Care.

The field names within a consent record are simply those used in the Clients (and Enrollments, etc) records, as already defined in the API, which in turn is based on the 2014 HUD Data Definitions.

Does that clarify what the signatures mean? And, would that ontology cover the use cases you have in mind as well?

>It would also be useful, I think, to have a records request method
>(sort of the reverse/pull of client consent).

Oh, that's simply "GET /consents/{CONSENT_RECORD_ID}"

(We anticipate it being used in practice, too, because sometimes a consent grant needs to be approved by someone else -- an administrator -- before it takes effect.)

>btw, I noticed in your pages you reference compatibility with the
>apis at https://github.com/hmis-api .  That's been unsupported now
>for almost 2 years, and all our current HMIS/CES API listings are
>posted here .  

Fixed, thank you!

Best regards,
-Karl

[Eric Jahn]

Karl,

Thanks for your clarifications.  I think your general ontology works, especially if you follow the HMIS logical model for the relationships between CoC and organization.  I'll have to think more about if it covers the bases, as we get more into our records sharing and consent design.  Because HMIS is kind of a niche, and this consent functionality isn't really specific to HMIS, ours will probably have to be more generic to human services in general (for CES and what-not), as well as for HMIS, so we might use more abstracted languages, but then I guess ours wouldn't be part of an "HMIS" api per se.  But when communicating with an HMIS specific system, we could  call your API methods to interact with it (unless the target system also used a more generic API method).  This kind of segues into another thread about scope of an HMIS API, and scope of a more general Human Services API...  

Anyway, wouldn't "GET /consents/{CONSENT_RECORD_ID}" only work if there was already an existing consent record to reference?  I was referring to the ability to ask for the generation of a new consent record, for my user/program/etc., when none yet exists, so that I can see their records (as a case manager or whatever)?  Or maybe it would just be a request for access, and then behind the scenes, consent needs to be obtained before ACL access is granted.  And then there would be a GET request for the actual records, once sharing was granted.  

Thanks again for working on this!  It definitely needs more attention...  -Eric

[Karl Fogel]

Eric Jahn <er...@ejahn.net> writes:
>Thanks for your clarifications.  I think your general ontology works,
>especially if you follow the HMIS logical model for the relationships
>between CoC and organization.  I'll have to think more about if it
>covers the bases, as we get more into our records sharing and consent
>design.  Because HMIS is kind of a niche, and this consent
>functionality isn't really specific to HMIS, ours will probably have
>to be more generic to human services in general (for CES and
>what-not), as well as for HMIS, so we might use more abstracted
>languages, but then I guess ours wouldn't be part of an "HMIS" api
>per se.  But when communicating with an HMIS specific system, we
>could  call your API methods to interact with it (unless the target
>system also used a more generic API method).  This kind of segues
>into another thread about scope of an HMIS API, and scope of a more
>general Human Services API...  

Yeah, I see what you mean. The question of API scope is one we're thinking about too.

The only aspect of the proposed consent-record API that might need to change to be used in a more general Human Services scope is the name of the "coc_ids" field. The term "continuum of care" seems to be mostly homelessness-specific, although there are a few initiatives that seem to use it in a broader health-services sense.

We could change that field's name to something more generic, like "services_group" or something. But I'm not sure that's really a win. As far as I know, there isn't as yet any term that means, for human services generally, what "continuum of care" means for homelessness services specifically. And to the extent that there is or will be such a term in human services, it looks likely that "continuum of care" will end up being that term anyway.

So I guess I've come full circle and would just propose that we keep "coc_ids". But I'm very open to hearing other suggestions, especially from anyone who knows of a more general term of art that has the same meaning but in a non-homelessness-specific way.

Other than that, the rest of the consent-record spec looks about the right shape to me, and I guess we'll go with it unless we hear otherwise.

>Anyway, wouldn't "GET /consents/{CONSENT_RECORD_ID}" only work if
>there was already an existing consent record to reference?  I was
>referring to the ability to ask for the generation of a new consent
>record, for my user/program/etc., when none yet exists, so that I can
>see their records (as a case manager or whatever)?  Or maybe it would
>just be a request for access, and then behind the scenes, consent
>needs to be obtained before ACL access is granted.  And then there
>would be a GET request for the actual records, once sharing was
>granted.  

Ah -- to generate a new consent record, you use "POST /consents"; the returned response body will contain the new record, and it will have the "id" field filled in. I've updated the documentation now to make it all clearer.

Best regards,
-Karl

[Eric Jahn]

Karl, 

But not all consent/sharing arrangement will be for the whole CoC, or for HMIS in general.  We're just using the term "service group" to represent any funding stream, arbitrary community sub group, a CoC, or whatever.  They can overlap services they each contain.  It has some precedent in some areas, but nothing in human services is pervasive, so yeah, it's a toss up.  -Eric

--
You received this message because you are subscribed to the Google Groups "hmis-api" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hmis-api+u...@googlegroups.com.
To post to this group, send email to hmis...@googlegroups.com.
Visit this group at https://groups.google.com/group/hmis-api.

To view this discussion on the web visit https://groups.google.com/d/msgid/hmis-api/87ziowjxdw.fsf%40red-bean.com.

[Karl Fogel]

Eric Jahn <er...@alexandriaconsulting.com> writes:
>But not all consent/sharing arrangement will be for the whole CoC, or
>for HMIS in general.  We're just using the term "service group" to
>represent any funding stream, arbitrary community sub group, a CoC,
>or whatever.  They can overlap services they each contain.  It has
>some precedent in some areas, but nothing in human services is
>pervasive, so yeah, it's a toss up.  -Eric

Sure. Though then again there's no requirement to include a non-empty CoC set in a request anyway -- one could just list out the specific organizations.

However, we could change the name of the field to "service_group", if that's what you're using... ?

Best regards,
-Karl

>CANHzzoOjwCZOHp9W2StgRqbB2macBW-4yojvZE-n3PEA5i%3D-JQ%40mail.gmail.com
>.

[Eric Jahn]

Karl, we've added implementing your client consent API to our task list for October.  When we start work on it, we'll probably have more feedback.  -Eric

Eric Jahn
Data Architect/IT Director
Alexandria Consulting LLC
St. Petersburg, Florida
727.537.9474
alexandriaconsulting.com

--
You received this message because you are subscribed to the Google Groups "hmis-api" group.

To unsubscribe from this group and stop receiving emails from it, send an email to hmis-api+unsubscribe@googlegroups.com.

To post to this group, send email to hmis...@googlegroups.com.
Visit this group at https://groups.google.com/group/hmis-api.

To view this discussion on the web visit https://groups.google.com/d/msgid/hmis-api/87ziowjxdw.fsf%40red-bean.com.

[Karl Fogel]

Eric Jahn <er...@alexandriaconsulting.com> writes:
>Karl, we've added implementing your client consent API to our task
>list for October.  When we start work on it, we'll probably have more
>feedback.  -Eric

Eric, thanks -- I'm really glad to hear this. Please post here with any feedback on the spec, definitely. While we've implemented it, it's still very early in production, and there's certainly time to fix any problems.

Adding Dave Totten to CC, just so he's aware of this API coordination.

Best regards,
-Karl

> send an email to hmis-api+u...@googlegroups.com.

> To post to this group, send email to hmis...@googlegroups.com.
> Visit this group at https://groups.google.com/group/hmis-api.
> To view this discussion on the web visit https://
> groups.google.com/d/msgid/hmis-api/87ziowjxdw.fsf%40red-bean.com.
> For more options, visit https://groups.google.com/d/optout.
>
>

>--
>You received this message because you are subscribed to the Google
>Groups "hmis-api" group.
>To unsubscribe from this group and stop receiving emails from it,

>send an email to hmis-api+u...@googlegroups.com.

>To post to this group, send email to hmis...@googlegroups.com.
>Visit this group at https://groups.google.com/group/hmis-api.
>To view this discussion on the web visit https://groups.google.com/d/
>msgid/hmis-api/

>CANHzzoMtMJjHzQrtNeH2VEw7o5s9FX9pFMUH%2B8KTOKY7B3HQFw%40mail.gmail.com
>.