Retrieve usages
Returns the usages for an activity definition.
Tip
Check the Swagger page for more technical information on the endpoints.
Endpoint details
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/activity-structure-versions/{structureVersionId}/levels/{level}/activity-definitions/{activityDefinitionReference}/usages
Headers: Authorization: Bearer {token}, User-Agent: {agent}
Scope: connector-protimeapi-activity-definitions.read
URL parameters
These parameters need to be filled in when calling this endpoint.
| Parameter | Description |
|---|---|
<structureVersionId> |
The ID of the activity structure. The ID can be found in the configuration in myProtime. |
<level> |
Defines the level in the structure. |
<activityDefinitionReference> |
The internal ID or an external reference. |
Response properties
| Field | Type | Required | Writable | Description |
|---|---|---|---|---|
changeVersion |
string | Yes | Read-only | Property to indicate the order of changes. |
activityDefinitionId.id |
guid | Yes | Read-only | Unique identifier for the activity definition. |
usages.activityUsageKind |
string | Yes | Yes | The kind of usage: Circle, Group, or Person. |
usages.usageReference.id |
integer | Yes | Yes | The reference ID for the usage (circle, group, or person). |
usages.from |
date | Yes | Yes | Start date (YYYY-MM-DD) for the usage. |
usages.until |
date | No | Yes | End date (YYYY-MM-DD) for the usage. If not set, usage is open-ended. |
External references
The endpoint supports predefined and custom external references. See the external references page for details.
The following collections are supported for this endpoint:
| Collection | Predefined | Custom |
|---|---|---|
activity-definitions |
@data-entry-code, @external-reference |
Supported |
circles |
None | Supported |
groups |
None | Supported |
people |
@badge-number, @employee-number |
Supported |
Caution
There are some restrictions on the characters allowed in URL requests. See the fetching resources page for more information.
Error responses
| Status | Condition |
|---|---|
400 |
Invalid external reference format |
404 |
Activity definition not found |
Examples
Retrieve usages with internal ID
Example retrieving usages for activity definition with internal ID 38fc2206-b51f-434a-9c36-9e0esfc5e70e:
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/activity-structure-versions/b2347a7a-d60d-446f-b03b-7es2cc8c3281/levels/3/activity-definitions/38fc2206-b51f-434a-9c36-9e0esfc5e70e/usages
Retrieve usages with external reference
Example retrieving usages with data entry code 30002:
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/activity-structure-versions/b2347a7a-d60d-446f-b03b-7es2cc8c3281/levels/3/activity-definitions/30002/usages?externalReferences=(activity-definitions,@data-entry-code)
Retrieve with external reference in response
Example retrieving usages with internal ID 38fc2206-b51f-434a-9c36-9e0esfc5e70e and requesting data entry code in response:
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/activity-structure-versions/b2347a7a-d60d-446f-b03b-7es2cc8c3281/levels/3/activity-definitions/38fc2206-b51f-434a-9c36-9e0esfc5e70e/usages?externalReferences=(activity-definitions,@data-entry-code)