Segment Services, Version 3.0

81 Segment Services, Version 3.0

This chapter provides the information necessary to send messages contained in version 3.0 of the Segment Services API. Information can be obtained using the Web Service Description Language (WSDL) in conjunction with a Simple Object Access Protocol (SOAP), XML Schema, and various methods contained in the classes of the API to provide the web service described above.

The URL for the WSDL is:

https://<servername>:<portNumber>/ws/v3_0/SegmentServices?wsdl

where <servername> is the name or address of the server. For a cloud installation, the default port number is 443.

The information presented below describes the methods and classes.

The format of the method and any arguments is shown along with an explanation of what the method does and any other information that is necessary to use the method properly. If an argument is shown in dark blue, it is a class and the class name is a link to a description of the class and its attributes.

The class section shows the attributes of the classes along with an explanation of each attribute and when necessary, when they are used.

Note:

Authentication is required. See Introduction for information on creating and implementing an authentication key.

Methods

This section presents the methods used in Version 3.0 of the Segment Services API.

addCustomerToSegment

string[] addCustomerToSegment(                              string[] customerIds,                              long segmentId,                              string securityUserId)     throws RelateProcessingException

Variable	Required?	Description
`customerIds`	[optional]	Array of customer IDs.
`segmentId`	[required]	ID of the segment.
`securityUserId`	[required]	ID of the Customer Engagement user performing the action.

The addCustomerToSegment method adds a customer to an existing segment.

This method returns an array of string elements.

Note:

The securityUserId provided within this message must be assigned the proper Security Group permission for this operation to be performed successfully.

addOrDeleteSegmentFranchisee

void addOrDeleteSegmentFranchisee(       SegFranchiseeRequestType segmentFranchiseeData,       string securityUserId)     throws RelateProcessingException

Variable	Required?	Description
`segmentFranchiseeData`	[required]	A segment and the franchisees that will be added or deleted.
`securityUserId`	[required]	ID of the Customer Engagement user performing the action.

The addOrDeleteSegmentFranchisee method adds or removes one or more franchisees to or from a segment.

This method has no return value.

Note:

The securityUserId provided within this message must be assigned the proper Security Group permission for this operation to be performed successfully.

createManualSegment

long createManualSegment(                         string segmentName,                         string description,                         boolean privateFlag,                         string userId,                         boolean clientelingFlag,                         SegmentAttributeType attributes,                         string securityUserId)     throws RelateProcessingException

Variable	Required?	Description
`segmentName`	[required]	Name of the segment.
`description`	[required]	Description of the segment.
`privateFlag`	[optional]	Indicates whether the segment is private (`true`) or public (`false`).
`userId`	[optional]	ID of the user creating the segment.
`clientelingFlag`	[optional]	Indicates whether the segment will be made available to the clienteling module.
`attributes`	[optional]	Attributes for the segment.
`securityUserId`	[required]	ID of the Customer Engagement user performing the action.

The createManualSegment method creates a new segment that will contain individually selected customers. These customers are added using the addCustomerToSegment method and removed using the removeCustomerFromSegment method.

This method returns a long value.

Note:

The securityUserId provided within this message must be assigned the proper Security Group permission for this operation to be performed successfully.

deleteSegment

void deleteSegment(            long segmentId,            string securityUserId)     throws RelateProcessingException

Variable	Required?	Description
`segmentId`	[required]	ID of the segment.
`securityUserId`	[required]	ID of the Customer Engagement user performing the action.

The deleteSegment method deletes a segment, provided it is not assigned to a loyalty eligibility rule or to a promotion.

This method has no return value.

Note:

The securityUserId provided within this message must be assigned the proper Security Group permission for this operation to be performed successfully.

getCustomersOfSegment

wsPageOfSegmentCustomers getCustomersOfSegment(                          long segmentId,                          string[] optionalAssociateIds,                          int startIndex,                          int pageSize,                          string securityUserId)     throws RelateProcessingException

Variable	Required?	Description
`segmentId`	[required]	ID of the segment.
`optionalAssociateIds`	[optional]	Array of IDs for associates to whom the customers are assigned.
`startIndex`	[optional]	Start index of the customer list.
`pageSize`	[optional]	Maximum number of records per page.
`securityUserId`	[required]	ID of the Customer Engagement user performing the action.

The getCustomersOfSegment method retrieves a set of customers belonging to a segment, beginning with customer number startIndex and containing pageSize customers.

This method returns a wsPageOfSegmentCustomers element.

Note:

The securityUserId provided within this message must be assigned the proper Security Group permission for this operation to be performed successfully.

getMyManualSegments

wsSegmentSummary[] getMyManualSegments(                          string relateUserId,                          string securityUserId)     throws RelateProcessingException

Variable	Required?	Description
`relateUserId`	[required]	ID of user making request.
`securityUserId`	[required]	ID of the Customer Engagement user performing the request.

The getMyManualSegments retrieves the manual segments for a user.

This method returns an array of wsSegmentSummary elements.

Note:

The securityUserId provided within this message must be assigned the proper Security Group permission for this operation to be performed successfully.

getSegments

wsSegmentSummary[] getSegments(              string relateUserId,              boolean ignoreNonListSegments,              dateTime optionalNewerThanLastRunDate,              segmentViewType optionalSegmentViewType,              long optionalSegmentId,              string securityUserId)     throws RelateProcessingException

Variable	Required?	Description
`relateUserId`	[optional]	ID of user making request.
`ignoreNonListSegments`	[optional]	Indicates whether to only return segments containing a list of customers (`true`), or to also include segments that only produce customer counts (`false`).
`optionalNewerThanLastRunDate`	[optional]	Indicates whether to only return segments newer than the entered date.
`optionalSegmentViewType`	[optional]	Type of segment (`PRIVATE`, `PUBLIC`, or `OPEN_ACCESS`).
`optionalSegmentId`	[optional]	ID of segment.
`securityUserId`	[required]	ID of the Customer Engagement user performing the action.

The getSegments method returns an array of segments matching the entered search criteria.

This method returns an array of wsSegmentSummary elements.

Note:

The securityUserId provided within this message must be assigned the proper Security Group permission for this operation to be performed successfully.

removeCustomerFromSegment

string[] removeCustomerFromSegment(                               string[] customerIds,                               string segmentId,                               string securityUserId)     throws RelateProcessingException

Variable	Required?	Description
`customerIds`	[optional]	ID of the customer.
`segmentId`	[required]	ID of the segment.
`securityUserId`	[required]	ID of the Customer Engagement user performing the action.

The removeCustomerFromSegment method removes a customer from a manual segment.

This method returns an array of string elements.

Note:

The securityUserId provided within this message must be assigned the proper Security Group permission for this operation to be performed successfully.

updateManualSegment

long updateManualSegment(                         long segmentId,                         string segmentName,                         string description,                         boolean privateFlag,                         string userId,                         boolean clientelingFlag,                         SegmentAttributeType attributes,                         string securityUserId))     throws RelateProcessingException

Variable	Required?	Description
`segmentId`	[required]	ID of the segment.
`segmentName`	[required]	Name of the segment.
`description`	[required]	Description of the segment.
`privateFlag`	[required]	Indicates whether the segment is private (`true`) or public (`false`).
`userId`	[optional]	ID of the user creating the segment.
`clientelingFlag`	[required]	Indicates whether the segment will be made available to the clienteling module.
`attributes`	[optional]	Attributes for the segment.
`securityUserId`	[required]	ID of the Customer Engagement user performing the action.

The updateManualSegment method makes changes to an existing segment. To make changes to the customers in a segment, add customers using the addCustomerToSegment method and remove customers using the removeCustomerFromSegment method.

This method returns a long value.

Note:

The securityUserId provided within this message must be assigned the proper Security Group permission for this operation to be performed successfully.

Classes

This section presents the classes used in Version 3.0 of the Segment Services API.

RelateProcessingException

For a description of this class, see Introduction.

SegFranchiseeRequestType

The SegFranchiseeRequestType class contains the following elements:

Type	Element	Description
string	SegmentId	ID of the segment.
SegmentFranchiseesType	SegmentFranchisees	Franchisees for the segment.

SegmentAttributeType

The SegmentAttributeType class contains the following element:

Type	Element	Description
SegmentAttributeValueType[]	attribute	Array of segment attributes.

The SegmentAttributeType class contains the following attributes:

Type	Attribute	Description
string	GroupName	Name of the attribute group.
string	Action	Action to perform on the attributes.

SegmentAttributeValueType

The SegmentAttributeValueType class contains the following element:

Type	Element	Description
string[]	AttributeValue	Array of values for the attribute.

The SegmentAttributeValueType element contains the following attribute:

Type	Attribute	Description
string	AttributeName	Name of the attribute.

SegmentFranchiseeType

The getValue() function for this type returns a string element.

The SegFranchiseeType class contains the following attributes:

Type	Attribute	Description
FranchiseeActionType	action	Action to perform on the franchisee.
string	franchiseeId	ID of the franchisee.
string	franchiseeName	Name of the franchisee.

SegmentFranchiseesType

The SegmentFranchiseesType class contains the following element:

Type	Element	Description
SegmentFranchiseeType[]	SegmentFranchisee	Array of franchisees and the actions to perform on them for the segment.

wsAttributeValue

The wsAttributeValue class contains the following elements:

Type	Element	Description
long	attributeId	ID of the attribute.
string	attributeName	Name of the attribute.
string	attributeValue	Value of the attribute.

wsCustTiny

The wsCustTiny class contains the following elements:

Type	Element	Description
string	associateId	ID of associate (if any) assigned to the customer.
string	custId	ID of the customer.
string	firstName	Customer first name.
string	lastName	Customer last name.

wsPageOfSegmentCustomers

The wsPageOfSegmentCustomers class contains the following elements:

Type	Element	Description
wsCustTiny[]	customers	The customers in the page.
boolean	morePages	Indicates whether there are more pages in the results.
long	pageSize	Number of customers on the page.
long	startIndex	Sequence number indicating the order of the first customer in the page results.

wsSegmentAttribute

The wsSegmentAttribute class contains the following elements:

Type	Element	Description
string	action	The action to perform on the attribute.
wsAttributeValue[]	attribute	Array of attribute values.
string	groupName	Name of the attribute group.

wsSegmentSummaryWithAttribute

The wsSegmentSummaryWithAttribute class contains the following elements:

Type	Element	Description
wsSegmentAttribute	attributeGroup	Segment attributes.
string	createdByUserId	ID of the user who created the segment.
long	custCount	Number of customers in the segment.
string	description	Description of the segment.
boolean	isListSegment	Indicates whether the segment is a list segment.
boolean	isManualSegment	Indicates whether the segment is a manual segment.
dateTime	lastRunDate	The last time the segment was run.
string	name	Name of the segment.
long	segmentId	ID of the segment.
segmentQueryType	segmentQueryType	Type of query used to create the segment.
segmentViewType	segmentViewType	Type of view used for the segment.