Data Integration Web Services Whitepaper

Overview

The Simplicity Data Integration Web Services provides the means of interacting with customer information, history related to campaign activities, email services and access to any configured entities (such as the Person entity, or an Organisation entity).

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 Organisation). It also includes the ability to create campaign activity, and send emails.

Campaign activity services are used to insert campaign activity (in the form of emails sent, data exports, and surveys taken) against an entity (such as a person). These services are used to keep history records about the interaction that has taken place with a user via a campaign.

Email services are used to create and send emails. These emails can be for campaigns, from templates, delayed, or a mixture of these options.

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). Each entity has its own set of configurable attributes (for example a Person in the Person entity could have a Gender attribute).

These services allow the creation and deletion of data records (such as a Person in the Person entity, or an Organisation in the Organisation entity). It also includes the ability the update data (such as changing the address of a Person), or search the data (such as return all the Person records in the Person entity whose First Name is “Bob”).

Another feature of these services is the ability to select entites based on criteria from related entities. For example, by using the person service it is possible to select people based on the household they belong to, using the person_household relationship.

It is also possible to return a list (with configured attributes) from a select statement. For example, searching for a person with the name “Joe” could return a list of people, with the return parameters ‘First Name’ and Last Name’ (as opposed to all the attributes associated with the person record).

Stored Procedures Services are available to provide additional functionality if required. If a store procedure is currently used within your Simplicity Version (ie, cleaning a household address) then the same stored procedures can be called via the Entity Web Service (ie, the Household Service).

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.

Accessibility Diagram

The web services are accessed via standard web requests as illustrated.

Frequently Asked Questions

What is an entity?

An entity is a custom configured scalable table in a database (ie, the Person entity). Each record in the table is often referred to as the object or concept it represents (ie, a person). Each object or concept has multiple attributes configured to it, for example, a Person has name, a gender, an address, an email address etc. An entity can be configured to represent any information you may require.

What is campaign activity?

Campaign Activity is a record that logs what activity takes place in relation to a user. This includes events like sending emails, exporting data etc.

Where is campaign activity written to? Is it written when we use a custom form?

Within the DIWS framework is service dedicated to Campaign Activity. With this service you can write activity records against any configured entity (such as a person, or an organization). So yes, you can write an ‘email sent’ campaign activity record against the person ‘Joe Blogs’, with the activity type ‘Christmas Dec 09 Email Sent’.

Please be aware that this DOES NOT happen automatically as it does in Simplicity, you will need to have a developer add this functionality to your project.

Can the Data Integration Web Service be used without the Passport Web Service?

While the two services are separate, the Data Integration Web Services (DIWS) can not be used without the Passport Web Services. This is because each method within DIWS passes a security token which is set within the Passport Web Services. If implemented correctly, this ensures the integrity of the data from outside threats.

Can anyone use these services?

It is highly recommended that only a trained developer with experience in VB.NET implement the Data Integration Web Service framework into a webform to be used by an average user.

Campaign Activity Web Service Features

This service can provide the means to create associated campaign activity records against campaigns and entities (such as a Person in the Person entity) in Simplicity.

Inserting Activity Records (Email, Export, Surveys)

An activity record is written against a campaign, or an entity record (such as a Person in the Person entity). You can insert an activity record against the campaign or entity record to show that an event has happened.

Activities that you may wish to write records for may be things like sending an email, exporting data for the mailhouse, or a user took a survey.

Email Web Service Method Features

This service can provide the means to send, delay or select emails that have been created.

Selecting Emails

Emails can be selected by their unique email ID. By selecting an email you can view the campaign associated with the email, the status of the email (ie sent or delayed), whether the email has been sent, the date the email was successfully sent, the date the email joined the mail queue, and who added it to the mail queue.

Sending Emails

Emails can be sent via this web service. They can be delayed or sent immediately. They can also be sent from a template, or from a campaign where an activity record will be inserted against the campaign. An activity record can also be inserted against an entity, if one is specified.

Please note that if sending from a campaign, if the campaign name does not exist it will be created. If it is blank or ambiguous, (ie multiple campaigns with the same name exist) no campaign tracking is initiated and the Activity will not be inserted.

Entity Web Service Method Features

This web service provides the means to create, select, update and delete data in a custom configured entity record, and the pertaining links to related entities in Simplicity.

Please note that these methods are configured especially for each specific entity, and may be different in your version of DIWS.

As an example we will be using a PERSON entity to show how these methods can be used, and what can be done with them.

You can also have duplicate web services’ running for the same entity. Ie, you could have two Person Web Service’s running at the same time, for example you could run the Person Service and the SecondPerson service concurrently.

Selecting People

A person can be selected by RSN (the unique GUID identifier for each person record), by name (either full or partial) or by email address. This will return either a person record or a result set of people with the appropriate attributes.

For example, below is a sample Person Seach Screen.

If a person record is searched (in this case by name and email address, or a partial mix of these), and the said person doesn’t exist an error code will be returned and an error message can be published to the screen.

If a person record is searched and the said person does exist the matching record (or records) will be returned, and the associated attributes can be printed to screen.

Selecting People with List Functionality

A person can be selected by a set of predefined parameters (such as first name) and list of people with predefined attributes will be returned. These predefinied attributes might be First Name, Surname, Email Address and Gender. No other person attributes (such as phone number, or address) will be returned. This ensures that you are only receiving the data you require.

Inserting People

A person can be inserted into Simplicity with the relevant information supplied for insertion. This will save a new record in the databse which can be viewed at a later date.

Below is an example ‘insert person’ page. Only the attributes which are required are captured.

If the application’s validation rules are not met, error messages can be printed to the screen. (Please be aware that this functionality is not included in the Web Services, and you will need to ensure the captured data’s integrity within your application).

If a person can not be inserted, the web services will return an error code.

When a person record is inserted successfully a confirmation message can be printed to screen.

The newly added person is now in the Simplicity Database and can then be accessed through the Web Services, or the Desktop eqivilent.

Updating a Record

Attributes of an already existing person record can be updated, and then saved in the database. A specific field can be updated or the entire record can be overwritten depending on the configuration of Web Services. (If you would like the ability to update a single field, please request the functionality as this is not standard).

Deleting a Record

A person that already exists in the Simplicity database can be deleted (removed from the database). This action will delete the entire record of the person, not just attributes of a person.

Selecting Related Entities

A relationship between entities can be selected by the RSN (the unique GUID identifier for each person record) of the person. This will return all relationships between the person and any other entity e.gthe staff/employer relationship between a Person and an Organisation.

This method will return a Relationship, that has the relationship Type (ie staff/employer), the Join RSN (the unique identifier for the relationship), the other entity in the relationship (ie, the Organisation)

Inserting Related Entities

A relationship between the person entity and another entity (such as the staff/employer relationship between a Person and an Organisation) can be created and stored in the Simplicity database.

This method will insert a Relationship that has the relationship Type (ie staff/employer), the Join RSN (the unique identifier for the relationship), and the other entity in the relationship (ie, the Organisation)

Deleting Related Entities

An existing relationship can be deleted (removed from the database). This action will severe the relationship between the person record and the record from another entity in which it is related to (such as the staff/employer relationship between a Person and an Organisation).

Logging In

A user with an enabled account can log in and out of the person service. If the login is successful a token will be provided as well as the profile of the account owner who logged in. This token is only valid for a configurable duration, and only with a valid token can the services be accessed.

You can also specify a campaign name and segment (that must exist in Simplicity) if you would like an activity record written again that campaign when the user logs in.

There is also the ability to define the login model, which defines the number of tokens allowed in a session. The three models are as follows:

MultipleLogins: Allows multiple concurrent tokens.
SingleLogin: If the user has an active token an error is returned.
RoamingLogin: If the user has an active session then the token is expired and a new token is issued.
On logging out, the token is expired and the services will be unavailable until the user logs in.

Please note that this feature requires the purchase of the Passport Web Services. This feature is not standard, and if you would like this as part of your Web Service configuration you will need to request it.

This is a sample log in page. From here a user can enter a previously defined username and password (at this point the user’s account has been created by another user with the appropriate permissions, and the account is enabled).

If the login credentials are not correct, an error code will be returned, and an error message can be returned to the screen.

If the login credentials are correct a ‘success’ code and the attributes associated with the account owner will be returned and a confirmation message unique to the account owner can be returned to the screen.

Authentication

You are able to authenticate a user. This is where the current token of a session is expired. A new token is then created, and the expired token is liked to the new token’s Campaign list as a referring label code. As well as the new token, the full profile of the account owner is provided.

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.

Survey Answers Web Service Method Features

This service is used to insert the answers of a survey/online form, and to select survey answer records by CampaignListRSNs, Dedupe Keys, Labelcode or Survey instances.

Inserting Survey Answers

A survey answer record or a range of records can be inserted into Simplicity with the relevant information supplied for insertion. This will save a new record in the databse against an entity (such as a person) which can be viewed at a later date.

Selecting Survey Answers

A survey answer record can be selected by RSN (the unique GUID identifier for each record), by Campaign List RSNs (the RSN which holds together all the segments of a campaign), Dedupe Keys (keys that define what fields must match for a record to be considered a duplicate), LabelCodes (codes used to tie a user/entity to their activity), or by Survey Instances.

This will return either a survey answer record or a result set of survey answers with the appropriate attributes.

Web Service Overview