Communities

Save PDF

Last UpdatedJan 20, 2023
6 minute read

A community is an organizational entity that facilitates data sharing across multiple tenants.

`List Communities a Tenant is Joined to`

Gets all communities a tenant is joined to.

Request

GET /api/v1-preview/Communities
?query={query}&skip={skip}&count={count}

Parameters

[optional] string query
(not supported) Search string identifier.

[optional] integer skip
Parameter representing the zero-based offset of the first object to retrieve. If unspecified, a default value of 0 is used.

[optional] integer count
Parameter representing the maximum number of objects to retrieve. If unspecified, a default value of 100 is used.

Response

Status Code	Body Type	Description
200	Community[]	Returns the current communities for the tenant. This is a set of objects of type `Community`.
400	ErrorResponse	Bad Request. The server could not understand the request.
401	None	Unauthorized. The client has not been authenticated.
403	ErrorResponse	Forbidden. The client does not have the required permissions to make the request.
408	ErrorResponse	Request Timeout. The request has timed out.
500	ErrorResponse	Internal Server Error. The server has encountered a situation it doesn't know how to handle.

Example response body

200 Response (Community[])

[
  {
    "Id": "string",
    "MemberRoleId": "string",
    "Name": "string",
    "DisplayName": "string",
    "Description": "string",
    "Tenants": [
      {
        "Id": "string",
        "Name": "string",
        "Status": "None",
        "IsOwner": true,
        "UserCount": 0,
        "ClientCount": 0,
        "PreferredRegionId": "string",
        "ContactEmail": "string",
        "CommunityAlias": "string"
      }
    ],
    "DateCreated": "2019-08-24T14:15:22Z",
    "PreferredRegionId": "string",
    "CommunityRoles": [
      {
        "Id": "string",
        "Name": "string",
        "Description": "string",
        "RoleScope": 0,
        "TenantId": "string",
        "CommunityId": "string",
        "RoleTypeId": "string"
      }
    ]
  }
]

`Create a New Community`

Creates a new community within a specific tenant. The tenant sending this request will be assigned ownership of the community. The calling user or client will be granted community administrator and member roles for the community.

Request

POST /api/v1-preview/Communities

Parameters

Request Body

Community information to create

{
  "Name": "string",
  "Description": "string",
  "PreferredRegionId": "string",
  "ContactEmail": "user@example.com"
}

Response

Status Code	Body Type	Description
201	Community	Returns the created community of type `Community`.
400	ErrorResponse	Bad Request. The server could not understand the request.
401	ErrorResponse	Unauthorized. The client has not been authenticated.
403	ErrorResponse	Forbidden. The client does not have the required permissions to make the request.
408	ErrorResponse	Request Timeout. The request has timed out.
409	ErrorResponse	None
500	ErrorResponse	Internal Server Error. The server has encountered a situation it doesn't know how to handle.

Example response body

201 Response (Community)

{
  "Id": "string",
  "MemberRoleId": "string",
  "Name": "string",
  "DisplayName": "string",
  "Description": "string",
  "Tenants": [
    {
      "Id": "string",
      "Name": "string",
      "Status": "None",
      "IsOwner": true,
      "UserCount": 0,
      "ClientCount": 0,
      "PreferredRegionId": "string",
      "ContactEmail": "string",
      "CommunityAlias": "string"
    }
  ],
  "DateCreated": "2019-08-24T14:15:22Z",
  "PreferredRegionId": "string",
  "CommunityRoles": [
    {
      "Id": "string",
      "Name": "string",
      "Description": "string",
      "RoleScope": 0,
      "TenantId": "string",
      "CommunityId": "string",
      "RoleTypeId": "string"
    }
  ]
}

`Get a Community by Id`

Gets a community and related information by Id.

Request

GET /api/v1-preview/Communities/{communityId}
?resolveCompanyName={resolveCompanyName}

Parameters

string communityId
Community unique identifier.

[optional] boolean resolveCompanyName
Parameter to resolve company name for community tenants. Default is to include.

Response

Status Code	Body Type	Description
200	Community	Returns a specified community for the tenant. This is an object of type `Community`.
400	ErrorResponse	Bad Request. The server could not understand the request.
401	None	Unauthorized. The client has not been authenticated.
403	ErrorResponse	Forbidden. The client does not have the required permissions to make the request.
408	ErrorResponse	Request Timeout. The request has timed out.
500	ErrorResponse	Internal Server Error. The server has encountered a situation it doesn't know how to handle.

Example response body

200 Response (Community)

{
  "Id": "string",
  "MemberRoleId": "string",
  "Name": "string",
  "DisplayName": "string",
  "Description": "string",
  "Tenants": [
    {
      "Id": "string",
      "Name": "string",
      "Status": "None",
      "IsOwner": true,
      "UserCount": 0,
      "ClientCount": 0,
      "PreferredRegionId": "string",
      "ContactEmail": "string",
      "CommunityAlias": "string"
    }
  ],
  "DateCreated": "2019-08-24T14:15:22Z",
  "PreferredRegionId": "string",
  "CommunityRoles": [
    {
      "Id": "string",
      "Name": "string",
      "Description": "string",
      "RoleScope": 0,
      "TenantId": "string",
      "CommunityId": "string",
      "RoleTypeId": "string"
    }
  ]
}

`Update Community Info`

Updates attributes of a community such as name and description.

Request

PUT /api/v1-preview/Communities/{communityId}

Parameters

string communityId
Community identifier

Request Body

The community object that contains the attributes to use for the update.

{
  "Name": "string",
  "Description": "string",
  "PreferredRegionId": "string"
}

Response

Status Code	Body Type	Description
200	None	Success. The community tenant was updated.
400	ErrorResponse	Bad Request. The server could not understand the request.
401	ErrorResponse	Unauthorized. The client has not been authenticated.
404	ErrorResponse	Not Found. The requested community tenant was not found.
500	ErrorResponse	Internal Server Error. The server has encountered a situation it doesn't know how to handle.

`Delete a Community`

Deletes a community by Id.

Request

DELETE /api/v1-preview/Communities/{communityId}

Parameters

string communityId
The id of the community to delete.

Response

Status Code	Body Type	Description
204	None	No Content. The community was successfully deleted.
400	ErrorResponse	Bad Request. The server could not understand the request.
401	ErrorResponse	Unauthorized. The client has not been authenticated.
403	ErrorResponse	Forbidden. The client does not have the required permissions to make the request.
404	ErrorResponse	Not Found. The community was not found.
408	ErrorResponse	Request Timeout. The request has timed out.
500	ErrorResponse	Internal Server Error. The server has encountered a situation it does not know how to handle.

Definitions

Community

The Community object

Properties

Property Name	Data Type	Required	Nullable	Description
Id	guid	false	false	Community identifier.
MemberRoleId	guid	false	false	Community member role identifier.
Name	string	false	true	Community name.
DisplayName	string	false	true	Requesting tenant's display name for the community. Either community alias for requesting tenant or community name if community alias is null.
Description	string	false	true	Community description.
Tenants	[CommunityTenant]	false	true	List of CommunityTenant that are in the community
DateCreated	date-time	false	true	Date community was created.
PreferredRegionId	string	false	true	Preferred Region Id. This is community wide default if not specified in the similar community tenant field. Community search returns cross region info, so the preferred region stores what region end point to start search.
CommunityRoles	[Role]	false	true	The list of community roles for this community.

{
  "Id": "string",
  "MemberRoleId": "string",
  "Name": "string",
  "DisplayName": "string",
  "Description": "string",
  "Tenants": [
    {
      "Id": "string",
      "Name": "string",
      "Status": "None",
      "IsOwner": true,
      "UserCount": 0,
      "ClientCount": 0,
      "PreferredRegionId": "string",
      "ContactEmail": "string",
      "CommunityAlias": "string"
    }
  ],
  "DateCreated": "2019-08-24T14:15:22Z",
  "PreferredRegionId": "string",
  "CommunityRoles": [
    {
      "Id": "string",
      "Name": "string",
      "Description": "string",
      "RoleScope": 0,
      "TenantId": "string",
      "CommunityId": "string",
      "RoleTypeId": "string"
    }
  ]
}

CommunityTenant

The CommunityTenant object

Properties

Property Name	Data Type	Required	Nullable	Description
Id	guid	false	false	Tenant Id
Name	string	false	true	Tenant name
Status	CommunityTenantStatus	false	false	CommunityTenant status in a community
IsOwner	boolean	false	false	Boolean indicating whether the CommunityTenant is the owner of the community
UserCount	integer	false	false	Summary count of the users authorized to access the community within the tenant
ClientCount	integer	false	false	Summary count of the clients authorized to access the community within the tenant
PreferredRegionId	string	false	true	Preferred Region Id of a community tenant. This overrides the default community region.
ContactEmail	string	false	true	Contact email of a community tenant. It serves as a point of contact for community tenants.
CommunityAlias	string	false	true	Community alias given by tenant for the community.

{
  "Id": "string",
  "Name": "string",
  "Status": "None",
  "IsOwner": true,
  "UserCount": 0,
  "ClientCount": 0,
  "PreferredRegionId": "string",
  "ContactEmail": "string",
  "CommunityAlias": "string"
}

CommunityTenantStatus

Represents a status of a community tenant.

Enumerated Values

Property	Value
None	None
Paused	Paused
Active	Active

Role

Object for retrieving a role

Properties

Property Name	Data Type	Required	Nullable	Description
Id	string	false	true	Role identifier. Generated by the server upon creation.
Name	string	false	true	Role name. This cannot be empty.
Description	string	false	true	Role description
RoleScope	RoleScope	false	true	Role scope
TenantId	string	false	true	Tenant identifier, if this is a Tenant Role. Otherwise, set to null.
CommunityId	string	false	true	Community identifier, if this is a Community Role. Otherwise set to null.
RoleTypeId	string	false	true	Role type identifier for built-in roles

{
  "Id": "string",
  "Name": "string",
  "Description": "string",
  "RoleScope": 0,
  "TenantId": "string",
  "CommunityId": "string",
  "RoleTypeId": "string"
}

RoleScope

The object that represents the scope of a given role

Enumerated Values

Property	Value
None	0
Tenant	1
Community	2
Cluster	3

ErrorResponse

Object returned whenever there is an error

Properties

Property Name	Data Type	Required	Nullable	Description
OperationId	string	true	false	Operation identifier of action that caused the error
Error	string	true	false	Error description
Reason	string	true	false	Reason for the error
Resolution	string	true	false	Resolution to resolve the error
DynamicProperties	object	false	true	Additional properties

{
  "OperationId": "string",
  "Error": "string",
  "Reason": "string",
  "Resolution": "string",
  "DynamicProperties": {
    "property1": null,
    "property2": null
  },
  "property1": null,
  "property2": null
}

CreateCommunityInput

The CreateCommunityInput object. This is the model input for creating a community.

Properties

Property Name	Data Type	Required	Nullable	Description
Name	string	false	true	Name of the community to be created.
Description	string	false	true	Description of the community.
PreferredRegionId	string	false	true	Preferred Region Id.
ContactEmail	email	false	true	Contact email of a community owning tenant. It serves as a point of contact for community tenants.

{
  "Name": "string",
  "Description": "string",
  "PreferredRegionId": "string",
  "ContactEmail": "user@example.com"
}

UpdateCommunityInput

The UpdateCommunityInput object

Properties

Property Name	Data Type	Required	Nullable	Description
Name	string	false	true	Community name.
Description	string	false	true	Community description.
PreferredRegionId	string	false	true	Preferred Region Id.

{
  "Name": "string",
  "Description": "string",
  "PreferredRegionId": "string"
}

CONNECT data services developer documentation

Communities

List Communities a Tenant is Joined to

Request

Parameters

Response

Example response body

Create a New Community

Request

Parameters

Request Body

Response

Example response body

Get a Community by Id

Request

Parameters

Response

Example response body

Update Community Info

Request

Parameters

Request Body

Response

Delete a Community

Request

Parameters

Response

Definitions

Community

Properties

CommunityTenant

Properties

CommunityTenantStatus

Enumerated Values

Role

Properties

RoleScope

Enumerated Values

ErrorResponse

Properties

CreateCommunityInput

Properties

UpdateCommunityInput

Properties

In This Topic

Related Links

`List Communities a Tenant is Joined to`

`Create a New Community`

`Get a Community by Id`

`Update Community Info`

`Delete a Community`