Update database

Update a database tree

Add, update or delete a resource, lock, or role in the database tree.

Request

POST https://www.activityinfo.org/resources/databases/{databaseId}

Request body

application/json

object
resourceUpdates	array[object]	List of resources to add or update.	required
id	string	The id of the resource to update.	required
parentId	string	The id of this resource's new 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.	optional
label	string	The resource's updated human-readable label.	optional
type	string	The resource's type, for new resources.Values: DATABASE FOLDER REPORT FORM SUB_FORM	optional
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.	optional
icon	string	Icon for the resource.	optional
resourceDeletions	array[string]	List of resource ids to delete from the database.	required
lockUpdates	array[object]	List of locks to add or update	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 descroption pf the rule based lock.	optional
deactivated	boolean		required
lockDeletions	array[string]	List of lock ids to delete	required
roleUpdates	array[object]	List of roles to add or update.	required
id	string	This role's id	required
label	string	This role's human-readable label	required
permissions	array[object]	Permissions granted this role.	required
operation	string	Values: VIEW View the resource, whether a form, folder, or database. 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_TRANSLATIONS Allows the user to manage the translations.	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.	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
roleDeletions	array[string]	List of role ids to delete.	required
languageUpdates	array[string]	List of languages to add or update	required
languageDeletions	array[string]	List of languages to delete	required
originalLanguage	string	Original language update	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		required
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
continuousTranslation	boolean	True if the database continuous automatic translation is enabled	required
translationFromDbMemory	boolean	True if automatic translation from database memory is allowed for the database	required
thirdPartyTranslation	boolean	True if third-party translation is allowed for the database	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.	required
operation	string	Values: VIEW View the resource, whether a form, folder, or database. 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_TRANSLATIONS Allows the user to manage the translations.	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.	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
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 descroption pf 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

Error responses

Status Code	Error Code	Description
401	AUTHENTICATION_REQUIRED	The request must be authenticated

Examples

Add a folder

You can add a folder by including it in the list of resourceUpdates. If a folder with the given id does not exist, it will be added.

curl -X POST https://www.activityinfo.org/resources/databases/ck8oykh8m5 \
  -u anything:APITOKEN \
  -H 'Content-type: application/json' \
  --data-binary @- << EOF
{
  "resourceUpdates": [
    {
      "id": "ceponkikiswy1bt2",
      "parentId": "ck8oykh8m5",
      "label": "My new folder",
      "type": "FOLDER"
    },
    {
      "id": "clfl7zq12ohs",
      "parentId": "ceponkikiswy1bt2",
      "label": "My subfolder",
      "type": "FOLDER"
    }
  ]
}
EOF

Delete a form, folder, or report from the database.

You can delete a resource by including its id in the resourceDeletions list. Note that subforms cannot be deleted through this endpoint, a subform can only be deleted by removing its field from the form schema.

curl -X POST https://www.activityinfo.org/resources/databases/ck8oykh8m5 \
  -u anything:APITOKEN \
  -H 'Content-type: application/json' \
  --data-binary @- << EOF
{
  "resourceDeletions": [
    "ceponkikiswy1bt2"
  ]
}
EOF

Add new role

curl -X POST https://www.activityinfo.org/resources/databases/ck8oykh8m5 \
  -u anything:APITOKEN \
  -H 'Content-type: application/json' \
  --data-binary @- << EOF
{
  "roleUpdates": [
    {
      "id": "cht8p4kdeimokm5",
      "label": "Reporting partner",
      "permissions": [
        {
          "operation": "VIEW",
          "filter": "REPORTING_PARTNER == @user.partner && INCIDENT_TYPE != 'GBV'"
        },
        {
          "operation": "EDIT_RECORD",
          "filter": "REPORTING_PARTNER == @user.partner && INCIDENT_TYPE != 'GBV'"
        },
        {
          "operation": "ADD_RECORD",
          "filter": "REPORTING_PARTNER == @user.partner && INCIDENT_TYPE != 'GBV'"
        },
        {
          "operation": "EXPORT_RECORDS"
        }
      ],
      "parameters": [
        {
          "parameterId": "partner",
          "label": "Partner",
          "range": "ck8oyloog8"
        }
      ],
      "filters": [
        {
          "id": "partner",
          "label": "where record is the user's partner and is not GBV",
          "filter": "REPORTING_PARTNER == @user.partner && INCIDENT_TYPE != 'GBV'"
        }
      ],
      "version": 0,
      "grantBased": false
    }
  ]
}
EOF

Add rule based lock

curl -X POST https://www.activityinfo.org/resources/databases/ck8oykh8m5 \
  -u anything:APITOKEN \
  -H 'Content-type: application/json' \
  --data-binary @- << EOF
{
  "lockUpdates": [
    {
      "id": "clfl85yy0sdi8uc1",
      "label": "February reporting",
      "resourceId": "ck8oykh8m5",
      "dateRange": {
        "start": "2023-01-01",
        "end": "2023-01-31"
      },
      "deactivated": false
    }
  ]
}
EOF

Set original language

curl -X POST https://www.activityinfo.org/resources/databases/ck8oykh8m5 \
  -u anything:APITOKEN \
  -H 'Content-type: application/json' \
  --data-binary @- << EOF
{
  "originalLanguage": "FR"
}
EOF

Add languages for translation

curl -X POST https://www.activityinfo.org/resources/databases/ck8oykh8m5 \
  -u anything:APITOKEN \
  -H 'Content-type: application/json' \
  --data-binary @- << EOF
{
  "languageUpdates": [
    "FA",
    "PS"
  ]
}
EOF

Next item

Update database user grants