Select a target group (list, segment)

What to achieve

Editors should be able to select lists or segments from the UM in order to select the target audience for a newsletter or even for a single section within a newsletter.

How to achieve it

To be able to use this function the CMS must have the following capabilities:

Simple integration

The CMS must be able to create custom content (multi-)select or checkbox fields which can read the option list from a remote REST interface.

Advanced integration

The CMS must be able to create custom fields which can read, select and store structured objects from a remote REST interface.

Select target group as recipients for the newsletter

A custom content field will be added to the newsletter object where the editors can select one or more groups from the Universal Messenger. The result value will be then used to add to <destination> in the XML event file.

Select target group for a single newsletter section

A custom content field will be added to a newsletter section object where the editors can select one or more groups from the Universal Messenger. The result value will then be used for personalization instructions.

Details

Universal Messenger ChannelList REST interface

See also REST API doc

Request

URL: <um-rest-url>/de.pinuts.cmsbs.restapi.Channels/index
Parameters:
- umopen: API token (prior to UM 7.56)
- (optional) semtag: Tenant semtag string as a filter

Headers (UM 7.56 or newer):
- Authorization: Basic Auth credentials of API key with permission de.pinuts.cmsbs.restapi:ListChannels
  See also Universal Messenger 7.56.0 (EN) | Securing REST endpoints with API keys

Response

Format: JSON
Body: Array of channel objects with the following attributes:
- id: internal name, this must be used as a value for both <destination> of personalization filter.
  If the CMS can only store flat strings, this is the string to store.
- title: can be used as a label for the editors
- isPublic: is a public channel (might not be relevant but can be used as a filter for the editors)
- isVChannel: indicated whether objects represents a segment (VCHannel) or a list (Channel), this determines which syntax must be used (see below)
- oid: internal ID, if the CMS implementation needs an ID for the stored object this attribute can be used
- estimatedCount: contains an estimation of the the number of members (recipients)

Example response

[{
    "id": "demo",
    "title": "Demo",
    "isPublic": false,
    "isVChannel": false,
    "oid": "2333888",
    "estimatedCount": 435
}, {
    "id": "sales",
    "title": "Sales employees",
    "isPublic": false,
    "isVChannel": false,
    "oid": "2333883",
    "estimatedCount": 23021
}]

Output

Define newsletter recipients

Newsletter recipient groups selected by editors must be added to the XML event file inside <destination>:

<event>
  <destination>
    for each group
      if group.isVChannel
        <vchannel>group.id</vchannel>
      else
        <channel>group.id</channel>
      end
    end
  </destination>
  ...
</event>

Limit target group for newsletter content section

Content section target group for a newsletter content section selected by editors must be added as personalization instruction to the newsletter HTML code:

<html>
  <body>
    ...
    if group
      if group.isVChannel
      {if|inVChannel("group.id")|
      else
      {if|inChannel("group.id")|
      end
      
      <p>This text will be limited to the selected group</p>
      }
    end
    ...
  </body>
</html>