Scope Change Workflow

[vikasrohit]

Updated requirements:

Objective

Once a project is started, scope change can occur at several points of delivery, including:

• Customer/team wants to repurchase a solution (Ex. 1 RUX was performed, another RUX on the same app is desired)
• Customer wants to add a new phase (i.e. a new workstream) of work (Ex. We sold them design, but now they also want us to do the development)
• Customer wants to add an additional add-on(s) to an already planned workstream
• Customer wants to modify the "size" (# of screens, # of devices) of the existing scope of work

High-Level Requirements:

A change in scope should result in three changes to the project.
Scope Card: The rendered summary scope document needs to be updated to reflect the changes to deliverables, cost and timeline to the customer.
Community Work Budget: The available project total community work budget, as well as the associated workstream budget estimate, needs to update for Topcoder to accurately track the new available budget they have.
Workstreams: Based upon the selection either a new workstream will need to be added if a new deliverable is included, OR an existing workstream needs to have its summary duration updated if an add-on or change in size modifies the existing workstream(s)
Send to SFDC/Retrieve data from SFDC: We need to send the change to SFDC and align it to the customer's billing account for this project, so that the Account Executive can complete the sale.

Workflow:

Increasing Project Scope

• Both customer and Topcoder should be able to increase the scope of the project, by:
  • Repurchasing an already completed solution (Ex. 1 RUX was completed on a project, but customer wants another RUX for the same app)
  • Adding an additional phase of work (Ex. Going from just design, to design + dev & QA)
  • Including additional add-ons within the scope of an existing phase
  • Increasing the "size" of the existing project (Ex. Increasing number of screens or devices required)
• If a Topcoder user has modified the scope of the project, the a customer user on the project must approve this change. If the customer user initiated the scope change, this step is not required.
• Once the scope change is "approved" from the customer-end, the change in project scope should be sent to SFDC in association with the customer’s billing account and project ID. If there is an Account Executive assigned to the customer billing account in SFDC, they should also receive an email alert that the scope of the project has increased so that they can follow-up with the customers immediately and close the sale.
• Once the sale is completed in SFDC (opportunity marked ‘won’), the changes to the project scope (cost for customer, community work budget, workstream durations) should be reflected.

Decreasing Project Scope

• Both customer and Topcoder should be able to increase the scope of the project, with restrictions to the following scenarios only:
  • If no work has been initiated (no challenges/tasks have started), the scope of the project can be decreased with no restrictions.
  • If the project has only one workstream and work has already begun (i.e. challenges/tasks have started), scope cannot be decreased.
  • If the project has multiple workstreams, the scope can be decreased only for workstreams that has had no work start yet.
• If a Topcoder user has modified the scope of the project, the a customer user on the project must approve this change. If the customer user initiated the scope change, this step is not required.
• Once the scope change is "approved" from the customer-end, the change in project scope should be sent to SFDC in association with the customer’s billing account and project ID. If there is an Account Executive assigned to the customer billing account in SFDC, they should also receive an email alert that the scope of the project has increased so that they can follow-up with the customers immediately and modify the project’s billing information.
• Once the sale is completed in SFDC (opportunity marked ‘won’), the changes to the project scope (cost for customer, community work budget, workstream durations) should be reflected.

[vikasrohit]

fyi @maxceem @RishiRajSahu we need to think about how to handle the approval of the customer for the scope change, apart from that I think it is only about sending proper notification to the stakeholders about the scope change. Let me know if I missed something here.

[maxceem]

@vikasrohit here are some thoughts which come to my mind:

1. If non-customer made some change and now such a change is waiting for account manager approval:

   1. what information should be shown:
      1. old information
      2. or changed but not approved yet?
   2. Or should we show the old and new information together but new information should be highlighted somehow that it's waiting for approval?

2. As I understand after we change the scope in one of three ways and requested account manager approval, the account manager has two choices: approve the change and reject the change.

   1. If the account manager approves changes, then changes are applied and become the current state of the project.
   2. If the account manager rejects changes, should we revert changes? Or should we just notify the person who made them that they are not approved and let that person adjust them and send another approval request or cancel them somehow?

3. We also should deal if several changes have been done by multiple users.

   1. If one non-customer user made some changes and requested approval and after before they were approved or rejected and made more changes, we can just add new changes to the first approval batch.
   2. If one non-customer user made some changes and after the anohter non-customer user made some changes. Should account manager review changes from these two users in one batch or in two separate batches?
   3. If the non-customer user made some changes and requested review and while changes were pending some customer user made some changes which are applied immediately without review there could be some conflict if after changes from non-customer user would be approved.

So far looks like quite a complex task, or do I overthinking and the idea is simpler?

[vikasrohit]

Thanks for the valuable thoughts @maxceem. These are valid queries, however, we might be able to simplify things by assuming certain things.

1. I think we need to keep the old state and proposed changes separately in our data model and let the product/design team to have best possible visual representation of the data.

2. For rejection use case, I guess we should be able to allow the requestor to amend the proposal and resend it until it is approved or the requestor decide to cancel.

3. I am thinking of allowing one pending scope change at a time for a project i.e. no user (event the customer) can adjust the scope until there is a pending scope change set. As additional feature, we might allow the requestor of the current pending scope change to append more changes in the same set, but I am not sure about this yet and need to discuss it with product team.

[maxceem]

Great that it helped.

Regarding 3. blocking others from editing scope while there is a pending change may be not comfortable and slow down the work in general - IMHO. So maybe we could think about some other ways around. Maybe most things we can let users edit anytime. For example for adding phases and add-ons, this should be ok.

4. By the way, can we only add scope, or also reduce? Like remove phases, add-ons and reduce screens?

[vikasrohit]

blocking others from editing scope while there is a pending change may be not comfortable and slow down the work in general - IMHO. So maybe we could think about some other ways around. Maybe most things we can let users edit anytime. For example for adding phases and add-ons, this should be ok.

Anything that can change the scope (price or time) of the project, should be atomic and I think we need to prevent any new change set while one is pending for approval.

By the way, can we only add scope, or also reduce? Like remove phases, add-ons and reduce screens?

Yes, scope can be reduced as well.

[vikasrohit]

@maxceem just updated the requirements with more details and rephrased for better understanding. For now, we don't have to worry about the sales process i.e. submitting scope change to the SFDC and then waiting for the approval are the things, we don't have in the scope for this task. We just need to support creating scope change request in pending status and then must have the ability (via API) to change it to approved status.

[vikasrohit]

My proposed solution:

1. New model/table ScopeChangeRequest(scope_change_requests(id, title, description, projectId, oldScope, newScope, status, approvedBy, approvedAt, createdBy, createdAt, updatedBy, updatedAt, deletedBy, deletedAt)). Need standard CRUD operations around this model as /projects/{id}/scopeChanges
2. Disable directly editing the scope questions via scope tab (we might not need this as we would show the Scope tab only for old projects which does not support new smart scopes) or the new scope drawer i.e. we should not make a PATCH request to the projects API for new smart forms on click of Save button. We also has to add backend validation as well to prevent updating the project scope directly via the API.
3. The only (for old forms we have multiple Save buttons one for each section) Save button on the scope which would trigger the scope change workflow.
4. On click of the Save button call the API endpoint to create new ScopeChangeRequest object, if there is no existing ScopeChangeRequest with pending or approved status for this project. If there is an existing such pending/approved scope change request, we should disable the Save button and add a tooltip stating the reason.
5. There would be some UI (TBD) which would show the pending or approved scope change requests and way to approve/reject (only if the status is pending) them for customers. For now, we can:
   • show a red cue on the collapsed project estimation component and show a simple text (e.g. Scope change is pending for approval. View Request.) where View Request would be a simple hyperlink
   • clicking on which the UI in the scope drawer updates itself to show the new suggested scope. Here we have the possibility of showing some kind of visual cue (using pristine flag of the formsy model) for the fields which are updated in the new scope.
   • there would a button, only for the customers, for approving the request on this UI clicking on which would mark the request in approved status.
6. We don't have to do any thing else in the workflow on moving a scope change request into approved status. This status means that the scope change request is approved by the customer, however, to actually take the scope change reflected in the project's scope, the request has to be activated(via API endpoint) by topcoder finance team. So, we would need API endpoint to accept the status change of the scope change request with appropriate authorizations.
7. When a scope change request is activated, we need to do followings:
   • Merge (or may be just override) the new scope JSON to the project
   • Evaluate the project's new scope for price and time estimation to deduce the building blocks of estimation
   • Create the pricing_estimations and pricing_estimation_items as per our standard logic which we are following at the time of project creation

@maxceem this is most probably not the exhaustive list of things that we need to do to achieve the requirements, its my best guess. So, please feel free to suggest completely different approach or any updates to this one.

[vikasrohit]

@vigneshTheDev assigned the issue to you and I have committed POC changes in https://github.com/appirio-tech/connect-app/tree/feature/scope_change_workflow and https://github.com/topcoder-platform/tc-project-service/tree/feature/scope_change_workflow branches. I have added many TODOs in the new code that I have written for this feature, so those are the definitely first thing to start with for us. Apart from that few of the major tasks are as follows:

• Backend: Initially when I designed the model, I thought of saving the complete value of the details JSON object before and after the scope change request and then determining the difference between them at runtime when we need to show the differences. However, after implementing the flow, I realized that it might be easy to have oldScope field as is for ScopeChangeRequest while instead of newScope we can store the changes only i.e. we can rename the field to scopeChange or simply change and assume that it would only store the changes in the oldScope data
• Backend: LIST endpoint for ScopeChangeRequest is not needed as of now as we don't yet have the use case where we need to list all scope change requests. This task requires no action as we haven't implemented PATCH endpoint yet, it is just for tracking purposes.
• Backend: PATCH endpoint for ScopeChangeRequest model should not allow updating oldScope and scopeChange/change fields. One has to cancel/activate the current pending request to change the scope change request's changes.
• Backend: Unit tests for all implemented endpoints
• Frontend: We need to create a new component for rendering a scope change request. As of now, I have just rendered the title of the scope change in SpecificationContainer component, which should be replaced with this component. The component would render the scope changes as one field in each line. e.g. if scopeChange JSON object of the current pending scope change request is { "details": { "appDefinition" : { "numberOfScreens" : "5-8", "targetDevices" : "phone" } } }, the component should render

  Number of screens changed to '5-8' from '2-4'
  Target devices changed to 'phone' from 'tablet'
  

Now as you would have noticed that I have used Number of screens as text for numberOfScreens field. To get this human readable text for a field, we have to lookup in the template by full field name (e.g. in this case details.appDefinition.numberOfScreens would match with a question the template) and use the found question's summaryTitle or title (based on availability).

I would keep adding more tasks here.

[vigneshTheDev]

@vikasrohit, Thanks for assigning the task. I'll look into it and get back to you.

[vikasrohit]

@vigneshTheDev Let me know your understanding about the requirements and any questions you have before starting with actual work. Also, let me know if you understand the POC code, I have pushed to the mentioned branches. It would be great if you can provide me estimate of efforts and prize you see for both frontend and backend to achieve the requirements.