Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Panel
Table of Contents
maxlevel2

...

Formatting specifications for each web service, including details about parameter requirements, are provided.

...

List Users: URI Parameters 

Name

Description

Specifications

Required

showTokens

Show tokens.

Boolean

  • True - Includes the Token details

  • False (Default) - Empty Token List

N

Anchor
List Users XML and JSON Examples
List Users XML and JSON Examples
List Users: XML and JSON Examples

...

Name

Description

Specifications

Required

Mutually Exclusive With

userid

Unique ID for this User.


Y
(unless username
is specified)

username

username

Name used within the Controller to identify this User.

Maximum 40 alphanumerics.

Y
(unless userid
is specified)

userid

showTokens

Show tokens.

Boolean

  • True - Includes the Token details

  • False (Default) - Empty Token List

N


Anchor

...

 Description

...

URI

...

http://host_name/uc/resources/user/token

...

HTTP Method

...

DELETE

...

Description

...

Delete the personal access token(s)

...

Example URI

...

http://localhost:9090/uc/resources/user/token?tokenname=test1&username=abc

http://localhost:9090/uc/resources/user/token?tokenname=test1&userid=1234567

...

Authentication

...

HTTP Basic

...

Produces Content-Type

...

Consumes Content-Type

...

Example Responses

...

  • Status 200

    • Personal access token revoked successfully.

  • Status 400

    • Error message.

  • Status 403

    • Operation prohibited due to security constraints.

  • Status 404

    • A user with name “{name}” does not exist.

    • A user with id "{uuid}" does not exist.

  • Status 500

    • Unexpected request failure. See log(s) for more details.

Revoke Personal Access Token: Query Parameters

The following request parameters will be needed for the service.

...

Property

...

UI Field Name

...

Description

...

Specifications

...

Required

...

Mutually Exclusive With

...

userid

...

N/A

...

UUID of the user

...

UUID of the user

...

Y

...

username

...

username

...

N/A

...

User Name

...

String value of User name

...

N

...

userid

...

tokenname

...

token name

...

Token Name

...

Specifies the name of the application that will access the Universal Controller Web Service APIs using the personal access token.

...

Y

...

Property

...

UI Field Name

...

Description

...

Specifications

...

Required

...

Active

...

Specification for whether or not the user is active. An active user can log in to the Controller. An inactive user cannot log in to the Controller, and the user will not appear in user lists.

...

Boolean. Valid Values: true/false. Default is false.

...

N

...

Web Browser Access

...

Specification for whether or not the user can log in to the user interface.

Valid Values:

Default is – System Default – (0).

...

N

...

Business Phone

...

Properties
Properties
Properties

Anchor
User Properties
User Properties
User Properties

For the Modify User web service; specification for whether or not to exclude related records (User Permissions, User Roles) from the update, even if they are provided in the request.
 

Property

UI Field Name

Description

Specifications

Required

Anchor
active - USER
active - USER
active

Active

Specification for whether or not the user is active. An active user can log in to the Controller. An inactive user cannot log in to the Controller, and the user will not appear in user lists.

Boolean. Valid Values: true/false. Default is false.

N

Anchor
browserAccess - USER
browserAccess - USER
browserAccess

Web Browser Access

Specification for whether or not the user can log in to the user interface.

Valid Values:



Default is – System Default – (0).

N

Anchor
businessPhone - USER
businessPhone - USER
businessPhone

Business Phone

Business phone number of this user.


N

Anchor
commandLineAccess - USER
commandLineAccess - USER
commandLineAccess

Command Line Access

Specification for whether or not the user can log in to the Universal Controller Command Line Interface (CLI).

Valid values:



Default is – System Default – (0).

N

Anchor
department - USER
department - USER
department

Department

Business department of this user.


N

Anchor
email - USER
email - USER
email

Email

Email address of this user.


N

Anchor
excludeRelated - USER
excludeRelated - USER
excludeRelated

n/a

For the Modify User web service; specification for whether or not to exclude related records (User Permissions, User Roles) from the update, even if they are provided in the request.
 


Note
titleNote

In XML, excludeRelated is specified as an attribute in the <user> element.

Valid values: true/false (default is false).

N

Anchor
firstName - USER
firstName - USER
firstName

First Name

First Name of this user.


N

Anchor
lastName - USER
lastName - USER
lastName

Last Name

Last Name of this user.


N

Anchor
commandLineAccess lockedOut - USERcommandLineAccess
lockedOut - USER
commandLineAccess

Command Line Access

lockedOut

Locked out

Specification for whether or not the user can log in to the Universal Controller Command Line Interface (CLI).

Valid values:

Default is – System Default – (0)

is locked out of the Controller.

Boolean. Valid Values: true/false. Default is false.

N

Anchor
department loginMethod - USERdepartment
loginMethod - USER
departmentloginMethod

Department

Business department of this user.Login Methods

Login method(s) that the user can authenticate with.

Valid Values:


N

Anchor
email manager - USERemail
manager - USER
emailmanager

EmailManager

Email address Business manager of this user.

Manager user ID

N

Anchor
excludeRelated middleName - USERexcludeRelated
middleName - USER
excludeRelated

n/a

Note
titleNote

In XML, excludeRelated is specified as an attribute in the <user> element.

Valid values: true/false (default is false).

middleName

Middle Name

Middle Name of this user.


N

Anchor
firstName mobilePhone - USERfirstName
mobilePhone - USER
firstNamemobilePhone

First Name

First Name Mobile Phone

Mobile phone number of this user.


N

lockedOut - USERlockedOut

Locked out

Anchor
lastName passwordNeedsReset - USERlastName
passwordNeedsReset - USER
lastName

Last Name

Last Name of this user.

N

AnchorlockedOut - USER

passwordNeedsReset

Password Requires Reset

Specification for whether or not the user is locked out of the Controllerwill be prompted to reset the password at next login.

Boolean. Valid Values: true/false. Default is false.

N

Anchor
loginMethod retainSysIds - USERUserloginMethod
retainSysIds - USERUser
loginMethod

Login Methods

Login method(s) that the user can authenticate with.

Valid Values:retainSysIds

n/a

Specification for whether or not the Create a User web service will persist the sysId property.




Note
titleNote

In XML, retainSysIds is specified as an attribute in the <user> element.

Valid values: true/false (default is true).

N

Anchor
manager sysId - USERmanager
sysId - USER
managersysId

Manager

Business manager of this user.

Manager user IDn/a

System ID field in the database for this record.

Persisted only if retainSysIds is set to true.

N

Anchor
middleName timeZone - USERmiddleName
timeZone - USER
middleNametimeZone

Middle Name

Middle Name Time Zone

Time zone of this user.

N

AnchormobilePhone - USERmobilePhone - USERmobilePhone

Mobile Phone

Mobile phone number When this user logs in, all scheduling times will be shown in the user's time zone, unless the trigger specifies a different time zone.

N

Anchor
title - USER
title - USER
title

Title

Business title of this user.


N

Property

UI Field Name

Description

Specifications

Required

AnchorallGroups - PERMallGroups - PERMallGroups

Member of Any Business Service or Unassigned

Specification for whether or not this permission applies both to records that belong to any Business Service and to records that do not belong to any Business Service

Anchor
passwordNeedsReset userName - USERpasswordNeedsReset
userName - USER
passwordNeedsReset

Password Requires Reset

Specification for whether or not the user will be prompted to reset the password at next login.

Boolean. Valid Values: true/false. Default is false.

N

AnchorretainSysIds - UserretainSysIds - User retainSysIds

n/a

Specification for whether or not the Create a User web service will persist the sysId property.

Note
titleNote

In XML, retainSysIds is specified as an attribute in the <user> element.

Valid values: true/false (default is true).

N

AnchorsysId - USERsysId - USERsysId

n/a

System ID field in the database for this record.

Persisted only if retainSysIds is set to true.

N

AnchortimeZone - USERtimeZone - USERtimeZone

Time Zone

Time zone of this user.

When this user logs in, all scheduling times will be shown in the user's time zone, unless the trigger specifies a different time zone.

N

Anchortitle - USERtitle - USERtitle

Title

Business title of this user.

N

AnchoruserName - USERuserName - USERuserName

User ID

Log in ID for this user.

Y

AnchoruserPassword - USERuserPassword - USERuserPassword

Password

Password of this user.
 
If userPassword is included in the request, userPassword will be updated.

Used only by the Create a User and Modify a User web services.

Y
(for Create
a User)

AnchorwebServiceAccess - USERwebServiceAccess - USERwebServiceAccess

Web Service Access

Specification for whether or not the user can log in to the Universal Controller RESTful Web Services API.

Valid values:

Default is – System Default – (0).

N

...

userName

User ID

Log in ID for this user.


Y

Anchor
userPassword - USER
userPassword - USER
userPassword

Password

Password of this user.
 
If userPassword is included in the request, userPassword will be updated.

Used only by the Create a User and Modify a User web services.

Y
(for Create
a User)

Anchor
webServiceAccess - USER
webServiceAccess - USER
webServiceAccess

Web Service Access

Specification for whether or not the user can log in to the Universal Controller RESTful Web Services API.

Valid values:



Default is – System Default – (0).

N

Anchor
User Permission Properties
User Permission Properties
User Permission Properties

defaultGroupnameWildcardopCreateCreate

 
If the Strict Connection Execute Constraints Universal Controller system property is false:



If the Strict Connection Execute Constraints Universal Controller system property is true:


opExecute

 
Must be set to true if opCreate is set to true.

Boolean. Valid Values: true/false. Default is false.
 
If the Strict Business Service Membership Read Constraints Universal Controller system property is false:

opUpdateopswiseGroups

Applies this permission to records that are members of the selected Business Service(s).
 
XML

 
JSON

permissionType

Valid values:

sysId

Property

UI Field Name

Description

Specifications

Required

Anchor
allGroups - PERM
allGroups - PERM
allGroups

Member of Any Business Service or Unassigned

Specification for whether or not this permission applies both to records that belong to any Business Service and to records that do not belong to any Business Service.

Boolean. Valid Values: true/false. Default is false.

N

Anchor
commands - PERM
commands - PERM
commands

Commands

Commands that are associated with each permission.

Valid values: see #Command Permissions, below.

N

Anchor
defaultGroup - PERM
defaultGroup - PERM
defaultGroup

Unassigned to Business Service

Specification for whether or not this permission applies to records that do not belong to any Business Service.

Boolean. Valid Values: true/false. Default is false.

N

Anchor
nameWildcard - PERM
nameWildcard - PERM
nameWildcard

Name

Specification to apply this permission to records whose name matches the string specified here.

Wildcards (*'s) can be used.

Y

Anchor
opCreate - PERM
opCreate - PERM
opCreate

Create

Allows the user to create records of the specified permissionType.

Boolean. Valid Values: true/false. Default is false.
 
Cannot be set to true if permissionType is Agent.

N

Anchor
opDelete - PERM
opDelete - PERM
opDelete

Delete

Allows the user to delete records of the specified permissionType.

Boolean. Valid Values: true/false. Default is false.

N

Anchor
commands opExecute - PERMcommands
opExecute - PERM
commandsopExecute

Commands

Commands that are associated with each permission.

Valid values: see #Command Permissions, below.

N

Anchor
defaultGroup - PERMdefaultGroup - PERM

Unassigned to Business Service

Specification for whether or not this permission applies to records that do not belong to any Business ServiceExecute

Allows the user to execute records of the specified permissionType.

Boolean. Valid Values: true/false. Default is false.

N

Anchor
nameWildcard - PERMnameWildcard - PERM

Name

Specification to apply this permission to records whose name matches the string specified here.

Wildcards (*'s) can be used.

Y

Anchor
opCreate - PERMopCreate - PERM

N

Anchor
opRead - PERM
opRead - PERM
opRead

Read

Allows the user to create read records of the specified permissionType.

Boolean. Valid Values: true/false. Default is false.
 

Cannot be set to true if permissionType is Agent.

If the Strict Business Service Membership Read Constraints Universal Controller system property is false:


N

Anchor
opDelete opUpdate - PERMopDelete
opUpdate - PERM
opDeleteopUpdate

DeleteUpdate

Allows the user to delete update records of the specified permissionType.

Boolean. Valid Values: true/false. Default is false.

N

Anchor

N

Anchor
opswiseGroups - PERM
opExecute opswiseGroups - PERM
opExecute

Execute

Allows the user to execute records of the specified permissionType.

Boolean. Valid Values: true/false. Default is false.
 
If the Strict Connection Execute Constraints Universal Controller system property is false:

If the Strict Connection Execute Constraints Universal Controller system property is true:opswiseGroups

Member of Business Services

Applies this permission to records that are members of the selected Business Service(s).
 
XML


Panel


 
JSON


Panel


N

Anchor
opRead permissionType - PERMopRead
permissionType - PERM
opReadpermissionType

Read

Allows the user to read records of the specified permissionType.

N

Anchor
opUpdate - PERMopUpdate - PERM

Update

Allows the user to update records of the specified permissionType.

Boolean. Valid Values: true/false. Default is false.
 
Must be set to true if opCreate is set to true.

N

Anchor
opswiseGroups - PERMopswiseGroups - PERM

Member of Business Services

Panel
Panel

N

Anchor
permissionType - PERMpermissionType - PERM

Type

Type of permission for this user.

Y

Anchor
sysId - PERMsysId - PERM

n/a

System ID field in the database for a record.

Persisted only if retainSysIds is set to true.

N

...

Permission Type

Commands

Agent

  • ALL
  • resume_agent
  • suspend_agent

Agent Cluster

  • ALL
  • resolve_agent_cluster
  • resume_agent_cluster
  • suspend_agent_cluster
  • resume_agent_cluster_membership
  • suspend_agent_cluster_membership

Application

  • ALL
  • appl_start
  • appl_stop
  • appl_query

Bundle

  • ALL
  • promote_bundle

Calendar

  • ALL
  • copy_calendar

Credential

Database Connection

  • ALL
  • copy_database_connection
  • database_connection_test

Email Connection

  • ALL
  • copy_email_connection
  • email_connection_test

Email Template

  • ALL
  • copy_email_template

OMS Server

  • ALL
  • resume_oms_server
  • suspend_oms_server

PeopleSoft Connection

  • ALL
  • copy_peoplesoft_connection

Promotion Target

  • ALL
  • refresh_target_agents

SAP Connection

  • ALL
  • copy_sap_connection

Script

  • ALL
  • copy_script

SNMP Manager

  • ALL
  • copy_snmp_manager

Task

  • ALL
  • copy_task
  • launch
  • recalculate_forecast
  • reset_statistics
  • reset_zos_override_statistics
  • set_execution_restriction

Task Instance

  • ALL
  • cancel
  • clear_all_dependencies
  • clear_exclusive
  • clear_resources
  • clear_timewait
  • force_

    Type

    Type of permission for this user.

    Valid values:


    Y

    Anchor
    sysId - PERM
    sysId - PERM
    sysId

    n/a

    System ID field in the database for a record.

    Persisted only if retainSysIds is set to true.

    N

    Anchor
    Command Permissions
    Command Permissions
    Command Permissions

    Permission Type

    Commands

    Agent

    • ALL
    • resume_agent
    • suspend_agent

    Agent Cluster

    • ALL
    • resolve_agent_cluster
    • resume_agent_cluster
    • suspend_agent_cluster
    • resume_agent_cluster_membership
    • suspend_agent_cluster_membership

    Application

    • ALL
    • appl_start
    • appl_stop
    • appl_query

    Bundle

    • ALL
    • promote_bundle

    Calendar

    • ALL
    • copy_calendar

    Credential


    Database Connection

    • ALL
    • copy_database_connection
    • database_connection_test

    Email Connection

    • ALL
    • copy_email_connection
    • email_connection_test

    Email Template

    • ALL
    • copy_email_template

    OMS Server

    • ALL
    • resume_oms_server
    • suspend_oms_server

    PeopleSoft Connection

    • ALL
    • copy_peoplesoft_connection

    Promotion Target

    • ALL
    • refresh_target_agents

    SAP Connection

    • ALL
    • copy_sap_connection

    Script

    • ALL
    • copy_script

    SNMP Manager

    • ALL
    • copy_snmp_manager

    Task

    • ALL
    • copy_task
    • launch
    • recalculate_forecast
    • reset_statistics
    • reset_zos_override_statistics
    • set_execution_restriction

    Task Instance

    • ALL
    • cancel
    • clear_all_dependencies
    • clear_exclusive
    • clear_resources
    • clear_timewait
    • force_finish
    • force_finish_cancel
    • hold
    • insert_task
    • rerun
    • release
    • release_recursive
    • retrieve_output
    • set_edge_satisfied (Mark as Satisfied in UI)
    • set_edges_satisfied (Clear Predecessors in UI)
    • set_priority_low
    • set_priority_medium
    • set_priority_high
    • set_manual_completed
    • set_manual_started
    • skip
    • unskip

    Trigger

    • ALL
    • assign_trigger_execution_user
    • copy_trigger
    • disable_trigger
    • enable_trigger
    • recalculate_forecast
    • set_skip_count
    • trigger_now

    Variable


    Virtual Resource

    • ALL
    • copy_virtual_resource

    ...

    Anchor
    Create Personal Access Token
    Create Personal Access Token
    Create Personal Access Token


     Description

    URI

    http://host_name/uc/resources/user/token

    HTTP Method

    POST

    Description

    Create the personal access token

    Example URI

    http://localhost:8080/uc/resources/user/token

    Authentication

    HTTP Basic

    Produces Content-Type

    text/plain

    Consumes Content-Type

    Application/XML, Application/JSON

    Example Responses

    • Status 200

      • ucp_taUFeDdhrlpn8Gc5Vu9IO2LRQ29pbvBRJUSPvifX

    • Status 400

      • Error message.

    • Status 403

      • Operation prohibited due to security constraints.

    • Status 404

      • A user with name “{name}” does not exist.

      • A user with id "{uuid}" does not exist.

    • Status 500

      • Unexpected request failure. See log(s) for more details.

    Create Personal Access Token: Payload Properties (XML, JSON)

    Property

    UI Field Name

    Description

    Specifications

    Required

    Mutually Exclusive With

    Anchor
    userId
    userId
    userId

    N/A

    UUID of the user

    UUID of the user

    N

    userName

    Anchor
    userName
    userName
    userName

    N/A

    User Name

    String value of User name

    N

    userId

    Anchor
    name
    name
    name

    Token Name

    Token Name

    Specifies the name of the application that will access the Universal Controller Web Service APIs using the personal access token.

    Y


    Anchor
    expiration
    expiration
    expiration

    Expiration

    Description of property.

    Specifies when the personal access token expires. If left unspecified, the token never expires.

    N


    Create Personal Access Token: XML and JSON Examples


    XML

    JSON

    Example Request
    Expand
    titleXML
     <token>
            <expiration>2022-07-30</expiration>
            <name>test1</name>
            <userId></userId>
            <userName>sha</userName>
        </token>
    Expand
    titleJSON
    {
            "expiration": "2022-07-30",
            "name": "test1",
            "userName": "ops.admin",
            "userId": ""
        }
    Example Response
    Expand
    titleXML
    ucp_taUFeDdhrlpn8Gc5Vu9IO2LRQ29pbvBRJUSPvifP
    Expand
    titleJSON
    ucp_taUFeDdhrlpn8Gc5Vu9IO2LRQ29pbvBRJUSPvifP


    Anchor
    List Personal Access Tokens
    List Personal Access Tokens
    List Personal Access Tokens


     Description

    URI

    http://host_name/uc/resources/user/token/list

    HTTP Method

    GET

    Description

    List the user tokens

    Example URI

    http://localhost:9090/uc/resources/user/token/list

    http://localhost:9090/uc/resources/user/token/list?username=test

    http://localhost:9090/uc/resources/user/token/list?userid=1234567

    Authentication

    HTTP Basic

    Produces Content-Type

    Application/XML, Application/JSON

    Consumes Content-Type


    Example Responses

    • Status 200

      • Successful token list

    • Status 400

      • Error message.

    • Status 403

      • Operation prohibited due to security constraints.

    • Status 404

      • A user with name “{name}” does not exist.

      • A user with id "{uuid}" does not exist.

    • Status 500

      • Unexpected request failure. See log(s) for more details.

    List Personal Access Tokens: Query Parameters

    The following request parameters can be used to filter the results of this service.

    Property

    UI Field Name

    Description

    Specifications

    Required

    Mutually Exclusive With

    userid

    N/A

    UUID of the user

    UUID of the user

    N

    username

    username

    N/A

    User Name

    String value of User name

    N

    userid


    List Personal Access Tokens: XML and JSON Examples


    XML

    JSON

    Example Response
    Expand
    titleXML
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <tokens>
        <token>
            <createTime>2022-07-28 17:11:35 -0400</createTime>
            <expiration>20220730</expiration>
            <lastUsed>Never</lastUsed>
            <name>test2</name>
            <userName>ops.admin</userName>
        </token>
        <token>
            <createTime>2022-07-29 12:39:20 -0400</createTime>
            <expiration>20220730</expiration>
            <lastUsed>Never</lastUsed>
            <name>test3</name>
            <userName>ops.admin</userName>
        </token>
        <token>
            <createTime>2022-07-28 17:08:07 -0400</createTime>
            <expiration>20220730</expiration>
            <lastUsed>Never</lastUsed>
            <name>test4</name>
            <userName>ops.admin</userName>
        </token>
        <token>
            <createTime>2022-07-29 12:56:33 -0400</createTime>
            <expiration>20220730</expiration>
            <lastUsed>Never</lastUsed>
            <name>test5</name>
            <userName>ops.admin</userName>
        </token>
    </tokens>
    Expand
    titleJSON
    [
        {
            "createTime": "2022-07-28 17:11:35 -0400",
            "expiration": "20220730",
            "lastUsed": "Never",
            "name": "test2",
            "userName": "ops.admin"
        },
        {
            "createTime": "2022-07-29 12:39:20 -0400",
            "expiration": "20220730",
            "lastUsed": "Never",
            "name": "test3",
            "userName": "ops.admin"
        },
        {
            "createTime": "2022-07-28 17:08:07 -0400",
            "expiration": "20220730",
            "lastUsed": "Never",
            "name": "test4",
            "userName": "ops.admin"
        },
        {
            "createTime": "2022-07-29 12:56:33 -0400",
            "expiration": "20220730",
            "lastUsed": "Never",
            "name": "test5",
            "userName": "ops.admin"
        }
    ]

    ...

    Name

    Description

    Specifications

    Required

    Mutually Exclusive With

    userid

    Unique ID for this User.

    Y
    (unless username
    is specified)

    username

    username

    Name used within the Controller to identify this User.

    Maximum 40 alphanumerics.

    Y
    (unless userid
    is specified)

    userid

    showTokens

    Show tokens.

    Boolean

    • True - Includes the Token details

    • False (Default) - Empty Token List

    N

    Anchor
    Revoke Personal Access Token
    Revoke Personal Access Token
    Revoke Personal Access Token


     Description

    URI

    http://host_name/uc/resources/user/token

    HTTP Method

    DELETE

    Description

    Delete the personal access token(s)

    Example URI

    http://localhost:9090/uc/resources/user/token?tokenname=test1&username=abc

    http://localhost:9090/uc/resources/user/token?tokenname=test1&userid=1234567

    Authentication

    HTTP Basic

    Produces Content-Type


    Consumes Content-Type


    Example Responses

    • Status 200

      • Personal access token revoked successfully.

    • Status 400

      • Error message.

    • Status 403

      • Operation prohibited due to security constraints.

    • Status 404

      • A user with name “{name}” does not exist.

      • A user with id "{uuid}" does not exist.

    • Status 500

      • Unexpected request failure. See log(s) for more details.

    Revoke Personal Access Token: Query Parameters

    The following request parameters will be needed for the service.

    Property

    UI Field Name

    Description

    Specifications

    Required

    Mutually Exclusive With

    userid

    N/A

    UUID of the user

    UUID of the user

    Y

    username

    username

    N/A

    User Name

    String value of User name

    N

    userid

    tokenname

    token name

    Token Name

    Specifies the name of the application that will access the Universal Controller Web Service APIs using the personal access token.

    Y