Graphql
Alfresco API
Alfresco people search and file uploads via GraphQL
Alfresco has the possibility to search for known users. Those users may be synchronized from a LDAP directory.
retrieve a single person via the Alfresco API
query FindAlfrescoPerson {
alfrescoPerson(id: "mmustermann") {
id
cn
firstName
lastName
fullName
email
organizationalUnit
enabled
emailNotificationsEnabled
avatarId
absent
}
}
retrieve multiple persons via the Alfresco API
query SearchAlfrescoPersons {
alfrescoPersons(where: { q: "mustermann" }, paging: { limit: 5 }, sort: { by: lastName }) {
nodes {
id
cn
firstName
lastName
fullName
email
organizationalUnit
enabled
emailNotificationsEnabled
avatarId
absent
}
}
}
Profile avatar upload (@alfrescoWebscript, multipart)
Uploads hit the Alfresco repository webscript with the usual ticket (alf_ticket), not Alfresco Share in the browser. On the field definition, set bodyType: multipart.
Requirements
- Valid ticket for the user who owns the avatar.
usernamein the payload = Alfresco person id (cm:userName); must match the ticket user (the webscript enforces this).
Example (schema extension name may differ, e.g. Aquanet uploadAvatar):
mutation UploadAvatar {
uploadAvatar(
payload: {
fileBase64: "<base64 or data:image/jpeg;base64,...>"
filename: "photo.jpg"
username: "mmustermann"
}
) {
fileName
nodeRef
status {
code
name
}
}
}
Other upload webscripts: Declare a mutation with @alfrescoWebscript(endpoint: "…", method: post, bodyType: multipart) and a payload that matches your script (see internal Technical doc: file uploads / Alfresco multipart).
Webscript response caching (headers.cacheability)
Pass headers.cacheability on an @alfrescoWebscript query to store public JSON responses (file, Redis, or memory, depending on config).
Example value: "public, max-age=300, stale-while-revalidate=604800".
- With
cacheability: if Identity Hub already has an entry for that key, the user GET always gets that body. After the Alfresco response'sCache-Control: max-age, a background refresh runs with an Alfresco ticket. Failed refresh (500, 401, timeout) keeps the stored body. Error responses are not written. A later valid 200 with an empty array is allowed to replace the entry. - Without
cacheability: no cache read or write (preview / live). - Do not treat
stale-while-revalidateas “give up and call Alfresco on the user request.” It is not a serve cutoff.
Validate cached responses against the declared type
Set validateResponse: true on @alfrescoWebscript to check responses against the field's GraphQL return type, including supported directives on fields within response objects:
type Record {
code: String!
}
type Batch {
records: [Record!]
}
extend type Query {
batch(headers: CacheHeaders): Batch
@alfrescoWebscript(endpoint: "records", validateResponse: true)
}
Here CacheHeaders is the schema's input type containing cacheability: String. Validation runs only for calls that send a non-empty headers.cacheability.
The check uses the final runtime schema, including inherited fields. Compressed HTTP responses are decoded for validation and stored with their original bytes. It requires the declared object or array root, every non-null property and every declared list property, recursively, after applying these field directives in schema order:
@aliasreads the configured source path, including nested and bracket paths. With several paths, it uses the first non-null value, including an empty array;path: []selects the containing object. An incompatible first value fails validation even if a later path has a valid value.@ensureArrayaccepts missing or null values as an empty array and wraps a single value in an array. Every resulting element must still match its declared type. A list without@ensureArrayrejects missing and null values, even when the list is nullable; an empty array is valid.@ensureBooleanconverts values to text and ignores letter case:1,trueandyesbecometrue; all other values, including missing and null values, becomefalse. Whitespace is preserved. This follows the directive's conversion rather than JavaScript truthiness.
For example, records: [Record!]! @alias(path: "payload.records") @ensureArray accepts a single record at payload.records. Directive order matters: placing @alias after a coercion replaces that earlier transformation with the source-path value.
Scalars use their GraphQL serializer; abstract types require a valid __typename. Nullable non-list properties may be absent. Validation preserves extra properties and never rewrites the cached response. Empty or unparseable bodies fail validation. A rejected response is neither stored nor returned. A failed background refresh keeps the last good cached response; without one, the call reports an error. Previously stored incompatible responses are bypassed.
AlfrescoPerson.cn reads the raw person id through @alias; the response does not need a separate cn. Built-in Alfresco workflow fields computed by resolvers validate their declared raw inputs instead: definition formKey uses startFormResourceKey, definition permissions uses key, process name and formKey use processDefinitionKey, process priority and tasks use id, and task formKey uses formResourceKey. These sources must have the required string or ID shape. Validation does not fetch related resources or evaluate permissions; those resolvers run only when GraphQL selects their fields.
Contract rejection logs include the schema field path, expected GraphQL type and raw shape (such as object, array, string or undefined). They contain no response values or property names taken from response data. A computed field's path also identifies the required source.
Validation defaults to false. It does not run custom resolvers or transformations from other directives. Enable it where the response matches the declared type using the supported field directives above. Fields that omit the option keep their existing caching behavior, regardless of their response structure.