Hospital - Annual medical report


An annual medical report is a form for easy document generation and or file upload with a generalized rundown of the patients’ physical health status. Direct connection to Circularo allows for storage and signature in-app as well as easy access from users’ accounts after login.

The signing feature is provided by Circularo itself as a great replacement for manual signature. Sign field can be placed anywhere on the document as long as the form is set up properly.

Any bonus field in the document creation can be added and/or worthless fields can be removed so they do not take up precious space on your record.

If you have your document prepared and only need to upload it, then there is a dropzone ready for you in the upload section of the form.

How to use

Creating a new document

How to go about creating a new document:

  1. Begin: Upon opening the main screen click the button called “Generate a report“ which will bring you to a blank form.

  2. Fill in the name: This will trigger change and the name will get validated. With every keypress.

    1. First name and Last name have to be filled in if you wish to continue.
      1. If the name is valid then the “Patient Information“ section title will turn green and the patient’s name will be added after into parentheses.
      2. If the name is invalid then the section title will be red which indicates that you are still to fill valid name.
    2. Now if the name was valid all other sections should be blue as the “Patient information” section when you were starting. None of these sections is required to be filled in. Hence if you want you can send an empty document with the name only. (Any field can be made required upon request).
  3. Fill in the rest: As you are filling in the rest of the information about the patient’s condition with every keypress your inputs are being stored in an internal object which is then upon successful filling stored into SessionStorage so you do not lose your data if you accidentally press reload button

  4. Send: When you feel like the form is filled in enough just press the send button. If the form requires you to fill something in “Send“ button will be disabled and upon hovering it with the cursor it will show you what is wrong. If everything was filled in properly the button will get disabled and text will change to “Sending…“ which indicated that Circularo is preparing your document to be signed.

  5. Sign: When the document is finished preparing you will get automatically redirected to the Circularo document signing form. When you scroll down in the form you will find a yellow rectangle. When you click it; it will open a modal where you can manually write your signature or upload one.

  6. Finish: Press the finish button and your document will be stored in Circularo, signed, and ready to be used/viewed later. You will get redirected back to the form where you will be given the option to create/upload a new document.

Uploading a document

  1. Begin: Press the “Upload a report“ button which will bring you to the upload state screen with three inputs and a dropzone.

  2. Fill in the name: Before you choose your file fill in the patient’s name so that the document in Circularo has a correct title. (Form will not allow you to continue before you fill in First and Last names)

  3. Select file: Select a document from your computer which you want to upload by either clicking on the dropzone area which will bring up file explorer or simply drag and drop the file into the dropzone.

  4. Send: When the proper file is selected, and a name filled in press the “Send“ button. If everything goes according to design your file will be uploaded while the button stays disabled and says “Sending…“ When it is done you will be redirected to the Sign form in Circularo.

  5. Sign: When you are at the form scroll to the bottom of your document where you will find a yellow rectangular area; This is a sign field. When you press it; it will bring up a modal where you can manually create or upload a signature. When you are done with creating/selecting a signature, press the “Sign“ button. Your new signature should appear in the document within the yellow area.

  6. Finish: When you are done reviewing and signing the document press the button that says “Finish“ at the top and the document will get signed also in Circularo. When it is done, you will be redirected back to the Public Form where a “Send next“ option button will be awaiting you.

Reset form

If you ever need to completely reset all filled in information you might need a reset button. In this public form, it is called “Start over“ and can be found at the bottom of the screen.

Pressing this button will clear all information from SessionStorage and also sites internal storage it will clear all data from input fields which means that you will need to fill in the name again.

This reset also works in the upload form except it does not remove the file from the dropzone, you will need to press the “Remove file” button there yourself.

Technical background


To be able to work with the Circularo backend you need to obtain an API Key.

Get a token

For technical staff:

  1. Send a request to your tenant’s backend endpoint POST /login with body

      "name": "string", // your login username
      "password": "string", // your login password
      "permanent": true, // if you need the token to stay for good
      "tenant": "string" // your tenant (use "Default" if you are not sure)
  2. In the response, there is an attribute token, that is what you need

For technically insecure staff:

  1. Go to Swagger
  2. Find section called Login
  3. Find tab names POST /login
  4. Press Try it out
  5. Fill in the information by the scheme in the code section above (copy-paste and replace the insides of the right-hand side strings)
  6. Press Execute
  7. Navigate downwards to Response body and find a field called token, that is your token so copy it

Retrieve API key

For technical staff:

Send a request with your token as a query parameter to the endpoint of POST /api/key

The response only contains a field id that is your API key.

For technically insecure staff:

  1. While still in Swagger navigate to the top and you will find a little button with a lock symbol on it and the word Authorize, press it and it will open a modal. With one or more fields.

    Most importantly if there is one just paste your newly retrieved token in it. If there are multiple input fields find the one titled Token and place your token there.

  2. Now navigate a little lower to section called API

  3. Find tab named POST /api/key

  4. Press the Try it out button

  5. Now press Execute

  6. Response body part should appear again with 1 long line titled id in it

  7. Copy what is on the right-hand side of the colon and that is your API Key which you should use as your token


Getting a token (for non-technical staff)

Create a new API Key

Template and workflow

Next step when you have a token you will need a template for the report you want to make

Prepare a template

  1. Open Administration > Templates
  2. Press Add Template button on top of the screen
  3. Select a name for your template
  4. Prepare proper settings (follow the guide below)
  5. Add fields to be filled in
  6. Prepare what the PDF file should look like when finished in the Template tab of the form builder
  7. Link the fields properly using AngularJS notation (ng-model=model.<name of the given field>)

Prepare workflow

  1. Open Administration > Workflows
  2. Press Add Workflow button on top of the page
  3. Select a name for your workflow (rule of thumb for the naming convention is wf_<single word to describe what the workflow does>)
  4. Prepare states that the document can be in
  5. Prepare transitions and their specific behaviors
  6. Go to your template and assign it the new workflow

File upload

Usually, you need to upload a file only from a dropzone.

  1. Prepare a dropzone

  2. Add an event listener for fileadded and set up either auto upload or add it to queued files.

    Upload endpoint is POST /files/uploadFiles


Guide (API Integration Samples - Create a file)

Example (Create document and automatically sign it using workflow action)

Document creation

When you need to prepare an edoc you need to send it to POST /documents endpoint with all information required.

If your edoc is just a file, then fill in its information received from upload (see File upload section) into the documentObject inside the body.pdfFile attribute

documentObject object structure

        type: string, // name of your template
        body: {
            documentType: string, // name of your template             
            draftType: "create", // unless your have a draft prepared... Don't change it
            documentTitle: '', // here you will put the title of your edoc to be displayed in circularo
            pdfFile?: object, // optional - required only if you are using an already uploaded file
            <attribute-name>: string // any attribute your template contains and you want to fill in 
        definitionType: string, // 'edoc' if you want to fill in the data from form or 'ext' if uploading external file
        workflow: string, // Your workflow name
        actionId: number, // number code of state you want your item to be placed to
        optionalData: {
            signFields: [{
                type: string, // 'signature' for handwritten signature
                usage: "autosign", 
                position: {
                    "percentX": number<0 - 1>, // X axis percentage offset of your sign field from top left corner of the page                 
                    "percentY": number<0 - 1>, // Y axis percentage offset of your sign field from top left corner of the page                 
                    "percentWidth": number<0 - 1>, // Percentage of width of the page taken by your sign field
                    "percentHeight": number<0 - 1>, // Percentage of height of the page taken by your sign field
                page: number // Which page should your sign field be on (counting from 1)


replace <attribute-name> with the name of the field, you added in template creation and used in template building as model value (<TEMPLATE_NAME>_<FIELD_NAME>) now just fill in the value

You can put it in there when sending the request as

documentObject.body['<TEMPLATE_NAME>_<FIELD_NAME>'] = value; 


API Integration - Create a document

Example (Create document and automatically sign it using workflow action)

Redirect to Circularo without login straight to sign form

After the document is created you want to sign it and the best way to do exactly that is to get automatically redirected to a signature form directly in Circularo.

The best way to do this is to get the document’s ID after the upload and use it in coordination with the /loginRedirect state transfer.

How to:

  1. Prepare a return URL (if you have a state to be returned to - use that) and store it in a constant.

  2. Get front-end URL and append our transition state of /loginRedirect behind it.

  3. Add authentication with ?token=<token>

  4. Add query parameters:

    1. You want to go to signature form so use &redirect=app.sign

    2. redirect params with:

                      documentId: string, // ID of the uploaded edoc
                      documentType: string, // template name
                      forceHandover: string, // name of user who is signing
                      callbackUrl: string // the url you stored in a constant in the first step
  5. Store this string in a variable or you can immediately redirect (step 6)

  6. Redirect using window.location.href = <your url>


Redirect on Login with token to a given state