Retrieve an activity definition
Introduction
You can retrieve an activity definition by ID or an external reference using the GET call. The ID is available in the location header after a successful POST call for creating 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}
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
This list of properties is returned by this endpoint.
| Property | Type | Description |
|---|---|---|
changeVersion |
string | Property to indicate the order of changes. |
id |
string | Unique identifier for the activity definition. |
structureVersion |
string | Identifier for the activity structure version. Links the definition to a specific structure configuration. |
level |
integer | Level of the activity definition in the configured structure. |
canConfigureRestrictions |
boolean | Indicates if restrictions can be configured for this definition. |
name.default |
string | Default name value of the activity definition. Shown to users if no translation is available. |
name.translations |
string | A list of translated names by language code. Allows localization for different languages. |
parent.id |
string | Unique identifier of the parent activity definition in a hierarchy set-up. Can only be set during creation! |
shortCode |
string | Short code for the activity definition. |
dataEntryCode |
string | 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 | 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 | Additional information about the activity definition. Can be used for notes or extra details. |
activeFrom |
string | Start date (YYYY-MM-DD) when the activity definition is active. Controls when the definition becomes available for registrations. |
activeUntil |
string | End date (YYYY-MM-DD) when the activity definition is no longer active. Controls when the definition is no longer available. |
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:
Note
Restrictions will not be visible when canConfigureRestrictions = false for the activity definition.
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
It’s possible to use predefined external references and custom external references. More information can be found on the External References Page.
For a list of predefined external references, see the external reference options section.
Note
Check the query options below the endpoint on the Swagger page for the relevant external references.
Caution
There are some restrictions on the characters allowed in URL requests. See the fetching resources page for more information.
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