Histórico da Página

Document status	Finished
Date	2/14/2018
Version	2.0
Previous version	1.0
Authors	Jandir Deodato De Souza Silva, Danilo Basilio Medeiros

Content

1 Rest users
2 Methods available
- 2.1 GET
3 Parameters
4 Parameters
- 4.1 GET (GetUserId)
- 4.2 POST
5 Parameters
- 5.1 PUT
6 Parameters
- 6.1 DELETE
7 Parameters

Rest users

The SCIM 'users' is a protocol of application REST for the provision and management of identity data in the web. The protocol support the creation, modification, recover and discovery of users.

The service users of Protheus enables the inclusion and manipulation of users data in the system. It is highly recommendable the authentication of services to be enabled in the rest server to avoid improper manipulation of data. All users authenticating to use this service must have access to routine CFGA510 (the register of users in Protheus)
D

etails of REST Protheus configuration and how to connect the authentication of the services, access REST Protheus page here.

Aviso

title	Notification

Via REST, you can only perform the basic creation of the user. To configure permissions, accesses, menus etc, you need to use Identity.ty.

Methods available

GET

Syntax /users/{userId}

To recover a known user, the customers send GET requests. If the user exists, the server responds with the state 200 code and adds result in the body of the answer. You can also list the users of the system, omitting the submission of pathParam {userId}.

Parameters

pathParam

Name	Type	Description	Default
userId	string	id or user code in the system

queryParam

Name	Type	Description	Default
showAdmin	boolean	Indicates whether get must return to admin user	false
count	numeric	Indicates how many users must return by method	All
startIndex	numeric	Indicates from which user found, the return must happen.	1
attributes	string	Indicates which attributes of jSon must return. The attributes must be separated by ','.	Return all attributes

Notification:
The parameters attributes is case sensitive.

Return:

Parameters

Body

Name	Type	Description
totalResults	numeric	Indicates the number of records found
itemsPerPage	numeric	Number of items returned in the request
startIndex	numeric	Record "from" the return of records
Id	string	Id or code of user in Protheus
goal	jSon	Related to the creation of user
created	String	Date of user creation. Returns in the format YYYY-MM-DD_HH:MM:SS
lastModified	String	Data of last change of the user. Returns in the format YYYY-MM-DD_HH:MM:SS
externalId	string	External code of the user (e-mail for the majority of the systems)
name	string	Code of user in the system
givenName	string	First name of the user
familyName	string	Second name of the user
displayName	string	name of user in the system
emails	array of objects
emails:value	string	E-mail in the system
emails:type	string	Type of e-mail. Always return "work"
primary	boolean	Indicates whether it is the primary e-mail of the user. Always returns true
active	boolean	Returns whether the user is active in the system
groups	array of objects	Groups to which the user belongs
groups:value	string	Group code
groups:display	string	Group Description
title	string	User position
employeeNumber	string	Employee code
department	string	Code of the user department
manager	array of objects	Information of the user's leaders
manager:manageId	string	Code of the user's leader
manager:displayName	string	Name of the leader in the system

Example of return json

Wiki Markup

{
    "schemas": \[
        "urn:scim:schemas:core:2.0:User",
        "urn:scim:schemas:extension:enterprise:2.0:User"
    \],
    "id": "000021",
    "meta": \{
        "created": "2018-02-13_00:00:00",
        "lastModified": "2018-02-13_00:00:00"
    \},
    "externalId": "[email protected]",
    "userName": "User1",
    "name": \{
        "formatted": "User1",
        "givenName": "User1",
        "familyName": "."
    \},
    "displayName": "Use1r",
    "emails": \[
        \{
            "value": "[email protected]",
            "type": "work",
            "primary": true
        \}
    \],
    "active": true,
    "groups": \[
        \{
            "value": "000001",
            "display": "grupo2"
        \}
    \],
    "title": "Coordenador",
    "employeeNumber": "02|00|000001",
    "department": "RH",
    "manager": \[
        \{
            "managerId": "000000",
            "displayName": "Administrador"
        \}
    \]
\}

The search for a user by the Id differs only of the omission in the result of parameters _totalResult{_}, _itensPerPage_ and _startIndex{_}.

GET (GetUserId)

Syntax /users/GetUserId
Returns id of the user currently logged by the REST service in Protheus.

Example of method return
{
"userID": "000000"
}

POST

Syntax /users/{userid}/{operation}

Creates new users in the system developing in the request, when successful, the respond code 201 (created).

Parameters

pathParam

Name	Type	Description	Default
userId	string	User code in the system (POST to block or unblock an existing user. To block or unblock, send operation parameter)
operation	string	Values accepted: activate and deactivate. Indicates whether user is activated in the system (activate) or whether the user is blocked via SAML (deactivate) or whether a new user is created (parameter blank or any other value different than the previous one. If parameter userId is sent, but parameter operation was not sent, we assume a new user was created in the system

body

Name	Type	Description	Default
userName	string	User name	value of attribute ext/adDomain
displayName	string	full name of user
externalId	string	External code of user	External code of user. When sent, it indicates the user blocked via SAML is reactivated. The Submission of an externalld that does not exist generates the inclusion of a new user.
title	string	User position
emails * ^mandatory	array of objects	The first e-mail with primary value indicated as true is the e-mail registered for the user (you need, at least, a primary e-mail. Any non-primary e-mail sent is discarded). If the e-mail sent already exists in other user, the e-mail is blank.
emails:value	string	E-mail code
emails:primary	boolean	Indicates whether it is a primary e-mail
active	boolean	indicates whether user is active or blocked	true
groups	array of objects	groups to which the user is associated
groups:value * ^mandatory	string	group code
password	string	user password. When password is not informed, the admin must change it.	random hash.
ext/SAMAccountName	string	Indicates the user login in SSO (if informed, it substitutes the value informed in the userName field)
ext/adDomain	string	SSO user domain
urn:scim:schemas:extension:enterprise:2.0:User	object	Indicates configurations of superior user
urn:scim:schemas:extension:enterprise:2.0:User:manager	array of objects	Array having information of superior user
urn:scim:schemas:extension:enterprise:2.0:User:manager:managerId	string	code of superior user
urn:scim:schemas:extension:totvs:2.0:User/forceChangePassword	boolean	Identifies whether you must change the password in the first access	false
urn:scim:schemas:extension:totvs:2.0:User/employeeNumber	string	Vínculo fincional do usuário. Values of Group of Companies, Branch and Code of the binding separated by "	". Example for group 18, branch D MG 01 and code 002: 18	D MG 01	002
urn:scim:schemas:extension:totvs:2.0:User/department	string	code of the user department
urn:scim:schemas:extension:totvs:2.0:User/groupRule	numeric	Defines the rule of prioritization per group: 1 prioritize, 2 disconsider and 3 add. Any value other than this, when sent, assumes value 1.

Example of request for inclusion of user:

Wiki Markup

{ 
   "schemas":\[ 
      "urn:scim:schemas:core:2.0:User",
      "urn:scim:schemas:extension:enterprise:2.0:User"
   \],
   "externalId":"TesteUsr",
   "meta":\{ 
\\
\\
   \},
   "userName":"Usr Tst",
   "displayName":"User",
   "title":"Coordenador",
   "emails":\[ 
      \{ 
         "value":"[email protected]",
         "primary":true
      \}
   \],
   "active":true,
   "groups":\[ 
      \{ 
         "value":"000002"
      \}
   \],
   "password":"pass001",
   "urn:scim:schemas:extension:totvs:2.0:User/forceChangePassword":true,
   "urn:scim:schemas:extension:enterprise:2.0:User/employeeNumber":"02|00|000001",
   "urn:scim:schemas:extension:enterprise:2.0:User/department":"RH",
   "urn:scim:schemas:extension:totvs:2.0:User/groupRule":2,
   "ext/sAMAccountName":"user0007",
   "ext/adDomain":"XP01",
   "urn:scim:schemas:extension:enterprise:2.0:User":\{ 
      "manager":\[ 
         \{ 
            "managerid":"000000"
         \}
      \]
   \}
\}

PUT

Syntax /users/{userid}

Method used to update an existing user. All parameters can be sent, such as the POST method.

Parameters

pathParam

Name	Type	Description	Default
userId * ^mandatory	string	user code

Return: true, false or error generated.

DELETE

Syntax /users/{userid}

Method used to block an existing user. User is blocked, and all items bound to its record (groups, functional binding etc) are disassociated.

Parameters

pathParam

Name	Type	Description	Default
userId * ^mandatory	string	User code

Return: true, false or error generated.

Páginas filhas

Versões comparadas

Versão antiga 61

Nova versão 62

Chave

Rest users

Methods available

GET

Parameters

Parameters

GET (GetUserId)

POST

Parameters

PUT

Parameters

DELETE

Parameters