Pass Through Call to ServiceScheduling's "UpdateUserRequest" API

This RESTified API will perform a pass-through call to the ServiceScheduling 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 ServiceScheduling "UpdateUserRequest" API.

UpdateUser Object Format

UpdateUser

{
	"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?

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.

SS Field: empID

Yes

user

object

N/A

Required section containing the details of the new user to be added.

Property	Type	Length	Description
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: user.name
enabled	boolean		If true, the new user is permitted to use ServiceManager. SS Field: user.enabled
profile	string	10	The user profile for the user to be created. The user profile must exist in the ServiceOptimizer database. SS Field: 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 ServiceScheduling. See `password` below. SS Field: user.authentication
password	string	50	The new user's password. Ignored if `authentication` is `LDAP`. SS Field: user.password
unitType	string SS: UserUnitType		The values can be `ROOT,BRU,DRU` or `FRU`. Defaults to `ROOT` if omitted during creation. SS Field: 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. SS Field: user.respUnit

role

object

Property Type Length Description Req?

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.

SS Field: role.action

Yes

id

string

SS: integer

A valid role.

Required for each <role> section supplied.

SS Field: role.id

Yes

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

HTTP Response

Success

On success, a JSON-formatted version of the ServiceScheduling "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 ServiceScheduling "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, 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)

Resource URL Summary

HTTP Headers

API Specifics

Pass Through Call to ServiceScheduling's "UpdateUserRequest" API

URL

HTTP Request Body

UpdateUser Object Format

UpdateUser Object Properties (Bold property name indicates required field)

HTTP Response

Success

Return Codes

UpdateUser RESTified API

Resource URL Summary

HTTP Headers

API Specifics

Pass Through Call to ServiceScheduling's "UpdateUserRequest" API

URL

HTTP Request Body

UpdateUser Object Format

UpdateUser Object Properties (Bold property name indicates required field)

HTTP Response

Success

Return Codes