Use the API for notice capabilities that are not available in the Console. This reference explains how to update selected notice fields with a patch, store custom field values, lock a notice, and run many notice operations in one request. It applies to accreditation notices sent to schools and team notices sent to visiting teams.
Changing Chosen Fields with a Patch
You can change one or two notice fields, such as making a notice inactive, by sending patch instructions instead of the full record. Rhythm starts with the saved notice, applies your instructions, and then checks the finished record the same way it checks a full update.
Warning
A patch must still leave the full notice in a valid state. For example, Rhythm refuses a patch that changes the audience to “only certain roles” when the notice has no roles listed, even if the audience field was valid before the patch.
Storing Custom Field Values
You can use the API to store your association’s own custom field values on a notice, even though notices do not have a custom fields screen in Setup. Files in custom field values are handled differently for each notice type:
| Notice type | A file in a custom field value |
|---|---|
| Accreditation notice (sent to a school) | Is not moved into the notice's own storage, so the file cannot be opened reliably later |
| Team notice (sent to a visiting team) | Is moved into the notice's own storage when you save, and removed when the notice is deleted |
Warning
If you attach a file through a custom field on an accreditation notice sent to a school, do not rely on opening it later. Use a team notice when the custom field value needs to carry a file reliably, or keep the file somewhere else and reference it with a value your own system can resolve.
Tip
A custom field of type HTML looks different depending on where you view it. On the record itself, it appears as formatted text. In a query result or an export, such as an Excel export, the same field returns its raw HTML markup instead of the formatted text.
Locking a Notice Against Changes or Deletion
You can lock a notice so later changes or deletions are refused until someone removes the lock. A lock has two levels:
| Lock value | Effect |
|---|---|
| Locked against deletion only | The notice can still be changed, but not deleted |
| Locked against updates and deletion | The notice can be neither changed nor deleted |
A lock does not affect sending the notice, because sending only reads the notice and does not change it. Because the lock is a field on the notice record, anyone who can update the notice can set or clear it. When a notice is locked against updates, they can clear the lock only by including that change in the same kind of write that would otherwise be refused.
Running Many Notice Operations in One Request
You can send up to 100 create, read, update, patch, or delete operations for accreditation notices or team notices in one batch request. Each operation goes through the same checks it would face on its own, and Rhythm reports each outcome separately. If some operations in a batch fail, the successful ones still take effect.
Related
- Accreditation Console and API Addresses
- Accreditation Notices
- Team Notices
- Custom Fields Explained