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/15 08:43] – [Ready to use REST API Data collectors] Iseler, Marc712:collector_data_rest_api [2025/09/24 14:50] (current) – Filpes, Claudia
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?400|}}+{{ :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.
 +
  
 ==== Ready to use REST API Data collectors ==== ==== Ready to use REST API Data collectors ====
Line 13: Line 14:
   * **License Usage** data collector: {{ :712:apicollector_licenseusage.zip |download-link}}   * **License Usage** data collector: {{ :712:apicollector_licenseusage.zip |download-link}}
   * **All Roles** data collector: {{ :712:apicollector_allroles.zip |download-link}}   * **All Roles** data collector: {{ :712:apicollector_allroles.zip |download-link}}
-  * **All Roles with associated Activities** data collector: download-link+  * **All Roles with associated Activities** data collector: {{ :712:apicollector_allroleswithactivities.zip |download-link}}
  
 ==== Installation and Deployment ==== ==== Installation and Deployment ====
   * 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 38: 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 44: 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 79: Line 81:
 </code> </code>
  
-==== Data Population via Administrative Jobs ====+==== All Roles ====
  
-The data is populated in the REST API endpoint through the execution of [[:711:admin_jobs|Administrative Jobs]] scripts. Each Admin job is designed to handle a specific use case, exporting relevant data and storing it at the endpoint for retrieval.+This data collector provides a list of all roles contained in a workspaces valid version.  
 +To deploy this download the data collection script, extract the .js-file and create an Admin Job with the following properties to update the list of roles every Friday night:
  
-{{:712:datacollectorprocess.png?400|}}+<code> 
 +Name: Data Collector - allRoles 
 +Cron Expression: 0 0 23 ? * FRI 
 +</code>
  
-These Admin job scripts are fully customizable, and additional scripts can be developed to support new use cases. Please contact one of our consultants to customize scripts for your specific needs.+Make sure the API token user owns the permissions: Domain **Workspaces**, Operations **Read**
  
 +With the following command you then can query for the list of all Roles of //all Workspaces//:
  
 +<code bash>
 +curl -H "Authorization: Bearer <accessToken>" "<stages-URL>/stages/api/1/collectordata/allRoles"
 +</code>
  
-==== Methods ====+To query the list of roles for a specific workspace add the workspace ID as additional parameter:
  
-  * Classes and methods for writing data are described in the JavaScript API documentation (link inside Stages on Administration Page > Further Information)+<code bash> 
 +curl -H "Authorization: Bearer <accessToken>" "<stages-URL>/stages/api/1/collectordata/allRoles/65" 
 +</code>
  
-''GET /stages/api/1/collectordata/{key}/{workspaceId}''+The result may look like the following example:
  
-Returns the single JSON value that was stored for the given key and workspace ID+<code javascript> 
 +{ 
 +        "workspaceId": "65", 
 +        "value": { 
 +            "workspaceName": "Samples", 
 +            "rolesCount": 1, 
 +            "allRoles": [ 
 +                { 
 +                    "roleName": "Process owner", 
 +                    "roleURL": "/stages/#/workspace/65/_wv/(process/role/_kLjy0AGYtaO_ysHItgOztg)", 
 +                    "roleIdentity": "_kLjy0AGYtaO_ysHItgOztg" 
 +                } 
 +            ] 
 +        } 
 +    } 
 +</code>
  
-''GET /stages/api/1/collectordata/{key}?wsFilter=id1&wsFilter=id2&wsFilter=id3...''+==== All Roles with associated Activities ====
  
-Returns the list of scoped key-value pairs for the given key and the workspaces with the given IDs. When the list of workspace IDs is empty, all matching key-value pairs will be returned. A scoped key-value pair is a JSON object with the following properties+This data collector provides a list of all roles contained in the valid version of a workspace (ignores Reference models). Every role entry shows the associated Activities grouped by the RASIC-association type. 
 +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:
  
-  * ''workspaceId'' +<code javascript> 
-  * ''value''+const projectPath = "Company|Samples|Programs and Projects"; 
 +</code> 
 + 
 +Then create an Admin Job with the following properties to update the list of roles every Friday night: 
 + 
 +<code> 
 +Name: Data Collector - allRolesWithActivities 
 +Cron Expression: 0 0 23 ? * FRI 
 +</code> 
 + 
 +Make sure the API token user owns the permissions: Domain **Processes**, Operations **Read** 
 + 
 +With the following command you then can query for the list of all Roles with Activities for Workspace with ID 65: 
 + 
 +<code bash> 
 +curl -H "Authorization: Bearer <accessToken>" "<stages-URL>/stages/api/1/collectordata/allRolesWithActivities/65" 
 +</code> 
 + 
 +The result may look like the following example: 
 + 
 +<code javascript> 
 +... 
 +"allRoles": [ 
 +        { 
 +            "roleName": "CCB: Change Control Board", 
 +            "roleURL": "/stages/#/workspace/166/V2.8%20%28tailored%29/(process/role/_ciNhEFCC-Bq_ysHItgOztg)", 
 +            "roleIdentity": "_ciNhEFCC-Bq_ysHItgOztg", 
 +            "roleTailoringStatus": "Not tailored", 
 +            "roleAssociations": { 
 +                "Responsible": [ 
 +                    { 
 +                        "activityName": "Approve Change Request", 
 +                        "activityURL": "/stages/#/workspace/166/V2.8%20%28tailored%29/(process/activity/_raw44Ohgtje_ysHItgOztg)", 
 +                        "activityIdentity": "_raw44Ohgtje_ysHItgOztg", 
 +                        "activityTailoringStatus": "Not tailored" 
 +                    } 
 +                ] 
 +            } 
 +        },... 
 +</code> 
 + 
 + 
 +==== Data Retrieval via http GET ==== 
 + 
 +Query a single JSON value that was stored for the given key and workspace ID: 
 + 
 +<code> 
 +GET /stages/api/1/collectordata/{key}/{workspaceId} 
 +</code> 
 + 
 +Query JSON-data-structures for multiple workspaces at once which returns the list of scoped key-value pairs for the given key and the workspaces with the given IDs 
 + 
 +<code> 
 +GET /stages/api/1/collectordata/{key}?wsFilter=id1&wsFilter=id2&wsFilter=id3 
 +</code> 
 + 
 +Querying a data-collector without specifying one or multiple workspaces returns all available JSON data structures 
 + 
 +<code> 
 +GET /stages/api/1/collectordata/{key} 
 +</code> 
 + 
 +==== Creating customized REST endpoints ==== 
 + 
 +The data is populated in the REST API endpoint through the execution of [[:712:admin_jobs|Administrative Jobs]] scripts. Each Admin job is designed to handle a specific use case, exporting relevant data and storing it at the endpoint for retrieval. 
 + 
 +These Admin job scripts are fully customizable, and additional scripts can be developed to support new use cases. Please contact one of our consultants to customize scripts for your specific needs.
  
 +For customizing data collector scripts on your own you can find the comprehensive Stages internal API documentation on the Administration Start page > section "Further information".
  
 ==== Example ==== ==== Example ====
Line 122: 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 136: 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>