# Group Placeholder Users ## Actions | Link | Description | Condition | |:-------------------:| -------------------------------------------------------------------- | ---------------------------------------------------------------- | | showUser | Link to the OpenProject placeholder user page (HTML) | | | updateImmediately | Update a placeholder from the instance | **Permission**: manage_placeholder_user | | delete | Permanently remove a placeholder from the instance | **Permission**: manage_placeholder_user | ## Linked Properties | Link | Description | Type | Constraints | Supported operations | Condition | |:-----------:|-------------------------------------------------------------- | ------------- | --------------------- | -------------------- | ----------------------------------------- | | self | This user | User | not null | READ | | | memberships | Link to collection of all the user's memberships. The list will only include the memberships in projects in which the requesting user has the necessary permissions. | MemberCollection | | READ | **Permission**: view members or manage members in any project | ## Local Properties | Property | Description | Type | Constraints | Supported operations | Condition | | :----------: | --------------------------------------------------------- | -------- | ---------------------------------------------------- | -------------------- | ----------------------------------------------------------- | | id | Placeholder user's id | Integer | x > 0 | READ | | | name | Placeholder user's full name, formatting depends on instance settings | String | | READ | | | createdAt | Time of creation | DateTime | | READ | | | updatedAt | Time of the most recent change to the user | DateTime | | READ | | ## PlaceholderUser [/api/v3/placeholder_users/{id}] + Model + Body { "_type": "PlaceholderUser", "_links": { "self": { "href": "/api/v3/placeholder_users/1", "title": "placeholder" }, "show": { "href": "/placeholder_users/1", "type": 'text/html' }, "delete": { "href": "/api/v3/placeholder_users/1", "method": "DELETE" }, }, "id": 1, "name": "placeholder", "createdAt": "2014-05-21T08:51:20Z", "updatedAt": "2014-05-21T08:51:20Z" } ## View placeholder user [GET] + Parameters + id (required, integer) + Response 200 (application/hal+json) [PlaceholderUser][] + Response 404 (application/hal+json) Returned if the user does not exist or if the API user does not have permission to view them. **Required permission** The user needs to have the manage_placeholder_user permission + Body { "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound", "message": "The specified user does not exist or you do not have permission to view them." } ## Update placeholder user [PATCH] Updates the placeholder user's writable attributes. When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body. + Parameters + id (required, integer, `1`) ... Placeholder user id + Request Update PlaceholderUser (application/json) + Body { "name": "New name" } + Response 200 [PlaceholderUser][] + Response 400 (application/hal+json) Occurs when the client did not send a valid JSON object in the request body. + Body { "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody", "message": "The request body was not a single JSON object." } + Response 403 (application/hal+json) Returned if the client does not have sufficient permissions. **Required permission:** Administrators, manage_placeholder_user global permission + Body { "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission", "message": "You are not allowed to access this resource." } + Response 404 (application/hal+json) Returned if the user does not exist. **Required permission:** Administrators, manage_placeholder_user global permission + Body { "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound", "message": "The requested resource could not be found." } + Response 422 (application/hal+json) Returned if: * the client tries to modify a read-only property (`PropertyIsReadOnly`) * a constraint for a property was violated (`PropertyConstraintViolation`) + Body { "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation", "message": "Name is already taken.", "_embedded": { "details": { "attribute": "name" } } } ## Delete placeholder user [DELETE] Permanently deletes the specified placeholder. This action will be performed asynchronously and the response will only accept the deletion request. The actual deletion will then potentially take a while. + Parameters + id (required, integer, `1`) ... Placeholder user id + Response 202 Returned if the account was successfully scheduled for deletion. + Body + Response 403 (application/hal+json) Returned if the client does not have sufficient permissions. **Required permission:** Administrators or manage_placeholder_user permission + Body { "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission", "message": "You are not authorized to access this resource" } + Response 404 (application/hal+json) Returned if the user does not exist. + Body { "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound", "message": "The requested resource could not be found." } ## PlaceholderUsers [/api/v3/users{?offset,pageSize,filters,sortBy}] + Model + Body { "_links": { "self": { "href": "/api/v3/placeholder_users" } }, "total": 2, "count": 1, "_type": "Collection", "_embedded": { "elements": [ { "_type": "PlaceholderUser", "_links": { "self": { "href": "/api/v3/placeholder_users/1", "title": "placeholder" }, "showUser": { "href": "/placeholder_users/1", "type": 'text/html' }, "updateImmediately": { "href": "/api/v3/placeholder_users/1", "title": "Update placeholder" "method": "PATCH" }, "delete": { "href": "/api/v3/placeholder_users/1", "title": "Delete placeholder" "method": "DELETE" } }, "id": 1, "name": "placeholder", "createdAt": "2014-05-21T08:51:20Z", "updatedAt": "2014-05-21T08:51:20Z" } ] } } ## List Placeholder Users [GET] Lists placeholders. Only administrators or users with manage_placeholder_user global permission have permission to do this. + Parameters + offset = `1` (optional, integer, `25`) ... Page number inside the requested collection. + pageSize (optional, integer, `25`) ... Number of elements to display per page. + filters (optional, string, `[{ "group": { "operator": "=", "values": ["1"] } }, { "name": { "operator": "=", "values": ["placeholder"] } }]`) ... JSON specifying filter conditions. Accepts the same format as returned by the [queries](#queries) endpoint. Currently supported filters are: + group: Name of the group in which to-be-listed placeholder users are members. + name: Filter placeholder users in whose first or last names, or email addresses the given string occurs. + status: Filter placeholder users by their status. Possible values are "active" and "locked" + sortBy (optional, string, `[["name", "asc"]]`) ... JSON specifying sort criteria. Accepts the same format as returned by the [queries](#queries) endpoint. Currently supported orders are: + id + name + group + Response 200 (application/hal+json) [PlaceholderUsers][] + Response 400 (application/hal+json) Returned if the client sends an unknown sort column. + Body { "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidQuery", "message": "Unknown sort column." } + Response 403 (application/hal+json) Returned if the client does not have sufficient permissions. **Required permission:** Administrator or manage_placeholder_user permission + Body { "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission", "message": "You are not authorized to access this resource." } ## Create placeholder user [/api/v3/placeholder_users] ## Create Placeholder User [POST] Creates a new placeholder user. Only administrators and users with manage_placeholder_user global permission are allowed to do so. When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body. + Request Create User (application/json) + Body { "name": "placeholder" } + Response 201 [PlaceholderUser][] + Response 400 (application/hal+json) Occurs when the client did not send a valid JSON object in the request body. + Body { "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody", "message": "The request body was not a single JSON object." } + Response 403 (application/hal+json) Returned if the client does not have sufficient permissions. **Required permission:** Administrator or manage_placeholder_user + Body { "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission", "message": "You are not authorized to access this resource." } + Response 422 (application/hal+json) Returned if: * a constraint for a property was violated (`PropertyConstraintViolation`) + Body { "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation", "message": "Name is already taken.", "_embedded": { "details": { "attribute": "name" } } }