REST API

API reference for Form Portal integration.

Overview

The Form Portal exposes REST endpoints for: - Retrieving form lists - Creating form instances - Getting role and workflow information - Accessing form data

All endpoints require authentication and appropriate privileges.

Authentication

All API requests require: - Valid Ambience session - Session cookie in request - Appropriate privileges

Example:

curl -X GET https://your-server/form-portal/forms/mycurrent \
  -H "Cookie: session=your-session-cookie" \
  -H "Accept: application/json"

View Endpoints

Get Role Information

Retrieve user’s role information.

Endpoint: GET /form-portal/role-info

Privilege Required: mod-form-portal

Response:

{
  "formRoles": [
    {"id": "employee", "name": "Employee"},
    {"id": "manager", "name": "Manager"}
  ],
  "checklistRoles": [
    {"id": "inspector", "name": "Inspector"}
  ]
}

Example:

curl -X GET https://your-server/form-portal/role-info \
  -H "Cookie: session=..." \
  -H "Accept: application/json"

Get Workflows

Retrieve available workflows.

Endpoint: GET /form-portal/workflows

Privilege Required: mod-form-portal

Response:

[
  {
    "id": "workflow-id-1",
    "name": "Leave Approval"
  },
  {
    "id": "workflow-id-2",
    "name": "Purchase Order"
  }
]

Get Current Forms

Retrieve user’s current forms.

Endpoint: GET /form-portal/forms/mycurrent

Privilege Required: mod-form-portal

Response:

[
  {
    "id": "instance-id-1",
    "formType": "WorkflowForm",
    "formId": "form-template-id",
    "submissionId": "submission-id",
    "name": "Leave Request",
    "fullPath": "form-runtime/form-id/workflow-id/instance-id/index.html",
    "by": "user-id",
    "when": 1705315800000,
    "status": "",
    "role": "employee"
  }
]

Example:

curl -X GET https://your-server/form-portal/forms/mycurrent \
  -H "Cookie: session=..." \
  -H "Accept: application/json"

Get Submitted Forms

Retrieve user’s submitted forms.

Endpoint: GET /form-portal/forms/mysubmitted

Privilege Required: mod-form-portal

Response: Same format as current forms

Get Archived Forms

Retrieve user’s archived forms.

Endpoint: GET /form-portal/forms/myarchived

Privilege Required: mod-form-portal

Response: Same format as current forms

Get Current Checklists

Retrieve user’s current checklists.

Endpoint: GET /form-portal/checklists/mycurrent

Privilege Required: mod-form-portal

Response: Same format as forms

Get Submitted Checklists

Retrieve user’s submitted checklists.

Endpoint: GET /form-portal/checklists/mysubmitted

Privilege Required: mod-form-portal

Response: Same format as forms

Get Archived Checklists

Retrieve user’s archived checklists.

Endpoint: GET /form-portal/checklists/myarchived

Privilege Required: mod-form-portal

Response: Same format as forms

Create Endpoints

Get Form Templates for Role

Retrieve form templates available to a role.

Endpoint: GET /form-portal/forms/role/{roleId}

Privilege Required: mod-form

Path Parameters: - roleId - Role identifier

Response:

[
  {
    "formId": "form-template-id",
    "name": "Leave Request",
    "description": "",
    "lastModified": 1705315800000
  }
]

Example:

curl -X GET https://your-server/form-portal/forms/role/employee \
  -H "Cookie: session=..." \
  -H "Accept: application/json"

Create Form Instance

Create a new form instance with workflow.

Endpoint: POST /form-portal/forms/create

Privilege Required: mod-form

Request Body:

{
  "formId": "form-template-id",
  "workflowId": "workflow-definition-id"
}

Response:

instance-id-123

Example:

curl -X POST https://your-server/form-portal/forms/create \
  -H "Cookie: session=..." \
  -H "Content-Type: application/json" \
  -d '{
    "formId": "form-template-id",
    "workflowId": "workflow-definition-id"
  }'

Success: Returns instance ID as plain text

Error: Returns error message

Get Checklist Templates for Role

Retrieve checklist templates available to a role.

Endpoint: GET /form-portal/checklists/role/{roleId}

Privilege Required: mod-checklist

Path Parameters: - roleId - Role identifier

Response: Same format as form templates

Create Checklist Instance

Create a new checklist instance.

Endpoint: POST /form-portal/checklists/create

Privilege Required: mod-checklist

Request Body:

{
  "checklistId": "checklist-template-id"
}

Response:

instance-id-456

Example:

curl -X POST https://your-server/form-portal/checklists/create \
  -H "Cookie: session=..." \
  -H "Content-Type: application/json" \
  -d '{
    "checklistId": "checklist-template-id"
  }'

Data Models

Form Object

interface Form {
  id: string;              // Instance ID
  formType: FormType;      // "Form" | "Checklist" | "WorkflowForm"
  formId: string;          // Template ID
  submissionId: string;    // Submission tracking ID
  name: string;            // Display name
  fullPath: string;        // Path to form runtime
  by: string;              // User ID who created
  when: number;            // Timestamp (milliseconds)
  status: string;          // Status information
  role: string;            // Associated role
}

CreateFormInfo Object

interface CreateFormInfo {
  formId: string;          // Template ID
  name: string;            // Template name
  description: string;     // Template description
  lastModified: number;    // Timestamp (milliseconds)
}

RoleInfo Object

interface RoleInfo {
  formRoles: Role[];       // Roles with form access
  checklistRoles: Role[];  // Roles with checklist access
}

interface Role {
  id: string;              // Role ID
  name: string;            // Role display name
}

WorkflowInfo Object

interface WorkflowInfo {
  id: string;              // Workflow ID
  name: string;            // Workflow name
}

Error Handling

Error Responses

Access Denied (403):

{
  "error": "Access denied",
  "message": "User lacks required privilege"
}

Not Found (404):

{
  "error": "Not found",
  "message": "Resource not found"
}

Bad Request (400):

{
  "error": "Bad request",
  "message": "Invalid request parameters"
}

Server Error (500):

{
  "error": "Server error",
  "message": "Internal server error"
}

Error Handling Example

fetch('https://your-server/form-portal/forms/mycurrent', {
  credentials: 'include',
  headers: {
    'Accept': 'application/json'
  }
})
.then(response => {
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }
  return response.json();
})
.then(forms => {
  console.log('Forms:', forms);
})
.catch(error => {
  console.error('Error:', error);
});

Integration Examples

JavaScript/TypeScript

Get Current Forms:

async function getCurrentForms() {
  const response = await fetch('/form-portal/forms/mycurrent', {
    credentials: 'include',
    headers: {
      'Accept': 'application/json'
    }
  });
  
  if (!response.ok) {
    throw new Error(`Failed to get forms: ${response.status}`);
  }
  
  return await response.json();
}

Create Form Instance:

async function createFormInstance(formId, workflowId) {
  const response = await fetch('/form-portal/forms/create', {
    method: 'POST',
    credentials: 'include',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ formId, workflowId })
  });
  
  if (!response.ok) {
    throw new Error(`Failed to create form: ${response.status}`);
  }
  
  return await response.text(); // Returns instance ID
}

Python

Get Current Forms:

import requests

def get_current_forms(session_cookie):
    response = requests.get(
        'https://your-server/form-portal/forms/mycurrent',
        cookies={'session': session_cookie},
        headers={'Accept': 'application/json'}
    )
    response.raise_for_status()
    return response.json()

Create Form Instance:

def create_form_instance(session_cookie, form_id, workflow_id):
    response = requests.post(
        'https://your-server/form-portal/forms/create',
        cookies={'session': session_cookie},
        headers={'Content-Type': 'application/json'},
        json={'formId': form_id, 'workflowId': workflow_id}
    )
    response.raise_for_status()
    return response.text  # Returns instance ID

cURL Examples

Get Role Info:

curl -X GET https://your-server/form-portal/role-info \
  -H "Cookie: session=your-session-cookie" \
  -H "Accept: application/json"

Get Current Forms:

curl -X GET https://your-server/form-portal/forms/mycurrent \
  -H "Cookie: session=your-session-cookie" \
  -H "Accept: application/json"

Create Form:

curl -X POST https://your-server/form-portal/forms/create \
  -H "Cookie: session=your-session-cookie" \
  -H "Content-Type: application/json" \
  -d '{"formId":"form-123","workflowId":"workflow-456"}'

Get Templates for Role:

curl -X GET https://your-server/form-portal/forms/role/employee \
  -H "Cookie: session=your-session-cookie" \
  -H "Accept: application/json"

Rate Limiting

Currently, no rate limiting is enforced. However:

  • Avoid excessive API calls
  • Cache responses where appropriate
  • Use reasonable polling intervals
  • Batch operations when possible

Best Practices

Authentication

  • Use secure session management
  • Rotate session cookies regularly
  • Implement session timeout
  • Use HTTPS for all requests

Error Handling

  • Check HTTP status codes
  • Parse error messages
  • Implement retry logic for transient errors
  • Log errors for debugging

Performance

  • Cache role and workflow information
  • Minimize API calls
  • Use appropriate polling intervals
  • Implement pagination if needed

Security

  • Validate all inputs
  • Use HTTPS exclusively
  • Implement CORS appropriately
  • Monitor for suspicious activity

API Versioning

Currently, the API is unversioned. Breaking changes will be:

  • Documented in release notes
  • Communicated in advance
  • Backward compatible when possible

Support

For API issues:

  1. Check this documentation
  2. Review server logs
  3. Verify authentication
  4. Check privileges
  5. Contact support

Next Steps: - Installation - Deploy and configure - Access Control - Manage permissions - Administration - Admin overview

Next: Troubleshooting