n8n-nodes-nookal

This is an n8n community node that provides integration with the Nookal practice management system via their GraphQL API using OAuth 2.0 client credentials flow.

Installation

Follow the installation guide in the n8n community nodes documentation.

Community Nodes (Recommended)

1. Go to Settings > Community Nodes
2. Select Install
3. Enter n8n-nodes-nookal in Enter npm package name
4. Agree to the risks of using community nodes
5. Select Install

After installation, the Nookal node will be available in your n8n instance.

Manual Installation

To install the node locally, you can use npm:

npm install n8n-nodes-nookal

For Docker installations, add the package to your n8n Docker image or use environment variables.

Prerequisites

Before using this node, you need:

1. Nookal Account: Access to a Nookal practice management system
2. API Credentials: Client ID and Client Secret from Nookal
   • Contact Nookal support or your system administrator to obtain these credentials
   • Ensure your account has the necessary API permissions

Configuration

1. Set up Credentials

1. In n8n, go to Credentials
2. Click Add Credential
3. Search for and select Nookal OAuth2 API
4. Fill in the required fields:
   • Client ID: Your Nookal-provided Client ID
   • Client Secret: Your Nookal-provided Client Secret
   • Scope: (Optional) Specific scopes if required by your Nookal setup
   • Authentication: Choose "Header" (recommended) or "Body"

2. Test the Connection

After saving your credentials, use the Test button to verify the connection to Nookal's API.

Supported Operations

Patient Operations

• Get: Retrieve a specific patient by ID
• Get All: Retrieve all patients (with pagination)
• Create: Create a new patient record
• Update: Update an existing patient record

Appointment Operations

• Get: Retrieve a specific appointment by ID
• Get All: Retrieve all appointments (with pagination)
• Create: Create a new appointment
• Update: Update an existing appointment
• Cancel: Cancel an appointment

Practitioner Operations

• Get: Retrieve a specific practitioner by ID
• Get All: Retrieve all practitioners (with pagination)

Location Operations

• Get: Retrieve a specific location by ID
• Get All: Retrieve all locations (with pagination)

Custom Query

• Execute: Run custom GraphQL queries against the Nookal API

Usage Examples

Example 1: Get All Patients

1. Add a Nookal node to your workflow
2. Select Patient as the resource
3. Select Get All as the operation
4. Set the limit (e.g., 50)
5. Configure your Nookal OAuth2 API credentials

Example 2: Create a New Patient

1. Add a Nookal node to your workflow
2. Select Patient as the resource
3. Select Create as the operation
4. Fill in the patient data:
   • First Name: "John"
   • Last Name: "Doe"
   • Email: "john.doe@example.com"
   • Phone: "+1234567890"
   • Date of Birth: "1990-01-01"
   • Gender: "MALE"

Example 3: Custom GraphQL Query

1. Add a Nookal node to your workflow
2. Select Custom Query as the resource
3. Select Execute as the operation
4. Enter your GraphQL query:

query GetPatientsWithAppointments {
  patients(first: 10) {
    edges {
      node {
        id
        firstName
        lastName
        email
        appointments(first: 5) {
          edges {
            node {
              id
              startTime
              endTime
              status
            }
          }
        }
      }
    }
  }
}

5. Add variables if needed (JSON format):

{
  "startDate": "2024-01-01",
  "endDate": "2024-12-31"
}

GraphQL Schema

The node is designed to work with Nookal's GraphQL API. Common fields include:

Patient Fields

• id: Unique identifier
• firstName: Patient's first name
• lastName: Patient's last name
• email: Email address
• phone: Phone number
• dateOfBirth: Date of birth
• gender: Gender (MALE, FEMALE, OTHER)
• address: Address information
• createdAt: Creation timestamp
• updatedAt: Last update timestamp

Appointment Fields

• id: Unique identifier
• startTime: Appointment start time
• endTime: Appointment end time
• type: Appointment type
• status: Appointment status
• notes: Appointment notes
• patient: Associated patient information
• practitioner: Associated practitioner information
• location: Associated location information

Error Handling

The node includes comprehensive error handling:

• Authentication Errors: Invalid credentials or expired tokens
• GraphQL Errors: Invalid queries or missing fields
• Network Errors: Connection issues or timeouts
• Validation Errors: Invalid input data

Errors are returned with descriptive messages to help with troubleshooting.

Rate Limiting

Be aware of Nookal's API rate limits. The node doesn't implement automatic rate limiting, so consider:

• Adding delays between requests in high-volume workflows
• Using pagination for large data sets
• Implementing retry logic for rate-limited requests

Troubleshooting

Common Issues

1. Authentication Failed

   • Verify your Client ID and Client Secret
   • Check that your Nookal account has API access
   • Ensure the credentials are saved correctly in n8n

2. GraphQL Errors

   • Verify your query syntax
   • Check that all required fields are included
   • Ensure you have permissions for the requested data

3. Connection Timeout

   • Check your network connectivity
   • Verify Nookal's API endpoint is accessible
   • Consider increasing timeout settings if needed

Getting Help

• Check the Nookal API documentation
• Review n8n's community nodes documentation
• Open an issue on the project's GitHub repository

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

Version 1.0.0

• Initial release
• Support for Patient, Appointment, Practitioner, and Location operations
• OAuth 2.0 client credentials authentication
• Custom GraphQL query support
• Comprehensive error handling

Support

For support with this community node:

1. Check the documentation above
2. Review the Nookal API documentation
3. Open an issue on GitHub
4. Contact the n8n community for general n8n questions