UpdateRespondents

Description

Updates the respondents. Missing respondents will be added.

If 'merge' is set to true and the respondents have existing 'key'-values, existing rows will be updated. If set to false, existing rows will not be updated. In both cases, rows will be added if 'key'-values are not found. If "inTransaction" is set to true, the update will be performed in a transaction. If an error occurs, a rollback for the whole update will be executed. The "transactionKey" parameter must be specified if "inTransaction" is set to true. Since the operation will perform a rollback if an error occurs, the return value will not have any function when the a transaction is used.
Signature
ErrorMessage[] UpdateRespondents(string key,string projectId, DataSet ds, bool validate, bool merge, string uniqueKey,bool inTransaction, int transactionKey)

Parameters

Name Data Type Description

key

string required

The authentication key

projectId

string required

The project ID

ds

DataSet

DataSet containing the respondent rows to be updated.

validate

bool required

Validation of the content of the respondents.

merge

bool required

Update existing rows when possible.

uniqueKey

string optional

The name of the unique key to use when updating the respondents. If set to null or an empry string, the internal id (respid) for respondents will be used.

inTransaction

bool

True runs the update in a transaction, False does not.

transactionKey

int

A key, defined by the user to be able to track if the transaction succeded or not (cannot be a negative number). See GetTransactionStatus.

Response

Data Type Description

ErrorMessage[ ]

Example

//***************************************************
//
// GetRespondents
// UpdateRespondents
//
//***************************************************

// Array of error-objects that will be returned if errors
// in a UpdateRespondents()-function
ErrorMessage[] errors;

// We will use ds and dt when retrieving respondents
DataSet ds;
DataTable dt;

// New instance of the SurveyData webservice
SurveyDataSoapClient sd = new SurveyDataSoapClient();

// We make the assumption that we have a project with
// the backgroundvariables 'gender' (precodes F and M),
// age (integer) and email (string).

// Get empty DataTable
ds = sd.GetRespondents(key,
    SurveyDataUtil.NewRespondentTransferDef(
    true,true,projectID));
dt = ds.Tables[SurveyDataUtil.RespondentTableName];

// Add a new column
// (If 'email' is needed and not already specified as a backgroundvariable
// in the survey the column should be added to enable email sendout)
// In this example we assume that 'email' is already a background variable.
string newColumnName = "myNewColumn";
if (!dt.Columns.Contains(newColumnName))
{
    dt.Columns.Add(
        new DataColumn(newColumnName,typeof(string)));
}

// Add a new row
DataRow dr = dt.NewRow();
dr["gender"] = "F";
dr["age"] = 17;
dr[newColumnName] = "my new value";
dr["email"] = "dummy@dummy.com";
dt.Rows.Add(dr);

// Make the update
errors = sd.UpdateRespondents(key,projectID,ds,true,false,"",false,-1);

// Check if there was any errors
if (errors.Length>0)
{
    //Implement error-handling here
}


// Make a definition that limits to retrieve the user columns 'email'
// and the new column defined by the variable newColumnName
// and the system columns 'respid' and SID from all female respondents (gender=F)
RespondentTransferDef def =
    SurveyDataUtil.NewRespondentTransferDef(
    false,false,projectID);
ArrayList fieldNames = new ArrayList();
fieldNames.Add("email");
fieldNames.Add(newColumnName);
def.FieldNames = (string[])fieldNames.ToArray(typeof(string));
RespondentSystemVariables s = new RespondentSystemVariables();
s.IncludeRespId = true;
s.IncludeSID = true;
def.SystemVariables = s;
def.Where = SurveyDataUtil.NewWhereClause(
    SurveyDataUtil.NewBinaryComparison(
    ComparisonType.Equal,
    SurveyDataUtil.NewQueryField("gender"),
    SurveyDataUtil.NewQueryConstant(ConfirmitDbType.VarChar,"F")));

// Read the specified respondents
ds = sd.GetRespondents(key,def);
dt = ds.Tables[SurveyDataUtil.RespondentTableName];

// Change the new column for the retrieved rows
foreach (DataRow drResp in dt.Rows)
    drResp[newColumnName] = "My female comment";

// Make the update
// Note that we needed to retrieve the 'respid' to be able to update
errors = sd.UpdateRespondents(key,projectID,ds,true,true,"",false,-1);

// Check if there was any errors
if (errors.Length>0)
{
    //Implement error-handling here
}