Custom tasks

With custom tasks you extend a user journey with your own steps:

• an interactive task shows your own hosted page to the user,
• an automated task calls your own API through cidaas.

You add custom tasks to a copy of the standard flow at injection points. This page explains the three building blocks: injection points, custom hosted pages and the Web API registry.

Prerequisites

• A hosted pages layout that the application uses (see Hosted Pages Management).
• For interactive tasks: your hosted page, reachable under a URL for each language you support.
• For automated tasks: an HTTPS endpoint of your system and its credentials.

Injection points

An injection point is a defined place in a user journey where you can add tasks. cidaas offers injection points where your tasks are useful and safe: before or after a security step, never inside it.

Each journey page lists its injection points and what is already known at that point: Login, Onboarding, Account recovery.

Rules for all injection points:

1. Your tasks can add requirements or end the journey. They cannot skip or weaken a security step of cidaas (for example MFA or uniqueness checks).
2. Every application that uses the flow runs your tasks at that injection point.
3. Before the user is authenticated, entered data is not proven. Do not treat an identifier as proof of identity before authentication.

Interactive tasks: custom hosted pages

An interactive task shows a page that you build and host.

Step 1: Add the page to the hosted page group

Add your page to the hosted page group of the layout, with a URL for each language. The ID of a custom page must start with c_, for example c_company_details. IDs without this prefix are reserved for cidaas pages.

Field	Example
Hosted page ID	c_company_details
Locale	en-US, de-DE
URL	https://onboarding.example.com/company?lang=en

Step 2: Reference the page in the task

The operationId of the interactive task is the hosted page ID. cidaas resolves the URL from the hosted page group in the user's language.

- name: company_details
  type: manual
  operationId: c_company_details
  condition: '!has(ctx.c_companyId)'
  timeout: 30m
  outputMapping:
    companyName: c_companyName
    vatId: c_vatId

An interactive task has no input mapping: your page never receives data from the journey context.

How your page gets and returns data

1. Get data: your page calls operations from the Web API registry through cidaas. cidaas adds the credentials, calls your API and returns its response unchanged. cidaas does not add journey context data to the call. Only the operations allowed for this task can be called, and only while the journey waits on this page.
2. Return the result: the step is completed in one of two ways, and cidaas stores the result in the journey context according to the output mapping of the task:
   • by your page, when the user is done, or
   • by your API, server-side: your API has access to the running journey and can complete the step with its result or end the journey. Use this for results your API has decided, for example a verified company or a consent ID.

The browser never calls your API directly and never sees credentials.

Deleting custom pages

You can delete a custom page per language. Make sure it is not used in an active user journey: cidaas does not block the deletion.

Automated tasks: Web API registry

An automated task calls one of your APIs. You register the API once in the Web API registry and reference it in tasks by its operationId.

Step 1: Register the API

Field	Required	Description
operationId	yes	Stable key, lowercase letters, digits and hyphens ([a-z0-9-]+), e.g. crm-check-customer
Display name	yes	Name shown in the admin UI
Description	no	Note for administrators (purpose, owner)
Endpoint, method	yes	URL and HTTP method of your API
Credentials	yes	API key, TOTP, basic authentication or cidaas client credentials (OAuth 2.0)
Allowed path patterns	no	Additional restriction of the URL path

Credentials are stored in cidaas and used server-side only. They are never sent to the browser. Use separate registrations for staging and production.

Step 2: Use the API in a task

- name: crm_check
  type: automated
  executor: webapi
  operationId: crm-check-customer
  timeout: 5s
  inputMapping:
    c_customerNumber: customerNumber
    identifier: email
  outputMapping:
    match: c_crmMatch
    customerId: c_customerId

For automated tasks, cidaas sends the mapped context values to your API and maps the response back into the journey context. If your API does not answer within the timeout, the task fails; use a condition on results.crm_check.status to decide how the journey continues.

Security considerations

Your custom tasks become part of the sign-in, registration and recovery of your users. Follow these rules when you build custom hosted pages and the APIs behind them.

Validate everything the page sends

Everything your page sends — the input of calls through cidaas and the result it completes the step with — comes from the user's browser and can be manipulated.

• Validate all input in your API: type, length, format, allowed values.
• Make decisions in your API, not in the page, for example “customer found” or “company verified”.
• For values that grant something, for example a group ID or a consent ID for the token, do not rely on the result the page sends. Let your API complete the step with the value, or fetch it with a following automated task: then the value reaches the journey context directly from your API.

Protect your APIs and credentials

• Give each Web API registration only the rights it needs, for example read-only access for a lookup.
• Use separate registrations and credentials for staging and production. Rotate credentials regularly.
• Use allowed path patterns to restrict a registration to the endpoints it needs.

Do not reveal whether an account or customer exists

• Before the user is authenticated or the email address or mobile number is verified, show the same message whether or not your check found the person.
• If your check ends the journey, use a neutral message, for example “We could not complete your request.”

Plan for failure

• Set a short timeout on automated tasks and handle results.<task>.status in the following conditions.
• Decide for each task whether the journey continues or ends when your API is unavailable. For checks that protect access, end the journey (fail closed).

Checklist before you publish

• Each custom page has a URL for every language you support.
• Your API validates all input from custom pages.
• Each Web API has separate registrations for staging and production.
• Conditions cover the failure of your API (timeout, error).
• Your tasks write only your own c_ variables or variables that allow writing.
• You have tested the journey with and without your tasks taking effect.

Need Support?

Please contact us directly on our support page or reach out to cidaas support at [email protected].