Franchisee Services, Version 3.0

40 Franchisee Services, Version 3.0

This chapter provides the information necessary to send messages contained in Version 3.0 of the Franchisee 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.

The URL for the WSDL is:

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

Where <servername> is the name or address of the server. The default port number is 443.

The information presented 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 Franchisee Services API.

addOrDeleteFranchiseeLocations

long addOrDeleteFranchiseeLocations(
      FranchiseeLocationsRequestType franchiseeLocations,
      string updateUserId,
      string securityUserId)
        throws RelateProcessingException

Variable	Required?	Description
franchiseeLocations	Required	Franchisees being added or deleted.
updateUserId	Required	ID of the POS user performing the action.
securityUserId	Required	ID of the Customer Engagement user performing the action

The addOrDeleteFranchiseeLocations method adds locations to or deletes locations from a franchisee.

This method returns a long value.

addOrDeleteFranchiseeUsers

long addOrDeleteFranchiseeUsers(
     FranchiseeUsersRequestType franchiseeLocations,
     string updateUserId,
     string securityUserId)
        throws RelateProcessingException

Variable	Required?	Description
franchiseeUsers	Required	Users being added or deleted.
updateUserId	Required	ID of the POS user performing the action.
securityUserId	Required	ID of the Customer Engagement user performing the action

The addOrDeleteFranchiseeUsers method adds users to or deletes users from a franchisee.

This method returns a long value.

addOrUpdateFranchisee

long addOrUpdateFranchisee(
                           FranchiseeRequestType franchisee,
                           string updateUserId,
                           string securityUserId)
     throws RelateProcessingException

Variable	Required?	Description
franchisee	Required	Franchisee being added or updated.
updateUserId	Required	ID of the POS user performing the action.
securityUserId	Required	ID of the Customer Engagement user performing the action.

The addOrUpdateFranchisee method adds a franchisee or updates franchisee information.

This method returns a long value.

deleteFranchisee

long deleteFranchisee(
                       long franchiseeId,
                       string franchiseeName,
                       string securityUserId)
      throws RelateProcessingException

Variable	Required?	Description
franchiseeId	Required	Franchisee being deleted.
franchiseeName	Optional	Name of the franchisee.
securityUserId	Required	ID of the Customer Engagement user performing the action.

The deleteFranchisee method deletes a franchisee.

This method returns a long value.

getAllFranchisees

AllFranchiseesResponseType getAllFranchisees(
                                string securityUserId)
            throws RelateProcessingException

Variable	Required?	Description
securityUserId	Required	ID of the Customer Engagement user performing the request.

The getAllFranchisees method returns all franchisees that the user has access to.

This method returns an AllFranchiseesResponseType element.

getFranchisee

FranchiseeResponseType getFranchisee(
                            long franchiseeId,
                            string franchiseeName,
                            string securityUserId)
        throws RelateProcessingException

Variable	Required?	Description
franchiseeId	Required	Franchisee being retrieved.
franchiseeName	Optional	Name of the franchisee.
securityUserId	Required	ID of the Customer Engagement user performing the action.

The getFranchisee method retrieves a franchisee.

This method returns a FranchiseeResponseType element.

getFranchiseeCustomers

FranchiseeCustomerResponseType getFranchiseeCustomers(
                       long franchiseeId,
                       string franchiseeName,
                       string securityUserId,
                       int startIndex,
                       int pageSize)
          throws RelateProcessingException

Variable	Required?	Description
franchiseeId	Required	Franchisee being retrieved.
franchiseeName	Optional	Name of the franchisee.
securityUserId	Required	ID of the Customer Engagement user performing the action.
startIndex	Required	Number of first customer to retrieve, in the list of customers.
pageSize	Required	Number of customers to retrieve (that is, page size).

The getFranchiseeCustomers method retrieves a certain number of customers associated with a franchisee, starting at a certain customer in the list of customers.

This method returns a FranchiseeCustomerResponseType element.

Classes

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

AllFranchiseesResponseType

The AllFranchiseesResponseType element contains the following elements:

Type	Element	Description
FranchiseeResponseType[]	franchisee	Array of franchisees.

FranchiseeCustomerContainerReturnType

The FranchiseeCustomerContainerReturnType element contains the following elements:

Type	Element	Description
FranchiseeCustomerReturnType[]	customer	Array of customers.

FranchiseeCustomerResponseType

The FranchiseeCustomerResponseType element contains the following elements:

Type	Element	Description
long	franchiseeId	ID of the franchisee.
string	franchiseeName	Name of the franchisee.
FranchiseeLocationContainerReturnType	customers	Franchisee locations.

FranchiseeCustomerResponseType element contains the following attributes:

Type	Attribute	Description
int	startIndex	Number of the first record in the list.
boolean	morePages	Whether there are more pages available.
int	int pageSize	Number of records in the page.

FranchiseeCustomerReturnType

The getValue() function for the FranchiseeCustomerReturnType class returns a string value.

FranchiseeCustomerReturnType element contains the following attributes:

Type	Attribute	Description
string	custId	ID of the customer.
string	firstName	Customer first name.
string	lastName	Customer last name.

Exception

See Introduction..

FranchiseeLocationContainerReturnType

The FranchiseeLocationContainerReturnType element contains the following elements:

Type	Element	Description
FranchiseeLocationReturnType[]	FranchiseeLocation	Array of locations.

FranchiseeLocationContainerType

The FranchiseeLocationContainerType element contains the following elements:

Type	Element	Description
FranchiseeLocationType[]	FranchiseeLocation	Array of locations.

FranchiseeLocationReturnType

The getValue() function for the FranchiseeLocationReturnType class returns a string value.

FranchiseeLocationReturnType element contains the following attributes:

Type	Attribute	Description
string	retailLocationId	ID of the retail location.
string	retailLocationName	Name of the retail location.

FranchiseeLocationType

The getValue() function for the FranchiseeLocationType class returns a string value.

FranchiseeLocationType element contains the following attributes:

Type	Attribute	Description
FranchiseeActionType	action	Action to perform on the location.
string	retailLocationId	ID of the retail location.
string	retailLocationName	Name of the retail location.

FranchiseeLocationsRequestType

The FranchiseeLocationsRequestType element contains the following elements:

Type	Element	Description
long	franchiseeId	ID of the franchisee.
string	franchiseeName	Name of the franchisee.
FranchiseeLocationContainerType	FranchiseeLocations	Franchisee locations.

FranchiseeResponseType

The FranchiseeResponseType element contains the following elements:

Type	Element	Description
long	franchiseeId	ID of the franchisee.
string	franchiseeName	Name of the franchisee.
string	franchiseeDescription	Description of the franchisee.
string	address1	Address line 1.
string	address2	Address line 2.
string	address3	Address line 3.
string	address4	Address line 4.
string	city	Franchisee city.
string	state	Franchisee state/province.
string	postalCode	Franchisee postal/zip code.
string	county	Franchisee county
string	country	Franchisee country.
string	phoneNumber	Franchisee phone number.
string	emailAddress	Franchisee email address.
boolean	activeFlag	Whether the franchisee is active.
FranchiseeUserContainerReturnType	franchiseeUsers	Users associated with the franchisee.
FranchiseeLocationContainerType	franchiseeLocations	Locations associated with the franchisee.

FranchiseeRequestType

The FranchiseeRequestType element contains the following elements:

Type	Element	Description
long	franchiseeId	ID of the franchisee.
string	franchiseeName	Name of the franchisee.
string	franchiseeDescription	Description of the franchisee.
string	address1	Address line 1.
string	address2	Address line 2.
string	address3	Address line 3.
string	address4	Address line 4.
string	city	Franchisee city.
string	state	Franchisee state/province.
string	postalCode	Franchisee postal/zip code.
string	county	Franchisee county
string	country	Franchisee country.
string	phoneNumber	Franchisee phone number.
string	emailAddress	Franchisee email address.

Note:

Oracle recommends that the contact details for a franchisee (for example, email address or phone) identify the physical store rather than an individual.

FranchiseeUserContainerReturnType

The FranchiseeUserContainerReturnType element contains the following elements:

Type	Element	Description
FranchiseeUserReturnType[]	franchiseeUser	Array of users.

FranchiseeUserContainerType

The FranchiseeUserContainerType element contains the following elements:

Type	Element	Description
FranchiseeUserType[]	FranchiseeUser	Array of users.

FranchiseeUsersRequestType

The FranchiseeUsersRequestType element contains the following elements:

Type	Element	Description
long	franchiseeId	ID of the franchisee.
string	franchiseeName	Name of the franchisee.
FranchiseeUserContainerType	FranchiseeUsers	Franchisee users.

FranchiseeUserReturnType

The getValue() function for the FranchiseeUserReturnType class returns a string value.

FranchiseeUserReturnTypeelement contains the following attributes:

Type	Attribute	Description
string	userId	ID of the user.
string	userName	Name of the user.

FranchiseeUserType

The getValue() function for the FranchiseeUserType class returns a string value.

FranchiseeUserTypeelement contains the following attributes:

Type	Attribute	Description
FranchiseeActionType	action	Action to perform on the location.
string	userId	ID of the user.
string	userName	Name of the user.

GroupAttributeType

The attributesType element contains the following elements:

Type	Element	Description
string	attributeId	ID of the attribute.
string	attributeName	Name of the attribute.
string	attributeDescription	Description of the attribute.
AttributesIntendedUseType	intendedUse	Intended use of the attribute.
string	dataType	Data type of the attribute.
boolean	uniqueFlag	Indicates whether the attribute can only be set once for each element to which it is assigned.
boolean	requiredFlag	Indicates whether the attribute is required for each element in its intended use.
boolean	editableFlag	Indicates whether the attribute value can be edited.
boolean	openAccessFlag	Indicates whether the attribute has open access.
string	attributeGroup	Attribute group to which the attribute belongs.

RelateProcessingException

For a description of this class, see Introduction.