Troubleshooting Note Publishing Errors (Lumary Integration)

Overview

When a session note linked to a Lumary appointment is signed in Motivity, Motivity sends the session's actual start and end times to Lumary to complete the appointment. Lumary validates this request against its own business rules (appointment status, licensing, payroll, billing, and time tolerances). If any rule is not met, Lumary rejects the request and the note will show as Publishing Failed in Motivity.

Key concept: These errors are returned by Lumary and reflect the state of records in Lumary. Motivity displays the error so you can act on it, but in most cases the correction happens on the Lumary side. Once corrected, the publish can be retried from Motivity.

Where to Find Failed Publishes

In Motivity Clinical, open the Integration area (requires the Manage Integration permission — available to Administrators).
Open the Notes panel. Notes needing attention are grouped by status, including Publishing Failed.
Select a failed note to open its Publishing State, which lists each publish attempt.

[Screenshot: Notes panel showing the Publishing Failed filter]

How to Read the Error

Each failed attempt appears as a Network Error entry with a timestamp. Expand it to view the HTTP Error details. The most important field is Response Content — this contains the message returned by Lumary explaining exactly why the publish was rejected.

Example:

"This appointment is in Draft status and will not accept actual start and end times for completion."

[Screenshot: Publishing State panel with the Response Content message highlighted]

General Resolution Workflow

Read the message in Response Content and match it to the reference table below.
Correct the issue in Lumary (or have your Lumary administrator do so). Motivity cannot change appointment status, licensing, payroll, or billing records in Lumary.
Return to the note's Publishing State in Motivity and select Clear errors and retry.
Confirm the note now shows as Published and the appointment shows as Complete in Lumary.

Important — do not repeatedly unsign and re-sign the note. Re-signing does not resolve a publishing error and creates unnecessary revisions on the note. The publish will continue to fail until the underlying issue is corrected in Lumary. Fix the Lumary-side issue first, then retry.

Error Reference

Record lookup

Error message	What it means	How to resolve
A matching appointment could not be located.	The linked appointment no longer resolves to an Employee Appointment record in Lumary — it was likely deleted.	Link the note to an alternate appointment.
This employee does not have an active Lumary License.	The appointment's employee has no linked User record in Lumary, or that User is inactive.	In Lumary, link the employee to an active, licensed User.

Note on licensing: Lumary enforces licensing for both clients and staff. A learner or member can show as Linked in Motivity and still fail to publish if the corresponding Lumary record is unlicensed or inactive — linking confirms the records are matched, not that they meet Lumary's licensing requirements.

Appointment status

Error message	What it means	How to resolve
This appointment is in Draft status and will not accept actual start and end times for completion.	The Employee Appointment in Lumary is still in Draft status.	In Lumary, move the appointment from Draft to Scheduled, then retry from Motivity.
This appointment has been cancelled and will not accept actual start and end times for completion.	The Employee Appointment in Lumary is Cancelled.	A cancelled appointment cannot be completed. In Lumary, uncancel the appointment or create a new one, then link and retry.

Payroll

Error message	What it means	How to resolve
This appointment has been extracted for Payroll. It must be removed from the payroll extract to allow updated actuals.	The appointment already has locked payroll extract items, and the times being sent differ from the actuals already on the record.	In Lumary, remove the appointment from the payroll extract or unlock the extract items, then retry. (Resending the same times already on record is allowed — this only blocks a change to the actuals.)

Billing

Error message	What it means	How to resolve
This appointment has already been processed for Billing.	The session is already Complete in Lumary and has progressed into billing.	The appointment was already billed. Contact your billing team — this cannot be resolved by retrying.

Note name length

Error message	What it means	How to resolve
There were custom validation error(s)... "Session Note Name: data value too large... (max length=80)" (errorCode STRING_TOO_LONG)	Lumary limits the published document's name to 80 characters, and the note's name (plus its internal ID) exceeds that limit, so Lumary rejects the note document. This is common with long descriptive note names.	Shorten the note template's name in Motivity to prevent this on future notes (template name changes apply only to newly created notes). Notes that have already failed with this error will not publish on retry — complete those appointments manually in Lumary; the signed note remains saved in Motivity and can be downloaded and attached in Lumary manually if needed.

Temporary errors (no correction needed)

Error message	What it means	How to resolve
Failed to create document record (response references Lumary maintenance or being "down for maintenance")	The publish attempt occurred while Lumary was temporarily unavailable, such as during an overnight maintenance window. Nothing is wrong with the note, the staff member, or your configuration.	Select Clear errors and retry once Lumary is available again. No other correction is needed.

Publishing can occur outside business hours, so occasional attempts may coincide with Lumary maintenance windows. These errors are expected from time to time and are safe to simply retry.

Time tolerance

Error message	What it means	How to resolve
The provided start time of <value> is outside of the allowed tolerance of <n> mins from the scheduled start time of <value>.	The session's actual start time differs from the scheduled start by more than the tolerance configured in Lumary.	Adjust the note/session times to fall within tolerance, adjust the scheduled appointment in Lumary, or adjust the time tolerance configurations within Lumary, then retry. in Lumary, then retry.
The provided end time of <value> is outside of the allowed tolerance of <n> mins.	Same as above, for the end time.	Same as above.

About tolerances: Tolerance is configured in Lumary per Session Type (the Actual Times Tolerance (Mins) field). Small differences between scheduled and actual times are normal and accepted; this error only appears when the difference exceeds your organization's configured tolerance. These checks exist to catch likely mistakes (for example, a clock-in of 1:00–5:00 against a 9:00–11:00 appointment) before they reach billing.

If session times legitimately differ from the appointment: When a session ran meaningfully late or long, adjust the scheduled appointment in Lumary to reflect the correct times before signing/publishing, rather than relying on note times that fall outside tolerance. Your organization can also review whether the configured tolerance for that Session Type fits your workflows.

Frequently Asked Questions

Who can retry a failed publish? Any user with the Manage Integration permission can access the Notes Publishing area and retry. Providers (e.g., RBTs, BCBAs) do not see these errors — Administrators should monitor this area regularly.

Some of a staff member's notes publish and others fail. Why? Publishing outcomes are determined per session, not per staff member. If a user's notes show mixed results, check each failed note's error message: common causes include the appointment's status in Lumary, session times outside tolerance, the learner's Lumary record, or a temporary error during a Lumary maintenance window. A staff-level issue (such as a missing license) fails all of that user's notes, not some of them.

The note shows signed in Motivity but the appointment isn't complete in Lumary. Why? Check the Publishing State for the note. If a publish attempt failed, the error message will explain why. The note being signed in Motivity means Motivity attempted to publish; completion in Lumary only occurs once Lumary accepts the times.

I fixed the issue in Lumary. Why isn't the note published yet? Publishing does not automatically re-attempt after a Lumary-side fix. Return to the note's Publishing State and select Clear errors and retry. The note must also be in a signed state to publish — if it was unsigned during troubleshooting, re-sign it first, then retry.

Do I contact Motivity or Lumary support? Use the error message as your guide. If the fix involves records or configuration in Lumary (appointment status, licensing, payroll, billing, tolerances), your Lumary administrator or Lumary support is the right first contact. Contact Motivity support if the error message is missing or unclear, if a retry fails after the Lumary-side issue is confirmed fixed, or if notes are failing without an error entry.