Viedoc WCF API

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 the EU:

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

For Japan:

https://v4apijp.viedoc.net/HelipadService.svc?wsdl
https://v4apitrainingjp.viedoc.net/HelipadService.svc?wsdl
https://v4apistagejp.viedoc.net/HelipadService.svc?wsdl

For China:

https://api.viedoc.cn/HelipadService.svc?wsdl
https://apitraining.viedoc.cn/HelipadService.svc?wsdl

For the USA:

https://api.us.viedoc.com/HelipadService.svc?wsdl
https://apitraining.us.viedoc.com/HelipadService.svc?wsdl

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

See Guide to Viedoc server instances for more information.

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>

<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.
`PartialComplete`	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:

StudyEventOID
FormOID
ItemGroupOID
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:vied="Viedoc.API"

<soapenv:Header>

<soapenv:Body>

<vied:GetMetaData>

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

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

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

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

</vied: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.