REST API - Create an action

Last modified on 2023/12/08 18:05
Contents

POST  /requests/{rfc_number}/actions

  • The method supports the creation of a single action per call.

Notes

       Open url.png  See Service Manager REST API

  • You must supply a table in JSON format in the body of the HTTP request.
  • To define the type of action for the action to be created:
    • You can use the name of the action_type_id (preferably) or the action_type_name objects.
    • 2023.4 - Build 2023.4.108.0.04+ You can also use the name of the action_type_guid object.
    • if you used the name of the action_type_name object, you must enter the value of the object in the language of the user logged in to the REST API.
  • To define the group assigned to the task, you can use the name of the group_id, the group_name or the group_mail objects.
  • If successful, an HTTP status code 201 is returned and a URL link (HREF) to the created resource is provided.
CommonNotes_JSONandFields

JSON Format / Field Format:

  • The field names are those of the Service Manager.data model.

example  available_field_1

  • To update a field, respect the following JSON format: "field_name":"value".
  • JSON object names, including those representing Service Manager database fields, are not case sensitive.

example  field_name, Field_Name and FIELD_NAME are equivalent

List of parameters / fields

Mandatory parameters

  • You must use the parameter below in the URL.
     
Parameter Type Description / Example
rfc_number string Ticket identifier
  • You must use the JSON objects below in the body of the HTTP request.
Minimum version Parameter Type Description / Example
action_type_id, action_type_name integer / string Identifier / Name for the action type to be created
2023.4 - Build 2023.4.108.0.04 / action_type_guid integer / string GUID for the action type to be created
group_id / group_mail / group_name integer / string Identifier / E-mail address / Name of the group who must perform the action

Optional parameters

None

Optional fields

You can use all the fields from the AM_ACTION table in the body of the HTTP request, except those you have added to the Service Manager database (These are fields with the prefix e_).
 

Minimum version Parameter Type Description / Example
creation_date_ut string Creation date of the action, expressed in Universal Time.
  • By default, current date (now).
Autumn 2020 - Build 2020.2.122.2 comment string Description related to the object
contact_id, contact_identification, contact_mail, contact_name integer / string Key / Employee number / Email address / Contact name in charge of the action.
  • The objects are processed in this priority order by the search algorithm.
description string Comment related to the object
doneby_id, doneby_identification, doneby_mail, doneby_name integer / string Key / Employee number / Email address / Support name in charge of the action.
  • The objects are processed in this priority order by the search algorithm.
expected_start_date_ut / expected_end_date_ut string Scheduled start date / Scheduled end date of the action, expressed in Universal Time.
group_id, group_mail, group_name integer / string Key / Email address / Group name in charge of the action.
  • The objects are processed in this priority order by the search algorithm.
max_intervention_date_ut string Latest possible date where the action needs to be executed, expressed in Universal Time.
  • If the date is not completed, it is computed starting from the creation date of the action and the OLA of the group.
parent_action_id integer Key of the parent action.

Description of the actions carried out

An action is created for the ticket.

  • Status: In progress
  • The calculations of the creation wizard are done.

You can specify the parent_action_id field in the json body.

  • If the parent_action_id is completed: the new action will be attached to the parent_action_id
  • If the parent_action_id is not completed:
    • The new action will be attached to the last action related to the rfc_number which are assigned to the user / group passed as parameters.
    • If several parent actions are found, the process is cancelled (there is an ambiguity on parent_action_id).

HTTP status codes for the method

StatusHeader

   A Timeout error code will be returned if the server does not respond to the REST Web service request within a given time (by default 60 seconds).

Code Error Description
Status201
201 Created Request successfully processed and element created.
Status401
401 Unauthorized Incorrect authentication process for accessing the resource: Incorrect login/password, invalid session, incorrect Service Manager account.

example

{
 "error": "Invalid Login / Password"
}
Status405
405 Method not allowed Unauthorized request method, i.e. it is not supported or not appropriate for the resource.

example

{
 "error": "Invalid input parameter"
}

Examples

Example of the body of an HTTP request

{
"action": {
   "action_type_id": "10",
   "group_name": "US network expert"
    }
}

Result with a status code 201 returned

{
  "HREF":  "https://{your_server}/api/v1/{your_account}/actions/I191213_000001"
}
ConventionsAPI

REST API Conventions

Convention Meaning
Orange Parameters used in an HTTP request string which do not correspond to Service Manager database fields.

example   Method View a list of assets

https://{your_server}/api/v1/{your_account}/assets?max_rows=3&fields=asset_tag
Black and Bold Parameters used in the URL of an HTTP request which correspond to Service Manager database fields.

example   Method View an asset

https://{your_server}/api/v1/{your_account}/assets/{asset_id}
Green Parameters used in the body of an HTTP request which represent JSON object names corresponding to Service Manager database fields; they allow the value of a database field to be assigned or modified.

example   Method Close an incident/request

{  "closed": {  "end_date": "11/20/2016 12:12:12",  }  }
Parameters used in the body of an HTTP request which represent JSON object names not corresponding to Service Manager database fields.

example   Method Reopen an incident/request

{  "restarted": {  "comment": "string (required)"  }  }
Tags:
Created on 2022/05/28 10:50
Powered by XWiki © EasyVista 2022