---
name: process-templates
description: >
  Instructs AI agents how to launch, monitor, and download results from
  Kyriba process templates. Used for data import, data export, batch jobs,
  and report generation. Always used in combination with the Data API for imports.
version: 1.0.0
scopes:
  - process-template-scope
authors:
  - kyriba
tags:
  - kyriba
  - connectivity
  - process-templates
  - api
---

> **Auth** — POST {AUTH_BASE_URL}/oauth/token · Basic base64(CLIENT_ID:CLIENT_SECRET) · no scope.
> Use token_type verbatim — do not hardcode `Bearer`. On 401: retry once with the other scheme (`token` vs `Bearer`). On 429: wait Kyriba-Customer-Rate-Limit-Reset.

# Kyriba API Skill: Process Templates

---

## Required Kyriba Permission

```
process-template-scope
```

This is a Kyriba access permission — not an OAuth scope parameter. Do NOT add `scope=` to the token request.

---

## What are Process Templates?

A process template is a reusable workflow in Kyriba for importing, exporting, batching, or reporting. Each run produces a `taskId` used to track execution status and download output.

---

## Base Path

```
/v1/process-templates
```

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/process-templates` | List available process templates |
| `POST` | `/v1/process-templates/{templateRef}/run` | Run a process template |
| `GET` | `/v1/process-templates/{taskUuid}/status` | Get task execution status |
| `GET` | `/v1/process-templates/{taskUuid}/details` | Get full task details |
| `GET` | `/v1/process-templates/{templateRef}/files?taskId={taskUuid}` | Download output file |

`templateRef` accepts either `uuid` or `code`.

---

## Workflow Patterns

### Import Data (file-based)
```
1. POST /v1/data/files          -> fileId       (see Data skill)
2. POST /v1/process-templates/{templateRef}/run?fileIds={fileId}  -> taskId
3. GET  /v1/process-templates/{taskId}/status  -> poll until final status
```

### Export / Trigger (no file)
```
1. POST /v1/process-templates/{templateRef}/run   (no fileIds)   -> taskId
2. GET  /v1/process-templates/{taskId}/status     -> poll until Complete
3. GET  /v1/process-templates/{templateRef}/files?taskId={taskId} -> download
```

### Polling Best Practice
- Interval: **5 seconds**
- Max attempts: **30**
- Stop on: `Complete`, `Warning`, or `Failed`

---

## Run Response

```json
[
  {
    "fileId": null,
    "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
]
```

- For **export/trigger** templates: `fileId` is `null`
- For **import** templates: `fileId` is the UUID of the uploaded file

>  Always verify `taskId` is present for each `fileId` in the response - checking only the HTTP status code is misleading when a file was already integrated.
>  `taskId` is a UUID. Use it directly as the `{taskUuid}` path parameter in status/details/files endpoints.

---

## Task Status Values

| Status | Final? | Meaning |
|---|---|---|
| `Pending` | No | Queued, not yet started |
| `In progress` | No | Currently executing |
| `Complete` |  Yes | Finished successfully |
| `Warning` |  Yes | Finished with some rejected records |
| `Failed` |  Yes | Execution failed |

> `Complete` and `Warning` both mean the task finished. `Warning` = partial success.

---

## Report Format Options

When running a **report** template, pass optional headers:

| Header | Values | Description |
|---|---|---|
| `kyriba-report-format` | `html`, `htmlfp`, `pdf`, `xls`, `xlsx`, `csv` | Override output format |
| `kyriba-report-hide-header` | `true`/`false` | Hide report header |
| `kyriba-report-hide-total` | `true`/`false` | Hide total lines |

> Running a non-report template with `kyriba-report-format` returns `400`.

---

## List Response

```json
{
  "metadata": { "total": 1107, "count": 100, "limit": 100, "offset": 0 },
  "results": [
    {
      "uuid": "...",
      "code": "AD08",
      "interfaceCode": "AD08",
      "description": "Export users",
      "module": "Set-up",
      "category": "Entities and accounts(SU)",
      "type": "Export users",
      "canAdminOwnership": "PUBLIC",
      "canLaunchOnlyOwnership": "PUBLIC",
      "canUseOwnership": "PUBLIC",
      "displayByDefault": false,
      "launchWhenOpening": false,
      "initializedAutomatically": false
    }
  ]
}
```

**Known `category` value patterns:** `Report(AD)`, `Process(EX)`, `Report(Cash)`, `Entities and accounts(SU)`, `Inquire(AD)`, etc.

## Status Response

```
GET /v1/process-templates/{taskUuid}/status
```
```json
{ "status": "Complete" }
```

Status key is `status`. Possible values: `Pending`, `In progress`, `Complete`, `Warning`, `Failed`.

## Details Response

```
GET /v1/process-templates/{taskUuid}/details
```
```json
{
  "uuid": "...",
  "taskType": "Export users",
  "taskStatus": "Complete",
  "taskStartTime": "2026-07-08 23:15:49",
  "taskEndTime": "2026-07-08 23:16:14",
  "taskCode": "AD08_JOB",
  "taskLog": [
    "07/08/2026 <INFO> Start of task ...",
    "07/08/2026 <INFO> Total of exported users: 10",
    "07/08/2026 <INFO> End of task ..."
  ]
}
```

> Note: the details endpoint uses `taskStatus` (not `status`). `taskLog` contains human-readable execution log lines.

## List Templates - Filterable Fields

```
code, uuid, interfaceCode, description, module, category, type
```

**Example - find report templates:**
```
GET /v1/process-templates?filter=category==Report(AD)&sort=code
```

---

## Error Reference

| Status | Meaning |
|---|---|
| `200` | Run succeeded - returns task/file UUIDs |
| `400` | Unsupported template type or invalid params |
| `403` | Required Kyriba permission not configured on your API client |
| `404` | Task or file not found |
| `415` | Wrong Content-Type |

---

## OpenAPI Spec & Postman Collection

- OpenAPI: `https://developer.kyriba.com/static/apis/process-templates/process-templates.yaml`
- Postman: `https://developer.kyriba.com/static/apis/process-templates/process-templates-postman-collection.json`