Get Started

Be the First to Know:

Sign Up for Exclusive Updates!

Frontend Installation

The frontend serves as the entrance gate for users to access DCP. Depending on the required modules, some steps in the installation guide below may be skipped or repeated multiple times.

Prerequisite: Install Dependencies

Ensure your server meets the software dependencies required by DCP.

Ensure that Node.js version 16.x is installed. Newer version are currently not supported.

Ensure that Git is installed.

Step 1: Clone Repository

Clone the repository of the DCP Framework or the corresponding module from our Public Repositories.

git clone https://gitlab.com/roche/dcp/platform/frontend/apps/{path_to_component}

Step 2: Execute Installation

After switching into the cloned folder, initiate the installation with npm by using the following command:

npm install --force

Step 3: Create settings file

Define the settings of your instance by pasting and adjusting the following content into the settings.json file in the root folder.

{
	"apiUrl": "test.example.com",
	"baseAppUrl":"test-example.com",
	"apiEnv": "prod",
	"production": true,
	"privacyPolicyUrl":"test",
	"backendPortCheckUrl":"8181",
	"apiServiceUrl":"gxp-api-node.example.com"
}

Step 4: Update deploy URL

Update the deploy URL in the angular.json file.

Step 5: Trigger app build

Start the build of your instance by executing the following command in the root directory:

npm run build

Done: Successfully deployed

After completion of the app build, your app is available under your defined URL. To learn more about the configuration options during installation, please refer to:

Documentation for Developers

Backend Installation

Welcome to the guide on setting up the backend.

Depending on the module, either .NET Framework or .NET need to be installed.

.NET Framework

Prerequisites

In your build environment, ensure that the .NET Framework SDK for the project target (4.8) is installed. Build environment requires internet access in order to restore the packages.

Step 1: Clone Repository

Clone the repository of the DCP Framework or the corresponding module from our Public Repositories.

git clone https://gitlab.com/roche/dcp/platform/backend/{path_to_component}

Step 2: Configure App Settings

Rename the example configurations appsettings.example.json to appsettings.json and adjust the the settings according to your needs.

.NET

Prerequisites

In your build environment , ensure that the .NET SDK for the project target (usually .NET 8) is installed. Build environment requires internet access in order to restore the packages.

Step 1: Clone Repository

Clone the repository of the DCP Framework or the corresponding module from our Public Repositories.

git clone https://gitlab.com/roche/dcp/platform/backend/{path_to_component}

Step 2: Configure App Settings

Rename the example configurations appsettings.example.json to appsettings.json and adjust the the settings according to your needs.

Step 3: Update Package Registry

Add the DCP package registry to the list of known sources:

dotnet nuget add -Name "DCP" -Source "https://gitlab.com/api/v4/projects/56986357/packages/nuget/index.json" -UserName {your_username} -Password {your_token}

Step 4: Building the App

Build the solution by running:

msbuild DigitalClonePlatformCore.sln

Step 4: Copy Files

Copy the content of the build output to the wwwroot folder of your server

Backend Installation

Welcome to the guide on setting up the backend.

In case your server is not connected to the internet, a different installation approach needs to be followed.

Online Installation

Prerequisites

Ensure that R and devtools are installed.

Step 1: Install Package

Execute the following command to install your desired package:

devtools::install_gitlab(repo = "roche/dcp/analytical-core/r-language/{path_to_repo}")

Offline Installation

Step 1: Clone Repository

Clone the repo on a computer with internet connectivity and open the project in R Studio.

Step 2: Build Package

Execute the following command to build the package on the server:

devtools::build()

Step 3: Copy Files

Copy the build archive (.tar.gz) to the offline server.

Step 4: Install Package

Execute package installation on the server with the following command:

R CMD INSTALL {archive_file}.tar.gz

Step 5: Restart Server

Complete the installation with restarting the openCPU instance by executing:

systemctl restart httpd

Introduction

Introducing a REST API optimized for efficient data retrieval, with support for all read requests. This API is secured through OAuth, a widely recognized authentication and authorization protocol, to ensure data privacy and access control. Users are required to create dedicated API credentials to access the service, enhancing data security. In the data-centric landscape, this REST API, seamlessly integrated with OAuth and reinforced by dedicated API credentials, serves as a gateway to accessing valuable information with reliability and precision.

Authentication

The following code snippets provide an idea about the required POST requests to obtain an API token.

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.your-domain.tld/core/oauth/token',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => 'grant_type=client_credentials&clientId=your_client_id&clientSecret=your_client_secret',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/x-www-form-urlencoded'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/x-www-form-urlencoded");

var urlencoded = new URLSearchParams();
urlencoded.append("grant_type", "client_credentials");
urlencoded.append("clientId", "your_client_id");
urlencoded.append("clientSecret", "your_client_secret");

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: urlencoded,
  redirect: 'follow'
};

fetch("https://api.your-domain.tld/core/oauth/token", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

import http.client

conn = http.client.HTTPSConnection("https://api.your-domain.tld")
payload = 'grant_type=client_credentials&clientId=your_client_id&clientSecret=your_client_secret'
headers = {
  'Content-Type': 'application/x-www-form-urlencoded'
}
conn.request("POST", "/core/oauth/token", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.your-domain.tld/core/oauth/token");
var collection = new List<KeyValuePair<string, string>>();
collection.Add(new("grant_type", "client_credentials"));
collection.Add(new("clientId", "your_client_id"));
collection.Add(new("clientSecret", "your_client_secret"));
var content = new FormUrlEncodedContent(collection);
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

library(httr)

headers = c(
  'Content-Type' = 'application/x-www-form-urlencoded'
)

body = list(
  'grant_type' = 'client_credentials',
  'clientId' = 'your_client_id',
  'clientSecret' = 'your_client_secret'
)

res <- VERB("POST", url = "https://api.your-domain.tld/core/oauth/token", body = body, add_headers(headers), encode = 'form')

cat(content(res, 'text'))

Token

As response to the authentication POST request, a JSON Web Token (JWT) is issued.

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ...",
    "token_type": "bearer",
    "expires_in": 839,
    "refresh_token": "RsV6fyI4HZAHRwRjYzE74c0gJaFL1fksP...",
    ".issued": "Fri, 16 Feb 2024 13:38:10 GMT",
    ".expires": "Fri, 16 Feb 2024 13:52:10 GMT"
}

As response to the authentication POST request, a JSON Web Token (JWT) is issued.

Find your Endpoint

To ensure data integrity, the DCP API Service is only providing read access to data stored in DCP. It is not allowing to perform write transation. For Basic and each module, specific endpoints are accessible via the DCP API Serivce. Details can be found on the Swagger page hosted on your API.

Example Data Request

In this example, data from the Basic Module is queried, which provides fundamental capabilities to work with time series based data. The corresponding module can easily identified based on the querying url, e.g. https://api.your-domain.tld/{Module_Slug}/{Module_Function}/{Endpoint}.

Requesting Data from Basic

In the following example, a simple GET request will be executed to request the event frames (batches) related to a specific device. The device will be defined via an unique identifier (WebId).

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.your-domain.tld/basic/BatchDataStudio/GetDeviceEventFrames?webId=Your_Device_WebId',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer Your_Access_Token'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer Your_Access_Token");

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("https://api.your-domain.tld/basic/BatchDataStudio/GetDeviceEventFrames?webId=Your_Device_WebId", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

import http.client

conn = http.client.HTTPSConnection("https://api.your-domain.tld")
payload = ''
headers = {
  'Authorization': 'Bearer Your_Access_Token'
}
conn.request("GET", "/basic/BatchDataStudio/GetDeviceEventFrames?webId=Your_Device_WebId", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.your-domain.tld/basic/BatchDataStudio/GetDeviceEventFrames?webId=Your_Device_WebId");
request.Headers.Add("Authorization", "Bearer Your_Access_Token");
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

library(httr)

headers = c(
  'Authorization' = 'Bearer Your_Access_Token'
)

res <- VERB("GET", url = "https://api.your-domain.tld/basic/BatchDataStudio/GetDeviceEventFrames?webId=Your_Device_WebId", add_headers(headers))

cat(content(res, 'text'))

Response Body

The response depends highly on the called endpoint. Thus, each endpoint returns a different data structure of the response body, which can be further processed in third party applications.

{
    "Data": [
        {
            "Id": "EVENT_FRAME_ID",
            "Values": {
                "Attribute": "Value",
            },
            "IntervalInSeconds": 7602.2299957,
            "StartTime": "2024-02-16T10:35:33.2620086Z",
            "EndTime": "2024-02-16T12:42:15.4920043Z",
            "Interval": "02:06:42.2299957"
        }
    ],
    "DataTypes": {
        "Attribute": "Double"
    },
    "WarningCode": 0
}

Response Header

The response header provides important information about the GxP status of the returned data. This information is covered in the isValidated key of the response header. Its value decodes the validation status of each underlying technology layer used to produce the response, e.g. True, False, undefined, undefined.

Those four layers are:

System Backend
Data Source
Calculation Engine
Entity (e.g. Model)