Activity definitions

Introduction

Through the API there’s a possibility to retrieve, create or update activity definitions.

Tip

Check the Swagger page for more technical information on the endpoints.

Properties

Property	Type	Description
`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.
`externalReference`	string	External reference identifier for the activity definition. Needs to be unique within the structure and level when used!
`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.

Tip

If your configuration requires users to manually enter the data entry code when creating an activity definition, the dataEntryCode field is mandatory and must be provided in the request body. It cannot be null or omitted. If this field is missing, the API will return a 400 Bad Request error. Please ensure you include dataEntryCode when required by your configuration.

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.

Hierarchy

A hierarchy is a structured way to organize and manage complex data by adding order and relationships. For instance, in a multinational organization, tracking an activity might become challenging when every country has a “Sales” department. Instead of using overly detailed names (e.g., “Country - City - Sales”), a hierarchy allows the user to define levels such as Company > Country > Location > Department. This ensures uniqueness and simplifies tasks like filtering reports (e.g., selecting all activities for “Country” with one filter).

Add hierarchy

If you want to add a hierarchy, a parent Id must be included in the request. This ID is available in the location header after a successful POST call for an activity definition.
It’s possible to use predefined or custom external references for the parent.
Hierarchy can only be used when an activity definition is created. Updating an hierarchy isn’t possible.

Note

If you need to update the parent because it was created incorrectly:

Set an end date on the current activity definition to close it.
Create a new activity definition with the correct parent.
Ensure that the necessary references remain unique.

Caution

When you configure a hierarchy for activity definitions, you are also required to set up usage. If no more detailed configuration is needed, you can simply assign the company or an organizational group to the highest level of the hierarchy. Lower levels will automatically inherit the usage from the higher level.

Usage

It is possible to limit the usage of an activity definition. Activity definitions can be used by anyone for whom the structure applies (as defined in the structure configuration). Rights allow you to limit the usage to groups, circles or people.

Restrictions

With restrictions it is possible to restrict the activities a user can select. Some level can be defined to have restrictions on one or more other levels.

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.

Endpoints

Below you can find the supported endpoints for this data collection.

GET an activity definition by reference

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.

GET https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/activity-structure-versions/{structureVersionId}/levels/{levelIndex}/activity-definitions/{activityDefinitionReference}

Example with an internal Id:
GET https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/activity-structure-versions/{structureVersionId}/levels/{levelIndex}/activity-definitions/38fc2206-b51f-434a-9c36-9e0esfc5e70e

Expand with usages and restrictions

You can expand your request to include usages and restrictions by adding the expand filter to your request.

Example to retrieve usages and restrictions:
GET 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=usage,restrictions

POST activity definitions

It is possible to create activity definitions with the POST call.

The location header will contain the activity definition Id.

POST https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/activity-structure-versions/{structureVersionId}/levels/{levelIndex}/activity-definitions

Parameter	Description
`<structureVersionId>`	The Id of the activity structure. The Id can be found in the configuration in myProtime.
`<levelIndex>`	Defines the level in the structure.

Request body

Depending on the configuration in myProtime, add the necessary fields in the request body.

More info can be found on the Configuration page

Example for creating an Activity Definition:

// POST https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/activity-structure-versions/{structureVersionId}/levels/{levelIndex}/activity-definitions
{
  "name": {
    "default": "Cleaning",
    "translations": {
      "nl": "Schoonmaken",
      "fr": "Nettoyer"
    }
  },
  "shortCode": "CL_002",
  "dataEntryCode": "00026",
  "externalReference": "Cleaning",
  "info": "Cleaning the main building",
  "activeFrom": "2024-07-01",
  "activeUntil": "2024-12-31"
}

Example for adding a hierarchy:

{
  "name": {
    "default": "Cleaning",
    "translations": {
      "nl": "Schoonmaken",
      "fr": "Nettoyer"
    }
  },
  "parent": {
    "id": "0b3642ae-16c9-4914-b099-2ba4b99d5ee9"
  },

PUT (create or update) activity definitions by reference

You can use this endpoint to create a new or update an existing activity definition. This behavior depends on the use of the reference, as follows:

If the external reference corresponds to an existing activity definition, that definition will be updated.
If the external reference does not match any existing activity definition, a new one will be created.
Creating or updating activity definitions is only possible using an external reference. When using an internal ID as a reference, only an update is supported since these ID’s are generated during creations and can’t be provided. An update of the activity definition will happen when it already exists, or a “404: not found” error will be responded when the internal ID is not known in our system.

Depending on configuration in myProtime, add the necessary fields in the request body.

Caution

If some other required fields are missing from the request, they will be left empty.

Request when using an activity definition guid (internal Id):
PUT https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/activity-structure-versions/{structureVersionId}/levels/{levelIndex}/activity-definitions/{ActivityDefinitionId}

Request when using an external reference:
PUT https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/activity-structure-versions/{structureVersionId}/levels/{levelIndex}/activity-definitions/{externalReference}?externalReferences=(activity-definitions,{ReferenceName})

Parameter	Description
`<structureVersionId>`	The Id of the activity structure. The Id can be found in the configuration in myProtime.
`<levelIndex>`	Defines the level in the structure.
`<activityDefinitionId>`	The internal Id (GUID) of the activity definition.
`<externalReference>`	A predefined or custom external reference of the activity definition.
`<referenceName>`	Defines the custom or predefined reference name of the activity definition.

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.

Example with a data entry code:
PUT https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/activity-structure-versions/{structureVersionId}/levels/{levelIndex}/activity-definitions/20003?externalReferences=(activity-definitions,@data-entry-code)

Example with a custom external reference:
PUT https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/activity-structure-versions/{structureVersionId}/levels/{levelIndex}/activity-definitions/122456?externalReferences=(activity-definitions,CustomActivityReference)

Behaviour:

If the Id already exists, the activity definition will be updated.
If the Id does not exist, a new activity definition will be inserted.

The behavior depends on the presence of the Id in the system.

Request body

Depending on the configuration in myProtime, add the necessary fields in the request body.

Parent (hierarchy)

If the Id matches an existing activity definition and it has a parent, the parent should be included in the request. Otherwise, a “Bad Request” response will be returned. It’s possible to use an external reference for the parent.

Example for creating/updating an activity definition:

{
  "name": {
    "default": "Cleaning"
  },
  "shortCode": "A003",
  "dataEntryCode": "20003",
  "externalReference": "CL01",
  "info": "Updating Activity Definition",
  "activeFrom": "2024-09-01",
  "activeUntil": "2024-09-30"
}

POST usage on activity definitions

POST https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/activity-structure-versions/{structureVersionId}/levels/{levelIndex}/activity-definitions/{activityDefinitionId}/usages

Parameter	Description
`<structureVersionId>`	The ID of the activity structure. Can be found in the configuration in myProtime.
`<levelIndex>`	Defines the level in the structure.
`<activityDefinitionId>`	The ID available in the location header after a successful POST call for an activity definition.

Request body

Field	Description
`activityUsageKind`	Determines the rights on People, Groups, or Circles.
`usageReference`	ID or a Custom external reference.
`from`	Start date of the usage.
`until`	End date of the usage. If no end date is required, omit “until” or send it as an empty string (`""`).

Example for creating a usage to a circle:

{
  "activityUsageKind": "Circle",
  "usageReference": {
    "id": 13
  },
  "from": "2024-08-01",
  "until": "2024-08-31"
}

PUT usage on activity definitions

PUT https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/activity-structure-versions/{structureVersionId}/levels/{levelIndex}/activity-definitions/{activityDefinitionId}/usages

Parameter	Description
`<structureVersionId>`	The ID of the activity structure. Can be found in the configuration in myProtime.
`<levelIndex>`	Defines the level in the structure.
`<activityDefinitionId>`	The ID available in the location header after a successful POST call for an activity definition.

Request body

Field	Description
`activityUsageKind`	Determines the rights on People, Groups, or Circles.
`usageReference`	ID or a Custom external reference.
`originalFrom`	The existing start date in myProtime. It must match the current value in the system.
`originalUntil`	The existing end date in myProtime. If no end date exists, omit `originalUntil` from the request; otherwise, use the current value.
`updatedFrom`	The new start date for the usage.
`updatedUntil`	The new end date for the usage. If no end date is required, omit `updatedUntil` or send it as an empty string (`""`).

Example for updating a usage to a circle:

{
  "activityUsageKind": "Circle",
  "usageReference": {
    "id": 13
  },
  "originalFrom": "2024-08-01",
  "originalUntil": "2024-08-31",
  "updatedFrom": "2024-08-15",
  "updatedUntil": "2024-08-31"
}

DELETE usage on activity definitions

DELETE https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/activity-structure-versions/{structureVersionId}/levels/{levelIndex}/activity-definitions/{activityDefinitionId}/usages

Parameter	Description
`<structureVersionId>`	The ID of the activity structure. Can be found in the configuration in myProtime.
`<levelIndex>`	Defines the level in the structure.
`<activityDefinitionId>`	The ID available in the location header after a successful POST call for an activity definition.

Request body

Field	Description
`activityUsageKind`	Determines the rights on People, Groups, or Circles.
`usageReference`	ID or a Custom external reference.
`from`	Required start date of the usage.
`until`	End date of the usage. If no date is present, omit `"until"` or send it as an empty string (`""`).

Example for deleting a usage to a circle:

{
  "activityUsageKind": "Circle",
  "usageReference": {
    "id": 13
  },
  "from": "2024-08-01",
  "until": "2024-08-31"
}

PUT restrictions on an activity definition

It is possible to update the restrictions of an activity definition with the PUT call.
PUT https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/activity-structure-versions/{structureVersionId}/levels/{levelIndex}/activity-definitions/{activityDefinitionId}/restrictions

Parameter	Description
`<structureVersionId>`	The ID of the activity structure. Can be found in the configuration in myProtime.
`<levelIndex>`	Defines the level in the structure.
`<activityDefinitionId>`	The ID available in the location header after a successful POST call for an activity definition.

Example for updating restrictions:

"restrictions": [
[
  {
    "levelIndex": 1,
    "activityDefinitions": [
      {
        "id": "a7d853ea-89eb-4735-83d1-b891c6fde398"
      },
      {
        "id": "22d320ed-f6ed-44bd-b7b1-fe58f518960c"
      }
    ]
  },
  {
    "levelIndex": 3,
    "activityDefinitions": [
      {
        "id": "b2593723-9574-4659-8367-706645454367"
      }
    ]
  }
]

Absences

Activities

Counters

People

Activity definitions

Introduction

Properties

Activity definition Reference

Hierarchy

Add hierarchy

Usage

Restrictions

External references

Endpoints

GET an activity definition by reference

Expand with usages and restrictions

POST activity definitions

Request body

PUT (create or update) activity definitions by reference

External references

Request body

Parent (hierarchy)

POST usage on activity definitions

Request body

PUT usage on activity definitions

Request body

DELETE usage on activity definitions

Request body

PUT restrictions on an activity definition