User endpoints

User endpoints¶

This endpoint allows users to be created, modified or deleted and is visible from the path:

<api-root>/scim/v2/Users

By default, users for whom the value of the FLAG_ELIMINATED ('deleted flag') column within the REP_USER table is equal to DELETED('1'), RECODED('2') or FORGOTTEN('5') are filtered out and cannot be extracted by the SCIM API.

Operations¶

Operation	Http Method	Body of the request	Path variable	Query string parameters	Body of the answer	HTTP response body	Response Status (SCIM Exception)
Create	POST	User	-	-	User	201 (Created)	405 (Method not permitted) 409 (Conflict)
Read	GET	-	userId	-	User	200 (OK)	404 (Not found)
Delete	DELETE	-	userId	-	-	200 (OK)	404 (Not found)
Replace	PUT	User	userId	-	User	200 (OK)	404 (Not found)
Search	GET	-	-	filter sortBy sortOrder startIndex count (all parameters are optional)	User List	200 (OK)	400 (Invalid request) 405 (Method not permitted)
Update	PATCH	PatchRequest	userId	-	User	200 (OK)	400 (Invalid request) 404 (Not found)

SCIM exceptions¶

Examples of invocation

HTTP Status	Descriptions
400 (Invalid request)	It occurs when the request does not match the service specification, e.g. by invoking the 'search' method when the filter is not well defined (wrong parameters/syntax errors) or by invoking the 'update' method when the Patch request is invalid.
404 (Not found)	It occurs when the requested resource is non-existent; for example, if an attempt is made to replace, update, search or delete a user but there is no user matching the identification code used.
405 (Method not permitted)	It occurs when the HTTM method is not permitted for the requested endpoint or if the serialised object supplied does not correspond to the object expected by that method. For instance, when an incorrect user object is provided in the body of the request.
409 (Conflict)	This occurs when, for example, a request is made to create a new user using a user ID code already in use in the system.

Supported standard SCIM fields¶

The following table shows the standard SCIM user fields supported.

SCIM User Field	Supported cardinality (collection only)	Supported Values
userName	-	-
name.givenName	-	-
name.familyName	-	-
emails	only 1	String Formula for establishing type work
phoneNumbers	only 1	String Formula for establishing type work
meta.lastModified
password
userType		L(Local)/E(External)
groups
preferredLanguage	only 1	*LanguageCaption - CountryCaption
active		True/False

*Note: the preferredLanguage field only supports values in the format LanguageCaption - CountryCaption (example: en-US) and only values managed by the Tagetik application are allowed¶

If values are used for the preferredLanguage field that do not comply with the required format or are not managed by the application during creation or update, a Status Code '400 Bad request' is sent with an error message 'Invalid Language Code' or 'Language Code Not Managed'.

Custom fields¶

The following table shows the custom user fields of CCH Tagetik.

SCIM User Field	Description	Supported Values
userReferences	Indicates the existing user from whom the new user will inherit roles	-
locked	user lock status	True/False (immutable, equal to the opposite of the 'active' field)
mustChangePwdAtNextLogin	Forces user to change password at next login	True/False
interactionType	Client interaction type	0 (interactive)/1 (Machine to Machine)
lastLogin	Last access in application	-
validityStartDate	Validity start date	**
validityEndDate	Validity end date	**
descriptionLanguage	Descriptions Language	-
userRoles	The list of databases the user can access and the corresponding role	-
dbAllowed	List of databases associated with the user, with ID, description and lock status	-

**Note: when creating or updating, it is possible to specify the time for the fields validityStartDate and validityEndDate. Nevertheless, any time entered is ignored and replaced with '00:00:00' for both fields.

SCIM Enterprise User Schema Extension fields¶

The following table shows the supported Enterprise scheme user fields.

SCIM User Field	Description	Supported Values
department	Specifies the user's department	-

¶

Examples¶

Show list of all users
Method	GET
URL	`<api-root>/scim/v2/Users`
Body	-
Note

Get single user
Method	GET
URL	`<api-root>/scim/v2/Users/MYUSER`
Body	-
Example answer	{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:tgk:params:scim:schemas:extension:2.0:User", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" ], "id": "MYUSER", "externalId": "MYUSER", 'meta': { "resourceType': 'User', "lastModified": 1700149220782 }, "userName": "MYUSER", "name': { "familyName": "My", "givenName": "User". }, "userType': 'E', "preferredLanguage': 'en-IT', "active": true, "emails": [ { "value": "myuser@example.com" } ], "partiallyBlocked': false, "urn:tgk:params:scim:schemas:extension:2.0:User": { "userReferences": [ "REF_USER_CODE" ], "locked": false, "mustChangePwdAtNextLogin": false, "interactionType": "INTERACTIVE", "lastLogin": "2024-01-01T10:10:10.000Z", "validityStartDate": "2020-01-01T00:00:00Z", "validityEndDate": "2030-01-01T00:00:00Z", "descriptionLanguage": "es", "userRoles": [ { "dbId": "[!]", "role": "$ALL" }, { "dbId": "TCPM_DEMO_DEV", "role": "$ALL" } ], "dbAllowed": [ {"id": "TCPM_DEMO_DEV", "description": "TCPM_DEMO_DEV", "locked": false}] }, "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { "department": "User Department" }
Note	With this request we obtain the attributes of an existing user MYUSER with the preferredLanguage 'en-IT'.

Create new user
Method	POST
URL	`<api-root>/scim/v2/Users`
Body	{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "externalId": "MYUSER", "userName": "MYUSER", "userType': 'E', "active": true, "preferredLanguage': 'en-IT', "emails":[ { "value":"myuser@example.com", "type":"work", "primary": true } ], "name": { "familyName": "User", "givenName": "My" }, "urn:tgk:params:scim:schemas:extension:2.0:User": { "userReferences": [ "REF_USER_CODE" ], "descriptionLanguage": "it" } }
Note	This request adds an external user MYUSER with email myuser@example.com and with preferredLanguage 'en-IT', and sets the reference user to 'REF_USER_CODE'.

Apply changes to existing users
Method	PATCH
URL	`<api-root>/scim/v2/Users/MYUSER`
Body	{ "schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp", "urn:tgk:params:scim:schemas:extension:2.0"], "Operations":[{ "op":"add", "path":"urn:tgk:params:scim:schemas:extension:2.0:User:userReferences", "value":["REF_USER_CODE"]}] }
Note	This request adds the reference user 'REF_USER_CODE' to the existing user 'MYUSER'. To replace the existing reference user, use " `"op":"replace"` instead of `"op":"add"`.

Apply changes to user roles
Method	PATCH
URL	`<api-root>/scim/v2/Users/MYUSER`
Body	{ "schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp", "urn:tgk:params:scim:schemas:extension:2.0"], "Operations":[{"op":"add", "path":"urn:tgk:params:scim:schemas:extension:2.0:User:userRoles", "value":[{"dbId":"DB_ID", "role":"COD_RUOLO"}]}] }
Note	This request adds the role 'COD_RUOLO' to the existing user 'MYUSER' for the database 'DB_ID'. To replace the role, use ' `"op":"replace"` instead of `"op":"add"`. Please note that, starting from SP34, for the add and replace operations involving the user–application DB association, the "Application DB Restrictions" field will be set to "Restricted" by default, in order to ensure the same behaviour as the CCH Tagetik web interface.

Assign type 'work' to email
Method	PATCH
URL	`<api-root>/scim/v2/Users/MYUSER`
Body	{ "schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp", "urn:tgk:params:scim:schemas:extension:2.0", "urn:ietf:params:scim:schemas:extensions:enterprise:2.0:User"], "Operations":[{"op":"add", "path":"emails[type eq \"work\"].value", "value":"test@test.it"}]}] }
Note	This request modifies the 'email' field to set its type to ‘work’.

Delete user
Method	DELETE
URL	`<api-root>/scim/v2/Users/MYUSER`
Body	-
Note	This request deletes the MYUSER user.