Document toolboxDocument toolbox

Update User SOAP API

Owned by Matthew Wren
Jan 29, 2024
7 min read

On This Page:

Related Pages:

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

Description

Allows updates to be made to user accounts in ServiceScheduling.

Definition

The definition of this API is:

Web Service

Type

Description

Req?

Val?

<sp:UpdateUserRequest>

 




 

<userId>?</userId>

string(50)

The User ID for the user to be updated. The User ID must already exist in the ServiceOptimizer database.

(tick)

(tick)


<user>
Optional section containing the details of updates to the user to be made.



<name>?</name>string(50)If supplied, the value will be used as the new name of the user.



<enabled>?</enabled>BooleanIf supplied, the value will be used as the new value that defines if the user is permitted to use ServiceManager.



<profile>?</profile>string(10)If supplied, the value will be used as the new value for the user profile for the user. The user profile must exist in the ServiceOptimizer database
(tick)


<authentication>?</authentication>

AuthType

If supplied, the value will be used as the new value that defines how the user's login will be authenticated.

Either SECURED or LDAP.

If LDAP, then the user's login will be authenticated using the configured external LDAP server; otherwise, authentication will be performed by ServiceScheduling. See password below.





<password>?</password>string(50)

If supplied, the value will be used as the new value for the user's password, if the authentication is set to INTERNAL. Ignored if authentication is LDAP.





<unitType>?</unitType>UserUnitType

If supplied, the value will be used as the new value for the user's unit type.

This can be ROOT, BRU, DRU or FRU.





<respUnit>?<respUnit>string(8)

If supplied, the value will be used as the new value for the user's RU.

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.


(tick)

</user>




<role>

Optional section containing the details of updates to user roles and formal parameters. The <role> section may be repeated zero or more times, as required.





<action>?</action>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.

(tick)


<id>?</id>int

A valid role.

Required for each <role> section supplied.

(tick)(tick)


<formalParameter>

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.






<parameterType>?</parameterType>

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.

(tick)(tick)



<parameterName>?</parameterName>string(20)

The name of the formal parameter.

Required for each <formalParameter> section supplied.

(tick)(tick)



<value>?</value>string(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.

(tick)(tick)



<assignmentType>?</assignmentType>

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.

(tick)


</formalParameter>





...
Optional, additional formalParameter sections, as required.


</role>




...
Optional, additional <role> sections, as required.

</sp:UpdateUserRequest>

 




Examples

Assume that a new user has been created using the Create User SOAP API, and that this user's ID is 45.

No Formal Parameter Example

Assume that a role with ID of 4 has been defined, which has the following permissions defined:

  • System.Planner : ALL

That is:

  • The role grants permissions to use ServicePlanner.

The following is a valid way to grant the user the permission to use SystemPlanner:

<sp:UpdateUserRequest>
  <login>
    <databaseUser>DBuser</databaseUser>
    <password>password</password>
    <spUser>exampleUser</spUser>
  </login>
  <userId>45</userId>
  <role>
    <action>ADD</action>
    <id>4</id>
  </role>
</sp:UpdateUserRequest>

The above uses the action of ADD to add the role with ID of 4 to the user. As the role does not have any formal parameters for its permissions, no formal parameters are required in the API call.

Formal Parameter Examples

Assume that a role with ID of 5 has been defined, which has the following permissions defined:

  • FRU(FRU_ID:FM) : R
  • FRU(FRU_ID.FM).Team : ALL

That is:

  • The role grants:
    • Read permission to the FRU that is set via the parameter name of FM
    • Create, Read, Update and Delete permissions at the Team level in the FRU that is set via the parameter name of FM

Example 1

The following (with a login clause) is a valid way to grant the user the permission to access the Eastern Region and Western Region FRUs (where east_ref and west_ref are the reference values for the FRUs):

<sp:UpdateUserRequest>
  ...
  <userId>45</userId>
  <role>
    <action>ADD</action>
    <id>5</id>
    <formalParameter>
      <parameterType>FRUID</parameterType>
      <parameterName>FM</parameterName>
      <value>east_ref</value>
      <assignmentType>EQ</assignmentType>
    </formalParameter>
    <formalParameter>
      <parameterType>FRUID</parameterType>
      <parameterName>FM</parameterName>
      <value>west_ref</value>
      <assignmentType>EQ</assignmentType>
    </formalParameter>
  </role>
</sp:UpdateUserRequest>

The above uses the action of ADD to add the role with ID of 5 to the user. As the role has an FRU_ID formal parameter of FM for its permissions, this formal parameter is required at least once in the API call.

In this case, the formal parameter is given twice, with different values, to add the role with ID of 5 to the user for two different FRUs (i.e. the Eastern Region and the Western Region FRUs).

Example 2

Assuming Example 1 above has been called, then the following is a valid way to additionally grant the user permission to access the Northern Region FRU (where nrth_ref is the reference value for the FRU):

<sp:UpdateUserRequest>
  ...
  <userId>45</userId>
  <role>
    <action>UPDATE</action>
    <id>5</id>
    <formalParameter>
      <parameterType>FRUID</parameterType>
      <parameterName>FM</parameterName>
      <value>east_ref</value>
      <assignmentType>EQ</assignmentType>
    </formalParameter>
    <formalParameter>
      <parameterType>FRUID</parameterType>
      <parameterName>FM</parameterName>
      <value>west_ref</value>
      <assignmentType>EQ</assignmentType>
    </formalParameter>
    <formalParameter>
      <parameterType>FRUID</parameterType>
      <parameterName>FM</parameterName>
      <value>nrth_ref</value>
      <assignmentType>EQ</assignmentType>
    </formalParameter>
  </role>
</sp:UpdateUserRequest>

The above uses the action of UPDATE to replace the existing assignment of the role with ID of 5 for the user with a new set of formal parameters.

It is not possible to use an action of ADD, as the user already has had the role with ID of 5 added. This is why the action of UPDATE must be used to change the details of a role that has already been granted to a user.

In addition, when using the action of UPDATE, as noted in the documentation above, any current formal parameters for the defined role being deleted from the user, and replaced with the supplied formal parameters. This is why all of the three desired formal parameters need to be supplied in the UPDATE to result in the (effective) addition of one new formal parameter.

Example 3

Assuming Example 2 above has been called, then the following is a valid way to remove the user's permission to access the Northern Region FRU:

<sp:UpdateUserRequest>
  ...
  <userId>45</userId>
  <role>
    <action>UPDATE</action>
    <id>5</id>
    <formalParameter>
      <parameterType>FRUID</parameterType>
      <parameterName>FM</parameterName>
      <value>east_ref</value>
      <assignmentType>EQ</assignmentType>
    </formalParameter>
    <formalParameter>
      <parameterType>FRUID</parameterType>
      <parameterName>FM</parameterName>
      <value>west_ref</value>
      <assignmentType>EQ</assignmentType>
    </formalParameter>
  </role>
</sp:UpdateUserRequest>

The above uses the action of UPDATE to replace the existing assignment of the role with ID of 5 for the user with a new set of formal parameters.

Example 4

The following is a valid way to remove the user's permissions granted by the role with ID of 5 completely:

<sp:UpdateUserRequest>
  ...
  <userId>45</userId>
  <role>
    <action>REMOVE</action>
    <id>5</id>
  </role>
</sp:UpdateUserRequest>

The above uses the action of REMOVE to remove the assignment of the role with ID of 5 from the user.

In this case, no formal parameters are required, even though the role defines formal parameters in its permissions, as the role is being removed from the user.

Return Structure

The API returns the standard return structure.

Return Codes

In addition to the Standard Return Codes, the possible Return Codes from this API are:

  • 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)