Reporting

This feature allows creating reports and sending them to recipients. This is highly flexible and can be configured via parameters.

Overview

In order to create reports, a so-called report scheduler has to be created. It will take care of creating the reports:

• one time
• regularly, e.g. every day, every week, at the first of the month, etc...

Each report scheduler is based on a report definition, which can be seen as a template for the report. It defines all parameters that can be changed, e.g. the language of the report, the recipients or the generated file type. Those report definitions can be queried before, so you have all the required information to create a report scheduler.

Once the report scheduler is created, it will attempt to create reports based on the given schedule and send it to the recipients.

Report Scheduler

Preparing the Report Scheduler

Before you can create a new report scheduler, you need to fetch some information, so all required fields in the mutation can be set.

Picking a Site

To get a list of all sites for which the current user can create a report scheduler, run a query like this one:

query AVAILABLE_SITES_TO_CREATE_REPORT($first: Int, $input: SiteQueryInput) {
  sites(first: $first, input: $input) {
    totalCount
    nodes {
      eid
      name
    }
  }
}

Input variables:

{
  "first": 10,
  "input": {
    "canBeUsedToCreateReport": true
  }
}

This will return the first 10 sites that can be used to create reports. You can use one of their eids in the upcoming instructions.

Picking Users as Recipients

Now that you have picked a site, you need to query its users that can be set as report recipients. This can be done with a query like this one:

query AVAILABLE_REPORT_RECIPIENTS(
  $where: SiteUserFilterInput!
  $input: SiteFindInput!
  $first: Int
) {
  site(input: $input) {
    site {
      eid
      users(
        first: $first
        where: $where
        input: { includeSuperAdmins: true }
        order: { email: ASC }
      ) {
        nodes {
          user {
            eid
            email
          }
        }
      }
    }
  }
}

Input variables:

{
  "where": {
    "canBeReportRecipient": { "eq": true }
  },
  "first": 10,
  "input": {
    "eid": "<site_eid>"
  }
}

This will fetch the first 10 users (including super admins) for the site <site_eid>, sorted by email address. You can use one or more of their eids later.

Report Definitions

A report definition represents a template for reports that are available to a customer. It contains information about which file formats are available, or which parameters can be set when generating the report.

Reports can have different scopes:

• SITE_DATA: The report contains site data, such as measured or aggregated data
• SITE_EVENT_GROUP: The report contains event data, such as alerts
• EXTERNAL: The report will be generated using information not managed by Solytic. This should be used only if you have customized integrations with our reporting services.

Here is an example query:

query FETCH_REPORTS_TEMPLATES($filter: ReportDefinitionFilterInput) {
  reportDefinitions(where: $filter) {
    nodes {
      eid
      fileFormats
      name
      reportDefinitionParameters {
        nodes {
          eid
          name
          prompt
          availableValues {
            eid
            label
            value
          }
          parameterType
        }
      }
    }
  }
}

Input variables:

{
  "filter": {
    "scope": { "eq": "SITE_DATA" }
  }
}

Example response:

{
  "data": {
    "reportDefinitions": {
      "nodes": [
        {
          "eid": "<eid>",
          "fileFormats": [
            "PDF",
            "WORD"
          ],
          "name": "Performance Report Monthly",
          "reportDefinitionParameters": {
            "nodes": [
              {
                "eid": "<eid>",
                "allowBlankValue": "False",
                "allowMultipleValues": "False",
                "allowNullValue": "False",
                "availableValues": [
                  {
                    "eid": "<eid>",
                    "label": "english_us",
                    "value": "en-US"
                  },
                  {
                    "eid": "<eid>",
                    "label": "german_de",
                    "value": "de-DE"
                  },
                  {
                    "eid": "<eid>",
                    "label": "spanish_es",
                    "value": "es-ES"
                  }
                ],
                "name": "Language",
                "parameterType": "TEXT",
                "prompt": "language"
              },
              {
                "eid": "<eid>",
                "allowBlankValue": "False",
                "allowMultipleValues": "False",
                "allowNullValue": "True",
                "availableValues": [],
                "name": "Month",
                "parameterType": "DATE_TIME",
                "prompt": "one_time_report_month"
              }
            ]
          },
          "scope": "SITE_DATA"
        }
      ]
    }
  }
}

So based on the above report definition "Performance Report Monthly", you could play around with the parameters to create different reports:

• fileFormats: create a Word or PDF document
• parameter Language: create the report in English, German or Spanish
• parameter Month: fill the report for a given month, e.g. July

In order to understand the requirements of a report definition parameter, additional fields are returned. For example, allowBlankValue informs you if the field can be left blank. For more information, check the GraphQL documentation for each field via Playground.

Sometimes you can only pick from a list of available options. This is the case if the field availableValues is not empty, which we can see in the above example. The Language parameter can only accept English, German or Spanish.

Creating a Report Scheduler

Now that you know the details of a report definition, you can create a report scheduler based on it and fill it with the required and optional parameters.

There are some rules:

• The value specified in recurringInterval
  • can be empty, which means that the report will be generated once. The scheduler will be of type ONCE.
  • can be set as a crontab string, e.g. 0 9 1 * * (9:00 UTC at the first of every month), which means that the report will be generated regularly. The scheduler will be of type PERIODIC.
• If the scope of a report is
  • SITE_DATA:
    • The minimum frequency that you can set to generate reports is 1 day.
  • SITE_EVENT_GROUP:
    • The minimum frequency that you can set to generate reports is 5 minutes.
  • EXTERNAL:
    • The minimum frequency that you can set to generate reports is 5 minutes.
    • The parameter siteEId is not required, since the scheduler will have external dependencies instead.

Example mutation:

mutation CREATE_REPORT_SCHEDULER($input: ReportSchedulerCreateInput!) {
  createReportScheduler(input: $input) {
    reportScheduler {
      eid
      name
    }
  }
}

Input variables for the report schedulers where the scope is SITE_DATA or SITE_EVENT_GROUP:

{
  "input": {
    "fileFormat": "PDF",
    "isActive": true,
    "name": "My Test Report Scheduler",
    "recurringInterval": "0 9 1 * *",
    "reportNotificationSettings": [
      {
        "recipientEId": "<recipient_id>"
      }
    ],
    "reportSchedulerParameters": [
      {
        "reportDefinitionParameterEId": "<report_definition_parameter_eid>",
        "value": "<value_supported_by_definition>"
      }
    ],
    "reportDefinitionEId": "<report_definition_eid>",
    "siteEId": "<site_eid>"
  }
}

Input variables for the report schedulers where the scope is EXTERNAL:

{
  "input": {
    "fileFormat": "PDF",
    "isActive": true,
    "name": "My Test Report Scheduler",
    "recurringInterval": "0 9 1 * *",
    "reportExternalNotificationSettings": [
      {
        "emailAddress": "testemail@gmail.com"
      }
    ],
    "reportSchedulerParameters": [
      {
        "reportDefinitionParameterEId": "<report_definition_parameter_eid>",
        "value": "<value_supported_by_definition>"
      }
    ],
    "reportDefinitionEId": "<report_definition_eid>",    
    "externalReference":"5c283865-e3a0-4ca5-b66f-eded08428011"
  }
}

• This will create a report scheduler "My Test Report Scheduler" that
  • runs at 9:00 at the first of the month. Time is specified in UTC.
  • is active once created
  • uses the report definition <report_definition_eid> as a template
  • fetches the data for site <site_eid>
• The generated report
  • is in PDF format
  • will be sent to registered and non-blocked users, specified via <recipient_eid>.
  • will be sent to the specified <emailAddress> regardless if they belong to registered users or not.
  • will be in English, as specified via the report definition parameter <report_definition_parameter_eid>

For external report schedulers, you can set an external reference which is an open text that API consumers can use to identify the report scheduler with information that is external to Solytic. It can be internal IDs of their entities, custom identifier, or any other reference they can use to query the report scheduler later.

Updating a Report Scheduler

If you want to update an existing report scheduler, you can use the updateReportScheduler mutation.

Example mutation:

mutation UPDATE_REPORT_SCHEDULER($input: ReportSchedulerUpdateInput!) {
  updateReportScheduler(input: $input) {
    reportScheduler {
      eid
      name
    }
  }
}

Input variables:

{
  "input": {
    "name": "Changed name",
    "eid": "<report_scheduler_eid>"
  }
}

Deleting a Report Scheduler

To delete a report scheduler, use the deleteReportScheduler mutation.

Example mutation:

mutation DELETE_REPORT_SCHEDULER($input: ReportSchedulerDeleteInput!) {
  deleteReportScheduler(input: $input) {
    eid
  }
}

Input variables:

{
  "input": {
    "eid": "<report_scheduler_eid>"
  }
}

Reports

Querying Reports

Once a report scheduler has generated reports, those reports can then be queried.

Here is an example query:

• it will return all successfully generated reports belonging to a given report scheduler
• the reports are ordered by the creation date
• each report includes the related file
• each file contains a download link so that the rendered report can be downloaded

info

Download links are valid for 1 day from the time of creation. To get a new link, simply resend the query.

You can filter and sort by other properties as well. To find the available ones, check the GraphQL documentation for each field via Playground.

query FETCH_REPORTS_FOR_REPORT_SCHEDULER(
  $input: ReportSchedulerFindInput!
  $filter: ReportFilterInput,
  $order: ReportSortInput
) {
  reportScheduler(input: $input) {
    reportScheduler {
      eid
      name
      reports(where: $filter, order_by: $order) {
        nodes {
          eid
          name
          file {
            eid
            name
            mimeType
            size
            downloadLink
          }
          status
          createdAt
          lastUpdatedAt
        }
      }
    }
  }
}

Input variables:

{
  "input": {
    "eid": "<report_scheduler_eid>"
  },
  "filter": {
    "status": "SUCCESSFUL"
  },
  "order": {
    "createdAt": "DESC"
  }
}