View source for Configure Run Report command

{{Report TOC}}
[[Resco mobile apps]] can generate [[mobile Reports|mobile reports]] using data from the CRM. In the app, reports are usually initiated using the [[command editor|command]] '''Run Report'''. 
* Since [[Releases/Spring 2021|release 14.0]], it is possible to configure the behavior of this command using the '''On Execute''' rule.
* Since [[Releases/Autumn_2021|release 14.2]], you can configure this directly in command properties.
* Since app version 16.0.2 and JSBridge.js version 16.0, you can use the configuration in JavaScript.

== Configure in command properties ==
[[File:Advanced report config.png|right]]
# Do one of the following to start the [[command editor]]:
#* In Woodford, edit a form, then click '''Commands'''.
#* In the Questionnaire Designer, edit a questionnaire, then click '''Edit'''.
# Add the Run Report command to the list of selected commands.
# Select the new command and click '''Properties''', then click '''Advanced report configuration'''.
#* Select the default (pre-selected) report, either by ID (and select the report from a list) or by name (and enter a name).
#* If you have multiple reports defined and you want to make sure that users don't choose a wrong report, click '''Define filter''' and set which reports should be available with this button.
#* Enter '''Output file name''' if you want to control how the report file is named.
#* As '''Save report to entity''', select the entity where the report file is saved.
#* Select which report formats should be available in the app.
#* Select which commands should be available for a generated report.
#* As '''Action after report generation''' (or '''Immediate action'''), select "Save and close" if you want to save the report automatically after generation. Users can opt to view the generated report.
#* Enable '''Auto run''' if you want the report generation start immediately after selecting the command in the app (skipping in-app configuration).
#* Enable '''Automatically save signed reports''' to automatically save reports signed by all parties.
# Click '''OK''' and save all changes.

== Configure via rules/JSBridge ==

As an alternative to the command properties, you can pass the configuration string in an [[On Execute]] rule or in [https://github.com/Resconet/JSBridge/wiki/MobileCRM.MobileReport MobileCRM.MobileReport] object.

=== Configuration string ===

The configuration is stored as a JSON string with the following format:

<syntaxhighlight lang="json">
{
    "formats": [
        "pdf",
        "word"
    ],
    "commands": [
        "save",
        "email",
        "openexternal"
    ],
    "autorun": true,
    "filter": "<fetch version=\"1.0\"><entity name=\"resco_mobilereport\"><filter type=\"and\"><filter type=\"and\"><condition attribute=\"statuscode\" operator=\"eq\" value=\"1\"/><filter type=\"and\"><filter type=\"and\"><condition attribute=\"name\" operator=\"like\" value=\"%{{Shared.sharedVar1}}%\"/></filter></filter></filter></filter></entity></fetch>",
    "reportId": "Account Report",
    "reportName": "Account Report {sharedVar1} {dummy1} {dummy2:yyMMdd_HHmmss} {modifiedon:yyMMdd_HHmmss}",
    "attachmentType": "annotation",
    "immediateAction": "None" / "SaveAndClose"
}
</syntaxhighlight>

All fields in the configuration are optional and can be skipped. In that case, Resco Mobile CRM falls back to the default values.

;formats: The list of allowed report formats. Supported values: <code>Pdf, Html, Word, Excel</code>. Case insensitive. You can use <code>*</code> wildcard as the first and only item in the array to indicate that all formats are allowed. An empty array means no formats are allowed. Default is <code>*</code>.

;commands: The list of allowed report commands (i.e., actions available for a complete report). Supported values: <code>Save, eSignature, SendTo, View, OpenExternal, Print, Email, Copy, Export</code>. Case insensitive. The <code>*</code> wildcard is supported the same way as with formats. Default is <code>*</code>.

;autorun: Indicates if the report runs automatically or a user needs to explicitly execute it. Supported values: <code>true</code>, <code>false</code>. Default is <code>false</code> for regular entities and <code>true</code> for questionnaires.

;filter: Serves to restrict the reports a user can choose from the dropdown menu. It is not required for default report as indicated by '''reportId''' to be included in fetch results, however, it is a good idea for consistency.

:The fetch expression in XML format encoded as JSON compatible value. It must be for the <code>resco_mobilereport</code> entity.

:The conditions in fetch can use placeholder values in format <code><nowiki>{{Entity.fieldname}}</nowiki></code> or <code><nowiki>{{Shared.variableName}}</nowiki></code>. Variable names are case-sensitive. Values are taken from the parent entity (the one on which the form is executed, e.g., Account or Questionnaire).

:The default value is a fetch expression consisting only of automatically added conditions as described below.

:The following conditions are automatically added to the fetch if not present in configured fetch.

:* <code>resco_entityname = {name of parent entity}</code> - ensures that only reports dedicated for the parent entity can be selected.
:* <code>statuscode = 1</code> - ensures that only active reports can be selected.
:* <code>resco_sourcetype = ReportSourceType.Both or ReportSourceType.Record</code> - ensure that the right type of report based on how many source records there are.
:* <code>resco_languagecode in [ -1, lcid ]</code> - ensures that only reports for the current user's language and language-neutral reports can be selected.

:Inspections only (resco_questionnaire entity)
:* <code>resco_recordid = {ID of parent questionnaire's template}</code> - ensures that only reports created for the template of parent questionnaire can be selected.

:Note: By including your own conditions in the configured fetch you can make these filters more (or less) restrictive.

;reportId: Identifies the report selected by default. Report Identifier (<code>Guid</code>) or Report name (<code>string</code>) can be provided. Default is no report for regular entities and automatic (embedded) report for questionnaires.

;reportName: The output filename used for the generated report. The name can contain valid C# format string constructs referencing fields or shared form variables, e.g. <code>Filename {modifiedon:yyMMdd_HHmmss}</code>. Values are taken from the report's parent entity.

:The default value is in format: <code>{resco_mobilereport.name} {createdon:yyMMdd_HHmmss}</code>.

;attachmentType: The name of the binary entity used for storing generated reports. The default value depends on the project configuration.<br>Since [[Releases/Summer 2023|release 16.1]], if you are running the report from a form, you can save it to a [[file column]] of the form entity.

;autosavesigneddoc: Indicates whether a report should be automatically saved when users sign it. Supported values: <code>true</code>, <code>false</code>. Default is <code>true</code>.
: '''Note:''' This function requires Resco Mobile CRM 14.1 and later.

;immediateAction: Use "SaveAndClose" to save the report automatically after generation. Users can opt to view the generated report. This function requires Resco Mobile CRM 14.2 and later.

=== On Execute rule ===

A configuration string, as detailed in the previous section, can be used in the On Execute rule to configure the behavior of the Run Report command. You have to enter it in the ParamString field. This function is available for form commands and questionnaire commands.

{|
| [[File:On execute rule for run report command on Account entity.png|400px]]
| [[File:On execute rule for run report command on Questionnaire.png|400px]]
|- style="text-align: center;"
| On execute rule for the Account entity <br>(in [[Woodford]])
| On execute rule for the Questionnaire entity<br> (in the [[Questionnaire Designer]])
|}

; Step Command.Param Assign 1: The Param field is used to distinguish between the old and the new format of the ParamString. It is an integer and its value stands for the version of the configuration. The legacy value is 0, the new JSON format is 1.

; Step Command.ParamString Assign  ,,{ "formats"...}: This is where you enter the configuration string.

Note: Previous versions of MobileCRM (13.3 and older) relied on ParamString to only store Guid of default report and name of attachment entity in a comma-delimited string (e.g., <code>C8735473-FFA8-4D87-AF7B-F4B6C7CFECEA,annotation</code>). To maintain backward compatibility (avoid crashes) with MobileCRM 13.3 and earlier, it is needed to start configuration string with two commas, e.g. <code>,,{ "formats": ["pdf", "word"], "commands" : ["save", "email", "openexternal"], ... }</code>.

=== Script example ===

Use the new function showFormWithConfiguration of the [https://github.com/Resconet/JSBridge/wiki/MobileCRM.MobileReport MobileCRM.MobileReport] object to take advantage of the JSON configuration. Note that when used in JavaScript, the fetch filter needs an additional backslash to properly escape the characters (two backslashes instead of one).

<syntaxhighlight lang="js">
function showReportDialog() {
  MobileCRM.UI.EntityForm.requestObject(function (entityForm) {
    var report = new MobileCRM.Reference("resco_mobilereport", "012f0a8c-547f-42e5-a8f3-67abb7767969");
    var ref = new MobileCRM.Reference("account", entityForm.entity.id);
    var params = '{ "formats": ["pdf"], "commands": ["save", "email"], "autorun": false, "reportName": "Account Report", "filter": "<fetch version=\\"1.0\\"><entity name=\\"resco_mobilereport\\"><filter type=\\"and\\"><condition attribute=\\"name\\" operator=\\"like\\" value=\\"test2\\"/></filter></entity></fetch>", "reportId": "test2", "attachmentType": "annotation", "immediateAction": "None" }';
    MobileCRM.MobileReport.showFormWithConfiguration(report, [ref], null, params, MobileCRM.bridge.alert, null);
  }, MobileCRM.bridge.alert, null);
}
</syntaxhighlight>

== Known limitations ==
* The feature is available for reports on [[form]]s and questionnaires. It is not available from [[view]]s.
* The settings are ignored in the web version of Resco apps.






{{Feedback}}
[[Category:Woodford]]