Linking objects to REST Web Services

The first step is to add the REST web service behaviour to the object that you want to use to integrate with the endpoint.

To add the REST Web Service behaviour to an object:

1. In Object Designer, open the object that you want to use the REST web service with.
2. Select the object at the top of the Attributes tree, then in the Properties grid, click alongside Behaviours.
   The Behaviour Selection dialog appears.
3. Select REST Web Service in the Available Items list, then click .
   REST Web Service moves to the Selected Items list.
4. Click OK and save the changes.
   The Behaviour Selection dialog closes, and a new item, REST Web Services, appears in the Property grid.
   Also, four new attributes are created on the object: Rest Service Creation Request Body, Rest Service Creation Status, Rest Service Creation Request URI, and a relationship called Rest Service Creation Request Body Template that is a relationship to a new reference list object called ObjectBody. (Where Object is the name of the object you added the behaviour to.)

You will need to create windows for any new objects created.

5. In the Properties grid, click alongside REST Web Services.
   The REST Web Services dialog appears.
6. On the Request tab, type the URI to the endpoint that you want to use in the End Point URI field.

You can include placeholder variables in the End Point URI field. This is most typically done for PATCH.

7. Select POST, PATCH, or DELETE as appropriate.
   Post is typically used to create items, whereas Patch is used to update existing items. If you want to create an item using the REST web service and then update the same item using the REST web service, you need to create two objects: one to create the item using Post, and another to update the item using Patch.
8. In the Content Type drop-down, select the content type you are sending.
9. In the Authentication Type list, select the type of authentication required: None, Basic, API Key (header), OAuth2 (Client Credentials), or OAuth2 (Password) along with the additional parameters as required.
10. Click OK.

There may be times when you want to switch off the REST behaviour temporarily. You can do this for a specific object by clearing the Enable check box on the REST Web Services dialog.

If you want to perform further actions on the record you create with the REST web service, you need to specify the path to the unique identifier returned by your external application and the location in Service Desk where you want to store this information.

To store unique identifiers:

1. On the Response Mapping tab of the Behaviour Selection dialog, in the Source field enter the path to the unique identifier returned by your external application.
   You can use dot notation to identify items in the source payload. Enter * if you want to use the entire response.
2. In the Target field enter the Service Desk attribute of type string where you want to store the returned value in Service Desk.
   This will be in the form {_Request/Field}.
3. In the Accept drop-down, select the content type you expect to receive.
   If you select an XML format specify the XML Namespaces, separating the names of multiple namespaces with spaces. For example, xmlns:h="http://www.w3.org/TR/html4/" xmlns:r="http://www.example.com/example/"
4. Click OK.

Now that you have configured the link between the Service Desk object and the endpoint, you can specify the Body of the payload you want to send. The payload must be JSON or XML. Some endpoints accept multiple different payloads. For example, Ivanti Automation provides a single endpoint that accepts payloads for multiple runbooks with the required runbook specified in the Body of the payload.

This is why the Rest Service Creation Request Body Template relationship to the ObjectBody reference list object is created when you add the REST web service behaviour. This enables you to create a reference list (for details, see Creating new reference lists) to store the different payload Bodies and then, as a part of your procedure, provide a mechanism for the appropriate reference list instance to be selected (for example by using value type on an Automatic Action; for details, see Specifying dynamic values for automatic actions). By adding placeholders similar to those used when specifying dynamic values in automatic actions into your ObjectBody, you can include values taken from instances of objects in Service Desk to include in the payload. If you use placeholder variables, add them in the context of the RESTful object.

Every object that has the REST behaviour must have at least one item in the corresponding reference list that contains the appropriate payload Body.

You can use a tool such as Swagger to make a call to your endpoint to help you to design this payload.