Skip to end of metadata
Go to start of metadata

5.5.3 Features and changes

General 

Extra info


General

[W701] Added extra API functions to search for interviews globally by telephone/mail

On the survey properties in Supervisor, there's a way to specify in which questions the telephone number and/or email address are stored:

In supervisor, there's a global ‘find interview’, with the ability to look for an email address or telephone number in all surveys:

The user needs sufficient permissions to delete/modify the interviews for the selected surveys. 

 

Extra notes:

CCA Settings for the superviser cca api url should contain the server ip/name & not localhost.

Both Email address & telephone number need to be linked with an open question in order to work.

 

 

[W773] Added support for several extra API functions for AskiaFace integration (to replace AskiaFieldAPI.ocx)

AskiaFace users (module=AskiaFace): 

  • GET /SurveyTasks/{id}/Content 

  • Returns a datatoken. The datatoken can be used in {{url}}/files/requests/37c3f1c7-e1eb-9e63-a457-7a6644f3cf86/download 

  • GET /SurveyTasks/{id}/Survey/XML 

  • GET /SurveyTasks/{id}/Resources 

  • GET /SurveyTasks/{id}/Resources/{rid} 

  • GET /SurveyTasks/{id}/Interviews?format=1 (or for a datfile -> format=0 or format=DatFile) 

  • PUT /SurveyTasks/{id}/Interviews 

  

Surveys 

1/ Get the list of all surveys attached to the Agent 

GET /Clients/Face/SurveyTasks 

(the agent is specified through the session, which is sent through the HTTP header) 

(the based is based on the data sent back to Win32 AskiaFace – LSTSUR command) 

[ 

  { 

    "id": 123, 

    "name": "survey name", 

    "capiGroups": ["id": 456, "name": "capi1" }], 

    "progressionType": 1, 

    "revisionId": 666, 

    "revisionDate": "2019-06-19T12:12:12.000Z", 

    "newSeed": 1, 

    "checksum": 123456789, 

    "quota": { 

      "IncludeRunning": true, 

      "SingleTarget": false, 

      "InterviewQuotaType": 1, à interview/session/live 

      "Revision": 123, 

      "MinTarget": 100, 

      "MaxTarget": 200, 

      "Completed": 64, 

      "AllocationType": 1, à survey/agent 

      "Questions": [ 

        { 

          "Token": 1, 

          "Type": 1, à single/multiple/numeric 

          "Code": 1, 

          "Responses": [ 

            "Token": 2, 

            "Priority": 3, 

            "AllowOverQuota": 1, à survey/agent/never 

            "Type": 1, à group/numeric_range/closed_response 

            "Name": "", à only for groups 

            "Code": 123, 

            "RangeMin": "", à only for ranges 

            "RangeMax": "", à only for ranges 

            "MinTarget": 100, 

            "MaxTarget": 200, 

            "Completed": 64, 

            "Questions": … ], 

            "Responses": [ … ] à only for groups 

          ] 

        } 

      ] 

    } 

  } 

] 

  

2/ Get the XML, embedded in json, of a survey: 

GET /SurveyTasks/{id}/Survey/XML 

Depending on the HTTP Accept header we’ll either return XML (text/xml) or XML wrapped in JSON (application/json). 

  

  

Resources 

  

1/ Get a list of resources: 

GET /SurveyTasks/{id}/Resources 

 [ 

{ 

"id": 123, 

"name": "file.png", 

"checksum": 123456789 

},  

{ 

"id": 456, 

"name": "file2.png", 

"checksum": 0987654321 

} 

] 

  

2/ Get a resource 

GET /SurveyTasks/{id}/Resources/{resourceId} 

Also note that this request will return a datatoken, which can then be downloaded using the /Files controller 

  

  

Interviews 

  

Add/update an existing interview 

PUT /SurveyTasks/{id}/Interviews 

If Content-Type is application/octet-stream, the data should be in DAT format 

If Content-Type is text/xml, the data should be in XML format  

Note that this will update an existing interview based on the GUID in the XML, or add a new interview if it doesn’t exist 
We use the GUID instead of the interview ID to allow an update of an interview created earlier by the same client, for which the client can’t know the interview ID 
We don’t use the seed because it isn’t guaranteed to be unique


[W774] Added support for several extra API functions for CodeIT integration

To retrieve the survey structure 

  • GET /SurveyTasks/123/Survey 

This will retrieve the entire survey, as described in AskiaCore. 

  

The response is identical to the current survey embedded in GET /SurveyTasks/123/Quota: 

{ 

    "Categories": [ 

      { 

        "CreatedAt": "2019-05-04T07:42:09.0481976+02:00", 

        "CreatedBy": 2, 

        "DeletedAt": "2019-05-04T07:42:09.0481976+02:00", 

        "DeletedBy": 4, 

        "Id": 5, 

        "LastError": "sample string 6", 

        "Name": "sample string 7", 

        "UpdatedAt": "2019-05-04T07:42:09.0481976+02:00", 

        "UpdatedBy": 9 

     }, 

      { 

        ... 

      } 

    ], 

    "CreatedAt": "2019-05-04T07:42:09.0481976+02:00", 

    "CreatedBy": 2, 

    "DefaultLanguageId": 3, 

    "DeletedAt": "2019-05-04T07:42:09.0481976+02:00", 

    "DeletedBy": 5, 

    "Description": "sample string 6", 

    "Id": 7, 

    "Languages": [ 

      { 

        "Id": 1, 

        "LocaleName": "sample string 2" 

      }, 

      { 

        "Id": 1, 

        "LocaleName": "sample string 2" 

      } 

    ], 

    "LastError": "sample string 8", 

    "Name": "sample string 9", 

    "PortalId": 10, 

    "Questions": [ 

      { 

        "AllowsNoResponses": true, 

        "Categories": [ 

          { 

            "CreatedAt": "2019-05-04T07:42:09.0481976+02:00", 

            "CreatedBy": 2, 

            "DeletedAt": "2019-05-04T07:42:09.0481976+02:00", 

            "DeletedBy": 4, 

            "Id": 5, 

            "LastError": "sample string 6", 

            "Name": "sample string 7", 

            "UpdatedAt": "2019-05-04T07:42:09.0481976+02:00", 

            "UpdatedBy": 9 

          }, 

          { 

            ... 

          } 

        ], 

        "ClosedImportationType": 0, 

        "CreatedAt": "2019-05-04T07:42:09.0638223+02:00", 

        "CreatedBy": 3, 

        "DecimalPrecision": 4, 

        "DeletedAt": "2019-05-04T07:42:09.0638223+02:00", 

        "DeletedBy": 6, 

        "IVRNumber": "sample string 7", 

        "Id": 8, 

        "ImportationBase": "sample string 9", 

        "ImportationString": "sample string 10", 

        "ImportationType": 0, 

        "IsExcludedFromTranslation": true, 

        "IsLevelDeveloped": true, 

        "IsLevelLinked": true, 

        "IsProbability": true, 

        "IsRanked": true, 

        "IsRecordable": true, 

        "IsScaled": true, 

        "IsVisibleInAnalyse": true, 

        "LastError": {}, 

        "LinkType": 0, 

        "LinkedQuestionId": 20, 

        "MaxResponseCount": 21, 

        "MaxValue": 22.1, 

        "MinResponseCount": 23, 

        "MinValue": 24.1, 

        "NoResponseEntry": "sample string 25", 

        "ParentId": 26, 

        "Pattern": "sample string 27", 

        "Position": 28, 

        "QuestionIdToIncrement": 29, 

        "Responses": [ 

          { 

            "BaseType": 0, 

            "CreatedAt": "2019-05-04T07:42:09.0638223+02:00", 

            "CreatedBy": 2, 

            "DeletedAt": "2019-05-04T07:42:09.0638223+02:00", 

            "DeletedBy": 4, 

            "EntryCode": "sample string 5", 

            "Factor": 1.1, 

            "Id": 6, 

            "IsExcludedFromTranslation": true, 

            "IsExclusive": true, 

            "IsSelectable": true, 

            "LastError": {}, 

            "ParentId": 11, 

            "Position": 12, 

            "QuestionId": 13, 

            "ResourceId": 14, 

            "RotationBehaviour": 0, 

            "SemiOpenQuestionId": 15, 

            "Type": 0, 

            "UpdatedAt": "2019-05-04T07:42:09.0638223+02:00", 

            "UpdatedBy": 17, 

            "UserData": "sample string 18" 

          }, 

          { 

            ... 

          } 

        ], 

        "RotationSeed": 30, 

        "RotationType": 0, 

        "Shortcut": "sample string 31", 

        "Type": 0, 

        "UpdatedAt": "2019-05-04T07:42:09.0638223+02:00", 

        "UpdatedBy": 33, 

        "UserData": "sample string 34", 

        "Visibility": 0 

      }, 

      { 

        ... 

      } 

    ], 

    "UpdatedAt": "2019-05-04T07:42:09.0638223+02:00", 

    "UpdatedBy": 12, 

    "Version": "sample string 13" 

  } 

  

  • GET /SurveyTasks/123/Survey/Questions 

This will retrieve a simplified list of questions 

  

Response: 

[ 

  { 

    "Id": 8, 

    "Shortcut": "sample string 31", 

    "Type": 0 

  }, 

  { 

    ... 

  } 

] 

  

  • GET /SurveysTasks/123/Survey/Questions/456 

This will retrieve the full question details, including the responses. 

The response is a subset to one question from the full survey above, EXCEPT for the added properties for the question/response captions: 

{ 

  "AllowsNoResponses": true, 

  "AnalyseCaption": "sample string 1", 

  "Id": 2, 

  "LinkType": 0, 

  "LinkedQuestionId": 1, 

  "LocalizedAnalyseCaptions": { 

    "1": "sample string 2", 

    "3": "sample string 4" 

  }, 

  "LocalizedMainCaptions": { 

    "1": "sample string 2", 

    "3": "sample string 4" 

  }, 

  "MainCaption": "sample string 3", 

  "MaxResponseCount": 1, 

  "ParentId": 4, 

  "Responses": [ 

    { 

      "EntryCode": "sample string 1", 

      "Id": 2, 

      "IsExclusive": true, 

      "LocalizedMainCaptions": { 

        "1": "sample string 2", 

        "3": "sample string 4" 

      }, 

      "MainCaption": "sample string 4", 

      "RotationBehaviour": 0 

    }, 

    { 

      "EntryCode": "sample string 1", 

      "Id": 2, 

      "IsExclusive": true, 

      "LocalizedMainCaptions": { 

        "1": "sample string 2", 

        "3": "sample string 4" 

      }, 

      "MainCaption": "sample string 4", 

      "RotationBehaviour": 0 

    } 

  ], 

  "Shortcut": "sample string 5", 

  "Type": 0, 

  "Visibility": 0 

} 

  

To update the survey structure 

  • PUT /SurveyTasks/123/Survey/Questions/456 

This will update the full question – including the responses. 
Note that missing data is NOT removed. 
This isn’t entirely RESTful, but it’s consistent with the current behaviour of PUT /SurveyTask/123 (which also only updates the included properties) 

This function will use CQuestion::FromXML, so I think all question properties (and all response properies) should be accessible. 

  

The request data is identical to the GET /SurveyTasks/123/Survey/Questions/456 request. 

Note that the response code for non-existing responses will be ignored 
  
Response should indicate (at least) the IDs of added responses – or the full question Pagina-einde  

To retrieve bulk interview data 

  • GET /SurveyTasks/123/Interviews?questionId=1&questionId=2& after=2019-01-01T00:00:00.000&before=2019-12-31T23:59:59.999 

This will return interview data for the specified questions CREATED between after and before. 

(all date/times are in UTC) 
[ 

  { 

    "interviewId": 123, 

    "interviewGuid": "5b14789b-7483-4a4f-9628-56557722e043", 

    "startTimeUTC": "2019-02-03T00:01:02.123", 

    "startTimeUTCOffset": 3600, 

    "endTimeUTC": "2019-02-03T00:01:02.123", 

    "endTimeUTCOffset": 3600, 

    "responses": [ 

      { 

        "questionId": 100, 

        "loopItemIds": [101, 102], 

        "data": "response data", 

      }, 

      … 

    ] 

  }, 

  … 

] 

  

To update interview data 

  • PUT /SurveyTasks/123/Interviews/1 

This will update only the specified responses for the interview 

{ 

  "responses": [ 

    { 

      "questionId": 100, 

      "loopItemIds": [101, 102], 

      "data": "response data", 

    }, 

    … 

  ] 

} 


[W878] Added support for extra API function to add auditing event on accessing encrypted data externally

When survey data is accessed by interview (through modify interview, or the API), a record is already added to statistic_SupervisorActions (Action = Task_GetInterviewData). 

  

Similarly, when survey data is accessed by question, a record will be added in the statistic_SupervisorActions table: 

  • ObjectType = survey 

  • ObjectID = survey ID 

  • Action = Task_GetQuestionData (new enum value) 

  • ActionData = XML: 

  • <Details QuestionID=”123” ManualAction=”true QuestionEncrypted=”true”> 

<Comment>…</Comment> 

</Details> 

  • ManualAction indicates whether the record was created manually (through the API), or by CCA 

  • QuestionEncrypted indicates whether the question data is encrypted 

  

On the CcaAPI 2 extra functions will be added to generate these statistics: 

  • Service.AddSupervisorActionGetSurveyInterviewData(surveyIdinterviewId, comment) 

  • Service.AddSupervisorActionGetSurveyQuestionData(surveyIdquestionId, comment) 

  

On the CcaWebAPI these extra functions will be added: 

  • POST /SurveyTasks/{surveyId}/SupervisorActions/GetInterviewData 

{ 

interviewId: 123, 

comment: “xxx” 

} 

  • POST /SurveyTasks/{surveyId}/SupervisorActions/GetQuestionData 

{ 

questionId: 123, 

comment: “xxx” 

} 

  

CCA checks whether the user has the permission to view the task 

 

[W879] Added support for extra API function to add auditing event on modifying data externally

When an interview is modified, a record will be added in the statistic_SupervisorActions table: 

  • ObjectType = survey => ID 71 

  • ObjectID = survey ID 

  • Action = Task_UpdateInterviews (renamed from existing Task_UpdateInterview enum value from modify interview on Supervisor) => ID 205 

  • ActionData = XML: 

  • <Details InterviewIDs=”123,456 ManualAction=”true> 

<Comment>…</Comment> 

</Details> 

  • ManualAction indicates whether the record was created manually (through the API), or by CCA 

  • Note: the current Task_UpdateInterview will be updated to allow multiple interview IDs and a comment 


When an interview is deleted, a record will be added in the statistic_SupervisorActions table: 

  • ObjectType = survey => ID 71 

  • ObjectID = survey ID 

  • Action = Task_DeleteInterviews (existing enum value from modify interview on Supervisor) => ID 208 

  • ActionData = XML: 

  • <Details InterviewID=”123” ManualAction=”true”> 

<Comment>…</Comment> 

</Details> 

  • ManualAction indicates whether the record was created manually (through the API), or by CCA 

Currently there are 2 different actions: Task_DeleteInterview and Task_DeleteInterviews. These 2 will be merged in the latter (Task_DeleteInterviews) 

  

On the CcaAPI 2 extra functions will be added to generate these statistics: 

  • Service.AddSupervisorActionUpdateSurveyInterviews(surveyIdinterviewIds[], comment) 

  • Service.AddSupervisorActionDeleteSurveyInterviews(surveyIdinterviewIds[], comment) 

  

On the CcaWebAPI these extra functions will be added: 

  • POST /SurveyTasks/{surveyId}/SupervisorActions/UpdateInterviews 

Example body: { "interviewId": 123, "comment": "xxx" }

  • POST /SurveyTasks/{surveyId}/SupervisorActions/DeleteInterviews 

Example body: { "interviewId": 123, "comment": "xxx" }

  

CCA checks whether the user has the permission to view the task 

[W503] Connect to SMTP via TLS

In the Mailing configuration you can now use TLS servers:

[W1044] Added option to disable schedules when duplicating a list

A new CCA Setting is added:

This setting is set by default on 'No'.

When duplicating a list, the schedules on the copied list will be disabled or enabled, depending on the cca setting.

 

 

[W789] Added extra statistics when sending mails

Statistic_Mail table is added to the statistics database where we store all the relevant information for the emailing done through Cca. 

That will concern: 

  • Emailing on list (invitation and reminders, manual mailing (from find/edit contact). 

  • Emailing made with the ‘send email’ routing in interview 

  • Emailing made from Askiaclient (for switch mode). 

Note: ‘internal’ emails, like notification mails on schedules, are not included. 

  

This table contains this information: 

  • Email address 

  • Survey ID 

  • List ID 

  • Contact ID 

  • Type of mailing 

  •     Send test email from list properties > Type = -3 

  •     Send email askiadesign routing from Cati > type = -2 

  •     Send email askiadesign routing from Web > type = -1 

  •     Send email from cca, supervisor eg invitation mail, reminder >= 0 (their own mailing type) 

  • Datetime of mailing (UTC) 

  • Smtp used 

  • Sender 

  • Subject 

  • MailResult 

  • BouncedTime 

  • BouncedReason 

  • BouncedMail 

  • Cc 

  • Bcc 

  • ReplyTo 

Extra info

Known issue: AskiaClient 5.5.3 does not work for CATISync in HABE Project.

  • No labels