Segment Services, Version 1.1

80 Segment Services, Version 1.1

This chapter provides the information necessary to send messages contained in version 1.1 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/v1_1/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 1.1 of the Segment Services API.

addCustomerToSegment

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

Variable	Required?	Description
`customerIds`	[optional]	Array of customer IDs.
`segmentId`	[required]	ID of the segment.

The addCustomerToSegment method adds a customer to an existing segment.

This method returns an array of string elements.

createManualSegment

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

Variable	Required?	Description
`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`	[required]	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.

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.

getCustomersOfSegment

wsPageOfSegmentCustomers getCustomersOfSegment(                          long segmentId,                          string[] optionalAssociateIds,                          int startIndex,                          int pageSize,     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`	[required]	Start index of the customer list.
`pageSize`	[required]	Maximum number of records per page.

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.

getMyManualSegments

wsSegmentSummary[] getMyManualSegments(                          string relateUserId,     throws RelateProcessingException

Variable	Required?	Description
`relateUserId`	[required]	ID of user making request.

The getMyManualSegments retrieves the manual segments for a user.

This method returns an array of wsSegmentSummary elements.

getSegments

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

Variable	Required?	Description
`relateUserId`	[optional]	ID of user making request.
`ignoreNonListSegments`	[required]	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.

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

This method returns an array of wsSegmentSummary elements.

removeCustomerFromSegment

void removeCustomerFromSegment(                               string[] customerIds,                               string segmentId,     throws RelateProcessingException

Variable	Required?	Description
`customerIds`	[optional]	ID of the customer.
`segmentId`	[optional]	ID of the segment.

The removeCustomerFromSegment method removes a customer from a manual segment.

This method returns an array of string elements.

updateManualSegment

void updateManualSegment(                         long segmentId,                         string segmentName,                         string description,                         boolean privateFlag,                         string userId,                         boolean clientelingFlag,                         SegmentAttributeType attributes,     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`	[required]	ID of the user creating the segment.
`clientelingFlag`	[required]	Indicates whether the segment will be made available to the clienteling module.
`attributes`	[required]	Attributes for the segment.

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.

Classes

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

RelateProcessingException

For a description of this class, see Introduction.

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.

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.