Background:

This article provides a comprehensive guide on using API calls to create an organization and roles for the organization, as well as assigning permissions and documents to these roles. Organizations often have complex structures with various roles and permissions assigned to each role. Manually creating these roles and assigning permissions can be a tedious and time-consuming process. However, with the help of APIs, this process can be automated and streamlined, making it much more efficient. In this article, we will explore how to use API calls to create an organization, define roles, and assign permissions and documents to these roles, ultimately saving valuable time and resources. Whether you are a software developer or an IT administrator, this guide will provide you with the knowledge and tools necessary to automate this critical organizational process.

Note: For all APIs that must authenticate the user’s login, you must add a Param as the connect token. This will require “?token={token}“ to be appended to the end of the request URL, where {token} is replaced with the value of your connect token. You can learn how to create a connect token here: How To Use Connect Tokens | Wyn-Enterprise.

Steps to Complete:

1. Get all Orgs

GET {serverURL}/api/v2/identity/organizations

This API call will return a list of the organizations that are already present on the Wyn server. If you have not added an organization yet, then you will only have the Global organization. Please note the id of the organizations, since that is necessary to complete step 2.

Below is a sample output:

[
    {
        "id": "global",
        "name": "Global",
        "description": null,
        "enabled": true,
        "path": "/",
        "parentTenantId": null,
        "order": 0,
        "createTime": "2022-08-15T15:26:47.208169-04:00",
        "props": null
    },
    {
        "id": "d0c69b3d-3fc2-4560-9483-e96b807cbce4",
        "name": "North",
        "description": null,
        "enabled": true,
        "path": "/North",
        "parentTenantId": null,
        "order": 0,
        "createTime": "2022-10-12T15:10:57.169712-04:00",
        "props": null
    }
]

2. Create Org

POST {serverURL}/api/v2/identity/organizations

Body (raw):

{
  "parentTenantId": "d0c69b3d-3fc2-4560-9483-e96b807cbce4",
  "name": "API Generated Organization"
}

This API enables you to create a new organization that will be a child of the parent organization identified by its parentTenantId. To specify the parent organization, you must include its ID in the body, which you retrieved in step 1. Alternatively, you can use the “global” organization ID to create a top-level organization. In this example, we made an organization that is the child of the North organization.

Below is a sample output:

{
    "id": "940a581f-41dd-4982-88b0-4f6ff09df179",
    "name": "API Generated Organization",
    "description": null,
    "enabled": true,
    "path": "/North/API Generated Organization",
    "parentTenantId": "d0c69b3d-3fc2-4560-9483-e96b807cbce4",
    "order": 1,
    "createTime": "2023-04-21T16:04:04.0899211Z",
    "props": [
        {
            "id": "050b1980-8192-43f1-ad89-ee71db8b3727",
            "allowSubTenantEditing": true,
            "editable": true,
            "allowSubTenantViewing": true,
            "viewable": true,
            "values": [
                "XYZ"
            ],
            "name": "Department",
            "description": null,
            "required": true,
            "valueType": 0,
            "multivalued": true
        }
    ]
}

3. Create Role in Org

POST {serverURL}/api/v2/identity/organizations/940a581f-41dd-4982-88b0-4f6ff09df179/roles

Body (raw):

"API Generated Role"

This API will create a role in the organization that you designate in the request URL. Replace {organizationID} with the organization you wish to add the role to, such as the one you created in step 2, and in the body, enter the name of the role in quotation marks.

Below is a sample output:

{
    "id": "a95806bd-5fbc-4adf-878c-6225a680ceb2",
    "name": "API Generated Role",
    "creatorId": null,
    "createTime": "2023-04-21T16:17:04.0540362Z",
    "isBuiltin": false,
    "allowEditPermissions": true,
    "permissions": null,
    "members": null,
    "tenantId": "940a581f-41dd-4982-88b0-4f6ff09df179"
}

4. Set Functionality Permissions for Role

POST {serverURL}/api/v2/identity/roles/a95806bd-5fbc-4adf-878c-6225a680ceb2/permissions

Body (raw):

{
  "permissions": [
    "create-dataset",
      "allow-translate-document-title",
      "create-semantic-model",
      "create-web-page",
      "schedule-reports",
      "view-dashboard",
      "view-data-monitoring",
      "allow-sharing",
      "view-report",
      "view-resource-portal",
      "view-revision",
      "report-export",
      "view-document-information",
      "create-report",
      "create-data-source",
      "create-dashboard",
      "create-data-monitoring",
      "report-printing",
      "allow-downloading"
  ]
}

This API allows for a user to update or set the permissions of a specified role. Notice that by setting the role ID into the request URL, the user can specify the role they wish to modify. The example above shows all of the available permissions to set, except for "assign-manage-user" and "manage-user"

Below is a sample output, shortened from the above example:

[
    {
        "name": "allow-sharing",
        "description": "Allow sharing documents to others.",
        "enabled": true,
        "order": 4000,
        "module": null,
        "category": "management",
        "isCustomPermission": false
    },
    {
        "name": "create-dashboard",
        "description": "Create, view, edit and delete dashboards.",
        "enabled": true,
        "order": 400,
        "module": null,
        "category": "dashboards",
        "isCustomPermission": false
    }
]

5. Add Document Permissions to Role

POST /api/v2/documents/permission/batch-update

Body (raw):

{
 "documentIds": [
    "{documentID1}",
    "{documentID2}"
  ],
  "operationType": "AddNew",
  "grantCollection": [
    {
      "role": "{roleName}",
      "ops": [
        "Execute",
        "Read",
        "Update"
      ]
    }
  ]
}

This API will allow you to batch add documents into the role with the exact permission you allow. Adjust the {documentID} to the ID of the document you wish to add, and replace {roleName} with the name of the role you wish to add the documents to.

Below is a sample output:

[
  {
    "documentId": "b0e43c5c-3390-4570-94b8-9b655348f26a",
    "title": "Income Statement Dashboard",
    "fileExt": ".dbd",
    "contentType": "application/json",
    "creatorName": "admin",
    "modifierName": "admin",
    "deleterName": null,
    "description": null,
    "isSystemReserved": null,
    "isResource": false,
    "hideOnMobile": null,
    "meta": "{\"version\":\"6.1.1\"}",
    "hideInDocumentPortal": null,
    "organizationId": null,
    "organizationIdPath": "",
    "thumbnail": null,
    "schemaVersion": null
  },
  {
    "documentId": "420cb224-8151-4fe6-a28e-b2b1d8fb93c5",
    "title": "Employability Report",
    "fileExt": ".rdlx",
    "contentType": "application/xml",
    "creatorName": "admin",
    "modifierName": "admin",
    "deleterName": null,
    "description": null,
    "isSystemReserved": null,
    "isResource": false,
    "hideOnMobile": null,
    "meta": null,
    "hideInDocumentPortal": null,
    "organizationId": null,
    "organizationIdPath": "",
    "thumbnail": null,
    "schemaVersion": null
  }
]

Conclusion:

In conclusion, with the information provided, users should be equipped with the necessary knowledge to automate the process of creating an organization, defining a role, and assigning appropriate permissions and documents to that role. By scripting this process, users can streamline their workflow and save valuable time and resources. This approach can also help ensure consistency and accuracy across multiple instances of the process.