Add database

Adds a new database. The authenticated user becomes its first user, and the database belongs to the requested billing account, or to the user's own billing account when none is requested.

Only users who hold a billing role in the target billing account, or in one of its parent accounts, are permitted to add databases to it.

Request

POST https://www.activityinfo.org/resources/databases

Request body

application/json

object
id	string	The id of the new database.	required
label	string	Human readable name of the database.	required
templateId	string	The id of the template to use in creating the new database. The the two templates currently supported are "reporting" (Multi-partner reporting) and "casemanagement." If ommitted, a blank database with three simple roles will be added.	required
description	string	An optional, longer description for the database.	optional
billingAccountId	integer	The id of the billing account that the new database will belong to. The requesting user must hold a billing role in this account or in one of its parent accounts. If omitted, the requesting user's own billing account is used.	optional

Successful response

application/json

object
databaseId	string	This database's id	required
userId	string	The id of the requesting user. The contents of the tree depends on the permissions of the requesting user.	optional
version	string	The monotonically-increasing version of the database tree. The version number is incremented whenever a change is made that affects the database tree.	required
label	string	This database's human-readable label.	required
description	string		required
ownerRef	object	The database's individual owner, if it still has one. Absent for databases that are administered through roles alone.	optional
id	string		required
name	string		required
email	string		required
language	string	Current database language	required
originalLanguage	string	Original database language	optional
languages	array[string]	The languages that have been defined for this database translation.	required
suspended	boolean	True if this database is suspended for billing reasons	required
role	object	The requesting user's assigned role in this database.	required
roleId	string	The id of the role assigned to this user.	required
roleParameters	object	The values of the parameters defined for this role.	required
roleResources	array[string]	The resources (database, folder, forms, or subforms) to which the role's permissions are to apply.	required
roles	array[object]	The roles that have been defined for this database.	required
id	string	This role's id	required
label	string	This role's human-readable label	required
permissions	array[object]	Permissions granted this role. Applicable for legacy roles, for grant based roles it will be limited to permissions that are NOT related to resources, like MANAGE_USERS, MANAGE_ROLES	required
operation	string	Values: VIEW View the resource, whether a form, folder, or database. DISCOVER Find the resource in the list of forms in the user interface ADD_RECORD Add a record within a form contained by this folder or form. EDIT_RECORD Edit a record's values within a form contained by this folder or form. MANAGE_REFERENCE_DATA Add, edit, and delete records within reference forms DELETE_RECORD Delete a record within this form. BULK_DELETE Bulk record delete within this form EXPORT_RECORDS Export Records from a form, folder or database. MANAGE_USERS Grant permissions to a user to this database, folder, or form. LOCK_RECORDS Add, modify, or remove locks on records. ADD_RESOURCE Create a new Resource (Form or Folder) EDIT_RESOURCE Edit a Resource's schema, structure, attributes or data. DELETE_RESOURCE Delete a Resource (Form or Folder) MANAGE_COLLECTION_LINKS Manage (open/close) collection links for the given form AUDIT Access the Audit logs for a database (or a subset) SHARE_REPORTS Allow the user to share reports with other roles in the database. PUBLISH_REPORTS Allows the user to publish reports. MANAGE_ROLES Add, modify and delete roles MANAGE_AUTOMATIONS View, add, modify and delete automations MANAGE_TRANSLATIONS Allows the user to manage the translations. RESOLVE_DUPLICATES View and merge duplicate records SHARE_VIEWS Allow the user to share views with other users in the database. MANAGE_IMPORT_CONFIGS Allow the user to view and manage saved import configurations on the resource. SECURITY_CONTACT Receive the security notifications for this database: support-access claims, compromised-user alerts and the periodic risk report. A database-level permission carried by a role; it grants no access to data on its own. VIEW_FIELD Allow the user to view a field's data. EDIT_FIELD Allow the user to modify a field's data.	required
filter	string	A formula which restricts a permission to specific records. Only record-level permissions can be filtered.	optional
securityCategories	array[string]		required
parameters	array[object]	Parameters defined for this role. Parameters can be referenced in filtering formulas.	required
parameterId	string		required
label	string		required
range	string		required
filters	array[object]	Pre-defined filters. Role filters allow other users to choose filters for permissions without having to write formulas themselves. -- NOTEWORTHY - only used by legacy roles	required
id	string	This filter's id.	required
label	string	This filter's human-readable label	required
filter	string	A formula that can be used to filter a record-level permission.	required
grants	array[object]		required
resourceId	string		required
operations	array[string]		required
assignableRoles	array[string]	Ids of the roles that holders of this role may assign to, or remove from, other users. Holders must also hold the MANAGE_USERS permission. This explicit list is ignored when assignAnyRole is true, and for legacy roles. Ids of roles that no longer exist are ignored.	required
assignAnyRole	boolean	When true, holders of this role may assign any role in the database, including roles created later. When false, only the roles listed in assignableRoles may be assigned.	required
securityCategories	array[object]	The security categories that have been defined for this database.	required
id	string	This security category's id	required
label	string	This security category's human-readable label	required
resources	array[object]	The set of resources (folders, forms, and subforms) that belong to this database.	required
id	string	The resource's id. Form and subform resources must have globally-unique ids (across all of ActivityInfo) but folder ids are only guaranteed to be unique within a single database.	required
type	string	The resource type. Values: DATABASE FOLDER REPORT FORM SUB_FORM	required
parentId	string	The id of this resource's parent, for example, a folder id. If this is a top-level folder or form, the the parentId will be the id of the database itself.	required
label	string	The resource's human-readable label.	required
visibility	string	The resource's visibility. Values: PUBLIC Public. Visible to all Users on system, regardless of assigned permissions. PRIVATE Visible only to users given explicit permissions. REFERENCE Visible only if another Resource on the Database is visible to the current User. Used to provide Forms with data to be referenced, but not requiring an explicit grant to be generated for the User.	required
locks	array[object]	The record locks that have been defined on this database.	required
id	string	This lock's id.	required
label	string	A human-readable label for this lock	required
resourceId	string	The resource (database, folder, form, or subform) to which this lock applies.	required
dateRange	object	The date range to which this lock applies.	optional
startDate	local_date		required
endDate	local_date		required
formula	string	The formula to which this rule based lock applies.	optional
message	string	user description of the rule based lock.	optional
deactivated	boolean		required
grants	array[object]	The permission grants that have been made to the requesting user for this database.	required
resourceId	string		required
operations	array[string]		required
billingAccountId	integer		required
billingPlan	string	The billing plan name under which this database falls. The billing plan can have an affect on which features are avialable within this database.	required

Error responses

Status Code	Error Code	Description
400	BILLING_ACCOUNT_NOT_ACTIVE	The authenticated user's billing account is not active.
400	INVALID_DATABASE_ID	The user has provided an invalid database id.
400	NO_BILLING_ACCOUNT	The authenticated user has no billing account, and so cannot add a database.
401	AUTHENTICATION_REQUIRED	The request must be authenticated
403	BILLING_ACCOUNT_FORBIDDEN	The authenticated user may not add databases to the requested billing account.
409	DATABASE_EXISTS	A database with this id already exists.

Example

curl -X POST https://www.activityinfo.org/resources/databases \
  -u anything:APITOKEN \
  -H 'Content-type: application/json' \
  --data-binary @- << EOF
{
  "id": "ck8oykh8m5",
  "label": "My new database",
  "templateId": "",
  "description": null,
  "billingAccountId": null
}
EOF

The above command returns JSON structured like this:

{
  "databaseId": "ck8oykh8m5",
  "userId": "432201",
  "version": "0#0",
  "label": "",
  "description": "",
  "billingAccountId": 0,
  "language": "",
  "role": {
    "id": "admin",
    "parameters": {
      
    },
    "resources": [
      "ck8oykh8m5"
    ]
  },
  "suspended": false,
  "billingPlan": "",
  "storage": "",
  "publishedTemplate": false,
  "grants": [
    {
      "resourceId": "ck8oykh8m5",
      "optional": false,
      "operations": [
        {
          "operation": "VIEW"
        },
        {
          "operation": "DISCOVER"
        },
        {
          "operation": "ADD_RECORD"
        },
        {
          "operation": "EDIT_RECORD",
          "securityCategories": [
            "reviewer"
          ]
        },
        {
          "operation": "DELETE_RECORD"
        },
        {
          "operation": "BULK_DELETE"
        },
        {
          "operation": "EXPORT_RECORDS"
        },
        {
          "operation": "LOCK_RECORDS"
        },
        {
          "operation": "ADD_RESOURCE"
        },
        {
          "operation": "EDIT_RESOURCE"
        },
        {
          "operation": "DELETE_RESOURCE"
        },
        {
          "operation": "MANAGE_COLLECTION_LINKS"
        },
        {
          "operation": "AUDIT"
        },
        {
          "operation": "SHARE_REPORTS"
        },
        {
          "operation": "PUBLISH_REPORTS"
        },
        {
          "operation": "MANAGE_TRANSLATIONS"
        },
        {
          "operation": "RESOLVE_DUPLICATES"
        },
        {
          "operation": "SHARE_VIEWS"
        },
        {
          "operation": "MANAGE_IMPORT_CONFIGS"
        },
        {
          "operation": "VIEW_FIELD"
        },
        {
          "operation": "EDIT_FIELD"
        },
        {
          "operation": "MANAGE_USERS"
        },
        {
          "operation": "MANAGE_ROLES"
        },
        {
          "operation": "MANAGE_AUTOMATIONS"
        },
        {
          "operation": "SECURITY_CONTACT"
        }
      ]
    }
  ],
  "roles": [
    {
      "id": "admin",
      "label": "Administrator",
      "permissions": [
        {
          "operation": "MANAGE_USERS"
        },
        {
          "operation": "MANAGE_ROLES"
        },
        {
          "operation": "MANAGE_AUTOMATIONS"
        },
        {
          "operation": "SECURITY_CONTACT"
        }
      ],
      "grants": [
        {
          "resourceId": "ck8oykh8m5",
          "optional": false,
          "operations": [
            {
              "operation": "VIEW"
            },
            {
              "operation": "DISCOVER"
            },
            {
              "operation": "ADD_RECORD"
            },
            {
              "operation": "EDIT_RECORD",
              "securityCategories": [
                "reviewer"
              ]
            },
            {
              "operation": "DELETE_RECORD"
            },
            {
              "operation": "BULK_DELETE"
            },
            {
              "operation": "EXPORT_RECORDS"
            },
            {
              "operation": "LOCK_RECORDS"
            },
            {
              "operation": "ADD_RESOURCE"
            },
            {
              "operation": "EDIT_RESOURCE"
            },
            {
              "operation": "DELETE_RESOURCE"
            },
            {
              "operation": "MANAGE_COLLECTION_LINKS"
            },
            {
              "operation": "AUDIT"
            },
            {
              "operation": "SHARE_REPORTS"
            },
            {
              "operation": "PUBLISH_REPORTS"
            },
            {
              "operation": "MANAGE_TRANSLATIONS"
            },
            {
              "operation": "RESOLVE_DUPLICATES"
            },
            {
              "operation": "SHARE_VIEWS"
            },
            {
              "operation": "MANAGE_IMPORT_CONFIGS"
            },
            {
              "operation": "VIEW_FIELD"
            },
            {
              "operation": "EDIT_FIELD"
            }
          ]
        }
      ],
      "version": 0,
      "grantBased": true,
      "assignAnyRole": true
    },
    {
      "id": "readonly",
      "label": "Read only",
      "grants": [
        {
          "resourceId": "ck8oykh8m5",
          "optional": false,
          "operations": [
            {
              "operation": "VIEW"
            },
            {
              "operation": "DISCOVER"
            }
          ]
        }
      ],
      "version": 0,
      "grantBased": true,
      "assignAnyRole": false
    },
    {
      "id": "dataentry",
      "label": "Data Entry",
      "grants": [
        {
          "resourceId": "ck8oykh8m5",
          "optional": false,
          "operations": [
            {
              "operation": "VIEW"
            },
            {
              "operation": "DISCOVER"
            },
            {
              "operation": "EDIT_RECORD"
            },
            {
              "operation": "ADD_RECORD"
            },
            {
              "operation": "DELETE_RECORD"
            },
            {
              "operation": "EXPORT_RECORDS"
            }
          ]
        }
      ],
      "version": 0,
      "grantBased": true,
      "assignAnyRole": false
    }
  ]
}

Next item

Add database user