SetUser

Allows site administrators to update the information of an existing user. If the Primary Large Telephony Server is unavailable, the page first tries to connect to the NextGen telephony server. If that connection is unavailable, the page will connect to the Backup 2 Large server instead. On Control Hub managed sites SetUser can also result in assigning or removing meeting sites licenses from the user.

The SetUser command returns an exceededSiteHostLimit error if an attempt to change a user's active=ACTIVATED parameter means that the WebEx site's host limit would be exceeded.

Note: To enhance Personal Conference security, the XML API now supports a user's telephone PIN that is used to add security to Personal Conference Number audio.

The PIN element is available in the createUser, setUser, and getUser operations to support a user's telephone PIN:

Element	Parent	Definition	Type	Default
`PIN`	`<phones>`	Secondary level of authentication for PCN and when host is using the phone and inviting additional attendees	string 0..1

The joinBeforeHost element is available in the createUser, setUser, and getUser operations to support the "PCN Join Before Host" setting:

Element	Parent	Definition	Type	Default
`joinBeforeHost`	`<personalTeleconf>`	Indicates if PCN-Join Before Host is enabled for the user	boolean 0..1	`FALSE`

If an XML API user who has never had a PIN launches a PCN meeting and calls WebEx audio access number, the WebEx audio IVR will prompt user to enter their PIN. The user needs to create their PIN before attempting to launch a PCN meeting. Otherwise, the user will not be ale to launch meetings any more.

The host must set a PIN before a PCN account can be added or edited. The 'createUser' and 'setUser' API requires the user to have a valid PIN in order to add or edit a PCN account. If a valid PIN does not exist, the XML API returns the error message: "valid PIN is required".

The PIN can be set through the XML API by using CreateUser or SetUser API. Use the GetUser API to retrieve the host's PIN.

When using CreateUser or SetUser to specify the PIN, the XML API checks whether the value provided is a valid PIN. Single number values and simple sequences, like 1111 or 1234 are not allowed. If value is not a valid
PIN, the XML API throws the exception: WBXValidationException (ID=999999, "Not a valid PIN! PIN must be 4-digit number and not allow PIN to be Single number values or simple sequences, like 1111 or 1234.") "Not a valid PIN".

Create/SetUser will only allow the site admin to specify <personalTeleconf><joinBeforeHost> for the host. This option
can only be specified on the SiteAdmin page - so the host is not allowed to change the setting. If this rule is violated, the XML API will throw
the exception: NoPrivilegeException(ID = 000001, "Access denied, additional privileges are required")

If the <personalTeleconf><account><joinBeforeHost> value is set through the XML API Create/SetUser request, this input value will now be
ignored. Only the value of new element <personalTeleconf><joinBeforeHost> should be used.

The XML API GetUser response will still return <personalTeleconf><account><joinBeforeHost>, but the value will be identical to the value of the new element <personalTeleconf><joinBeforeHost>.

The setUser API includes video callback information (SIP URLs). The schema has changed to include this information as part of the videoSystems element as shown in the following schema diagram.

Request

In general, the SetUser request only updates the elements (simple or complex) that are explicitly specified. Unspecified elements
remain unchanged. However, if a complex element (like <meetingType>) that contains 0..n or 1..n sub elements is specified, then the entire
set of sub elements is updated.

The sample XML shows an example of a request to change the value of meetingType. The sample shows an example in which all previous <meetingType> values would be replaced by the single 105 value.

<meetingTypes>
    <meetingType>105</meetingType>
</meetingTypes>

The following example is a setUser request that allows a user or admin to set the hostPIN:

<?xml version="1.0" encoding="UTF-8"?>
<serv:message xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <header>
    <securityContext>
      <webExID></webExID>
      <password></password>
      <siteName></siteName>
      <returnAdditionalInfo>true</returnAdditionalInfo>
    </securityContext>
  </header>
  <body>
    <bodyContent xsi:type="java:com.webex.xmlapi.service.binding.user.SetUser">
      <webExId></webExId>
      <personalMeetingRoom>
        <hostPIN></hostPIN>
      </personalMeetingRoom>
    </bodyContent>
  </body>
</serv:message>

The following schema diagram shows the structure of the elements in a setUser request message.

Figure 3-25 • Schema diagram for setUser

The following schema diagram shows the child elements in the personalMeetingRoom element.

Figure 3-26 • Schema diagram for personalMeetingRoom

Note The logic of some of the elements is as follows:

Most user options now default to “true” or “false” depending on the
site settings and the SetUser request settings. The elements
affected can be found in Table 2-5 and an example of how the
settings interact can be found in Table 2-6.
After validation, any invalid settings will be automatically reset
to “off”.
Users can be forced to change their password on their next login or
locked out of their account entirely by Site Admin.
If sme is TRUE and a specified prodID does not exist on the
site, a validation error occurs.
If more than one prodID is specified, the request updates the
association between smeInfo and products. For example, the
original values are
<products><prodID>120</prodID><prodID>123</prodID></products> and
you specified
<products><prodID>123</prodID><prodID>124</prodID></products>
with the request, then the result you will get is
<products><prodID>124</prodID><prodID>123</prodID></products>.
If sme is FALSE, then all the smeInfo related records associated
with this user are removed automatically.
The enable element has been added to support the “Create this user
as administrator on the Service Desk site” option in Site Admin.
Regarding the role of the user, one of the three elements
(siteAdmin, roSiteAdmin and host) must be specified as
TRUE. If more than one is set to TRUE, the role of the user is
automatically determined in the sequence of siteAdmin,
roSiteAdmin and host. For example, if both siteAdmin and
host are set to TRUE, then the role of the user is siteAdmin.
If none of the three elements is set to TRUE, then the default
role of the user is host.
SetUser allows the user to change their user name via the
newWebExId element. If the Site Admin has enabled the “Allow user to
change user name” setting then the user can change their setting as
long as it does not conflict with a prior name.
The following APIs will now synchronize their information if the
syncWebOffice flag has been set to true: CreateUser, SetUser,
DelUser, ActivateUser and InactivateUser.

The following containers and their associated elements were added: personalMeetingRoom, sessionOptions, supportCenter, schedulingTemplates and
orderTabs. This allows the API to return additional fields from My Profile.

When SetUser counts active host accounts, attendee account and
designated chat user are excluded from the count, but site admin and
admin view only are included.
The boolean element myWorkspaces has been added in order to
support the WebOffice integration capabilities.

The sample XML document updates the information of an existing user account. Be sure to use key identification values that are correct for your website.

<?xml version="1.0" encoding="UTF-8"?>
<serv:message xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:serv="http://www.webex.com/schemas/2002/06/service">
    <header>
        <securityContext>
          <siteName>acme</siteName>
          <webExID>admincred@acme.com</webExID>
          <password>P@ssword123</password>
        </securityContext>
    </header>
<body>
    <bodyContent xsi:type="java:com.webex.service.binding.user.SetUser">
        <webExId>hostid</webExId>
        <personalMeetingRoom>
            <welcomeMessage>This is welcome message</welcomeMessage>
            <headerImageBranding>false</headerImageBranding>
        </personalMeetingRoom>
        <sessionOptions>
            <defaultSessionType>100</defaultSessionType>
            <defaultServiceType>EventCenter</defaultServiceType>
            <autoDeleteAfterMeetingEnd>false</autoDeleteAfterMeetingEnd>
            <displayQuickStartHost>true</displayQuickStartHost>
            <displayQuickStartAttendees>false</displayQuickStartAttendees>
        </sessionOptions>
        <supportCenter>
            <orderTabs>
            <tab>Tools</tab>
            <tab>Desktop</tab>
            <tab>Application</tab>
            <tab>Session</tab>
            </orderTabs>
        </supportCenter>
    </bodyContent>
</body>
</serv:message>

For descriptions of the global elements in the security context of the header, see Global Request Elements in Security Context. For descriptions of the non-global elements, see Elements in WebEx XML Schema Definitions for the User Service.

Response

The sample XML document shows the change that has been made to the existing service instance.

<?xml version="1.0" encoding="UTF-8"?>
<serv:message xmlns:serv="http://www.webex.com/schemas/2002/06/service"
    xmlns:com="http://www.webex.com/schemas/2002/06/common"
    xmlns:use="http://www.webex.com/schemas/2002/06/service/user">
    <serv:header>
        <serv:response>
            <serv:result>SUCCESS</serv:result>
            <serv:gsbStatus>PRIMARY</serv:gsbStatus>
        </serv:response>
    </serv:header>
    <serv:body>
        <serv:bodyContent xsi:type="use:setUserResponse"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
    </serv:body>
</serv:message>

The following schema diagram shows the structure of the elements in the setUserResponse message.

Figure 3-28 • Schema diagram for setUserResponse

The result and exceptionID global elements allow you to confirm that an instantiation request was successful. These elements are described in “Global Response Elements Showing Results and Errors”.