# Freshservice

Integrating Freshservice with Apono allows users to create a Freshservice ticket that triggers an access request in Apono. Depending on your preferred workflow, you can then manage approvals in Slack, Microsoft Teams, CLI, or the Apono web portal.

{% hint style="success" %}
This solution is customizable. Approvals can either be handled within Freshservice or through Apono’s approval flows in external tools.
{% endhint %}

***

### Prerequisites

<table><thead><tr><th width="177.578125">Item</th><th>Description</th></tr></thead><tbody><tr><td><strong>Apono API Token</strong></td><td><br><a href="../architecture-and-security/personal-api-tokens">Credentials</a> enabling secure, programmatic access to the Apono API</td></tr><tr><td><strong>Apono IDs</strong></td><td><p>Apono identifiers required for the Freshservice integration:</p><ul><li>Integration ID</li><li>Resource ID</li><li>Permissions<br></li></ul><p>Follow these steps to obtain these IDs:</p><ol><li>On the <a href="https://app.apono.io/resources"><strong>Inventory</strong></a> page, on the <strong>Resources</strong> tab, click <strong>Basic</strong>.</li><li>From the <strong>Integration</strong> dropdown menu, select one integration. Only the resources associated with the integration will be displayed.</li><li>Click a resource from the list. The <strong>Entitlements Details</strong> panel appears.</li><li>From the page URL, copy the values for the <code>integration</code> and <code>resourceId</code> query strings.</li><li>In the <strong>Entitlements Details</strong> panel, on the <strong>Entitlement</strong>s tab, copy each of the values under the <strong>PERMISSION</strong> column.</li></ol></td></tr><tr><td><strong>Freshservice Admin Permission</strong></td><td><br>Permission to manage all features except billing</td></tr></tbody></table>

***

### Build a workflow

{% hint style="warning" %}
Freshservice's user interface and features may change over time. If any of the following steps have changed, please refer to [Freshservice's documentation](https://support.freshservice.com/support/solutions/articles/157143-using-webhooks-with-the-workflow-automator).
{% endhint %}

Freshservice's Workflow Automator allows you to define the events and conditions that trigger an access request, and configure the necessary web requests to communicate with the Apono API.

<figure><img src="https://1094436629-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fv6MBfUGvblSdAz31yJXm%2Fuploads%2Fgit-blob-cc5b6e01e5adb96e74450a71442ca8dee109a647%2Fimage%20(63).png?alt=media" alt=""><figcaption><p>Workflow Automator canvas</p></figcaption></figure>

Follow these steps to build a workflow:

1. In Freshservice, click **Admin**. The admin page appears.
2. In the search field, enter **Workflow Automator**.
3. Click **Workflow Automator**. The **Workflow Automator** page appears.
4. Click **New Workflow**. The **New Workflow** panel opens.
5. Enter a meaningful **Title** for the workflow.
6. Select the relevant **Module**.
7. Under **Workflow Type**, select **Event Based Workflow**.
8. Click **Create**. The **New Workflow** panel closes and the **Event** panel opens.
9. Define the event that triggers this workflow.

<details>

<summary>Defining an Event</summary>

![](https://1094436629-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fv6MBfUGvblSdAz31yJXm%2Fuploads%2Fgit-blob-00ef5d97922c353e27440222c1d28962b7bdb23b%2Ffreshservice-event-panel.png?alt=media)

Follow these steps to define an event:

1. In the first field, build the event from the dropdown options.
2. Select who can perform the event.
3. Click **Done**. The **Event** panel closes. The module appears on the canvas.

</details>

10. (Optional) Define a condition for the event.

<details>

<summary>Defining a Condition</summary>

Follow these steps to define a condition:

1. From the side menu, click and drag a **Condition** module to the canvas. The **Condition** panel opens.
2. Define the condition with the **Match** or **Build Expression** option.
3. Click **Done**. The **Condition** panel closes. The module appears on the canvas.

</details>

11. Define a web request to retrieve the user's ID.

<details>

<summary>Defining a Web Request</summary>

![](https://1094436629-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fv6MBfUGvblSdAz31yJXm%2Fuploads%2Fgit-blob-83272c2996b35d8d751ed85927201a96a02966cf%2Ffreshservice-event-panel-web-request-get.png?alt=media)

Follow these steps to retrieve the user's ID:

1. From the side menu, click and drag a **Web Request** module to the canvas. The **Web Request** panel opens.

{% hint style="info" %}
If a condition has been added, be sure that the module is positioned at the end of the **YES** branch
{% endhint %}

2. Under **Request Type**, select **GET**.
3. Under **Endpoint**, enter *<https://api.apono.io/api/v2/users/\\{{ticket.from\\_email\\}}>*.
4. From the **Credentials** dropdown menu, select **Inline Credential**.
5. From the **Authentication Type** dropdown menu, select **API key**.
6. Under **Key**, enter *Authorization*.
7. Under **Value**, enter *Bearer APONO\_API\_TOKEN*. Be sure to replace *APONO\_API\_TOKEN* with the value of your Apono personal API token.
8. At the bottom of the panel, in the **Enter Label** field, add a label for the web request module, such as *Grab User ID*.
9. Click **Done**. The **Web Request** panel closes. The module appears on the canvas.

</details>

12. Parse the user ID.

<details>

<summary>Defining a JSON Parser</summary>

![](https://1094436629-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fv6MBfUGvblSdAz31yJXm%2Fuploads%2Fgit-blob-42bda8a7c2eaacda0f646954bb3e8491b5c0d5bb%2Ffreshservice-json-parser.png?alt=media)

Follow these steps to define the JSON parser:

1. From the side menu, click and drag a **JSON Parser** module to the canvas. The **JSON Parser** panel opens.
2. Under **Source**, click **{ + }**. The **Placeholders** menu appears.
3. Click **Web Request Fields > response\_body**.
4. Click **X** to close the **Placeholders** menu.
5. Copy and paste the following JSON object into the **JSON** field.

```json
{
  "id": "1234567890345678",
  "email": "peter.parker@dailybugle.com",
  "first_name": "Peter",
  "last_name": "Parker",
  "active": true
}
```

6. Click **Generate Output** to generate the fields necessary for the next step. The output appears in the **Output** panel.
7. In the **Enter Label** field, enter a label for the module, such as *Parse User ID*.
8. Click **Done**. The **JSON Parser** panel closes. The module appears on the canvas.

</details>

13. Define a web request to create an access request.

<details>

<summary>Defining a Web Request</summary>

![](https://1094436629-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fv6MBfUGvblSdAz31yJXm%2Fuploads%2Fgit-blob-fe7f72bd6eb30a831f3ec75118f771512ec7a827%2Ffreshservice-event-panel-web-request-post.png?alt=media)

Follow these steps to create an access request:

1. From the side menu, click and drag a **Web Request** module to the canvas.
2. Under **Request Type**, select **POST**.
3. Under **Endpoint**, enter *<https://api.apono.io/api/v3/access-requests>*.
4. From the **Credentials** dropdown menu, select **Inline Credential**.
5. From the **Authentication Type** dropdown menu, select **API key**.
6. Under **Key**, enter *Authorization*.
7. Under **Value**, enter *Bearer APONO\_API\_TOKEN*. Be sure to replace *APONO\_API\_TOKEN* with the value of your Apono personal API token.
8. Copy and paste the following JSON payload into the **Body** field. This payload contains all the parameters required by the Apono API.

{% hint style="info" %}
Be mindful of the following points regarding this payload:

* Be sure to replace the following placeholders with the actual Apono ID values:
  * `APONO_INTEGRATION_ID`
  * `RESOURCE_ID_1`, `RESOURCE_ID_2`
  * `PERMISSION_1`, `PERMISSION_2`
* Click **Insert Placeholders** to verify the placeholders. The **Placeholders** window opens.
  * For `user_id`, check **Parser Fields > P1 - Parse User ID > root > id**.
  * For `justification`, check **Tickets > Description**. The `_text` appended to the placeholder ensures that additional HTML is removed from the description.
    {% endhint %}

```json
{
  "user_id": "{{P1.root.id}}",
  "integration_id": "APONO_INTEGRATION_ID",
  "resource_ids": ["RESOURCE_ID_1", "RESOURCE_ID_2"],
  "permissions": ["PERMISSION_1", "PERMISSION_2"],
  "justification": "{{ticket.description_text}}",
  "duration_in_sec": 3600
}
```

9. Add a header:
   1. Under **Headers**, click **Add Header**.
   2. Under **Key**, enter *Content-Type*.
   3. Under **Value**, enter *application/json*.
10. At the bottom of the panel, in the **Enter Label** field, add a label for the module, such as *Access Request*.
11. Click **Done**. The **Web Request** panel closes. The module appears on the canvas.

</details>

14. Click **Activate**. The **Activate Automator** popup window appears.
15. Click **Confirm**.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.apono.io/docs/access-requests-and-approvals/freshservice.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.