Orgs, Sharing, & Subscriptions

What's an Organization?

Organizations in Qrvey are a tagging system that enables you to group assets (such as Dashboards) with users (as defined by clientId). This powers Ownership & Sharing of Dashboards, as well as Subscriptions within the Download Manager.

When to use Org:0

• If you want content shared by users in embedded mode to be visible to users in Composer mode (and vice versa).
• If you want content pushed in by CD to be visible to users in embedded mode.

Ownership & Sharing

Dashboards (excluding Legacy Dashboards) have the concept of Ownership. When a user creates a dashboard, you must pass a clientId to identify the user and an orgId to identify the organization the user belongs to. If this user wants to share the dashboard, they can share it with their organization (defined by the user's orgId) or pass the orgs object to share it with specific users or roles within the same organization.

Users with an Administrator role can view all dashboards:

• Users with the default Administrators role in Composer are able to view, edit, and delete all dashboards associated with applications they have access to. This applies even if they are not the owner or the dashboards have not been explicitly shared with them. Dashboards should be visible regardless of the orgId in which they were created. This elevated access cannot be restricted through Sharing settings or any dashboard-level configuration.
• In embedded scenarios, if orgId: "org:0", any user with the Administrators role and whose clientId matches their userId, or the clientId matches a userId with the Administrators role, should also have access to all dashboards. This rule is ignored if the embedded request passes an orgId other than "org:0".
• The same behavior applies to API calls where a userId under the Administrators role is provided, and the clientId equals that userId.
• If a user does not have access to a given application, they will not gain access to that application or its dashboards, regardless of their role or orgId.
• Composer or org:0 users can view dashboards created in other orgIds, but they are not allowed to modify the Sharing configuration of those dashboards.

Sharing must occur within the same organization. The user who wants to share the dashboard must have a valid clientId and orgId.

To share a Dashboard with another user, they must must have:

• orgId
• orgs.users[] with the user's clientId and valid email.

Note: The string org:0 is internally reserved for the "Qrvey Composer Org". In other words, assets made within Qrvey Composer are associated with "org:0", so use that string to display them in an embedded scenario.

Any widgets that need to access dashboard information, such as Automation (Flows), must also pass the clientId and orgId. This ensures that only dashboards the clientId has access to are listed, as well as charts inside them when attached to Send Email actions.

When embedding Dashboards created within Composer:

• Set orgId: "org:0", to associate it with the "Qrvey Composer" Organization.
  Note: If you pass "org:0" into a widget, it will behave as if it is in Composer.
• Then pass the desired clientId to enable Dashboard personalization.
• These options will function just like in Composer, even displaying the Composer users for sharing.

Example:

"orgs": [
  {
    "orgId": "org:0",
    "users": [
      {
        "clientId": "john_smith",
        "email": "john_smith@qrvey.com"
      }
    ]
  }
]

When accessing a dashboard that has been shared with a role, assign the role to the user so they can access the dashboard.

{ // the dashboard config object
  "appId": "XVDq3Xr",
  "userId": "Sk7HuNH",
  "clientId": "jane_doe",
  "expiresIn": "1y",
  "orgId": "org:0",
  "roles": ["QA"]
}

Include roles in orgs.orgRoles[] to share the dashboard with specific roles:

"orgs": [
  {
    "orgId": "org:0",
    "orgRoles": ["QA"]
  }
]

For JWT/Config-Based Sharing in Embedded Dashboards, embed the dashboard with the orgs[] object in the QV Token or config object. This enables the UI to display the list of users and roles for sharing.

{
  "appId": "XVDq3Xr",
  "userId": "Sk7HuNH",
  "clientId": "jane_doe",
  "expiresIn": "1y",
  "orgId": "org:0",
  "roles": ["QA"],
  "orgs": [
    {
      "orgId": "1",
      "orgRoles": [
        "QA"
      ],
      "users": [
        {
          "clientId": "john_smith",
          "email": "john_smith@qrvey.com"
        }
      ]
    }
  ]
}

Subscriptions