Reports And Documents

To design a report you have to configure a document template of the Report type and define its layout using the Report Designer. See the “Adding/Editing Document Templates” section for details.

For the user to be able to produce and print out a report the report layout and the corresponding operation have to be configured. To design a report you have to configure a document template of the Report type (report template) and define its layout using the Report Designer (see the “Adding/Editing Document Templates” section). To get AwareIM to produce the report so that the user can see it and print it out you can do either of the following:

1. Define a menu item of the Create Document type (see the “Setting Menu Item Properties” section). AwareIM includes the default menu item of the Create Document type that allows the user to select the report she wants to create among all the report templates defined. Alternatively you can configure your own menu item that will generate the report from your specific report template. When a user selects this menu item in the Operation Mode AwareIM will generate the report and show it on the screen as PDF document (then it can be printed from the browser). A report created in this manner is not stored in the system and have to be re-created each time.
2. Define an attribute of the Document type in some business object and set its initial value to the name of your report template (see the “Attributes of Document Type” section ). Whenever the instance of the business object is created the report will be generated and stored permanently in PDF format as the value of the attribute. The user can bring up the form of the business object and press the View Document button to get the report to be displayed on the screen (then it can be printed from the browser). A report created in this manner gets permanently stored in the system together with the instance of the business object.
3. Define an operation of the Create Document type on a form of a business object – see the “Adding/Editing Form Operations” section.
4. A report may be generated as part of the process that uses DISPLAY DOCUMENT action. When the action is executed the report is displayed on the screen as PDF document. Note that the action can generate the report from the template as in the first option or display the document already stored as the value of the attribute of the Document type as in the second option.

When you design a report you can refer to attributes of business objects using tag elements – see the “Document Generation” section for details.

When you design a report you can define calculations to be performed inside tag elements. You can use any expressions allowed by the Rule Language. The common expression is, for example, to calculate the sum total of the attribute:

<<SUM Account.Balance>> 

See the “Document Generation” section for more details.

Sometimes you may want to group the data shown in a report by some criteria and print out a special header and/or footer for each group. To do this you need to configure the following:

1. The query that provides the data for the report must sort the data accordingly.
2. The layout of the report must include group bands. Each group band must have a group condition defined.

See the “Report Generation” and “Setting Band Properties” sections for more details.

You can show values of attributes of business objects related to a particular business object on a report. For example, if a PurchaseOrder object is related to an OrderLineItem object via a multiple relationship you can show which order line items are related to a particular purchase order on the report.

To include values of attributes of the related object in the report you have to define a sub-report element in the report. The sub-report element must refer to the report showing the instances of the related object and the query of the sub-report element must find the related objects. For example:

FIND OrderLineItem WHERE OrderLineItem IN PurchaseOrder.MyLineItems 

See also the “Editing Sub-report/Sub-presentation Element” section.

Sometimes it may be necessary to include a particular element (such as text or image) in the report only under certain conditions (for example, you may show sensitive data to one category of users but not others). In this case you can define a conditional element in the layout of your report and specify the conditions of printing. See the “Reports” and “Editing Conditional Element” sections for details.

Sometimes the same element may be shown with different properties (for example, in different colors) depending on some conditions – for example you can show the account balance in red if it is less than, say, 100 dollars and in green otherwise. This can be achieved by defining a conditional element in the layout of the report. The element will print the text in different colors depending on the conditions - see the “Reports” and “Editing Conditional Element” sections for more details.

Quite often you need to print out either the total number of data records in the report (or page or group) or the sequence number of a data record in the report (or page or group). This can be achieved by using the ELEMENT_COUNT or ELEMENT_COUNTER functions.

If you use ELEMENT_COUNT function inside a tag element the report will print out the total number of data records in the report (or page or group). If you use ELEMENT_COUNTER function inside the tag element the report will print out the sequence number of the data record in the report (or page or group). See the “Editing Tag Element” section for more details. You can also use other report specific functions such as PAGE_NUMBER and NUMBER_OF_PAGES. The full list of such functions is provided in the “Report and Documents Functions” section.

If you want to use the layout of a report in a different report you can export the layout of the first report and then import it into the second report. See the “Adding/Editing Document Templates” section for details on how to export and import the report layout.

In AwareIM documents and files are stored in attributes of the Document type. See the “Attributes of Document Type” and “Document Management” sections for more details.

AwareIM can perform “document merge” of Microsoft Word documents, Microsoft Excel documents, plain text documents and HTML documents. If you want to provide the “document merge” functionality in your system you have to configure document templates of any of the above mentioned types (see the “Adding/Editing Document Templates” section). Alternatively you can use document templates defined by the end user (Developer Edition only)

The templates must include tags that will be “merged” with real data when the final document is produced – see the “Document Generation” section for details on how it is done. To get AwareIM to produce the “merged document” so that the user can see it and print it out you can do either of the following:

• Define a menu item of the Create Document type (see the “Setting Menu Item Properties” section. AwareIM includes the default menu item of the Create Document type that allows the user to select the document she wants to create among all the document templates defined. Alternatively you can configure your own menu item that will generate the document from your specific document template. When a user selects this menu item in the Operation Mode AwareIM will generate the “merged document” and show it on the screen (then it can be printed from the browser). A document created in this manner is not stored in the system and have to be re-created each time.
• Define an attribute of the Document type in some business object and set its initial value to the name of your document template (see the “Attributes of Document Type” section). Whenever the instance of the business object is created the “merged document” will be generated and stored permanently as the value of the attribute. The user can bring up the form of the business object and press the View Document button to get the document to be displayed on the screen (then it can be printed from the browser). A document created in this manner gets permanently stored in the system together with the instance of the business object.
• A document may be generated as part of the process that uses DISPLAY DOCUMENT action. When the action is executed the document is displayed on the screen. Note that the action can generate the document from the template as in the first option or display the document already stored as the value of the attribute of the Document type as in the second option.
• Define a form operation of the Create Document type that can be invoked from the form of the business object. The instance of the object being edited will be used as the data source for the “merged document”. See the “Adding/Editing Form Operations” section for more details.

The data that AwareIM will use for the document may come from several sources:

• The user may explicitly specify a query to be used as part of the Create Document menu command
• The user may explicitly select certain instances of objects to be used as the data source when viewing the results of some query and then run the Create Document operation
• You can specify the query in your process as the FIND action that will put the desired data into the context.
• You can specify the query in the DISPLAY DOCUMENT action (USING clause)
• You can specify the query when configuring the document template

The preferred approach is to use the DISPLAY DOCUMENT action in a process. The action may use the query as the data source. If you are displaying the report AwareIM will just display it on screen. For other types of documents AwareIM will generate as many documents as there are instances returned by the query. You can get AwareIM to display the results on screen and let the user select specific instances to print out. Or you can use the MERGE INTO ONE clause in the action in which case AwareIM will merge all documents into a single document and show it immediately to the user who can then print it out.

This is described in the “User Defined Documents and Reports” and “Building Query” sections.

AwareIM does not support “multiple allowed” for attributes of the Document type, however, there is a way for you to implement “Multiple file upload” functionality when the user selects several documents at once and uploads them all to the system. In order to implement this functionality you need the following:

1. Define a business object representing your document. This business object should have at least one attribute of the Document type. It can have other attributes as well, such as Description of the document, type etc
2. Make sure that this object can be created automatically, i.e. if it has some mandatory attributes, the initial values for these attributes are provided. This is because AwareIM will be creating instances of this object behind the scenes and if some required values are not initialised properly by rules AwareIM will not be able to create instances of the object
3. Define a multiple reference to this object in the business object that will store the documents. In other words, rather than defining a Document attribute in this object you define a multiple reference to the object that includes this Document. For example, if you want to define attachments to your Order object, first define an OrderAttachment object with the Attachment Document attribute and then define multiple reference attribute Attachments (of the OrderAttachment type) to the Order object
4. Go to the Presentation option of the multiple reference attribute (Attachments in the example above) and go to the Panel Operations. Then add the Add New operation.
5. Select “Use multi-file upload for document attribute” as the parameter of the operation and specify the name of the Document attribute. At run time the user will be able to select multiple files to upload and for each file AwareIM will create an instance of the Document wrapper object (ObjectAttachment), upload the file into the Document attribute of this object and attach the instance of this object as a reference (to the Order object)

Starting from version 5.7 it is now possible to implement multiple file upload as a process. To do this you need to write a process that assumes that the Context contains a predefined business object called FileItem. This object has one attribute of the Document type called Doc. The process receives multiple instances of this object and it can do something with the documents stored in the Doc attribute – for example, copy them to some other business object, for example:

CREATE Photo FOR EACH FileItem WITH Photo.Picture = FileItem.Doc 

There are two ways you can let users edit documents that they store in the attribute of the Document type.

The default approach is to let users download the document, then edit the document outside of AwareIM using the appropriate editor and then let them upload the modified document back into the Document attribute of the business object. When you define an attribute of the Document type AwareIM automatically provides the buttons to upload the document to AwareIM and download it from AwareIM, so this approach is quite straightforward. The disadvantage of this approach is that the user has to perform quite a few steps to modify the document – download, edit and upload back.

An alternative approach is to use Zoho or Office Online document editors to edit/view the document in-place. Zoho (http://www.zoho.com) provides powerful web-based editors to edit many types of documents – MS Word, MS Excel, MS Power Point, Open Office, RTF, HTML etc. The user edits the document using the browser and when he presses the Save button the modified document is automatically saved in AwareIM.

Office Online allows editing Microsoft Office documents only. Just like Zoho the user edits the document using the browser and the changes are automatically saved in AwareIM. To edit documents using Office Online you have to make sure that your server where AwareIM is running meets Microsoft requirements –

1. It has to be added to the Microsoft “WOPI allow list” – please contact Microsoft for this
2. Tomcat has to be setup to run on either port 80 (testing mode only) or port 443 (both testing and production modes)

By default AwareIM runs Office Online in the testing mode. To enable the production mode create the file called oo.props that contains the following property:

DiscoveryUrl=https://onenote.officeapps.live.com/hosting/discovery

Put this file in the AwareIM/Tomcat/webapps/AwareIM directory.

See also this article for more details about putting Office Online in the production mode: https://wopi.readthedocs.io/en/latest/build_test_ship/shipping.html

To enable document editing feature the configurator has to do the following:

1. For Zoho integration make a decision whether their system will use their users’ Zoho account or their own Zoho account. If they want to use their own account they need to register this account with Zoho and then go to the following URL https://zapi.zoho.com to create the API key.
2. Then they need to create an attribute of the Document type as usual, go to the Presentation options of this attribute and tick the “Zoho editing” or “Office Online editing” checkboxes
3. For Zoho integration click the Settings button next to the checkbox and provide the Zoho API key
4. At runtime AwareIM will automatically display the editing button next to the attribute. When the user clicks on this button the corresponding Zoho or Office Online editor will be invoked.
5. If configurators want their users to use their own Zoho account, they will need to define a special attribute in the SystemSettings business object that will hold the Zoho API key. At step 4 they need to provide the name of this attribute, rather than the API key itself. Before the system is used by customers their system administrator will need to perform step 2 to register Zoho API key and set its value into the appropriate attribute of the SystemSettings object.

Embedded spreadsheets can be used to display data as an Excel table or to get Excel to perform calculations that can then be written into attributes of business objects and stored in the database. This can be especially useful if you already have existing Excel spreadsheets that you want to re-use to perform some calculations.

To use embedded spreadsheets in AwareIM you need to do the following:

1. Define an attribute of the Document type in some object
2. Open this attribute for editing, select the “Allowed Extensions” property and then choose “Embedded Spreadsheet” from the drop down list of allowed extensions.
3. If you will be storing results of spreadsheet calculations in the database define attributes that will store these calculations (the attributes must belong to the same object that owns the Document attribute)

When the system shows the form of this object in the browser AwareIM will generate a button that will allow users to create and edit spreadsheets. When the user presses this button AwareIM will display an Excel-like spreadsheet. You can create your own spreadsheet or use an existing one by importing an Excel file or using Copy and Paste to paste cells from Excel into the AwareIM spreadsheet.

If you want AwareIM to populate an existing spreadsheet with data from the database you need to specify the contents of the cell as “tag expression” that refers to objects in Context, for example <<Customer.Name>>. The Context will contain the instance of the object that owns the Document attribute with the spreadsheet. When the user presses the “Read Data” button at the top of the spreadsheet AwareIM will replace contents of the cell that have tag expressions with data from the database.

Once the data has been populated Excel will obviously re-calculate everything based on the values read from the database. You can then save results of the calculation in attributes of the object(s) in Context. To do this you need to do the following:

1. Click on the “Mapping” button at the top of the spreadsheet to define cells that will be written into attributes of the object(s) in Context. You need to define which cell to write and then provide a tag expression that defines where this cell will be written into. Note that the mapping is saved with the spreadsheet, so you only need to define mapping once
2. Click on the “Save Data” button to get AwareIM to save the cells defined in “mapping” into the database