Table of Contents

Collector Data REST API

The REST API feature provides a framework to create customized REST API endpoints each designed to serve a specific use case. This allows to extract structured information (JSON) from Stages for usage in external systems in a flexible, secure and easy-to-use way.

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.

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

Installation and Deployment

License Usage

This data collector provides information about the current usage of Stages user licenses. To deploy this download the data collection script here, extract the .js-file and create an Admin Job with the following properties: 

Name: Data Collector - License Usage
Cron Expression: 0 * * ? * *

Make sure the API token user owns the permissions: Domain User, Operations Read and Modify

With the following command you then can query for the current license usage: 

curl -H "Authorization: Bearer <accessToken>" "<stages-URL>/stages/api/1/collectordata/licenseUsage"

The result may look like the following example: 

{
    "workspaceId": "1",
    "value": {
        "licenses": [
            {
                "name": "Process Modeler (MODEL) (floating)",
                "type": "FLOATING",
                "totalLicenses": 7,
                "usedLicenses": 5
            },
            {
                "name": "Project Manager (floating)",
                "type": "FLOATING",
                "totalLicenses": 50,
                "usedLicenses": 34
            },
            {
                "name": "Process Participant (PART) (floating)",
                "type": "FLOATING",
                "totalLicenses": 200,
                "usedLicenses": 149
            },
            {
                "name": "Administrator (ADM)",
                "type": "NAMED",
                "totalLicenses": 1,
                "usedLicenses": 0
            }
        ],
        "dataCollectionTimestamp": "2025-09-11T14:44:00.085Z"
    }
}

All Roles

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: 

Name: Data Collector - allRoles
Cron Expression: 0 0 23 ? * FRI

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: 

curl -H "Authorization: Bearer <accessToken>" "<stages-URL>/stages/api/1/collectordata/allRoles"

To query the list of roles for a specific workspace add the workspace ID as additional parameter: 

curl -H "Authorization: Bearer <accessToken>" "<stages-URL>/stages/api/1/collectordata/allRoles/65"

The result may look like the following example: 

{
        "workspaceId": "65",
        "value": {
            "workspaceName": "Samples",
            "rolesCount": 1,
            "allRoles": [
                {
                    "roleName": "Process owner",
                    "roleURL": "/stages/#/workspace/65/_wv/(process/role/_kLjy0AGYtaO_ysHItgOztg)",
                    "roleIdentity": "_kLjy0AGYtaO_ysHItgOztg"
                }
            ]
        }
    }

All Roles with associated Activities

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: 

const projectPath = "Company|Samples|Programs and Projects";

Then create an Admin Job with the following properties to update the list of roles every Friday night: 

Name: Data Collector - allRolesWithActivities
Cron Expression: 0 0 23 ? * FRI

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: 

curl -H "Authorization: Bearer <accessToken>" "<stages-URL>/stages/api/1/collectordata/allRolesWithActivities/65"

The result may look like the following example: 

...
"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"
                    }
                ]
            }
        },...

Data Retrieval via http GET

Query a single JSON value that was stored for the given key and workspace ID: 

GET /stages/api/1/collectordata/{key}/{workspaceId}

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 

GET /stages/api/1/collectordata/{key}?wsFilter=id1&wsFilter=id2&wsFilter=id3

Querying a data-collector without specifying one or multiple workspaces returns all available JSON data structures 

GET /stages/api/1/collectordata/{key}

Creating customized REST endpoints

The data is populated in the REST API endpoint through the execution of 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

Writing the data

// Create a data store and require Read+Modify, Users, Open permissions for the created records
const store = commands.getDataStore("USERS", "OPEN", "RM");
 
// Write a JSON object for the key and workspace ID 1
store.put("myDemoKey", 1, { greeting: "Hello World" });
 
// Write a JSON object for the key and workspace ID 2
store.put("myDemoKey", 2, { greeting: "Hello Mary" });

Reading the data (single value)

GET /stages/api/1/collectordata/demoKey/1

returns 

{ greeting: "Hello World" }

Required permissions: R, Collector Data, Open and RM Users, Open on workspace 1

Reading the data (multiple records)

GET /stages/api/1/collectordata/demoKey?wsFilter=1&wsFilter=2

returns 

[
    {
        workspaceId: 1,
        value: {
            greeting: "Hello World"
        }
    },
    {
        workspaceId: 2,
        value: {
            greeting: "Hello Mary"
        }
    }
]

Required permissions: R, Collector Data, Open and RM Users, Open on workspaces 1 and 2. When the permission is only present for some of the workspaces, a filtered list will be returned!

Rate Limiting

By default, requests to the Collector Data REST API are rate-limited to 100 requests per minute for each API token. You can change the limits using config properties: 

<!-- Maximum number of requests allowed in a unit of time (default: 100) -->
<property name="restapi.ratelimit.maxRequests" value="100" />
<!-- Duration of a unit of time in seconds (default: 60) -->
<property name="restapi.ratelimit.period.inSeconds" value="60" />