Stages Documentation

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
712:collector_data_rest_api [2025/09/16 08:15] – [Ready to use REST API Data collectors] Iseler, Marc712:collector_data_rest_api [2026/02/18 09:33] (current) – [Cross-Origin Resource Sharing] Deutschmann, Niklas
Line 5: Line 5:
 To use a REST API endpoint a Stages User needs to install a respective Data collector first. By default there are no REST endpoints available. A data collector is technically realized via an Admin Job. Every Admin Job is populating exactly one REST endpoint. To use a REST API endpoint a Stages User needs to install a respective Data collector first. By default there are no REST endpoints available. A data collector is technically realized via an Admin Job. Every Admin Job is populating exactly one REST endpoint.
  
-{{ :712:datacollectorprocess.png?direct }}+{{ :712:data_collector_process.png?direct }}
  
 The framework allows to retrieve data for one or more workspaces in one call. Every call always requires an API token which is equipped with sufficient permissions to access the data provided by a REST API endpoint. The framework allows to retrieve data for one or more workspaces in one call. Every call always requires an API token which is equipped with sufficient permissions to access the data provided by a REST API endpoint.
Line 19: Line 19:
   * Configure server for API token generation (see [[712:api-tokens]])   * Configure server for API token generation (see [[712:api-tokens]])
   * As a user with MODEL-license create an API token  in User Settings > Security and Privacy   * As a user with MODEL-license create an API token  in User Settings > Security and Privacy
 +    * when the API token is used a user-session for this user is created and a user-license is used
   * The user needs to be equipped at least with the permission   * The user needs to be equipped at least with the permission
     * Domain: Collector Data     * Domain: Collector Data
Line 39: Line 40:
 With the following command you then can query for the current license usage: With the following command you then can query for the current license usage:
  
-<code>+<code bash>
 curl -H "Authorization: Bearer <accessToken>" "<stages-URL>/stages/api/1/collectordata/licenseUsage" curl -H "Authorization: Bearer <accessToken>" "<stages-URL>/stages/api/1/collectordata/licenseUsage"
 </code> </code>
Line 45: Line 46:
 The result may look like the following example: The result may look like the following example:
  
-<code>+<code javascript>
 { {
     "workspaceId": "1",     "workspaceId": "1",
Line 94: Line 95:
 With the following command you then can query for the list of all Roles of //all Workspaces//: With the following command you then can query for the list of all Roles of //all Workspaces//:
  
-<code>+<code bash>
 curl -H "Authorization: Bearer <accessToken>" "<stages-URL>/stages/api/1/collectordata/allRoles" curl -H "Authorization: Bearer <accessToken>" "<stages-URL>/stages/api/1/collectordata/allRoles"
 </code> </code>
Line 100: Line 101:
 To query the list of roles for a specific workspace add the workspace ID as additional parameter: To query the list of roles for a specific workspace add the workspace ID as additional parameter:
  
-<code>+<code bash>
 curl -H "Authorization: Bearer <accessToken>" "<stages-URL>/stages/api/1/collectordata/allRoles/65" curl -H "Authorization: Bearer <accessToken>" "<stages-URL>/stages/api/1/collectordata/allRoles/65"
 </code> </code>
Line 106: Line 107:
 The result may look like the following example: The result may look like the following example:
  
-<code>+<code javascript>
 { {
         "workspaceId": "65",         "workspaceId": "65",
Line 128: Line 129:
 To deploy this, download the data collection script, extract the .js-file and modify the following line adjusted to your workspace hierarchy. The script will process recursively all workspaces below this given workspace: To deploy this, download the data collection script, extract the .js-file and modify the following line adjusted to your workspace hierarchy. The script will process recursively all workspaces below this given workspace:
  
-<code>+<code javascript>
 const projectPath = "Company|Samples|Programs and Projects"; const projectPath = "Company|Samples|Programs and Projects";
 </code> </code>
Line 143: Line 144:
 With the following command you then can query for the list of all Roles with Activities for Workspace with ID 65: With the following command you then can query for the list of all Roles with Activities for Workspace with ID 65:
  
-<code>+<code bash>
 curl -H "Authorization: Bearer <accessToken>" "<stages-URL>/stages/api/1/collectordata/allRolesWithActivities/65" curl -H "Authorization: Bearer <accessToken>" "<stages-URL>/stages/api/1/collectordata/allRolesWithActivities/65"
 </code> </code>
Line 149: Line 150:
 The result may look like the following example: The result may look like the following example:
  
-<code>+<code javascript>
 ... ...
 "allRoles": [ "allRoles": [
Line 216: Line 217:
 === Reading the data (single value) === === Reading the data (single value) ===
  
-<code ->+<code>
 GET /stages/api/1/collectordata/demoKey/1 GET /stages/api/1/collectordata/demoKey/1
 </code> </code>
Line 230: Line 231:
 === Reading the data (multiple records) === === Reading the data (multiple records) ===
  
-<code ->+<code>
 GET /stages/api/1/collectordata/demoKey?wsFilter=1&wsFilter=2 GET /stages/api/1/collectordata/demoKey?wsFilter=1&wsFilter=2
 </code> </code>
Line 266: Line 267:
 </code> </code>
  
 +==== Cross-Origin Resource Sharing ====
 +Starting with Stages 7.12.5, CORS (Cross-Origin Resource Sharing) can be configured for collector data API requests. This configuration change is **only** needed when another web application needs to make **client-side HTTP requests** to the API (because the same-origin policy is only enforced in web browsers)
  
 +The following configuration can be added to ''web-customer.xml'' (at the beginning right after the opening ''<web-app>'' tag). The ''cors.allowed.origins'' parameter can **not** be set to "*", so you can not allow API requests from any origin.
 +<code xml>
 +<filter>
 +    <filter-name>CorsFilter</filter-name>
 +    <filter-class>org.apache.catalina.filters.CorsFilter</filter-class>
 +    <init-param>
 +        <!-- URLs of the web applications (comma-separated) for which API requests should be allowed -->
 +        <param-name>cors.allowed.origins</param-name>
 +        <param-value>https://stages-api-client1.example.com, https://stages-api-client2.example.com</param-value>
 +    </init-param>
 +    <init-param>
 +        <param-name>cors.support.credentials</param-name>
 +        <param-value>true</param-value>
 +    </init-param>
 +    <init-param>
 +        <param-name>cors.allowed.methods</param-name>
 +        <param-value>GET,OPTIONS</param-value>
 +    </init-param>
 +    <init-param>
 +        <param-name>cors.allowed.headers</param-name>
 +        <param-value>Origin,Authorization</param-value>
 +    </init-param>
 +</filter>
 +<filter-mapping>
 +    <filter-name>CorsFilter</filter-name>
 +    <url-pattern>/api/1/collectordata/*</url-pattern>
 +</filter-mapping>
 +</code>
 +
 +**Testing your configuration:**
 +
 +The best way to test the configuration:
 +  * Go to the website that should be the origin of the API requests (https://stages-api-client1.example.com in the example above)
 +  * Open the browser's developer tools (F12)
 +  * In the "Console" tab, execute the following request
 +
 +<code>
 +fetch("https://<Stages Server URL>/stages/api/1/collectordata/<Record Key>", { headers: { "Authorization": "Bearer <API Token>" }}).then(r => r.json()).then(console.log);
 +</code>