Activities

Activites are the central component of the Activities domain. Each activity can consist of one or more levels. The top level of an activity is called Level 1. After Level 1, the term 'levels' is synonymous with 'sub-level activities.'

Use activities to monitor and react to progress on production, grant, or project work by tracking your employees, capital assets, and materials. Activities provide real-time information to improve decision-making about how to best use your workforce and resources.

Prerequisites

You must create the necessary building blocks before creating activities.

Refer to the Hierarchy of Activities entities section in the Guide to Activities overview for more information.

Pre-defined activities

Pre-defined activities are used to generate activity events that fill the gaps between logged activity events and to account for unpaid breaks.

Note: You cannot edit or delete pre-defined activities.

The system includes the following pre-defined activities:

Pre-defined activityDescription
IDLEIdle activity used by the system to fill gaps between logged activity events.
MEALBREAKUNPAIDMeal Break activity used by the system to account for unpaid, automatic meal breaks.
MEALBREAKPAIDMeal Break activity used by the system to account for paid meal breaks.

Example

In this example, we create, verify, update, and delete an activity query.

Create an activity

When creating an activity, consider the methods that employees will use to enter data:

  • Manual entry of a long name at a data collection device increase the time to complete the form and the chance for error.
  • If employees will use data collection devices with numeric-only keypads or a bar code scanner, the name of the activity must be numeric.

In this example, consider creating an activity that represents a meeting. The request below creates a new level 1 activity named "Example Meeting".

Example request

Call the Create Activity POST /v1/work/activities operation with the following request payload.

{
  "name": "Example Meeting",
  "combinedName": "Example Meeting",
  "searchName": "EXAMPLE MEETING",
  "description": "This activity represents an entity used to track the time spent on a meeting.",
  "level": 1,
  "sequence": 1,
  "isEditableActualStartDate": true,
  "isEditableActualCompleteDate": true,
  "completeStatus": {
    "qualifier": "Incomplete"
  },
  "isEditableCompleteStatus": true,
  "completedPercent": 0,
  "isEditableCompletedPercent": false,
  "heldHistory": {
    "qualifier": "Never Held or Released"
  },
  "isEditableHeldHistory": true,
  "requiredQuantity": 0,
  "isEditableRequiredQuantity": true,
  "completedQuantity": 0,
  "movedQuantity": 0,
  "isEditableMovedQuantity": false,
  "receivedQuantity": 0,
  "isEditableReceivedQuantity": false,
  "autoMoveMultiQuantity": 1,
  "scrappedQuantity": 0,
  "movedToReworkQuantity": 0,
  "unaccountedQuantity": 0,
  "header": {
    "activityType": {
      "qualifier": "Direct"
    },
    "sequenceValidationType": {
      "qualifier": "None"
    },
    "isIncludedCompleteQuantity": true,
    "isIncludedScrappedQuantity": false,
    "isIncludedReworkedQuantity": false,
    "isExtendedCompletionStatus": true,
    "isHoldParent": false,
    "isAutoMoves": false,
    "canBeStartedBeforeStartDate": true,
    "canBeStartedAfterEndDate": true
  },
  "processType": {
    "qualifier": "Run"
  },
  "canBeDefault": true,
  "isExcludedFromSequenceValidation": false,
  "isMilestone": false,
  "priorityType": {
    "qualifier": "Low"
  },
  "laborHoursAllocationType": {
    "qualifier": "Even"
  },
  "minDurationAmount": 72000,
  "maxDurationAmount": 86400000,
  "validateRequiredQuantity": false,
  "requiredVarianceOverPct": 10,
  "validateReceivedQuantity": false,
  "receivedVarianceOverPct": 10,
  "laborQuantityAllocationType": {
    "qualifier": "Even Allocation"
  },
  "dataAccess": {
    "dataAccessType": {
      "qualifier": "All"
    },
    "genericJobs": [],
    "laborCategories": []
  },
  "bottomLevel": true
}

Example response

A success response returns HTTP status code 200 and a response body similar to the following example.

{
  "id": 1,
  "name": "Example Meeting",
  "combinedName": "Example Meeting",
  "searchName": "EXAMPLE MEETING",
  "description": "This activity represents an entity used to track the time spent on a meeting.",
  "parent": {
    "id": 1,
    "qualifier": "Example Meeting"
  },
  "level": 1,
  "sequence": 1,
  "isEditableActualStartDate": true,
  "isEditableActualCompleteDate": true,
  "completeStatus": {
    "id": 1,
    "qualifier": "Incomplete"
  },
  "isEditableCompleteStatus": true,
  "completedPercent": 0,
  "isEditableCompletedPercent": false,
  "heldHistory": {
    "id": 0,
    "qualifier": "Never Held or Released"
  },
  "isEditableHeldHistory": true,
  "requiredQuantity": 0,
  "isEditableRequiredQuantity": true,
  "completedQuantity": 0,
  "movedQuantity": 0,
  "isEditableMovedQuantity": false,
  "receivedQuantity": 0,
  "isEditableReceivedQuantity": false,
  "autoMoveMultiQuantity": 1,
  "scrappedQuantity": 0,
  "movedToReworkQuantity": 0,
  "unaccountedQuantity": 0,
  "header": {
    "id": 1,
    "name": "Example Meeting",
    "activityType": {
      "id": 1,
      "qualifier": "Direct"
    },
    "sequenceValidationType": {
      "id": 0,
      "qualifier": "None"
    },
    "isIncludedCompleteQuantity": true,
    "isIncludedScrappedQuantity": false,
    "isIncludedReworkedQuantity": false,
    "isExtendedCompletionStatus": true,
    "isHoldParent": false,
    "isAutoMoves": false,
    "canBeStartedBeforeStartDate": true,
    "canBeStartedAfterEndDate": true
  },
  "processType": {
    "id": 0,
    "qualifier": "Run"
  },
  "canBeDefault": true,
  "isExcludedFromSequenceValidation": false,
  "isMilestone": false,
  "priorityType": {
    "id": 0,
    "qualifier": "Low"
  },
  "laborHoursAllocationType": {
    "id": 0,
    "qualifier": "Even"
  },
  "minDurationAmount": 72000,
  "maxDurationAmount": 86400000,
  "validateRequiredQuantity": false,
  "requiredVarianceOverPct": 10,
  "validateReceivedQuantity": false,
  "receivedVarianceOverPct": 10,
  "laborQuantityAllocationType": {
    "id": 0,
    "qualifier": "Even Allocation"
  },
  "version": 1,
  "dataAccess": {
    "dataAccessType": {
      "id": 4,
      "qualifier": "All"
    },
    "genericJobs": [],
    "laborCategories": []
  },
  "transfer": {
    "laborCategories": []
  },
  "bottomLevel": true
}

Verify

To verify, call the Retrieve Activity by ID GET /v1/work/activities/{id} or the Retrieve Activity by Name GET /v1/work/activities?name={name} operation.

Calling GET /v1/work/activities/1 or GET /v1/work/activities?name=Example Meeting returns:

{
  "id": 1,
  "name": "Example Meeting",
  "combinedName": "Example Meeting",
  "searchName": "EXAMPLE MEETING",
  "description": "This activity represents an entity used to track the time spent on a meeting.",
  "parent": {
    "id": 1,
    "qualifier": "Example Meeting"
  },
  "level": 1,
  "sequence": 1,
  "isEditableActualStartDate": true,
  "isEditableActualCompleteDate": true,
  "completeStatus": {
    "id": 1,
    "qualifier": "Incomplete"
  },
  "isEditableCompleteStatus": true,
  "completedPercent": 0,
  "isEditableCompletedPercent": false,
  "heldHistory": {
    "id": 0,
    "qualifier": "Never Held or Released"
  },
  "isEditableHeldHistory": true,
  "requiredQuantity": 0,
  "isEditableRequiredQuantity": true,
  "completedQuantity": 0,
  "movedQuantity": 0,
  "isEditableMovedQuantity": false,
  "receivedQuantity": 0,
  "isEditableReceivedQuantity": false,
  "autoMoveMultiQuantity": 1,
  "scrappedQuantity": 0,
  "movedToReworkQuantity": 0,
  "unaccountedQuantity": 0,
  "header": {
    "id": 1,
    "name": "Example Meeting",
    "activityType": {
      "id": 1,
      "qualifier": "Direct"
    },
    "sequenceValidationType": {
      "id": 0,
      "qualifier": "None"
    },
    "isIncludedCompleteQuantity": true,
    "isIncludedScrappedQuantity": false,
    "isIncludedReworkedQuantity": false,
    "isExtendedCompletionStatus": true,
    "isHoldParent": false,
    "isAutoMoves": false,
    "canBeStartedBeforeStartDate": true,
    "canBeStartedAfterEndDate": true
  },
  "processType": {
    "id": 0,
    "qualifier": "Run"
  },
  "canBeDefault": true,
  "isExcludedFromSequenceValidation": false,
  "isMilestone": false,
  "priorityType": {
    "id": 0,
    "qualifier": "Low"
  },
  "laborHoursAllocationType": {
    "id": 0,
    "qualifier": "Even"
  },
  "minDurationAmount": 72000,
  "maxDurationAmount": 86400000,
  "validateRequiredQuantity": false,
  "requiredVarianceOverPct": 10,
  "validateReceivedQuantity": false,
  "receivedVarianceOverPct": 10,
  "laborQuantityAllocationType": {
    "id": 0,
    "qualifier": "Even Allocation"
  },
  "version": 1,
  "dataAccess": {
    "dataAccessType": {
      "id": 4,
      "qualifier": "All"
    },
    "genericJobs": [],
    "laborCategories": []
  },
  "transfer": {
    "laborCategories": []
  },
  "bottomLevel": true
}

Note: the Retrieve Activity by Name GET /v1/work/activities?name={name} operation returns the object above enclosed in an array.

Update the activity

After creating the above activity, perhaps you realize that several items need to be revised:

  • The complete status should be "Not Started" instead of "Incomplete"
  • The Actual start and end dates should not be editable
  • The way your organization tracks meeting progress is a percentage system, so the required quantity should be 100
  • The Type should be Indirect instead of Direct, since meetings do not directly affect production

Later, you can use the update request to associate other Work entities with this activity, such as:

  • units of measure (with the unitOfMeasure object reference)
  • customers (with the customer object reference)
  • activity result templates (with the relatedResultTemplate object reference)

To update the activity with these changes, call the Update Activity by ID PUT /v1/work/activities/1 operation with the following request payload.

Example request

{
  "name": "Example Meeting",
  "id": 1,
  "combinedName": "Example Meeting",
  "searchName": "EXAMPLE MEETING",
  "description": "This activity represents an entity used to track the time spent on a meeting.",
  "level": 1,
  "sequence": 1,
  "isEditableActualStartDate": false,
  "isEditableActualCompleteDate": false,
  "completeStatus": {
    "qualifier": "Not Started"
  },
  "isEditableCompleteStatus": true,
  "completedPercent": 0,
  "isEditableCompletedPercent": false,
  "heldHistory": {
    "qualifier": "Never Held or Released"
  },
  "isEditableHeldHistory": true,
  "requiredQuantity": 100,
  "isEditableRequiredQuantity": true,
  "completedQuantity": 0,
  "movedQuantity": 0,
  "isEditableMovedQuantity": false,
  "receivedQuantity": 0,
  "isEditableReceivedQuantity": false,
  "autoMoveMultiQuantity": 1,
  "scrappedQuantity": 0,
  "movedToReworkQuantity": 0,
  "unaccountedQuantity": 0,
  "header": {
    "id": 1,
    "name": "Example Meeting",
    "activityType": {
      "qualifier": "Indirect"
    },
    "sequenceValidationType": {
      "qualifier": "None"
    },
    "isIncludedCompleteQuantity": true,
    "isIncludedScrappedQuantity": false,
    "isIncludedReworkedQuantity": false,
    "isExtendedCompletionStatus": true,
    "isHoldParent": false,
    "isAutoMoves": false,
    "canBeStartedBeforeStartDate": true,
    "canBeStartedAfterEndDate": true
  },
  "processType": {
    "qualifier": "Run"
  },
  "canBeDefault": true,
  "isExcludedFromSequenceValidation": false,
  "isMilestone": false,
  "priorityType": {
    "qualifier": "Low"
  },
  "laborHoursAllocationType": {
    "qualifier": "Even"
  },
  "minDurationAmount": 72000,
  "maxDurationAmount": 86400000,
  "validateRequiredQuantity": false,
  "requiredVarianceOverPct": 10,
  "validateReceivedQuantity": false,
  "receivedVarianceOverPct": 10,
  "laborQuantityAllocationType": {
    "qualifier": "Even Allocation"
  },
  "dataAccess": {
    "dataAccessType": {
      "qualifier": "All"
    },
    "genericJobs": [],
    "laborCategories": []
  },
  "bottomLevel": true
}

Example response

{
  "id": 1,
  "name": "Example Meeting",
  "combinedName": "Example Meeting",
  "searchName": "EXAMPLE MEETING",
  "description": "This activity represents an entity used to track the time spent on a meeting.",
  "parent": {
    "id": 1,
    "qualifier": "Example Meeting"
  },
  "level": 1,
  "sequence": 1,
  "isEditableActualStartDate": true,
  "isEditableActualCompleteDate": true,
  "completeStatus": {
    "id": 0,
    "qualifier": "Not Started"
  },
  "isEditableCompleteStatus": true,
  "completedPercent": 0,
  "isEditableCompletedPercent": false,
  "heldHistory": {
    "id": 0,
    "qualifier": "Never Held or Released"
  },
  "isEditableHeldHistory": true,
  "requiredQuantity": 100,
  "isEditableRequiredQuantity": true,
  "completedQuantity": 0,
  "movedQuantity": 0,
  "isEditableMovedQuantity": false,
  "receivedQuantity": 0,
  "isEditableReceivedQuantity": false,
  "autoMoveMultiQuantity": 1,
  "scrappedQuantity": 0,
  "movedToReworkQuantity": 0,
  "unaccountedQuantity": 0,
  "header": {
    "id": 1,
    "name": "Example Meeting",
    "activityType": {
      "id": 0,
      "qualifier": "Indirect"
    },
    "sequenceValidationType": {
      "id": 0,
      "qualifier": "None"
    },
    "isIncludedCompleteQuantity": true,
    "isIncludedScrappedQuantity": false,
    "isIncludedReworkedQuantity": false,
    "isExtendedCompletionStatus": true,
    "isHoldParent": false,
    "isAutoMoves": false,
    "canBeStartedBeforeStartDate": true,
    "canBeStartedAfterEndDate": true
  },
  "processType": {
    "id": 0,
    "qualifier": "Run"
  },
  "canBeDefault": true,
  "isExcludedFromSequenceValidation": false,
  "isMilestone": false,
  "priorityType": {
    "id": 0,
    "qualifier": "Low"
  },
  "laborHoursAllocationType": {
    "id": 0,
    "qualifier": "Even"
  },
  "minDurationAmount": 72000,
  "maxDurationAmount": 86400000,
  "validateRequiredQuantity": false,
  "requiredVarianceOverPct": 10,
  "validateReceivedQuantity": false,
  "receivedVarianceOverPct": 10,
  "laborQuantityAllocationType": {
    "id": 0,
    "qualifier": "Even Allocation"
  },
  "version": 2,
  "dataAccess": {
    "dataAccessType": {
      "id": 4,
      "qualifier": "All"
    },
    "genericJobs": [],
    "laborCategories": []
  },
  "transfer": {
    "laborCategories": []
  },
  "bottomLevel": true
}

Note that the version is automatically incremented to 2. To successfully update this activity again, you must pass version 2 in the request body.

Delete the activity

To delete this activity, call the Delete Activity by ID DELETE /v1/work/activities/1 operation.

The system returns HTTP status 204 with an empty response body.