Table of Contents
FormKiQ Core is an Open Source Headless Document Management System (DMS) that runs completely in YOUR Amazon Web Services (AWS) Cloud.
You can use FormKiQ Core to power:
- Easily store Documents / Form data from your website
- Quickly Tag and Organize your Documents
- Flexible integrate into existing application or build custom workflows
FormKiQ Core is built for any size organization, from personal websites to large, enterprise organizations requiring full control of any number of internal and external documents.
FormKiQ Core is built using AWS Serverless services like AWS Lambda, Amazon API Gateway, Amazon DynamoDB and Amazon S3; this means that there are no servers for you to maintain or manage, and all of your data stays within your AWS cloud.
Please visit our website to see the full list of features.
โ API First (FormKiQ API) and Cloud-Native Architecture
โ Easy Integration with Existing Applications
โ Built Using Serverless Services (no servers to maintain or manage)
โ Supports Unlimited Document Tagging & Versioning
โ Document Processing Through Subscribing to Document Events
โ Supports Both Multi-Tenant and Multi-Instance
โ Includes an Intuitive User Interface (FormKiQ Console) for Document Management
Click the link below to see how you can run the FormKiQ Demo is YOUR AWS Account.
FormKiQ Core was created using serverless technology. This means that there are no servers to manage; everything is managed by AWS. All AWS services FormKiQ uses pay-per-usage billing. You can start using FormKiQ with very little cost. AWS provides a free tier to all AWS accounts. This means that some AWS services you can use for free pending you stay under the usage limits. Below is the list of services FormKiQ uses and their approximate usage costs, so give you an idea on how much it costs to run FormKiQ. (All costs in USD)
Service | Cost |
---|---|
Amazon Api Gateway | $1.00 per million requests |
Amazon DynamoDB | First 25 GB Free |
Write request units - $1.25 per million write request units | |
Read request units $0.25 per million read request units | |
Amazon CloudFront | $0.085 per GB of Data Transfer Out to Internet |
Amazon S3 | $0.023 per GB / Month |
AWS Lambda | approx. first 400,000 requests Free per Month |
$0.0000168667 per additional request |
FormKiQ core can be used immediately after being deployed to handle web form submissions on your website. (In fact, you don't even need to be hosting your site in AWS to use FormKiQ for processing your site visitor's form submissions.)
The easiest way to include FormKiQ on your website is through the FormKiQ Client SDK npm module.
You can see FormKiQ Core and the FormKiQ Client SDK in action in the examples below:
https://github.com/formkiq/formkiq-webform-examples-contact
https://github.com/formkiq/formkiq-webform-examples-jobapplication
FormKiQ Core has been architected using Amazon Web Services (AWS) Serverless technologies. This provides several benefits:
โ Only pay AWS for usage (all services come with a generous monthly free tier)
โ Easily scales to thousands of concurrent requests
โ No servers to maintain or manage
FormKiQ core uses the following AWS technologies:
- Amazon S3 - for storage of files / documents
- Amazon CloudFront - for hosting the FormKiQ Console
- AWS Lambda - for document processing
- Amazon DynamoDB - storing of document metadata
- API Gateway - to serve the RESTful API platform
- Amazon Simple Notification Service (SNS) - document status notify system, allows applications to be notified that a document has been create/deleted or updated
- AWS IAM and Amazon Cognito - User and System authentication
FormKiQ Core supports being installed using the AWS SAM CLI.
After the deployment is completed, you will receive an email with a link to the FormKiQ Console, which has been installed in your AWS Cloud as part of the setup. You will be asked to login to your account, and once you do, you will be prompted to change your password.
Once you have set your password, you are ready to use FormKiQ Core.
For more information on what is created by the deployment (including Outputs), please see What's Deployed.
The AWS Serverless Application Model (SAM) is an open-source framework for building serverless applications.
You can download the SAM zip file from the FormKiQ Core Release page.
Once downloaded you can following the Install document for instructions on how to install FormKiQ Core.
After the FormKiQ Cloudformation Stack completes output values from the deployment are made available in the CloudFormation Outputs and in the SSM Parameter Store. Below you'll find a description of the outputs.
CloudFormation Outputs
Key | Description |
---|---|
CognitoClientId | Cognito Client Id |
CognitoUserPoolId | Cognito User Pool Id |
ConsoleUrl | The URL for the FormKiQ Console |
FormKiQVersion | FormKiQ Version |
HttpApiUrl | The URL for the API endpoint that uses Cognito authorization |
IamApiUrl | The URL for the API endpoint that uses IAM authorization |
SSM Parameter Store
SSM parameters made it easy for applications to automatically lookup FormKiQ configuration. All configuration keys start with '/formkiq/{AppEnvironment}'
Parameter | Description |
---|---|
api/DocumentsHttpUrl | The URL for the API endpoint that uses Cognito authorization |
api/DocumentsIamUrl | The URL for the API endpoint that uses IAM authorization |
cognito/AdminGroup | Cognito Admin Group |
cognito/IdentityPoolId | Cognito Identity Pool |
cognito/UserPoolArn | Cognito User Pool Arn |
cognito/UserPoolClientId | Cognito User Pool Client |
cognito/UserPoolId | Cognito User Pool |
cognito/UserPoolProviderName | Cognito User Pool Provider Name |
cognito/UserPoolProviderUrl | Cognito User Pool Provider URL |
console/AdminEmail | Console Admin Email |
console/Url | The URL for the FormKiQ Console |
console/version | Console Version |
dynamodb/CacheTableName | DynamoDB Cache table name |
dynamodb/DocumentsTableName | DynamoDB Documents table name |
iam/ApiGatewayInvokeGroup | API Gateway Group that allows invoking of endpoints |
iam/ApiGatewayInvokeGroupArn | API Gateway Group Arn that allows invoking of endpoints |
iam/ApiGatewayInvokeRole | API Gateway Role that allows invoking of endpoints |
iam/ApiGatewayInvokeRoleArn | API Gateway Role Arn that allows invoking of endpoints |
lambda/ConsoleInstaller | Lambda for Console Installation |
lambda/DocumentsApiRequests | Lambda for processing API Requests |
lambda/DocumentsUpdateObject | Lambda for processing Document Update Events |
lambda/StagingCreateObject | Lambda for processing Staging Document Create Events |
region | Deployment Region |
s3/Console | Console S3 Bucket |
s3/ConsoleArn | Console S3 Bucket Arn |
s3/ConsoleDomainName | Console S3 Bucket Domain Name |
s3/ConsoleRegionalDomainName | Console S3 Bucket Regional Domain Name |
s3/DocumentsS3Bucket | Documents S3 Bucket Name |
s3/DocumentsStageS3Bucket | Documents Staging S3 Bucket Name |
sns/SnsDocumentsCreateEventTopicArn | SNS Topic for Document Create Events |
sns/SnsDocumentsDeleteEventTopicArn | SNS Topic for Document Delete Events |
sns/SnsDocumentsUpdateEventTopicArn | SNS Topic for Document Update Events |
sqs/DocumentsUpdateArn | SQS ARN for processing Document Update Events |
sqs/DocumentsUpdateUrl | SQS URL for processing Document Update Events |
version | FormKiQ Stacks Version |
FormKiQ creates two APIs on deployment. One API uses Cognito authorization and the other uses IAM authorization.
See CloudFormation Outputs for API URLs.
Below is a summary of the FormKiQ Core FormKiQ API. The API was built using the OpenAPI Specification.
Method | Url | Description |
---|---|---|
GET | /documents | Returns a list of documents |
POST | /documents | Create document |
GET | /documents/{documentId} | Get document details |
PATCH | /documents/{documentId} | Update document details |
DELETE | /documents/{documentId} | Delete document |
GET | /documents/{documentId}/versions | Get versions of document |
GET | /documents/{documentId}/content | Get document content |
GET | /documents/{documentId}/tags | Get document tags |
POST | /documents/{documentId}/tags | Add tag to document |
GET | /documents/{documentId}/tags/{tagKey} | Get a specific tag |
PUT | /documents/{documentId}/tags/{tagKey} | Update tag |
DELETE | /documents/{documentId}/tags/{tagKey} | Delete tag |
GET | /documents/{documentId}/url | Get document URL |
GET | /documents/upload | Returns URL that can accept uploads largers than 5 MB |
GET | /documents/{documentId}/upload | Returns URL that can accept uploads largers than 5 MB to update a specific document |
POST | /search | Document search |
POST | /public/documents | Public (unauthenticated) URL for creating a document, used for web forms |
GET | /webhooks | Returns a list of webhooks |
POST | /webhooks | Create Webhook |
Many services today allow you to uses webhooks to notify your application when an event happens in the service. For example, Stripe allow you to specify a webhooks to notify your application when an event happens in your account.
With FormKiQ you can create webhook endpoints that you can use to receive and store event notifications from other services. Using the /webhooks API (or from the console), you can create a webhook and then enter that webhook in Stripe or other supporting services and immediately start receiving notifications.
FormKiQ allows you to take this one step further and using the Document Events (that are created every time a webhook notification is received), you can easily write custom code that is automatically executed.
While FormKiQ Core was built using an API First design methodology that allows easy integration with existing applications, you can also use the console interface that is set up with FormKiQ Core.
The FormKiQ Console supports:
โ Adding / Removing Documents
โ Adding / Removing Document Tags
โ Search Documents
โ Executing FormKiQ API Calls within the API Explorer - you can use API methods directly from the console
The FormKiQ Console is open source and can be found on Github.
An email will be sent to your AdminEmail address with a link to the FormKiQ Console once the deployment has completed, but you can also find the Console URL in your CloudFormation Outputs.
FormKiQ Core follows AWS' best practices when it comes to protect data and services. Amazon Cognito is the default authentication and authorization for the FormKiQ API and the FormKiQ Console. (AWS Identity and Access Management (IAM) is also available for accessing the API.)
Each FormKiQ Core deployment creates its own User Pool. By default, FormKiq Core uses the "AdminEmail" parameter to create a user with administrator privileges. FormKiq Core sends a confirmation link to the "AdminEmail" during deployment.
All user maintenance operations can be done via the Amazon Cognito console. To learn how to add additional users see Amazon Cognito's Developer Guide for instructions.
See Outputs for FormKiQ configuration.
During deployment, FormKiQ Core creates three Cognito Groups within its Cognito User Pool:
- Admins
- default
- default_read
Users in the "Admins" group have full access to all documents in FormKiQ Core.
Users in the "default" group will have read/write access to documents in the default siteid.
Users in the "default_read" group will have read only access to documents in the default siteid.
All group maintenance operations can be done via the Amazon Cognito console. To learn how to add users to a cognito group see Amazon Cognito's Developer Guide for instructions.
When integrating FormKiQ with existing application or other AWS services, AWS Identity and Access Management (IAM) is a preferred authorization mechanism. For this reason FormKiQ creates 2 APIs, one uses Cognito authorization and the other uses IAM authorization.
FormKiQ creates an IAM group that provides access to invoke FormKiQ APIs in Amazon API Gateway. Users added to this group and can signing the request which authenticates it with API Gateway.
See Outputs for more information on FormKiQ's IAM configuration.
Document events are a powerful feature of FormKiQ Core. This feature allows operations to be triggered on documents automatically on a change event. For example, when a document is created, a document event could trigger it to:
- send an email notification
- scan for viruses
- insert data into a database
- etc.
Document event are created and sent through Amazon Simple Notification Service (SNS). Amazon SNS is a messaging service that can be used for application to application communication. FormKiQ Core uses it as a publish/subscribe service, where applications can listen to the SNS service and be notified about different document events.
FormKiQ Core creates a single SnsDocumentEvent
topic where all documents events are sent. You can use Amazon SNS subscription filter policies .
FormKiQ Core provides the following message attributes you can filter on. https://docs.aws.amazon.com/sns/latest/dg/sns-subscription-filter-policies.html
Message Attribute | Possible Value(s) | Description |
---|---|---|
type | create, delete, update | Document Event(s) for create, update, or delete document |
siteId | default, (custom siteId) | Site Tenant Document Event was created in |
See the SSM Parameter Store Outputs for SNS Topics
FormKiQ Core supports running as a multi-tenant application. This can be used for internal departments or teams, or for external clients. During deployment, a "default" SiteId is created; all documents are stored in that tenant by default.
To create another SiteId is as simple as adding a Cognito group to the user pool
Creating a Cognito Group with the same name as the SiteId but ending in "_read" will create a readonly group. The users in this group will have readonly access to that SiteId.
Each API requests has a "SiteId" parameter you can pass to specify which SiteId you would like to use.
NOTE: This parameter is only needed if a user belongs to multiple SiteIds or if the user is in the "Admins" Group (full access) and wants to perform an operation in a SiteId other than "default".
Please see our wiki for instructions.
MIT - 2020 (c) FormKiq Inc. More details see LICENSE file.