Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Status
colourGreen
title5.4.0

A pass-through API to ServiceScheduling Scheduling (when configured) which allows the ServiceSchedulingScheduling's UpdateUserRequest API to be called.  

Description

The sp:UpdateUserRequest API method can be used to update user account details in the ServiceScheduling Scheduling system, as an alternative to the ServiceManager UI for managing users.  


Panel
borderColorgrey
bgColorwhitesmoke
borderStylesolid

On this page:

Table of Contents
maxLevel2

Related pages:


Resource URL Summary


Panel
borderColorgrey
bgColorwhitesmoke
borderStylesolid

Pass Through Call to ServiceSchedulingScheduling's "UpdateUserRequest" API

PUT /up/v5/rest/scheduling/UpdateUser

Include Page
_Default HTTP Headers
_Default HTTP Headers


API Specifics



Panel
borderColor#D3D3D3

Pass Through Call to

ServiceScheduling

Scheduling's "UpdateUserRequest" API

This RESTified API will perform a pass-through call to the ServiceScheduling Scheduling sub-system's "UpdateUserRequest" API (when configured).

URL

Panel
borderColorgrey
bgColorwhitesmoke
borderStylesolid

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 Scheduling "UpdateUserRequest" API.

UpdateUser Object Format

Code Block
languagejs
titleUpdateUser
collapsetrue
{
	"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)

PropertyTypeLengthDescriptionReq?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

userobjectN/A

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


PropertyTypeLengthDescriptionReq?ServiceDispatch Field Mapping
namestring50

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

enabledboolean

If true, the new user is permitted to use ServiceManager.

yes

user.enabled

profilestring10

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 ServiceSchedulingScheduling. See password below.

yes

user.authentication

passwordstring50

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

respUnitstring8

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 DRUrespUnit must be an DRU reference.

If unitType is FRU, respUnit must be an FRU reference. 

yed

user.respUnit


yes

-

roleobject


PropertyTypeLengthDescriptionReq?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

formalParameterobject

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


PropertyTypeLengthDescription
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

parameterNamestringSS: 20

The name of the formal parameter.

Required for each <formalParameter> section supplied.

SS Field: role.formalParamter.parameterName

valuestringSS: 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 ServiceScheduling Scheduling "UpdateUserRequest" API response will be returned.

Code Block
languagejs
{
    "Success": true,
    "Code": 0,
    "Message": "OK",
    "Payload": {
        "result": {
            "type": "OK",
            "code": "0"
        }
    }
}

Error

On error, a JSON-formatted version of the ServiceScheduling Scheduling "UpdateUserRequest" API response will be returned.

Code Block
languagejs
{
    "Success": false,
    "Code": 9,
    "Payload": {
        "returnCode": {
            "type": "Error",
            "code": "SCH Error Code"
        }
    }
}

Return Codes

In addition to to the  Standard Return Codes, and the Scheduling Error codes, the possible Return Codes from this API are:

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)