1. Graphql
  2. Alfresco API

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

graphql
query FindAlfrescoPerson {
	alfrescoPerson(id: "mmustermann") {
		id
		cn
		firstName
		lastName
		fullName
		email
		organizationalUnit
		enabled
		emailNotificationsEnabled
		avatarId
		absent
	}
}

retrieve multiple persons via the Alfresco API

graphql
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.
  • username in 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):

graphql
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's Cache-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-revalidate as “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:

  • @alias reads 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.
  • @ensureArray accepts 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 @ensureArray rejects missing and null values, even when the list is nullable; an empty array is valid.
  • @ensureBoolean converts values to text and ignores letter case: 1, true and yes become true; all other values, including missing and null values, become false. 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.