Abstract implementation of SourceInterface containing basic utilities and logical separation between the Gems database and the Source database

package Gems
subpackage OpenRosa
copyright Copyright (c) 2011 Erasmus MC
license New BSD License
since Class available since version 1.5
inherited_from \Gems_Tracker_Source_SourceAbstract

 Methods

Standard constructor for sources

__construct(array $sourceData, \Zend_Db_Adapter_Abstract $gemsDb) 
inherited_from \Gems_Tracker_Source_SourceAbstract::__construct()

Parameters

$sourceData

array

The information from gems__sources for this source.

$gemsDb

\Zend_Db_Adapter_Abstract

Do not want to copy db using registry because that is public and this should be private

Standard constructor for sources

__construct(array $sourceData, \Zend_Db_Adapter_Abstract $gemsDb) 
Inherited
inherited_from \Gems_Tracker_Source_SourceInterface::__construct()

Parameters

$sourceData

array

The information from gems__sources for this source.

$gemsDb

\Zend_Db_Adapter_Abstract

Do not want to copy db using registry because that is public and this should be private

Checks wether this particular source is active or not and should handle updating the gems-db with the right information about this source

checkSourceActive(integer $userId) : boolean

Parameters

$userId

integer

Id of the user who takes the action (for logging)

Returns

boolean

Survey source synchronization check function

checkSurvey(string $sourceSurveyId, integer $surveyId, integer $userId) : mixed

Parameters

$sourceSurveyId

string

$surveyId

integer

$userId

integer

Returns

mixedmessage string or array of messages

Inserts the token in the source (if needed) and sets those attributes the source wants to set.

copyTokenToSource(\Gems_Tracker_Token $token, string $language, integer $surveyId, string $sourceSurveyId = null) : integer

Parameters

$token

\Gems_Tracker_Token

$language

string

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Exceptions

\Gems_Tracker_Source_SurveyNotFoundException

Returns

integer1 of the token was inserted or changed, 0 otherwise

Returns a field from the raw answers as a date object.

getAnswerDateTime(string $fieldName, \Gems_Tracker_Token $token, integer $surveyId, string $sourceSurveyId = null) : \MUtil_Date

A seperate function as only the source knows what format the date/time value has.

Parameters

$fieldName

string

Name of answer field

$token

\Gems_Tracker_Token

Gems token object

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Returns

\MUtil_Datedate time or null

Gets the time the survey was completed according to the source

getCompletionTime(\Gems_Tracker_Token $token, integer $surveyId, string $sourceSurveyId = null) : \MUtil_Date

A source always return null when it does not know this time (or does not know it well enough). In the case \Gems_Tracker_Token will do it's best to keep track by itself.

Parameters

$token

\Gems_Tracker_Token

Gems token object

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Returns

\MUtil_Datedate time or null

Returns an array containing fieldname => label for each date field in the survey.

getDatesList(string $language, integer $surveyId, string $sourceSurveyId = null) : array

Used in dropdown list etc..

Parameters

$language

string

(ISO) language string

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Returns

arrayfieldname => label

getId()

getId() : integer
Inherited
inherited_from \Gems_Tracker_Source_SourceInterface::getId()

Returns

integerThe source Id of this source

Returns an array of arrays with the structure: question => string, class => question|question_sub group => is for grouping type => (optional) source specific type answers => string for single types, array for selection of, nothing for no answer

getQuestionInformation(string $language, integer $surveyId, string $sourceSurveyId = null) : array

Parameters

$language

string

(ISO) language string

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Returns

arrayNested array

Returns an array containing fieldname => label for dropdown list etc.

getQuestionList(string $language, integer $surveyId, string $sourceSurveyId = null) : array

.

Parameters

$language

string

(ISO) language string

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Returns

arrayfieldname => label

Returns the answers in simple raw array format, without value processing etc.

getRawTokenAnswerRow(string $tokenId, integer $surveyId, string $sourceSurveyId = null) : array

Function may return more fields than just the answers.

Parameters

$tokenId

string

Gems Token Id

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Returns

arrayField => Value array

Returns the answers of multiple tokens in simple raw nested array format, without value processing etc.

getRawTokenAnswerRows(array $filter, integer $surveyId, string $sourceSurveyId = null) : array

Function may return more fields than just the answers. The $filter param is an array of filters to apply to the selection, it has some special formatting rules. The key is the db-field to filter on and the value could be a value or an array of values to filter on.

Special keys that should be mapped to the right field by the source are: respondentid organizationid consentcode token

So a filter of [token]=>[abc-def][def-abc] will return the results for these two tokens while a filter of [organizationid] => 70 will return all results for this organization.

Parameters

$filter

array

filter array

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Returns

arrayOf nested Field => Value arrays indexed by tokenId

Returns the recordcount for a given filter

getRawTokenAnswerRowsCount(array $filter, integer $surveyId, string $sourceSurveyId = null) : integer

Abstract implementation is not efficient, sources should handle this as efficient as possible.

inherited_from \Gems_Tracker_Source_SourceAbstract::getRawTokenAnswerRowsCount()

Parameters

$filter

array

filter array

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Returns

integer

Returns the recordcount for a given filter

getRawTokenAnswerRowsCount(array $filter, integer $surveyId, string $sourceSurveyId = null) : integer
Inherited

Abstract implementation is not efficient, sources should handle this as efficient as possible.

inherited_from \Gems_Tracker_Source_SourceInterface::getRawTokenAnswerRowsCount()

Parameters

$filter

array

filter array

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Returns

integer

Get the select object to use for RawTokenAnswerRows

getRawTokenAnswerRowsSelect(array $filter, \type $surveyId, \type $sourceSurveyId = null) : \Zend_Db_Select

Parameters

$filter

array

$surveyId

\type

$sourceSurveyId

\type

Returns

\Zend_Db_Select

Get the db adapter for this source

getSourceDatabase() : \Zend_Db_Adapter_Abstract
Inherited
inherited_from \Gems_Tracker_Source_SourceInterface::getSourceDatabase()

Returns

\Zend_Db_Adapter_Abstract

Gets the time the survey was started according to the source.

getStartTime(\Gems_Tracker_Token $token, integer $surveyId, string $sourceSurveyId = null) : \MUtil_Date

A source always return null when it does not know this time (or does not know it well enough). In the case \Gems_Tracker_Token will do it's best to keep track by itself.

Parameters

$token

\Gems_Tracker_Token

Gems token object

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Returns

\MUtil_Datedate time or null

getSurvey()

getSurvey(\type $surveyId, \type $sourceSurveyId = null) : \OpenRosa_Tracker_Source_OpenRosa_Form

Parameters

$surveyId

\type

$sourceSurveyId

\type

Returns

\OpenRosa_Tracker_Source_OpenRosa_Form

Returns a model for the survey answers

getSurveyAnswerModel(\Gems_Tracker_Survey $survey, string $language = null, string $sourceSurveyId = null) : \MUtil_Model_ModelAbstract

Parameters

$survey

\Gems_Tracker_Survey

$language

string

Optional (ISO) language string

$sourceSurveyId

string

Optional Survey Id used by source

Returns

\MUtil_Model_ModelAbstract

Return info about the survey (row from gems__openrosaforms)

getSurveyInfo(integer $sourceSurveyId) : array

Parameters

$sourceSurveyId

integer

Returns

array

Returns the url that (should) start the survey for this token

getTokenUrl(\Gems_Tracker_Token $token, string $language, integer $surveyId, string $sourceSurveyId) : string

Parameters

$token

\Gems_Tracker_Token

Gems token object

$language

string

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Returns

stringThe url to start the survey

Checks whether the token is in the source.

inSource(\Gems_Tracker_Token $token, integer $surveyId, string $sourceSurveyId = null) : boolean

Parameters

$token

\Gems_Tracker_Token

Gems token object

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Returns

boolean

Returns true if the survey was completed according to the source

isCompleted(\Gems_Tracker_Token $token, integer $surveyId, string $sourceSurveyId = null) : boolean

Parameters

$token

\Gems_Tracker_Token

Gems token object

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Returns

booleanTrue if the token has completed

Sets the answers passed on.

setRawTokenAnswers(\Gems_Tracker_Token $token, $answers, integer $surveyId, string $sourceSurveyId = null

Parameters

$token

\Gems_Tracker_Token

Gems token object

$answers

array Field => Value array

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

Sets the completion time.

setTokenCompletionTime(\Gems_Tracker_Token $token, \Zend_Date|null $completionTime, integer $surveyId, string $sourceSurveyId = null

Parameters

$token

\Gems_Tracker_Token

Gems token object

$completionTime

\Zend_Datenull

\Zend_Date or null

$surveyId

integer

Gems Survey Id (actually required)

$sourceSurveyId

string

Optional Survey Id used by source

Updates the gems database with the latest information about the surveys in this source adapter

synchronizeSurveyBatch(\Gems_Task_TaskRunnerBatch $batch, integer $userId) : array
Inherited
inherited_from \Gems_Tracker_Source_SourceInterface::synchronizeSurveyBatch()

Parameters

$batch

\Gems_Task_TaskRunnerBatch

$userId

integer

Id of the user who takes the action (for logging)

Returns

arrayReturns an array of messages

Updates the gems database with the latest information about the surveys in this source adapter

updateConsent(\Gems_Tracker_Token $token, integer $surveyId, string $sourceSurveyId = null, string $consentCode = null) : array: integer

Parameters

$token

\Gems_Tracker_Token

$surveyId

integer

Gems Survey Id

$sourceSurveyId

string

Optional Survey Id used by source

$consentCode

string

Optional consent code, otherwise code from token is used.

Returns

arrayReturns an array of messages / public function synchronizeSurveys($userId) { $messages = $this->_scanForms(); // Surveys in LS $db = $this->getSourceDatabase(); $select = $db->select(); $select->from('gems__openrosaforms'); $openRosaSurveys = $db->fetchAssoc($select); if (!$openRosaSurveys) { //If no surveys present, just use an empty array as array_combine fails $openRosaSurveys = array(); $openRosaSurveyIds = array(); } else { $openRosaSurveyIds = array_combine(array_keys($openRosaSurveys), array_keys($openRosaSurveys)); } // Surveys in Gems $gemsSurveys = $this->_getGemsSurveysForSynchronisation(); foreach ($gemsSurveys as $surveyId => $sourceSurveyId) { $survey = $this->tracker->getSurveyBySourceId($sourceSurveyId, $this->getId()); if (isset($openRosaSurveyIds[$sourceSurveyId])) { // Exists $values['gsu_survey_name'] = $openRosaSurveys[$sourceSurveyId]['gof_form_title'] . ' [' . $openRosaSurveys[$sourceSurveyId]['gof_form_version'] . ']'; $values['gsu_surveyor_active'] = $openRosaSurveys[$sourceSurveyId]['gof_form_active']; $values['gsu_status'] = 'OK'; } else { // No longer exists $values['gsu_surveyor_active'] = 0; $values['gsu_status'] = 'No longer exists'; } $survey->saveSurvey($values, $userId); } foreach (array_diff($openRosaSurveyIds, $gemsSurveys) as $sourceSurveyId) { // New survey $values = array(); $values['gsu_survey_name'] = $openRosaSurveys[$sourceSurveyId]['gof_form_title'] . ' [' . $openRosaSurveys[$sourceSurveyId]['gof_form_version'] . ']'; $values['gsu_surveyor_active'] = $openRosaSurveys[$sourceSurveyId]['gof_form_active']; $values['gsu_active'] = 0; $values['gsu_status'] = ''; $survey = $this->tracker->getSurveyBySourceId($sourceSurveyId, $this->getId()); $survey->exists = false; $survey->saveSurvey($values, $userId); } return $messages; } Updates the consent code of the the token in the source (if needed)
integer1 of the token was inserted or changed, 0 otherwise

Open the dir, suppressing possible errors and try to create when it does not exist

_checkDir(\type $directory) : \Directory

Parameters

$directory

\type

Returns

\Directory

Returns all surveys for synchronization

_getGemsSurveysForSynchronisation() : array
Inherited

Returns

arrayPairs gemsId => sourceId

Returns all surveys for synchronization

_getSourceSurveysForSynchronisation() : array
inherited_from \Gems_Tracker_Source_SourceAbstract::_getSourceSurveysForSynchronisation()

Returns

arrayof sourceId values or false

Returns all surveys for synchronization

_getSourceSurveysForSynchronisation() : array
Inherited

Returns

arrayof sourceId values or false

Creates a where filter statement for tokens that do not have a correct name and are in a tokens table

_getTokenFromSqlWhere(string $from, string $fieldName) : string
Inherited

Parameters

$from

string

The tokens that should not occur

$fieldName

string

Name of database field to use

Returns

string

Creates a SQL update statement for tokens that do not have a correct name and are in a tokens table.

_getTokenFromToSql(string $from, string $to, string $fieldName) : string
Inherited

Parameters

$from

string

The tokens that should not occur

$to

string

The tokens that replace them

$fieldName

string

Name of database field to use

Returns

string

_scanForms()

_scanForms() 

This helper function updates the surveys in the gems_surveys table that no longer exist in in the source and returns a list of their names.

_updateGemsSurveyExists(array $surveyorSids, integer $userId) : array
Inherited

Parameters

$surveyorSids

array

The gsu_surveyor_id's that ARE in the source

$userId

integer

Id of the user who takes the action (for logging)

Returns

arrayThe names of the surveys that no longer exist

Updates this source, both in the database and in memory.

_updateSource(array $values, integer $userId) : integer
Inherited

Parameters

$values

array

The values that this source should be set to

$userId

integer

The current user

Returns

integer1 if data changed, 0 otherwise

Adds database (if needed) and tablename prefix to the table name

addDatabasePrefix(\return $tableName, boolean $addDatabaseName = true) : string
Inherited

Parameters

$tableName

\return

$addDatabaseName

boolean

Optional, when true (= default) and there is a database name then it is prepended to the name.

Returns

string

Extract limit and offset from the filter and add it to a select

filterLimitOffset(array $filter, \Zend_Db_Select $select) 
Inherited

Parameters

$filter

array

$select

\Zend_Db_Select

getBaseUrl()

getBaseUrl() : string
Inherited

Returns

stringBase url for source

Returns all info from the Gems surveys table for a givens Gems Survey Id

getSurveyData(integer $surveyId, string $field = null) : array
Inherited

Uses internal caching to prevent multiple db lookups during a program run (so no caching beyond page generation time)

Parameters

$surveyId

integer

$field

string

Optional field to retrieve data for

Returns

array

Updates the gems__tokens table so all tokens stick to the (possibly) new token name rules.

updateTokens(integer $userId, $updateTokens = true) : integer
Inherited

Parameters

$userId

integer

Id of the user who takes the action (for logging)

$updateTokens

Returns

integerThe number of tokens changed

Returns the source surveyId for a given Gems survey Id

_getSid(\type $surveyId) : \type

Parameters

$surveyId

\type

Returns

\type

 Properties

 

This holds the path to the location where OpenRosa will store it's files.

$baseDir : string

Default

Will be set on init to: GEMS_ROOT_DIR . '/var/uploads/openrosa/';

 

This holds the path to the location where the form definitions will be stored.

$formDir : string

Default

 

$loader

$loader : \Gems_Loader

Default

 

$project

$project : \Gems_Project_ProjectSettings

Default

 

$tracker

$tracker : \Gems_Tracker

Default

 

$translate

$translate : \Zend_Translate

Default

 

Holds the current batch if there is any

$_gemsDb : \Gems_Task_TaskRunnerBatch: \Zend_Db_Adapter_Abstract

Default

 

The information from the gems__sources for this source

$_sourceData : array

Default

 

The database connection to the source, usedable by all implementations that use a database

$_sourceDb : \Zend_Db_Adapter_Abstract

Default