/
Scripting Requirements & Best Practices for Library Staff

Scripting Requirements & Best Practices for Library Staff

Draft 20260127

Requirements

Credential Management

  • Credentials (API keys, tokens, passwords) must be stored in 1Password, the password manager supported by HUIT. See Getting Started with Password Managers in the IT Help Knowledge Base to learn more.

  • Individuals without HUIT affiliation may request a 1Password account from HUIT. See Set-up your 1Password Account to learn how.

  • Credentials must not be embedded in code, scripts, notebooks, documentation, or committed to version control.

  • Keys must not be shared. Each individual running a script must use their own credential.

  • Shared 1Password vaults (e.g., ITS) should be used only when operationally required; individual credentials are preferred.

Secure Execution Environment

  • Locally run scripts and associated configuration files (including .env) must reside on and be executed from a HUIT-managed machine. This requirement ensures current patching, software updates, and baseline security controls.

Configuration Handling

  • Sensitive values must be loaded from environment variables.

  • .env files must be excluded from version control and treated as sensitive artifacts.

  • Sample configuration files may be provided using placeholders only (e.g., .env.example).

Error Handling and Return Codes

  • Scripts must capture and evaluate return codes for external calls.

  • Non-success responses (e.g., 403, 404, 5xx) must be explicitly handled and logged.

  • Silent failures are not acceptable.

Logging and Output

  • Scripts must implement structured logging rather than relying solely on basic print statements.

  • DEBUG logging level should be used for deep analysis and troubleshooting. (not for standard production usage)

  • INFO logging level should be used for tracing high-level script activity. (for standard production usage)

  • Logs must clearly identify errors, unexpected responses, and execution outcomes.

  • Logs must not include credentials or other sensitive information.

Rate Limiting and Defensive Controls (where applicable)

  • Scripts interacting with external services (e.g., Alma & OCLC) must include pacing controls (sleep/delay).

  • Scripts should be designed to avoid triggering rate limiting or automated defensive blocks.

Code Management

  • Code should be version-controlled within Github.

  • Updates to the code should be reviewed and approved by one or more peers.

  • Code repositories must include a README explaining:

    • Setup steps

    • Required environment variables

    • How to run the script

    • How to interpret logs and errors

  • Code should include unit tests.

A.I. Usage

A.I. has become increasingly effective at generating software that approaches production-grade. With detailed specifications and clear guidelines, A.I. can be expected to produce software that incorporates modern approaches and frameworks for addressing many of the requirements listed above.

Harvard provides staff access to two tools that can be used for creating small scripting projects. These tools provide privacy and security protections for ensuring Harvard data is not used for training large language models. These tools can be used for up to Level 3 confidential data:

The following file may be used as a starting point or inspiration for directives to be provided to an A.I. along with specification guidance when generating code.


We don't have a way to export this macro.