Viedoc WCF API

  • Published by Viedoc System 2025-05-02
  • Print

はじめに

このドキュメントには、WCFの標準を使用して、開発環境またはその他のシステムをViedocのパブリックWebサービスに接続するための情報が含まれています。

ViedocのパブリックApplication Programming Interface (API)はHTTPサービス上のSOAPであり、以下にて利用可能です。https：//VIEDOC_HOST /HelipadService.svc

また、https://[VIEDOC_HOST]/HelipadService.svc?wsdl から、wsdlメタデータファイルをダウンロードすることができます。

EU サーバー

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

日本サーバー

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

中国サーバー
https://api.viedoc.cn/HelipadService.svc?wsdl
https://apitraining.viedoc.cn/HelipadService.svc?wsdl

USサーバー

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

その他の接続先のホストについては、Viedoc Technologies までお問い合わせください。

詳しくは Guide to Viedoc server instances を参照ください。

メソッド

トークン

概要

トークンメソッドはクライアントを認証するために使用されます。後続のすべての要求を認証する際の認証トークンを受領するためには、トークンを呼び出す必要があります。

クライアントを認証するには、以下の情報を提供する必要があります。

  • 有効なクライアントID、Viedocの特定の試験に紐付いたクライアントID（GUID）。クライアントIDは、デモまたは本番環境の試験のいずれかに紐付いています。

  • Viedocのユーザーネームとパスワード。Viedocにデータを送信できるようにするには、ユーザーがViedocのその試験と施設にアクセスすることができ、データ入力を許可するロールが付与されている必要があります。

注意！API管理者のロールに割り当てられている場合のみ、API設定ウィンドウにアクセスして、APIクライアントIDを作成することができます。トークン/GetTokenメソッドが使用されると、保留中になっている、ユーザーへのロールの招待がすべて自動的に承認されます。

クライアントIDを取得する方法についての詳細は、API 設定を参照ください。

C# Syntax

ApiTokenModel tokenModel = Token(ApiAuthenticationModel loginModel);

パラメーター

Tokenメソッドには以下のパラメータがあります。

パラメータ

データ型

内容
loginModel ApiAuthenticationModel 一連の認証情報
詳細は3.1 ApiAuthenticationModelを参照してください。

戻り値

トークンメソッドでは、以下のプロパティを持つApiTokenModelオブジェクトを返します。

プロパティ データタイプ 内容
Token string

後続の要求で認証に使用可能な、新しい認証トークン
Result ApiResultType

メソッド呼び出しから返される結果の種類とステータスを定義します。詳細については、3.2 ApiResultTypeのセクションを参照してください。
ErrorCode int

結果がエラーの場合：エラーの種類を示す整数が入ります。詳細については、4 エラーコードのセクションを参照してください。
Errormessage string 結果がエラーの場合：人間が読める形式でのエラーの記述
ExpiryDateTime DateTime

トークンの有効期限（日時）

HTTP呼び出しの例

<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>

HTTP応答の例

<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>

GetToken

概要

GetTokenメソッドの説明は、2.1トークンセクションのトークン方式に関する記述を参照してください。

C# Syntax

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

パラメータ

GetTokenメソッドには、以下のパラメーターがあります。

パラメータ

データタイプ

内容
ClientGuid ApiAuthenticationModel

Viedocの特定の試験に紐付けられたクライアントID。Viedoc Admin
から取得可能。必須。
UserName string Viedocのログインユーザーネーム。必須。
Password string 一致するViedoc ログインパスワード。必須。
TimeSpanInSeconds int

認証トークンを有効とする時間（秒単位）。任意のパラメーター。
デフォルトは300秒（5分）。最大は1800秒（30分）。

戻り値

GetTokenメソッドの戻り値のリストについては、2.1.4 戻り値のセクションで説明されているTokenメソッドの戻り値を参照してください。

SubmitData

概要

Viedocへのデータ送信にSubmitDataメソッドを使用することが可能です 。

C# Syntax

ApiSubmitResultModel SubmitData(string token, string odmXml,

ApiSubmitDataOptions options = null);

パラメータ

SubmitDataメソッドには、以下のパラメータがあります。

パラメータ

データタイプ

内容
Token string

認証トークン。クライアントID、ユーザーネーム、パスワードを使用してTokenメソッドを呼び出すことで取得できます。
OdmXml string

ODM XML形式でアップロードされるデータ
Options ApiSubmitDataOptions データの送信オプション。任意のパラメーター。3.3 ApiSubmitDataOptionsセクションを参照してください。

戻り値

SubmitDataメソッドでは、以下の特性を持つApiSubmitResultModelオブジェクトを返します：

プロパティ 型 内容
Token string

後続の要求で認証に使用可能な、新しい認証トークン
Result ApiResultType

メソッドの呼び出しから返される結果の種類とステータスを定義します。詳細については、3.2 ApiResultTypeのセクションを参照してください。
ErrorCode int

結果がエラーの場合：エラーの種類を示す整数が入ります。詳細については、4 エラーコードのセクションを参照してください。
ErrorMessage string

結果がエラーの場合：人間が読める形式でのエラーの記述
TransactionGUID GUID

TransactionStatusまたはTransactionDataを呼び出す時など、将来の要求でトランザクションを識別するために使用される、トランザクションに割り当てられたGUID。アップロードされる患者またはデータポイントの数に関係なく、SubmitDataメソッドを呼び出すたびに、1つのトランザクションGUIDが割り当てられます。

呼び出し例

数字 項目 内容
1 MetaDataVersionOID

インポートするデータに使用する、メタデータの[Version].[Revision]
2 SubjectKey

データのインポート先の患者に対するViedocの患者キー
3 LocationOID 施設IDはViedoc Adminから取得可能です。
4 Event/form/item OIDs

イベント、フォームおよび項目のOIDは、エクスポートされたメタデータのバージョンまたはViedoc Designerから取得可能です。

注意！StudyEvent が繰り返す場合、StudyEventRepeatKey が与えられるべきです。

例:
<StudyEventData StudyEventOID="AE" StudyEventRepeatKey="1">
5 ItemDataInteger

許可されているデータ値のタイプは以下の通りです。

  • ItemDataString
  • ItemDataInteger
  • ItemDataDouble
  • ItemDataPartialDateTime*
  • ItemDataPartialDate
  • ItemDataPartialTime

* 時間データを収集する CRF変数には、Viedoc のタイムゾーンのコンテナがありません。そのような変数のデータは、通常、試験実施場所と同じタイムゾーンの時間を表しているとみなされます。したがって、例えば2020-01-29T08:34:00のように、タイムゾーン情報を含まない時間データを入力することをお勧めします。時間帯を考慮しなければならない場合、例えば血液サンプルが異なる時間帯に位置する研究室で分析された場合、追加のCRF変数を使用してその情報を収集することができます。タイムゾーン情報がデータ値の一部としてAPI（またはインポートアプリケーション）を介してViedocに送信された場合、データ値に反映されます。これは、Viedocにはそれを保存する場所がないためです。例えば、2000-01-01T00:00:00+01:00（1時間オフセット）は1999-12-31T23:00:00Z（オフセットなし）に変換され、CRFでは1999-12-31 23:00として表示されます。このため、時間帯情報を取り除くために必要な変換は、Viedocに時間データを入力する前に処理しておくことをお勧めします。

応答例

<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>

画像ファイルのアップロード

ファイルアップロードアイテムには、例えば画像などのファイルをインポートすることができます。これは、SubmitDataメソッドを使用して他の種類のデータをインポートする方法と似ています。ファイルをインポートする前に、base64文字列に変換する必要があります。変換方法は、使用するプログラムによって異なります（例えば、Pythonではbase64モジュールのtheb64encode関数を使用できます）。ファイルアップロードアイテムのアイテムデータタイプは、ODM XMLでsItemDataBase64Binaryとして指定する必要があります。


値（base64文字列）に加えて、v4:FileNameプロパティも指定する必要があります。つまり、拡張子を含むファイル名です。XML名前空間v4は、ODM開始タグで定義する必要があります。

こちらの画像を参考にしてください。

TransactionStatus

概要

過去に送信されたデータのインポートステータスをチェックするために、TransactionStatusメソッドを使用することができます。

C# Syntax

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

パラメーター

TransactionStatusメソッドには、以下のパラメータがあります。

名前

データ型

内容
Token 文字列 認証トークン
TransactionGUID GUID

SubmitDataメソッドを呼び出すときに取得されるトランザクションGUID

戻り値

TransactionStatusメソッドでは、以下の特性を持つApiResultModelオブジェクトを返します：

プロパティ 型 内容
Token

文字列

 後続の要求で認証に使用可能な、新しい認証トークン
Result

ApiResultTpe

メソッドの呼び出しから返される結果のタイプとステータスを定義します。詳細については、3.2 ApiResultTypeのセクションを参照してください。
ErrorCode

整数

結果がエラーの場合：エラーの種別を示す整数が入ります。詳細については、エラーコードのセクションを参照してください。
ErrorMessage

文字列

 結果がエラーの場合：人間が読める形式でのエラーの記述

呼び出し例

<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>

応答例

<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

概要

過去に送信されたデータを取得するために、TransactionDataメソッドを使用することが可能です。

C# Syntax

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

パラメーター

TransactionDataメソッドには、以下のパラメータがあります。

名前

データ型

内容
Token 文字列

認証トークン
TransactionGUID GUID

SubmitData方式を呼び出すときに取得されるGUID

戻り値

TransactionDataメソッドでは、以下の特性を持つApiTransactionDataModelオブジェクトを返します：

プロパティ

型

内容
Token

文字列

 後続の要求で認証に使用可能な、新しい認証トークン
Result

ApiResultType

メソッドの呼び出しから返される結果の種類とステータスを定義します。詳細については、3.2 ApiResultTypeのセクションを参照してください。
ErrorCode

整数

結果がエラーの場合：エラーの種類を指定する整数が入ります。詳細については、4 エラーコードのセクションを参照してください。
ErrorMessage

文字列

 結果がエラーの場合：人間が読める形式でのエラーの記述
OdmXml

文字列

 ODM XML形式でアップロードされたデータ

呼び出し例

応答例

<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">

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

</ItemGroupData>

</FormData>

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

<ItemGroupData ItemGroupOID="VSG1">

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

<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

概要

ODM XML形式で試験のメタデータバージョンを取得するために、GetMetaDataメソッドを使用することが可能です。

C# Syntax

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

パラメーター

GetMetaDataメソッドには、以下のパラメータがあります。

名前

データ型

内容
Token string 認証トークン
metaDataOid string

[Version]. [Revision]形式のメタデータOID。たとえば、1.1はバージョン1の改訂1を意味します。メタデータOIDはViedoc AdminまたはDesignerから取得可能です。
includeSdm

bool

エクスポートされたメタデータODM XMLファイルに、試験デザインモデル（SDM）のプロパティを含めるかどうかを定義します。trueまたはfalseに設定することができます。デフォルトはfalseに設定されています。
includeViedocExtensions

bool

エクスポートされたメタデータのODM XMLファイルに、Viedoc固有の拡張子のプロパティを含めるかどうかを定義します。trueまたはfalseに設定することができます。デフォルトはfalseに設定されています。

戻り値

GetMetaDataメソッドでは、以下の特性を持つApiGetMetaDataResultModelオブジェクトを返します：

プロパティ

型

内容

Token

string

後続の要求で認証に使用可能な、新しい認証トークン

Result

ApiResultType

メソッドの呼び出しから返される結果の種類とステータスを定義します。詳細については、3.2 ApiResultTypeのセクションを参照してください。

ErrorCode

int

結果がエラーの場合：エラーの種類を指定する整数が入ります。詳細については、4 エラーコードのセクションを参照してください。

ErrorMessage

string

結果がエラーの場合：人間が読める形式でのエラーの記述

OdmXml

string

試験で要求されているメタデータバージョンを含むODM XML

呼び出し例

<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>

応答例

<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

概要

一連のデータポイント（複数可）に対する試験デザインのバージョン（メタデータバージョン）を取得するために、GetMetaDataVersionForKeySetsメソッドを使用することができます。

C# Syntax

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

パラメーター

GetMetaDataVersionForKeySetsメソッドでは、以下のパラメータがあります。

名前

データ型

内容
Token string 認証トークン
KeySets List<ViedocKeySet>

取得すべき試験デザイン（メタデータ）バージョンに対する、キーセットのリストが含まれています。
キーセット内の個々のキーはすべてオプションで、指定されたすべてのキーに基づいた試験デザインバージョンが返されます。セクション3.4 ViedocKeySetを参照してください。

戻り値

GetMetaDataVersionForKeySetsメソッドでは、以下の特性を持つApiGetMetaDataVersionsResultModelオブジェクトを返します：

プロパティ

型

内容

Token

stging

後続の要求で認証に使用可能な、新しい認証トークン

Result

ApiResultType

メソッドの呼び出しから返される結果の種類とステータスを定義します。詳細については、3.2 ApiResultType のセクションを参照してください。

ErrorCode

int

結果がエラーの場合：エラーの種類を示す整数が入ります。詳細については、4 エラーコードのセクションを参照してください。

ErrorMessage

string

結果がエラーの場合：人間が読める形式でのエラーの説明

KeySets

List<ViedocKeySet>

試験で要求されているメタデータバージョンを含むODM XML

HTTP呼び出し例

<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>

応答例

<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>

GetClinicalStudySites

概要

GetClinicalStudySites メソッドは、ユーザーが Viedoc Clinic でアクセスできるサイトに関する情報を返します。

C# Syntax

ApiGetClinicalStudySitesResultModel GetClinicalStudySites(string token);

パラメーター

GetClinicalStudySitesメソッドには、以下のパラメータがあります。

パラメーター

データ型

内容
Token string 認証トークン

戻り値

GetClinicalStudySitesメソッドでは、以下の特性を持つApiStudySiteModelオブジェクトを返します：

プロパティ

タイプ

内容

Country

string

国名

CountryCode

string

国コード二文字
ExpectedNumberOfSubjectsEnrolled int 施設に登録予定の症例数
ExpectedNumberOfSubjectsScreened int 施設での予定スクリーニング数
MaximumNumberOfSubjectsScreened int 施設での最大スクリーニング数

Guid

string

サイトID

SiteCode

string

Adminで設定したサイトコード

SiteName

string

Adminで設定したサイト名
SiteType string サイトのタイプ : トレーニング又は本番
TimeZone string WindowsのタイムゾーンID
TzOffset int UTCからのオフセット（分単位）

HTTP呼び出し例

<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>

HTTP応答例

<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

概要

GetClinicalDataメソッドは、クリニカルデータをODM形式でエクスポートするために使用することができます。

C# Syntax

ApiGetClinicalDataResultModel GetClinicalData(string token, ApiGetClinicalDataRequestModel options);

パラメーター

GetClinicalDataメソッドには以下のパラメーターがあります。

パラメーター

データ型

内容

Token

string

認証トークン

options

ApiGetClinicalDataRequestModel

データエクスポートのためのオプションとフィルター。3.5 ApiGetClinicalDataRequestModel を参照してください。

戻り値

GetClinicalData メソッドは、以下の特性を持つ ApiGetClinicalDataResultModel オブジェクトを返します。

プロパティ タイプ 内容
Token string 後続のリクエストで認証に使用できる新しい認証トークン。

Result

ApiResultType

 メソッドの呼び出しから返される結果のタイプとステータスを定義します。ApiResultType 列挙型で、Success または Error の値が使用されます。
ErrorCode int エラーが発生した場合 resultには、エラーの種類を指定する整数が含まれます。詳細はセクション 4. エラーコードを参照してください。
ErrorMessage string

エラーが発生した場合、エラーの内容を記述します。
OdmXml string ODM形式でエクスポートされたデータ。

HTTP呼び出し例

注意! クローズの順番は重要です。以下のコード例内の順序に従うことが重要です。

<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>

HTTP応答例

<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>

注意！GetClinicalData は StudyEventRepeatKeyをサポートしていません。

複合データ型

ApiAuthenticationModel

ApiAuthenticationModelには、以下の要素が含まれます。

プロパティ

型

内容
ClientGUID GUID

Viedocの特定の試験に紐付けられたクライアントID。Viedoc Admin
から取得できます。この要素は必須です。
UserName string

Viedoc ログインユーザーネーム。この要素は必須です。
Password string 一致するViedocログインパスワード。この要素は必須です。
TimeSpanInSeconds int

認証トークンが有効となる時間（秒単位）。任意の要素です。
デフォルトは300秒（5分）で、最大1800秒（30分）です。

ApiResultType

ApiResultTypeは以下のいずれかの値を持つenumデータ型です*。

Pending

要求は現在処理中で、まだ結果は出ていません。
Success

要求は正常に完了しました。
Error

要求はエラーのため、終了しました。発生したエラーの内容については、エラーコードとメッセージを参照してください。
InProgress

データのインポートが開始され、現在処理中です。
PartialComplete

データのインポートは開始されましたが、現在待機中です。残りの患者のロックが解除されてから、データのインポートを再開します。
データのインポートは開始されましたが、無効なIDのため、患者が見つかりませんでした。この患者はインポートされません。次の患者の識別を続けます。

* GetClinicalDataでは、値がSuccessまたはErrorのApiResultType enumデータ型のみが使用されます。

ApiSubmitDataOptions

注意！

  • API メソッド SubmitData を使用すると、有効なデザイン内に存在するが、試験ワークフローに従って各イベント内に存在しないフォームにデータを送信できます。このような場合、新しいフォームが作成され、イベントに追加されます。
  • WCF API を使用してフォームにデータをプッシュする際、他の項目や項目グループからデータを計算する関数が設定されている項目がある場合、それらの計算は自動的に更新されません。ただし、関数に依存する項目が、その関数に依存する同じ項目グループに追加された場合は、計算が実行されます。

プロパティ

データ型

内容
AllowCreatingSubjects bool

一致する患者が見つからなかった場合に、データのインポート中に新しい患者を作成するかどうかを定義します。trueまたはfalseに設定できます。デフォルトはtrueに設定されています。
AllowInitiatingStudyEvents bool

データのインポート中に未実施イベントを実施するかどうかを定義します。trueまたはfalseに設定できます。デフォルトはtrueです。

ViedocKeySet

ViedocKeySetのタイプには、以下のプロパティが含まれます。

プロパティ

データ型

内容
Uniqueld string

内部での使用のみ。要求に投入された場合、このプロパティの値は考慮されません。
SubjectKey string

患者のViedocの患者キー
StudySiteId int

施設のデータベースID
CountryCode string

2文字の国コード
SiteCode string

Adminで設定された施設コード。必須です。
SiteNo int

施設番号
StudySujbectSeqNo int

試験レベルでの患者の通し番号
SiteSubjectSeqNo int

施設レベルでの患者の通し番号
StudyEventDefId string

試験デザインで設定された試験イベントOID
StudyEventRepeatKey string

試験イベントの繰り返しキー
EventDate DateTime

ISO8601形式のイベント日付
FormDefId string

試験デザインで設定されたフォームOID
FormRepeatKey string

フォームの繰り返しキー
ItemDefId string

試験デザインで設定された項目OID
MetaDataVersionIOD string

[VERSION].[REVISION]形式の試験デザインOID（バージョン）。過去に送信されたすべてのキーの値に基づいて、応答に投入されます。

ApiGetClinicalDataRequestModel

ApiGetClinicalDataRequestModelデータ型には、以下のプロパティが含まれます。

SiteCode string

Adminで設定された施設コード。必須です。
SubjectFilter string

任意の文字列を使用した患者フィルター。オプションです。
SubjectKey string

患者のViedocの患者キー。オプションです。
StudyEventOID string

試験デザインで設定された試験イベントOID。オプションです。
FormOID string

試験デザインで設定されたフォームOID。オプションです。
ItemOID string

試験デザインで設定された項目OID。オプションです。
TimePeriodDateType ApiTimePeriodDateType SystemDate|EventDate。オプションです。
TimePeriodOption ApiTimePeriodOption Until|From|Between。オプションです。
FromDate DateTime 入力した日付またはイベントの日付でデータを照合するために使用されます。
オプションです。
ToDate DateTime 入力した日付またはイベントの日付でデータを照合するために使用されます。
オプションです。
ExcludeExtensions bool

SDM、Viedoc および監査証跡を除外するかどうかを定義し
ます。trueまたはfalseに設定できます。デフォルトはfalseに設定されています。
IncludeAdminData bool エクスポートにユーザーおよび施設のデータを含めるかどうかを定義します。trueまたはfalseに設定できます。デフォルトはfalseに設定されています。
IncludeVisitDates bool

イベント日付フォームをエクスポートに含めるかどうかを定義します。イベント日付フォームには、イベント日付、予定日、およびイベントの許容範囲が含まれます。trueまたはfalseに設定することができます。デフォルトはfalseに設定されています。
IncludeQueries bool クエリをエクスポートに含めるかどうかを定義します。
trueまたはfalseに設定できます。デフォルトはfalseに設定されています。
IncludeReviewStatus bool レビューステータスをエクスポートに含めるかどうかを定義します。trueまたはfalseに設定できます。デフォルトはfalseに設定されています。
IncludeSignatures bool 署名をエクスポートに含めるかどうかを定義します。trueまたはfalseに設定できます。デフォルトはfalseに設定されています。
IncludeMedicalCoding bool コーディングをエクスポートに含めるかどうかを定義します。trueまたはfalseに設定できます。デフォルトはfalseに設定されています。
ViedocVersion string

エクスポートに使用するデータ構造バージョンを定義します。Viedoc4.39のリリース時点では、データ構造バージョンを4.38、4.39または最新のViedocバージョンに設定することができます。何も指定されていない場合、Viedoc AdminのAPI設定で選択されているViedocバージョンが使用されます。

エラーコード

以下の表では、エラーコードとその説明をリストしています。

コード

メッセージ

説明
100

無効なユーザーネームまたはパスワード

 指定されたユーザーネームまたはパスワードは無効です。
101

無効なクライアントGUID

 入力されたクライアントIDは無効です。
102

無効なトークン

無効なTokenです。
103

使用されていません

104

XMLデータが必要です

要求にODM xmlデータが含まれていません。
105

使用されていません
106 無効なクライアントGUID/ユーザー

指定されたトークンは、無効なクライアントGUIDまたは無効なユーザーを示しています。トークンがシステムから発行された場合は起こる可能性が低い現象です。
107

使用されていません
108

使用されていません
109

不正アクセス、
データを送信したユーザーのみがトランザクション情報を取得できます

データを送信したユーザーのみが、TransactionDataおよびTransactionStatusを呼び出することが可能です。
110

無効なトランザクション GUID
111

アクセス拒否

ユーザーは指定されたリソースにアクセスできません。
112

メタデータのバージョンが見つかりません

 リクエストされたメタデータのバージョンは試験で見つかりませんでした。
114 SSOのユーザーです ドメインはシングルサインオン用に設定されており、APIログインはサポートされていません。
121 無効の施設
122 ユーザーにはエクスポート権限がありません

ワークフローの例

Viedocへのデータ送信方法の例

はじめに

この章では、Viedocへのデータ送信方法の例を提示します。また、Viedocのどこで以下の情報を取得できるかを説明します。

  • クライアントID
  • 施設IDとデザインバージョン
  • 要素のOID
  • 項目のデータ型
  • 患者ID

この章では、取得した情報を使用してODM XML臨床データファイルを作成する手順も解説します。

クライアントIDを取得する

API の設定を参照ください。

試験場コードと設計バージョンの入手

データをインポートするサイトのサイトコードと有効な設計バージョンをメモしてください。この Viedoc Adminのスタディサイト一覧に試験施設コードと有効設計が表示されます。有効設計バージョンは、各施設ごとに[VERSION].[REVISION]という形式で表示されます。

要素のOIDを取得する

以下のOIDを取得します。

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

これらのOIDはViedoc Designerの試験デザインから取得するか、GetMetaData APIメソッドを呼び出してメタデータバージョンをダウンロードすることで取得できます。

<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>

GetMetaData APIメソッドを呼び出してメタデータバージョンをダウンロードする場合、以下の要素に対して返されたODM XMLファイルを見つけて、OIDを書き留めます。

  • StudyEventDef (StudyEventOIDを取得する)
  • FormDef (FormOIDを取得する)
  • ItemGroupDef (ItemGroupOIDを取得する)とItemRef (ItemOIDを取得する)

項目のデータ型を取得する

項目のデータ型を取得します。項目のデータ型はViedoc Designerから取得するか、ODM XMLのItemDef要素のDataType属性で確認することができます。

ClinicalDataの要素を作成するときは、項目のデータ型に対応するデータ要素を使用します。

ITEMDEF データ型 ITEMDATA データ型
String ItemDataString
Text ItemDataString
Integer ItemDataInteger
Double ItemDataDouble
DateTime ItemDataPartialDateTime
Date ItemDataPartialDate
Time ItemDataPartialTime

患者キーを取得する

患者キーはViedoc Clinicで取得できます。

StudySubjectSeqNoまたはStudySiteSubjectSeqNoを使用して、患者を照合することも可能です。これらは、それぞれ試験および施設の患者の通し番号です。

Viedocの患者とインポートされた患者のデータを照合するとき 、StudySubjectSeqNoとStudySiteSubjectSeqNoが最初に使用されます。これらは両方とも、ODM臨床データのSubjectData要素の拡張属性として指定することができます。StudySubjectSeqNoまたはStudySiteSubjectSeqNoで一致する患者が見つからない場合、患者キーを使用して一致する患者を検索します。

どちらの方式でも一致する患者が見つからない場合、以下が適用されます。

  • AllowCreateSubjectsがTrueに設定されている場合、新しい患者が作成されます。
  • AllowCreateSubjectsがFalseに設定されている場合、患者はスキップされます。DataImportLogにPartialCompleteとして記載され、存在しない患者であることが提示されます。

Viedocで新しい患者が作成されると、次に利用可能なStudySubjectSeqNoとStudySiteSubjectSeqNoが患者に付与されます。これらの通し番号は異なる2つの方式でオーバーライドすることができます。

  • 患者通し番号を明示的に属性として指定する
  • 患者通し番号を患者キー形式に含めることにより、患者通し番号を患者キーから抽出することができます。これには、Viedoc Designerの試験デザインの患者ID形式設定で指定する施設コードと施設の患者通し番号が必要になります。

ODM XML ClinicalData ファイルを構築する

ここまでの手順で取得した情報に基づいて、送信するODM XMLを次のように構築することができます。

前述のとおり、黄色でハイライトされているテキストはすべて、取得したMetaDataバージョンのOID、施設のOIDおよび項目のOIDに置き換える必要があります。

緑色でハイライトされているすべてのテキストは、それぞれの項目の値に置き換える必要があります。

先に記載された通り、これでSubmitDataメソッドを使用してClinicalData ODMを送信することができるようになります。2.3 SubmitDataのセクションを参照してください。

ページトップへ戻る