Outline typical organization workflows for VPATs for both vendors & clients

[mgifford]

Would be useful to know more about both how VPATs are typically generated and how they are consumed.

I assume it is basically like

Client

• A contracting officer receives the VPAT
• Sends it to both the 508 SME
• Accessibility review done of the VPAT, then returned to the contracting officer with a pass/fail

Vendor

• Receives a RFP that requires a VPAT
• Either develops a VPAT internally with the accessibility team or contracts out responsibility
• Stores that document for future use by sales
• Contract submitted with the VPAT

Understanding the process better may help to improve it.

[brennanyoung]

I have chief responsibility for accessibility in a firm which is focused on e-learning software. We are developing a culture of making "internal VPATs". The audience for these is our own project managers and product owners. This has already proved to be a valuable strategic tool, so that planning and project estimation can be based on informed decisions. This is especially important when we have known WCAG violations that can't be fixed in a single cycle (because of our platform orientation and architecture).

Also when 3rd party audits are performed I can compare my own internal assessments with the 3rd party one, and calibrate my own auditing skills (which are improving all the time).

We have also experimented with generating these internal VPATs from Jira boards, with some success, although this has not yet become a routine. We added a WCAG field to our Jira boards, so that issue can be tagged with the most relevant success criteria. The WCAG popup on each card includes all the level A and AA SCs from WCAG 2.1, plus the additional entries "None" (default), "Triage" and "No SC". Generating the VPAT requires a query which pulls out all issues where the WCAG value is not none, and then we have a script which populates the generated document with reference to any open Jira tasks.

I'd be very interested to see integration with Jira and other popular bugtracking software on the radar for the OPAT effort.

[mgifford]

This is great. We do know that others are interested in doing something very similar with pulling bugs from JIRA or other issue tracking tools like GitHub. I'm curious to learn more about how you are organizing your WCAG popup. Also, would like to learn more about this script you've developed @brennanyoung to pull together the open JIRA tasks.

Having this live information at your fingertips can be very helpful to drive sprints forward in a way that helps make measurable improvements in accessibility. Thanks @brennanyoung

[brennanyoung]

I didn't create the Jira WCAG field myself, but I know it's something called a "custom field". I might be able to get hold of the relevant details and artifacts from our Jira admin guys. It's just a popup (single-select) field.

We run the script from node. The script create an object called VPG which sets up the fields we expect to fill, and then we access the board via Jira's REST API, pulling out each issue, and pushing it into an array for each success criterion. If an array is empty at the end, we assume that we comply with that SC. (Not bulletproof, but acceptable if the test regime is in place).

Here's a snippet of the script prototype which handles the results from the Jira REST POST request. This is still quite primitive, where stuff like dates and names are hardcoded, because it's just a proof of concept but you can get the basic idea. The actual generation happens in the object referred to as VPG, the vpat generator, which contains a flat 'database' of WCAG SC identifiers, and a bunch of HTML boilerplate and templating procedures. I can share this too, if necessary, but there are zillions of HTML templating solutions out there, and I imagine many may prefer to output to .docx or .pdf or some such, so it's a bit of a side issue.

/*
REST API docs at https://developer.atlassian.com/server/jira/platform/rest-apis/
*/
var fs = require('fs');
var Client = require('node-rest-client').Client;
var VPG = require('./WCAG21.js').VPATgen;
const jiraRoot = "https://HIDDEN.com/jira/"; // URL of Jira instance
const wcagField = "customfield_1234" // custom field in our Jira board for WCAG SCs
const tripletPattern = /^\d\.\d\d?\.\d\d?/;
var restRoot = jiraRoot + "rest/";
var restAuthURI = restRoot + "auth/1/session";

client = new Client();

// Provide user credentials, which will be used to log in to JIRA.
var loginArgs = {
    data: {
        "username": "not_a_real_username",
        "password": "not_a_real_Password"
    },
    headers: {
        "Content-Type": "application/json"
    }
};
console.log("Request to " + jiraRoot);

// Make the request return the search results, passing the header information including the cookie.
	client.post(restRoot + "api/2/search", searchArgs, function(searchResult, response) {
		var decodedBuffer; // only used if we don't get a 200
	    if (response.statusCode !== 200) {
			console.log("Search result status", response.statusCode, response.statusMessage);
			var decodedBuffer = new Buffer(searchResult).toString('ascii');
            console.log('search result (decoded):', decodedBuffer);
			throw "REST search failed :(";
			return;
		}
		// now we have a meaningful result...
		console.dir(searchResult, {depth: null, colors: true})
		var issues = searchResult.issues;
		// set up the header data (hardcoded here, but shouldn't be)
		VPG.setProductName("Lifesaver Pro Deluxe");
		VPG.setProductVersion("1.2 RC 1");
		VPG.setProductDescription("e-learning software");
		VPG.setContactName("Joe Blow");
		VPG.setContactEmail("[email protected]");
		VPG.setVendorName("Acme Corp.");
		VPG.setVpatVersion("0.1");
		VPG.setDate("Spring 2021");

		// run thru the issues, and find which success criterion each one pertains to
		issues.forEach(function (issue) {
			var issueKey = issue.key;
			var fields = issue.fields;
			var wcagSC = fields[wcagField][0].value;
			var wcagSC_Triplet = wcagSC.match(tripletPattern)[0];
			var priority = "(" + fields["priority"].name + ")";
			console.log(issueKey, wcagSC, priority, wcagSC_Triplet);
			// tell the generator to include the issue		
			VPG.addIssue(wcagSC_Triplet, issueKey);			
		});

		// call the generator to convert its accumulated data into a VPAT
		var vpatMarkup = VPG.generateVPAT();

		var fileName = 'VPATGENERATED.HTML'; // not the best name
		var stream = fs.createWriteStream(fileName);
		stream.once('open', function(fd) {
  			stream.end(vpatMarkup);
  		});
  		console.log("HTML VPAT CREATED");
	});
});

[mgifford]

Thanks for sharing this @brennanyoung - I'm definitely interested in your VPAT Generator (VPG) tool. At this point we've got your YAML -> HTML document working, so wouldn't need that.

You can see the results with this Drupal example https://github.com/GSA/open-product-accessibility-template/tree/main/opat

Seeing how you run through the JIRA tickets by SC is interesting. It is useful to see examples of how this can be done like this.

How are you presently storing the references back to JIRA right now? Are those links then stored in a way that your product team can use to evaluate it?

How often are you generating reports? This could be so useful as an asset if you are evaluating progress between sprints.

Do you know anyone else who is developing "internal VPATs".

[brennanyoung]

Well, all this is proof of concept work, so I would say it's barely operational, and we can't talk about "how often" yet. I produce an internal VPAT manually whenever a project manager requests it.

Each WCAG violation is intended to appear in the VPAT as a hyperlink to the corresponding Jira issue. (Not implemented, but trivial).

"internal VPAT" is our own coinage. I don't know any other org that is doing this, but it seems like an obvious step for any org whose accessibility conformance effort matures beyond the early panic-and-chaos stage. We should probably change the nomenclature to "internal ACR" (it's not a template if it's been filled out!), but it arises from the fact that our partner organisations are connected with the US public sector, and we needed to produce documents which would make sense to them. We had tried - abortively - some other approaches to making an ACR, but they were always too tightly coupled to our own production idioms. Since we found out that our partners understand what a VPAT represents to customers, we just followed the template, and that has shown real clarity and value, with the side benefit of informing management about some of the WCAG landscape.

[mgifford]

This is really useful, thanks @brennanyoung