Reassign Assessment - PATCH /{userId}

  • Release version: Australia
  • Updated October 16, 2019
  • 3 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Reassign Assessment - PATCH /{userId}

    This REST API endpoint allows ServiceNow customers to reassign an in-progress assessment instance to a different user. It is used to transfer ownership of an assessment currently in the “Open” state, updating the primary owner on the assessment instance persona record. This change designates a new responsible user for completing the assessment.

    Show full answer Show less

    Use Cases

    • Reassign assessment responsibility when an employee changes roles or leaves the organization.
    • Correct an incorrectly assigned assessment.
    • Delegate assessment completion to a more suitable team member.

    Key Requirements

    • The assessment must be in the “Open” state to be eligible for reassignment.
    • The requesting user must have write access to the assessment’s persona assignment record to perform the reassignment.

    API Details

    • HTTP Method: PATCH
    • URL format: /api/snsmartasmt/instance/asmt/{asmtInstanceId}/user/{userId} (optionally with version prefix)
    • Path Parameters:
      • asmtInstanceId (required): Sysid of the assessment instance.
      • userId (required): Sysid of the user to reassign the assessment to.
      • apiversion (optional): To specify endpoint version.
    • Request Body: None required or accepted.
    • Headers: Accepts standard REST headers including Authorization for authentication and Accept for response format.

    Expected Responses

    • 200 Success: Assessment reassigned successfully; response body is empty.
    • 400 Bad Request: Missing required path parameters.
    • 403 Forbidden: Requesting user lacks write permissions on the persona assignment record.
    • 404 Not Found: Assessment instance, user, or persona assignment record not found.
    • 406 Not Acceptable: Reassignment cannot proceed due to business rules, e.g., assessment not in “Open” state or already assigned to the target user.

    Error Handling

    If an error occurs, the response includes a JSON object with:

    • status: "failure"
    • error.message: Descriptive error message (e.g., "User not authorized to reassign.")
    • error.detail: Additional error details if available.

    Practical Application

    Use this endpoint to ensure assessment ownership is accurately maintained, improving accountability and workflow continuity. It supports organizational changes and correction of assignment errors without manual intervention. Make sure your API calls include the correct assessment and user IDs and that your user has the necessary permissions to avoid authorization errors.

    Reassigns an assessment instance to a different user. Use this endpoint when you need to transfer ownership of an in-progress assessment from the current assignee to another user.

    The assessment must be in the “Open” state to be reassigned. This endpoint updates the primary owner on the assessment instance persona record, effectively changing who is responsible for completing the assessment.

    Common use cases include:
    • Transferring assessment responsibility when an employee changes roles or leaves the organization.
    • Correcting an incorrectly assigned assessment.
    • Delegating assessment completion to a more appropriate team member.
    Note:
    The requesting user must have write access to the assessment’s persona assignment record to perform the reassignment.

    URL format

    Versioned URL: PATCH /api/sn_smart_asmt/{api_version}/instance/asmt/{asmtInstanceId}/user/{userId}

    Default URL: PATCH /api/sn_smart_asmt/instance/asmt/{asmtInstanceId}/user/{userId}

    Supported request parameters

    Table 1. Path parameters
    Name Description
    api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

    Data type: String
    asmtInstanceId Required. Sys_id of the assessment instance to reassign.

    Table: Assessment Instance [sn_smart_asmt_instance]

    Maximum length: 32

    Data type: String
    userId Required. Sys_id of the user to whom the assessment will be reassigned.

    Table: User [sys_user]

    Maximum length: 32

    Data type: String
    Table 2. Query parameters
    Name Description
    None
    Table 3. Request body parameters (XML or JSON)
    Name Description
    None

    Headers

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    Table 4. Request headers
    Header Description
    Accept Data format of the response body. Supported values: application/json, application/xml, text/xml. Default: application/json.
    Authorization Authentication credentials. Use Basic authentication with base64-encoded username:password, or an OAuth 2.0 bearer token.
    Content-Type Not required for this endpoint as there is no request body, but if provided, supported values are: application/json, application/xml, text/xml.
    Table 5. Response headers
    Header Description
    Content-Type Data format of the response body. Matches the Accept header value or defaults to application/json.
    X-Is-Logged-In Flag that indicates whether the requesting user is logged in. Possible values: true, false.
    X-Transaction-ID Unique identifier for the transaction, useful for debugging and support requests.

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 6. Status codes
    Status code Description
    200 Success. The assessment was successfully reassigned to the specified user. No response body is returned.
    400 Bad Request. The request is missing required path parameters.
    Possible error messages:
    • Assessment id is not passed.
    • User id is not passed.
    403 Forbidden. The requesting user doesn't have authorization to reassign this assessment. This occurs when the user lacks write access to the assessment’s persona assignment record.

    Error message: User not authorized to reassign.

    404 Not Found. The specified resource doesn't exist.
    Possible error messages:
    • Assessment instance not found.
    • User not found.
    • Persona assignment record for assessor is not available for the assessment.
    406 Not acceptable. The reassignment can't be completed due to business rule constraints.
    Possible error messages:
    • Assessment can’t be reassigned as it's not in {state_name} state - Assessment must be in Open state.
    • Assessment can’t be reassigned as it's already assigned to the current user
    • Unable to reassign the assessment - Generic failure during update.

    Response body parameters (JSON or XML)

    Name Description
    Object Return object containing results of the reassignment.
    {
  "error": {Object},
  "status": "String"
}
    error Object containing error details.

    Data type: Object

    "error": {
  "detail": "String",
  "message": "String"
  }
    error.message Human-readable description of the error that occurred.
    Examples:
    • Assessment ID isn't passed.
    • User not authorized to reassign.
    • Assessment instance not found.

    Data type: String
    error.detail Additional details about the error, if available. May be empty.

    Data type: String
    status Indicates the outcome of the request. Possible values: "failure" (when an error occurs). Successful responses (HTTP 200) return an empty body with no status field.

    cURL request

    This PATCH example reassigns the assessment with ID 4d812fed47f8835060b5e65d416d431a to the user with ID 62826bf03710200044e0bfc8bcbe5df1.

    curl "https://testsae.service-now.com/api/sn_smart_asmt/instance/asmt/4d812fed47f8835060b5e65d416d431a/user/62826bf03710200044e0bfc8bcbe5df1" \
--request PATCH \
--header "Accept:application/json" \
--user 'admin':'admin'

    Response:

    {
  "error": {
    "message": "Assessment can't be reassigned as it is already assigned to the current user",
    "detail": ""
  },
  "status": "failure"
}