# Goal
Use this API to create, update, and get a user's goals from Cornerstone Performance. You can also use this API to update a user's progress on a goal.
# Create
Use this endpoint to create new user goals. The same rules that the Cornerstone UI enforces while creating user goals also apply for the API. For additional details on creating user goals through the UI, please refer to this help article. You will need to be logged into your Cornerstone portal to access this link.
- You can create only one goal per request using this API.
- If a particular field is configured as 'Read-Only (Assigned Goals)' under the Goal Configuration settings (by Division) in your Cornerstone portal, that field cannot be set using this API.
- Tasks and targets cannot be set using this API if they are not enabled under the Goal Configuration settings (by Division) in your Cornerstone portal using the 'Include' checkbox.
- The weight of all tasks and targets within a goal must add up to 100%. Note that you can only set the weight using the API if the 'Allow tasks and targets to be individually weighted inside of a goal' setting under Goal Preferences is enabled in your Cornerstone portal.
- Goal perspective and category values included in the API request body must be valid values configured in your Cornerstone portal. For more information about configuring perspectives and categories, please see this help article. You will need to be logged into your Cornerstone portal to access this link.
- While this API allows you to set the progress for a goal and tasks and set the actual value for targets while creating the goal, you cannot use it to update progress and actual value on an existing goal. To update progress and actual value, please use the Update Goal Progress API.
Permission Required: Goals - Create
OAuth 2.0 Scope: goal:create
# Error Descriptions
Handled Error List
| Error Types | Error Message |
|---|---|
| PermissionDenied | Provided user does not have application permissions and/or constraints to perform this operation. |
| MissingArgument | The following Arguments are missing: GoalItem |
| CustomException | Goal Title Missing. |
| CustomException | Goal Assignment Missing. |
| CustomException | Managed By User required. |
| CustomException | Invalid Managed By User. |
| CustomException | Goal Start Date Missing. |
| CustomException | Goal Target Date Missing. |
| CustomException | Invalid Goal Start Date. |
| CustomException | Invalid Goal Target Date. |
| CustomException | Target Date must be after Start Date. |
| CustomException | Perspective Missing. |
| CustomException | Invalid Perspective. |
| CustomException | Invalid Category Item. |
| CustomException | Goal Weight must be between 0 and 100. |
| CustomException | Invalid AllowOtherUsersToSeeAndAlignWithThisGoal. |
| CustomException | Task Description Missing. |
| CustomException | Task Start Date Missing. |
| CustomException | Task Due Date Missing. |
| CustomException | Invalid Task Start Date. |
| CustomException | Invalid Task Due Date. |
| CustomException | Task Due Date must be after Start Date. |
| CustomException | Task Start Date must be within the Goals date range. |
| CustomException | Task Due Date must be within the Goals date range. |
| CustomException | Task Weight must be between 0 and 100. |
| CustomException | Target Description Missing. |
| CustomException | Target Start Date Missing. |
| CustomException | Target Due Date Missing. |
| CustomException | Invalid Target Start Date. |
| CustomException | Invalid Target Due Date. |
| CustomException | Target Due Date must be after Start Date. |
| CustomException | Target Start Date must be within the Goals date range. |
| CustomException | Target Due Date must be within the Goals date range. |
| CustomException | Target Weight must be between 0 and 100. |
| CustomException | Invalid Target Type. |
| CustomException | Threshold field is disabled. |
| CustomException | Stretch field is disabled. |
| CustomException | The weights for all components must add up to 100%. |
| CustomException | OU Not Found. |
| CustomException | Invalid OU Type. |
| CustomException | Invalid User. |
| CustomException | Invalid Assign To User/Ou. |
# Details
Use this endpoint to retrieve details of user goals from your Cornerstone portal.
Note that if you are searching by Title alone, then the results will include only those Goals which are directly assigned to the users. It will not include Manager, Division & Company Goals.
Permission Required: Goals - Create
OAuth 2.0 Scope: goal:read
# Error Descriptions
Handled Error List
| Error Types | Error Message |
|---|---|
| Permission Denied | Provided user does not have application permissions and/or constraints to perform this operation. |
| CustomException. | Either Goal Title or Goal User Id is required. |
| CustomException. | Start Date Missing. |
| CustomException. | End Date Missing. |
| CustomException | Invalid Start Date. |
| CustomException | Invalid End Date. |
| CustomException | Invalid User. |
# Update
Use this endpoint to update existing user goals in your Cornerstone portal. The same rules that the Cornerstone UI enforces while creating user goals also apply for the API. For additional details on creating user goals through the UI, please refer to this help article. You will need to be logged into your Cornerstone portal to access this link.
- If a particular field is configured as 'Read-Only (Assigned Goals)' under the Goal Configuration settings (by Division) in your Cornerstone portal, that field cannot be updated using this API.
- Tasks and targets cannot be updated using this API if they are not enabled under the Goal Configuration settings (by Division) in your Cornerstone portal using the 'Include' checkbox.
- The weight of all tasks and targets within a goal must add up to 100%. Note that you can only update the weight using the API if the 'Allow tasks and targets to be individually weighted inside of a goal' setting under Goal Preferences is enabled in your Cornerstone portal.
- Goal perspective and category values included in the API request body must be valid values configured in your Cornerstone portal. For more information about configuring perspectives and categories, please see this help article. You will need to be logged into your Cornerstone portal to access this link.
- While this API allows you to update the progress for a goal and task and update the actual value for a target, it does not support updating progress in certain scenarios such as when a goal has an approval workflow or when the goal does not have any tasks or targets tied to it. Please use the 'Update Goal Progress' API if the only operation you intend to perform is to update progress made by a user on a goal.
Permission Required: Goals - Create
OAuth 2.0 Scope: goal:updatefull
# Error Descriptions
Handled Error List
| Error Types | Error Message |
|---|---|
| MissingArgument | The following Arguments are missing: GoalItem |
| PermissionDenied | Provided user does not have application permissions and/or constraints to perform this operation. |
| CustomException | Goal Title Missing. |
| CustomException | User Id Missing. |
| CustomException | Invalid User. |
| CustomException | Multiple Goal Found for the same Title. |
| CustomException | Goal not found. |
| CustomException | Goal Start Date Missing. |
| CustomException | Goal Target Date Missing. |
| CustomException | Invalid Goal Start Date. |
| CustomException | Invalid Goal Target Date. |
| CustomException | Target Date must be after Start Date. |
| CustomException | Perspective Missing. |
| CustomException | Invalid Perspective. |
| CustomException | Invalid Category Item. |
| CustomException | Goal Weight must be between 0 and 100. |
| CustomException | Invalid AllowOtherUsersToSeeAndAlignWithThisGoal. |
| CustomException | Task Description Missing. |
| CustomException | Task Start Date Missing. |
| CustomException | Task Due Date Missing. |
| CustomException | Invalid Task Start Date. |
| CustomException | Invalid Task Due Date. |
| CustomException | Task Due Date must be after Start Date. |
| CustomException | Task Start Date must be within the Goals date range. |
| CustomException | Task Due Date must be within the Goals date range. |
| CustomException | Task Weight must be between 0 and 100. |
| CustomException | Target Description Missing. |
| CustomException | Target Start Date Missing. |
| CustomException | Target Due Date Missing. |
| CustomException | Invalid Target Start Date. |
| CustomException | Invalid Target Due Date. |
| CustomException | Target Due Date must be after Start Date. |
| CustomException | Target Start Date must be within the Goals date range. |
| CustomException | Target Due Date must be within the Goals date range. |
| CustomException | Target Weight must be between 0 and 100. |
| CustomException | Invalid Target Type. |
| CustomException | Threshold field is disabled. |
| CustomException | Stretch field is disabled. |
| CustomException | The weights for all components must add up to 100%. |
# Update Goal Progress
Use this endpoint to update goal progress, one goal at a time. The same rules that the Cornerstone UI enforces while updating goals also apply for the API. More specifically,
- Progress can be updated at the goal level if the goal does not have a task or target.
- If a goal has a task, progress must be updated at the task level.
- If a goal has a target, progress must be updated by modifying the 'actual value' for the target.
- If a goal has tasks and targets defined, progress must be updated by modifying the 'progress' and 'actual value' respectively.
- If you do not provide an 'actual value' in the request payload, the API defaults the 'actual value' to the 'start value'.
- Progress and actual value cannot be updated for goals in draft status.
- Actual value provided in the request body must be greater than start value defined for the goal target.
- If the Progress field is configured as Read-Only in the Goal Configuration settings (by Division) in your Cornerstone portal, the overall goal completion progress cannot be updated using the API. The Progress field can be configured as Read-Only for goals that are uploaded to the system via a data feed.
- If the Task and Target fields are configured as Read-Only in the Goal Configuration settings (by Division), Task progress and Target actual value cannot be updated using the API. Task progress and Target actual value can be configured as Read-Only for goals that are uploaded to the system via a data feed and non-shared goals that are assigned to a user. Also, task progress can be configured as Read-Only for goals that are imported from the Goal Library.
- Depending on the configuration of the portal (backend setting), the progress percentage field may accept up to two decimal places.
- Goal progress can exceed 100% if the 'Allow goal progress to exceed 100%' setting is checked under Goal Preferences (by Division) in your Cornerstone portal.
For additional details on updating goal progress through the UI, please refer to this help article. You will need to be logged into your Cornerstone portal to access this link.
Permission Required: Goals - Create
OAuth 2.0 Scope: goalprogress:updatefull
# Error Descriptions
Handled Error List
| Error Message | Error Description |
|---|---|
| The following Arguments are missing: GoalItem | Missing 'GoalItem' in the request body. |
| Provided user does not have application permissions and/or constraints to perform this operation. | User does not have the 'Goals - Create' permission. |
| GoalId or Title missing | Either GoalId or Title must be provided in the request body.. |
| UserId missing | UserId must be provided in the request body. |
| Invalid user | UserId provided in the request body is not present in the portal. |
| Multiple Goal Found for the same Title | GoalId was not provided in the request body. Title was provided in the request body, however, there are multiple goals with the same title for the user. |
| Goal not found | GoalId or Title provided in the request body is not found to be associated with the UserId included in the request. |
| Cannot update goal progress. Task or Target present | Value included for GoalProgress, but task or target is present for the goal. Progress must be reported at the task or target level. |
| Task not found | The description provided in the request body for the task is not found to be associated with the UserId and GoalId included in the request. |
| Target not found | The description provided in the request body for the target is not found to be associated with the UserId and GoalId included in the request. |
| Cannot update goal progress. Goal is in draft status | Progress cannot be updated for goals in draft status. |
| Goal progress cannot exceed 100% | Values provided in GoalProgress, TaskProgress or ActualValue will cause the overall goal progress to exceed 100%. But the 'Allow goal progress to exceed 100%' setting is not checked under Goal Preferences for the user's division. |
| Goal progress cannot be updated | The Progress field is set as Read-Only in the Goal Configuration settings for the user's division. The overall goal completion progress cannot be updated. |
| Task progress cannot be updated | The Task field is set as Read-Only in the Goal Configuration settings for the user's division. Task progress cannot be updated. |
| Target actual value cannot be updated | The Target field is set as Read-Only in the Goal Configuration settings for the user's division. Target actual value cannot be updated. |
# Cancel Goal
Use this endpoint to update goal statuses to cancelled, one goal at a time. The same rules that the Cornerstone UI enforces while updating goals also apply for the API. More specifically,
- You can update only one goal per request using this API.
- You can update the status if Goal Progress is disabled by the administrator (i.e., the Progress field is disabled in Goals Configuration) and a goal has no tasks or targets.
For additional details on updating goal progress through the UI, please refer to this help article. You will need to be logged into your Cornerstone portal to access this link.
Permission Required: Goals - Create
OAuth 2.0 Scope: goal:updatefull
# Error Descriptions
Handled Error List
| Error Types | Error Message |
|---|---|
| Permission Denied | Provided user does not have application permissions and/or constraints to perform this operation. |
| CustomException. | Either Goal Title or Goal User Id is required. |
| CustomException | Invalid User. |
# Lock Goals
Use this endpoint to lock or unlock goals, one goal at a time. The same rules that the Cornerstone UI enforces while updating goals also apply for the API. More specifically,
- Managers may lock a goal at the end of the goal period or at the beginning of a review period.
When goals are locked, they cannot be updated either from the UI or the API until unlocked once again.
For additional details on updating goal progress through the UI, please refer to this help article. You will need to be logged into your Cornerstone portal to access this link.
To disable the Lock Goal Results functionality, contact Global Product Support.
Permission Required: Goals - Create
OAuth 2.0 Scope: goal:updatefull
# Error Descriptions
Handled Error List
| Error Types | Error Message |
|---|---|
| Permission Denied | Provided user does not have application permissions and/or constraints to perform this operation. |
| CustomException. | Either Goal Title or Goal User Id is required. |
| CustomException | Invalid User. |