it-glue-organizations

name: "IT Glue Organizations" description: > Use this skill when working with IT Glue organizations (companies/clients) - creating, searching, updating, and managing client documentation. Covers organization types, statuses, parent/child relationships, PSA sync, quick notes, and related resources like configurations, contacts, and passwords. when_to_use: "When creating, searching, updating, and managing client documentation" triggers: - it glue organization - it glue company - client documentation - organization lookup - it glue client - organization management - it glue org - company documentation

IT Glue Organizations Management

Overview

Organizations are the foundational entity in IT Glue, representing companies, clients, vendors, or internal entities. All documentation, configurations, contacts, passwords, and flexible assets are associated with an organization. Proper organization management enables comprehensive client documentation and cross-platform integration with PSA tools.

Key Concepts

Organization Types

Organizations are classified by type for categorization:

Organization Statuses

Parent/Child Relationships

Organizations can have hierarchical relationships:

Parent Organization (Acme Holdings)
├── Child: Acme East Division
├── Child: Acme West Division
└── Child: Acme International

This enables:

• Centralized management documentation
• Shared configurations across divisions
• Hierarchical reporting
• Inherited security settings

Field Reference

Core Fields

Relationship Fields

PSA Integration Fields

Metadata Fields

API Patterns

List Organizations

GET /organizations
x-api-key: YOUR_API_KEY
Content-Type: application/vnd.api+json

With Filters:

GET /organizations?filter[name]=Acme&filter[organization-status-id]=1

With Pagination:

GET /organizations?page[size]=100&page[number]=1&sort=name

Get Single Organization

GET /organizations/123456
x-api-key: YOUR_API_KEY

With Includes:

GET /organizations/123456?include=configurations,contacts,passwords

Create Organization

POST /organizations
Content-Type: application/vnd.api+json
x-api-key: YOUR_API_KEY

{
  "data": {
    "type": "organizations",
    "attributes": {
      "name": "New Client Corporation",
      "description": "IT services client since 2024",
      "quick-notes": "Primary contact: John Smith (555-123-4567)",
      "organization-type-id": 37,
      "organization-status-id": 1
    }
  }
}

Update Organization

PATCH /organizations/123456
Content-Type: application/vnd.api+json
x-api-key: YOUR_API_KEY

{
  "data": {
    "type": "organizations",
    "attributes": {
      "quick-notes": "Updated: New primary contact is Jane Doe",
      "alert": "Contract renewal due March 2024"
    }
  }
}

Delete Organization

DELETE /organizations/123456
x-api-key: YOUR_API_KEY

Warning: Deleting an organization removes all associated resources (configurations, passwords, documents, etc.)

Search by PSA ID

GET /organizations?filter[psa-id]=12345

Common Workflows

New Client Onboarding

1. Create organization with basic info
2. Set organization type (Customer)
3. Add quick notes for reference
4. Link to PSA with psa-id
5. Create primary contact
6. Add initial configurations
7. Document passwords

async function onboardClient(clientData) {
  // Step 1: Create organization
  const org = await createOrganization({
    name: clientData.companyName,
    description: clientData.description,
    'quick-notes': clientData.notes,
    'organization-type-id': CUSTOMER_TYPE_ID,
    'organization-status-id': ACTIVE_STATUS_ID
  });

  // Step 2: Create primary contact
  await createContact(org.id, {
    name: clientData.primaryContact.name,
    email: clientData.primaryContact.email,
    phone: clientData.primaryContact.phone,
    'contact-type-id': PRIMARY_CONTACT_TYPE
  });

  // Step 3: Create initial documentation
  await createDocument(org.id, {
    name: 'Client Overview',
    content: generateOverviewContent(clientData)
  });

  return org;
}

Client Offboarding

1. Archive passwords (don't delete for audit)
2. Export documentation if needed
3. Update organization status to Archived
4. Add offboarding notes with date and reason

async function offboardClient(orgId, reason) {
  // Update status to archived
  await updateOrganization(orgId, {
    'organization-status-id': ARCHIVED_STATUS_ID,
    alert: `ARCHIVED: ${new Date().toISOString().split('T')[0]} - ${reason}`
  });

  // Add final note
  await addQuickNote(orgId, `
    Client offboarded on ${new Date().toLocaleDateString()}
    Reason: ${reason}
    Final contact: [Record contact name and handoff details]
  `);
}

PSA Sync Verification

async function verifyPsaSync() {
  // Get all active organizations
  const orgs = await fetchOrganizations({
    filter: { 'organization-status-id': ACTIVE_STATUS_ID }
  });

  const syncStatus = {
    synced: [],
    unsynced: [],
    mismatched: []
  };

  for (const org of orgs) {
    if (!org.attributes['psa-id']) {
      syncStatus.unsynced.push(org);
    } else {
      // Verify PSA record exists
      const psaCompany = await lookupPsaCompany(org.attributes['psa-id']);
      if (psaCompany) {
        syncStatus.synced.push(org);
      } else {
        syncStatus.mismatched.push(org);
      }
    }
  }

  return syncStatus;
}

Bulk Organization Report

async function generateOrgReport() {
  const orgs = await fetchAllOrganizations();

  return orgs.map(org => ({
    name: org.attributes.name,
    type: org.relationships['organization-type']?.data?.id,
    status: org.relationships['organization-status']?.data?.id,
    hasConfigurations: org.relationships.configurations?.data?.length > 0,
    hasPasswords: org.relationships.passwords?.data?.length > 0,
    psaSynced: !!org.attributes['psa-id'],
    createdAt: org.attributes['created-at'],
    updatedAt: org.attributes['updated-at']
  }));
}

Error Handling

Common API Errors

Validation Errors

Error Recovery Pattern

async function safeCreateOrganization(data) {
  try {
    return await createOrganization(data);
  } catch (error) {
    if (error.status === 422 && error.detail?.includes('already been taken')) {
      // Organization exists - find and return it
      const existing = await findOrganizationByName(data.name);
      return existing;
    }

    if (error.status === 401) {
      throw new Error('API key invalid or expired. Check IT_GLUE_API_KEY.');
    }

    throw error;
  }
}

Best Practices

1. Use descriptive names - Include location or identifier if needed for uniqueness
2. Maintain quick notes - Keep emergency contact info readily available
3. Set organization types - Enable meaningful filtering and reporting
4. Link to PSA - Always set psa-id for cross-platform lookups
5. Use parent/child - Organize multi-location or division clients
6. Archive, don't delete - Preserve historical documentation
7. Regular audits - Review organization list quarterly
8. Document alerts - Use alert field for critical client notices
9. Primary contact - Always set a primary contact for each org
10. Standardize naming - Use consistent naming conventions

Related Skills

• IT Glue Configurations - Asset management for organizations
• IT Glue Contacts - Contact management
• IT Glue Passwords - Credential storage
• IT Glue Documents - Documentation
• IT Glue API Patterns - API reference