> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getprimo.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Execute a SaaS selection intent
> Validate the SaaS selection of an onboarding: opens one SAAS_PROVISIONING task per app in `apps` under the onboarding ticket, started now or SCHEDULED until `scheduleDate`, then completes the "Configure SaaS provisioning" task (type SAAS_SELECTION). This is the only way to complete a SAAS_SELECTION task: `updateTaskStatus` refuses it with `TaskLockedByTypeError` naming this operation. Start `apps` from `proposedApps` of `getSaasSelectionIntent`, taking each `saasId` from there or from `getSaas`: a `saasId` that is not a SaaS of the company, an app the onboarding ticket already has an account task for, the email provider and an app that creates its accounts at first login get no task, without a refusal; an empty `apps` opens none. To add one app to an onboarding without this task, use `createSaasProvisioningIntent`. Safe to retry: a selection validated earlier answers `outcome: ALREADY_EXECUTED` and opens nothing again. A `personalEmail` another employee already holds is not saved. Refused with `INVALID_SAAS_SELECTION` (a `saasId` that is not an id, or a recipient without an email), `TICKET_CLOSED` (the task was cancelled), `EXECUTION_IN_PROGRESS`, `INTENT_NOT_FOUND`.
Key: WriteScope: Company
## OpenAPI
````yaml https://api.getprimo.com/openapi.json post /saas-selection-intents/{intentId}/execute
openapi: 3.1.1
info:
title: Public API - BETA
description: Read docs on https://docs.getprimo.com/
version: '1.0'
contact: {}
servers:
- url: https://api.getprimo.com
security:
- apikey: []
tags: []
paths:
/saas-selection-intents/{intentId}/execute:
post:
tags:
- Onboardings
summary: Execute a SaaS selection intent
description: >-
Validate the SaaS selection of an onboarding: opens one
SAAS_PROVISIONING task per app in `apps` under the onboarding ticket,
started now or SCHEDULED until `scheduleDate`, then completes the
"Configure SaaS provisioning" task (type SAAS_SELECTION). This is the
only way to complete a SAAS_SELECTION task: `updateTaskStatus` refuses
it with `TaskLockedByTypeError` naming this operation. Start `apps` from
`proposedApps` of `getSaasSelectionIntent`, taking each `saasId` from
there or from `getSaas`: a `saasId` that is not a SaaS of the company,
an app the onboarding ticket already has an account task for, the email
provider and an app that creates its accounts at first login get no
task, without a refusal; an empty `apps` opens none. To add one app to
an onboarding without this task, use `createSaasProvisioningIntent`.
Safe to retry: a selection validated earlier answers `outcome:
ALREADY_EXECUTED` and opens nothing again. A `personalEmail` another
employee already holds is not saved. Refused with
`INVALID_SAAS_SELECTION` (a `saasId` that is not an id, or a recipient
without an email), `TICKET_CLOSED` (the task was cancelled),
`EXECUTION_IN_PROGRESS`, `INTENT_NOT_FOUND`.
operationId: executeSaasSelectionIntent
parameters:
- name: intentId
required: true
in: path
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExecuteSaasSelectionIntentBody'
responses:
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ExecuteSaasSelectionIntentResult_Output'
components:
schemas:
ExecuteSaasSelectionIntentBody:
type: object
properties:
apps:
description: >-
The applications to open an account task for — start from
`proposedApps` of `getSaasSelectionIntent`, then drop, add or
adjust. An empty list opens none and completes the task.
type: array
items:
type: object
properties:
saasId:
description: >-
The SaaS application (`id` from `getSaas`, or `saasId` of a
proposed app)
type: string
pattern: ^[a-f\d]{24}$
groups:
type: array
items:
type: object
properties:
id:
description: >-
The entitlement id from `getSaasById` of the
application, or null for one only an admin knows by name
anyOf:
- type: string
- type: 'null'
name:
type: string
minLength: 1
required:
- name
roles:
type: array
items:
type: object
properties:
id:
description: >-
The entitlement id from `getSaasById` of the
application, or null for one only an admin knows by name
anyOf:
- type: string
- type: 'null'
name:
type: string
minLength: 1
required:
- name
licenses:
type: array
items:
type: object
properties:
id:
description: >-
The entitlement id from `getSaasById` of the
application, or null for one only an admin knows by name
anyOf:
- type: string
- type: 'null'
name:
type: string
minLength: 1
required:
- name
organizationUnits:
type: array
items:
type: object
properties:
id:
description: >-
The entitlement id from `getSaasById` of the
application, or null for one only an admin knows by name
anyOf:
- type: string
- type: 'null'
name:
type: string
minLength: 1
required:
- name
credentialsRecipient:
anyOf:
- type: object
properties:
type:
description: >-
Who receives the temporary password of a new account.
EMPLOYEE sends it to the personal email; MANAGER and
TASK_OWNER are resolved when the account is created.
type: string
enum:
- ADMIN
- EMPLOYEE
- MANAGER
- TASK_OWNER
email:
description: >-
The address the password is sent to; empty only for
MANAGER or TASK_OWNER
anyOf:
- type: string
format: email
pattern: >-
^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
- type: string
const: ''
required:
- type
- email
- type: 'null'
required:
- saasId
scheduleDate:
description: >-
Creates each account task SCHEDULED until this date when it is in
the future; without it they start now.
anyOf:
- type: string
format: date-time
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
- type: 'null'
personalEmail:
description: >-
The employee's personal address, saved on the employee before the
account tasks open.
anyOf:
- type: string
format: email
pattern: >-
^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
- type: 'null'
required:
- apps
ExecuteSaasSelectionIntentResult_Output:
type: object
properties:
outcome:
type: string
description: >-
ALREADY_EXECUTED: the selection was validated earlier — no account
task was opened again
enum:
- EXECUTED
- ALREADY_EXECUTED
intent:
type: object
properties:
id:
type: string
description: Intent id — pass it to `executeSaasSelectionIntent`
taskId:
description: The SAAS_SELECTION task ("Configure SaaS provisioning")
anyOf:
- type: string
- type: 'null'
ticketId:
description: The onboarding ticket holding that task. Null if unreadable.
anyOf:
- type: string
- type: 'null'
employeeId:
type: string
proposedApps:
type: array
description: >-
The applications proposed for the employee when the task opened,
in the shape `apps` takes
items:
type: object
properties:
saasId:
description: The SaaS application (`id` from `getSaas`)
type: string
groups:
type: array
items:
type: object
properties:
id:
description: >-
The entitlement id from `getSaasById` of the
application, or null for one only an admin knows by
name
anyOf:
- type: string
- type: 'null'
name:
type: string
minLength: 1
required:
- id
- name
additionalProperties: false
roles:
type: array
items:
type: object
properties:
id:
description: >-
The entitlement id from `getSaasById` of the
application, or null for one only an admin knows by
name
anyOf:
- type: string
- type: 'null'
name:
type: string
minLength: 1
required:
- id
- name
additionalProperties: false
licenses:
type: array
items:
type: object
properties:
id:
description: >-
The entitlement id from `getSaasById` of the
application, or null for one only an admin knows by
name
anyOf:
- type: string
- type: 'null'
name:
type: string
minLength: 1
required:
- id
- name
additionalProperties: false
organizationUnits:
type: array
items:
type: object
properties:
id:
description: >-
The entitlement id from `getSaasById` of the
application, or null for one only an admin knows by
name
anyOf:
- type: string
- type: 'null'
name:
type: string
minLength: 1
required:
- id
- name
additionalProperties: false
credentialsRecipient:
description: >-
Who receives the password of a new account; empty email
for MANAGER or TASK_OWNER
anyOf:
- type: object
properties:
type:
description: >-
Who receives the temporary password of a new
account. EMPLOYEE sends it to the personal email;
MANAGER and TASK_OWNER are resolved when the
account is created.
type: string
enum:
- ADMIN
- EMPLOYEE
- MANAGER
- TASK_OWNER
email:
type: string
required:
- type
- email
additionalProperties: false
- type: 'null'
required:
- saasId
- groups
- roles
- licenses
- organizationUnits
- credentialsRecipient
additionalProperties: false
executedAt:
description: When the selection was validated; null while it is open
anyOf:
- type: string
format: date-time
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
- type: 'null'
createdAt:
type: string
format: date-time
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
updatedAt:
type: string
format: date-time
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
required:
- id
- taskId
- ticketId
- employeeId
- proposedApps
- executedAt
- createdAt
- updatedAt
additionalProperties: false
required:
- outcome
- intent
additionalProperties: false
securitySchemes:
apikey:
scheme: bearer
bearerFormat: API key
type: http
description: >-
Use your Primo API key in the Authorization header as `Bearer
`.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.