intake

README

CEDAR Intake API Client

This folder contains code for submitting data to the CEDAR Intake API for eventual storage in Alfabet. The Intake API is designed to take a JSON string in its Body field, as well as a schema identifier in its Schema field.

Swagger

The Swagger file for the Intake API is saved as cedar_intake.json in this folder. The Swagger we get from CEDAR needs preprocessing to add the "x-nullable": true property to the definition of the clientLastUpdatedDate field on the IntakeInput object. This is an optional field, but without the "x-nullable": true property, go-swagger will generate the corresponding Go code with a strfmt.DateTime field. If this type is used and .ClientLastUpdatedDate is not set in our Go code, the zero value of 0001-01-01T00:00:00.000Z will get sent to CEDAR Intake, which causes an error. With "x-nullable": true set, go-swagger generates Go code with a *strfmt.DateTime pointer field, and a nil pointer will prevent this field from being sent to CEDAR.

To run the preprocessing and regenerate code from an updated Swagger file, run scripts/generate_cedar_clients. This uses jq to add the "x-nullable": true field, then calls go-swagger to regenerate code.

See our general CEDAR documentation for info on accessing CEDAR and installing go-swagger for code generation.

Schemas

The CEDAR team needs a schema of the data we send them in order to decode it for storage in Alfabet. We have a script in cmd/gen_intake_schema/main.go, which uses the jsonschema package to generate JSON schema documents describing the possible payloads. This script gets called as a pre-commit hook if any relevant file is changed, in order to make sure the schemas are up-to-date.

Package Structure

• pkg/cedar/intake/gen/: This is auto-generated code from the Intake API's Swagger file. Of note is the IntakeInput type, which will be used by the API client to submit data.
• pkg/cedar/intake/models/: These struct definitions are the source of truth for generating the schema documents.
• pkg/cedar/intake/schemas/: These are the generated JSON schema documents used by the CEDAR team for validating the data we send.
• pkg/cedar/intake/translation/: Each file in this package corresponds to a file in pkg/cedar/intake/models, and contains code for the following:
  1. Translating a domain model (defined under pkg/models) into the type defined in pkg/cedar/intake/models.
  2. Marshaling that struct into a JSON string, then embedding it in an IntakeInput struct, tagged with the appropriate schema version.
• pkg/cedar/intake/client.go: A wrapper around the autogenerated client code from the Intake API Swagger, which has public methods for publishing different types of objects to the Intake API.

Manual Testing

cmd/test_cedar_intake/main.go is a script that creates test data (based on the seed data used in cmd/devdata/*.go), which can be used either for examining our translation of data locally or for testing pushing data over to CEDAR Intake, depending on whether the dump or submit subcommand is used.

• go run cmd/test_cedar_intake/main.go dump will create JSON files for test business case, GRT feedback, and system intake data inside the cmd/test_cedar_intake/ directory. These are examples of the payloads that will be marshaled and sent to CEDAR.
• go run cmd/test_cedar_intake/main.go submit will call our Intake client to send data to CEDAR. It requires that CEDAR_INTAKE_ENABLED, CEDAR_API_URL, and CEDAR_API_KEY environment variables to be set; these should be set in your .envrc.local, pointing to the CEDAR impl environment.

Checking whether CEDAR Intake received payload

The CEDAR Intake API has two endpoints that can be used together to verify that it received a payload we submitted, and what the payload was.

1. Use Postman to call GET /intake/status/client/{id}?clientStatus=Initiated&version=1, where id is the ClientID of the entity submitted (usually the ID of the top-level entity). If CEDAR received the payload, it will return an HTTP 200, and the body will contain a cedarId field. If it did not receive it, it will return an HTTP 400 with the error message "Intake could not be found with those parameters".
2. Use Postman to call GET /intake/cedar/{id}, where id is the value of the cedarId field from the previous response. The response should contain a body field containing the payload that was sent to CEDAR Intake.

Documentation

Overview

Package intake serves as an Anti-Corruption Layer (in Domain Driven Design parlance), keeping the implementation details of working with the downstream CEDAR Intake API well separated, so the rest of the internal workings of the EASi code are not using anything defined by the external API

Index

• type Client
  • func NewClient(cedarHost string, cedarAPIKey string, enabled bool) *Client
  • func (c *Client) CheckConnection(ctx context.Context) error
  • func (c *Client) PublishAction(ctx context.Context, action models.Action) error
  • func (c *Client) PublishBusinessCase(ctx context.Context, bc models.BusinessCaseWithCosts) error
  • func (c *Client) PublishNote(ctx context.Context, note models.SystemIntakeNote) error
  • func (c *Client) PublishSystemIntake(ctx context.Context, si models.SystemIntake) error

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client represents a connection to the CEDAR Intake API

func NewClient

func NewClient(cedarHost string, cedarAPIKey string, enabled bool) *Client

NewClient builds the type that holds a connection to the CEDAR Intake API

func (*Client) CheckConnection

func (c *Client) CheckConnection(ctx context.Context) error

CheckConnection hits the CEDAR Intake API `/healthcheck` endpoint to verify that our connection is functional

func (*Client) PublishAction

func (c *Client) PublishAction(ctx context.Context, action models.Action) error

PublishAction sends an action to CEDAR through the Intake API for eventual storage in Alfabet

func (*Client) PublishBusinessCase

func (c *Client) PublishBusinessCase(ctx context.Context, bc models.BusinessCaseWithCosts) error

PublishBusinessCase sends a business case to CEDAR through the Intake API for eventual storage in Alfabet

func (*Client) PublishNote

func (c *Client) PublishNote(ctx context.Context, note models.SystemIntakeNote) error

PublishNote sends a note to CEDAR through the Intake API for eventual storage in Alfabet

func (*Client) PublishSystemIntake

func (c *Client) PublishSystemIntake(ctx context.Context, si models.SystemIntake) error

PublishSystemIntake sends a system intake to CEDAR through the Intake API for eventual storage in Alfabet