Name Integration Web Services

Overview

The Name Integration Web Services are used in conjunction with the Simplicity Data Integration Web Services (DIWS) and the Passport Web Service to provide the ability to clean and ensure the integrity of the values used in the Name fields of entities (via the DIWS).

It provides the ability to format, validate, case and populate associated Name Fields to Simplicity Standards with ease.

These services are located via the URL format below located relative to the client’s SCIS website. This service can be delivered via http or https with the use of a SSL certificate where required./SingleView/Common/Formatting/NameSvc.asmx

Name Integration Web Service Method Definitions

The following methods provide the means to format, validate, case and populate associated Name Fields. This web service is accessed via http on port 80 or https on port 443 at the following url relative to the client’s SCIS website:

/SingleView/Common/Formatting/NameSvc.asmx

• FormatOrganisationName
• FormatPersonName
• FormatPersonNameFromComponents

Creating a Name Service Object

To create a Name Service object use the following code:

(Assumes the web reference is named ‘NameService’)

Dim namesvc As NameService.NameSvc

namesvc = New NameService.NameSvc

Web Service Method – FormatOrganisationName

This method takes an existing token and name of type string, and returns the associated Organisation Name Fields cased correctly.

Parameters

Token: Token supplied by logging into the Passport Web Service

Name: The organisation name (as type string)

Returns:

A Name Service object of class ‘FormatOrganisationNameResult’ with an error code, an Organisation Display Value, and an Organisation Company Name.

 

Sample Code

' Create the Name Service

Dim nameSvc As NameService.NameSvc

nameSvc = New NameService.NameSvc

' Format an Organisation Name

Dim name As String

name = "Hollywood Bakery Ltd"

Dim nameResult As NameService.OrganisationNameResult

nameResult = nameSvc.FormatOrganisationName(token, name)

' Collect Results

Dim companyName As String

Dim displayValue As String

If nameResult.ErrorCode = 0 Then

companyName = nameResult.Result.CompanyName

displayValue = nameResult.Result.DisplayValue

Else

' Returned an error code not OK.

EndIf

Web Service Method – FormatPersonName

This method takes an existing token and name of type string, and returns the associated Person Name Fields cased correctly.

 

Parameters

Token: Token supplied by logging into the Passport Web Service

Name: The person name (as type string)

Returns:

A Name Service object of class ‘FormatPersonNameResult’ with an error code and the following associated name fields:

DisplayValue, FirstName, PreferredNameOrFirstName, MiddleName, Surname,NameBadge, Initials, PreferredNameInitials, Title, Salutation, PreferredNameSalutation, LetterCarrier, PreferredNameLetterCarrier, InitialisedLetterCarrier, PreferredNameInitialisedLetterCarrier, PreferredName , PreferredNameDisplayValue, PrefferedNameInBracketsDisplayValue, FullLetterCarrier, PreferredNameFullLetterCarrier, Decoration.

 

Sample Code

' Create the Name Service

Dim nameSvc As NameService.NameSvc

nameSvc = New NameService.NameSvc

' Format an Person Name

Dim name As String

name = "Mr Matthew Revell"

Dim nameResult As NameService.PersonNameResult

nameResult = nameSvc.FormatPersonName(token, name)

' Collect Results

' Please not the example only collects a few results , you may want

' to collect more.

Dim title As String

Dim displayValue As String

Dim salutation As String

Dim firstName As String

Dim surname As String

If nameResult.ErrorCode = 0 Then

title = nameResult.Result.CompanyName

displayValue = nameResult.Result.DisplayValue

salutation = nameResult.Result.Salutation

firstName = nameResult.Result.FirstName

surname = nameResult.Result.Surname

Else

' Returned an error code not OK.

EndIf

Web Service Method – FormatPersonNameFromComponents

This method takes an existing token and several name components of type string, and returns the associated Person Name Fields cased correctly.

Parameters

Token: Token supplied by logging into the Passport Web Service

Title: The person title (as type string)

Decoration: The decoration name of the person (as type string)

PreferredName: The preffered name of the person (as type string)

GivenName: The given name of the person (as type string)

MiddleName: The middle name of the person (as type string)

FamilyName: The family name of the person (as type string)

Gender: The gender of the person (as type NameService.Gender, will be Male, Female or unknown)

Returns:

A Name Service object of class ‘FormatPersonNameResult’ with an error code and the following associated name fields:

DisplayValue, FirstName, PreferredNameOrFirstName, MiddleName, Surname,NameBadge, Initials, PreferredNameInitials, Title, Salutation, PreferredNameSalutation, LetterCarrier, PreferredNameLetterCarrier, InitialisedLetterCarrier, PreferredNameInitialisedLetterCarrier, PreferredName , PreferredNameDisplayValue, PrefferedNameInBracketsDisplayValue, FullLetterCarrier, PreferredNameFullLetterCarrier, Decoration.

Sample Code

' Create the Name Service

Dim nameSvc As NameService.NameSvc

nameSvc = New NameService.NameSvc

' Format an Person Name

Dim Title As String = "Mr"

Dim Decoration As String = ""

Dim PreferredName As String = "Matt"

Dim GivenName As String = "Matthew"

Dim MiddleName As String = "John"

Dim FamilyName As String = "Revell"

Dim nameResult As NameService.PersonNameResult

nameResult = nameSvc.FormatPersonName(token, Title, Decoration, PreferredName, GivenName, MiddleName, FamilyName, NameServices.Gender.Male)

' Collect Results

' Please not the example only collects a few results , you may want

' to collect more.

Dim displayValue As String

Dim salutation As String

Dim letterCarrier As String

Dim nameBadge As String

If nameResult.ErrorCode = 0 Then

displayValue = nameResult.Result.DisplayValue

salutation nameResult.Result.Salutation

letterCarrier = nameResult.Result.LetterCarrier

nameBadge = nameResult.Result.NameBadge

Else

' Returned an error code not OK.

EndIf

Name Web Service – Person Name Definitions

DisplayValue: The display value of the record (appears in the Simplicity Explorer)

FirstName: The first name of the person

PreferredNameOrFirstName: The preferred name of the person (if name can’t be derived will use First Name)

MiddleName: The middle name of the person

Surname: The surname of the person

NameBadge: Informal version of Salutation

Initials: The initials of the person

PreferredNameInitials: The initials of the person using the preferred name.

Title: The identifying appellation signifying status of the person (ie, Mr)

Salutation: Greeting used in an edm or letter

PreferredNameSalutation: The Salutation using the preferred name.

LetterCarrier: Used to address physical mail recipient.

PreferredNameLetterCarrier: Letter carrier using Preferred Name

InitialisedLetterCarrier: Letter carrier using only the person initials

PreferredNameInitialisedLetterCarrier: Letter carrier using the persons preferred name initials

PreferredName: The persons preferred name

PreferredNameDisplayValue: The display value using the persons preferred name

PreferedNameInBracketsDisplayValue: The display value with the preferred name in brackets.

FullLetterCarrier: Formal version of the letter carrier.

PreferredNameFullLetterCarrier: Formation version of the letter carrier

Decoration: The honorific bestowed to a person.

Gender: The gender (derived from the name)

Name Web Service – Person Casing Examples and Definitions

mr geoffrey david mcdonald, known as jeff with a nickname of styrn would appear as the following:

Title: Mr (derive from FirstName, if fails derive from MiddleName)

FirstName: Geoffrey

MiddleName: David

Surname: McDonald

Initials: G D M (first character from FirstName, MiddleName, FamilyName)

NickName: Styrn

LetterCarrier: Mr Geoffrey McDonald NZCE (use special formatting from the Title {The Hon Sir McDonald} else use Title GivenName Family Decoration, if GivenName is blank use Title FamilyName).

InitialisedLetterCarrier: Mr GD McDonald NZCE (use special formatting from the Title {The Hon Sir McDonald} else use Title (GivenName MiddleName Initials) FamilyName Decoration, if GivenName is blank use Title FamilyName).

FullLetterCarrier: Mr Geoffrey McDonald (Title FirstName FamilyName)

Salutation: Mr McDonald (Use Title FamilyName, or if title of FamilyName is blank use GivenName)

Decoration: NZCE

DisplayValue: Geoffrey McDonald (FirstName FamilyName)

NameBadge: Jeff (PrefferedName, if blank use FirstName, if blank use Title FamilyName)

Gender: Male (Derive from Title, if fails derive from FirstName, if fails derive from MiddleName) {Male, Female, Undefined}

PreferredName: Jeff

PreferredNameDisplayValue: Jeff McDonald (Use PreferredName FamilyName, if PreferredName is blank use FirstName FamilyName)

PreferredNameOrFirstName: Jeff (user PreferredName, if blank use FirstName)

PreferredNameSalutation: Mr McDonald (Use Title FamilyName, or if title of FamilyName is blank use PreferredName, if PreferredName is blank use GivenName)

PreferredNameLetterCarrier: Mr Jeff McDonald NZCE (use special formatting from the Title {The Hon Sir McDonald} else use Title PreferredName Family Decoration, if PreferredName is blank use Title GivenName Family Decoration, if GivenName is blank use Title FamilyName).

PreferredNameInitialisedLetterCarrier: Mr J D McDonald NZCE (use special formatting from the Title {The Hon Sir McDonald} else use Title (PreferredName MiddleName Initials) FamilyName Decoration, if PreferredName is blank use Title (GivenName MiddleName Initials) FamilyName Decoration , if GivenName is blank use Title FamilyName).

PreferredNameFullLetterCarrier: Mr Jeff McDonald (Title PreferredName FamilyName, if PreferredName is blank use Title GivenName FamilyName)

PreferredNameInitials: J D M (first character from PreferredName, MiddleName, FamilyName. If PreferredName is blank use GivenName, MiddleName, FamilyName.)

PreferredNameInBracketsDisplayValue: Geoffrey (Jeff) McDonald (FirstName (PreferredName) FamilyName, if PreferredName is blank use FirstName FamilyName, if FirstName is blank use PreferredName FamilyName).

Name Web Service – Result/Error Codes

‘Label Code’ refers to the Token as it is stored in the database, ‘Token’ refers to the Token as it is stored in the passport application

0 OK

1001 Exception

1006 Duplicate Label Code

1012 Invalid Name

1013 Account Status Active

1014 Account Status Inactive

1016 User already has an active token

3001 Invalid Token

3004 Insufficient Privileges

3006 Maximum Session Requests Exceeded

3007 Invalid Credentials