arazzo: 1.0.1
info:
  title: Knock Bulk Identify Users and Notify
  summary: Bulk identify a batch of users, wait for the operation to complete, then notify them.
  description: >-
    Bulk identifying users returns a bulk-operation handle that processes
    asynchronously. This flow submits a batch of users, polls the bulk operation
    until it reaches a terminal status, and then triggers a workflow for the
    identified recipients. Every step spells out its request inline so the flow
    can be read and executed without opening the underlying OpenAPI description.
  version: 1.0.0
sourceDescriptions:
- name: knockUsersApi
  url: ../openapi/knock-users-api-openapi.yml
  type: openapi
- name: knockBulkOperationsApi
  url: ../openapi/knock-bulk-operations-api-openapi.yml
  type: openapi
- name: knockWorkflowsApi
  url: ../openapi/knock-workflows-api-openapi.yml
  type: openapi
workflows:
- workflowId: bulk-identify-users-notify
  summary: Bulk identify users, poll the bulk operation, then trigger a workflow.
  description: >-
    Submits a batch of users for identification, polls the returned bulk
    operation until completed or failed, and triggers a workflow for the
    supplied recipient ids.
  inputs:
    type: object
    required:
    - apiKey
    - users
    - recipientIds
    - workflowKey
    properties:
      apiKey:
        type: string
        description: Knock secret API key (sk_...) used as a Bearer token.
      users:
        type: array
        description: The list of user objects to identify in bulk.
        items:
          type: object
      recipientIds:
        type: array
        description: The user ids to trigger the workflow for once identified.
        items:
          type: string
      workflowKey:
        type: string
        description: The key of the workflow to trigger.
      data:
        type: object
        description: Optional data payload passed into the workflow run.
  steps:
  - stepId: bulkIdentify
    description: >-
      Submit the batch of users for identification, returning a bulk operation
      handle to poll.
    operationId: bulkIdentifyUsers
    parameters:
    - name: Authorization
      in: header
      value: Bearer $inputs.apiKey
    requestBody:
      contentType: application/json
      payload:
        users: $inputs.users
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      bulkOperationId: $response.body#/id
  - stepId: pollBulkOperation
    description: >-
      Fetch the bulk operation and check its status. Re-runs this step while the
      operation is still queued or processing.
    operationId: getBulkOperation
    parameters:
    - name: Authorization
      in: header
      value: Bearer $inputs.apiKey
    - name: id
      in: path
      value: $steps.bulkIdentify.outputs.bulkOperationId
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      bulkStatus: $response.body#/status
      processedRows: $response.body#/processed_rows
    onSuccess:
    - name: bulkDone
      type: goto
      stepId: triggerWorkflow
      criteria:
      - context: $response.body
        condition: $.status == 'completed'
        type: jsonpath
    - name: bulkStillRunning
      type: goto
      stepId: pollBulkOperation
      criteria:
      - context: $response.body
        condition: $.status == 'queued' || $.status == 'processing'
        type: jsonpath
  - stepId: triggerWorkflow
    description: >-
      Trigger the workflow for the identified recipients now that the bulk
      identification has completed.
    operationPath: '{$sourceDescriptions.knockWorkflowsApi.url}#/paths/~1v1~1workflows~1{key}~1trigger/post'
    parameters:
    - name: Authorization
      in: header
      value: Bearer $inputs.apiKey
    - name: key
      in: path
      value: $inputs.workflowKey
    requestBody:
      contentType: application/json
      payload:
        recipients: $inputs.recipientIds
        data: $inputs.data
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      workflowRunId: $response.body#/workflow_run_id
  outputs:
    bulkOperationId: $steps.bulkIdentify.outputs.bulkOperationId
    bulkStatus: $steps.pollBulkOperation.outputs.bulkStatus
    workflowRunId: $steps.triggerWorkflow.outputs.workflowRunId