Concepts
/
Teams
Last updated

Understanding Teams in the API

Introduction

A Team represents a group within your organization that participates in the Request for Information (RFI) process. Teams are fundamental to organizing workflows, assigning responsibilities, and facilitating collaboration among different departments or units. By structuring your organization into teams within the API, you can:

  • Assign RFIs to specific groups for handling.
  • Manage permissions and access control at the team level.
  • Streamline communication and workflow among stakeholders.
  • Enhance accountability by tracking which team is responsible for each RFI.

What is a Team?

A team is a resource that encapsulates a group of users or a department within your organization. Each team has:

  • A unique identifier (name): Used to reference the team in API operations.
  • A display name (display_name): A human-readable name for UI and identification purposes.
  • Optional annotations: Key-value pairs for storing additional metadata.
  • Timestamps: Metadata indicating creation, update, and deletion times.
  • An ETag (etag): Used for optimistic concurrency control.

Teams are crucial for assigning roles and responsibilities in the RFI process, ensuring that the right group handles each task.

Roles of Teams in the RFI Process

Teams play specific roles in managing the lifecycle of an RFI:

1. Creator Team

  • Definition: The team that initiates or creates the RFI.
  • Responsibilities:
    • Defines the purpose and requirements of the RFI.
    • Provides initial input data when creating the RFI.
  • Usage: Specified using the creator_team field when creating an RFI or draft.

2. Broker Team

  • Definition: The team that facilitates and coordinates the RFI process.
  • Responsibilities:
    • Manages the workflow between the creator and assignee teams.
    • Reviews responses provided by the assignee team.
    • Approves or rejects answers during the review process.
  • Usage: Specified using the broker_team field when creating an RFI or draft.

3. Assignee Team

  • Definition: The team initially assigned to respond to the RFI.
  • Responsibilities:
    • Provides answers to the questions posed in the RFI.
    • Submits responses for review by the broker team.
  • Usage: Specified using the assignee_team field when creating an RFI or draft.

Managing Teams

Creating a Team

Establish a new team within your organization.

Request

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

{
  "display_name": "Compliance Team",
  "annotations": {
    "department": "Compliance",
    "location": "Head Office"
  }
}

Response

{
  "name": "teams/compliance-team-id",
  "uid": "unique-team-uid",
  "display_name": "Compliance Team",
  "annotations": {
    "department": "Compliance",
    "location": "Head Office"
  },
  "create_time": "2023-10-01T12:00:00Z",
  /* Other team details */
}

Action

  • Note the name of the team (e.g., teams/compliance-team-id) for future reference.

Listing Teams

Retrieve all teams within your organization.

Request

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

Response

{
  "teams": [
    {
      "name": "teams/compliance-team-id",
      "display_name": "Compliance Team",
      /* Other team details */
    },
    {
      "name": "teams/operations-team-id",
      "display_name": "Operations Team",
      /* Other team details */
    },
    /* Other teams */
  ]
}

Getting a Team

Fetch details of a specific team.

Request

GET /request/v1alpha/teams/{team}
Host: api.{customer}.app.identitii.com
Authorization: Bearer {access_token}
  • Replace {team} with the team ID (e.g., compliance-team-id).

Response

{
  "name": "teams/compliance-team-id",
  "display_name": "Compliance Team",
  "annotations": {
    "department": "Compliance",
    "location": "Head Office"
  },
  /* Other team details */
}

Updating a Team

Modify the information of an existing team.

Request

PATCH /request/v1alpha/teams/{team}
Host: api.{customer}.app.identitii.com
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "display_name": "Global Compliance Team",
  "annotations": {
    "department": "Compliance",
    "location": "Global"
  }
}
  • Include the fields you wish to update.
  • Use the update_mask query parameter to specify which fields to update (optional).

Response

{
  "name": "teams/compliance-team-id",
  "display_name": "Global Compliance Team",
  "annotations": {
    "department": "Compliance",
    "location": "Global"
  },
  /* Other team details */
}

Deleting a Team

Remove a team that is no longer active.

Request

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

Response

  • A successful deletion returns a 200 OK status with an empty body.

Undeleting a Team

Restore a previously deleted team.

Request

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

{
  "name": "teams/{team}"
}

Response

{
  "name": "teams/{team}",
  /* Restored team details */
}

Using Teams in the RFI Process

Assigning Teams When Creating an RFI

When creating an RFI or a draft, you must specify the relevant teams:

Request

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

{
  "input": { /* RFI input data */ },
  "creator_team": "teams/{creator_team_id}",
  "broker_team": "teams/{broker_team_id}",
  "assignee_team": "teams/{assignee_team_id}"
}
  • Replace {creator_team_id}, {broker_team_id}, and {assignee_team_id} with the appropriate team IDs.

RFI Lifecycle and Team Responsibilities

  • Creation: The creator team initiates the RFI.
  • Assignment: The RFI is assigned to the assignee team for response.
  • Review: The broker team reviews the responses.
  • Completion: Upon approval, the RFI is completed, and responsibility may return to the creator team.

Changing Teams

  • Current Assignee Team: The team currently responsible for the RFI.
  • Reassignment: The current_assignee_team changes automatically based on RFI state transitions (e.g., from assignee team to broker team upon submission for review).

Best Practices

Define Clear Team Roles

  • Distinct Responsibilities: Ensure each team has a well-defined role in the RFI process.
  • Avoid Overlaps: Minimize confusion by preventing overlapping responsibilities between teams.

Use Meaningful Display Names

  • Clarity: Assign descriptive display_name values for easy identification.
  • Consistency: Maintain consistent naming conventions across teams.

Manage Teams Lifecycle

  • Regular Audits: Periodically review teams to ensure they are still needed.
  • Handle Deletions Carefully: Be cautious when deleting teams to avoid disrupting ongoing RFIs.

Utilize Annotations

  • Metadata Storage: Use annotations to store additional information about the team (e.g., department codes, manager names).
  • Custom Attributes: Add organization-specific attributes without affecting the team's functionality.

Additional Considerations

Permissions and Access Control

  • API Credentials: Ensure that your API credentials have the necessary permissions to manage teams.
  • Team-Level Security: Implement access controls to restrict who can create, update, or delete teams.

Error Handling

  • Check for Errors: Always inspect API responses for errors and handle them appropriately.
  • Conflict Resolution: Use etag for optimistic concurrency control to prevent conflicting updates.

Hierarchical Teams (if applicable)

  • Parent Teams: If your organization uses hierarchical teams, utilize the parent_team field to represent team hierarchies.
  • Inheritance: Understand how responsibilities and permissions might inherit from parent to child teams.

Example: Creating and Using Teams

Step 1: Create Teams

Create the Creator Team

POST /request/v1alpha/teams
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "display_name": "Onboarding Team"
}

Create the Broker Team

POST /request/v1alpha/teams
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "display_name": "Compliance Team"
}

Create the Assignee Team

POST /request/v1alpha/teams
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "display_name": "Customer Service Team"
}

Step 2: Assign Teams When Creating an RFI

Create an RFI

POST /request/v1alpha/scenarios/customer-onboarding/rfis
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "input": { /* Customer onboarding data */ },
  "creator_team": "teams/onboarding-team-id",
  "broker_team": "teams/compliance-team-id",
  "assignee_team": "teams/customer-service-team-id"
}

Benefits of Using Teams

  • Organized Workflow: Streamlines the RFI process by clearly defining responsibilities.
  • Enhanced Collaboration: Facilitates communication between different groups.
  • Accountability: Tracks which team is responsible at each stage of the RFI lifecycle.
  • Scalability: Easily manage teams as your organization grows or changes.

Conclusion

Teams are a foundational concept, enabling structured and efficient management of the RFI process. By understanding and effectively utilizing teams, you can enhance collaboration, ensure accountability, and streamline workflows within your organization.

Next Steps

  • Implement Team Management: Integrate team creation and assignment into your onboarding processes.
  • Review Team Roles: Ensure that each team's role in the RFI process aligns with your organizational structure.
  • Explore Advanced Features: Investigate hierarchical teams and custom annotations to further tailor team functionality to your needs.

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

Previous page
Next page