This is the documentation for ConfiForms CLOUD app
ConfiForms app on Atlassian marketplace
This is a documentation for ConfiForms CLOUD REST API v1
To start with API you will need to generate an access token.
This is done in ConfiForms settings. Go to your Confluence settings and browse to "Atlassian Marketplace" section
Click on "ConfiForms configuration"
Select "API tokens" tab and click on "Generate token" button to generate an access token for ConfiForms REST API
Generated token is valid for 1 year and shall be used to access APIs
ConfiForms REST APIs
Server URL is https://app.confiforms.net
API prefix /rest/api/v1/
Please note that {token} can be omitted in the URLs if it is given via HTTP request header called "Auth-Token"
Search | Searches and filters ConfiForms entries based on a QUERY (ConfiForms Filters) given |
| /search/{token}/{pageId}/{formName}?q=<QUERY> Supports optional parameters:
| Where QUERY is an expression in ConfiForms Filters format Not providing a "QUERY" ("q" parameter) will match all records |
|---|---|---|---|---|
Delete | Deletes ConfiForms record from the form by id (UUID) |
| /delete/{token}/{pageId}/{formName}/{entryId} | User must have permissions to edit/delete the record. This means ConfiForms cloud system user (com.vertuna.confluence.plugins.confiforms) must have enough permissions to do that. |
DeleteBy | Deletes ConfiForms records from the form by given QUERY (ConfiForms Filters) |
| /deleteBy/{token}/{pageId}/{formName}?q=<QUERY> | Where QUERY is an expression in ConfiForms Filters format Not providing a "QUERY" ("q" parameter) will match all records. Use Search to see matching records to see what records will be affected by delete to test your "query" (filtering expression) |
Validate | Validates parameters against the rules and field types configured by the form |
| /validate/{token}/{pageId}/{formName}?<FIELDS> | fields are given in a key=value format as any HTTP request parameters |
Save / Update | Saves the parameters given as new record in ConfiForms form. Alls the rules are applied before saving according to form configuration. If an ID is provided in the fields set then ConfiForms attempts to update the record by given id with given data |
| /save/{token}/{pageId}/{formName}?<FIELDS> Instead of <FIELDS> parameters added to the request url query string you can use POST method and send over the JSON payload with the structure as follows: {
"fields": {
"field1":"field value",
"field2": "2020-04-25"
}
}
Multi-value fields you can give as JSON arrays "myfield": ["value1", "value2"] You can also POST a request with multipart/form-data. This comes handy when you want to upload attachments together with record creation. Alternatively you can have a file encoded as base64 {
"fields": {
...
"myfile": [
{
"fileName": "",
"fileContentType" : "see https://developer.mozilla.org/en-US/docs/Web/HTTP/MIME_types/Common_types",
"fileContent" : "BASE64 encoded content here"
},
{
"fileName": "",
"fileContentType" : "see https://developer.mozilla.org/en-US/docs/Web/HTTP/MIME_types/Common_types",
"fileContent" : "BASE64 encoded content here"
}
]
}
}
Please note that the parameter names must match the field names you have defined in your ConfiForms form | fields are given in a key=value format as any HTTP request parameters When you need to update the record the ID shall be given as "entryId" parameter When no entryId parameter found or the record by given entryId could not be found then a new record will be created Partial updates are supported. Meaning that you can supply less parameters than the record has (missing fields will not be updated). To set the field value to empty, do supply it as a parameter myfield= (where "myfield" is the name of the field you want to set the empty value for) |
Get | Loads ConfiForms record by id (UUID) |
| /get/{token}/{pageId}/{formName}/{entryId} Supports optional parameters:
| 404 if not found |
Update specific field by filter | Updates ConfiForms field by query (for each record matching the query) |
| /update/{token}/{pageId}/{formName}?q=<QUERY>&fv=field:value | Where QUERY is an expression in ConfiForms Filters format and "fv" is given in a field:value format, where "field" is the name of the field in ConfiForms record you want to update with "value" |
Definition | Returns form configuration |
| /definition/{token}/{pageId}/{formName} | Returns form definition (configuration) 404 if not found |
Examples
Example result returned by "Search"
/rest/api/v1/search/<TOKEN>/553943100/f?q=ve*
Complete URL
https://app.confiforms.net/rest/api/v1/search/<TOKEN>/553943100/f?q=ve*
{
"entries": [
{
"recordId": 0,
"createdBy": "<account_id>",
"created": 1541783367283,
"id": "5643297d-8bfd-4bf5-b8b6-ef102efe737a",
"fields": {
"t": "ve",
"h": "1541783367347"
},
"ownedBy": "<account_id>"
},
{
"recordId": 1,
"createdBy": "<account_id>",
"created": 1541783823254,
"id": "b2175873-b0f0-47b5-898d-630928ddeb68",
"fields": {
"t": "vew",
"h": "1541783823321"
},
"ownedBy": "<account_id>"
},
{
"recordId": 2,
"createdBy": "<account_id>",
"created": 1541783834097,
"id": "a53198b0-32ed-48a3-b821-ffaafa1d0438",
"fields": {
"t": "vew2",
"h": "1541783834159"
},
"ownedBy": "<account_id>"
}
],
"limit": 100,
"startAt": 1,
"total": 3
}
Example result returned by "Get"
/rest/api/v1/get/<TOKEN>/553943100/f/b2175873-b0f0-47b5-898d-630928ddeb68
Complete URL
https://app.confiforms.net/rest/api/v1/get/<TOKEN>/553943100/f/b2175873-b0f0-47b5-898d-630928ddeb68
{
"recordId": 1,
"createdBy": "<account_id>",
"created": 1541783823254,
"id": "b2175873-b0f0-47b5-898d-630928ddeb68",
"fields": {
"t": "vew",
"h": "1541783823321"
},
"ownedBy": "<account_id>"
}