JiraFieldMaster

Project Overview

JiraFieldMaster is a full-stack web application designed to provide advanced management and configuration capabilities for Jira fields. It allows users to define custom field behaviours, create rules based on various Jira contexts (like project, issue type, or status), manage data sources, and synchronize these configurations with a connected Jira instance. This tool helps streamline Jira workflows and enforce specific field display and behaviour logic beyond what is natively available in Jira.

Key Features

• Field Behaviour Rules: Define and manage complex rules to control Jira field visibility, requiredness, and other behaviours based on project, issue type, status, or other triggers. Includes CRUD operations for these rules.
• Multi-Context Fields: Configure fields that can have different settings or behaviours across various Jira contexts.
• Data Source Management: Create and manage external data sources that can be referenced by field behaviour rules.
• JIRA Connection Management: Securely store and manage connection details (URL, email, API token) for one or more Jira instances, with the ability to set an active connection.
• JIRA Synchronization: Synchronize defined rules and configurations to your active Jira instance.
• JIRA Metadata Fetching: Fetches essential Jira metadata such as projects, issue types, and custom fields to provide context and selection options within the application.
• Application Logging: Comprehensive logging of application events, API calls, and JIRA synchronization activities for monitoring and troubleshooting.
• In-Memory Data Storage: Runs out-of-the-box with in-memory storage for quick setup and testing. Data is transient and lost on server restart in this mode.
• Persistent Storage Support: Includes (currently commented out) support for persistent data storage using NeonDB (a serverless PostgreSQL provider) via Drizzle ORM.

Tech Stack

Backend

• Runtime: Node.js
• Framework: Express.js
• Language: TypeScript
• Database (Persistence Option): NeonDB (Serverless PostgreSQL)
• ORM: Drizzle ORM
• Authentication: Passport.js (Note: User authentication setup might need review for full implementation details)
• Build: esbuild

Frontend

• Framework: React
• Build Tool/Dev Server: Vite
• Language: TypeScript
• Styling: Tailwind CSS
• UI Components: Radix UI (accessible component library)
• Data Fetching/State Management: React Query
• Routing: Wouter

Shared (Backend & Frontend)

• Data Validation: Zod

Development

• Server Live Reload: tsx

Prerequisites

Before you begin, ensure you have the following installed on your system:

• Node.js: This project uses Node.js for both the backend and frontend development tooling. We recommend using the latest LTS (Long Term Support) version. You can download it from nodejs.org.
• npm (Node Package Manager): npm is included with Node.js. It's used to manage project dependencies.

Setup and Installation

1. Clone the Repository:

   git clone <repository-url> # Replace with the actual repository URL
   cd JiraFieldMaster # Or your repository's directory name

2. Install Dependencies: Install the necessary Node.js packages for both the server and client.

   npm install

3. Environment Variables (.env file): The application uses a .env file in the project root to manage environment-specific variables.

   • Default Operation (In-Memory Storage): By default, the application runs with an in-memory database. This means no .env file or DATABASE_URL is strictly required to start the application for basic testing. However, all data will be lost when the server restarts.

   • For Database Migrations & Persistent Storage (Optional): If you want to use Drizzle ORM's schema migration tools (e.g., npm run db:push) or enable persistent data storage (which requires code changes in server/db.ts), you'll need to set up a PostgreSQL database (like NeonDB) and provide its connection string.

     1. Create a file named .env in the root of the project.
     2. Add your PostgreSQL connection string to it:

        DATABASE_URL="your_postgresql_connection_string_here"

        (e.g., DATABASE_URL="postgresql://user:password@host:port/database?sslmode=require")

   • Important Note on .gitignore: The .env file typically contains sensitive credentials. It is highly recommended to add .env to your .gitignore file to prevent committing it to version control if it's not already listed. If your .gitignore does not include .env, you can add it by running:

     echo ".env" >> .gitignore 

     (This command appends .env to your .gitignore file.)

Running the Application

1. Development Mode

This mode is recommended for local development and testing. It uses in-memory storage by default (data is not saved permanently) and enables hot-reloading for both frontend and backend changes.

npm run dev

• The backend server will typically start on http://localhost:5000.
• The Vite development server will manage the React frontend, usually accessible through the same port due to proxying, or on a separate port shown in the console output.
• Changes to client or server code should automatically reload the application.

2. Database Schema Management (Optional - for Persistent Storage)

If you have configured your .env file with a DATABASE_URL and intend to use a persistent PostgreSQL database (requires uncommenting relevant code in server/db.ts as detailed in the "Note on Data Persistence" section):

• Apply Schema Migrations: This command pushes the defined Drizzle ORM schema to your database.

  npm run db:push

  Ensure your database server is running and accessible.

3. Production Mode

This mode builds optimized versions of the frontend and backend for deployment.

1. Build the Application:

   npm run build

   This command will:

   • Build the React client using Vite.
   • Build the Express server using esbuild, outputting to the dist/ directory.

2. Start the Production Server:

   npm run start

   • This starts the Node.js server from the dist/ directory.
   • By default, this will still use in-memory storage unless you have modified server/db.ts to use a persistent database and have set the DATABASE_URL in your production environment.

Project Structure

A brief overview of key directories in the project:

• client/: Contains the frontend React application.
  • client/src/: Source files for the React app (components, pages, hooks, etc.).
• server/: Contains the backend Express.js application.
  • server/index.ts: Main entry point for the server.
  • server/routes.ts: Defines API routes.
  • server/storage.ts: Handles data storage logic (currently in-memory).
  • server/db.ts: Configures database connection (currently NeonDB parts are commented out).
  • server/jira-sync.ts: Logic for synchronizing rules with JIRA.
• shared/: Contains code shared between the client and server.
  • shared/schema.ts: Zod schemas for data validation and TypeScript types.
• migrations/: Stores database migration files generated by Drizzle Kit when using a persistent database.
• dist/: Output directory for production builds (generated by npm run build).

Basic Usage

Once the application is running, you can access the web interface (typically at http://localhost:5000 during development). Here's a general guide to using JiraFieldMaster:

1. Dashboard:

   • The application will likely open to a dashboard page (dashboard.tsx) providing an overview or quick access to various modules.

2. Connect to JIRA:

   • Navigate to the "API Connections" or "JIRA Connections" section (related to api-connections.tsx).
   • Here, you can add or manage your JIRA instance details:
     • JIRA URL (e.g., https://yourcompany.atlassian.net)
     • Your email address associated with the JIRA account.
     • An API Token generated from your JIRA account (refer to Atlassian documentation on how to create API tokens).
   • Set one connection as "active" to be used for fetching JIRA data and applying configurations.

3. Manage Configurations: The sidebar or navigation menu should allow you to access different modules:

   • Field Behaviours (field-behaviours.tsx):
     • Define and manage rules that control how fields behave in JIRA (e.g., making fields required, read-only, or changing their visibility based on certain conditions like project, issue type, or status).
   • Multi-Context Fields (multi-context-fields.tsx):
     • Configure fields that might have different definitions or options depending on the JIRA context.
   • Data Sources (data-sources.tsx):
     • Set up and manage external data sources that your field behaviour rules might need to reference.
   • Field Actions (field-actions.tsx):
     • This section likely deals with specific actions or operations that can be performed on or by fields, possibly as part of the rules.

4. Synchronization with JIRA:

   • After defining rules, they need to be synchronized with your JIRA instance. Look for options to "sync" or "apply" configurations, often associated with the rules themselves or a general settings area.
   • The application uses the active JIRA connection to communicate with your JIRA instance.

5. View Logs (logs.tsx):

   • Check the application logs to monitor activities, JIRA API call statuses, and troubleshoot any issues with synchronization or data fetching.

6. Documentation (documentation.tsx):

   • There appears to be a dedicated documentation page within the app itself, which should provide more detailed guidance.

This provides a high-level overview. For specific functionalities and detailed steps, refer to the in-app documentation page and explore the different modules.

Note on Data Persistence

By default, JiraFieldMaster runs with in-memory storage (server/storage.ts). This is convenient for quick setup and testing, as it doesn't require any external database configuration. However, all data entered into the application will be lost when the server restarts.

To enable persistent data storage using a PostgreSQL database (like NeonDB, for which Drizzle ORM is configured):

1. Set up a PostgreSQL Database:

   • Ensure you have a PostgreSQL database instance running and accessible. You can use a cloud provider like Neon (neon.tech) which offers serverless PostgreSQL, or any other PostgreSQL provider.

2. Configure Environment Variable:

   • Create or update your .env file in the project root with the connection string for your database:

     DATABASE_URL="your_postgresql_connection_string_here"

3. Modify Server Database Configuration (server/db.ts):

   • Open the server/db.ts file.
   • You will need to comment out the in-memory storage parts and uncomment the sections related to NeonDB/PostgreSQL connection.
   • Specifically:
     • Comment out or remove export const db = null;
     • Uncomment the neonConfig.webSocketConstructor = ws; line if you are using NeonDB (it's often needed for serverless connections).
     • Uncomment the DATABASE_URL check:

       // if (!process.env.DATABASE_URL) {
       //   throw new Error(
       //     "DATABASE_URL must be set. Did you forget to provision a database?",
       //   );
       // }

     • Uncomment the pool creation and the db drizzle instance:

       // export const pool = new Pool({ connectionString: process.env.DATABASE_URL });
       // export const db = drizzle({ client: pool, schema });

   • Developer Note: The current storage.ts directly exports an instance of MemStorage. To use the persistent db instance from db.ts, storage.ts would need to be refactored. This might involve changing storage.ts to export a class that accepts the Drizzle db instance, or modifying routes.ts and other consumers to instantiate a database-backed storage class instead of using the exported MemStorage instance. This refactoring is beyond the scope of simply uncommenting lines in db.ts.

4. Apply Database Migrations:

   • Once your DATABASE_URL is set and you've prepared your application code (including the necessary refactoring mentioned above) to use the database, run the Drizzle Kit command to push the schema to your database:

     npm run db:push

After these steps (including the necessary code adjustments for storage.ts), the application would use your PostgreSQL database for data storage, and your data would persist across server restarts.

Contributing

Contributions are welcome! If you'd like to improve JiraFieldMaster or fix any issues, please follow these general steps:

1. Fork the Repository: Create your own fork of the project on your Git hosting provider.

2. Create a Feature Branch:

   git checkout -b feature/your-amazing-feature

   Or for bug fixes:

   git checkout -b fix/issue-description

3. Make Your Changes: Implement your feature or bug fix. Ensure your code follows the project's general style and conventions.

4. Check Code Quality: Before committing, run any available linting or type-checking scripts:

   npm run check 

   (This script is defined in package.json and typically runs tsc for TypeScript checks).

5. Commit Your Changes: Use clear and descriptive commit messages.

   git commit -m "feat: Add support for X feature" -m "Detailed description of changes..."

6. Push to Your Branch:

   git push origin feature/your-amazing-feature

7. Submit a Pull Request (PR): Open a Pull Request from your forked repository's branch to the main branch of the original JiraFieldMaster repository.

   • Provide a clear title and description for your PR, explaining the changes and why they are being made.
   • Reference any related issues.

We'll review your PR as soon as possible. Thank you for contributing!