# 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**.