Skip to main content
Bulk photo import matches each image to one recipient in the selected program. The match comes from the photo’s filename and the Unique Field to Consider you choose during import.
Use the Gratona Entity ID when possible. Gratona generates this system value for every recipient, and it does not change when profile information is edited.

​
Before you upload

  1. Open Imports, choose Profile Photos, and select the recipient program.
  2. Choose Recipients as the resource, then continue to the photo upload step.
  3. In Unique Field to Consider, select the field represented in every photo filename. Choose Entity ID when it is available in your source files.
  4. Decide whether the imported images should become the recipients’ profile photos.
You can select multiple photos, choose a folder, or drag a folder into the upload area. The upload screen shows the current file-size and batch-size limits for your workspace.
The photo import field selector showing Entity ID under system fields and the program's recipient fields in a separate group

​
Choose the matching field

You have two useful choices:
  • Entity ID is the safest default. Copy the system-generated Gratona ID from the recipient record or an export.
  • A recipient form field works when your organization already has a stable identifier, such as a recipient number, case number, email address, or username.
The selected field must contain a value for every recipient in the batch, and each value must identify exactly one recipient in the selected program. A field appearing in the selector does not guarantee that its data is unique. Avoid names, dates of birth, gender, or any other field that people can share.

​
Name each photo

The filename must contain the selected recipient field’s value. The file extension is not part of the match. For the most predictable result, make the filename just the value: Descriptive text can appear before or after the value. For example, recipient_4821_profile.jpg and student_DO0140540_profile.png can match the same values shown above. Spaces, hyphens, and underscores are treated as separators for general identifiers such as recipient numbers, so ABC-001.jpg can match a stored value of ABC 001. Even though descriptive text is supported, exact-value filenames are easier to audit. When matching a numeric Entity ID, avoid adding other numbers such as years or sequence numbers to the filename.
Preserve punctuation in email addresses and usernames. john-smith.jpg, john.smith.jpg, and johnsmith.jpg are different values. The match ignores letter case, but it does not treat those punctuation variants as the same username.
You do not need to add a field label such as Entity ID to the filename, and a CSV is not required for a photo import.

​
Supported images

Use one of these file types:
  • JPG or JPEG
  • PNG
  • GIF
Each filename must be unique within the selected batch. If two selected files use the same filename, Gratona keeps one and marks the duplicate as rejected before upload.
The photo upload screen showing four accepted files and one rejected duplicate filename

​
Validate before importing

Gratona validates the batch before attaching any photos. Review the validation results, especially skipped files:
  • No matching record means the filename does not contain a value found in the selected field for a recipient in this program.
  • Matched multiple records means the value is not unique enough to identify one recipient.
  • Invalid file type means the image is not a supported JPG, JPEG, PNG, or GIF.
  • File size exceeds the limit means the image is larger than the limit displayed on the upload screen.
Only validated files are imported. A skipped file is not attached to any recipient.
Completed photo validation showing three successful matches and one warning for an unmatched Entity ID

​
Troubleshooting a filename

If a photo does not match:
  1. Confirm that you selected the field represented in the filename.
  2. Copy the value directly from the recipient record or a recipient export.
  3. Rename the file to the exact value plus its extension, such as 4821.jpg.
  4. For email or username fields, restore every period, hyphen, underscore, plus sign, and @ character.
  5. Confirm that the recipient belongs to the program selected for the import.
  6. Validate the batch again before importing.
If more than one recipient has the selected value, correct the duplicate data or switch to the Gratona Entity ID. Gratona skips ambiguous files instead of guessing which recipient should receive the photo.