Update 4me request

step

This 4me step container updates a request.

Specification

connection

Required

A Relay 4me connection to useConnection docs
${connections.'4me'.my-4me-connection}
request

Required

object
The 4me request object
request.request_id

Required

integer
The id of the request to update.
request.addressed
Optional
boolean
Optional boolean, default: false — When the Satisfaction field of the request is set to ‘Dissatisfied’, a person who has the Service Desk Manager role, can check the Addressed box to indicate that the requester has been conciliated.
request.agile_board
Optional
integer
Optional reference to Agile Board — The Agile board on which the request is placed.
request.agile_board_column
Optional
integer
Optional reference to Agile Board Column — The column of the agile board on which the request is placed.
request.agile_board_column_position
Optional
integer
Optional integer — The Position field is used to specify the position of the request, relative to the other items within the column of the agile board. The topmost item has position 1.
request.category
Optional
string
Required enum — The Category field is used to select the category of the request. Valid values are:
  • incident: Incident - Request for Incident Resolution
  • rfc: RFC - Request for Change
  • rfi: RFI - Request for Information
  • reservation: Reservation - Request for Reservation
  • complaint: Complaint - Request for Support Improvement
  • compliment: Compliment - Request for Bestowal of Praise
  • other: Other - Request is Out of Scope
request.change
Optional
integer
Optional reference to Change — The Change field is used to link the request to a change.
request.ci
Optional
integer
Optional reference to Configuration Item — The Configuration item field is used to relate a CI to the request. When this field is used to update an existing request, all configuration items that are linked to this request will be replaced by the new configuration item. Multiple configuration items can be added to, or removed from, a request using the Requests - Configuration Items API.
request.completion_reason
Optional
string
Optional enum — The Completion reason field is used to select the appropriate completion reason for the request when it has been completed. Valid values are:
  • solved: Solved - Root Cause Analysis Not Required
  • workaround: Workaround - Root Cause Not Removed
  • gone: Gone - Unable to Reproduce duplicate: Duplicate - Same as Another Request of Customer
  • withdrawn: Withdrawn - Withdrawn by Requester no_reply: No Reply - No Reply Received from Customer rejected: Rejected - Rejected by Approver
  • conflict: Conflict - In Conflict with Internal Standard or Policy
  • declined: Declined - Declined by Service Provider
  • unsolvable: Unsolvable - Unable to Solve
request.custom_fields
Optional
object
Optional custom fields — Custom fields provided in JSON format by the UI Extension that is linked to the related request template. This should be an array of JSON hashes in which each hash has keys 'id' and 'value'
request.downtime_end_at
Optional
string
Optional datetime — The Downtime end field is used to specify the actual date and time at which the service became available again.
request.downtime_start_at
Optional
string
Optional datetime — The Downtime start field is used to specify the actual date and time at which the service outage started.
request.desired_completion_at
Optional
string
Optional datetime — The Desired completion field can be set to the date and time that has been agreed on for the completion of the request. The desired completion overwrites the automatically calculated resolution target of any affected SLA that is related to the request when the desired completion is later than the affected SLA’s resolution target. By default, the person selected in the Requested by field receives a notification based on the ‘Desired Completion Set for Request’ email template whenever the value in the Desired completion field is set, updated or removed.
request.feedback
Optional
object
Readonly hash — Hash containing the satisfied_url and the dissatisfied_url of the requested_for. In case the requested_by is different form the requested_for, the satisfaction link of the requested_by are also included. Feedback is null in case no feedback for the request can be provided at this time.
request.grouped_into
Optional
integer
Optional reference to Request — The Grouped into field displays the request group that is used to group the requests that have been submitted for the resolution of exactly the same incident, for the implementation of exactly the same change, for the provision of exactly the same information, etc.
request.grouping
Optional
string
Readonly enum, default: none — Valid values are:
  • none: None
  • group: Group
  • grouped: Grouped
request.id
Optional
integer
Readonly integer — The unique ID of the request.
request.impact
Optional
string
Optional enum — The Impact field is used to select the extent to which the service instance is impacted. Valid values are:
  • low: Low - Service Degraded for One User
  • medium: Medium - Service Down for One User
  • high: High - Service Degraded for Several Users
  • top: Top - Service Down for Several Users
request.internal_note
Optional
string
Optional text (max 64KB) — The Internal note field is used to provide information that is visible only for people who have the Auditor, Specialist or Account Administrator role of the account for which the internal note is intended. The X-4me-Account header can be included in an API PATCH request to add an internal note for a specific account (see Multiple Accounts).
request.internal_note_attachments
Optional
object
Writeonly attachments The attachments used in the Internal Note field.
request.knowledge_article
Optional
integer
Optional reference to Knowledge Article — The Knowledge Article field is automatically set to the latest knowledge article that was applied to the request.
request.major_incident_status
Optional
string
Optional enum — The Major Incident Status field is used to indicate the status in the major incident management process. Valid values are:
  • proposed: Proposed
  • rejected: Rejected
  • accepted: Accepted
  • resolved: Resolved
  • canceled: Canceled
request.member
Optional
integer
Optional reference to Person — The Member field is used to select the person to whom the request is to be assigned.
request.note
Optional
string
Optional text (max 64KB) — The Note field is used to provide any additional information that could prove useful for resolving the request and/or to provide a summary of the actions that have been taken since the last entry.
request.note_attachments
Optional
object
Writeonly attachments The attachments used in the Note field.
request.planned_effort
Optional
integer
Optional integer (max 600000) — The Planned effort field is used to specify the number of minutes the member is expected to spend working on the request.
request.problem
Optional
integer
Optional reference to Problem — The Problem field is used to link the request to a problem.
request.project
Optional
integer
Optional reference to Project — The Project field is used to link the request to a project.
request.reservation
Optional
integer
Optional reference to Reservation — The Reservations field is used to link the request to a reservation.
request.requested_by
Optional
integer
Required reference to Person — The Requested by field is used to select the person who submitted the request.
request.requested_for
Optional
integer
Required reference to Person — The Requested for field is used to select the person for whom the request was submitted. The person selected in the Requested by field is automatically selected in this field, but another person can be selected if the request is submitted for another person.
request.reviewed
Optional
boolean
Optional boolean, default: false — A request can be marked as reviewed by the problem manager of the service of the service instance that is linked to the request. Marking a request as reviewed excludes it from the ‘Requests for Problem Identification’ view. This field is automatically set to true when the Service instance field is empty, when the request is linked to a problem or change, or when the Grouping field is set to grouped. This field is also set to true when the completion_reason is solved and the impact is different from top.
request.service_instance
Optional
integer
Optional reference to Service Instance — The Service instance field is used to select the Service Instance in which the cause of the incident resides, for which the change is requested, or about which information is needed.
request.source
Optional
string
The source and sourceID fields keep track of where resources originate from. The source field is used to specify the name of the external system from which the data of a 4me record was obtained. The sourceID field is used to specify the unique identifier or number that can be used to find the record in the source system. When the data that is stored in 4me originates from multiple external systems, the combination of these two fields is used to uniquely identify records in the correct source system. When building an integration with 4me its is recommended to fill out both these fields while importing resources from an external system into 4me. An update of the source and sourceID field values of a record can only be performed by an API user who has the Account Administrator role of the account to which the record belongs. If the Account Administrator role does not provide write access to the type of record that needs to be updated, then the API user will also need another role that does give write access to this record type. For example, if an API user needs to be able to update the source and sourceID field values of requests, then this API user will need to have the Specialist role, as well as the Account Administrator role, of the account to which the requests belong.
  • source: an identifier for the client application submitting the resource or the name of an external system (limited to 30 characters)
  • sourceID - the unique identifier of the resource in an external system (limited to 128 characters)
request.sourceID
Optional
string
Optional string (max 128) - See source
request.status
Optional
string
Optional enum, default: assigned — The Status field is used to select the current status of the request. Valid values are:
  • declined: Declined
  • assigned: Assigned
  • accepted: Accepted
  • in_progress: In Progress
  • waiting_for: Waiting for…
  • waiting_for_customer: Waiting for Customer
  • change_pending: Change Pending
  • project_pending: Project Pending
  • completed: Completed
request.subject
Optional
string
Required string (max 255) — The Subject field is used to enter a short description of the request.
request.supplier
Optional
integer
Optional reference to Organization — The Supplier field is used to select the supplier organization that has been asked to assist with the request. The supplier organization is automatically selected in this field after a service instance has been selected that is provided by an external service provider organization.
request.supplier_requestID
Optional
string
Optional string (max 255) — The Supplier request ID field is used to enter the identifier under which the request has been registered at the supplier organization. If the supplier provided a link to the request, enter the entire URL in this field.
request.support_domain
Optional
string
Used to specify the support domain account ID in which the request is to be registered. This parameter needs to be specified when the current user’s Person record is registered in a directory account. The ID of a 4me account can be found in the ‘Account Overview’ section of the Settings console.
request.task
Optional
integer
Optional reference to Task — The Task field is visible only when the request was automatically generated by a task. When visible, this field contains the task that caused the request to be generated.
request.team
Optional
integer
Required reference to Team — The Team field is used to select the Team to which the request is to be assigned. By default, the first line team of the service instance that is related to the request will be selected. If a first line team has not been specified for the service instance, the support team of the service instance will be selected instead.
request.template
Optional
integer
Optional reference to Request Template — The Template field contains the link to the request template that was last applied to the request.
request.time_spent
Optional
integer
Optional integer — The Time spent field is used to enter the time that you have spent working on the request since you started to work on it or, if you already entered some time for this request, since you last added your time spent in it.
request.time_spent_effort_class
Optional
integer
Optional reference to Effort Class — The Effort class field is used to select the effort class that best reflects the type of effort for which time spent is being registered.
request.urgent
Optional
boolean
Optional boolean, default: false — When the request has been marked as urgent, the Urgent field is set to true.
request.waiting_until
Optional
string
Optional datetime — The Waiting until field is used to specify the date and time at which the status of the request is to be updated from waiting_for to assigned. This field is available only when the Status field is set to waiting_for.
debug
Optional
boolean
(Advanced) Turn on step debug logging by setting this to true

Outputs

request

Required

object
Request details
request.request_id
Optional
integer
The id of the request to update.
request.addressed
Optional
boolean
Optional boolean, default: false — When the Satisfaction field of the request is set to ‘Dissatisfied’, a person who has the Service Desk Manager role, can check the Addressed box to indicate that the requester has been conciliated.
request.agile_board
Optional
integer
Optional reference to Agile Board — The Agile board on which the request is placed.
request.agile_board_column
Optional
integer
Optional reference to Agile Board Column — The column of the agile board on which the request is placed.
request.agile_board_column_position
Optional
integer
Optional integer — The Position field is used to specify the position of the request, relative to the other items within the column of the agile board. The topmost item has position 1.
request.assignment_count
Optional
integer
Readonly integer — The Assignment count field is automatically set to the number of times that the Team field of the request has been set to a Team that is registered in the Account from which the request data is retrieved.
request.attachments
Optional
array
Readonly aggregated Attachments
request.category
Optional
string
Required enum — The Category field is used to select the category of the request. Valid values are:
  • incident: Incident - Request for Incident Resolution
  • rfc: RFC - Request for Change
  • rfi: RFI - Request for Information
  • reservation: Reservation - Request for Reservation
  • complaint: Complaint - Request for Support Improvement
  • compliment: Compliment - Request for Bestowal of Praise
  • other: Other - Request is Out of Scope
request.change
Optional
integer
Optional reference to Change — The Change field is used to link the request to a change.
request.ci
Optional
integer
Optional reference to Configuration Item — The Configuration item field is used to relate a CI to the request. When this field is used to update an existing request, all configuration items that are linked to this request will be replaced by the new configuration item. Multiple configuration items can be added to, or removed from, a request using the Requests - Configuration Items API.
request.completed_at
Optional
string
Readonly datetime — The Completed at field is automatically set to the date and time at which the request is saved with the status “Completed”.
request.completion_reason
Optional
string
Optional enum — The Completion reason field is used to select the appropriate completion reason for the request when it has been completed. Valid values are:
  • solved: Solved - Root Cause Analysis Not Required
  • workaround: Workaround - Root Cause Not Removed
  • gone: Gone - Unable to Reproduce duplicate: Duplicate - Same as Another Request of Customer
  • withdrawn: Withdrawn - Withdrawn by Requester no_reply: No Reply - No Reply Received from Customer rejected: Rejected - Rejected by Approver
  • conflict: Conflict - In Conflict with Internal Standard or Policy
  • declined: Declined - Declined by Service Provider
  • unsolvable: Unsolvable - Unable to Solve
request.created_at
Optional
string
Readonly datetime — The date and time at which the request was created.
request.created_by
Optional
integer
Required reference to Person — The Created by field is automatically set to the person who submitted the request.
request.custom_fields
Optional
object
Optional custom fields — Custom fields provided in JSON format by the UI Extension that is linked to the related request template.
request.downtime_end_at
Optional
string
Optional datetime — The Downtime end field is used to specify the actual date and time at which the service became available again.
request.downtime_start_at
Optional
string
Optional datetime — The Downtime start field is used to specify the actual date and time at which the service outage started.
request.desired_completion_at
Optional
string
Optional datetime — The Desired completion field can be set to the date and time that has been agreed on for the completion of the request. The desired completion overwrites the automatically calculated resolution target of any affected SLA that is related to the request when the desired completion is later than the affected SLA’s resolution target. By default, the person selected in the Requested by field receives a notification based on the ‘Desired Completion Set for Request’ email template whenever the value in the Desired completion field is set, updated or removed.
request.feedback
Optional
object
Readonly hash — Hash containing the satisfied_url and the dissatisfied_url of the requested_for. In case the requested_by is different form the requested_for, the satisfaction link of the requested_by are also included. Feedback is null in case no feedback for the request can be provided at this time.
request.grouped_into
Optional
integer
Optional reference to Request — The Grouped into field displays the request group that is used to group the requests that have been submitted for the resolution of exactly the same incident, for the implementation of exactly the same change, for the provision of exactly the same information, etc.
request.grouping
Optional
string
Readonly enum, default: none — Valid values are:
  • none: None
  • group: Group
  • grouped: Grouped
request.id
Optional
integer
Readonly integer — The unique ID of the request.
request.impact
Optional
string
Optional enum — The Impact field is used to select the extent to which the service instance is impacted. Valid values are:
  • low: Low - Service Degraded for One User
  • medium: Medium - Service Down for One User
  • high: High - Service Degraded for Several Users
  • top: Top - Service Down for Several Users
request.internal_note
Optional
string
Optional text (max 64KB) — The Internal note field is used to provide information that is visible only for people who have the Auditor, Specialist or Account Administrator role of the account for which the internal note is intended. The X-4me-Account header can be included in an API PATCH request to add an internal note for a specific account (see Multiple Accounts).
request.internal_note_attachments
Optional
object
Writeonly attachments The attachments used in the Internal Note field.
request.knowledge_article
Optional
integer
Optional reference to Knowledge Article — The Knowledge Article field is automatically set to the latest knowledge article that was applied to the request.
request.major_incident_status
Optional
string
Optional enum — The Major Incident Status field is used to indicate the status in the major incident management process. Valid values are:
  • proposed: Proposed
  • rejected: Rejected
  • accepted: Accepted
  • resolved: Resolved
  • canceled: Canceled
request.member
Optional
integer
Optional reference to Person — The Member field is used to select the person to whom the request is to be assigned.
request.new_assignment
Optional
boolean
Readonly boolean, default: true — The New assignment field is set to true when the request’s status is ‘Assigned’ or ‘Declined’.
request.next_target_at
Optional
string
Readonly datetime — The Next target field value is empty when the status of the request is ‘Completed’. The next target equals the response target when a response target exists and the response target is less than the desired completion. Otherwise, the next target equals the desired completion when a desired completion exists. Otherwise, if the status is ‘Waiting for Customer’ the next target is clock_stopped when an affected SLA is linked to the request which Accountability field is set to provider or supplier. Otherwise, if the status is ‘Waiting for Customer’ the next target is best_effort. Otherwise the next target is the resolution target when a resolution target exists. In all other cases, the next target is best_effort.
request.note
Optional
string
Optional text (max 64KB) — The Note field is used to provide any additional information that could prove useful for resolving the request and/or to provide a summary of the actions that have been taken since the last entry.
request.note_attachments
Optional
object
Writeonly attachments The attachments used in the Note field.
request.organization
Optional
integer
Readonly reference to Organization — The Organization field is automatically set when the request is saved for the first time to the organization that the person, who is selected in the Requested for field, belongs.
request.planned_effort
Optional
integer
Optional integer (max 600000) — The Planned effort field is used to specify the number of minutes the member is expected to spend working on the request.
request.problem
Optional
integer
Optional reference to Problem — The Problem field is used to link the request to a problem.
request.project
Optional
integer
Optional reference to Project — The Project field is used to link the request to a project.
request.reopen_count
Optional
integer
Readonly integer — The Reopen count field is automatically set to the number of times that the status of the request has changed from ‘Completed’ to a different value in the Account from which the request data is retrieved.
request.reservation
Optional
integer
Optional reference to Reservation — The Reservations field is used to link the request to a reservation.
request.resolution_target_at
Optional
string
Readonly datetime — The Resolution target field automatically indicates when the current assignment team needs to have completed the request. The target displayed in this field is the most stringent resolution target of the affected SLAs that are related to the request and for which the current assignment team is responsible.
request.response_target_at
Optional
string
Readonly datetime — The Response target field automatically indicates when the current assignment team needs to have responded to the request. The target displayed in this field is the most stringent response target of the affected SLAs that are related to the request and for which the current assignment team is responsible.
request.requested_by
Optional
integer
Required reference to Person — The Requested by field is used to select the person who submitted the request.
request.requested_for
Optional
integer
Required reference to Person — The Requested for field is used to select the person for whom the request was submitted. The person selected in the Requested by field is automatically selected in this field, but another person can be selected if the request is submitted for another person.
request.requester_resolution_target_at
Optional
string
Readonly datetime — The Requester resolution target field is automatically set to the most stringent resolution target of the request’s affected SLAs, which Accountability field is not set to sla_not_affected and which are linked to an SLA for which the person who is selected in the Requested for field has coverage.
request.reviewed
Optional
boolean
Optional boolean, default: false — A request can be marked as reviewed by the problem manager of the service of the service instance that is linked to the request. Marking a request as reviewed excludes it from the ‘Requests for Problem Identification’ view. This field is automatically set to true when the Service instance field is empty, when the request is linked to a problem or change, or when the Grouping field is set to grouped. This field is also set to true when the completion_reason is solved and the impact is different from top.
request.satisfaction
Optional
string
Readonly enum — The Satisfaction field is set when a requester uses the hyperlinks defined in the ‘Request Set to Completed’ email template to indicate whether or not he/she is satisfied with the manner in which a request has been handled. Valid values, apart from the default null, are:
  • dissatisfied: Dissatisfied
  • satisfied: Satisfied It is also possible to set the value of this field via the Request Satisfaction API.
request.service_instance
Optional
integer
Optional reference to Service Instance — The Service instance field is used to select the Service Instance in which the cause of the incident resides, for which the change is requested, or about which information is needed.
request.source
Optional
string
The source and sourceID fields keep track of where resources originate from. The source field is used to specify the name of the external system from which the data of a 4me record was obtained. The sourceID field is used to specify the unique identifier or number that can be used to find the record in the source system. When the data that is stored in 4me originates from multiple external systems, the combination of these two fields is used to uniquely identify records in the correct source system. When building an integration with 4me its is recommended to fill out both these fields while importing resources from an external system into 4me. An update of the source and sourceID field values of a record can only be performed by an API user who has the Account Administrator role of the account to which the record belongs. If the Account Administrator role does not provide write access to the type of record that needs to be updated, then the API user will also need another role that does give write access to this record type. For example, if an API user needs to be able to update the source and sourceID field values of requests, then this API user will need to have the Specialist role, as well as the Account Administrator role, of the account to which the requests belong.
  • source: an identifier for the client application submitting the resource or the name of an external system (limited to 30 characters)
  • sourceID - the unique identifier of the resource in an external system (limited to 128 characters)
request.sourceID
Optional
string
Optional string (max 128) - See source
request.status
Optional
string
Optional enum, default: assigned — The Status field is used to select the current status of the request. Valid values are:
  • declined: Declined
  • assigned: Assigned
  • accepted: Accepted
  • in_progress: In Progress
  • waiting_for: Waiting for…
  • waiting_for_customer: Waiting for Customer
  • change_pending: Change Pending
  • project_pending: Project Pending
  • completed: Completed
request.subject
Optional
string
Required string (max 255) — The Subject field is used to enter a short description of the request.
request.supplier
Optional
integer
Optional reference to Organization — The Supplier field is used to select the supplier organization that has been asked to assist with the request. The supplier organization is automatically selected in this field after a service instance has been selected that is provided by an external service provider organization.
request.supplier_requestID
Optional
string
Optional string (max 255) — The Supplier request ID field is used to enter the identifier under which the request has been registered at the supplier organization. If the supplier provided a link to the request, enter the entire URL in this field.
request.support_domain
Optional
Used to specify the support domain account ID in which the request is to be registered. This parameter needs to be specified when the current user’s Person record is registered in a directory account. The ID of a 4me account can be found in the ‘Account Overview’ section of the Settings console.
request.task
Optional
integer
Optional reference to Task — The Task field is visible only when the request was automatically generated by a task. When visible, this field contains the task that caused the request to be generated.
request.team
Optional
integer
Required reference to Team — The Team field is used to select the Team to which the request is to be assigned. By default, the first line team of the service instance that is related to the request will be selected. If a first line team has not been specified for the service instance, the support team of the service instance will be selected instead.
request.template
Optional
integer
Optional reference to Request Template — The Template field contains the link to the request template that was last applied to the request.
request.time_spent
Optional
integer
Optional integer — The Time spent field is used to enter the time that you have spent working on the request since you started to work on it or, if you already entered some time for this request, since you last added your time spent in it.
request.time_spent_effort_class
Optional
integer
Optional reference to Effort Class — The Effort class field is used to select the effort class that best reflects the type of effort for which time spent is being registered.
request.updated_at
Optional
string
Readonly datetime — The date and time of the last update of the request. If the request has no updates it contains the created_at value.
request.urgent
Optional
boolean
Optional boolean, default: false — When the request has been marked as urgent, the Urgent field is set to true.
request.waiting_until
Optional
string
Optional datetime — The Waiting until field is used to specify the date and time at which the status of the request is to be updated from waiting_for to assigned. This field is available only when the Status field is set to waiting_for.

Join our community

We’re excited to see and share in our community’s creation. Take a look at our community overview to learn how to begin contributing to Relay.