Story

Description

[Describe from a user perspective what needs to happen.]

Acceptance Criteria

Given

• [steps to setup the world/scenario]

When

• [action taken by the user/api]

Then

• [list each assertions]

Acceptance Criteria

• reliably parse valid X12.5 formatted ISA & GS enveloping
• handle multiple GS envelopes within an ISA
• handle multiple ST transactions within a GS
• validate checksums and throw an exception for violations of checksums in
  • GE segment
  • IEA segment
• Ensure object model allows for intuitive data hierarchy access

Given an authentic user
and a successful external validation
When the user attempts to sign in
Then the user should be issued an encrypted JSON Web Token
and the user should be signed in
and the token expiration should be set to a reasonable time period
and the token should refresh itself if the user is still active

In order to access the system, a user must request an access role. This should be done through self-service and then approved through a chain of command in order to validate

• need to access the system
• the appropriate level of access has been requested
• user identification information
• valid/current security training/clearance

An example of this process and one that needs to be supported is the Department of Defense Form DD-2875; however, this form is specific to the Defense Department and should not be directly implemented as other agencies have their own processes which should be honored.

Regardless of specific artifacts, the system should

• gather information from authoritative sources (CAC/PIV)
• support customized workflow
• produce necessary artifacts
• ensure that appropriate timeout/re-certification of need are honored
• be tied to RBAC authorizations
• enforce basic separation of duties (tied to RBAC authorizations)
• obfuscate identifying information about users and ensure that no single penetration can tie a user's identity to their transactions

The government must pay for good and services! To do that it needs to reference funds. Since entitlement systems are never financial systems of record, it is necessary to identify both that system and the identifier used by it for the funds.

Funds detail must also be captured for treasury reporting and payment requirements.

In contracting, funds are often given an alias which must be tracked, however, one funding line can be tied to many contracts.

Contracts often reference other documents these could include but not be limited to

• statements of work
• technical manuals
• requisitions

References of these documents must be tracked

Story

Description

As a development team building a Single Page Application (SPA), automated tests must be able to invoke JavaScript to test the display of information and functionality of the application.

Acceptance Criteria

Given

• An agreement's basic information

When

• the user navigates to /agreements/:id

Then

The agreement's

• order identifier
• release identifier (if present)
• total value
• effective date

should be displayed for the user.

Agreements and contracts are subject to terms and conditions, some of which span the entire agreement. Items such as Free-on-base point and remediation requirements can and should be defined.

The government adds to these terms and conditions by adding entire regulatory doctrines which can be referenced. Since these change the behavior of the business functionality of the agreement through its lifecycle, they are called out separately and tracked.

In the US Federal government, the Federal Acquisition Regulation (FAR) section 52 is dedicated to such restrictions (referred to as clauses).

The Department of Defense extends the FAR with the Defense Federal Acquisition Regulation Supplement (DFARS) where section 252 adds additional clauses and then adds Procedures Guidance and Information (PGIs) that can further modify behavior. Each branch and command of the armed forces then adds to these.

Since these regulations are common across services and include analogs in non-DoD agencies (e.g., the US General Services Administration (GSA) Acquisition Manual (GSAM) includes parts

• 512
• 529
• 536
• 541.5
• 546.3
• 552.1
• 552.2
• 552.3
• 570.07

All of which define these behaviors.

These must be tracked with respect to their

• source/origin
• detail/reference

• Integrate with Travis-CI
• Report build status
• Enforce PR check on merge to master branch

Story

Description

As a user with a role assigned to a party, I need my display to have ready access to impacted agreements. Since my office may be the buyer for some agreements and the accepter/inspector for others, it is critical to me to be able to see only the agreements where my role is relevant.

Acceptance Criteria

Given

• Several Agreements
• And a role
• And a party

When

• A role is assigned
  • on each agreement
  • for a party

Then

• the party should be able to access all agreements
  • where it plays a specific role
  • as well as where it plays any role

Acceptance Criteria:

• Provide a file-based mock of fake data for an agreement

Bonus points for being able to generate fake X12 data on the fly!

As an intent owner, filing out stories without a template is slow and inefficient.

Acceptance Criteria:

• Given an intent element
• When an intent owner opens an issue
• Then the template should guide their input
  • and ensure that acceptances are present
  • and epics are easily linked

Background

The post-award tool does not exist in a vacuum, nor is it reasonable to expect that at launch the system, any system will be in a place to use of post-awards own Open Source JSON based RESTful APIs. Therefore, the system must be capable of parsing incoming data into these formats reliably and bubbling up errors in usable states.

Should Support

It is a known state that B2B and some B2C transactions are transmitted by ANSI ASC X12 in the United States and UN UNESCO EDIFACT throughout Europe and the eastern hemisphere.

While numerous proprietary standards have been created over time including XML/SOAP, iDOC, fixed width text, TRADACOM or JSON, the post-award API will process known standards into the post-award open source API.

Acceptance Criteria

• external formatted data can be accepted by the application
• the parser can bubble up errors in parsing/processing
• the parser can support X12 850003050 and X12 850004010
• the parser can be packaged as a composer package
• the composer package can be autoloaded by Laravel 5.5 dependency discoverer

• Build an organization for FACET-Acq usage
• Establish setup for the Laravel post-award repostitory

Note that this epic relates only to practices identifying that the end client (user/system) is whom it claims to be, not whether it may or may not take an action. This is the difference between authentication (the former) and authorization (the latter).

As a business critical function, the system must be able to reliably determine that a calling client is whom they claim to be. The authentication method must

• appeal to a source of authority, which no FACET-Acq system is regarding individual or system identity
• provide revokability to compromised or access-terminated identities
• stateless
• secure
• non-intrusive

Given a user with a valid CAC or PIV certificate
When the user attempts to sign in
Then the user's PKI certificate should be used to authenticate the user
and the official CRL (certificate revocation list) should be checked
and the user's status within the business's directory server should be checked

Note, take a look into PKI JS as a possible support library for this. Classically this issue has been exceedingly difficult to reliably implement due to restrictions on server configuration. If this can be handled in a contained manner in the front end securely by digitally signing a session bound/CSRF protected challenge using PKI, that would be preferable rather than binding implementations to a single department or agency's current practice.

Acceptance Criteria:

• Given a contribution
• When a pull request is made
• Then the PR should link to the issue(s) it helps solve
  • and help tell the story
  • and describe the approach
  • and describe lessons learned

As an application user, regardless of my workflow needs, I eventually require the ability to review the agreement data on file. This could be the validation of the incoming information, research, or another job function, but the system needs to display the stateful representation of the agreement and all of its detail.

Technically, this should be conducted through RESTful APIs, and displayed through a Single Page Application (SPA).

At their core, agreements procure goods and services.

For each agreement, we need to track any number of goods/services purchased in several attribtues

• quantity procured
• cost per unit
• units to calculate
• funded by
• item specific terms
• schedule/delivery data

All actions taken upon an agreement or provided to the post-award management system must be tied to a role.

Many users may be assigned to a role and batch actions from external systems (within and outside of FACET-Acq) must also be assigned to a role. The key point here is that user actions and system actions are identical in effect and should be indistinguishable from each other outside of security activity logging.

Roles for the system should be based on major system functions and must implement the least-privilege principle.

A note on separation of duties

It is key to separate business processes from the actual separation of duties requirements for roles.

While a business process may dictate additional oversight (approvals from a new role) for entitlements of a specified threshold, this is not core functionality to the system and these requirements can change drastically over time. Therefore they should be handled as additional packages or external services to maintain core usability and maintainability while still providing enforcement of business need. These sorts of requirements are best run through segregated code maintained outside of the application itself.

Conversely, a role capable of adding new vendors to the approved seller list or of changing payment account information related to a seller must not be concurrently held with the ability to entitle invoices for vendors as this is a true separation of duties need for the system. These are based in system and accounting best practices, for an example, see this matrix from Vanderbilt University's School of Finance

All agreements share commonalities. These include

• identification information
• involved parties (e.g., a purchaser and seller)
• funding
• related documents
• terms/conditions
• goods/services

Post-award must track agreements maintaining state.

Story

Description

As a developer, the goal is to take advantage of the features offered by Laravel's Eloquent Active Record system. Simultaneously, we need to take advantage of UUID. In the current state, any model created by the factory or manually does not integrate with simple eloquent commands like static::find.

Acceptance Criteria

Given

• A model leveraging UUIDv4

When

• the model is searched with static::find()

Then

• the single match record must be returned

Many parties can be involved in a transaction, but it takes at least two

• buyer
• seller

Others may include

• fob point
• billing party
• administration office
• paying office

or others

• PSR-2 convention for PHP
• Unix style line endings
• Space indentation
  • 4 spaces for PHP
  • 2 spaces for javascript/vue files
• Markdown files

Acceptance Criteria:

• reliably parse valid IC formatted X12 for 850 transactions set for x12 versions
  • 003050
  • 004010
• validate grammar requirements for syntax in incoming transactions and throw an exception on violations
• provide an intuitive and meaningful object interaction interface

See the bots-edi GitHub project (Apache2 Licensed) for delineations of usage requirements and segment composition of functional transaction sets.