End-to-end example process

This example will demonstrate the API calls required to create a new Product, Study (Protocol), Country and Site. A document record will then be generated and a file uploaded to fulfil that document record. Note that HTTP headers in the responses have been removed for brevity. Credentials and access tokens have been obfuscated.

Generate an Authentication Token

Request

POST https://client-api.phlextmf.com/auth/v5/auth/login HTTP/1.1 
Host: client-api.phlextmf.com
Content-Type: application/json

{
     "Username":"[email protected]",
     "Password":"*******"
}

Response

HTTP/1.1 200 OK

{
  "access_token": "eyJhbGci....",
  "expires": 1558045954
}

The access token generated will be valid until the specified expiry and should be used as the Bearer token for subsequent requests.

Create the Attribute Values

Within the PhlexTMF system, most data fields for a Document are referred to as "Attributes" and the valid values for these attributes are known as "Attribute Values". This includes Protocol, Site, Artifact, etc. The Attributes API allows for the creation and manipulation of attribute values. The attributes API can be located at a REST endpoint within the Attributes service, and is accessible from the following (example) URI:

https://client-api.phlextmf.com/attributes/v5/attributes

The first section of this URI identifies the instance of PhlexTMF that is being called (client-api.phlextmf.com, in this example, will call the PhlexTMF instance named client).

The second section of the URI identifies the service being called (attributes service in this case).

The third section of the URI identifies the version of the PhlexTMF API being used (v5).

The final section of the URI is the path to the resource. The attributes resource would return a list of attributes within this PhlexTMF instance (see the API Reference section for details).

PhlexTMF files documents against 2 main "tree" structures. The Protocol tree and the Filing Structure tree:

Solid lines on the diagram above represent relations of type "ParentChild". Dotted lines represent links. When creating new values for these attributes, it may be required to specify one or more relations or links dependent on the PhlexTMF system setup, however the those depicted above represent the minimum relational configuration of the system. Values must be unique within an Attribute, unless they are in a ParentChild relation in which case the hierarchy must be unique.

Create the Product attribute value

To create the Product, a POST will be made to the attributes/product/values resource. Product is the starting point of the Protocol tree and thus it is not required to specify any relations or links.

Request

POST https://client-api.phlextmf.com/attributes/v5/attributes/product/values HTTP/1.1
Host: client-api.phlextmf.com
Content-Type: application/json
Authorization: Bearer eyJhbGci....

{
    "value":"API Test",
    "status":"1"
}

Response

HTTP/1.1 201 Created

{
  "attributeId": 3,
  "id": 1213,
  "attributeDisplayName": "Product",
  "value": "API Test",
  "sortOrder": null,
  "description": null,
  "helpContent": "",
  "processHelpContent": "",
  "processHelpLink": "",
  "status": 1
}

This will generate the Product record within the system, from which the remainder of the Study structure can be generated. The Product record can then be seen in the Study Management section of the PhlexTMF application as below:

Create the Protocol (Study) attribute value

To create the Protocol, a POST will be made to the attributes/protocol/values resource. When creating a Protocol, it is required to specify the Product and also the Filing Structure that the study is to use for indexing the documentation.

Request

POST https://client-api.phlextmf.com/attributes/v5/attributes/protocol/values HTTP/1.1
Host: client-api.phlextmf.com
Content-Type: application/json
Authorization: Bearer eyJhbGci....

{
    "value":"APITestProtocol1",
    "status":"1",
    "relations":{"product":"API Test"},
    "links":{"filingstructure":"TMF Reference Model V3"}
}

The relations value specified is the Product record (API Test) which is above Protocol in the tree and is the Product under which this Protocol will be created. The links value specifies the linked Filing Structure for this study, which configures the Filing Structure the study is to use.

A Protocol can only have one Filing Structure

The response from this call generates the Protocol and returns the generated entity:

Response

HTTP/1.1 201 Created

{
  "attributeId": 5,
  "id": 1214,
  "attributeDisplayName": "Protocol",
  "value": "APITestProtocol1",
  "sortOrder": null,
  "description": null,
  "helpContent": "",
  "processHelpContent": "",
  "processHelpLink": "",
  "status": 1
}

The Protocol is then represented within Study Management in the PhlexTMF application:

Add Countries to a Protocol

PhlexTMF is pre-configured with a standard list of Countries representing Phlexglobal's Gold Data, however depending upon the requirements, this can be modified, added to or replaced by a list based upon the client's requirements. Once a Country value is in use however, it cannot be removed. Adding a new Country value or linking an existing Country value to a Protocol works in the same way:

Request

POST https://client-api.phlextmf.com/attributes/v5/attributes/country/values HTTP/1.1
Host: client-api.phlextmf.com
Content-Type: application/json
Authorization: Bearer eyJhbGci....

{
    "value":"UNITED KINGDOM",
    "status":"1",
    "relations":{"product":"API Test","protocol":"APITestProtocol1"}
}

Response

HTTP/1.1 201 Created

{
  "attributeId": 7,
  "id": 201902483,
  "attributeDisplayName": "Country",
  "value": "UNITED KINGDOM",
  "sortOrder": null,
  "description": null,
  "helpContent": "",
  "processHelpContent": "",
  "processHelpLink": "",
  "status": 1
}

Unlike Site values, the Country attribute values are shared between Protocols. Therefore it is expected that Country values are reused and it is expected that the Country ID value for UNITED KINGDOM in one study will be the same as that for a different study.

Once added, the Country will appear underneath the Protocol within Study Management:

Creation of a Protocol will automatically add the N/A Country and N/A Site attribute values. These values are required by the system for Country and Trial level documents for which one or both of these values would not be applicable.

Creation of a Clinical Site

The last step in creating a full Protocol tree is the creation of the first Clinical Site. The creation of a Site requires that the Product, Protocol and Country relations are specified.

The system will allow for documents to be filed at Trial or Country level before the first Site is created.

Request

POST https://client-api.phlextmf.com/attributes/v5/attributes/site/values HTTP/1.1
Host: client-api.phlextmf.com
Content-Type: application/json
Authorization: Bearer eyJhbGci....

{
    "value":"0001: Smith",
    "status":"1",
    "relations":{"product","API Test","protocol":"APITestProtocol1","country":"UNITED KINGDOM"}
}

Response

HTTP/1.1 201 Created

{
  "attributeId": 8,
  "id": 1216,
  "attributeDisplayName": "Site-PI",
  "value": "0001: Smith",
  "sortOrder": null,
  "description": null,
  "helpContent": "",
  "processHelpContent": "",
  "processHelpLink": "",
  "status": 1
}

The API calls demonstrated above are simple examples of what is possible with the Attributes API and creates attribute values in the "Active" status. Should an implementation require the values be created in a status other than Active, this should be supplied in the POST. Details can be found in the API Reference.

Creation of a Document Record

The first step in adding a document into PhlexTMF is to create a POST to the Documents endpoint within the Documents service, accessible from the following URI:

https://client-api.phlextmf.com/documents/v5/documents

Creation of a document record requires a minimum set of Metadata. The example below shows the metadata required in a basic system to create a placeholder, however further metadata may be required in order to progress the document to Final. It is required to specify the Attribute Value ID of the metadata values when creating the document record.

Request

POST https://client-api.phlextmf.com/documents/v5/documents HTTP/1.1
Host: client-api.phlextmf.com
Content-Type: application/json
Authorization: Bearer eyJhbGci....

{
    "metadata":\[
        {"id":"4","AttributeId":"2","AttributeDisplayName":"Filing Structure","Value":"TMF Reference Model V3"},
        {"id":"1213","AttributeId":"3","AttributeDisplayName":"Product","Value":"API Test"},
        {"id":"1214","AttributeId":"5","AttributeDisplayName":"Protocol","Value":"APITestProtocol1"},
        {"id":"15","AttributeId":"6","AttributeDisplayName":"File Type","Value":"SITE"},
        {"id": 77,"AttributeId":"9", "AttributeDisplayName": "Zone", "Value": "05 Site Management" },
        {"id": 91, "AttributeId": 10, "AttributeDisplayName": "Section", "Value": "05.04 Site Management" },
        {"id": 469, "AttributeId": 11, "AttributeDisplayName": "Artifact", "Value": "05.04.03 Monitoring Visit Report" },
        {"id": 910, "AttributeId": 32, "AttributeDisplayName": "Sub Artifact", "Value": "Monitoring Visit Report" },
        {"id": 110000000142, "AttributeId": 7, "AttributeDisplayName": "Country", "Value": "UNITED KINGDOM" },
        {"id": 1216, "AttributeId": 8, "AttributeDisplayName": "Site-PI", "Value": "0001: Smith" }
    \]
}

Response

HTTP/1.1 201 Created

{
  "id": 155,
  "filename": "PTPTPT-155-D-",
  "nativeFileName": "",
  "fileSize": 0,
  "mimeType": "application/msword",
  "metadata": [
  ],
  "audits": [],
  "links": [],
  "queries": [],
  "uploadEndpoints": [
    {
      "location": "https://client-api.phlextmf.com/documents/v5/Files/155",
      "endpointType": 0,
      "params": {}
    }
  ],
  "downloadEndpoints": [
    {
      "pdfLocation": "https://client-api.phlextmf.com/documents/v5/Files/123?native=false&watermark=false",
      "pdfWatermarkLocation": "https://client-api.phlextmf.com/documents/v5/Files/123?native=false&watermark=true",
      "nativeLocation": "https://client-api.phlextmf.com/documents/v5/Files/123?native=true",
      "endpointType": 0,
      "params": null
    }
  ]
}

Document Fulfilment

The document record now needs a file uploading to complete the process and start the document processing workflow. In order to upload a file, issue a PUT request to the Files endpoint, specifying the document ID in the URL and the filename in the HTTP headers. The Content-Type header should be set to the correct MIME type for the document being sent and the filename must include the extension. The body of the PUT is the binary data of the file being uploaded.

An example PUT is as below:

Request

PUT https://client-api.phlextmf.com/documents/v5/files/155 HTTP/1.1
Host: client-api.phlextmf.com
Authorization: Bearer eyJhbGci....
Content-Type: application/pdf
fileName: document.pdf

Binary Data

A HTTP 204 status response indicates a successful submission.

Response

HTTP/1.1 204 OK

The resulting document is then visible in the PhlexTMF User Interface.

Generate an Authentication Token​

Create the Attribute Values​

Create the Product attribute value​

Create the Protocol (Study) attribute value​

Add Countries to a Protocol​

Creation of a Clinical Site​

Creation of a Document Record​

Document Fulfilment​

Generate an Authentication Token

Create the Attribute Values

Create the Product attribute value

Create the Protocol (Study) attribute value

Add Countries to a Protocol

Creation of a Clinical Site

Creation of a Document Record

Document Fulfilment