Pass Through Call to Scheduling's "UpdateUserRequest" API
This RESTified API will perform a pass-through call to the Scheduling sub-system's "UpdateUserRequest" API (when configured).
URL
PUT /up/v5/rest/scheduling/UpdateUser
HTTP Request Body
This request requires a JSON object supplied in the HTTP request body, which defines the parameters that will be passed through to the Scheduling "UpdateUserRequest" API.
{
"userId": "",
"user": {
"name": "",
"enabled": "",
"profile": "",
"authentication": "",
"password": "",
"unitType": "",
"respUnit": ""
},
"role": {
"action": "",
"id": "",
"formalParameter": {
"parameterType": "",
"parameterName": "",
"value": "",
"assignmentType": ""
}
}
}
UpdateUser Object Properties (Bold property name indicates required field)
| Property | Type | Length | Description | Req? | ServiceDispatch Field Mapping |
|---|
| userId | string
| SS: 50 | A new User ID for the user to be created. The User ID must not already exist in the ServiceOptimizer database. | Yes | empID |
| user | object | N/A | Required section containing the details of the new user to be added.
| Property | Type | Length | Description | Req? | ServiceDispatch Field Mapping |
|---|
| name | string | 50 | A new User ID for the user to be created. The User ID must not already exist in the ServiceOptimizer database. If supplied, the value will be used as the new name of the user. SS Field: | yes | user.name | | enabled | boolean |
| If true, the new user is permitted to use ServiceManager. | yes | user.enabled | | profile | string | 10 | The user profile for the user to be created. The user profile must exist in the ServiceOptimizer database. | yes | user.profile | | authentication | string SS: AuthType |
| Either SECURED or LDAP. If LDAP, then the new user's login will be authenticated using the configured external LDAP server; otherwise, authentication will be performed by Scheduling. See password below. | yes | user.authentication | | password | string | 50 | The new user's password. Ignored if authentication is LDAP. | yes | user.password | | unitType | string
|
| The values can be ROOT,BRU,DRU or FRU. Defaults to ROOT if omitted during creation. | yes | user.unitType | | respUnit | string | 8 | If unitType is ROOT, respUnit must be the top level RU, and will default to this if omitted. If unitType is BRU, respUnit must be an BRU reference. If unitType is DRU, respUnit must be an DRU reference. If unitType is FRU, respUnit must be an FRU reference. | yed | user.respUnit |
| yes | - |
| role | object |
| | Property | Type | Length | Description | Req? | ServiceDispatch Field Mapping |
|---|
| action | string SS: RoleAction |
| One of ADD, UPDATE or REMOVE. - When
ADD, the <role> section will result in the defined role (and supplied formal parameters, if any) being added to the user. - When
UPDATE, the <role> section will result in any current formal parameters for the defined role being deleted from the user, and replaced with the supplied formal parameters (if any). - When
REMOVE, the <role> section will result in the defined role (and any associated formal parameters) being deleted from the user.
Required for each <role> section supplied. | Yes | role.action | | id | string SS: integer |
| A valid role. Required for each <role> section supplied. | Yes | role.id | | formalParameter | object |
| Optional section containing the details of updates to user formal parameters. The <formalParameter> section may be repeated zero or more times, as required. Each supplied <formalParameter> section will be attempted to be matched against the required parameters defined by the supplied role <id> in the current <role> section. Only when the <formalParameter>'s <parameterType> and <parameterName> match a required parameter will the formal parameter be added - supplying a <formalParameter> section that does not match a defined formal parameter of the supplied role will result in an error. So, for example, if the supplied role <id> defines that FRU(FRU_ID.F).Team.Oper is a formal parameter, then in the <formalParameter> section: - The
<parameterType> must be FRUID; - The
<parameterName> must be "F"; and - The
<value> must be a single value for parameter F.
Note that multiple values may be supplied for the same <parameterType> and <parameterName> by supplying a separate <formalParameter> section for each value. If you provide the same parameterName, type and value multiple times this will result in a error. The <formalParameter> section is ignored when the <action> is REMOVE
| Property | Type | Length | Description |
|---|
| parameterType | string SS: ParameterID |
| One of FRUID, OPERID or TEAMID. - When
FRUID, the supplied formal parameter <value> will be used where the supplied role defines a formal parameter of the FRU_ID parameter type with name <parameterName>. - When
OPERID, the supplied formal parameter <value> will be used where the supplied role defines a formal parameter of the OPER_ID parameter type with name <parameterName>. - When
TEAMID, the supplied formal parameter <value> will be used where the supplied role defines a formal parameter of the TEAM_ID parameter type with name <parameterName>.
Required for each <formalParameter> section supplied. SS Field: role.formalParamter.parameterType | | parameterName | string | SS: 20 | The name of the formal parameter. Required for each <formalParameter> section supplied. SS Field: role.formalParamter.parameterName | | value | string | SS: 50 | The value for the formal parameter, being: - the FRU reference of the FRU;
- the Operative reference of the Operative; or
- the Team name of the Team
as required (based on the <parameterType> value). Alternatively, the wildcard value of "*" (without quotes) can be used, to mean either all FRUs, all Operatives, or all Teams (depending on the <parameterType>). Required for each <formalParameter> section supplied. SS Field: role.formalParamter.value | | assignmentType | string SS: AssignmentType |
| One of EQ or NEQ. Defines if permission should be given based on the role's formal parameter matching (EQ), or not matching (NEQ). Required for each <formalParameter> section supplied. SS Field: role.formalParamter.assignmentType |
| Yes | - |
| yes | - |
HTTP Response
Success
On success, a JSON-formatted version of the Scheduling "UpdateUserRequest" API response will be returned.
{
"Success": true,
"Code": 0,
"Message": "OK",
"Payload": {
"result": {
"type": "OK",
"code": "0"
}
}
}
Error
On error, a JSON-formatted version of the Scheduling "UpdateUserRequest" API response will be returned.
{
"Success": false,
"Code": 9,
"Payload": {
"returnCode": {
"type": "Error",
"code": "SCH Error Code"
}
}
}
Return Codes
In addition to the Standard Return Codes, and the Scheduling Error codes, the possible Return Codes from this API are:
Click here to expand...
- SP_USERID_DOES_NOT_EXIST (703)
SP_PROFILE_DOES_NOT_EXIST (704)SP_UNIT_REF_INVALID (705)SP_ROLE_ID_DOES_NOT_EXIST (706)SP_PARAMETER_VALUE_DOES_NOT_EXIST (707)SP_PARAMETER_TYPE_INVALID (708)SP_ROLE_EXISTS (709)SP_ROLE_DOES_NOT_EXIST (800)SP_PARAMETER_TYPE_DUPLICATED (801)SP_PARAMETER_NAME_LEFT_UNDEFINED (802)
