Understanding Scenarios

A Scenario is a predefined template that defines the structure, input schema, and lifecycle behaviors of Requests for Information (RFIs). Scenarios enable organizations to standardize the creation and management of RFIs by providing a consistent framework tailored to specific use cases or regulatory requirements.

By leveraging scenarios, you can:

Ensure Consistency: Use standardized templates for common RFI processes.
Simplify RFI Creation: Reduce the need to define the structure and requirements for each new RFI.
Enhance Compliance: Align RFIs with regulatory requirements by using predefined schemas.
Improve Efficiency: Streamline workflows by reusing scenarios for recurring processes.

What is a Scenario?

A scenario is essentially a blueprint for creating RFIs. It encapsulates:

Input Schema: Defines the data structure required when creating an RFI.
Display Metadata: Provides UI rendering instructions for client applications.
Lifecycle Behaviors: Specifies how RFIs based on the scenario progress through different states.
Time-to-Live (TTL): Sets the expiration time for RFIs, if applicable.

Scenarios are represented as resources within the API and have unique identifiers that are used when creating drafts or RFIs.

Key Components of a Scenario

Input Schema

Definition: A JSON schema that specifies the required and optional fields when creating an RFI.
Purpose: Ensures that all RFIs based on the scenario contain consistent and valid data.
Usage: Validates the input field when creating drafts or RFIs.

Display Metadata

Definition: Contains information for rendering the RFI in client applications.
Components:
- Instructions: Localized text providing guidance on how to handle the RFI.
- Groups and Questions: Defines how questions are grouped and displayed.
Purpose: Enhances the user experience by providing structured and localized content.

RFI TTL (Time-to-Live)

Definition: Specifies the duration after which an RFI will expire if not completed.
Purpose: Enforces deadlines and automates the lifecycle of RFIs.
Usage: Set using the rfi_ttl field in the scenario, formatted as a duration string (e.g., "3600s" for one hour).

Annotations

Definition: Key-value pairs for storing arbitrary metadata related to the scenario.
Purpose: Allows for custom metadata without affecting the scenario's functionality.
Usage: Accessible via the annotations field.

Managing Scenarios

Listing Scenarios

Retrieve a list of available scenarios to identify which one suits your needs.

Request

GET /request/v1alpha/scenarios
Host: api.{customer}.app.identitii.com
Authorization: Bearer {access_token}

Response

{
  "scenarios": [
    {
      "name": "scenarios/counterparty-assurance",
      "display_name": "Counterparty Assurance",
      "rfi_input_json_schema": { /* Schema details */ },
      "rfi_ttl": "86400s",
      /* Other scenario details */
    },
    /* Other scenarios */
  ]
}

Getting a Scenario

Fetch detailed information about a specific scenario.

Request

GET /request/v1alpha/scenarios/{scenario}
Host: api.{customer}.app.identitii.com
Authorization: Bearer {access_token}

Replace {scenario} with the scenario ID (e.g., counterparty-assurance).

Response

{
  "name": "scenarios/counterparty-assurance",
  "display_name": "Counterparty Assurance",
  "rfi_input_json_schema": { /* Schema details */ },
  "rfi_ttl": "86400s",
  /* Other scenario details */
}

Deleting a Scenario

Remove an unwanted scenario from your environment.

Request

DELETE /request/v1alpha/scenarios/{scenario}
Host: api.{customer}.app.identitii.com
Authorization: Bearer {access_token}

Response

A successful deletion will return a 200 OK status with an empty body.

Undeleting a Scenario

Restore a previously deleted scenario.

Request

POST /request/v1alpha/scenarios/{scenario}:undelete
Host: api.{customer}.app.identitii.com
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "name": "scenarios/{scenario}"
}

Response

{
  "name": "scenarios/{scenario}",
  /* Restored scenario details */
}

Using Scenarios

Step 1: Select an Appropriate Scenario

Identify the scenario that matches your RFI requirements by listing available scenarios and reviewing their display_name and rfi_input_json_schema.

Step 2: Create an RFI (or a Draft)

Directly Create an RFI: Use the scenario to create an RFI in one step.
Optionally Create a Draft: Start with a draft if you need to compose and refine the RFI before publishing.

Creating an RFI

POST /request/v1alpha/scenarios/{scenario}/rfis
Host: api.{customer}.app.identitii.com
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "input": { /* Data adhering to the scenario's input schema */ },
  "creator_team": "teams/{creator_team_id}",
  "broker_team": "teams/{broker_team_id}",
  "assignee_team": "teams/{assignee_team_id}"
}

Creating a Draft

POST /request/v1alpha/scenarios/{scenario}/drafts
Host: api.{customer}.app.identitii.com
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "input": { /* Data adhering to the scenario's input schema */ },
  "creator_team": "teams/{creator_team_id}",
  "broker_team": "teams/{broker_team_id}",
  "assignee_team": "teams/{assignee_team_id}"
}

Step 3: Proceed with the RFI Workflow

Respond to the RFI: Assignee team provides the required information.
Submit for Review: Responses are submitted for broker team's review.
Review and Complete: Broker team approves or rejects responses, completing the RFI lifecycle.

Benefits of Using Scenarios

Standardization: Ensures all RFIs follow a consistent structure and process.
Compliance: Aligns RFIs with regulatory standards and internal policies.
Efficiency: Reduces the time and effort required to create and manage RFIs.
Reusability: Scenarios can be reused across different RFIs, promoting best practices.

Customizing Scenarios

While scenarios are predefined, they can often be customized to fit specific organizational needs:

Annotations: Add custom metadata to scenarios for internal tracking.
Extensions: Depending on your environment, you may be able to define new scenarios or modify existing ones (contact support for more information).

Scenario Lifecycle

Active: Scenario is available for use in creating RFIs or drafts.
Deleted: Scenario is soft-deleted and can be restored using the undelete operation.
Archived: Scenarios may be archived to prevent future use while retaining historical data (implementation dependent).

Best Practices

Regularly Review Scenarios: Ensure that scenarios remain up-to-date with regulatory changes and organizational policies.
Document Custom Scenarios: If you create custom scenarios, document their purpose and structure for team members.
Use Meaningful Display Names: Assign clear and descriptive display_name values to scenarios for easy identification.

Example: Listing and Selecting a Scenario

List Scenarios

GET /request/v1alpha/scenarios
Host: api.{customer}.app.identitii.com
Authorization: Bearer {access_token}

Response

{
  "scenarios": [
    {
      "name": "scenarios/counterparty-assurance",
      "display_name": "Counterparty Assurance",
      /* Other details */
    },
    {
      "name": "scenarios/customer-onboarding",
      "display_name": "Customer Onboarding",
      /* Other details */
    },
    {
      "name": "scenarios/sanctions-list-match-resolution",
      "display_name": "Sanctions List Match Resolution",
      /* Other details */
    }
  ]
}

Select a Scenario

Choose the scenario that matches your RFI needs.
For example, to handle a sanctions list match, select scenarios/sanctions-list-match-resolution.

Additional Considerations

Error Handling

Invalid Input: If the data provided does not match the scenario's input schema, the API will return a validation error.
Permissions: Ensure your API credentials have the necessary permissions to access and manage scenarios.

ETags and Concurrency

ETags: Use the etag field for optimistic concurrency control when updating or deleting scenarios.
Concurrency: Handle concurrent modifications by checking ETags and retrying operations as needed.

Conclusion

Scenarios are a powerful feature that enable organizations to standardize and streamline the creation and management of RFIs. By understanding and effectively utilizing scenarios, you can enhance compliance, improve efficiency, and ensure consistency across your RFI processes.

Next Steps

Integrate Scenarios: Incorporate scenario selection and management into your RFI workflows.
Explore Scenarios: Review the available scenarios to identify those that best fit your needs.
Customize: Contact us to create custom scenarios tailored to your needs.

Note: Replace placeholders like {customer}, {access_token}, {scenario}, {creator_team_id}, {broker_team_id}, and {assignee_team_id} with your actual values when making API calls.

Understanding Scenarios

What is a Scenario?

Key Components of a Scenario

Input Schema

Display Metadata

RFI TTL (Time-to-Live)

Annotations

Managing Scenarios

Listing Scenarios

Getting a Scenario

Deleting a Scenario

Undeleting a Scenario

Using Scenarios

Step 1: Select an Appropriate Scenario

Step 2: Create an RFI (or a Draft)

Step 3: Proceed with the RFI Workflow

Benefits of Using Scenarios

Customizing Scenarios

Scenario Lifecycle

Best Practices

Example: Listing and Selecting a Scenario

List Scenarios

Select a Scenario

Additional Considerations

Error Handling

ETags and Concurrency

Conclusion

Next Steps

Was this helpful?