# Workato

**Early Access**: This integration is provided as an Open Authorization API (OAA) connector package. Contact our support team for more information.

## OAA Connector for Workato

Python connector for discovering Workato users and role assignments.

### Overview

This connector uses the Workato API and the Workato SCIM API to retrieve and map user access to roles. This connector does *not* gather detailed information about downstream applications connected to workato via recipes.

*NOTE*: This connector requires Workato API and SCIMv2 support on the Workato platform. Workato API support is an additional feature, provided as part of the **API Platform Add-On** SCIM support is an additional feature, provided as part of the **Advanced Security Add-On**

### Generic Application Mappings

This connector uses the OAA Application template to map applications and identities to permissions. The following table shows how Custom Application entities correspond to Workato entities:

| Workato           | Generic Application |
| ----------------- | ------------------- |
| Workato Workspace | Application         |
| User              | Local User          |
| Role              | Local Role          |
| Project           | Resource            |

### Setup

#### Workato Setup Instructions

1. Generate a Workato API token for a user with sufficient privileges to view all users and projects. See the [Workato API documentation](https://docs.workato.com/workato-api.html#how-to-generate-an-api-token) for complete steps.

Create an API Client Role for Veza. The Veza API Client Role requires the following access:

**Projects**

**Projects & Folders**

* List
* List projects

**Admin**

**Collaborator Roles**

* List non-system roles

**Workspace Details**

* Get details

1. Configure SCIM provisioning on the Workspace. See [Workato SCIM Provisioning](https://docs.workato.com/scim-workato.html#configure-workato) for complete steps.
2. Record the SCIM token.

#### Veza Setup Instructions

1. Generate an API key for your Veza user. API keys can be managed in the Veza interface under Administration -> API Keys. For detailed instructions consult the Veza User Guide.

#### Command Line

1. With Python 3.8+ install the requirements either into a virtual environment or to the system:

   ```shell
   pip3 install -r requirements.txt
   ```
2. Set the Veza API key and Zendesk API key as environment variables. All other parameters can be passed as either environment variables or command line arguments.

   ```shell
   export VEZA_API_KEY=<Veza API key>
   export WORKATO_API_KEY=<Workato API key>
   export WORKATO_SCIM_KEY=<Workato SCIM key>
   ```
3. Run the code, provide any parameters not exported as command line arguments:

   ```shell
   ./veza_workato.py --identity-domain "example.com" --identity-format "first_name.last_name@domain" --veza-url <instance.vezacloud.com>
   ```

**Identity Format**

Due to limitations in the Workato API and SCIM API responses, identity data must be computed during discovery. To ensure that identity information matches other systems discovered by Veza, two parameters must be provided:

1. The `identity-domain`: The IdP/identity domain of discovered users (ex: example.com)
2. The `identity-format` of usernames: The manner in which full display names (ex: John Doe) will be translated into identites

`identity-format` defaults to `<first_name>.<last_name>` (ex: "John Doe" -> john.doe). This can be overridden to `<first_initial><last_name>` (ex: "John Doe" -> jdoe) by setting `identity-format` to `first_initial_last_name` when invoking the connector

**Parameters**

| Parameter            | Environment Variable      | Value                                                                                    |
| -------------------- | ------------------------- | ---------------------------------------------------------------------------------------- |
| `identity-domain`    | `WORKATO_IDENTITY_DOMAIN` | The e-mail domain for discovered Workato users (ex: example.com)                         |
| `identity-format`    | `WORKATO_IDENTITY_FORMAT` | The username format for discovered Workato users (see: [Identity Format](#command-line)) |
| `--workato-api-url`  | `WORKATO_URL`             | URL for the Workato API (defaults to <https://www.workato.com/api> - the US endpoint)    |
| `--workato-scim-url` | `WORKATO_URL`             | URL for the Workato SCIM API (defaults to <https://app.workato.com/scim/v2>)             |
| `n/a`                | `WORKATO_API_KEY`         | API key generated for Workato                                                            |
| `n/a`                | `WORKATO_SCIM_KEY`        | SCIM API key generated for Workato                                                       |
| `--veza-url`         | `VEZA_URL`                | URL of Veza deployment                                                                   |
| `n/a`                | `VEZA_API_KEY`            | API key generated for Veza                                                               |
| `--verbose`          | `n/a`                     | Optional, enable verbose output and debug information                                    |
| `--save-json`        | `n/a`                     | Optional, save OAA payload to JSON file locally for debugging                            |


---

# 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.veza.com/4yItIzMvkpAvMVFAamTf/integrations/integrations/workato.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.