Change Broker configuration workflow

Use this configuration workflow to onboard a client application to Change Broker. This flow establishes a valid signup context, confirms readiness for update retrieval, and aligns monitored scope with your intended streams. After completing this workflow, your client application is ready to begin update retrieval with a valid starting bookmark and verified subscription.

Prerequisites

• Your client application can authenticate and authorize requests for the target account and service instance.

• The identity querying updates is the signup owner.

• You know the stream IDs that you want to monitor.

• Your client application can persist bookmark values between application restarts.

1. Create and activate a signup

This phase provisions a signup and confirms readiness for update retrieval by waiting for both Active state and bookmark availability, ensuring your client application has a valid starting bookmark.

1. Create signup with desired stream IDs (optional inactivity period) using the Create signup endpoint.

   Include the stream IDs you want to monitor in the create-signup request whenever possible. A successful request returns 202 Accepted, and the signup enters the Activating state. Signups are not deduplicated by name, so each request creates a new signup with a unique ID. If the service instance has reached its signup limit, the endpoint returns a 409 Conflict response.

2. Get signup by ID using the Get signup by ID endpoint. Poll until the signup is Active and bookmarkInfo.bookmarkAvailable is true, then persist the bookmark from bookmarkInfo.bookmark.

   The system returns the signup state and bookmark availability on each poll. Continue polling until the response shows Active state and bookmarkInfo.bookmarkAvailable: true, then read bookmarkInfo.bookmark and persist it immediately. This bookmark is required as the starting position for the first update query.

If either step does not behave as expected, verify account and service instance targeting first. If targeting is correct and the issue persists, use Change Broker troubleshooting and contact support.

2. Configure monitored streams

This phase validates stream accessibility and updates monitored streams when your subscribed set needs to change. In most cases, include your desired stream IDs when creating the signup, then use this phase to verify accessibility and apply later stream changes.

3. Update signup resources (stream IDs), as needed using the Update signup resources endpoint.

   Use this step when you need to add, remove, or replace stream resources after signup creation. If the signup already includes the streams you want to monitor, you can skip this step and continue to stream accessibility verification. A successful request returns 204 No Content. If some resources could not be processed, the endpoint returns 207 Multi-Status with details about which resources failed. Change Broker checks stream accessibility in the background after resources are added.

4. Get signup resources using the Get signup resources endpoint. Verify subscription and accessibility.

   The system returns the collection of resources associated with the signup, including the signup owner's authorization status for each resource (isAccessible: true or isAccessible: false). This helps confirm that expected streams are currently eligible to return data, but results might not be immediate. A resource can temporarily appear as isAccessible: false while background accessibility checks are still in progress.

   Note: Accessibility checks run asynchronously, so results may not be immediate for signups that have not been used within the past hour or for newly added streams. For example, after you update signup resources, or after a signup has been inactive for 1 hour or more, a resource can temporarily appear as isAccessible: false until background access checks finish. If needed, wait briefly and make the request again to confirm the latest accessibility state.

After these steps, your client application is ready to start update retrieval.

Next steps

• To start retrieving change data with your active signup and bookmark, see Change Broker update workflow.

• For setup mismatch recovery paths, see Change Broker troubleshooting.