Findings — observe: what changed

025_event_log

meta.old_value and meta.new_value answer "what was this before", but meta is unfilterable and unsortable: narrow on entity, event_type and attribute_name, sort -id, read meta yourself. [partial]

not measured: Whether event_type or meta can be set in the create body is untried: testing it costs another permanent row. Every event read was generated by another user; probe 049 covers the script's own.

The type has 16 fields, all of them server-written. id and created_at are the only two that order it, and meta is the only one that says what changed.

The four production uses, measured:

• meta holds the answer and refuses every query. old_value and new_value exist only where meta.type is attribute_change; new_entity, entity_retirement and entity_revival hold entity_id and entity_type and no values at all, and a preference change has no meta.type and the keys old, new, pref.

• Since serializable is unfilterable and unsortable (field_types/serializable), select rows by entity, event_type and attribute_name, order by -id, and inspect meta client-side.

• To restore a previous status: take the newest matching entry, check meta.new_value equals the value the entity holds now, then write meta.old_value. A mismatch means something changed since, and the entry is stale.

• A created entry cannot be deleted, so never write one to a real site. POST with project alone answers 201, invents description: "New Event", and leaves event_type, attribute_name, meta, user and entity null.

• Every one of those is then refused on PUT by a per-field permission rule, and DELETE is refused by PermissionRule 297. Both refusals name a role and a rule number, API Admin -- PermissionRule 297, so a script user in a different role may be permitted more; check the error before concluding the API forbids it everywhere.

• This probe spent its one create on the minimal body and stopped, so whether event_type or meta can be set in the create body is unmeasured: testing it costs another permanent row. One row from this probe survives in the sandbox project of the probed site. A ledger built here is append-only with no way to correct or retract an entry.

• Ids are reserved ahead of use and committed late. On the probed site the newest 500 rows spanned 738 ids with 9 gaps, the largest 33 wide, while every 1001-id window at depth 10000 or more was 100% dense. Gaps close, so they are held blocks and not deletions.

• A cursor that stores max(id) and asks for id greater_than <that> loses whatever later lands in the gaps it passed. Track a low-water mark instead: re-scan a window behind the head, or drive the feed from created_at and deduplicate on id.

• entity goes null when its target is deleted; meta remembers. On the probed site 12889 of 17778 Shotgun_Shot_Change rows have entity null, and each names a meta.entity_id whose Shot now 404s. Filtering on entity returns only live targets, so the history of a deleted entity is reachable by event_type and created_at alone.

• Every event this probe read was generated by somebody else. On the probed site the script's generate_event_log_entries was False for the whole window this probe ran in, so none of its own writes were logged and the reads above measure other users' events. Probe 049 measures what a script's own write puts in the log, and the flag that decides whether it appears at all.

• Narrowing works on everything but meta. On the probed site the unfiltered log holds 2462044 rows, one project 22811, one Shot 2. event_type takes starts_with and in, created_at takes in_last and between, and entity takes a {type, id} hash, type_is, and a dotted path such as entity.Shot.code.

• attribute_name alone is site-wide across every entity type, so pair it with event_type or entity.

• A sort on meta, on audit_trail or on a name the type does not have is accepted and ignored, falling back to ascending id, so a client cannot tell an ignored sort from a satisfied one.

corpus/findings/025_event_log.md

043_attention

The six attention calls share no convention with the rest of the API: no paging, no fields, links.self spelled /entity/Shot/7668, and a missing record id on activity_stream is a 500.

• activity_stream is not the event log. It has its own id space, its own paging keys and its own latency. On the probed site the newest update was id 246800 dated two days before the run, and three Shots created during the run were absent from their own streams and from the project's after 90 seconds of polling.

• Read EventLogEntry (probe 025) for anything a write has to confirm.

• Page it with max_id, not page[]. Both bounds are exclusive, earliest_update_id is the floor reached, and 0 there means the stream ran out. latest_update_id is site-wide when no max_id is given, so it does not describe the record you asked about.

• A record id that is not there answers 500 on activity_stream, on all four types tried, where followers, following and thread_contents all answer a named 404. Check the record first.

• The follow body's entity is the CamelCase schema name and nothing else. "shots", correct in every path segment and accepted by following?entity=, is a 500 with no clue in it.

• A partial follow list applies its good half and returns 404. The 404 names only the missing id, so treat the call as non-atomic and re-read followers.

• Neither follower list pages or takes fields. On the probed site one user's following was 896 rows in a single body, each row id, type and a link, with no name and no follow date.

• thread_contents returns Note, Attachment and Reply interleaved by time. The Note and Attachment rows name their author under created_by, the Reply rows under user, and entity_fields widened the first two and was ignored on the third.

corpus/findings/043_attention.md

049_script_events

A script's writes reach the event log only while its ApiUser has generate_event_log_entries True. The default is False and nothing errors when off. One create logs one row per field plus one _New.

• generate_event_log_entries on the ApiUser gates the whole feed, and its default is False. While it is off the write still answers 201, the log stays empty, and any webhook scoped to that change has nothing to fire on. Nothing errors, so a client cannot detect it from the response. Read the flag before concluding the API does not log an operation.

• A script can read and set its own flag. PUT /entity/api_users/<own id> with {"generate_event_log_entries": true} answers 200. Turning it on is a one-call fix; it also means a compromised script key can switch its own audit trail off.

• One create costs one row per populated field plus one _New. Four keys sent produced five Shotgun_<Type>_Change rows, because server-set defaults are logged too, and each sets in_create: true. A consumer counting operations must not count events.

• Events are visible 0.3s to 0.4s after the call. There is no lag to design around at this size.

• session_uuid is null on every row this script generated, and set on the rows the web interface generated. It does not group a script's calls into a session.

• A delete logs two rows and orphans all the others in the same instant. Shotgun_<Type>_Retirement puts retirement_date and display_name in meta, and every earlier row for that entity drops its entity link at once, so the history is reachable only through meta.entity_id, which is unfilterable (probe 025). Capture the id before deleting or lose the trail.

corpus/findings/049_script_events.md

066_user_feed

A HumanUser's activity_stream is what the person created, not what they follow: 0 of 9 rows touched the 81 followed records. A feed is a fan-out over their tasks' Shots and Assets.

• A HumanUser stream is the rows whose created_by is that person, plus the creation of the row itself. It is not the Inbox and it is not the follow list: the 77 Tasks and 4 Notes the person follows contributed nothing to it, and impersonating the person did not change it.

• A Shot's stream holds its Tasks and Versions as primary_entity rows; a Task's stream holds the Task alone. A feed of "my day" is one call per distinct Shot or Asset behind the person's Tasks, merged on id descending, with max_id for paging (endpoints/get_entity_type_id_activity_stream).

• read was false on every row under the script token and under sudo_as_login, so the stream does not expose the Inbox's read state. Keep the last id seen locally and page with min_id.

• What a Note or a Reply writes to any stream is probe 067.

corpus/findings/066_user_feed.md

067_notes_in_the_stream

A Reply reaches every linked stream in 33 s as create_reply, creates too; a script's Note create and status changes were absent after 430 s. Write as a person.

• create_reply is a fourth update_type, next to create, update and delete (probe 043). Its primary_entity is the Note, named <subject> - <content>, and meta holds the Reply's id and its content, so a feed can draw the reply without a second call.

• One update id is written once and fanned out: the same create_reply row, id 247337, was on the Note, the Version, the Shot, the Task and the Project. A fan-out over several streams must deduplicate on id.

• A record's stream holds the creates of its children: the Shot's had the Task and the Version, the Task's had the Version. The Version's stream holds no Task. Read the Shot or Asset, not the Task.

• Latency for what does show is under 33 s on the probed site, against the 90 s absence probe 043 measured. Poll at 30 s.

• A Note created by the script user wrote no create row on any of six streams, and two status changes by the script wrote no update, in 430 s. Attribute changes made in the web application are on the same streams.

• Autodesk staff on the community forum tie API-made Inbox items to sudo_as_login and to the script's "Generate Events" flag. A Note created under scope=sudo_as_login on the same site was on the Shot's stream and on its own within 60 s. Attribute a write to a person (probe 027).

• read_by_current_user on the Note read "unread" for the script, a string, not a boolean.

corpus/findings/067_notes_in_the_stream.md