Survey post successful week payment

[maxceem]

Context

Project Context

TaaS (Talent as a Service) is Topcoder project which let customers to hire top freelancers for gigs and directly manage the talents.

Challenge Context

In TaaS we have members (ResourceBookings) who are assigned to the customer's Jobs for some period of time. This time is divided into weeks (WorkPeriods) and payments to the ResourceBookings (members) is processed weekly. When the WorkPeriod is fully paid we would like to send a survey to the ResourceBooking to get the feedback about completed week.

Expected Outcome

Send weekly surveys for all completed WorkPeriods in batches.

Challenge Details

Technology Stack

• Node.js
• PostgreSQL
• SurveyMonkey API

Code access

The work in this challenge would be done in the next repositories:

• https://github.com/topcoder-platform/taas-apis branch feature/weekly-surveys
• https://github.com/topcoder-platform/taas-es-processor branch feature/weekly-surveys

Environment variables necessary to run this service would be shared on the forum.

Individual requirements

Update Models

• Add field "sendWeeklySurvey" to the model "ResourceBooking" - boolean, required, "true" by default - this field would indicate whether we should send weekly survey to this ResourceBooking or no.
• Add field "sentSurvey" to the model "WorkPeriod" - boolean, required, "false" by default - this field would indicate whether we've already sent a survey for this WorkPeriod of no.
• Add field "sentSurveyError" to the model "WorkPeriod" - json(b), optional - it should store the error details if error happened during sending survey in JSON(B) format: { errorCode: XXX, errorMessage: "..." }

Send Surveys

We want to send surveys to the "WorkPeriods" when "WorkPeriod.paymentStatus" becomes "completed". But SurveyMonkey only allows us sending 500 requests per day. If we send survey individually for each WorkPeriod we would exceed this limit very quickly. To overcome this we would like to send surveys in batches for each week. We already implemented this logic in other Topcoder Service and the here is a pseudo-code of the logic. It's very detailed and almost fully solves this task.

General logic:

• once per day get all the WorkPeriods where "paymentStatus == completed" and "sentSurvey == false" and "sentSurveyError == null" and "ResourceBooking.sendWeeklySurvey == true" (we already have "node-schedule" library which could be used to run code by schedule)
• send surveys for them, see method "sendSurvey" in the pseudo-code
• if error happens, then save error details into "sentSurveyError" for each failed WorkPeriod. Include server error message from SurveyMonkey if error happened during API request.

Minimize SurveyMonkey API calls

Provided pseudo-code logic already tries to minimize the number of SurveyMonkey API calls, but we should try to minimize it more if possible. For example, consider the following way:

• Instead of searching contacts one by one in upsertContactInSurveyMonkey search for all the needed contacts at once using /contacts/bulk
• After that create not existent contacts at once using the same bulk endpoint.
• Make sure to retrieve all the pages and respect bulk limits if any.
• You may also cache some data in-memory like this to avoid duplicate API calls if it helps. No need to over-engineer and create complex cache, simple in-memory cache should be fine as long as we don't store a huge data there.

If there are any other ways to reduce the number of calls, please do it. So after all the optimizations I guess per day we usually would make only 6 calls:

• create collector for each week (usually we would process only for 1-2 weeks during 1 day) - 2 calls
• search all the contacts - 1 call
• create all the missing contacts - 1 call
• send surveys for each collector (would be 1-2 usually) - 2 calls

Verification Guide

• Create a verification guide with the specific steps to follow so that reviewers could verify sending surveys logic.
• Include steps on how to config SurveyMonkey for testing: create account, create master collector, master message, contact list and so on.

General requirements

• For debugging purposes, each time we call SurveyMonkey API, log the API URL we are calling and how many calls we already did per day. Can store this counter in-memory.
• Keep separately scheduler logic from the SurveyMonkey API logic, as we are planning to replace SurveyMonkey with something else.
• As we changed the models:
  • Create a DB migration script inside "migrations" folder which would make any necessary updates to the DB schema.
  • Test, that when we migrate DB from the previous state using "npm run migrate", we get exactly the same DB schema as if we create DB from scratch using command "npm run init-db force".
  • Update mapping definitions for ElasticSearch indexes inside both repositories taas-apis and taas-es-processor.
  • Update taas-es-processor to support these fields.
  • Update Swagger and Postman if needed.
  • Update demo-data so "npm run data:import" and "npm run local:init" work good.
• Follow the existent code structure.
• Split code into reusable methods where applicable.
• Existent unit tests should pass.
• Lint should pass.

Scorecard Aid

The major requirements are:

• surveys should be sent as per description only once per WorkPeriod
• the number of SurveyMonkey API calls should be as minimal as possible (It doesn't matter if it's 5 or 10, but it should not linearly depend on how many WorkPeriods or Users we send survey to. If we send survey for 100 user and we have to make 100 calls - it's not a good approach)
• Verification Guide is also a major requirement in this challenge

Other requirements could be treated as per scorecard.

What To Submit

• Submit a zip file which would include:
  • a Git patch with changes you’ve made to the code in our repository.
  • Verification Guide in any text format
• Additionally, the winner would be required to raise a pull request to the repository after the challenge is completed.

[maxceem]

Pseudo code of how sending survey could work

/**
 * This code uses several environment variables
 *
 * SURVEY_CONTACT_GROUP_ID - the ID of contacts list which would be used to store all the contacts,
 *                            see https://developer.surveymonkey.com/api/v3/#contact_lists-id
 * SURVEY_MASTER_COLLECTOR_ID - the ID of master collector - this collector should be created manually,
 *                              and all other collectors would be created by copying this master collector.
 *                              This is needed so we can make some config inside master collector which would
 *                              be applied to all collectors.
 * SURVEY_MASTER_MESSAGE_ID - the ID of master message - similar to collector, this message would be created manually
 *                            and then script would create copies of this message to use the same config.
 */


/**
 * Check if the Contact already exists in Survey Monkey, if not
 * add to the Group
 */
 function upsertContactInSurveyMonkey(handle, email) {
  contactId = searchContact(handle, email);
  if (contactId) {
      return contactId;
  }
  return addContactToList(handle, email);
}

/**
 * Add Contact Email to List for sending a survey
 */
function addContactToList(handle, email) {
  response = http.post(BASE_URL + '/contact_lists/' + SURVEY_CONTACT_GROUP_ID + '/contacts', {
    first_name: handle,
    email
  });

  return response.id;
}

/**
 * Search contact by email
 */
function searchContact(handle, email) {
    response = http.get(BASE_URL + '/contacts?search_by=email&search=' + EncodingUtil.urlEncode(email, 'UTF-8'));
    return getSingleItem(response.data, 'More than 1 Survey Contact record found with email ' + email)
}

/*
 * Collector Logic
 */
function searchCollector(collectorName) {
  response = http.get(BASE_URL + '/surveys/' + SURVER_ID + '/collectors', {'name': collectorName});

  return getSingleItem(response.data, 'More than 1 collector found by name ' + collectorName)
}

function createCollector(collectorName) {
  collectorID = searchCollector(collectorName);
  if (collectorID) {
      return collectorID;
  }

  collectorID = cloneCollector();
  renameCollector(collectorID, collectorName);

  return collectorID;
}

function cloneCollector() {
  body = '{"from_collector_id":"' + this.SURVEY_MASTER_COLLECTOR_ID + '"}';
  response = http.post(BASE_URL + '/surveys/' + SURVER_ID + '/collectors', body);

  return response.id
}

function renameCollector(collectorId, name) {
  body = '{"name":"' + name + '"}';
  http.patch(BASE_URL + '/collectors/' + collectorId, body);
}

function addContactsToSurvey(collectorId, messageId, contactIds) {
  url = '/collectors/' + collectorId + '/messages/' + messageId + '/recipients/bulk';
  body = '{"contact_ids":' + contactIds + '}';

  http.post(BASE_URL +  url, body);
}

function sendSurveyAPI(collectorId, messageId) {
  url = '/collectors/' + collectorId + '/messages/' + messageId + '/send';
  http.post(BASE_URL +  url, '{}');
}

function createMessage(collectorId) {
  body = '{"from_collector_id":"' + this.SURVEY_MASTER_COLLECTOR_ID + '","from_message_id":"' + this.SURVEY_MASTER_MESSAGE_ID +'"}';
  response = http.post(BASE_URL + '/collectors/' + collectorId + '/messages', body);

  return response.id
}

function getSingleItem(lst, errorMessage) {
    if (lst.length == 0) {
      return null;
    }

    if (lst.length > 1) {
      throw new Error(errorMessage);
    }

    return lst[0].id;
}

function getCollectorName(dt) {
  return 'Week Ending ' + dt.format();
}

/**
 * This is the main method which would send a survey the ResourceBookings of the WorkPeriods.
 *
 * @param {Object} workPeriod work period to send a survey for
 */
function sendSurvey(workPeriods) {
  collectors = {}
  contactIds = {} // to cache contactId and avoid extra requests to SurveyMonkey API

  // for each WorkPeriod make sure to creat a collector (one per week)
  // so several WorkPeriods for the same week would be included into on collector
  // and gather contacts (members) from each WorkPeriods
  for (workPeriod of workPeriods) {
    collectorName = getCollectorName(workPeriod.endDate);

    // create collector and message for each week if not yet
    if (!collectors[collectorName]) {
      collectorId = createCollector(collectorName);
      messageId = createMessage(collectorId);
      collectors[collectorName] = {
        collectorId,
        messageId,
        contacts: []
      }
    }

    resourceBooking = workPeriod.getResourceBooking();
    if (!contactIds[resourceBooking.userId]) {
      user = helper.getUserById(resourceBooking.userId);
      contactId = upsertContactInSurveyMonkey(user.handle, user.email);
      contactIds[resourceBooking.userId] = contactId
    }

    collectors[collectorName].contacts.push(contactIds[resourceBooking.userId]);
  }

  // send surveys
  for (collectorName of collectors.keys()) {
    collector = collectors[collectorName]
    addContactsToSurvey(
      collector.collectorId,
      collector.messageId,
      collector.contacts
    );
    sendSurveyAPI(collector.collectorId, collector.messageId);
  }
}

[sandhiyakavi]

@maxceem For all the newly created WP, the 'sentSurvey' field of WP model is getting displayed as true by default ( status 'pending')

Ex: https://platform.topcoder-dev.com/taas/myteams/18160/rb/26616d88-5e53-445d-a7df-35fd595768ff

[sandhiyakavi]

Verified on Dev Env.

The Survey is sent to the resource whose "paymentStatus == completed" and "sentSurvey == false" and "sentSurveyError == null" and "ResourceBooking.sendWeeklySurvey == true"

Verified the Test cases in https://docs.google.com/spreadsheets/d/1pdyOKCmIbHK8mGmKyp3gcQ6Uc28SEulD/edit#gid=1938764403

[sandhiyakavi]

Working as expected in Prod.

cc: @maxceem @nkumar-topcoder