Data Integration Web Services Whitepaper - Technical
Overview
The Simplicity Data Integration web services provide the means of interacting with customer data, campaign activities, email services and any configured entity access.
This includes the creation, deletion and maintance of data (such as names or email addresses in a person entity) and the creation, deletion and maintance of relationships (such as a person employed in an organization). It also includes the ability to create campaign activity, and send emails. For a more detailed explanation, please see below.
Campaign activity services are used to insert campaign activity (in the form of emails, exports, and surveys) against an entity. 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/CampaignActivitySvc.asmx
Email services are used to send emails. These emails can be for campaigns, from templates, delayed, or a mixture of these options. 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/EmailSvc.asmx
Survey answer services are used to store the answers of an online survey against an entity (such as a person). This is helpful for analyzing data, and keeping historical records of each user. This service can be delivered via http or https with the use of a SSL certificate where required.
/SingleView/Common/SurveyAnswerSvc.asmx
Entity interaction services are used to select and manipulate data held within the attributes of entities (such as a person entity, or an organization entity). 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.
The first example provided illustrates a person entity service configured to have all available data attributes available to interact with.
/SingleView/Entities/PersonSvc.asmx
The second example provided illustrates a second person entity service configured to have a small subset of the available data attributes available to interact with.
/SingleView/Entities/SecondPersonSvc.asmx
The third example provided illustrates an organisation entity service configured to have a small subset of data attributes available to interact with.
/SingleView/Entities/OrganisationSvc.asmx
Any other required entities would be configured with a URL as illustrated below.
/SingleView/Entities/{ConfiguredEntity}Svc.asmx
Stored Procedure services are used to integrate additional functionality that currently exists within a clients Simplicity version. This allows stored procedures (such as “Household_Program_Dedupe”) to be integrated seamlessly as a Web Service method. If there is a stored procedure that you would like exposted to Web services, please contact your Simplicity Account Manager.
Selection Via List Functionality can be used to return a list that may contain attributes from multiple related entities in a record, as opposed to elements from a single entity. If you would like this functionality exposed to Web Services, please contact your Simplicity Account Manager.
Accessibility Diagram
The web services are accessed via standard web requests as illustrated.
The web services are accessed via standard web requests as illustrated.
Campaign Activity Web Service Method Definitions
The following methods provide the means to create associated campaign activity records against people or other required entities in Simplicity. 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/CampaignActivitySvc.asmx
- Creating a Campaign Activity Object
- InsertActivity
- InsertEmailActivity
- InsertExportActivity
- InsertSurveyActivity
- InsertActivity with Campaign List
- InsertEmailActivity with Campaign List
- InsertExportActivity with Campaign List
- InsertSurveyActivity with Campaign List
- CampaignActivity Result/Error Codes
Creating a Campaign Activity Object
This method is used to create a CampaignActivity Service object in VB.NET using the following code:
(Assumes the web reference is named ‘CampaignActivityService’)
Dim campaignactivitysvc As CampaignActivityService.CampaignActivitySvc
campaignactivitysvc = New CampaignActivityService.CampaignActivitySvc
Web Service Method – InsertActivity
This method is used to insert Activity against an entity.
Parameters
| Token: |
Token returned by Logging in to the Passport Web Service. |
| CampaignName: |
The campaign which the Inserted Activity will be associated with. If the campaign does not exist it will be created. If it is blank or ambiguous, i.e. multiple campaigns with the same name exist, no campaign tracking is initiated and the Activity will not be inserted.
|
| CampaignSegmentName: |
The campaign segment which the Inserted Activity will be associated with. If the campaign segment does not exist it will be created. If it is blank or ambiguous, i.e. multiple campaign segments with the same name exist for the given campaign, no campaign tracking is initiated and the Activity will not be inserted. |
| ActivityType: |
The Type of the Activity being inserted. |
| ActivitySubType: |
The Subtype of the Acitivity being inserted. |
| LogAgainstEntities: |
The list of entities that the campaign activities will be logged against. This list can be empty. LogAgainstEntities is an array of the following properties:
|
Public Class CampaignListEntity
Property EntityType As String
Property EntityRSN As String
End Class
Returns
Result contains the following properties:
Public ClassCreateCampaignActivityResult
Property CampaignAcitivtyRSN() As String
Property CampaignListRSN() As String
Property ErrorCode() As Integer
End Class
Sample Code (In VB.Net)
' Create the CampaignActivity Service
Dim campaignActivitySvc As CampaignActivityService.CampaignActivitySvc
campaignActivitySvc = New CampaignActivityService.CampaignActivitySvc
' Create the LogAgainstEntities object
Dim logAgainstList As New CampaignActivityService.CampaignListEntity
' Insert the activity
Dim campaignActivityResults As CampaignActivityService.CreateCampaignActivityResult
campaignActivityResults = campaignActivitySvc.InsertActivity (token, campaignName, campaignSegmentName, activityType, activitySubType, logAgainstList)
Web Service Method – InsertEmailActivity
This method is used to insert Email Campaign Activity against an entity.
Parameters
| Token: |
Token returned by Logging in to the Passport Web Service. |
| CampaignName: |
The campaign which the Inserted Activity will be associated with. If the campaign does not exist it will be created. If it is blank or ambiguous, i.e. multiple campaigns with the same name exist, no campaign tracking is initiated and the Activity will not be inserted.
|
| CampaignSegmentName: |
The campaign segment which the Inserted Activity will be associated with. If the campaign segment does not exist it will be created. If it is blank or ambiguous, i.e. multiple campaign segments with the same name exist for the given campaign, no campaign tracking is initiated and the Activity will not be inserted. |
| ActivityType: |
The Type of the Email Activity being inserted. |
| EmailAddress: |
The Email Address that this Activity will be associated with |
| LogAgainstEntities: |
The list of entities that the campaign activities will be logged against. This list can be empty. LogAgainstEntities is an array of the following properties: |
Public Class CampaignListEntity
Property EntityType As String
Property EntityRSN As String
End Class
Returns
Result contains the following properties:
Public ClassCreateCampaignActivityResult
Property CampaignAcitivtyRSN() As String
Property CampaignListRSN() As String
Property ErrorCode() As Integer
End Class
Sample Code (in VB.Net)
' Create the CampaignActivity Service
Dim campaignActivitySvc As CampaignActivityService.CampaignActivitySvc
campaignActivitySvc = New CampaignActivityService.CampaignActivitySvc
' Create the LogAgainstEntities object
Dim logAgainstList As New CampaignActivityService.CampaignListEntity
' Insert the email activity
Dim campaignEmailActivityResults As CampaignActivityService.CreateCampaignActivityResult
campaignEmailActivityResults = campaignActivitySvc.InsertEmailActivity (token, campaignName, campaignSegmentName, activityType, emailAddress, logAgainstList)
Web Service Method – InsertExportActivity
This method is used to insert Export Campaign Activity against an entity.
Parameters
| Token: |
Token returned by Logging in to the Passport Web Service. |
| CampaignName: |
The campaign which the Inserted Activity will be associated with. If the campaign does not exist it will be created. If it is blank or ambiguous, i.e. multiple campaigns with the same name exist, no campaign tracking is initiated and the Activity will not be inserted. |
| CampaignSegmentName: |
The campaign segment which the Inserted Activity will be associated with. If the campaign segment does not exist it will be created. If it is blank or ambiguous, i.e. multiple campaign segments with the same name exist for the given campaign, no campaign tracking is initiated and the Activity will not be inserted. |
| ActivityType: |
The Type of the Activity being inserted. |
| LogAgainstEntities: |
The list of entities that the campaign activities will be logged against. This list can be empty. LogAgainstEntities is an array of the following properties: |
Public Class CampaignListEntity
Property EntityType As String
Property EntityRSN As String
End Class
Returns
Result contains the following properties:
Public ClassCreateCampaignActivityResult
Property CampaignAcitivtyRSN() As String
Property CampaignListRSN() As String
Property ErrorCode() As Integer
End Class
Sample Code (in VB.Net)
' Create the CampaignActivity Service
Dim campaignActivitySvc As CampaignActivityService.CampaignActivitySvc
campaignActivitySvc = New CampaignActivityService.CampaignActivitySvc
' Create the LogAgainstEntities object
Dim logAgainstList As New CampaignActivityService.CampaignListEntity
' Insert the export activity
Dim campaignExportActivityResults As CampaignActivityService.CreateCampaignActivityResult
campaignExportActivityResults = campaignActivitySvc.InsertExportActivity (token, campaignName, campaignSegmentName, activityType, logAgainstList)
Web Service Method – InsertSurveyActivity
This method is used to insert Survey Campaign Activity against an entity.
Parameters
| Token: |
Token returned by Logging in to the Passport Web Service. |
| CampaignName: |
The campaign which the Inserted Activity will be associated with. If the campaign does not exist it will be created. If it is blank or ambiguous, i.e. multiple campaigns with the same name exist, no campaign tracking is initiated and the Activity will not be inserted. |
| CampaignSegmentName: |
The campaign segment which the Inserted Activity will be associated with. If the campaign segment does not exist it will be created. If it is blank or ambiguous, i.e. multiple campaign segments with the same name exist for the given campaign, no campaign tracking is initiated and the Activity will not be inserted. |
| ActivityType: |
The Type of the Activity being inserted. |
| SurveyName: |
The name of the survey this activity will be associated with. |
| LogAgainstEntities: |
The list of entities that the campaign activities will be logged against. This list can be empty. LogAgainstEntities is an array of the following properties: |
Public Class CampaignListEntity
Property EntityType As String
Property EntityRSN As String
End Class
Returns
Result contains the following properties:
Public ClassCreateCampaignActivityResult
Property CampaignAcitivtyRSN() As String
Property CampaignListRSN() As String
Property ErrorCode() As Integer
End Class
Sample Code (in VB.Net)
' Create the CampaignActivity Service
Dim campaignActivitySvc As CampaignActivityService.CampaignActivitySvc
campaignActivitySvc = New CampaignActivityService.CampaignActivitySvc
' Create the LogAgainstEntities object
Dim logAgainstList As New CampaignActivityService.CampaignListEntity
' Insert the survey activity
Dim campaignSurveyActivityResults As CampaignActivityService.CreateCampaignActivityResult
campaignSurveyActivityResults = campaignActivitySvc.InsertSurveyActivity (token, campaignName, campaignSegmentName, activityType, surveyName, logAgainstList)
Web Service Method – InsertActivityWithCampaignList
This method is used to insert Activity against an entity.
Parameters
| Token: |
Token returned by Logging in to the Passport Web Service. |
| CampaignSegmentRSN: |
The unique id (a GUID) of the campaign segment which the Inserted Activity will be associated with. |
| CampaignListRSN: |
This is the unique indenifier (a GUID) for the Campaign List associated with the inserted Activity. A Campaign List is a list the holds the relationships between the campaign, the user, any activities or associated codes. |
| ActivityType: |
The Type of the Activity being inserted. |
| ActivitySubType: |
The Subtype of the Acitivity being inserted. |
| LogAgainstEntities: |
The list of entities that the campaign activities will be logged against. This list can be empty. LogAgainstEntities is an array of the following properties: |
Public Class CampaignListEntity
Property EntityType As String
Property EntityRSN As String
End Class
Returns
Result contains the following properties:
Public ClassCreateCampaignActivityResult
Property CampaignAcitivtyRSN() As String
Property CampaignListRSN() As String
Property ErrorCode() As Integer
End Class
Sample Code (In VB.Net)
' Create the CampaignActivity Service
Dim campaignActivitySvc As CampaignActivityService.CampaignActivitySvc
campaignActivitySvc = New CampaignActivityService.CampaignActivitySvc
' Create the LogAgainstEntities object
Dim logAgainstList As New CampaignActivityService.CampaignListEntity
' Insert the activity
Dim campaignActivityResults As CampaignActivityService.CreateCampaignActivityResult
campaignActivityResults = campaignActivitySvc.InsertActivity (token, CampaignSegmentRSN campaignListRSN, activityType, activitySubType, logAgainstList)
Web Service Method – InsertEmailActivityWithCampaignList
This method is used to insert Email Campaign Activity against an entity.
Parameters
| Token: |
Token returned by Logging in to the Passport Web Service. |
| CampaignSegmentRSN: |
The unique id (a GUID) of the campaign segment which the Inserted Activity will be associated with. |
| CampaignListRSN: |
This is the unique indenifier (a GUID) for the Campaign List associated with the inserted Activity. A Campaign List is a list the holds the relationships between the campaign, the user, any activities or associated codes. |
| ActivityType: |
The Type of the Activity being inserted. |
| EmailAddress: |
The Email Address that this Activity will be associated with |
| LogAgainstEntities: |
The list of entities that the campaign activities will be logged against. This list can be empty. LogAgainstEntities is an array of the following properties: |
Public Class CampaignListEntity
Property EntityType As String
Property EntityRSN As String
End Class
Returns
Result contains the following properties:
Public ClassCreateCampaignActivityResult
Property CampaignAcitivtyRSN() As String
Property CampaignListRSN() As String
Property ErrorCode() As Integer
End Class
Sample Code (in VB.Net)
' Create the CampaignActivity Service
Dim campaignActivitySvc As CampaignActivityService.CampaignActivitySvc
campaignActivitySvc = New CampaignActivityService.CampaignActivitySvc
' Create the LogAgainstEntities object
Dim logAgainstList As New CampaignActivityService.CampaignListEntity
' Insert the email activity
Dim campaignEmailActivityResults As CampaignActivityService.CreateCampaignActivityResult
campaignEmailActivityResults = campaignActivitySvc.InsertEmailActivity (token, campaignSegmentRSN, campaignListRSN, activityType, emailAddress, logAgainstList)
Web Service Method – InsertExportActivityWithCampaignList
This method is used to insert Export Campaign Activity against an entity.
Parameters
| Token: |
Token returned by Logging in to the Passport Web Service. |
| CampaignSegmentRSN: |
The campaign segment which the Inserted Activity will be associated with. If the campaign segment does not exist it will be created. If it is blank or ambiguous, i.e. multiple campaign segments with the same name exist for the given campaign, no campaign tracking is initiated and the Activity will not be inserted. |
| CampaignListRSN: |
This is the unique indenifier (a GUID) for the Campaign List associated with the inserted Activity. A Campaign List is a list the holds the relationships between the campaign, the user, any activities or associated codes. |
| ActivityType: |
The Type of the Activity being inserted. |
| LogAgainstEntities: |
The list of entities that the campaign activities will be logged against. This list can be empty. LogAgainstEntities is an array of the following properties: |
Public Class CampaignListEntity
Property EntityType As String
Property EntityRSN As String
End Class
Returns
Result contains the following properties:
Public ClassCreateCampaignActivityResult
Property CampaignAcitivtyRSN() As String
Property CampaignListRSN() As String
Property ErrorCode() As Integer
End Class
Sample Code (in VB.Net)
' Create the CampaignActivity Service
Dim campaignActivitySvc As CampaignActivityService.CampaignActivitySvc
campaignActivitySvc = New CampaignActivityService.CampaignActivitySvc
' Create the LogAgainstEntities object
Dim logAgainstList As New CampaignActivityService.CampaignListEntity
' Insert the export activity
Dim campaignExportActivityResults As CampaignActivityService.CreateCampaignActivityResult
campaignExportActivityResults = campaignActivitySvc.InsertExportActivity (token, CampaignSegmentRSN, CampaignListRSN, activityType, logAgainstList)
Web Service Method – InsertSurveyActivityWithCampaignList
This method is used to insert Survey Campaign Activity against an entity.
Parameters
| Token: |
Token returned by Logging in to the Passport Web Service. |
| CampaignSegmentRSN: |
The campaign segment which the Inserted Activity will be associated with. If the campaign segment does not exist it will be created. If it is blank or ambiguous, i.e. multiple campaign segments with the same name exist for the given campaign, no campaign tracking is initiated and the Activity will not be inserted. |
| CampaignListRSN: |
This is the unique indenifier (a GUID) for the Campaign List associated with the inserted Activity. A Campaign List is a list the holds the relationships between the campaign, the user, any activities or associated codes. |
| ActivityType: |
The Type of the Activity being inserted. |
| SurveyName: |
The name of the survey this activity will be associated with. |
| LogAgainstEntities: |
The list of entities that the campaign activities will be logged against. This list can be empty. LogAgainstEntities is an array of the following properties: |
Public Class CampaignListEntity
Property EntityType As String
Property EntityRSN As String
End Class
Returns
Result contains the following properties:
Public ClassCreateCampaignActivityResult
Property CampaignAcitivtyRSN() As String
Property CampaignListRSN() As String
Property ErrorCode() As Integer
End Class
Sample Code (in VB.Net)
' Create the CampaignActivity Service
Dim campaignActivitySvc As CampaignActivityService.CampaignActivitySvc
campaignActivitySvc = New CampaignActivityService.CampaignActivitySvc
' Create the LogAgainstEntities object
Dim logAgainstList As New CampaignActivityService.CampaignListEntity
' Insert the survey activity
Dim campaignSurveyActivityResults As CampaignActivityService.CreateCampaignActivityResult
campaignSurveyActivityResults = campaignActivitySvc.InsertSurveyActivity (token, CampaignSegmentRSN, CampaignListRSN, activityType, surveyName, logAgainstList)
CampaignActivity 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
1003 Ambiguous Campaign
1005 Ambiguous Campaign Segment
1016 Invalid Campaign List
3001 Invalid Token
3007 Insufficient Privileges
4000 Campaign List Exception
4010 Campaign List Entity Exception
4020 Campaign List Activity Exception
Email Web Service Method Definitions
The following methods provide the means to create and send emails in Simplicity. 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/EmailSvc.asmx
- Creating an Email Object
- SelectEmailStatusById
- SendDelayedEmail
- SendDelayedEmailForCampaign
- SendDelayedEmailFromTemplate
- SendDelayedEmailFromTemplate2 (With Merge Label Codes)
- SendDelayedEmailFromTemplateForCampaign
- SendDelayedEmailFromTemplateForCampaign 2 (With Merge Label Codes)
- SendEmail
- SendEmailForCampaign
- SendEmailFromTemplate
- SendEmailFromTemplate 2 (With Merge Label Codes)
- SendEmailFromTemplateForCampaign
- SendEmailFromTemplateForCampaign 2 (With Merge Label Codes)
- Email Result/Error Codes
Creating an Email Object
This method is used to create an Email object in VB.Net using the following code:
(Assumes the web reference is named ‘EmailService’)
Dim emailsvc As EmailService.EmailSvc
emailsvc = New EmailService.EmailSvc
Web Service Method – SelectEmailStatusById
This method returns an email object of class ‘QueryEmailResult’ when searching with an emailID.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
ID: The ID of the Email to be queried.
Returns
Result contains the following properties:
Public Class QueryEmailResult
Property ErrorCode As Integer
Property EmailID As Int64
Property MessageID As String
Property CampaignListRSN As String
Property Status As String
Property SendAttempts As Integer
Property Sent As Boolean
Property SentOn As DateTime
Property SentBy As String
Property QueuedOn As DateTime
Property QueuedBy As String
End Class
Sample Code (in VB.Net)
' Create the email Service
Dim emailSvc As EmailService.EmailSvc
emailSvc = New EmailService.EmailSvc
' Search on the client ID.
Dim emailResults As EmailService.QueryEmailResult
emailResults = emailSvc.SelectEmailStatusByID(token, emailId)
Web Service Method – SendDelayedEmail
This method is used to delay an email which is to be sent.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
Email: The Email to be queued for sending. Contains the following properties:
Public Class Email
Property To As String
Property Cc As String
Property Bcc As String
Property From As String
Property ReplyTo As String
Property Subject As String
Property BodyText As String
Property BodyHtml As String
End Class
SendAfter: The date after which the email will be sent.
Returns
Result contains the following properties:
Public Class SendEmailResult
Property ErrorCode As Integer
Property EmailID As Int64
Property MessageID As String
Property CampaignListRSN As String
End Class
Sample Code (in VB.Net)
' Create the email Service
Dim emailSvc As EmailService.EmailSvc
emailSvc = New EmailService.EmailSvc
' Queue a delayed email
Dim emailResults As EmailService.SendEmailResult
emailResults = emailSvc.SendDelayedEmail(token, email, sendAfter)
Web Service Method – SendDelayedEmailForCampaign
This method is used to delay an email which is to be sent for a campaign.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
CampaignName: The campaign which the Queued Email will be associated with. If the campaign does not exist it will be created. If it is blank or ambiguous, i.e. multiple campaigns with the same name exist, no campaign tracking is initiated and the Email will not be queued.
CampaignSegmentName: The campaign segment which the Queued Email will be associated with. If the campaign segment does not exist it will be created. If it is blank or ambiguous, i.e. multiple campaign segments with the same name exist for the given campaign, no campaign tracking is initiated and the Email will not be queued.
Email: The Email to be queued for sending. Contains the following properties:
Public Class Email
Property To As String
Property Cc As String
Property Bcc As String
Property From As String
Property ReplyTo As String
Property Subject As String
Property BodyText As String
Property BodyHtml As String
End Class
SendAfter: The date after which the email will be sent.
LogAgainstEntities: The list of entities that the campaign activities will be logged against. This list can be empty. LogAgainstEntities is an array of the following properties:
Public Class CampaignListEntity
Property EntityType As String
Property EntityRSN As String
End Class
Returns
Result contains the following properties:
Public Class SendEmailResult
Property ErrorCode As Integer
Property EmailID As Int64
Property MessageID As String
Property CampaignListRSN As String
End Class
Sample Code (in VB.Net)
' Create the email Service
Dim emailsvc As EmailService.EmailSvc
emailsvc = New EmailService.EmailSvc
' Create the LogAgainstEntity object
Dim entityList As New EmailService.CampaignListEntity
' Send a delayed email for a campaign
Dim emailResults As EmailService.SendEmailResult
emailResults = emailsvc.SendDelayedEmailForCampaign(token, campaignName, campaignSegmentName, email, sendAfter, entityList)
Web Service Method – SendDelayedEmailFromTemplate
This method is used to delay an email which is to be sent from a template.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
EmailTemplate: The name of the Email Template to be queued.
SendAfter: The date after which the email will be sent.
MergeEntities: The list of entities to be merged into the Email Template. MergeEntities is an array of the following properties:
Public Class CampaignListEntity
Property EntityType As String
Property EntityRSN As String
End Class
Returns
Result contains the following properties:
Public Class SendEmailResult
Property ErrorCode As Integer
Property EmailID As Int64
Property MessageID As String
Property CampaignListRSN As String
End Class
Sample Code (in VB.Net)
' Create the email Service
Dim emailsvc As EmailService.EmailSvc
emailsvc = New EmailService.EmailSvc
' Create the MergeEntities object
Dim mergeEntities As New EmailService.CampaignListEntity
' Send a delayed email from a template
Dim emailResults As EmailService.SendEmailResult
emailResults = emailsvc.SendDelayedEmailFromTemplate(token, emailTemplate, sendAfter, mergeEntities)
Web Service Method – SendDelayedEmailFromTemplate 2 (With Merge Label Codes)
This method is used to delay an email which is to be sent from a template.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
EmailTemplate: The name of the Email Template to be queued.
SendAfter: The date after which the email will be sent.
MergeEntities: The list of entities to be merged into the Email Template. MergeEntities is an array of the following properties:
Public Class CampaignListEntity
Property EntityType As String
Property EntityRSN As String
End Class
LabelCodes: The merge codes which allow information in the email to be personalized to the user. LabelCodes are an array of the following properties:
Public Class MergeLabelCodes
Property LabelCode As String
Property LabelCodeName As String
End Class
Returns
Result contains the following properties:
Public Class SendEmailResult
Property ErrorCode As Integer
Property EmailID As Int64
Property MessageID As String
Property CampaignListRSN As String
End Class
Sample Code (in VB.Net)
' Create the email Service
Dim emailsvc As EmailService.EmailSvc
emailsvc = New EmailService.EmailSvc
' Create the MergeEntities object
Dim mergeEntities As New EmailService.CampaignListEntity
' Create the Label Codes object
Dim labelCodes As New EmailService.MergeLabelCode
' Send a delayed email from a template
Dim emailResults As EmailService.SendEmailResult
emailResults = emailsvc.SendDelayedEmailFromTemplate(token, emailTemplate, sendAfter, mergeEntities, labelCodes)
Web Service Method – SendDelayedEmailFromTemplateForCampaign
This method is used to delay an email which is to be sent from a template for a campaign.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
CampaignName: The campaign which the Queued Email will be associated with. If the campaign does not exist it will be created. If it is blank or ambiguous, i.e. multiple campaigns with the same name exist, no campaign tracking is initiated and the Email will not be queued.
CampaignSegmentName: The campaign segment which the Queued Email will be associated with. If the campaign segment does not exist it will be created. If it is blank or ambiguous, i.e. multiple campaign segments with the same name exist for the given campaign, no campaign tracking is initiated and the Email will not be queued.
EmailTemplate: The name of the Email Template to be queued.
SendAfter: The date after which the email will be sent.
MergeEntities: The list of entities to be merged into the Email Template. MergeEntities is an array of the following properties:
Public Class CampaignListEntity
Property EntityType As String
Property EntityRSN As String
End Class
LogAgainstEntities: The list of entities that the campaign activities will be logged against. This list can be empty. LogAgainstEntities is an array of the following properties:
Public Class CampaignListEntity
Property EntityType As String
Property EntityRSN As String
End Class
Returns
Result contains the following properties:
Public Class SendEmailResult
Property ErrorCode As Integer
Property EmailID As Int64
Property MessageID As String
Property CampaignListRSN As String
End Class
Sample Code (in VB.Net)
' Create the email Service
Dim emailSvc As EmailService.EmailSvc
emailSvc = New EmailService.EmailSvc
' Create the MergeEntites object
Dim mergeEntities As New EmailService.CampaignListEntity
' Create the LogAgainstEntities object
Dim logEntities As New EmailService.CampaignListEntity
' Queue a delayed template email for campaign
Dim emailResults As EmailService.SendEmailResult
emailResults = emailSvc.SendDelayedEmailFromTemplateForCampaign(token, campaignName, campaignSegmentName, emailTemplate, sendAfter, mergeEntities, logEntities)
Web Service Method – SendDelayedEmailFromTemplateForCampaign 2 (with Merge Label Codes)
This method is used to delay an email which is to be sent from a template for a campaign.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
CampaignName: The campaign which the Queued Email will be associated with. If the campaign does not exist it will be created. If it is blank or ambiguous, i.e. multiple campaigns with the same name exist, no campaign tracking is initiated and the Email will not be queued.
CampaignSegmentName: The campaign segment which the Queued Email will be associated with. If the campaign segment does not exist it will be created. If it is blank or ambiguous, i.e. multiple campaign segments with the same name exist for the given campaign, no campaign tracking is initiated and the Email will not be queued.
EmailTemplate: The name of the Email Template to be queued.
SendAfter: The date after which the email will be sent.
MergeEntities: The list of entities to be merged into the Email Template. MergeEntities is an array of the following properties:
Public Class CampaignListEntity
Property EntityType As String
Property EntityRSN As String
End Class
LabelCodes: The merge codes which allow information in the email to be personalized to the user. LabelCodes are an array of the following properties:
Public Class MergeLabelCodes
Property LabelCode As String
Property LabelCodeName As String
End Class
LogAgainstEntities: The list of entities that the campaign activities will be logged against. This list can be empty. LogAgainstEntities is an array of the following properties:
Public Class CampaignListEntity
Property EntityType As String
Property EntityRSN As String
End Class
Returns
Result contains the following properties:
Public Class SendEmailResult
Property ErrorCode As Integer
Property EmailID As Int64
Property MessageID As String
Property CampaignListRSN As String
End Class
Sample Code (in VB.Net)
' Create the email Service
Dim emailSvc As EmailService.EmailSvc
emailSvc = New EmailService.EmailSvc
' Create the MergeEntites object
Dim mergeEntities As New EmailService.CampaignListEntity
' Create the LogAgainstEntities object
Dim logEntities As New EmailService.CampaignListEntity
' Create the Label Codes object
Dim labelCodes As New EmailService.MergeLabelCode
' Queue a delayed template email for campaign
Dim emailResults As EmailService.SendEmailResult
emailResults = emailSvc.SendDelayedEmailFromTemplateForCampaign(token, campaignName, campaignSegmentName, emailTemplate, sendAfter, mergeEntities, labelCodes, logEntities)
Web Service Method – SendEmail
This method is used to send an email.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
Email: The Email to be queued for sending. Contains the following properties:
Public Class Email
Property To As String
Property Cc As String
Property Bcc As String
Property From As String
Property ReplyTo As String
Property Subject As String
Property BodyText As String
Property BodyHtml As String
End Class
Returns
Result contains the following properties:
Public Class SendEmailResult
Property ErrorCode As Integer
Property EmailID As Int64
Property MessageID As String
Property CampaignListRSN As String
End Class
Sample Code (in VB.Net)
' Create the email Service
Dim emailsvc As EmailService.EmailSvc
emailsvc = New EmailService.EmailSvc
' Send an email
Dim emailResults As EmailService.SendEmailResult emailResults = emailsvc.SendEmail(token, Email)
Web Service Method – SendEmailForCampaign
This method is used to send an email for a campaign.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
CampaignName: The campaign which the Queued Email will be associated with. If the campaign does not exist it will be created. If it is blank or ambiguous, i.e. multiple campaigns with the same name exist, no campaign tracking is initiated and the Email will not be queued.
CampaignSegmentName: The campaign segment which the Queued Email will be associated with. If the campaign segment does not exist it will be created. If it is blank or ambiguous, i.e. multiple campaign segments with the same name exist for the given campaign, no campaign tracking is initiated and the Email will not be queued.
Email: The Email to be queued for sending. Contains the following properties:
Public Class Email
Property To As String
Property Cc As String
Property Bcc As String
Property From As String
Property ReplyTo As String
Property Subject As String
Property BodyText As String
Property BodyHtml As String
End Class
LogAgainstEntities: The list of entities that the campaign activities will be logged against. This list can be empty. LogAgainstEntities is an array of the following properties:
Public Class CampaignListEntity
Property EntityType As String
Property EntityRSN As String
End Class
Returns
Result contains the following properties:
Public Class SendEmailResult
Property EmailID As Int64
Property MessageID As String
Property CampaignListRSN As String
End Class
Sample Code (in VB.Net)
Sample code demonstrates obtaining a valid token and sending a campaign email
Web Service Method – SendEmailFromTemplate
This method is used to send an email from a template.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
EmailTemplate: The name of the Email Template to be queued for immediate sending.
MergeEntities: The list of entities to be merged into the Email Template. MergeEntities is an array of the following properties:
Public Class CampaignListEntity
Property EntityType As String
Property EntityRSN As String
End Class
Returns
Result contains the following properties:
Public Class SendEmailResult
Property ErrorCode As Integer
Property EmailID As Int64
Property MessageID As String
Property CampaignListRSN As String
End Class
Sample Code (in VB.Net)
' Create the email Service
Dim emailsvc As EmailService.EmailSvc
emailsvc = New EmailService.EmailSvc
' Create the MergeEntity object
Dim entityList As New EmailService.CampaignListEntity
' Queue a template email
Dim emailResults As EmailService.SendEmailResult
emailResults = emailsvc.SendEmailFromTemplate(token, emailTemplate, entityList)
Web Service Method – SendEmailFromTemplate 2 (with Merge Label Codes)
This method is used to send an email from a template.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
EmailTemplate: The name of the Email Template to be queued for immediate sending.
MergeEntities: The list of entities to be merged into the Email Template. MergeEntities is an array of the following properties:
Public Class CampaignListEntity
Property EntityType As String
Property EntityRSN As String
End Class
LabelCodes: The merge codes which allow information in the email to be personalized to the user. LabelCodes are an array of the following properties:
Public Class MergeLabelCodes
Property LabelCode As String
Property LabelCodeName As String
End Class
Returns
Result contains the following properties:
Public Class SendEmailResult
Property ErrorCode As Integer
Property EmailID As Int64
Property MessageID As String
Property CampaignListRSN As String
End Class
Sample Code (in VB.Net)
' Create the email Service
Dim emailsvc As EmailService.EmailSvc
emailsvc = New EmailService.EmailSvc
' Create the MergeEntity object
Dim entityList As New EmailService.CampaignListEntity
' Create the Label Codes object
Dim labelCodes As New EmailService.MergeLabelCode
' Queue a template email
Dim emailResults As EmailService.SendEmailResult
emailResults = emailsvc.SendEmailFromTemplate(token, emailTemplate, entityList, labelCodes)
Web Service Method – SendEmailFromTemplateForCampaign
This method is used to send an email from a template for a campaign.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
CampaignName: The campaign which the Queued Email will be associated with. If the campaign does not exist it will be created. If it is blank or ambiguous, i.e. multiple campaigns with the same name exist, no campaign tracking is initiated and the Email will not be queued.
CampaignSegmentName: The campaign segment which the Queued Email will be associated with. If the campaign segment does not exist it will be created. If it is blank or ambiguous, i.e. multiple campaign segments with the same name exist for the given campaign, no campaign tracking is initiated and the Email will not be queued.
EmailTemplate: The name of the Email Template to be queued for immediate sending.
MergeEntities: The list of entities to be merged into the Email Template. MergeEntities is an array of the following properties:
Public Class CampaignListEntity
Property EntityType As String
Property EntityRSN As String
End Class
LogAgainstEntities: The list of entities that the campaign activities will be logged against. This list can be empty. LogAgainstEntities is an array of the following properties:
Public Class CampaignListEntity
Property EntityType As String
Property EntityRSN As String
End Class
Returns
Result contains the following properties:
Public Class SendEmailResult
Property ErrorCode As Integer
Property EmailID As Int64
Property MessageID As String
Property CampaignListRSN As String
End Class
Sample Code (in VB.Net)
' Create the email Service
Dim emailsvc As EmailService.EmailSvc
emailsvc = New EmailService.EmailSvc
' Create the MergeEntities object
Dim mergeEntities As New EmailService.CampaignListEntity
' Create the LogAgainstEntities object
Dim logEntities As New EmailService.CampaignListEntity
' Send a template email for campaign
Dim emailResults As EmailService.SendEmailResult
emailResults = emailsvc.SendEmailFromTemplateForCampaign(token, campaignName, campaignSegmentName, emailTemplate, mergeEntities, logEntities)
Web Service Method – SendEmailFromTemplateForCampaign 2 (With Merge Label Codes)
This method is used to send an email from a template for a campaign.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
CampaignName: The campaign which the Queued Email will be associated with. If the campaign does not exist it will be created. If it is blank or ambiguous, i.e. multiple campaigns with the same name exist, no campaign tracking is initiated and the Email will not be queued.
CampaignSegmentName: The campaign segment which the Queued Email will be associated with. If the campaign segment does not exist it will be created. If it is blank or ambiguous, i.e. multiple campaign segments with the same name exist for the given campaign, no campaign tracking is initiated and the Email will not be queued.
EmailTemplate: The name of the Email Template to be queued for immediate sending.
MergeEntities: The list of entities to be merged into the Email Template. MergeEntities is an array of the following properties:
Public Class CampaignListEntity
Property EntityType As String
Property EntityRSN As String
End Class
LabelCodes: The merge codes which allow information in the email to be personalized to the user. LabelCodes are an array of the following properties:
Public Class MergeLabelCodes
Property LabelCode As String
Property LabelCodeName As String
End Class
LogAgainstEntities: The list of entities that the campaign activities will be logged against. This list can be empty. LogAgainstEntities is an array of the following properties:
Public Class CampaignListEntity
Property EntityType As String
Property EntityRSN As String
End Class
Returns
Result contains the following properties:
Public Class SendEmailResult
Property ErrorCode As Integer
Property EmailID As Int64
Property MessageID As String
Property CampaignListRSN As String
End Class
Sample Code (in VB.Net)
' Create the email Service
Dim emailsvc As EmailService.EmailSvc
emailsvc = New EmailService.EmailSvc
' Create the MergeEntities object
Dim mergeEntities As New EmailService.CampaignListEntity
' Create the LogAgainstEntities object
Dim logEntities As New EmailService.CampaignListEntity
' Create the Label Codes object
Dim labelCodes As New EmailService.MergeLabelCode
' Send a template email for campaign
Dim emailResults As EmailService.SendEmailResult
emailResults = emailsvc.SendEmailFromTemplateForCampaign(token, campaignName, campaignSegmentName, emailTemplate, mergeEntities, labelCodes, logEntities)
Email 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
1003 Ambiguous Campaign
1005 Ambiguous Campaign Segment
1016 Invalid Campaign List
3001 Invalid Token
3007 Insufficient Privileges
4000 Campaign List Exception
4010 Campaign List Entity Exception
4030 Email Send Exception
4040 Email Merge Exception
Survey Answers Web Service Method Definitions
The following methods provide the means to select and create survey answer records against entities (such as a person, or organisation) in Simplicity. 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/surveyanswersvc.asmx
- Creating a Survey Answer Object
- Insert
- InsertRange
- SelectByCampaignListRSN
- SelectByDedupeKey
- SelectByLabelCode
- SelectByRSN
- SelectBySurveyInstanceRSN
- SelectDedupeKeyCount
Creating a Survey Answer Object
This method is used to create a SurveyAnswer Service object in VB.NET using the following code:
(Assumes the web reference is named ‘SurveyAnswerService’)
Dim surveyanswersvc As SurveyAnswerService.SurveyAnswerSvc
surveyanswersvc = New SurveyAnswerService.SurveyAnswerSvc
Web Service Method – Insert
This method is used to insert a survey answer record into Simplicity.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
SurveyAnswer: A survey answer object which contains the following properties:
Public Class SurveyAnswer
Property RSN As String
Property DisplayValue As String
Property Survey_RSN As String
Property Parent_RSN As String
Property SurveyInstance_RSN As String
Property OnlineForm_RSN As String
Property DateTime As Date
Property KeyCode As Date
Property LabelCode As Date
Property Page_Index As Date
Property Survey_Index As Date
Property SurveyInstance_DedupeKey As Date
Property Answers As Answers
End Class
Public Class Answers
Property SurveyAnswerField As SurveyAnswerField
End Class
Public Class SurveyAnswerField
Property FieldName as String
Property Value
End Class
Glossary
RSN: This is the unique identifier (a GUID) of this Survey Answer Record (this field is a required field).
DisplayValue: This is a string that appears in the Simplicity Explorers for this record. This is usually the name of the survey.
Survey_RSN: This is the unique indentifier (a GUID) of the Survey.
Parent_RSN: This is the entity to which the survey answer record will be linked to. For example, if a survey is about a person’s lifestyle choices you may want to link it to the person who filled it out, and you will store the persons RSN in this field.
SurveyInstance_RSN: This is the unique identifier (a GUID) for this instance of the survey, and its unique answers.
OnlineForm_RSN: This is the unique indentifer (a GUID) for the online form attached to this survey. An online form is made of surveys.
DateTime: This is the date and times that the survey answers were completed.
KeyCode: This is a unique code that allows users paths to the survey to be tracked. Website tiles or emails may pass through a unique keycode that may be helpful for analysis at a later date.
LabelCode: A labelcode is a unique code that allows an entity (such as a person) to be linked back to a record within Simplicity.
Page_Index: This is the page order number that the survey answered appears on (an online form may be made of up multiple pages, and there may be multiple surveys on a page)
Survey_Index: This is the survey order number that the survey answered appears in.
SurveyInstance_DedupeKey: This is a field used to prevent a user from entering a survey multiple times.
FieldName: This is the survey answer field field name. This MUST match what has been set up on the survey in Simplicity. (It will look something like 00001).
Value: This is the value that the user has entered.
Returns
Result contains the following properties:
Public Class InsertResult
Property ErrorCode As Integer
Property RSN as String
Property SurveyInstance_RSN as String
Property LogAgainst_RSN as String
Property Survey_Index as Integer
Property PageIndex as Integer
End Class
Sample Code (in VB.Net)
' Create new survey answer service
Dim surveyAnswerSvc As SurveyAnswerService.SurveyAnswerSvc
surveyAnswerSvc = New SurveyAnswerService.SurveyAnswerSvc
' Create answers
Dim answers(1) As SurveyAnswerService.SurveyAnswerField
answers(1) = New SurveyAnswerService.SurveyAnswerField
answers(0).FieldName = "00001"
answers(0).Value = "Answer to be stored against this field"
' Create survey answers
Dim surveyAnswers As SurveyAnswerService.SurveyAnswer
surveyAnswers = New SurveyAnswerService.SurveyAnswer
' Assign values
' Please note not all values have been populated. Please populate these yourself.
surveyAnswers.RSN = Guid.NewGuid.ToString
surveyAnswers.DisplayValue = "Survey Display Value"
surveyAnswers.Date = Today.Date()
surveyAnswers.Answers = answers
Dim insertResults As SurveyAnswerService.InsertResult
insertResults = surveyAnswerSvc.Insert(token, surveyAnswers)
Web Service Method – Insert Range
This method is used to insert a multiple of survey answer records into Simplicity.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
SurveyAnswers: A survey answer object which contains the following properties:
Public Class SurveyAnswer
Property RSN As String
Property DisplayValue As String
Property Survey_RSN As String
Property Parent_RSN As String
Property SurveyInstance_RSN As String
Property OnlineForm_RSN As String
Property DateTime As Date
Property KeyCode As Date
Property LabelCode As Date
Property Page_Index As Date
Property Survey_Index As Date
Property SurveyInstance_DedupeKey As Date
Property Answers As Answers
End Class
Public Class Answers
Property SurveyAnswerField As SurveyAnswerField
End Class
Glossary
RSN: This is the unique identifier (a GUID) of this Survey Answer Record (this field is a required field).
DisplayValue: This is a string that appears in the Simplicity Explorers for this record. This is usually the name of the survey.
Survey_RSN: This is the unique indentifier (a GUID) of the Survey.
Parent_RSN: This is the entity to which the survey answer record will be linked to. For example, if a survey is about a person’s lifestyle choices you may want to link it to the person who filled it out, and you will store the persons RSN in this field.
SurveyInstance_RSN: This is the unique identifier (a GUID) for this instance of the survey, and its unique answers.
OnlineForm_RSN: This is the unique indentifer (a GUID) for the online form attached to this survey. An online form is made of surveys.
DateTime: This is the date and times that the survey answers were completed.
KeyCode: This is a unique code that allows users paths to the survey to be tracked. Website tiles or emails may pass through a unique keycode that may be helpful for analysis at a later date.
LabelCode: A labelcode is a unique code that allows an entity (such as a person) to be linked back to a record within Simplicity.
Page_Index: This is the page order number that the survey answered appears on (an online form may be made of up multiple pages, and there may be multiple surveys on a page)
Survey_Index: This is the survey order number that the survey answered appears in.
SurveyInstance_DedupeKey: This is a field used to prevent a user from entering a survey multiple times.
Returns
Result contains the following properties:
Public Class InsertResult
Property ErrorCode As Integer
Property RSN as String
Property SurveyInstance_RSN as String
Property LogAgainst_RSN as String
Property Survey_Index as Integer
Property Page_Index as Integer
End Class
Sample Code (in VB.Net)
' Create new survey answer service object
Dim surveyAnswerSvc As SurveyAnswerService.SurveyAnswerSvc
surveyAnswerSvc = New SurveyAnswerService.SurveyAnswerSvc
' Create answers
Dim answers() As SurveyAnswerService.SurveyAnswerField
answers(0) = New SurveyAnswerService.SurveyAnswerField
answers(0).FieldName = "00001"
answers(0).Value = "Answer to be stored against this field"
' Create survey answers
Dim surveyAnswers() As SurveyAnswerService.SurveyAnswer
surveyAnswers(0) = New SurveyAnswerService.SurveyAnswer
' Assign values
' Please note not all values have been populated. Please populate these yourself.
surveyAnswers(0).RSN = Guid.NewGuid.ToString
surveyAnswers(0).DisplayValue = "Survey Display Value"
surveyAnswers(0).Date = Today.Date()
surveyAnswers(0).Answers = answers
Dim insertResults As SurveyAnswerService.InsertRangeResult
insertResults = surveyAnswerSvc.InsertRange(token, surveyAnswers)
Web Service Method – SelectByCampaignListRSN
This method allows a selection of Survey Answer records based on the Campaign List RSN and the Online Form RSN.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
OnlineForm_RSN: The unique identifier (a GUID) of the online form associated with the survey.
CampaignList_RSN: The unique identifier (a GUID) of the campaign List, which is a list which relates entities (such as a person) to things like label codes and campaigns.
FieldNames: These are the names of the fields
Returns
Result contains the following properties:
Public Class SelectSurveyAnswerResult
Property ErrorCode As Integer
Property RSN as String
Property DisplayValue as String
Property Survey_RSN as String
Property Parent_RSN as String
Property SurveyInstance_RSN as String
Property OnlineForm_RSN as String
Property DateTime as DateTime
Property KeyCode as String
Property LabelCode as String
Property Page_Index as Integer
Property Survey_Index as Integer
Property SurveyInstance_DedupeKey as String
Property CreatedOn as DateTime
Property ModifiedOn as DateTime
Property ModifiedBy as String
Property Answers
End Class
Sample Code
' Create new survey answer service object
Dim surveyAnswerSvc As SurveyAnswerService.SurveyAnswerSvc
surveyAnswerSvc = New SurveyAnswerService.SurveyAnswerSvc
' Search via dedupe key
Dim insertResults As SurveyAnswerService.SelectSurveyAnswersResult
insertResults = surveyAnswerSvc.SelectByCampaignListRSN(token, onlineFormRSN, campaignListRSN, fieldNames)
Web Service Method – SelectByDedupeKey
This method allows a selection of Survey Answer records based on the DedupeKey
Parameters
Token: Token returned by Logging in to the Passport Web Service.
OnlineForm_RSN: The unique identifier (a GUID) of the online form associated with the survey.
DedupeKey: This is a string of the Dedupe Key (the name of the field you’d like to dedupe against)
FieldNames: These are the names of the fields
Returns
Result contains the following properties:
Public Class SelectSurveyAnswerResult
Property ErrorCode As Integer
Property RSN as String
Property DisplayValue as String
Property Survey_RSN as String
Property Parent_RSN as String
Property SurveyInstance_RSN as String
Property OnlineForm_RSN as String
Property DateTime as DateTime
Property KeyCode as String
Property LabelCode as String
Property Page_Index as Integer
Property Survey_Index as Integer
Property SurveyInstance_DedupeKey as String
Property CreatedOn as DateTime
Property ModifiedOn as DateTime
Property ModifiedBy as String
Property Answers
End Class
Sample Code
' Create new survey answer service object
Dim surveyAnswerSvc As SurveyAnswerService.SurveyAnswerSvc
surveyAnswerSvc = New SurveyAnswerService.SurveyAnswerSvc
' Search via dedupe key
Dim insertResults As SurveyAnswerService.SelectSurveyAnswersResult
insertResults = surveyAnswerSvc.SelectByDedupeKey(token, onlineFormRSN, dedupeKey, fieldNames)
Web Service Method – SelectByLabelCode
This method allows a selection of Survey Answer records based on the DedupeKey
Parameters
Token: Token returned by Logging in to the Passport Web Service.
OnlineForm_RSN: The unique identifier (a GUID) of the online form associated with the survey.
LabelCode: This is the label code (a unique string used to link an entity to a form or email)
FieldNames: These are the names of the fields
Returns
Result contains the following properties:
Public Class SelectSurveyAnswerResult
Property ErrorCode As Integer
Property RSN as String
Property DisplayValue as String
Property Survey_RSN as String
Property Parent_RSN as String
Property SurveyInstance_RSN as String
Property OnlineForm_RSN as String
Property DateTime as DateTime
Property KeyCode as String
Property LabelCode as String
Property Page_Index as Integer
Property Survey_Index as Integer
Property SurveyInstance_DedupeKey as String
Property CreatedOn as DateTime
Property ModifiedOn as DateTime
Property ModifiedBy as String
Property Answers
End Class
Sample Code
' Create new survey answer service object
Dim surveyAnswerSvc As SurveyAnswerService.SurveyAnswerSvc
surveyAnswerSvc = New SurveyAnswerService.SurveyAnswerSvc
' Search via labelcode
Dim insertResults As SurveyAnswerService.SelectSurveyAnswersResult
insertResults = surveyAnswerSvc.SelectByLabelCode(token, onlineFormRSN, LabelCode, fieldNames)
Web Service Method – SelectSurveyInstance
This method allows a selection of Survey Answer records based on the DedupeKey
Parameters
Token: Token returned by Logging in to the Passport Web Service.
OnlineForm_RSN: The unique identifier (a GUID) of the online form associated with the survey.
SurveyInstance_RSN: The unique identifier (a GUID) of an instance of the Survey Answers
FieldNames: These are the names of the fields
Returns
Result contains the following properties:
Public Class SelectSurveyAnswerResult
Property ErrorCode As Integer
Property RSN as String
Property DisplayValue as String
Property Survey_RSN as String
Property Parent_RSN as String
Property SurveyInstance_RSN as String
Property OnlineForm_RSN as String
Property DateTime as DateTime
Property KeyCode as String
Property LabelCode as String
Property Page_Index as Integer
Property Survey_Index as Integer
Property SurveyInstance_DedupeKey as String
Property CreatedOn as DateTime
Property ModifiedOn as DateTime
Property ModifiedBy as String
Property Answers
End Class
Sample Code
' Create new survey answer service object
Dim surveyAnswerSvc As SurveyAnswerService.SurveyAnswerSvc
surveyAnswerSvc = New SurveyAnswerService.SurveyAnswerSvc
' Search via survey instance
Dim insertResults As SurveyAnswerService.SelectSurveyAnswersResult
insertResults = surveyAnswerSvc.SelectByLabelCode(token, onlineFormRSN, surveyInstanceRSN, fieldNames)
Web Service Method – SelectByRSN
This method allows a selection of Survey Answer records based on the DedupeKey
Parameters
Token: Token returned by Logging in to the Passport Web Service.
RSN: The unique identifier (a GUID) of the survey answer record.
FieldNames: These are the names of the fields
Returns
Result contains the following properties:
Public Class SelectByRSNResult
Property ErrorCode As Integer
Property RSN as String
Property DisplayValue as String
Property Survey_RSN as String
Property Parent_RSN as String
Property SurveyInstance_RSN as String
Property OnlineForm_RSN as String
Property DateTime as DateTime
Property KeyCode as String
Property LabelCode as String
Property Page_Index as Integer
Property Survey_Index as Integer
Property SurveyInstance_DedupeKey as String
Property CreatedOn as DateTime
Property ModifiedOn as DateTime
Property ModifiedBy as String
Property Answers
End Class
Public Class Answers
Property SurveyAnswerField As SurveyAnswerField
End Class
Sample Code (in VB.Net)
' Create new survey answer service object
Dim surveyAnswerSvc As SurveyAnswerService.SurveyAnswerSvc
surveyAnswerSvc = New SurveyAnswerService.SurveyAnswerSvc
' Search for Survey Answer Record
Dim insertResults As SurveyAnswerService.SelectSurveyAnswerResult
insertResults = surveyAnswerSvc.SelectByRSN(token, RSN, fieldNames)
Web Service Method – SelectDedupeKeyCount
This method returned the number of Survey Answer records of a particular survey are duplicates (as definted by the dedupe key.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
Survey_RSN: The unique identifier (a GUID) of the the survey.
DedupeKey: This is a string of the Dedupe Key (the name of the field you’d like to dedupe against)
Returns
Result contains the following properties:
Public Class SelectDedupeKeyCountResult
Property ErrorCode As Integer
Property DedupeKeyCount as Integer
End Class
Sample Code
' Create new survey answer service object
Dim surveyAnswerSvc As SurveyAnswerService.SurveyAnswerSvc
surveyAnswerSvc = New SurveyAnswerService.SurveyAnswerSvc
' Search via dedupe key
Dim insertResults As SurveyAnswerService.SelectDedupeKeyCountResult
insertResults = surveyAnswerSvc.SelectDedupeKeyCount(token, surveyRSN, DedupeKey)
Person Web Service Method Definitions
The following methods provide the means to create, select, update and delete person entity records and links from the person entity to related entities in Simplicity. 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/Entities/PersonSvc.asmx
- Creating a Person Object
- Creating a Relationship Object
- SelectByRSN
- SelectByName
- SelectByNameAndEmailAddress
- Insert
- Update
- Delete
- LookupEntityRSN
- Login
- Authenticate
- SelectRelatedEntities
- InsertRelatedEntity
- DeleteRelatedEntity
- Person Web Service Result/Error Codes
Creating a Person Object
To create a Person Service object in VB.Net use the following code:
(Assumes the web reference is named ‘PersonService’)
Dim personsvc As PersonService.PersonSvc
Personsvc = New PersonService.PersonSvc
Creating a Relationship Object
A relationship object is used to insert/delete related entity objects.
(Assumes the web reference is named ‘PersonService’)
Dim currentRelationship As PersonService.Relationship
currentRelationship = New PersonService.Relationship
Web Service Method – SelectByRSN
This method sends a Person RSN to the PersonService and returns a person object.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
RSN: The RSN of the Person to be retrieved.
Returns
The service returns an ErrorCode, a ‘PartialResultSet’ Boolean (which describes whether a complete Result Set has been returned, or only a partial set), and the Result Set in the form of a person object:
Public Class Person
Property Accounting_PaymentDueDays As Integer
Property ActivePolicies As Boolean
Property AirNZAirpointsNumber As Long
Property CDNumber As String
Property ClientID As String
Property CreatedBy As String
Property CreatedOn As Date
Property DateOfBirth As Date
Property Decoration As String
Property DisplayValue As String
Property DriverLicenceExpiryDate As Date
Property EriverLicenceNumber As String
Property Email As String
Property Email_Home As String
Property Email_Home_ModifiedOn As Date
Property Email_ModifiedOn As Date
Property FamilyName As String
Property Fax_Local As String
Property Fax_ModifiedOn As Date
Property GivenName As String
Property Invalid_Email As Boolean
Property Invalid_Email_Home As Boolean
Property Invalid_Fax As Boolean
Property Invalid_Mobile As Boolean
Property Invalid_PhoneBusiness As Boolean
Property Invalid_PhoneHome As Boolean
Property Invalid_PostalAddress As Boolean
Property Invalid_StreetAddress As Boolean
Property LetterCarrier As String
Property MiddleName As String
Property Mobile_Local As String
Property Mobile_ModifiedOn As Date
Property Mobile_PrefCallingTime As String
Property ModifiedBy As String
Property ModifiedOn As Date
Property Nickname As String
Property Phone_Business_Extension As String
Property Phone_Business_Local As String
Property Phone_Business_PrefCallingTime As String
Property Phone_Home_Local As String
Property Phone_Home_PrefCallingTime As String
Property PhoneBusiness_ModifiedOn As Date
Property PhoneHome_ModifiedOn As Date
Property PostalAddress_CorrectionCode As String
Property PostalAddress_Country As String
Property PostalAddress_DoNotClean As Boolean
Property PostalAddress_DPID As String
Property PostalAddress_ErrorCode As Integer
Property PostalAddress_Latitude As Double
Property PostalAddress_Line1 As String
Property PostalAddress_Line2 As String
Property PostalAddress_Line3 As String
Property PostalAddress_Line4 As String
Property PostalAddress_Line5 As String
Property PostalAddress_Line6 As String
Property PostalAddress_Line7 As String
Property PostalAddress_Longitude As Double
Property PostalAddress_MapGrid_X As Integer
Property PostalAddress_MapGrid_Y As Integer
Property PostalAddress_MeshBlock As Integer
Property PostalAddress_ModifiedOn As Date
Property PostalAddress_PostCode As String
Property PostalAddress_StatementOfAccuracyCode As String
Property PostalAddress_StatementOfAccuracyLastUpdated As Date
Property PostalAddress_StatementOfAccuracyReason As String
Property PostalAddress_StatementOfAccuracyUpdatedTrigger As Boolean
Property PostalAddress_Suburb As String
Property PostalAddress_TownCityState As String
Property QantasFFNumber As Long
Property RelationshipAOwnerBorrower As Boolean
Property RelationshipBInsured As Boolean
Property RelationshipCPayerBeneficiary As Boolean
Property RSK_Counter As Double
Property RSN As String
Property Salutation As String
Property SingleViewID As String
Property StreetAddress_CorrectionCode As String
Property StreetAddress_Country As String
Property StreetAddress_DoNotClean As Boolean
Property StreetAddress_DPID As String
Property StreetAddress_ErrorCode As Integer
Property StreetAddress_Latitude As Double
Property StreetAddress_Line1 As String
Property StreetAddress_Line2 As String
Property StreetAddress_Line3 As String
Property StreetAddress_Line4 As String
Property StreetAddress_Line5 As String
Property StreetAddress_Line6 As String
Property StreetAddress_Line7 As String
Property StreetAddress_Longitude As Double
Property StreetAddress_MapGrid_X As Integer
Property StreetAddress_MapGrid_Y As Integer
Property StreetAddress_MeshBlock As Integer
Property StreetAddress_ModifiedOn As Date
Property StreetAddress_PostCode As String
Property StreetAddress_StatementOfAccuracyCode As String
Property StreetAddress_StatementOfAccuracyLastUpdated As Date
Property StreetAddress_StatementOfAccuracyReason As String
Property StreetAddress_StatementOfAccuracyUpdatedTrigger As Boolean
Property StreetAddress_Suburb As String
Property StreetAddress_TownCityState As String
Property Tenure_DateCommenced As Date
Property Tenure_NextReviewDate As Date
Property Title As String
Property TotalAnnualisedPremium As Decimal
Property TotalAnnualisedRepayments As Decimal
Property TotalRFMScore As Long
Property VehicleType As String
Property Website As String
Property Channel As Person_Channel
Property DistributionGroup As Person_Distribution_Group
Property PersonType As Person_Client_Type
Property PolicyBenefitCategory As Policy_Benefit_Category
Property Roles As User_Roles
Property SpeakerSpecialistArea As SpeakerSpecialArea
Property Suppression_Codes As Suppression_Codes
Property Accounting_PaymentTerms As Accounting_PaymentTerms
Property AgeGroup As Person_Age_Group
Property Currency As Currency
Property EmailOptIn As Opt_In
Property Gender As Gender
Property IncomeGroup As Person_Income_Group
Property LongestTenureMonthsGroup As Person_Longest_Tenure_Months_Group
Property MailOptIn As Opt_In
Property MaritalStatus As Marital_Status
Property OccupationGroup As Person_Occupation_Group
Property Origin As Entity_Origin
Property RFMGroup As Person_RFM_Group
Property ShortestTenureMonthsGroup As Person_Shortest_Tenure_Months_Group
Property SMSOptIn As Opt_In
Property taxRate As Tax_Rate
End Class
Sample Code (in VB.Net)
' Create Person Objects
Dim personSvc As PersonService.PersonSvc = New PersonService.PersonSvc
Dim person As PersonService.Person
Dim personResult As PersonService.SelectPersonResult
' Search for person, and store result in a person object
personResult = personSvc.SelectByRSN(token, RSN) person = personResult.ResultSet
Web Service Method – SelectByName
This method sends a Person Given Name and Family Name to the PersonService and returns Person objects that meet the criteria.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
NoResults: The number of records in the result set.
GivenName: The Given Name of the person to be selected. GivenName supports wildcard and partial matching.
FamilyName: The Family Name of the person to be selected. FamilyName supports wildcard and partial matching.
Returns
The service returns an ErrorCode, a ‘PartialResultSet’ Boolean (which describes whether a complete Result Set has been returned, or only a partial set), and the Result Set in the form of a person object:
Public Class Person
Property Accounting_PaymentDueDays As Integer
Property ActivePolicies As Boolean
Property AirNZAirpointsNumber As Long
Property CDNumber As String
Property ClientID As String
Property CreatedBy As String
Property CreatedOn As Date
Property DateOfBirth As Date
Property Decoration As String
Property DisplayValue As String
Property DriverLicenceExpiryDate As Date
Property EriverLicenceNumber As String
Property Email As String
Property Email_Home As String
Property Email_Home_ModifiedOn As Date
Property Email_ModifiedOn As Date
Property FamilyName As String
Property Fax_Local As String
Property Fax_ModifiedOn As Date
Property GivenName As String
Property Invalid_Email As Boolean
Property Invalid_Email_Home As Boolean
Property Invalid_Fax As Boolean
Property Invalid_Mobile As Boolean
Property Invalid_PhoneBusiness As Boolean
Property Invalid_PhoneHome As Boolean
Property Invalid_PostalAddress As Boolean
Property Invalid_StreetAddress As Boolean
Property LetterCarrier As String
Property MiddleName As String
Property Mobile_Local As String
Property Mobile_ModifiedOn As Date
Property Mobile_PrefCallingTime As String
Property ModifiedBy As String
Property ModifiedOn As Date
Property Nickname As String
Property Phone_Business_Extension As String
Property Phone_Business_Local As String
Property Phone_Business_PrefCallingTime As String
Property Phone_Home_Local As String
Property Phone_Home_PrefCallingTime As String
Property PhoneBusiness_ModifiedOn As Date
Property PhoneHome_ModifiedOn As Date
Property PostalAddress_CorrectionCode As String
Property PostalAddress_Country As String
Property PostalAddress_DoNotClean As Boolean
Property PostalAddress_DPID As String
Property PostalAddress_ErrorCode As Integer
Property PostalAddress_Latitude As Double
Property PostalAddress_Line1 As String
Property PostalAddress_Line2 As String
Property PostalAddress_Line3 As String
Property PostalAddress_Line4 As String
Property PostalAddress_Line5 As String
Property PostalAddress_Line6 As String
Property PostalAddress_Line7 As String
Property PostalAddress_Longitude As Double
Property PostalAddress_MapGrid_X As Integer
Property PostalAddress_MapGrid_Y As Integer
Property PostalAddress_MeshBlock As Integer
Property PostalAddress_ModifiedOn As Date
Property PostalAddress_PostCode As String
Property PostalAddress_StatementOfAccuracyCode As String
Property PostalAddress_StatementOfAccuracyLastUpdated As Date
Property PostalAddress_StatementOfAccuracyReason As String
Property PostalAddress_StatementOfAccuracyUpdatedTrigger As Boolean
Property PostalAddress_Suburb As String
Property PostalAddress_TownCityState As String
Property QantasFFNumber As Long
Property RelationshipAOwnerBorrower As Boolean
Property RelationshipBInsured As Boolean
Property RelationshipCPayerBeneficiary As Boolean
Property RSK_Counter As Double
Property RSN As String
Property Salutation As String
Property SingleViewID As String
Property StreetAddress_CorrectionCode As String
Property StreetAddress_Country As String
Property StreetAddress_DoNotClean As Boolean
Property StreetAddress_DPID As String
Property StreetAddress_ErrorCode As Integer
Property StreetAddress_Latitude As Double
Property StreetAddress_Line1 As String
Property StreetAddress_Line2 As String
Property StreetAddress_Line3 As String
Property StreetAddress_Line4 As String
Property StreetAddress_Line5 As String
Property StreetAddress_Line6 As String
Property StreetAddress_Line7 As String
Property StreetAddress_Longitude As Double
Property StreetAddress_MapGrid_X As Integer
Property StreetAddress_MapGrid_Y As Integer
Property StreetAddress_MeshBlock As Integer
Property StreetAddress_ModifiedOn As Date
Property StreetAddress_PostCode As String
Property StreetAddress_StatementOfAccuracyCode As String
Property StreetAddress_StatementOfAccuracyLastUpdated As Date
Property StreetAddress_StatementOfAccuracyReason As String
Property StreetAddress_StatementOfAccuracyUpdatedTrigger As Boolean
Property StreetAddress_Suburb As String
Property StreetAddress_TownCityState As String
Property Tenure_DateCommenced As Date
Property Tenure_NextReviewDate As Date
Property Title As String
Property TotalAnnualisedPremium As Decimal
Property TotalAnnualisedRepayments As Decimal
Property TotalRFMScore As Long
Property VehicleType As String
Property Website As String
Property Channel As Person_Channel
Property DistributionGroup As Person_Distribution_Group
Property PersonType As Person_Client_Type
Property PolicyBenefitCategory As Policy_Benefit_Category
Property Roles As User_Roles
Property SpeakerSpecialistArea As SpeakerSpecialArea
Property Suppression_Codes As Suppression_Codes
Property Accounting_PaymentTerms As Accounting_PaymentTerms
Property AgeGroup As Person_Age_Group
Property Currency As Currency
Property EmailOptIn As Opt_In
Property Gender As Gender
Property IncomeGroup As Person_Income_Group
Property LongestTenureMonthsGroup As Person_Longest_Tenure_Months_Group
Property MailOptIn As Opt_In
Property MaritalStatus As Marital_Status
Property OccupationGroup As Person_Occupation_Group
Property Origin As Entity_Origin
Property RFMGroup As Person_RFM_Group
Property ShortestTenureMonthsGroup As Person_Shortest_Tenure_Months_Group
Property SMSOptIn As Opt_In
Property taxRate As Tax_Rate
End Class
NOTE: This method can be customized and renamed for each entity to select on any combination of values.
Sample Code (in VB.Net)
' Create Person Objects
Dim personSvc As PersonService.PersonSvc = New PersonService.PersonSvc
Dim people As PersonService.Person()
Dim peopleResult As personService.SelectPersonResult
' Search for people, and store result in a resultset
peopleResult = personSvc.SelectByName(token, noResults, firstName, surname)
people = peopleResult.ResultSet
Web Service Method – SelectByNameAndEmailAddress
This method sends a Person Given Name, Family Name and Email Address to the PersonService and returns person objects that meet the criteria.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
GivenName: The Given Name of the person to be selected. GivenName supports wildcard and partial matching.
FamilyName: The Family Name of the person to be selected. FamilyName supports wildcard and partial matching.
Email: The email address of the person to be selected. Email supports wildcard and partial matching.
Returns
The service returns an ErrorCode, a ‘PartialResultSet’ Boolean (which describes whether a complete Result Set has been returned, or only a partial set), and the Result Set in the form of a person object:
Public Class Person
Property Accounting_PaymentDueDays As Integer
Property ActivePolicies As Boolean
Property AirNZAirpointsNumber As Long
Property CDNumber As String
Property ClientID As String
Property CreatedBy As String
Property CreatedOn As Date
Property DateOfBirth As Date
Property Decoration As String
Property DisplayValue As String
Property DriverLicenceExpiryDate As Date
Property EriverLicenceNumber As String
Property Email As String
Property Email_Home As String
Property Email_Home_ModifiedOn As Date
Property Email_ModifiedOn As Date
Property FamilyName As String
Property Fax_Local As String
Property Fax_ModifiedOn As Date
Property GivenName As String
Property Invalid_Email As Boolean
Property Invalid_Email_Home As Boolean
Property Invalid_Fax As Boolean
Property Invalid_Mobile As Boolean
Property Invalid_PhoneBusiness As Boolean
Property Invalid_PhoneHome As Boolean
Property Invalid_PostalAddress As Boolean
Property Invalid_StreetAddress As Boolean
Property LetterCarrier As String
Property MiddleName As String
Property Mobile_Local As String
Property Mobile_ModifiedOn As Date
Property Mobile_PrefCallingTime As String
Property ModifiedBy As String
Property ModifiedOn As Date
Property Nickname As String
Property Phone_Business_Extension As String
Property Phone_Business_Local As String
Property Phone_Business_PrefCallingTime As String
Property Phone_Home_Local As String
Property Phone_Home_PrefCallingTime As String
Property PhoneBusiness_ModifiedOn As Date
Property PhoneHome_ModifiedOn As Date
Property PostalAddress_CorrectionCode As String
Property PostalAddress_Country As String
Property PostalAddress_DoNotClean As Boolean
Property PostalAddress_DPID As String
Property PostalAddress_ErrorCode As Integer
Property PostalAddress_Latitude As Double
Property PostalAddress_Line1 As String
Property PostalAddress_Line2 As String
Property PostalAddress_Line3 As String
Property PostalAddress_Line4 As String
Property PostalAddress_Line5 As String
Property PostalAddress_Line6 As String
Property PostalAddress_Line7 As String
Property PostalAddress_Longitude As Double
Property PostalAddress_MapGrid_X As Integer
Property PostalAddress_MapGrid_Y As Integer
Property PostalAddress_MeshBlock As Integer
Property PostalAddress_ModifiedOn As Date
Property PostalAddress_PostCode As String
Property PostalAddress_StatementOfAccuracyCode As String
Property PostalAddress_StatementOfAccuracyLastUpdated As Date
Property PostalAddress_StatementOfAccuracyReason As String
Property PostalAddress_StatementOfAccuracyUpdatedTrigger As Boolean
Property PostalAddress_Suburb As String
Property PostalAddress_TownCityState As String
Property QantasFFNumber As Long
Property RelationshipAOwnerBorrower As Boolean
Property RelationshipBInsured As Boolean
Property RelationshipCPayerBeneficiary As Boolean
Property RSK_Counter As Double
Property RSN As String
Property Salutation As String
Property SingleViewID As String
Property StreetAddress_CorrectionCode As String
Property StreetAddress_Country As String
Property StreetAddress_DoNotClean As Boolean
Property StreetAddress_DPID As String
Property StreetAddress_ErrorCode As Integer
Property StreetAddress_Latitude As Double
Property StreetAddress_Line1 As String
Property StreetAddress_Line2 As String
Property StreetAddress_Line3 As String
Property StreetAddress_Line4 As String
Property StreetAddress_Line5 As String
Property StreetAddress_Line6 As String
Property StreetAddress_Line7 As String
Property StreetAddress_Longitude As Double
Property StreetAddress_MapGrid_X As Integer
Property StreetAddress_MapGrid_Y As Integer
Property StreetAddress_MeshBlock As Integer
Property StreetAddress_ModifiedOn As Date
Property StreetAddress_PostCode As String
Property StreetAddress_StatementOfAccuracyCode As String
Property StreetAddress_StatementOfAccuracyLastUpdated As Date
Property StreetAddress_StatementOfAccuracyReason As String
Property StreetAddress_StatementOfAccuracyUpdatedTrigger As Boolean
Property StreetAddress_Suburb As String
Property StreetAddress_TownCityState As String
Property Tenure_DateCommenced As Date
Property Tenure_NextReviewDate As Date
Property Title As String
Property TotalAnnualisedPremium As Decimal
Property TotalAnnualisedRepayments As Decimal
Property TotalRFMScore As Long
Property VehicleType As String
Property Website As String
Property Channel As Person_Channel
Property DistributionGroup As Person_Distribution_Group
Property PersonType As Person_Client_Type
Property PolicyBenefitCategory As Policy_Benefit_Category
Property Roles As User_Roles
Property SpeakerSpecialistArea As SpeakerSpecialArea
Property Suppression_Codes As Suppression_Codes
Property Accounting_PaymentTerms As Accounting_PaymentTerms
Property AgeGroup As Person_Age_Group
Property Currency As Currency
Property EmailOptIn As Opt_In
Property Gender As Gender
Property IncomeGroup As Person_Income_Group
Property LongestTenureMonthsGroup As Person_Longest_Tenure_Months_Group
Property MailOptIn As Opt_In
Property MaritalStatus As Marital_Status
Property OccupationGroup As Person_Occupation_Group
Property Origin As Entity_Origin
Property RFMGroup As Person_RFM_Group
Property ShortestTenureMonthsGroup As Person_Shortest_Tenure_Months_Group
Property SMSOptIn As Opt_In
Property taxRate As Tax_Rate
End Class
NOTE: This method can be customized and renamed for each entity to select on any combination of values.
Sample Code (in VB.Net)
' Create Person Objects
Dim personSvc As PersonService.PersonSvc = New PersonService.PersonSvc
Dim people As PersonService.Person()
Dim peopleResult As personService.SelectPersonResult
' Search for people, and store result in a resultset
peopleResult = personSvc.SelectByNameAndEmailaddress(token, firstName, surname, emailAddress)
people = peopleResult.ResultSet
Web Service Method - Insert
This method takes a new Person Object and inserts it into the database.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
Value: The Person to be inserted into the database.
Returns
An integer indicating the result of the insert.
Sample Code (in VB.Net)
' Create Person Objects
Dim individualResult As Integer
Dim personSvc As PersonService.PersonSvc = New PersonService.PersonSvc
Dim individual As PersonService.Person = New PersonService.Person
' Assign information to the person object
' (The data assigned is fictional, and for example use only)
individual.RSN = Guid.NewGuid.ToString
individual.Title = "Mr"
individual.GivenName = "Donald"
individual.FamilyName = "Duck"
individual.DisplayValue = "Donald Duck"
' Call the Insert method, and store the resulting code in an integer
individualResult = personSvc.Insert(token, individual)
Web Service Method – Update
This method takes a Person Object that already exists in the database, and updates the values.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
Value: The a person object of the Person to be updated
Returns
An integer indicating the result of the update.
Sample Code (in VB.Net)
' Create Person Objects
Dim individualResult As Integer
Dim personsvc As PersonService.PersonSvc = New PersonService.PersonSvc
Dim individual As PersonService.Person = New PersonService.Person
' Assign information to the person object
' (The data assigned is fictional, and for example use only)
individual.Title = "Mr"
individual.GivenName = "Donald"
individual.FamilyName = "Duck"
individual.DisplayValue = "Donald Duck"
' Call the Update method, and store the resulting code in an integer
individualResult = personsvc.Update(token, individual)
Web Service Method – Delete
This method takes a Person Object that already exists in the database, and deletes the values.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
RSN: The RSN of the Person to be deleted
Returns
An integer indicating the result of the delete.
Sample Code (in VB.Net)
' Create Person Objects
Dim individualResult As Integer
Dim personSvc As PersonService.PersonSvc = New PersonService.PersonSvc
Dim individual As PersonService.Person
' At this point you would assign the person to be deleted to the person object
' ‘individual’.
' Call the Update method, and store the resulting code in an integer individualResult = personsvc.Update(token, individual)
Web Service Method – LookupEntityRSN
This method looks up the current Person Object RSN given any historical RSN
Parameters
Token: Token returned by Logging in to the Passport Web Service.
Prospect_RSN: The historical RSN of the Person
Returns
An object indicating the result of the look up, and the current RSN
Sample Code (in VB.Net)
' Create Person Objects
Dim lookupResult As PersonService.LookupEntityRSNResult
Dim personSvc As PersonService.PersonSvc = New PersonService.PersonSvc
' Call the Update method, and store the resulting code in an integer lookupResult = personsvc.LookupEntityRSN(token, rsn)
Web Service Method – Login
This method takes several input variables and returns a Person (LoginResult) object, and well as the full profile of the account owner.
Parameters
Key: Client ID (type GUID)
AuthorisationPassword: The password used to authorise the use of this method.
CampaignName: The campaign which all activities associated with the login will be associated with. If blank or invalid no campaign tracking is initiated.
CampaignSegment: The campaign segment which all activities associated with the login will be associated with. If blank or invalid no campaign tracking is initiated.
AccountName: The username used to validate credentials.
Password: The password used to validate credentials. Optional WHEN Authorised Username and Password is provided. This allows the client database to maintain master username and passwords and Simplicity to be a slave without storing any passwords.
TokenValidDuration: The duration the token is valid.
LoginModel: The type of model to use (MultipleLogins, SingleLogin, RoamingLogin)
Returns
A passport object of class ‘Login Result’ with a token, error code, account name, and email address. It also returns the account RSN, the account Owner RSN, type and display value, the account permissions, and the full profile of the account owner.
Additional Notes:
This method does not come with our standard Web Services Installs. You will need to request this method if you’d like to use it. Also, to use this method you will need to have purchased the Passport Services.
MultipleLogins: Allows multiple concurrent tokens.
SingleLogin: If the user has an active token an error (1016) is returned.
RoamingLogin: If the user has an active session then the token is expired and a new token is issued.
Permissions
AccountName must be an Active account. AccountName must have a password specified.
Sample Code (in VB.Net)
' Create Person Service
Dim personsvc As PersonService.PersonSvc = New PersonService.PersonSvc
Dim loginResults As PersonService.LoginResult
' Attempt to login
loginResults = personsvc.Login(Key, AuthorisationPassword, CampaignName, CampaignSegment, AccountName, Password, TokenValidDuration, LoginModel)
Web Service Method – Authenticate
This method takes an existing token and it is expired. A new token is created and the now expired token is linked to the new token’s CampaignList as a referring label code.
The CampaignList that activities are logged against will be changed if the new token’s Campaign/CampaignSegment is different to that of the previous token.
Parameters
Key: Client ID (type GUID)
Authorisation Password: The password used to authorise the use of this method.
Token: Token supplied by logging into the Passport Web Service
CampaignName: The campaign which all activities associated with the login will be associated with. If black or invalid no campaign tracking is initiated.
CampaignSegment: The campaign segment which all activities associated with the login will be associated with. If blank or invalid no campaign tracking is initiated.
Returns
A passport object of class ‘Authentication Result’ with a token, error code, account name, and email address. It also returns the account RSN, the account Owner RSN, type and display value, the account permissions, and the full profile of the account owner.
Sample Code (in VB.Net)
' Create Person Service
Dim personsvc As PersonService.PersonSvc = New PersonService.PersonSvc
Dim authenticateResult As PersonService.AuthenticateResult
' Authenticate
AuthenticateResult = personsvc.Authenticate(key, AuthorisationPassword, token, campaignName, campaignSegment)
Web Service Method – SelectRelatedEntities
This method takes the RSN of the person and returns the requested relationships.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
RSN: The RSN of the Person to select relationships for.
Relationship: The Relationship to select.
Returns
Result is an array containing the following properties:
Public Class Relationship
Property Relationship_Type As Relationship_Type
Property Join_RSN As String
Property Entity_RSN As String
Property Entity_DisplayValue As String
Property Entity_Type As String
End Class
Sample Code (in VB.Net) – select by related entities
This sample selects the ‘current employer’ records from the person-organisation relationship.
' Create Person Object
Dim personSvc As PersonService.PersonSvc = New PersonService.PersonSvc
Dim individual As PersonService.Person
' At this point you would assign the person object ‘individual’ values, such as
' ‘individual.RSN’.
' Create Relationship Object
Dim employerRelationship As PersonService.Relationship
' At this point you would assign the relationship object ‘employerRelationship’
' values, such as ‘employerRelationship.Entity_RSN’ and
' ‘employerRelationship.Join_RSN’.
' Search for people, and store result in a resultset
Dim relationshipResult As personService.SelectRelationshipResult
relationshipResult = personSvc.SelectRelatedEntity(token, individual.RSN, employerRelationship)
Web Service Method - InsertRelatedEntity
This method inserts a relationship between an entity related to the person entity.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
RSN: The RSN of the Person to insert this relationship for.
DisplayValue: The Display Value of the Person to insert this relationship for.
EntityToInsert: The Relationship to insert.
Public Class Relationship
Property Relationship_Type As Relationship_Type
Property Join_RSN As String
Property Entity_RSN As String
Property Entity_DisplayValue As String
Property Entity_Type As String
End Class
The relationship type will be defined as per the database set up (ie a staff-employer relationship between the person and organisation could be used).
The Join_RSN is a new GUID unique to this relationship.
The Entity RSN is the RSN of the Entity to which the person is forming a relationship. If we were inserting a staff-employer relationship, the RSN we would use would be the RSN of the organisation in this relationship.
The Entity Display Value is a display value that should be used to indentify which entity record this person has a relationship with (ie, if this is a staff-employer relationship and the person is a current staff member of the organisation ‘Simplicity’, then perhaps the appropriate display value to identify this relationship to the person would be ‘Simplicity’)
The entity type is the name of the entity to which this person is forming a relationship. If we were inserting a staff-employer relationship with an organisation, then ‘Organisation’ would be the appropriate value to use.
Returns
An Integer indicating the result of the insert
Notes
Please do not use null for the display values. While the display values are not mandatory, they are used in the desktop version of Simplicity and are what your users will see.
Sample Code (in VB.Net)
This sample inserts the ‘current employer’ relationship between the person and organisation entities.
Dim relationshipResult As Integer
' Create Person Object
Dim personSvc As PersonService.PersonSvc = New PersonService.PersonSvc
Dim individual As PersonService.Person
' At this point you would assign the person object ‘individual’ values, such as
' ‘individual.RSN’.
' Create Relationship Object
Dim currentRelationship As PersonService.Relationship
' At this point you would assign the relationship object ‘currentRelationship’
' values, such as ‘currentRelationship.Entity_RSN’ and
' ‘currentRelationship.Join_RSN’.
' Insert relationship
relationshipResult = personSvc.InsertRelatedEntity(token, individual.RSN, individual.DisplayValue, currentRelationship)
Web Service Method – DeleteRelatedEntity
This method deletes a relationship between an entity related to the person entity.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
RSN: The RSN of the Person for whom this relationship will be deleted.
DisplayValue: The Display Value of the Person for whom this relationship will be deleted.
EntityToDelete: The Relationship to delete.
Public Class Relationship
Property Relationship_Type As Relationship_Type
Property Join_RSN As String
Property Entity_RSN As String
Property Entity_DisplayValue As String
Property Entity_Type As String
End Class
Returns
An Integer indicating the result of the delete
Notes
Please do not use null for the display values. While the display values are not mandatory, they are used in the desktop version of Simplicity and are what your users will see.
Sample Code (in VB.Net)
This sample deletes the ‘current employer’ relationship between the person and organisation entities.
Dim relationshipResult As Integer
' Create Person Object
Dim personSvc As PersonService.PersonSvc = New PersonService.PersonSvc
' At this point you would assign the person object ‘individual’ values, such as
' ‘individual.RSN’ and ‘individual.DisplayValue’.
' Create Relationship Object
Dim currentRelationship As PersonService.Relationship
' At this point you would assign the relationship object ‘currentRelationship’
' values, such as ‘currentRelationship.Entity_RSN’ and
' ‘currentRelationship.Join_RSN’.
' Delete relationship
relationshipResult = personSvc.DeleteRelatedEntity(token, individual.RSN, individual.DisplayValue, currentRelationship)
Person 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
3001 Invalid Token
3007 Insufficient Privileges
3100 Select: Entity Not Found
3110 Insert: Invalid RSN
3111 Insert: Entity already exists
3112 Insert Exception
3120 Update: Invalid RSN
3121 Update Exception
3130 Delete Exception
3140 Select Relationship: Not Found
3141 Insert Relationship Exception
3142 Delete Relationship Exception
SecondPerson Web Service Method Definitions
The following methods provide the means to create, select, update and delete person entity records and links from the person entity to related entities in Simplicity. 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/Entities/SecondPersonSvc.asmx
This web service allows you to point to the same entitiy (in this case the person entity) but have different options defined. This allows you to return different data, have methods that take different paramaters, select different relationships etc.
- Creating a SecondPerson Object
- Creating a Relationship Object
- SelectByRSN
- SelectByName
- SelectByNameAndEmailAddress
- Login
- Authenticate
- Insert
- Update
- Delete
- SelectRelatedEntities
- InsertRelatedEntity
- DeleteRelatedEntity
- Person Web Service Result/Error Codes
Creating a Person Object
To create a Person Service object in VB.NET use the following code:
(Assumes the web reference is named ‘SecondPersonService’)
' Create SecondPerson Object
Dim secondPersonSvc As SecondPersonService.PersonSvc
secondPersonSvc = New SecondPersonService.PersonSvc
Creating a Relationship Object
A relationship object is used to insert/delete related entity objects.
(Assumes the web reference is named ‘PersonService’)
' Create Relationship Object
Dim currentRelationship As PersonService.Relationship
currentRelationship = New PersonService.Relationship
Web Service Method – SelectByRSN
This method sends a Person RSN to the PersonService and returns a person object.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
RSN: The RSN of the Person to be retrieved.
Returns
The service returns an ErrorCode, a ‘PartialResultSet’ Boolean (which describes whether a complete Result Set has been returned, or only a partial set), and the Result Set in the form of a person object:
Public Class Person
Property Sccounting_PaymentDueDays As Integer
Property DisplayValue As String
Property Invalid_Email As Boolean
Property Invalid_Email_Home As Boolean
Property Invalid_Fax As Boolean
Property Invalid_Mobile As Boolean
Property Invalid_PhoneBusiness As Boolean
Property Invalid_PhoneHome As Boolean
Property Invalid_PostalAddress As Boolean
Property Invalid_StreetAddress As Boolean
Property RSN As String
Property StreetAddress_Line1 As String
Property StreetAddress_Line2 As String
Property StreetAddress_Line3 As String
Property StreetAddress_Line4 As String
Property StreetAddress_Line5 As String
Property StreetAddress_Line6 As String
Property StreetAddress_Line7 As String
Property Suppression_Codes As Suppression_Codes
Property Gender As Gender
End Class
Sample Code (in VB.Net)
' Create SecondPerson Object
Dim secondPersonSvc As SecondPersonService.PersonSvc
secondPersonSvc = New SecondPersonService.PersonSvc
Dim secondPersonResult As SecondPersonService.SelectPersonResult
' Search for person, and store result in a person object
secondPersonResult = secondPersonSvc.SelectByRSN(token, RSN) secondPerson = secondPersonResult.ResultSet
Web Service Method – SelectByName
This method sends a Person Given Name and Family Name to the PersonService and returns person objects that meet the criteria.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
GivenName: The Given Name of the person to be selected. GivenName supports wildcard and partial matching.
FamilyName: The Family Name of the person to be selected. FamilyName supports wildcard and partial matching.
Returns
The service returns an ErrorCode, a ‘PartialResultSet’ Boolean (which describes whether a complete Result Set has been returned, or only a partial set), and the Result Set in the form of a person object:
Public Class Person
Property Accounting_PaymentDueDays As Integer
Property DisplayValue As String
Property Invalid_Email As Boolean
Property Invalid_Email_Home As Boolean
Property Invalid_Fax As Boolean
Property Invalid_Mobile As Boolean
Property Invalid_PhoneBusiness As Boolean
Property Invalid_PhoneHome As Boolean
Property Invalid_PostalAddress As Boolean
Property Invalid_StreetAddress As Boolean
Property RSN As String
Property StreetAddress_Line1 As String
Property StreetAddress_Line2 As String
Property StreetAddress_Line3 As String
Property StreetAddress_Line4 As String
Property StreetAddress_Line5 As String
Property StreetAddress_Line6 As String
Property StreetAddress_Line7 As String
Property Suppression_Codes As Suppression_Codes
Property Gender As Gender
End Class
NOTE: This method can be customized and renamed for each entity to select on any combination of values.
Sample Code (in VB.Net)
' Create SecondPerson Object
Dim secondPersonSvc as PersonService.PersonSvc
secondPersonSvc = New PersonService.PersonSvc
Dim secondPeople As PersonService.Person()
Dim secondPersonResult As PersonService.SelectPersonResult
' Search for people, and store result in a resultset
secondPersonResult = secondPersonSvc.SelectByName(token, firstName, surname)
secondPeople = secondPersonResult.ResultSet
Web Service Method – SelectByNameAndEmailAddress
This method sends a Person Given Name, Family Name and Email Address to the PersonService and returns person objects that meet the criteria.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
GivenName: The Given Name of the person to be selected. GivenName supports wildcard and partial matching.
FamilyName: The Family Name of the person to be selected. FamilyName supports wildcard and partial matching.
Email: The Email Address of the person to be selected. Email supports wildcard and partial matching.
Returns
The service returns an ErrorCode, a ‘PartialResultSet’ Boolean (which describes whether a complete Result Set has been returned, or only a partial set), and the Result Set in the form of a person object:
Public Class Person
Property Accounting_PaymentDueDays As Integer
Property DisplayValue As String
Property Invalid_Email As Boolean
Property Invalid_Email_Home As Boolean
Property Invalid_Fax As Boolean
Property Invalid_Mobile As Boolean
Property Invalid_PhoneBusiness As Boolean
Property Invalid_PhoneHome As Boolean
Property Invalid_PostalAddress As Boolean
Property Invalid_StreetAddress As Boolean
Property RSN As String
Property StreetAddress_Line1 As String
Property StreetAddress_Line2 As String
Property StreetAddress_Line3 As String
Property StreetAddress_Line4 As String
Property StreetAddress_Line5 As String
Property StreetAddress_Line6 As String
Property StreetAddress_Line7 As String
Property Suppression_Codes As Suppression_Codes
Property Gender As Gender
End Class
NOTE: This method can be customized and renamed for each entity to select on any combination of values.
Sample Code (in VB.Net)
' Create SecondPerson Object
Dim secondPersonSvc as PersonService.PersonSvc =
secondPersonSvc = New PersonService.PersonSvc
Dim secondPeople As PersonService.Person()
Dim secondPersonResult As PersonService.SelectPersonResult
' Search for people, and store result in a resultset
secondPersonResult = secondPersonSvc.SelectByNameAndEmailaddress(token, firstName, surname, emailAddress)secondPeople = peopleResult.ResultSet
Web Service Method – Login
This method takes several input variables and returns a Person (LoginResult) object, and well as the full profile of the account owner.
Parameters
Key: Client ID (type GUID)
AuthorisationPassword: The password used to authorise the use of this method.
CampaignName: The campaign which all activities associated with the login will be associated with. If blank or invalid no campaign tracking is initiated.
CampaignSegment: The campaign segment which all activities associated with the login will be associated with. If blank or invalid no campaign tracking is initiated.
AccountName: The username used to validate credentials.
Password: The password used to validate credentials. Optional WHEN Authorised Username and Password is provided. This allows the client database to maintain master username and passwords and Simplicity to be a slave without storing any passwords.
TokenValidDuration: The duration the token is valid.
LoginModel: The type of model to use (MultipleLogins, SingleLogin, RoamingLogin)
Returns
A passport object of class ‘Login Result’ with a token, error code, account name, and email address. It also returns the account RSN, the account Owner RSN, type and display value, the account permissions, and the full profile of the account owner.
Additional Notes:
This method does not come with our standard Web Services Installs. You will need to request this method if you’d like to use it. Also, to use this method you will need to have purchased the Passport Services.
MultipleLogins: Allows multiple concurrent tokens.
SingleLogin: If the user has an active token an error (1016) is returned.
RoamingLogin: If the user has an active session then the token is expired and a new token is issued.
Permissions
AccountName must be an Active account. AccountName must have a password specified.
Sample Code (in VB.Net)
' Create Person Service
Dim secondPersonSvc as PersonService.PersonSvc =
secondPersonSvc = New PersonService.PersonSvc
' Attempt to login
Dim secondLoginResults As PersonService.LoginResult
secondLoginResults = secondPersonSvc.Login(Key, AuthorisationPassword, CampaignName, CampaignSegment, AccountName, Password, TokenValidDuration, LoginModel)
Web Service Method – Authenticate
This method takes an existing token and it is expired. A new token is created and the now expired token is linked to the new token’s CampaignList as a referring label code.
The CampaignList that activities are logged against will be changed if the new token’s Campaign/CampaignSegment is different to that of the previous token.
Parameters
Key: Client ID (type GUID)
Authorisation Password: The password used to authorise the use of this method.
Token: Token supplied by logging into the Passport Web Service
CampaignName: The campaign which all activities associated with the login will be associated with. If black or invalid no campaign tracking is initiated.
CampaignSegment: The campaign segment which all activities associated with the login will be associated with. If blank or invalid no campaign tracking is initiated.
Returns
A passport object of class ‘Authentication Result’ with a token, error code, account name, and email address. It also returns the account RSN, the account Owner RSN, type and display value, the account permissions, and the full profile of the account owner.
Sample Code (in VB.Net)
' Create Person Service
Dim secondPersonSvc as PersonService.PersonSvc =
secondPersonSvc = New PersonService.PersonSvc
' Attempt to login
Dim secondAuthenticateResults As PersonService.AuthenticateResult
' Authenticate
Dim secondAuthenticateResults As PersonService.AuthenticateResult
secondAuthenticateResults = secondPersonSvc.Authenticate(key, AuthorisationPassword, token, campaignName, campaignSegment)
Web Service Method - Insert
This method takes a new Person Object and inserts it into the database.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
Value: The Person to be inserted into the database.
Returns
An integer indicating the result of the insert.
Sample Code (in VB.Net)
' Create SecondPerson Object
Dim secondPersonSvc as PersonService.PersonSvc
secondPersonSvc = New PersonService.PersonSvc
Dim secondIndividual As PersonService.Person
' Assign information to the secondPerson object
' (The data assigned is fictional, and for example use only)
secondIndividual.RSN = Guid.NewGuid.ToString
secondIndividual.Title = "Mr"
secondIndividual.GivenName = "Mickey"
secondIndividual.FamilyName = "Mouse"
' Search for people, and store result in a resultset
' Call the Insert method, and store the resulting code in an integer
Dim secondIndividualResult As Integer
secondIndividualResult = secondPersonSvc.Insert(token, secondIndividual)
Web Service Method – Update
This method takes a Person Object that already exists in the database, and updates the values.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
Value: The a person object of the Person to be updated
Returns
An integer indicating the result of the update.
Sample Code (in VB.Net)
' Create SecondPerson Objects
Dim secondPersonSvc As PersonService.PersonSvc = New PersonService.PersonSvc
Dim secondIndividual As PersonService.Person
' Assign information to the secondPerson object
' (The data assigned is fictional, and for example use only)
secondIndividual.Title = "Mr"
secondIndividual.GivenName = "Mickey"
secondIndividual.FamilyName = "Mouse"
' Call the Update method, and store the resulting code in an integer
Dim individualSecondResult As Integer
individualSecondResult = secondPersonSvc.Update(token, secondIndividual)
Web Service Method – Delete
This method takes a Person Object that already exists in the database, and updates the values.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
RSN: The RSN of the Person to be deleted
Returns
An integer indicating the result of the delete.
Sample Code (in VB.Net)
' Create Person Objects
Dim SecondPersonSvc As PersonService.PersonSvc = New PersonService.PersonSvc
Dim secondIndividual As PersonService.Person
' At this point you would assign the person to be deleted to the person object
' ‘secondIndividual’.
' Call the Update method, and store the resulting code in an integer
Dim individualResult As Integer
individualResult = SecondPersonSvc.Update(token, secondIndividual)
Web Service Method – SelectRelatedEntities
This method takes the RSN of the person and returns the requested relationships.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
RSN: The RSN of the Person to select relationships for.
Relationship: The Relationship to select.
Returns
Result is an array containing the following properties:
Public Class Relationship
Property Relationship_Type As Relationship_Type
Property Join_RSN As String
Property Entity_RSN As String
Property Entity_DisplayValue As String
Property Entity_Type As String
End Class
Sample Code (in VB.Net) – select by related entities
This sample selects the ‘current employer’ records from the person-organisation relationship.
' Create Person Object
Dim secondPersonSvc As PersonService.PersonSvc = New PersonService.PersonSvc
Dim secondIndividual As PersonService.Person
' At this point you would assign the person object ‘secondIndividual’ values, such as
' ‘secondIndividual.RSN’ and ‘secondIndividual.DisplayValue’.
' Create Relationship Object
Dim employerRelationship As PersonService.Relationship
' At this point you would assign the relationship object ‘employerRelationship’
' values, such as ‘employerRelationship.Entity_RSN’ and
' ‘employerRelationship.Join_RSN’.
' Search for people, and store result in a resultset
relationshipResult As personService.SelectRelationshipResult
relationshipResult = secondPersonSvc.SelectRelatedEntity(token, secondIndividual.RSN, employerRelationship)
Web Service Method - InsertRelatedEntity
This method inserts a relationship between an entity related to the person entity.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
RSN: The RSN of the Person to insert this relationship for.
DisplayValue: The Display Value of the Person to insert this relationship for.
EntityToInsert: The Relationship to insert.
Public Class Relationship
Property Relationship_Type As Relationship_Type
Property Join_RSN As String
Property Entity_RSN As String
Property Entity_DisplayValue As String
Property Entity_Type As String
End Class
Returns
An Integer indicating the result of the insert
Notes
Please do not use null for the display values. While the display values are not mandatory, they are used in the desktop version of Simplicity and are what your users will see.
Sample Code (in VB.Net)
This sample inserts the ‘current employer’ relationship between the person and organisation entities.
' Create Person Object
Dim secondPersonSvc As PersonService.PersonSvc = New PersonService.PersonSvc
Dim secondIndividual As PersonService.Person
' At this point you would assign the person object ‘secondIndividual’ values, such as
' ‘secondIndividual.RSN’ and ‘secondIndividual.DisplayValue’.
' Create Relationship Object
Dim currentRelationship As PersonService.Relationship
' At this point you would assign the relationship object ‘employerRelationship’
' values, such as ‘employerRelationship.Entity_RSN’ and
' ‘employerRelationship.Join_RSN’.
' Insert relationship
Dim relationshipResult As Integer
relationshipResult = secondPersonSvc.InsertRelatedEntity(token, secondIndividual.RSN, secondIndividual.DisplayValue, currentRelationship)
Web Service Method – DeleteRelatedEntity
This method deletes a relationship between an entity related to the person entity.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
RSN: The RSN of the Person for whom this relationship will be deleted.
DisplayValue: The Display Value of the Person for whom this relationship will be deleted.
EntityToInsert: The Relationship to delete.
Public Class Relationship
Property Relationship_Type As Relationship_Type
Property Join_RSN As String
Property Entity_RSN As String
Property Entity_DisplayValue As String
Property Entity_Type As String
End Class
Returns
An Integer indicating the result of the delete
Notes
Please do not use null for the display values. While the display values are not mandatory, they are used in the desktop version of Simplicity and are what your users will see.
Sample Code (in VB.Net)
This sample deletes the ‘current employer’ relationship between the person and organisation entities.
' Create Person Object
Dim secondPersonsvc As PersonService.PersonSvc = New PersonService.PersonSvc
Dim secondIndividual As PersonService.Person
' At this point you would assign the person object ‘secondIndividual’ values, such as
' ‘secondIndividual.RSN’ and ‘secondIndividual.DisplayValue’.
' Create Relationship Object
Dim currentRelationship As PersonService.Relationship
' At this point you would assign the relationship object ‘employerRelationship’
' values, such as ‘employerRelationship.Entity_RSN’ and
' ‘employerRelationship.Join_RSN’.
' Delete relationship
Dim relationshipResult As Integer
relationshipResult = secondPersonsvc.DeleteRelatedEntity(token, secondIndividual.RSN, secondIndividual.DisplayValue, currentRelationship)
SecondPerson 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
3001 Invalid Token
3007 Insufficient Privileges
3100 Select: Entity Not Found
3110 Insert: Invalid RSN
3111 Insert: Entity already exists
3112 Insert Exception
3120 Update: Invalid RSN
3121 Update Exception
3130 Delete Exception
3140 Select Relationship: Not Found
3141 Insert Relationship Exception
3142 Delete Relationship Exception
Organisation Web Service Method Definitions
The following methods provide the means to create, select, update and delete organisation entity records and links from the organisation entity to related entities in Simplicity. 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/Entities/OrganisationSvc.asmx
- Creating an Organisation Object
- Creating a Relationship Object
- SelectByRSN
- SelectByCompanyName
- Login
- Authenticate
- Insert
- Update
- Delete
- SelectRelatedEntities
- InsertRelatedEntity
- DeleteRelatedEntity
- Organisation Result/Error Codes
Creating an Organisation Object
To create an Organisation Service object in VB.Net use the following code:
(Assumes the web reference is named ‘OrganisationService’)
Dim organisationSvc As OrganisationService.OrganisationSvc
organisationSvc = New OrganisationService.OrganisationSvc
Dim organisations As OrganisationService.Organisation()
Creating a Relationship Object
A relationship object is used to insert/delete related entity objects.
(Assumes the web reference is named ‘OrganisationService’)
Dim currentRelationship As OrganisationService.Relationship
currentRelationship = New OrganisationService.Relationship
Web Service Method – SelectByRSN
This method sends an Organisation RSN to the OrganisationService and returns an organisation object.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
RSN: The RSN of the Organisation to be retrieved.
Returns
Result contains the following properties:
Public Class Organisation
Property DisplayValue As String
Property PostalAddress_Line1 As String
Property PostalAddress_Line2 As String
Property PostalAddress_Line3 As String
Property PostalAddress_Line4 As String
Property PostalAddress_Line5 As String
Property PostalAddress_Line6 As String
Property PostalAddress_Line7 As String
Property RSN As String
Property StreetAddress_Line1 As String
Property StreetAddress_Line2 As String
Property StreetAddress_Line3 As String
Property StreetAddress_Line4 As String
Property StreetAddress_Line5 As String
Property StreetAddress_Line6 As String
Property StreetAddress_Line7 As String
End Class
Sample Code (in VB.Net)
' Create Organisation Objects
Dim organisationSvc As OrganisationService.OrganisationSvc
organisationSvc = New OrganisationService.OrganisationSvc
Dim organisation As OrganisationService.Organisation()
' Search for organisation, and store result in an organisation object
organisation = organisationSvc.SelectByRSN(token, RSN)
Web Service Method – SelectByCompanyName
This method sends an Organisation Name and returns organisation objects that meet the criteria.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
Name: The name of the organisation to be selected. This variable
supports partial matching.
Returns
Result contains the following properties:
Public Class Organisation
Property DisplayValue As String
Property PostalAddress_Line1 As String
Property PostalAddress_Line2 As String
Property PostalAddress_Line3 As String
Property PostalAddress_Line4 As String
Property PostalAddress_Line5 As String
Property PostalAddress_Line6 As String
Property PostalAddress_Line7 As String
Property RSN As String
Property StreetAddress_Line1 As String
Property StreetAddress_Line2 As String
Property StreetAddress_Line3 As String
Property StreetAddress_Line4 As String
Property StreetAddress_Line5 As String
Property StreetAddress_Line6 As String
Property StreetAddress_Line7 As String
End Class
Sample Code (in VB.Net)
' Create Organisation Objects
Dim organisationSvc As OrganisationService.OrganisationSvc
organisationSvc = New OrganisationService.OrganisationSvc
Dim organisations As OrganisationService.Organisation()
Dim organisationResult As OrganisationService.SelectOrganisationsResult
' Pass organisationName to search and return an array
organisationResult = organisationsvc.SelectByName(token, organisationName)
organisations = organisationResult.ResultSet
Web Service Method – Login
This method takes several input variables and returns a Person (LoginResult) object, and well as the full profile of the account owner.
Parameters
Key: Client ID (type GUID)
AuthorisationPassword: The password used to authorise the use of this method.
CampaignName: The campaign which all activities associated with the login will be associated with. If blank or invalid no campaign tracking is initiated.
CampaignSegment: The campaign segment which all activities associated with the login will be associated with. If blank or invalid no campaign tracking is initiated.
AccountName: The username used to validate credentials.
Password: The password used to validate credentials. Optional WHEN Authorised Username and Password is provided. This allows the client database to maintain master username and passwords and Simplicity to be a slave without storing any passwords.
TokenValidDuration: The duration the token is valid.
LoginModel: The type of model to use (MultipleLogins, SingleLogin, RoamingLogin)
Returns
A passport object of class ‘Login Result’ with a token, error code, account name, and email address. It also returns the account RSN, the account Owner RSN, type and display value, the account permissions, and the full profile of the account owner.
Additional Notes:
This method does not come with our standard Web Services Installs. You will need to request this method if you’d like to use it. Also, to use this method you will need to have purchased the Passport Services.
MultipleLogins: Allows multiple concurrent tokens.
SingleLogin: If the user has an active token an error (1016) is returned.
RoamingLogin: If the user has an active session then the token is expired and a new token is issued.
Permissions
AccountName must be an Active account. AccountName must have a password specified.
Sample Code (in VB.Net)
' Create Person Service
Dim organisationSvc As OrganisationService.OrganisationSvc
organisationSvc = New OrganisationService.OrganisationSvc
Dim loginResults As OrganisationService.LoginResult
' Attempt to login
loginResults = organisationSvc.Login(Key, AuthorisationPassword, CampaignName, CampaignSegment, AccountName, Password, TokenValidDuration, LoginModel)
Web Service Method – Authenticate
This method takes an existing token and it is expired. A new token is created and the now expired token is linked to the new token’s CampaignList as a referring label code.
The CampaignList that activities are logged against will be changed if the new token’s Campaign/CampaignSegment is different to that of the previous token.
Parameters
Key: Client ID (type GUID)
Authorisation Password: The password used to authorise the use of this method.
Token: Token supplied by logging into the Passport Web Service
CampaignName: The campaign which all activities associated with the login will be associated with. If black or invalid no campaign tracking is initiated.
CampaignSegment: The campaign segment which all activities associated with the login will be associated with. If blank or invalid no campaign tracking is initiated.
Returns
A passport object of class ‘Authentication Result’ with a token, error code, account name, and email address. It also returns the account RSN, the account Owner RSN, type and display value, the account permissions, and the full profile of the account owner.
Sample Code (in VB.Net)
' Create Organisation Service
Dim organisationSvc As OrganisationService.OrganisationSvc
organisationSvc = New OrganisationService.OrganisationSvc
Dim authenticateResult As OrganisationService.AuthenticateResult
' Authenticate
AuthenticateResult = organisationSvc.Authenticate(key, AuthorisationPassword, token, campaignName, campaignSegment)
Web Service Method – Insert
This method takes a new Organisation Object and inserts it into the database.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
Value: The Organisation to be inserted into the database.
Returns
An integer indicating the result of the insert.
Sample Code (in VB.Net)
' Create Organisation Objects
Dim organisationSvc As OrganisationService.OrganisationSvc
organisationSvc = New OrganisationService.OrganisationSvc
Dim company As OrganisationService.Organisation
' Assign information to the organisation object
' (The data assigned is fictional, and for example use only)
company.RSN = Guid.NewGuid.ToString
company.CompanyName = "Acme Acres Ltd"
company.DisplayValue = "Acme Acres"
' Call the Insert method, and store the resulting code in an integer
Dim organisationResult As Integer
organisationResult = organisationSVC.Insert(token, company)
Web Service Method – Update
This method takes an Organisation Object that already exists in the database, and updates the values.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
Value: The Organisation to be updated
Returns
An integer indicating the result of the update.
Sample Code (in VB.Net)
' Create Organisation Objects
Dim organisationSvc As OrganisationService.OrganisationSvc
organisationSvc = New OrganisationService.OrganisationSvc
Dim company As OrganisationService.Organisation
' Assign information to the organisation object
' (The data assigned is fictional, and for example use only)
company.CompanyName = "Acme Acres Ltd"
' Call the Update method, and store the resulting code in an integer Dim organisationResult As Integer
organisationResult = organisationSvc.Update(token, company)
Web Service Method – Delete
This method takes an Organisation Object that already exists in the database, and deletes it from the database.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
RSN: The RSN of the Organisation to be deleted
Returns
An integer indicating the result of the delete.
Sample Code (in VB.Net)
' Create Organisation Objects
Dim organisationSvc As OrganisationService.OrganisationSvc
organisationSvc = new OrganisationService.OrganisationSvc
Dim company As OrganisationService.Organisation
' At this point you would assign the organisation to be deleted to the organisation
' object ‘secondIndividual’.
' Call the Delete method, and store the resulting code in an integer Dim organisationResult As Integer
organisationResult = OrganisationSvc.Delete(token, company.RSN)
Web Service Method – SelectRelatedEntities
This method takes the RSN of the organisation and returns the requested relationships.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
RSN: The RSN of the Organisation to select relationships for.
Relationship: The Relationship to select.
Returns
Result is an array containing the following properties:
Public Class Relationship
Property Relationship_Type As Relationship_Type
Property Join_RSN As String
Property Entity_RSN As String
Property Entity_DisplayValue As String
Property Entity_Type As String
End Class
Sample Code (in VB.Net)
This sample selects the ‘current staff’ records from the person-organisation relationship.
' Create Organisation Objects
Dim organisationSvc As OrganisationService.OrganisationSvc
organisationSvc = new OrganisationService.OrganisationSvc
Dim company As OrganisationService.Organisation
' At this point you would assign the organisation object ‘company’ values, such as
' ‘company.RSN’
' Create Relationship Object
Dim employeeRelationship As OrganisationService.Relationship
' At this point you would assign the relationship object ‘employerRelationship’
' values, such as ‘employerRelationship.Entity_RSN’ and
' ‘employerRelationship.Join_RSN’.
' Search for organisations, and store result in a resultset relationshipResult As organisationService.SelectRelationshipResult
relationshipResult = organisationSvc.SelectRelatedEntity(token, company.RSN, employeeRelationship)
Web Service Method – InsertRelatedEntity
This method inserts a relationship between an entity related to the person entity.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
RSN: The RSN of the Organisation to insert this relationship for.
DisplayValue: The Display Value of the Organisation to insert this relationship for.
EntityToInsert: The Relationship to insert.
Public Class Relationship
Property Relationship_Type As Relationship_Type
Property Join_RSN As String
Property Entity_RSN As String
Property Entity_DisplayValue As String
Property Entity_Type As String
End Class
Returns
An Integer indicating the result of the insert
Notes
Please do not use null for the display values. While the display values are not mandatory, they are used in the desktop version of Simplicity and are what your users will see.
Sample Code (in VB.Net)
This sample inserts the ‘current employer’ relationship between the person and organisation entities.
' Create Organisation Objects
Dim organisationSvc As OrganisationService.OrganisationSvc
organisationSvc = new OrganisationService.OrganisationSvc
Dim company As OrganisationService.Organisation
' At this point you would assign the organisation object ‘company’ values, such as
' ‘company.RSN’
' Create Relationship Object
Dim currentRelationship As OrganisationService.Relationship
' At this point you would assign the relationship object ‘employerRelationship’
' values, such as ‘employerRelationship.Entity_RSN’ and
' ‘employerRelationship.Join_RSN’.
' Insert relationship
Dim relationshipResult As Integer
relationshipResult = organisationSvc.InsertRelatedEntity(token, company.RSN, company.DisplayValue, employeeRelationship)
Web Service Method – DeleteRelatedEntity
This method deletes a relationship between an entity related to the organisation entity.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
RSN: The RSN of the Organisation for whom this relationship will be deleted.
DisplayValue: The Display Value of the Organisation for whom this relationship will be deleted.
EntityToInsert: The Relationship to delete.
Public Class Relationship
Property Relationship_Type As Relationship_Type
Property Join_RSN As String
Property Entity_RSN As String
Property Entity_DisplayValue As String
Property Entity_Type As String
End Class
Returns
An Integer indicating the result of the delete
Notes
Please do not use null for the display values. While the display values are not mandatory, they are used in the desktop version of Simplicity and are what your users will see.
Sample Code (in VB.Net)
This sample inserts the ‘current employer’ relationship between the person and organisation entities.
' Create Organisation Objects
Dim organisationSvc As OrganisationService.OrganisationSvc
organisationSvc = new OrganisationService.OrganisationSvc
Dim company As OrganisationService.Organisation
' At this point you would assign the organisation object ‘company’ values, such as
' ‘company.RSN’
' Create Relationship Object
Dim currentRelationship As Organisation Service.Relationship
' At this point you would assign the relationship object ‘employerRelationship’
' values, such as ‘employerRelationship.Entity_RSN’ and
' ‘employerRelationship.Join_RSN’.
' Delete relationship
Dim relationshipResult As Integer
relationshipResult = personsvc.DeleteRelatedEntity(token, company.RSN, company.DisplayValue, employeeRelationship)
Organisation 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
3001 Invalid Token
3007 Insufficient Privileges
3100 Select: Entity Not Found
3110 Insert: Invalid RSN
3111 Insert: Entity already exists
3112 Insert Exception
3120 Update: Invalid RSN
3121 Update Exception
3130 Delete Exception
3140 Select Relationship: Not Found
3141 Insert Relationship Exception
3142 Delete Relationship Exception
Stored Procedure Services Overview
The following method is an example of functionality that a stored procedure may provide. These methods are designed to fit stored procedures seamlessly into the Web Services architecture, and can be accessed via the entity that is most appropriate for that method (for example, the ‘Household_Program_Dedupe’ method will be found on the household service).
Only stored procedures that exist currently within your Simplicity Version can be exposed. As each Simplicity Configuration is unique, if you would like a Stored Procedure exposed to the Web Services, please contact your Simplicity Account Manager.
Example: Household_Program_Dedupe
This method is a stored procedure that takes a household address, and a programme code and returns how many duplicate households are stored against that program.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
Primary Surname: The primary surname of the household.
Address 1: Address Line 1
Address 2: Address Line 2
Address 3: Address Line 3
Address 4: Address Line 4
Address 5: Address Line 5
DPID: DPID Code (The Delivery Point Identifier, which is an 8 digit code allocated to a valid delivery point).
Program Code: The program to dedupe against
Returns
Result contains the following properties:
Public ClassHousehold_Program_DedupeResult
Property ErrorCode as Integer
Property ReturnCode as Integer
Property NoOfRegistrations as Integer
End Class
Sample Code (in VB.Net)
' Create Household Service
Dim householdSvc As HouseholdService.HouseholdSvc
householdSvc = new HouseholdService.HouseholdSvc
' Dedupe Househould Program
Dim dedupeResult As HouseholdService.Household_Program_DedupeResult
dedupeResult = householdSvc.Household_Program_Dedupe(token, "Surname", "1 Road Ave", "Subrub", "City/Town/State", "PostCode", "Country", "12345678", programCode, petType)
Example: Person_MemberUpdate
This stored procedure takes a memberID and a person RSN, the persons name and email address, and updates the person record and the member record.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
RSN: RSN of person to update.
MemberID: Member Id of person to update. Contains the following properties:
Public ClassMemberID
Property IsNull as Boolean
Property Value as As String
End Class
This structure is an example of nullable types. If the ‘isNull’ property is set to null, it will also set the value to ‘null’.
GivenName: The Given Name of the person to be selected. GivenName supports wildcard and partial matching.
FamilyName: The Family Name of the person to be selected. FamilyName supports wildcard and partial matching.
Email: The email address of the person to be selected. Email supports wildcard and partial matching.
Returns
Result contains the following properties:
Public ClassPerson_MemberUpdateResult
Property ErrorCode as Integer
Property ReturnCode as Integer
End Class
Sample Code (in VB.Net)
' Create Person Service
Dim personSvc As PersonService.PersonSvc
personSvc = new PersonService.PersonSvc
' Update Member
Dim udpdateResult As PersonService.Person_MemberUpdateResult
udpdateResult = personSvc. Person_MemberUpdate(token, personRSN, memberID, "Joe", "blogs", "joe.blogs@email.com")
Selection via List Functionality Overview
The following method is an example of functionality that a Selection via List Functionality can provide. It is used to return a list that may contain attributes from multiple related entities in a record, as opposed to elements from a single entity. If you would like this functionality exposed to Web Services, please contact your Simplicity Account Manager.
Example: Person_List_Select
This method takes a persons name, email (both person attributes), and an organization name, the distribution group and membership type (organization attributes). It returns a list of people associated with the organization.
Parameters
Token: Token returned by Logging in to the Passport Web Service.
Given Name: The given name of the person/people to select.
Surname: The surname of the person/people to select.
Company Name: The Company name of the organisation to select against
Email: The email address of the person/people to select.
SingleView ID: The Single View ID of the person/people to select.
Distribution Group:
Public Class DistributionGroup
Property ChristmasCard As Boolean
Property RightAddress As Boolean
Property Seed As Boolean
Property SimplicityNewsletter As Boolean
Class
Returns
Result contains a list of the following properties:
Public ClassPerson_List_SelectResult
Property Errorcode as String
Property PartialResultSet as Boolean
Property ResultSet as ResultSetStructure
End Class
Public Class ResultSet
Property RSN as String
Property Name as String
Property BusinessPhone as String
Property MobilePhone as String
Property Email as String
Property Employers as String
Property SimplicityNewsletter as Boolean
Property DistributionGroup as DistributionGroup
Property JobTitle as String
Property SingleViewID as String
End Class
Public Class DistributionGroup
Property ChristmasCard As Boolean
Property RightAddress As Boolean
Property Seed As Boolean
Property SimplicityNewsletter As Boolean
Class
Sample Code (in VB.Net)
' Create Person Service
Dim personSvc As PersonService.PersonSvc
personSvc = new PersonService.PersonSvc
' Set up Distribution Group
Dim distributionGroup As PersonService.Distribution
' Select Person List
Dim selectResult As PersonService.Person_List_SelectResult
selectResult = personSvc.Person_List_Select(token, "Joe", "", "", "Simplicity", "", "", distributionGroup, MembershipType.Company01to05)
Overall Result/Error Codes
0 Operation completed successfully
1001 An internal error occurred. Results should be discarded.
1002 Invalid campaign specified
1003 Ambiguous campaign specified
1004 Invalid campaign segment specified
1005 Ambiguous campaign segment specified
1006 Operation could not be completed – duplicate label code
1007 Invalid password specified for OldPassword parameter
1008 Invalid password specified for Password or NewPassword parameter
1009 Invalid email address specified
1010 Invalid account name. This may be due to the specified account name not existing, or the specified account name being Inactive
1011 Operation could not be completed – duplicate account name
1012 Invalid name specified for GivenName or FamilyName parameter
1013 Operation could not be completed – account status is Active
1014 Operation could not be completed – account status is Inactive
3001 Invalid token specified. This may be due to an incorrect or expired token being passed to the Passport web service. By default the token is only active for 5 minutes from last use. The token can, however, continue to be used outside the Passport web service for accessing online forms etc
3004 Operation could not be completed – account associated with the specified token does not have sufficient access rights to perform the operation
3007 Invalid credentials were supplied to one of the Login methods. This may be due to an invalid key, invalid account name or invalid password.
3100 Select found no results
3110 The RSN of the entity to be inserted was blank or invalid
3111 The Entity being inserted already exists in the database
3112 The Entity could not be inserted, possibly due to an internal error.
3120 The RSN of the entity to be updates was blank or invalid
3121 The Entity could not be updated, possibly due to an internal error
3130 The Entity could not be deleted, possibly due to an internal error
3140 Select found no results
3141 The Relationship could not be inserted, possibly due to an internal error
3142 The Relationship could not be deleted, possibly due to an internal error.
Help & Support