Mappings

API endpoints for mapping-related data mapping operations.

List All Mappings

get

This endpoint retrieves a list of all mappings in the data mapping system. It provides a comprehensive view of all the relationships and associations defined between different entities such as people, projects, and organizational units.

Use Cases

Relationship Overview: Obtain a full list of mappings to understand how entities are connected within the system.
Data Integration: Synchronize mapping data with external systems that rely on these relationships.
Auditing and Compliance: Review mappings for auditing purposes to ensure data integrity and compliance with organizational policies.

Required Access

Authentication: Bearer token is required.
Permissions: User must have appropriate roles and rights to view mapping records.

Authorizations

AuthorizationstringRequired

API authentication using Bearer tokens. Include your API token in the Authorization header: Authorization: Bearer <your-api-token>

Tokens can be obtained from the Opsera platform's API token management interface.

Responses

200

Successfully retrieved the list of mappings.

application/json

countintegerOptional

Total number of mappings retrieved.

Example: 42

400

Bad request - Invalid input parameters.

application/json

401

Unauthorized - Authentication failed or insufficient permissions.

application/json

500

Internal server error.

application/json

get

/api/v2/data/mapping

GET /api/v2/data/mapping HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "count": 42,
  "data": [
    {
      "id": "<mapping-id>",
      "parent": "department-id-123",
      "child": "team-id-456",
      "attributes": {
        "parentType": "department",
        "childType": "team",
        "relationship": "parent-child",
        "mappingType": "org-hierarchy"
      },
      "createdAt": "2023-11-01T12:00:00.000Z",
      "updatedAt": "2023-11-05T12:00:00.000Z"
    }
  ]
}

Create a New Mapping

post

Creates a new mapping in the data mapping system. This endpoint allows for the creation of mappings between entities such as people, projects, or organizational hierarchies. For more details, refer to the Opsera API Documentation.

Use Cases

People to Projects: Map individuals to specific projects for organizational tracking.
Organizational Hierarchies: Define relationships between different levels of an organization, such as departments, teams, or groups.
Integration and Synchronization: Establish mappings for system integrations and data synchronization.

Required Access

Authentication: Bearer token is required.
API Scope: api
Site Roles:
- Opsera Administrator
- Administrator
- Power User

Important Notes!
Mandatory Fields: The parent and child fields are required to establish a mapping.
Entity Existence: Ensure that the entities you are mapping (parent and child) already exist in the system.
Type Validation: The parentType and childType should accurately reflect the types of the entities (e.g., "department", "team", "person").
Attribute Definition: The attributes object can include additional metadata about the mapping.
Error Handling: Appropriate HTTP status codes are returned for different error scenarios.

Authorizations

AuthorizationstringRequired

API authentication using Bearer tokens. Include your API token in the Authorization header: Authorization: Bearer <your-api-token>

Tokens can be obtained from the Opsera platform's API token management interface.

Body

parentstringRequired

The unique identifier of the parent entity in the mapping.

Example: department-id-123

parentTypestringOptional

The type of the parent entity (e.g., "department", "team").

Example: department

childstringRequired

The unique identifier of the child entity in the mapping.

Example: team-id-456

childTypestringOptional

The type of the child entity (e.g., "team", "person").

Example: team

Responses

201

Mapping created successfully.

application/json

400

Bad Request - Invalid or missing input data.

application/json

401

Unauthorized - Authentication failed or insufficient permissions.

application/json

500

Internal Server Error - An unexpected error occurred.

application/json

post

/api/v2/data/mapping

POST /api/v2/data/mapping HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 172

{
  "parent": "department-id-123",
  "parentType": "department",
  "child": "team-id-456",
  "childType": "team",
  "attributes": {
    "relationship": "parent-child",
    "mappingType": "org-hierarchy"
  }
}

{
  "id": "<mapping-id>",
  "parent": "department-id-123",
  "parentType": "department",
  "child": "team-id-456",
  "childType": "team",
  "attributes": {
    "relationship": "parent-child",
    "mappingType": "org-hierarchy"
  },
  "createdAt": "2023-11-01T12:00:00.000Z"
}

Get a Mapping

get

This endpoint retrieves a specific mapping from the data mapping system using the mapping's unique ID. It allows you to fetch detailed information about relationships between entities, such as organizational hierarchies or project associations. For more details, refer to the Opsera API Documentation.

Use Cases

Retrieve Relationships: Fetch specific relationships between entities.
Audit and Validation: Validate existing mappings for data accuracy or compliance.
System Integrations: Retrieve mapping details for integration into external systems or workflows.

Required Access

Authentication: Bearer token is required.
API Scope: api
Site Roles:
- Opsera Administrator
- Administrator
- Power User

Important Notes!
Valid ID Format: The id path parameter must be a 24-character hexadecimal string.
Data Sensitivity: The mapping data may contain sensitive information. Handle it accordingly.
Error Handling: Appropriate HTTP status codes are returned for different error scenarios.

Authorizations

AuthorizationstringRequired

API authentication using Bearer tokens. Include your API token in the Authorization header: Authorization: Bearer <your-api-token>

Tokens can be obtained from the Opsera platform's API token management interface.

Path parameters

idstringRequired

The unique identifier of the mapping. Must be a 24-character alphanumeric string.

Example: 507f1f77bcf86cd799439011Pattern: ^[a-zA-Z0-9]{24}

Responses

200

Mapping retrieved successfully.

application/json

idstringOptional

The unique identifier of the mapping.

Example: <mapping-id>

parentstringOptional

The unique identifier of the parent entity in the mapping.

Example: department-id-123

childstringOptional

The unique identifier of the child entity in the mapping.

Example: team-id-456

400

Bad Request - Invalid ID format.

application/json

401

Unauthorized - Authentication failed or insufficient permissions.

application/json

403

Forbidden - Access is denied.

application/json

404

Not Found - Mapping not found.

application/json

500

Internal Server Error - An unexpected error occurred.

application/json

get

/api/v2/data/mapping/{id}

GET /api/v2/data/mapping/{id} HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "<mapping-id>",
  "parent": "department-id-123",
  "child": "team-id-456",
  "attributes": {
    "parentType": "department",
    "childType": "team",
    "relationship": "parent-child",
    "mappingType": "org-hierarchy"
  }
}

Update a Mapping

put

This endpoint updates an existing mapping in the data mapping system using the mapping's unique ID. It allows you to modify the relationships and attributes associated with a specific mapping record.

Use Cases

Relationship Updates: Modify existing mappings to reflect changes in organizational structure or project assignments.
Data Correction: Correct any inaccuracies or outdated information in a mapping record.
Integration Synchronization: Ensure that changes in mappings are consistently reflected across integrated systems.

Required Access

Authentication: Bearer token is required.
Permissions: User must have appropriate roles and rights to update mapping records.

Important Notes!
ID Format: The id parameter must be a 24-character alphanumeric string matching the pattern ^[a-zA-Z0-9]{24}$.
Partial Updates: Include only the fields you wish to update in the request body; unspecified fields will remain unchanged.
Validation: Ensure that the provided data adheres to the expected formats and constraints.
Concurrency: Be cautious of concurrent updates; consider implementing versioning or checks to prevent overwriting changes.

Authorizations

AuthorizationstringRequired

API authentication using Bearer tokens. Include your API token in the Authorization header: Authorization: Bearer <your-api-token>

Tokens can be obtained from the Opsera platform's API token management interface.

Path parameters

idstringRequired

The unique identifier of the mapping to update.

Example: <mapping-id>Pattern: ^[a-zA-Z0-9]{24}

Body

parentstringOptional

The updated unique identifier of the parent entity in the mapping.

Example: updated-department-id-123

childstringOptional

The updated unique identifier of the child entity in the mapping.

Example: updated-team-id-456

Responses

200

Mapping updated successfully.

application/json

idstringOptional

The unique identifier of the updated mapping.

Example: <mapping-id>

parentstringOptional

The parent entity in the mapping.

Example: updated-department-id-123

childstringOptional

The child entity in the mapping.

Example: updated-team-id-456

attributesobjectOptional

Additional attributes for the mapping.

Example: {"parentType":"department","childType":"team","relationship":"parent-child","mappingType":"org-hierarchy"}

updatedAtstring · date-timeOptional

Timestamp when the mapping was last updated.

Example: 2023-11-05T12:00:00.000Z

400

Bad request - Invalid or missing input data.

application/json

401

Unauthorized - Authentication failed or insufficient permissions.

application/json

404

Mapping not found.

application/json

500

Internal server error.

application/json

put

/api/v2/data/mapping/{id}

PUT /api/v2/data/mapping/{id} HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 188

{
  "parent": "updated-department-id-123",
  "child": "updated-team-id-456",
  "attributes": {
    "parentType": "department",
    "childType": "team",
    "relationship": "parent-child",
    "mappingType": "org-hierarchy"
  }
}

{
  "id": "<mapping-id>",
  "parent": "updated-department-id-123",
  "child": "updated-team-id-456",
  "attributes": {
    "parentType": "department",
    "childType": "team",
    "relationship": "parent-child",
    "mappingType": "org-hierarchy"
  },
  "updatedAt": "2023-11-05T12:00:00.000Z"
}

PreviousLogs NextOrganizational Hierarchies

Last updated 3 days ago

Good afternoon

hashtagList All Mappings

hashtagUse Cases

hashtagRequired Access

hashtagCreate a New Mapping

hashtagUse Cases

hashtagRequired Access

hashtagImportant Notes!

hashtagGet a Mapping

hashtagUse Cases

hashtagRequired Access

hashtagImportant Notes!

hashtagUpdate a Mapping

hashtagUse Cases

hashtagRequired Access

hashtagImportant Notes!

List All Mappings

Use Cases

Required Access

Create a New Mapping

Use Cases

Required Access

Important Notes!

Get a Mapping

Use Cases

Required Access

Important Notes!

Update a Mapping

Use Cases

Required Access

Important Notes!