Viedoc WCF API

  • Published by Viedoc System 2023-10-09
  • Print

Introduction

This document contains information on connecting your development environment or any other system to the Viedoc public web service using the Windows Communication Foundation (WCF) standards.

The Viedoc public Application Programming Interface (API) is a Simple Object Access Protocol (SOAP) over a Hypertext Transfer Protocol (HTTP) service. The API can be reached at: https://[VIEDOC_HOST]/HelipadService.svc

A wsdl metadata file can be downloaded from: https://[VIEDOC_HOST]/HelipadService.svc?wsdl
For example:

https://v4api.viedoc.net/HelipadService.svc?wsdl
https://v4apitraining.viedoc.net/HelipadService.svc?wsdl

Contact Viedoc Technologies for information about which host to connect to.

Methods

Token

Description

The Token method is used for authenticating the client. This method must be called to receive a token for authenticating all subsequent requests.

To authenticate the client, the following must be provided:

  • An active Client ID, a client ID (GUID) linked to a specific study in Viedoc. The client ID is linked to either the demo or the production study.

  • A Viedoc user name and password. To submit data into Viedoc, you need access to the study in Viedoc and to the study site with a role that allows data entry.

Note! You can only access the API configuration window and create an API client ID if you are assigned the role API Manager. All the pending role invitations for a user are automatically approved when the Token/GetToken method is used.

For information about how to obtain a client ID, see API configuration.

C# Syntax

ApiTokenModel tokenModel = Token(ApiAuthenticationModel loginModel);

Parameters

The Token method has the following parameters:

Parameter Data type Description
loginModel ApiAuthenticationModel A collection of authentication information.
See section 3.1 ApiAuthenticationModel for a description.

Returns

The Token method returns an ApiTokenModel object that has the following properties:

Property Data type Description
Token string A new authentication token that can be used for authentication in subsequent requests
Result ApiResultType Defines the type and status of the result returned from method invocation. See section 3.2 ApiResultType for details
ErrorCode int In case of an error result: contains an integer specifying the type of error. See section 4 Error codes for details.
ErrorMessage string In case of an error result: human readable description of the error
ExpiryDateTime DateTime Token expiration date and time

Example HTTP call

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:vied="Viedoc.API" xmlns:vied1="http://schemas.datacontract.org/2004/07/Viedoc.Services.Public">

<soapenv:Header/>

<soapenv:Body>

<vied:Token>

<vied:loginModel>

<vied1:ClientGuid>f4680c73-f936-48be-bf5e-560f05af640c</vied1:ClientGuid>

<vied1:UserName>[USERNAME]</vied1:UserName>

<vied1:Password>[PASSWORD]</vied1:Password>

<vied1:TimeSpanInSeconds>180</vied1:TimeSpanInSeconds>

</vied:loginModel>

</vied:Token>

</soapenv:Body>

</soapenv:Envelope>

Example HTTP response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">

<s:Body>

<TokenResponse xmlns="Viedoc.API">

<TokenResult xmlns:a="http://schemas.datacontract.org/2004/07/Viedoc.Services.Public" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

<a:Token>C8AD03E3C4...4A23A01E59</a:Token>

<a:Result>Success</a:Result>

<a:ErrorCode>0</a:ErrorCode>

<a:ErrorMessage i:nil="true"/>

<a:ExpiryDateTime>2017-01-17T15:50:14.6564955+00:00</a:ExpiryDateTime>

</TokenResult>

</TokenResponse>

</s:Body>

</s:Envelope>

GetToken

Description

For a description of the GetToken method, see the description of the Token method in section 2.1 Token.

C# Syntax

ApiTokenModel GetToken(Guid ClientGuid, string UserName, string password,
int timeSpanInSeconds);

Parameters

The GetToken method has the following parameters:

Parameter Data type Description
ClientGuid ApiAuthenticationModel Client ID linked to a specific study in Viedoc.
Can be obtained from Viedoc Admin. Required.
UserName string Viedoc login username. Required.
Password string Matching Viedoc login password. Required.
TimeSpanInSeconds int Time (in seconds) that the authentication token will be valid for. Optional.
Default is 300 seconds (5 min). Maximum is 1800 seconds (30 min).

Returns

For a list of the returns of the GetToken method, see the returns of the Token method as described in section 2.1.4 Returns.

SubmitData

Description

The SubmitData method can be used for submitting data into Viedoc.

C# Syntax

ApiSubmitResultModel SubmitData(string token, string odmXml,

ApiSubmitDataOptions options = null);

Parameters

The SubmitData method has the following parameters:

Parameter Data type Description
token string Authentication token. Can be obtained by invoking the Token method with client ID, username, and password.
odmXml string The data to be uploaded in ODM format
options ApiSubmitDataOptions Submit data options. Optional. See section 3.3 ApiSubmitDataOptions.

Returns

The SubmitData method returns an ApiSubmitResultModel object that has the following properties:

Property Data type Description
Token string A new authentication token that can be used for authentication in subsequent requests
Result ApiResultType Defines the type and status of the result returned from method invocation. See the section 3.2 ApiResultType for details.
ErrorCode int In case of an error result: contains an integer specifying the type of error. See section 4 Error codes for details.
ErrorMessage string In case of an error result: human readable description of the error
TransactionGuid GUID A GUID assigned to the transaction that can be used to identify the transaction in future requests, for example when invoking TransactionStatus or TransactionData. Every single call to the SubmitData method will be assigned one transaction GUID, irrespective of how many subjects or data points are uploaded.

Example call

Note! To access the example call as a text that you can copy into your tool, click here.

Number Item Description
1 MetaDataVersionOID [Version].[Revision] of the metadata that will be used for the imported data
2 SubjectKey Subject key in Viedoc for the subject that the data will be imported to
3 LocationOID Study site ID, can be obtained from VIedoc Admin
4

StudyEventOID

FormOID

ItemOID

Event, form, or item Object Identifiers (OIDs), can be obtained from an exported metadata version or from Viedoc Designer

Note! If the StudyEvent repeats, a StudyEventRepeatKey should be given. For example:
<StudyEventData StudyEventOID="AE" StudyEventRepeatKey="1">
5 ItemDataInteger Allowed data value types are:
  • ItemDataString
  • ItemDataInteger
  • ItemDataDouble
  • ItemDataDateTime*
  • ItemDataDate
  • ItemDataTime

* CRF variables that collect time data have no container for time zone in Viedoc. Data in such variables is typically regarded to represent time in the same time zone as where the study site is located. Thus, it is recommended to submit time data without the time zone information, for example 2020-01-29T08:34:00. If time zone is of interest, for example if a blood sample was analyzed in a lab located in a different time zone, an additional CRF variable can be used to collect that information. When time zone information is submitted to Viedoc through the API (or the import application) as part of a data value, it will be factored into the data value. This is due to the fact that Viedoc has no place to store it. For example, 2000-01-01T00:00:00+01:00 (1 hour offset) will be converted to 1999-12-31T23:00:00Z (no offset) and will be visible in the CRF as 1999-12-31 23:00. For this reason, it is advisable to take care of any conversions required to get rid of time zone information before you submit time data to Viedoc.

Example response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">

<s:Body>

<SubmitDataResponse xmlns="Viedoc.API">

<SubmitDataResult xmlns:a="http://schemas.datacontract.org/2004/07/Viedoc.Services.Public" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

<a:Token>77D5F18B4D...81066FCCB3</a:Token>

<a:Result>Pending</a:Result>

<a:ErrorCode>0</a:ErrorCode>

<a:ErrorMessage i:nil="true"/>

<a:TransactionGuid>b9d315b1-adb7-4eb2-93d7-f43c682aec9a</a:TransactionGuid>

</SubmitDataResult>

</SubmitDataResponse>

</s:Body>

</s:Envelope>

TransactionStatus

Description

The TransactionStatus method can be used to check the import status of previously submitted data.

C# Syntax

ApiResultModel resultModel = TransactionStatus(string token, GUID transactionGUID);

Parameters

The TransactionStatus method has the following parameters:

Parameter Data type Description
token string Authentication token
transactionGUID GUID The transaction GUID obtained when invoking the SubmitData method

Returns

The TransactionStatus method returns an ApiResultModel object that has the following properties:

Property Data type Description
Token string A new authentication token that can be used for authentication in subsequent requests
Result ApiResultType Defines the type and status of the result returned from method invocation. See section 3.2 ApiResultType for details.
ErrorCode int In case of an error result: contains an integer specifying the type of error. See section 4 Error codes for details.
ErrorMessage string In case of an error result: human readable description of the error

Example call

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:vied="Viedoc.API">

<soapenv:Header/>

<soapenv:Body>

<vied:TransactionStatus>

<vied:token>0D8D295A92...F019C59CE1</vied:token>

<vied:transactionGuid>b9d315b1-adb7-4eb2-93d7-f43c682aec9a</vied:transactionGuid>

</vied:TransactionStatus>

</soapenv:Body>

</soapenv:Envelope>

Example response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">

<s:Body>

<TransactionStatusResponse xmlns="Viedoc.API">

<TransactionStatusResult xmlns:a="http://schemas.datacontract.org/2004/07/Viedoc.Services.Public" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

<a:Token>910F3E7984...8F25E0B4C1C</a:Token>

<a:Result>Success</a:Result>

<a:ErrorCode>0</a:ErrorCode>

<a:ErrorMessage i:nil="true"/>

</TransactionStatusResult>

</TransactionStatusResponse>

</s:Body>

</s:Envelope>

TransactionData

Description

The TransactionData method can be used to obtain previously submitted data.

C# Syntax

ApiTransactionDataModel dataModel = TransactionData(string token, GUID transactionGUID);

Parameters

The TransactionData method has the following parameters:

Parameter Data type Description
token string Authentication token
transactionGUID GUID GUID obtained when invoking the SubmitData method

Returns

The TransactionData method returns an ApiTransactionDataModel object that has the following properties:

Property Data type Description
Token string A new authentication token that can be used for authentication in subsequent requests
Result ApiResultType Defines the type and status of the result returned from method invocation. See section 3.2 ApiResultType for details.
ErrorCode int In case of an error result: contains an integer specifying the type of error. See section 4 Error codes for details.
ErrorMessage string In case of an error result: human readable description of the error
OdmXml string The uploaded data in ODM format

Example call

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:vied="Viedoc.API">

<soapenv:Header/>

<soapenv:Body>

<vied:TransactionData>

<vied:token>0D8D295A92...F019C59CE1</vied:token>

<vied:transactionGuid>b9d315b1-adb7-4eb2-93d7-f43c682aec9a</vied:transactionGuid>

</vied:TransactionData>

</soapenv:Body>

</soapenv:Envelope>

Example response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">

<s:Body>

<TransactionDataResponse xmlns="Viedoc.API">

<TransactionDataResult xmlns:a="http://schemas.datacontract.org/2004/07/Viedoc.Services.Public" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

<a:Token>78EE476F86...C8235F79326</a:Token>

<a:Result>Success</a:Result>

<a:ErrorCode>0</a:ErrorCode>

<a:ErrorMessage i:nil="true"/>

<a:OdmXml><![CDATA[<ODM>

<ClinicalData MetaDataVersionOID="12.0">

<SubjectData SubjectKey="SE-AHU-006">

<SiteRef LocationOID="AHU" />

<StudyEventData StudyEventOID="V1">

<FormData FormOID="$EVENT">

<ItemGroupData ItemGroupOID="EventDateGroup">

<ItemDataDate ItemOID="EventDate">2016-10-02</ItemDataDate>

</ItemGroupData>

</FormData>

<FormData FormOID="VS" FormRepeatKey="V1">

<ItemGroupData ItemGroupOID="VSG1">

<ItemDataDateTime ItemOID="VSDT">2017-01-03T00:00</ItemDataDateTime>

<ItemDataInteger ItemOID="VSYN">1</ItemDataInteger>

</ItemGroupData>

<ItemGroupData ItemGroupOID="VSG6">

<ItemDataDouble ItemOID="VSDIA">75</ItemDataDouble>

<ItemDataDouble ItemOID="VSSYS">120</ItemDataDouble>

</ItemGroupData>

<ItemGroupData ItemGroupOID="VSG9">

<ItemDataDouble ItemOID="VSPULSE">80</ItemDataDouble>

</ItemGroupData>

</FormData>

</StudyEventData>

</SubjectData>

<AuditRecords />

</ClinicalData> </ODM >]]></a:OdmXml>

</TransactionDataResult>

</TransactionDataResponse>

</s:Body>

</s:Envelope>

GetMetaData

Description

The GetMetaData method can be used to get any study metadata version in ODM format.

C# Syntax

ApiGetMetaDataResultModel metaDataResultModel = GetMetaData(string token, string metaDataOid, bool includeSdm, bool includeViedocExtensions);

Parameters

The GetMetaData method has the following parameters:

Parameter Data type Description
token string Authentication token
metaDataOid string Metadata OID in the format:
[Version]. [Revision]. For example, 1.1 means version 1 and revision 1. The metadata OID can be obtained from Viedoc Admin or Designer.
includeSdm bool Defines whether Study Design Model (SDM) properties should be included in the exported metadata ODM file. Can be set to true or false, default is set to false.
includeViedocExtensions bool Defines whether Viedoc-specific extension properties should be included in the exported metadata ODM file. Can be set to true or false, default is set to false.

Returns

The GetMetaData method returns an ApiGetMetaDataResultModel object that has the following properties:

Property Data type Description
Token string A new authentication token that can be used for authentication in subsequent requests
Result ApiResultType Defines the type and status of the result returned from method invocation. See section 3.2 ApiResultType for details.
ErrorCode int In case of an error result: contains an integer specifying the type of error. See section 4 Error codes for details.
ErrorMessage string In case of an error result: human readable description of the error
OdmXml string ODM including the requested metadata version in the study

Example call

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:vied="Viedoc.API">

<soapenv:Header/>

<soapenv:Body>

<vied:GetMetaData>

<vied:token>3C5C012B4A...4AA6982B94</vied:token>

<vied:metaDataOid>12.0</vied:metaDataOid>

<vied:includeSdm>true</vied:includeSdm>

<vied:includeViedocExtensions>true</vied:includeViedocExtensions>

</vied:GetMetaData>

</soapenv:Body>

</soapenv:Envelope>

Example response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">

<s:Body>

<GetMetaDataResponse xmlns="Viedoc.API">

<GetMetaDataResult xmlns:a="http://schemas.datacontract.org/2004/07/Viedoc.Services.Public" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

<a:Token>65E6DF0A0B...26FDB77A85</a:Token>

<a:Result>Success</a:Result>

<a:ErrorCode>0</a:ErrorCode>

<a:ErrorMessage i:nil="true"/>

<a:OdmXml><![CDATA[<?xml version="1.0"?>

<ODM xmlns:sdm="http://www.cdisc.org/ns/studydesign/v1.0" xmlns:v4="http://www.viedoc.net/ns/v4" SourceSystemVersion="4.32.6226.25712" SourceSystem="VIEDOC" Originator="PCG Solutions AB" ODMVersion="1.3" AsOfDateTime="2017-01-18T12:49:44.503Z" FileOID="" Granularity="Metadata" FileType="Snapshot" Description="Demo study 2016" CreationDateTime="2016-10-05T08:48:41" v4:ModifiedSystemVersion="4.32" xmlns="http://www.cdisc.org/ns/odm/v1.3">

<Study OID="369cbf09-3322-43cc-b0ef-895be23bead0">

<GlobalVariables>

<StudyName>Demo study 2016</StudyName>

<StudyDescription>An open-label, multi center, dose escalation study investigating the...</StudyDescription>

...

</GlobalVariables>

<BasicDefinitions>

...

</BasicDefinitions>

<MetaDataVersion OID="12.0" Name="1" Description="Demo study 2016">

...

</MetaDataVersion<>

</Study>

</ODM>]]>/a:OdmXml>

</GetMetaDataResult>

</GetMetaDataResponse>

</s:Body>

</s:Envelope>

GetMetaDataVersionForKeySets

Description

The GetMetaDataVersionForKeySets method can be used to get the study design version(s) (metadata version) for a set of data point(s).

C# Syntax

ApiGetMetaDataVersionsResultModel GetMetaDataVersionsForKeySets(string token, List<ViedocKeySet> keySets)

Parameters

The GetMetaDataVersionForKeySets method has the following parameters:

Parameter Data type Description
token string Authentication token
keySets List<ViedocKeySet> Contains a list of keysets for which study design (metadata) version should be fetched.
All the individual keys in a keyset are optional and the returned study design version will be based on all the keys specified. See section 3.4 ViedocKeySet.

Returns

The GetMetaDataVersionForKeySets method returns an ApiGetMetaDataVersionsResultModel object that has the following properties:

Property Data type Description
Token string A new authentication token that can be used for authentication in subsequent requests
Result ApiResultType Defines the type and status of the result returned from method invocation. See section 3.2 ApiResultType for details.
ErrorCode int In case of an error result: contains an integer specifying the type of error. See section 4 Error codes for details.
ErrorMessage string In case of an error result: human readable description of the error
KeySets List<ViedocKeySet> ODM including the requested metadata version in the study

Example HTTP call

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:vied="Viedoc.API" xmlns:vied1="http://schemas.datacontract.org/2004/07/Viedoc.Services.Public">

<soapenv:Header/>

<soapenv:Body>

<vied:GetMetaDataVersionsForKeySets>

<vied:token>D188460837...6A04F67878</vied:token>

<vied:keySets>

<!--Zero or more repetitions:-->

<vied1:ViedocKeySet>

<vied1:uniqueId>1234</vied1:UniqueId>

<vied1:SubjectKey>SE-AHU-006</vied1:SubjectKey>

<vied1:CountryCode>SE</vied1:CountryCode>

<vied1:SiteCode>AHU</vied1:SiteCode>

<vied1:SiteNo>1</vied1:SiteNo>

<vied1:StudySubjectSqeNo>006</vied1:StudySubjectSeqNo>

<vied1:SiteSubjectSeqNo>006</vied1:SiteSubjectSeqNo>

<vied1:StudyEventDefId>V1</vied1:StudyEventDefId>

<vied1:FormDefId>VS</vied1:FormDefId>

<vied1:ItemDefId></vied1:ItemDefId>

<vied1:MetaDataVersionOID></vied1:MetaDataVersionOID>

</vied1:ViedocKeySet>

</vied:keySets>

</vied:GetMetaDataVersionsForKeySets>

</soapenv:Body>

</soapenv:Envelope>

Example response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">

<s:Body>

<GetMetaDataVersionsForKeySetsResponse xmlns="Viedoc.API">

<GetMetaDataVersionsForKeySetsResult xmlns:a="http://schemas.datacontract.org/2004/07/Viedoc.Services.Public" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

<a:Token>4E06BC9189...756CF1EA42</a:Token>

<a:Result>Success</a:Result>

<a:ErrorCode>0</a:ErrorCode>

<a:ErrorMessage i:nil="true"/>

<a:KeySet>

<a:ViedocKeySet>

<a:UniqueId>1234</a:UniqueId>

<a:SubjectKey>SE-AHU-006</a:SubjectKey>

<a:StudySiteId>13845</a:StudySiteId>

<a:CountryCode>SE</a:CountryCode>

<a:SiteCode>AHU</a:SiteCode>

<a:SiteNo>1</a:SiteNo>

<a:StudySubjectSeqNo>6</a:StudySubjectSeqNo>

<a:SiteSubjectSeqNo>6</a:SiteSubjectSeqNo>

<a:StudyEventDefId>V1</a:StudyEventDefId>

<a:StudyEventRepeatKey i:nil="true"/>

<a:EventDate>0001-01-01T00:00:00</a:EventDate>

<a:FormDefId>VS</a:FormDefId>

<a:FormRepeatKey i:nil="true"/>

<a:ItemDefId i:nil="true"/>

<a:MetaDataVersionOID>12.0</a:MetaDataVersionOID>

</a:ViedocKeySet>

</a:KeySet>

</GetMetaDataVersionsForKeySetsResult>

</GetMetaDataVersionsForKeySetsResponse>

</s:Body>

</s:Envelope>

GetClinicalStudySites

Description

The GetClinicalStudySites method returns information about the sites that a user has access to in Viedoc Clinic.

C# Syntax

ApiGetClinicalStudySitesResultModel GetClinicalStudySites(string token);

Parameters

The GetClinicalStudySites method has the following parameters:

Parameter Data type Description
token string Authentication token.

Returns

The GetClinicalStudySites method returns an ApiStudySiteModel object that has the following properties:

Property Data type Description
Country string The country name
CountryCode string Two-letter country code
ExpectedNumberOfSubjectsEnrolled int The expected number of enrolled subjects on site
ExpectedNumberOfSubjectsScreened int The expected number of screened subjects on site
MaximumNumberOfSubjectsScreened int The maximum number of screened subjects on site
Guid string Unique ID of the site
SiteCode string Site code as set in Admin
SiteName string Site name as set in Admin
SiteNumber int Site number
SiteType string Site type: Training or Production
TimeZone string The Windows time zone ID
TzOffset int The offset (in minutes) from UTC

Example HTTP call

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:vied="Viedoc.API">

<soapenv:Header/>

<soapenv:Body>

<vied:GetClinicalStudySites>

<vied:token>7C57A5F819...633211A5A2</vied:token>

</vied:GetClinicalStudySites>

</soapenv:Body>

</soapenv:Envelope>

Example HTTP response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">

<s:Body>

<Get ClinicalStudySitesResponse xmlns="Viedoc.API">

<GetClinicalStudySitesResult xmlns:a="http://schemas.datacontract.org/2004/07/Viedoc.Services.Public" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

<a:Token>BDE...930</a:Token>

<a:Result>Success</a:Result>

<a:ErrorCode>0</a:ErrorCode>

<a:ErrorMessage i:nil="true"/>

<a:StudySites>

<a:ApiStudySiteModel>

<a:Country>United States</a:Country>

<a:CountryCode>US</a:CountryCode>

<a:ExpectedNumberOfSubjectsEnrolled>75</a:ExpectedNumberOfSubjectsEnrolled>

<a:ExpectedNumberOfSubjectsScreened>100</a:ExpectedNumberOfSubjectsScreened>

<a:Guid>c57ffd6c-c279-11e9-b974-78c880284afa</a:Guid>

<a:MaximumNumberOfSubjectsScreened>120</a:MaximumNumberOfSubjectsScreened>

<a:SiteCode>01</a:SiteCode>

<a:SiteName>The Mayo Clinic</a:SiteName>

<a:SiteNumber>1</a:SiteNumber>

<a:SiteType>Training</a:SiteType>

 <a:TimeZone>Eastern Standard Time</a:TimeZone>

<a:TzOffset>300</a:TzOffset>

</a:ApiStudySiteModel>

<a:ApiStudySiteModel>

<a:Country>Singapore</a:Country>

<a:CountryCode>SG</a:CountryCode>

<a:ExpectedNumberOfSubjectsEnrolled>40</a:ExpectedNumberOfSubjectsEnrolled>

<a:ExpectedNumberOfSubjectsScreened>50</a:ExpectedNumberOfSubjectsScreened>

<a:Guid>c5800324-c279-11e9-b974-78c880284afa</a:Guid>

<a:MaximumNumberOfSubjectsScreened>60</a:MaximumNumberOfSubjectsScreened>

<a:SiteCode>02</a:SiteCode>

<a:SiteName>SingaporeGeneral Hospital</a:SiteName>

<a:SiteNumber>2</a:SiteNumber>

<a:SiteType>Training</a:SiteType>

<a:TimeZone>Singapore Standard Time</a:TimeZone>

<a:TzOffset>480</a:TzOffset>

</a:ApiStudySiteModel>

</a:StudySites>

</GetClinicalStudySitesResult>

</GetClinicalStudySitesResponse>

</s:Body>

</s:Envelope>

GetClinicalData

Description

The GetClinicalData method can be used for exporting clinical data in ODM format.

C# Syntax

ApiGetClinicalDataResultModel GetClinicalData(string token, ApiGetClinicalDataRequestModel options);

Parameters

The GetClinicalData method has the following parameters:

Parameter Data type Description
token string Authentication token
options ApiGetClinicalDataRequestModel Options and filters for clinical data export. See section 3.5 ApiGetClinicalDataRequestModel.

Returns

The GetClinicalData method returns an ApiGetClinicalDataResultModel object that has the following properties:

Property Data type Description
Token string A new authentication token that can be used for authentication in subsequent requests
Result ApiResultType Defines the type and status of the result returned from method invocation. An ApiResultType enum with the value Success or Error is used.
ErrorCode int In case of an error result: contains an integer specifying the type of error. See section 4 Error codes for details.
ErrorMessage string In case of an error result: human readable description of the error
OdmXml string The exported data in ODM format

Example HTTP call

Note! The order of the clauses is crucial. It is important to follow the order in the example code below.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:vied="Viedoc.API" xmlns:vied1="http://schemas.datacontract.org/2004/07/Viedoc.Services.Public">

<soapenv:Header/>

<soapenv:Body>

<vied:GetClinicalData>

<vied:token>2BB747D2E2...B46846DE34</vied:token>

<vied:options>

<vied1:SiteCode>AHU</vied1:SiteCode>

<vied1:SubjectFilter></vied1:SubjectFilter>

<vied1:SubjectKey>SE-AHU-006</vied1:SubjectKey>

<vied1:StudyEventOID>V1</vied1:StudyEventOID>

<vied1:FormOID>VS</vied1:FormOID>

<vied1:ItemOID>VSSYS</vied1:ItemOID>

<vied1:ExcludeExtensions>false</vied1:ExcludeExtensions>

<vied1:IncludeAdminData>true</vied1:IncludeAdminData>

<vied1:IncludeVisitDates>true</vied1:IncludeVisitDates>

<vied1:IncludeQueries>true</vied1:IncludeQueries>

<vied1:IncludeReviewStatus>true</vied1:IncludeReviewStatus>

<vied1:IncludeSignatures>true</vied1:IncludeSignatures>

<vied1:IncludeMedicalCoding>true</vied1:IncludeMedicalCoding>

<vied1:IncludeSubjectStatus>true</vied1:IncludeSubjectStatus>

</vied:options>

</vied:GetClinicalData>

</soapenv:Body>

</soapenv:Envelope>

Example HTTP response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">

<s:Body>

<GetClinicalDataResponse xmlns="Viedoc.API">

<GetClinicalDataResult xmlns:a="http://schemas.datacontract.org/2004/07/Viedoc.Services.Public" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

<a:Token>A53447308F...B9F6DB81BE</a:Token>

<a:Result>Success</a:Result>

<a:ErrorCode>0</a:ErrorCode>

<a:ErrorMessage i:nil="true"/>

<a:OdmXml><![CDATA[<?xml version="1.0"?>

<ODM xmlns:sdm="http://www.cdisc.org/ns/studydesign/v1.0" xmlns:v4="http://www.viedoc.net/ns/v4" FileType="Snapshot" v4:ModifiedSystemVersion="4.32" xmlns="http://www.cdisc.org/ns/odm/v1.3">

<Study OID="369cbf09-3322-43cc-b0ef-895be23bead0">

...

</Study>

<AdminData StudyOID="369cbf09-3322-43cc-b0ef-895be23bead0">

...

</AdminData>

<ClinicalData StudyOID="369cbf09-3322-43cc-b0ef-895be23bead0"

MetaDataVersionOID="21.0">

<SubjectData SubjectKey="SE-AHU-006" v4:StudySubjectSeqNo="10"

v4:SiteSubjectSeqNo="6">

...

</SubjectData>

<AuditRecords>

...

</AuditRecords>

</ClinicalData>

</ODM>]]></a:OdmXml>

</GetClinicalDataResult>

</GetClinicalDataResponse>

</s:Body>

</s:Envelope>

Note! GetClinicalData does not support StudyEventRepeatKey.

Complex Data Types

ApiAuthenticationModel

The ApiAuthenticationModel data type contains the following elements:

Property Data type Description
ClientGUID GUID Client ID linked to a specific study in Viedoc.
Can be obtained from Viedoc Admin. Required.
UserName string Viedoc login username. Required.
Password string Matching Viedoc login password. Required.
TimeSpanInSeconds int Time (in seconds) that the authentication token will be valid for. Optional.
Default is 300 seconds (5 min). Maximum is 1800 seconds (30 min).

ApiResultType

ApiResultType is an enum data type with one of the following values*:

Pending The request is being processed and no result yet.
Success The request has completed successfully.
Error The request terminated with an error. See error code and message for a description of the error that occurred.
InProgress Data import has started and date is currently being processed.
PartialComplete Data import has started but is in an idle state waiting for remaining subjects to be unlocked so that data import can resume.
Data import has started but a subject is not found due to invalid ID. The subject is not imported and the system continues to identify the next subject.
*For GetClinicalData, only an ApiResultType enum data type with the value Success or Error is used.

ApiSubmitDataOptions

Property Data type Description
AllowCreatingSubjects bool Defines whether new subjects will be created during the data import when unmatched subjects are found. Can be set to true or false, default is set to true.
AllowInitiatingStudyEvents bool Defines whether uninitiated events will be initiated during the data import. Can be set to true or false, default is true.

ViedocKeySet

The ViedocKeySet data type contains the following properties:

Property Data type Description
Uniqueld string For internal use only. The value of this property will be ignored if populated in a request.
SubjectKey string Subject key of a subject in Viedoc
StudySiteId int Database ID of the study site
CountryCode string Two letter country code
SiteCode string Site code as set in Admin. Required.
SiteNo int Site number
StudySujbectSeqNo int Sequence number of a subject on a study level
SiteSubjectSeqNo int Sequence number of a subject on a site level
StudyEventDefId string Study event OID as set in the study design
StudyEventRepeatKey string Study event repeat key
EventDate DateTime Event date in ISO8601 format
FormDefId string Form OID as set in the study design
FormRepeatKey string Form repeat key
ItemDefId string Item OID as set in the study design
MetaDataVersionOID string Study design OID (version) in the form [VERSION].[REVISION]. Will be populated in the response based on the submitted values of all the previous keys.

ApiGetClinicalDataRequestModel

The ApiGetClinicalDataRequestModel data type contains the following properties:

Property Data type Description
SiteCode string Site code as set in Admin. Required.
SubjectFilter string Subject filter using any string. Optional.
SubjectKey string Subject key of a subject in Viedoc. Optional.
StudyEventOID string Study event OID as set in the study design. Optional.
FormOID string Form OID as set in the study design. Optional.
ItemOID string Item OID as set in the study design. Optional.
TimePeriodDateType ApiTimePeriodDateType SystemDate|EventDate. Optional.
TimePeriodOption ApiTimePeriodOption Until|From|Between. Optional.
FromDate DateTime Used to match data by entered or event date.
Optional.
ToDate DateTime Used to match data by entered or event date.
Optional.
ExcludeExtensions bool Defines whether to exclude the Study Design Model (SDM), Viedoc and audit trails. Can be set to true or false, default is set to false.
IncludeAdminData bool Defines whether to include user and study site data in
the export. Can be set to true or false, default is set to
false.
IncludeVisitDates bool Defines whether the event date form will be included
in the export. The event date form includes the event
date, planned date and the event window. Can be set to
true or false, default is set to false.
IncludeQueries bool Defines whether queries will be included in the export.
Can be set to true or false, default is set to false.
IncludeReviewStatus bool Defines whether review status will be included in the
export. Can be set to true or false, default is set to
false.
IncludeSignatures bool Defines whether signatures will be included in the
export. Can be set to true or false, default is set to
false.
IncludeMedicalCoding bool Defines whether medical coding will be included in the
export. Can be set to true or false, default is set to
false.
IncludeSubjectStatus bool Defines whether to include the subject status in the export. Can be set to true or false, default is set to false.
ViedocVersion string Defines which data structure version is used for the
export. As of Viedoc release 4.39, the data structure
version can be set to 4.38, 4.39 or Latest Viedoc
Version. If nothing is specified, the Viedoc version set
in the API configuration settings in Viedoc Admin is
used.

Error codes

The following table displays a list of error codes and their description.

Code Message Description
100 Invalid username or password The provided username or password is invalid.
101 Invalid Client GUID The provided client ID is invalid.
102 Invalid token The token is invalid.
103 NOT USED
104 Xml data is required No ODM XML data was included in the request.
105 NOT USED
106 Invalid Client GUID/User The provided token represents an invalid client GUID
or an invalid user. This is very unlikely to occur when the token is
generated from the system.
107 NOT USED
108 NOT USED
109 Unauthorized access, only user who
submitted data can get transaction
information		 TransactionData and TransactionStatus can only be
invoked by the user who submitted the data.
110
111 Permission denied The user does not have access to the specified resource.
112 Metadata version not found The requested metadata version could not be found in
the study.
114 User is SSO user The domain is set up for single sign-on, and API login is not supported.
121 Invalid study site
122 User does not have export permission to site

A workflow example

An example of how to submit data into Viedoc

Introduction

This chapter serves as an example of how to submit data into Viedoc. It provides instructions on where in Viedoc you can obtain the following information:

  • A client ID
  • Study site ID and design version
  • Element OIDs
  • Item data types
  • Subject ID

This chapter also provides instructions to construct the clinical data file using the obtained information.

Obtaining the client ID

See API configuration.

Obtaining the study site code and design version

Note down the study site code and effective design version for the site or sites that data will be imported into. The
study site code and effective design are displayed in the study sites list in Viedoc Admin. The effective design version
is displayed in the form of [VERSION].[REVISION] for each site separately.

Obtaining the element OIDs

Obtain the following OIDs:

  1. StudyEventOID
  2. FormOID
  3. ItemGroupOID
  4. ItemOID

These OIDs can either be obtained from the study design in Viedoc Designer or by downloading the metadata
version by invoking the GetMetaData API method.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/">

<soapenv:Header>

<soapenv:Body>

<tem:GetMetaData>

<tem:token>FE4...171</tem:token>

<tem:metaDataOid>8.0</tem:metaDataOid>

<tem:includeSdm>true</tem:includeSdm>

<tem:includeViedocExtensions>true</tem:includeViedocExtensions>

</tem:GetMetaData>

</soapenv:Body>

</soapenv:Envelope>

If you choose to download the metadata version by invoking the GetMetaData API method, search the returned ODM file for the following elements, and note down the OIDs:

  • StudyEventDef (to obtain the StudyEventOID)
  • FormDef (to obtain the FormOID)
  • ItemGroupDef (to obtain the ItemGroupOID) and ItemRef (to obtain the ItemOID)

Obtaining the item data types

Obtain the item data types. The item data types can be obtained from Viedoc Designer or found in the DataType attribute of the ItemDef element in ODM.

When constructing the ClinicalData elements, use the data element corresponding to the item data type.

ItemDef Data type ItemData Data type
String ItemDataString
Text ItemDataString
Integer ItemDataInteger
Double ItemDataDouble
DateTime ItemDataDateTime
Date ItemDataDate
Time ItemDataTime

Obtaining the subject key

The subject key is obtained from Viedoc Clinic.

It is also possible to match subjects using the StudySubjectSeqNo or the StudySiteSubjectSeqNo. These are the sequence number of the subject in a study and study site respectively.

When trying to match data for an imported subject with a subject in Viedoc, the StudySubjectSeqNo and StudySiteSubjectSeqNo are used first. They can both be specified as extension attributes on the SubjectData element in the ODM clinical data. If no matching subject is found using the StudySubjectSeqNo or StudySiteSubjectSeqNo, the subject key is used to find a matching subject.

If no matching subject could be found using either method, the following applies:

  • If AllowCreateSubjects is set to true, a new subject is created.
  • If AllowCreateSubjects is set to false, the subject is skipped.
    The DataImportLog is indicated as PartialComplete and shows which subject that does not exist.

When creating a new subject in Viedoc, the subject will receive the next available StudySubjectSeqNo and StudySiteSubjectSeqNo. These sequence numbers can be overridden in two different ways:

  • By explicitly providing the subject sequence numbers as attributes.
  • By including the subject sequence numbers in the subject key format, so that the subject sequence numbers can be extracted from the subject key. This requires the site code and site subject sequence number to be as specified in the Subject ID Generation Settings in the study design in Viedoc Designer.

Constructing the ODM XML ClinicalData file

Note! To access the example ODM XML ClinicalData file as a text that you can copy into your tool, click here.

All text highlighted in yellow should be replaced with the MetaData version OID, Studysite OID, and Item OIDs obtained as previously described.

All text highlighted in green should be replaced with the values for the respective items.

The ClinicalData ODM can then be submitted using the SubmitData method as described earlier, see section 2.3 SubmitData.