AddUsergroupToFolderSubscribers API¶

Adds a specified user group to the subscription list of a folder, configuring which events trigger email notifications to all members of that group. Optionally cascades the subscription to all existing sub-folders. This is the user group equivalent of AddUserToFolderSubscribers -" it subscribes all members of a group at once rather than individual users.

Endpoint¶

/srv.asmx/AddUsergroupToFolderSubscribers

Methods¶

• GET /srv.asmx/AddUsergroupToFolderSubscribers?authenticationTicket=...&folderPath=...&groupName=...&ON_READ=...&...

• POST /srv.asmx/AddUsergroupToFolderSubscribers (form data)

• SOAP Action: http://tempuri.org/AddUsergroupToFolderSubscribers

Parameters¶

Boolean Parameter Format¶

All boolean parameters accept:

• true or True or 1 -" enable

• false or False or 0 -" disable

Response¶

Success Response¶

<response success="true" error="" />

Error Response¶

<response success="false" error="Folder not found." />

Required Permissions¶

The calling user must be authenticated. To add a user group as a subscriber, the calling user must have write access or manage access to the folder.

Example¶

GET Request¶

GET /srv.asmx/AddUsergroupToFolderSubscribers

  ?authenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301

  &folderPath=/Finance/Reports

  &groupName=Finance-Managers

  &ON_READ=false

  &ON_CHANGE=true

  &ON_UPDATE=true

  &ON_CHECKOUT=false

  &ON_APPROVE=true

  &ON_REJECT=true

  &ON_COMMENT=true

  &ON_MOVE=true

  &ON_DELETE=true

  &ON_CHECKIN=false

  &ON_NEWDOC=true

  &IncludeSubObjects=true

HTTP/1.1

POST Request¶

POST /srv.asmx/AddUsergroupToFolderSubscribers HTTP/1.1

Content-Type: application/x-www-form-urlencoded

authenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301

&folderPath=/Finance/Reports

&groupName=Finance-Managers

&ON_READ=false

&ON_CHANGE=true

&ON_UPDATE=true

&ON_CHECKOUT=false

&ON_APPROVE=true

&ON_REJECT=true

&ON_COMMENT=true

&ON_MOVE=true

&ON_DELETE=true

&ON_CHECKIN=false

&ON_NEWDOC=true

&IncludeSubObjects=true

SOAP Request¶

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"

               xmlns:tns="http://tempuri.org/">

  <soap:Body>

    <tns:AddUsergroupToFolderSubscribers>

      <tns:AuthenticationTicket>3f2504e0-4f89-11d3-9a0c-0305e82c3301</tns:AuthenticationTicket>

      <tns:folderPath>/Finance/Reports</tns:folderPath>

      <tns:groupName>Finance-Managers</tns:groupName>

      <tns:ON_READ>false</tns:ON_READ>

      <tns:ON_CHANGE>true</tns:ON_CHANGE>

      <tns:ON_UPDATE>true</tns:ON_UPDATE>

      <tns:ON_CHECKOUT>false</tns:ON_CHECKOUT>

      <tns:ON_APPROVE>true</tns:ON_APPROVE>

      <tns:ON_REJECT>true</tns:ON_REJECT>

      <tns:ON_COMMENT>true</tns:ON_COMMENT>

      <tns:ON_MOVE>true</tns:ON_MOVE>

      <tns:ON_DELETE>true</tns:ON_DELETE>

      <tns:ON_CHECKIN>false</tns:ON_CHECKIN>

      <tns:ON_NEWDOC>true</tns:ON_NEWDOC>

      <tns:IncludeSubObjects>true</tns:IncludeSubObjects>

    </tns:AddUsergroupToFolderSubscribers>

  </soap:Body>

</soap:Envelope>

JavaScript¶

Every call answers XML with HTTP 200, success or not, so success is the thing to branch on and errorCode is the number to report.

async function call(action, params) {
  const response = await fetch(`/srv.asmx/${action}?${new URLSearchParams(params)}`);
  const root = new DOMParser()
    .parseFromString(await response.text(), 'text/xml')
    .documentElement;

  if (root.getAttribute('success') !== 'true') {
    throw new Error(`${root.getAttribute('errorCode')}: ${root.getAttribute('error')}`);
  }
  return root;
}

Subscribes a user group to a folder, and optionally to everything inside it.

await call('AddUsergroupToFolderSubscribers', {
  authenticationTicket: ticket,
  folderPath: '/Public/Reports',
  groupName: 'Auditors',          // the folder's own library first, then the global groups
  ON_READ: true, ON_CHANGE: true, ON_UPDATE: false, ON_CHECKOUT: false, ON_APPROVE: false,
  ON_REJECT: false, ON_COMMENT: false, ON_MOVE: false, ON_DELETE: true, ON_CHECKIN: false,
  ON_NEWDOC: true,
  IncludeSubObjects: true,
});

Notes¶

• Update vs Add: If the user group is already a subscriber to the folder, this API updates the existing event flags rather than creating a duplicate entry.

• All Flags Required: All eleven event flag parameters are required and must be explicitly passed. Omitting a flag may result in a parse error or that flag defaulting to false.

• IncludeSubObjects: When true, the subscription is applied recursively to all sub-folders existing at the time of the call. Sub-folders created after this call will not automatically inherit the group subscription.

• ON_NEWDOC: This flag is unique to folder subscriptions. It triggers a notification whenever a new document is created or registered in the folder. This flag does not exist in document-level subscriptions.

• Group Membership: All current members of the named group will receive notifications. New group members added after the subscription is created will also automatically receive notifications because notifications are sent to all current group members at the time the event fires.

• Duplicate Notifications: If a user is both individually subscribed to the folder and a member of a subscribed group, they may receive duplicate notifications for the same event.

• Either kind of group: the folder's own library is searched first and then the global groups, so a library group of the same name as a global one wins inside its own library.

• Notifications by Email: Subscriptions trigger email notifications when the configured events occur. Email notifications require a properly configured email server in the infoRouter settings.

Event Flags Reference¶

Related APIs¶

• AddUsergroupToDocumentSubscribers - Add a user group to a specific document's subscription list

• AddUserToFolderSubscribers - Add an individual user to a folder's subscription list

• RemoveUsergroupFromFolderSubscribers - Remove a user group from a folder's subscription list

• GetSubscribers - Get the full subscriber list of a document or folder

• GetSubscriptions - Get all subscriptions for the current user

Error Codes¶

The errorCode values this operation returns, checked against a running server:

The ten event flags are the same on every add operation, and all ten have to be sent: they are declared as plain booleans, so a missing one is a model binding failure rather than a default. ON_NEWDOC is the eleventh, and belongs to the folder forms only.