Retrieve an activity definition
Returns a single activity definition record by its internal ID or external reference.
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}
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. Can be found in the configuration in myProtime. |
<level> |
Defines the level in the structure. |
<activityDefinitionReference> |
The internal ID (GUID) or an external reference of the activity definition. |
Response properties
| Field | Type | Required | Writable | Description |
|---|---|---|---|---|
id |
Guid | Yes | Read-only | Unique identifier (GUID) for the activity definition. |
structureVersion |
Guid | Yes | Read-only | Identifier for the activity structure version. Links the definition to a specific structure configuration. |
level |
integer | Yes | Read-only | Level of the activity definition in the configured structure. |
changeVersion |
string | — | Read-only | Property to indicate the order of changes. |
name.default |
string | Yes | Yes | Default name value of the activity definition. Shown to users if no translation is available. |
name.translations |
object | No | Yes | A list of translated names by language code. Allows localization for different languages. |
parent.id |
Guid | No | Yes | Unique identifier of the parent activity definition in a hierarchy set-up. |
parent.externalReferences |
object | No | — | External references for the parent activity definition (when external references are requested). |
shortCode |
string | No | Yes | Short code for the activity definition. |
dataEntryCode |
string | No | Yes | Data entry code for the activity definition, mostly used on hardware devices. Mandatory or optional depending on configuration. Can only be 16 characters long! |
externalReference |
string | No | Yes | External reference identifier for the activity definition. Needs to be unique within the structure and level when used! Can only be 16 characters long! |
info |
string | No | Yes | Additional information about the activity definition. Can be used for notes or extra details. |
activeFrom |
date | No | Yes | Start date (YYYY-MM-DD) when the activity definition is active. Controls when the definition becomes available for registrations. |
activeUntil |
date | No | Yes | End date (YYYY-MM-DD) when the activity definition is no longer active. Controls when the definition is no longer available. |
usages |
object | — | Read-only | Activity definition usages. Only returned when ?expand=usages is specified. |
restrictions |
object | — | Read-only | Activity definition restrictions. Only returned when ?expand=restrictions is specified. |
Activity Definition Reference
In the endpoints, the term activityDefinitionReference refers to an activity definition identifier, which can be either an internal ID or an external reference.
Expand with Usages and Restrictions
You can expand your request to include usages and restrictions by adding the expand filter to your request. There’s also a possibility to request usages and restrictions via separate endpoints:
Example with expand:
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?expand=usages,restrictions
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 |
activity-usages |
— | Supported (with ?expand=usages) |
activity-restrictions |
— | Supported (with ?expand=restrictions) |
Caution
There are some restrictions on the characters allowed in URL requests. See the fetching resources page for more information.
Error responses
| Status code | Description |
|---|---|
| 400 | Bad request. The external reference is invalid or malformed. |
| 401 | Unauthorized. The bearer token is missing, expired, or invalid. |
| 404 | Not found. The specified activity definition does not exist. |
Examples
Retrieve one activity definition
Example retrieving an 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
Retrieve with external reference and expand
Example retrieving with data entry code 00026 and expand:
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/activity-structure-versions/b2347a7a-d60d-446f-b03b-7es2cc8c3281/levels/3/activity-definitions/00026?externalReferences=(activity-definitions,@data-entry-code)&expand=usages,restrictions