Document toolboxDocument toolbox

Integration ServiceOptimizer Update User Job Derestriction SOAP API

Owned by Matthew Wren
Nov 24, 2022
2 min read

On This Page:

Related Pages:

The sp:UpdateUserDerestrictionsRequest API method can be used to:

  • Add restriction types to a user, to grant access to restricted jobs with the matching restriction type; and/or
  • Remove restriction types from a user, to remove access to restricted jobs with the matching restriction type.

Description

Allows restriction types for restricted jobs to be added and/or removed from ServiceGANTT users. 

Definition

The definition of this API is:

Web Service

  

Type

Description

Req?

Val?

<sp:UpdateUserDerestrictionsRequest>

 

 

 

 

 

<userId>?</userId>

string(50)

The User ID of the ServiceGANTT user for which restriction types are to be added and/or removed.

(tick)

(tick)

 <restrictions> Mandatory section.(tick)(tick)
  <remove> An optional section of one or more restriction types which should be removed from the ServiceGANTT user.(error) 
   <ref>?</ref>RestrictionRef

If the <remove> section is included in the API call, then at least one <ref> section must be included, specifying a restriction type to be removed from the ServiceGANTT user.

(tick)(tick)
   ... Additional <ref> sections, if required.(error) 
  </remove>    
  <add> An optional section of one or more restriction types which should be added to the ServiceGANTT user.(error) 
   <ref>?</ref>RestrictionRef

If the <add> section is included in the API call, then at least one <ref> section must be included, specifying a restriction type to be added to the ServiceGANTT user.

(tick)(tick)
   ... Additional <ref> sections, if required.(error) 
  </add>     
 </restrictions>    

</sp:UpdateUserDerestrictionsRequest>

 

 

 

 

If neither of the <add> or <remove> sections are included, this will be silently ignored, and SP_OK will be returned.

The API is atomic. That is, if processing any parts of the API call result in a failure, then the whole operation is rolled back, and no changes are committed.

The <remove> section is processed by the API first, followed by the <add> section. Therefore, if an API call is made to add and remove the same restriction type in the same call, then:

  • If the user did not previously have the restriction type added, then the API call will fail, on account of the <remove> not being valid; or
  • If the user did previously have the restriction type added, then the overall result will be no change at end of the operation (that is, the restriction type will first be removed, and then re-added).

Duplicate restriction types in the <add> section will return SP_USER_DERESTRICTION_EXISTS (698) (when attempting to add the duplicate), and the entire operation will fail.

Duplicate restriction types in the <remove> section will return SP_RESTRICTION_REF_DOES_NOT_EXIST (697) (when attempting to remove the duplicate), and the entire operation will fail.

A user's restriction types are cached in the ServiceGANTT session, so changes to the restricted jobs that a user is permitted to access will only take effect when the user next logs in to ServiceGANTT, or switches to a new FRU.

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_RESTRICTION_REF_DOES_NOT_EXIST (697)
  • SP_USER_DERESTRICTION_EXISTS (698)
  • SP_USER_DERESTRICTION_DOES_NOT_EXIST (699)
  • SP_USERID_DOES_NOT_EXIST (703)