Configuring Employee Images

Employee Images is a Plus tier feature that allows you to display profile images directly in your org chart nodes. This enhances visual recognition and makes your charts more engaging and informative.

Overview

Employee images appear in org chart nodes alongside employee information. Images are displayed with customizable appearance settings including size, shape, layout, and borders.

OrgNice supports multiple image sources:

  • Public URLs - Images from any publicly accessible web source (your own servers, CDNs, etc.)
  • Google Drive (Public Sharing) - Images shared publicly via Google Drive link
  • Google Drive (Private - Service Account Access) - Private images shared securely with OrgNice’s service account (no public sharing required)

Availability: Plus tier only. Trial users have full access during the trial period.

Setting Up Employee Images

Step 1: Prepare Your Data

To use employee images, you need a column in your Google Sheets that contains image URLs. Each URL should point to a publicly accessible image file.

URL Requirements

  • Protocol: HTTPS only (secure URLs)
  • Accessibility: The URL must be publicly accessible without authentication
  • Format: Common image formats are supported (JPG, PNG, WebP, GIF)
  • Size: Images should be reasonably sized (recommended: under 5MB)

Example Data Structure

Employee Name | Employee ID | Manager | Image URL
John Smith    | EMP001      | MGR001  | https://example.com/images/john.jpg
Jane Doe      | EMP002      | MGR001  | https://example.com/images/jane.png

Step 2: Map the Image Column

In the Project Setup page, locate the “Employee Images” field in the Mapping Card section.

Select the column from your Google Sheets that contains the image URLs. You can leave this unmapped if you don’t want to use employee images.

Note: Employee image mapping is only available if your account has the Plus tier.

Step 3: Configure Image Display

Once you’ve mapped the employee images column, you can customize how images appear in your charts using the Appearance settings. See the Customization section below.

Customization

Configure how employee images appear in your org chart nodes from the Appearance section in Project Setup.

Size

Choose the display size for employee images:

  • Small: 64×64 pixels - Compact option suitable for large charts
  • Medium (default): 128×128 pixels - Balanced size for most use cases
  • Large: 192×192 pixels - Prominent display for emphasis

Shape

Choose how employee images are displayed:

  • Circle (default): Images are displayed as circles
  • Square: Images are displayed as squares with optional rounded corners

Note: When shape is set to “Circle”, the border radius is automatically set to 50% and cannot be customized.

Layout

Choose how images are positioned relative to employee information:

  • Left (default): Image appears to the left of employee name and additional fields
  • Top: Image appears above employee name and additional fields

Choose “Left” for a compact horizontal layout. Choose “Top” for a stacked layout that emphasizes the image.

Border

Customize the border around employee images:

  • Width: Border thickness in pixels (0 = no border)
  • Style: Border style - Solid, Dashed, Dotted, Double, or None
  • Color: Border color selector
  • Radius (Square shape only): Curved corner radius in pixels (0 = sharp corners)

Note: Border radius customization only applies when shape is set to “Square”. For circles, the border radius is fixed at 50%.

Preview

Use the Preview section to see how your employee images will appear with your chosen settings. The preview updates in real-time as you adjust customization options.

Image Validation and Error Handling

OrgNice validates image URLs and handles failures gracefully.

Validation Process

Images are validated at the following stages:

  1. URL Validation: The URL must be publicly accessible via HTTPS
  2. Content Validation: The file must be a valid image format
  3. Image Validation: The image is normalized to the selected size and shape

Supported Image Formats

  • JPEG / JPG
  • PNG
  • WebP
  • GIF

Error Handling

If an image fails to load:

  • A placeholder icon is displayed in place of the image
  • The chart continues to render normally
  • A tooltip appears on hover showing the error reason
  • Validation errors are listed in the Validation section during setup

Common Error Reasons

  • URL Not Found (404): The image URL no longer exists or is incorrect
  • Access Denied (403): The URL requires authentication or has restricted access
  • Invalid Image: The file is not a valid image format
  • Connection Failed: The server is unreachable or offline

Troubleshooting

If images aren’t displaying:

  1. Verify URLs are correct - Check that image URLs in your Google Sheets are spelled correctly
  2. Ensure URLs are public - Test the URL in a new browser tab without logging in
  3. Check image format - Ensure files are in a supported format (JPG, PNG, WebP, GIF)
  4. Look for validation errors - Check the Validation section in Setup for detailed error messages
  5. Refresh your chart - Click the refresh button on the preview chart to reload images if they fail temporarily
  6. Re-map the column - Sometimes re-selecting the image column can help resolve temporary issues

Using Google Drive Images

Google Drive is a convenient way to manage employee images without hosting them on a separate server. OrgNice supports two ways to use Google Drive images: public sharing and private sharing via service account.

Option 1: Google Drive (Public Sharing)

Use images you’ve shared publicly. This is the easiest option for quick setups.

How to Set Up Public Google Drive Images

  1. Upload your image to Google Drive

    • Upload the image file to your Google Drive

  2. Share the file publicly

    • Right-click the image → Select “Share”
    • Change sharing permission to “Anyone with the link can view”
    • Copy the share link (format: https://drive.google.com/file/d/FILE_ID/view?usp=sharing)

  3. Add to your Google Sheets

    • Paste the share link directly into your Google Sheets image column
    • OrgNice automatically detects Google Drive links and fetches the image

Example

Share link from Google Drive:

https://drive.google.com/file/d/1ABC123XYZ789/view?usp=sharing

Pros: Simple, no configuration needed Cons: Files must be publicly shared (anyone with the link can view)

Option 2: Google Drive (Private - Service Account Access)

Use private Google Drive files without making them publicly accessible. OrgNice uses a service account to securely access images you share with it.

What is a Service Account?

A service account is a special Google Cloud account designed for automated, programmatic access. It’s not a user account—it’s a machine account managed entirely by Google Cloud.

Key points about OrgNice’s service account:

  • Service account email: gdrive-profile-images@orgnice-com.iam.gserviceaccount.com
  • It can only access files explicitly shared with it
  • It has read-only permissions (cannot modify or delete your files)
  • It cannot be impersonated or created outside Google Cloud
  • Google owns and controls the @iam.gserviceaccount.com domain exclusively

For more information, see Google Cloud IAM - Service Accounts.

How to Set Up Private Google Drive Images

  1. Service account email: gdrive-profile-images@orgnice-com.iam.gserviceaccount.com

    What is a service account? A service account is a special Google Cloud account designed for automated, programmatic access—not a user account. Learn more: Google Service Accounts

  2. Share Drive files with the service account

    • Open the Drive file containing your image
    • Click “Share” (or “Share” button in Drive)
    • Paste the service account email
    • Set permission to “Viewer” (read-only access)
    • Click Share (don’t send notification)

  3. Get the file ID or share link

    • Right-click the image file → “Get link”
    • Copy the full link, for example: 
      https://drive.google.com/file/d/FILE_ID/view?usp=sharing

  4. Add to your Google Sheets

    • Paste the full link into your image column
    • OrgNice detects the format and fetches the image

Example

Paste the Drive link directly in your image column:

https://drive.google.com/file/d/1ABC123XYZ789/view?usp=sharing

Pros: Files remain private; users can’t share them without your permission Cons: Requires one-time setup per file

Best Practices for Google Drive Images

For easier management and organizational consistency, especially when using private Google Drive images with the service account:

  1. Create a dedicated folder - Set up a single folder in Google Drive specifically for employee profile images (e.g., “OrgNice Profile Images”)
  2. Share the folder with the service account - Share this folder with gdrive-profile-images@orgnice-com.iam.gserviceaccount.com as Viewer
  3. Organize by employee - Add images to this folder and organize them (optionally by department or hire date)
  4. Use consistent naming - Name image files with employee IDs or names for easy identification and maintenance

This approach keeps your images organized and makes it easier to grant access to the service account.

Google Service Accounts

A service account is a special type of Google Cloud account designed for programmatic access and automated tasks—not a regular user account. It’s a machine account managed entirely by Google Cloud. Service accounts are commonly used by applications and services to securely access Google services like Drive, Gmail, Sheets, and more.

Why is this safe?

The service account domain @iam.gserviceaccount.com is:

  • Exclusively owned and controlled by Google — No third party can create or impersonate this domain
  • Cryptographically secured by Google Cloud IAM — Google issues and validates every service account email
  • Documented by Google — See Google Cloud Service Account Email Format

The service account can only access files you explicitly share with it. If you revoke sharing, it loses access immediately. You’re in control.

For more details on service account security, refer to:

Revoking Access

If you ever want to stop allowing OrgNice to access your images:

  1. Open the shared Drive file
  2. Click Share
  3. Find the service account email and click “Remove”
  4. Done — OrgNice can no longer access that file

Choosing Between Public and Private

Feature Public Share Private (Service Account)
Setup Time 2 minutes 2-3 minutes per file
Security Anyone with link can view Only OrgNice can access
Best For Public employee directories Confidential/internal employee data
Configuration None Share with service account

Exporting with Employee Images

When exporting your chart to different formats:

PNG and PDF Formats

  • Employee images are included in the export if they have successfully loaded
  • Images are normalized to the same size and format as displayed in the chart
  • Failed images (shown as placeholders) are not included in exports

SVG Format

  • Employee images are not included in SVG exports due to technical limitations of the format
  • Use PNG or PDF format if you need to export charts with employee profile images included

Examples

Example 1: Simple Profile Display

Setup: Image column mapped, Size=Medium, Shape=Circle, Layout=Left

Result: Circular profile images displayed to the left of employee names, suitable for most org charts.

Example 2: Prominent Employee Focus

Setup: Image column mapped, Size=Large, Shape=Circle, Layout=Top, Border=2px solid color

Result: Large circular images with colored borders displayed above employee information, emphasizing visual recognition.

Example 3: Professional Company Style

Setup: Image column mapped, Size=Medium, Shape=Square, Layout=Left, Border=1px solid gray, Radius=4px

Result: Square images with slight rounded corners, professional appearance matching corporate design standards.

Tips and Best Practices

  • Use consistent image dimensions: Square images (1:1 aspect ratio) work best
  • Test with a few rows first: Map a small set of rows and verify images display correctly before rolling out to the full chart
  • Use descriptive URLs: If possible, use image names that match employee IDs for easier maintenance
  • Backup URLs: Keep image URLs in a separate column for reference in case you need to update them
  • Monitor image availability: Periodically check that image URLs remain accessible
  • Resize images beforehand: While OrgNice handles sizing, pre-sized images (around 200-300px) load faster

Frequently Asked Questions

Q: Can I use images from Google Drive? A: Yes! See the Using Google Drive Images section for two options:

  • Public sharing (easiest setup)
  • Private sharing via service account (more secure)

Q: Is it safe to share files with OrgNice’s service account? A: Yes, completely safe. Service accounts are Google-managed machine accounts that:

  • Can only access files you explicitly share with them
  • Have read-only permissions (cannot modify or delete files)
  • Cannot be created or impersonated outside Google Cloud
  • Use the @iam.gserviceaccount.com domain, which is exclusively owned and controlled by Google

See Security & Trust in the Google Drive section for more details and links to Google’s official documentation.

Q: Can OrgNice see all my Google Drive files? A: No. The service account can only access files you explicitly share with it. It cannot browse or access any other files in your Drive.

Q: What if I want to revoke access later? A: You can revoke access anytime. Just open the shared Drive file, click Share, find the service account email, and click Remove. OrgNice will lose access immediately.

Q: What happens if an image URL is broken? A: A placeholder icon is shown instead of the image. The chart continues to display normally. You can fix the URL in your Google Sheets and click the refresh button on the chart to reload the images.

Q: Are images stored on OrgNice servers? A: Only normalized cached copies are temporarily stored for performance. Original images remain at their source URLs. OrgNice does not retain images permanently.

Q: Can I use employee images in exported charts? A: Yes, if the images have successfully loaded in the chart, they will be included in PNG, SVG, and PDF exports.

Q: Why is this feature Plus tier only? A: Employee images require additional processing resources for normalization, caching, and serving. The Plus tier includes this feature along with other advanced capabilities like Export and Public Sharing.