Workflow enhancement - assignment and "ownership" logic to users via departments

[pwalsh]

In #26 ( implemented in #29 ) we added basic support for departments in a jurisdiction, being the ability to associate a service request with a department. As noted in #26 (comment) there are several ways this feature can develop based on input we have from current users and potential users.

The current implementation optionally allows assigning a request to a department. This assignment has no impact or relation to the person assigned to the request at present. The department itself does have a primary contact name and email as metadata, but this is not a StaffUser object, and it just for display purposes, not for any use in the assignment of requests.

We have a new potential user with key user scenarios that we can support by iterating on the initial base.

Our current understanding of the user scenarios is as follows:

1. Departments have one or more staff users who are "team" or "department" leads, for the purposes of service delivery.
2. Assignees for tickets should come from a list of staff users who are explicitly associated with a department. This could be one of the department leads, or, another staff user who is not a lead.
3. Department leads will communicate with each other around any given request, and, communicate with the assigned person, and, communicate with the person who submitted the request.

Supporting this in the GovFlow API server requires:

1. A configuration setting for enforcing assignment via department (I think this will be a common use case, but not one we should enforce going forward for all users of govflow): ENFORCE_ASSIGNMENT_VIA_DEPARTMENT
2. Adding a relationship from StaffUser to Department - this relationship will be required for non-admin staff users when ENFORCE_ASSIGNMENT_VIA_DEPARTMENT is true.
3. Allow StaffUsers to belong to multiple Departments.
4. Don't allow StaffUsers to be removed from a Department if they have non-closed tickets assigned via the department.
5. Allow one or more staff users in a department to be a lead for this department - can implement this via a Group model for more flexibility around other "group types" or just as a boolean on the staff user / department relation now.
6. Various CRUD actions for relationships between staff users and department exposed via dedicated endpoints.

Probable client changes required:

1. Get some configuration from the GovFlow server via a "client config endpoint", to configure itself appropriately (I talked about that previously here in regard to captcha, and the more features we add that are configurable it makes more sense to centralize this config to the server and the clients configure themselves accordingly from there, rather than maintaining the same config in multiple places)
2. new screens for managing staff user / department / lead relations
3. In the workflow for requests, when ENFORCE_ASSIGNMENT_VIA_DEPARTMENT is true require assigning a department before assigning a staff user, and, if department changes, clear user assignment
4. At any time, given a request, have a list of department leads for the request as well as the assignee - this may or may not display in the UI, but will be required for further communication use cases.

[pwalsh]

A related issue is do we make explicit associations between departments and services.

[amirozer]

Thanks @pwalsh ,

Regarding ENFORCE_ASSIGNMENT_VIA_DEPARTMENT - I imagine this is an instance-level config? I think we might need to allow setting it for individual jurisdictions, and manage the setting in the DB, either in the Jurisdictions table in a new JurisdictionSettings table.

And I'd like us to consider the following scenario: If a request is assigned to a department and a user, and we re-assign it to a different department, do we unassign the user? Do we "force" choosing a new assignee before updating the assigned department?

[pwalsh]

@amirozer

Regarding ENFORCE_ASSIGNMENT_VIA_DEPARTMENT - I imagine this is an instance-level config? I think we might need to allow setting it for individual jurisdictions, and manage the setting in the DB, either in the Jurisdictions table in a new JurisdictionSettings table.

Yes, you are right, this needs to be a jurisdiction setting and not an instance setting.

And I'd like us to consider the following scenario: If a request is assigned to a department and a user, and we re-assign it to a different department, do we unassign the user? Do we "force" choosing a new assignee before updating the assigned department?

I meant to address with with my point 3 for the client in the original ticket:

require assigning a department before assigning a staff user, and, if department changes, clear user assignment

So I think the flow is (i) change department, (ii) auto clear user assignment, and (iii) the person taking the action then (optionally) re-assigns to a user from the new department.

If the same user is associated with both departments, we can leave the assignment.

[noamoss]

@pwalsh just to verify, what is the expected flow for changing an assigned user within the same department?

[pwalsh]

@noamoss in that case there is no change from how it currently works in the UI we use (which is not currently open source), and there is no change from how it works at the API level (here in GovFlow).

[noamoss]

Hi @pwalsh

1. Can you explain why do you think this is needed?

Allow StaffUsers to belong to multiple Departments.

Did we hear about a user that works simultaneously in more than one department/unit?

2. Same question for this part:

Allow one or more staff users in a department to be a lead for this department - can implement this via a Group model for more flexibility around other "group types" or just as a boolean on the staff user / department relation now.

If we don't know of a need to enable two stakeholders to be defined as a "lead", are not we just creating extra complications in terms of double assignment and notification for new tickets?

3. Your following comment brought up a point to notice:

So I think the flow is (i) change department, (ii) auto clear user assignment, and (iii) the person taking the action then (optionally) re-assigns to a user from the new department.

The offered implementation suggests that only a department leader has permission to assign the ticket to another worker from the same department. BUT I assume there are two extra configurations we will need to handle (maybe later):

3a. Can user X assign user Y to the ticket if they are from the same department?
When, for example, user X did their part, but user Y needs to verify or take another action before closing the ticket. Can they do it directly or it is just the head of the department that should be allowed to move the request ticket inside the department?

3b. Can user X assign user Y to the ticket if they are from a different department?
I assume that in some organizations this is a common and preferred method, enabling direct communication between workers and not only heads of departments. In these situations, there is another question to figure out: what event should be triggered toward the head of the department?

[pwalsh]

@noamoss

Allow StaffUsers to belong to multiple Departments.

We talked about exactly this use case on Monday with @amirozer - that what we call a department currently is actually a unit that represents a function, and persons could perform/associate with to multiple functions.

Allow one or more staff users in a department to be a lead for this department - can implement this via a Group model for more flexibility around other "group types" or just as a boolean on the staff user / department relation now.

If we don't know of a need to enable two stakeholders to be defined as a "lead", are not we just creating extra complications in terms of double assignment and notification for new tickets?

According to the initial call with client X, we do need more than one stakeholder to be defined as a lead, hence the proposed implementation, but, as you know I'm sitting on the finalization of this implementation until we do a more formal discovery interview.

The offered implementation suggests that only a department leader has permission to assign the ticket to another worker from the same department.

No, there is no suggestion that association with a department is a permission to perform assignment actions, only that it is an association to be a valid assignee when a request is associated with a given department.

Can user X assign user Y to the ticket if they are from the same department?

As above, nothing here is about permissions to perform assignment actions - any user for a jurisdiction at present can perform assignment actions.

Can user X assign user Y to the ticket if they are from a different department?

Does "they" refer to user X or Y? In either case though, see above, and also #51 (comment) for a description of the cascading relationship if a request department changes.

[noamoss]

@pwalsh

we call a department currently is actually a unit that represents a function

Ok, sorry for the confusion, so it makes sense to enable a user to relate to two units+functions - assuming we do not want to separate levels of "units" and "functions". I think later we will have to rethink this; as a "Unit" (an organizational entity, and a more generic term for a department, including both internal and external groups of users) will become responsible for different functions (or services). I am just reminding we already know that a key difference between organizations is the way the main functions are organized between their units/departments.

..., see above, and also #51 (comment) for a description of the cascading relationship if a request department changes.

I believe the permissions rules and restrictions will come as requests, and bringing it up now to approve nothing will prevent these kinds of implementation later, if needed.

[pwalsh]

@noamoss ( cc @amirozer @idoivri )

Ok, sorry for the confusion, so it makes sense to enable a user to relate to two units+functions - assuming we do not want to separate levels of "units" and "functions". I think later we will have to rethink this; as a "Unit" (an organizational entity, and a more generic term for a department, including both internal and external groups of users)

I agree and I think, like services, we will need to remodel this as a tree #30 and then the simple jurisdictions have a depth of 0, and more complex scenarios have nested entities. In terms of data modeling, I don't think there is a clear distinction between a "unit", a "function", or a "department" - they are all, let's say, "units" and the differentiation is in how a given jurisdiction would use them.

I believe the permissions rules and restrictions will come as requests

So do I, and I think we will address it then.

[noamoss]

@pwalsh

I guess we will discuss it, later on, #30, so for now, I will just comment that regarding

.... I don't think there is a clear distinction between a "unit", a "function", or a "department" - they are all, let's say, "units" and the differentiation is in how a given jurisdiction would use them.

I believe there is a difference between unit/departments (which are organizational entities) and a service/function which are chains of 1+ actions in the real world, waiting to be applied and then logged in the system.

[pwalsh]

@noamoss

I believe there is a difference between unit/departments (which are organizational entities) and a service/function which are chains of 1+ actions in the real world, waiting to be applied and then logged in the system.

Sure, there is nothing to disagree about there. But notice you say "service/function" - a service is a different entity altogether in GovFlow. In my understanding (using the current terms in GovFlow):

1. A Service is a classifier for a type of action (it is not the action itself)
2. A Department is an organizational unit under which (i) one or many action types (services) may be "performed", and (ii) one or many persons may have an association.

We discussed this week using a different term instead of Department because department has a specific meaning in local jurisdictions, and yet in GovFlow we might want to have Units that are not a 1:1 mapping to a department as understood by bodies that adopt GovFlow (currently: municipalities in the USA). Maybe Function is confusing too.

[noamoss]

@pwalsh

GovFlow we might want to have Units that are not a 1:1 mapping to a department as understood by bodies that adopt GovFlow (currently: municipalities in the USA)

... agreed, I believe Unit is a good term for a more abstract definition for a group of people (in the real world) in relation to an organization.

Maybe Function is confusing too.

let's try to clarify what do we talk about

A Service is a classifier for a type of action (it is not the action itself)
.
Can you elaborate on how do you perceive a ."type of action" is, and sharpen the difference from the action itself (function)?

[pwalsh]

@noamoss

let's try to clarify what do we talk about
Can you elaborate on how do you perceive a "type of action" is, and sharpen the difference from the action itself (function)?

We are based on 311, so you can see some examples of services here (The "Operation" section):

https://en.wikipedia.org/wiki/3-1-1

So, to take a nice example from there, "dead animal removal" is a service a jurisdiction (and more specifically, a jurisdiction via a department) performs, and refers to the "service type" that can be performed, and not the actual act (performance) of a person or machine going and removing a dead animal.

[noamoss]

@pwalsh

ok, so 3-1-1 "operation" (which you described as a "type of action" or "action classifier") holds the same meaning as "functionalities". We should choose a unified term, I am would go with either "operation" or "functionality" - just because they are the shorter ones and more accessible. for non-techy users.

Now, regarding the other part of "...the action itself", (or "the actual act (performance) of a person or a machine going and [doing stuff]...": will that be be represented in a separate instance? assuming the answer is yes, how would you name it?

[pwalsh]

@noamoss

ok, so 3-1-1 "operation" (which you described as a "type of action" or "action classifier") holds the same meaning as "functionalities". We should choose a unified term, I am would go with either "operation" or "functionality" - just because they are the shorter ones and more accessible. for non-techy users.

So, I just prefer to call it a "service" as it is now ( I just used the other terms in this disambiguation discussion :) ). I think service is the most appropriate term, and scales beyond 311, and, fits well with the idea of munis as "service delivery" organizations.

Now, regarding the other part of "...the action itself", (or "the actual act (performance) of a person or a machine going and [doing stuff]...": will that be be represented in a separate instance? assuming the answer is yes, how would you name it?

I don't think it is in our scope.

[noamoss]

@pwalsh

So, I just prefer to call it a "service" as it is now

and you are right, of course. agreed.

I don't think it is in our scope.

I am not sure it is, let's discuss (to verify I am not missing something)

[noamoss]

@pwalsh

The open 311 scheme also includes a service notice field:

Information about the action expected to fulfill the request or otherwise address the information reported.

Do we hold and/or use this field right now for service requests?

[pwalsh]

@noamoss you can add notes and information about our coverage of the Open 311 spec to this issue #4

[pwalsh]

merged in 8550b63