_new

Creates a new Report.

Parameters

name

The name of the Report to be created.

type

The Type of Report to be created:

• linear

• pie

• barchart

• job_completion

• recurrence

• grid

y_axis

The topic where data will be gathered from for the Report, potential topics depend on the area of data picked in the "type" parameter:

Linear, Bar and Pie Charts:

• job

• customer

• asset_table

• date_completed

Job Completion:

• date_completed

y_axis_scale

The way which gathered data will be scaled, will naturally be linear if this parameter is not set, or logarythmic if this parameter is set to "log".

event_type

The exact event being tracked and returned for the Report, usable depending on the type of Report being created:

(For Bar, Pie and Linear Chart types of Report)

• meeting_time

• cdate

• date_completed

• invoice-cdate

• invoice-email_sent

increments

The time frequency of which data will be gathered:

• days

• weeks

• months

conditions

An array of conditions for the Report, each condition having four values. There are several potential areas which this condition can note, listed below. e.g [["job:is_complete","eq","2",1]]

For all Report Types except Grid:

• job:is_recurring (Whether it is part of a Recurrence. 2nd value is always "1") 3rd value: 0=Not Recurring 1=Is Recurring

• job_type:in (Job Type. 2nd value is always "1") 3rd value is an array of Job Type IDs. e.g ["24003"]

For all Report Types except Job Completion and Grid:

• job:is_complete (Status of a Job. 2nd value is either "eq"/Equal or "ne"/Not Equal) 3rd value: 0=Incomplete 1=Complete 2=Processed 3=Requires Customer Authorisation 4=Authorised 5=Cancelled

• user:id (Assigned User. 2nd value is either "eq"/Equal or "ne"/Not Equal) 3rd value is equal to the ID of a User.

• user:created_by (Created by a User. 2nd value is either "eq"/Equal or "ne"/Not Equal) 3rd value is equal to the ID of a User.

• customer:county (Customer Address: County. 2nd value is either "eq"/Equal or "ne"/Not Equal) 3rd value is the name of a set County in a customer.

• job:priority (Priority. 2nd value is either "eq"/Equal or "ne"/Not Equal) 3rd value is a value of priority.

For Job Completion Report types:

• due_date:margin (Due Date Margin. 2nd value is always "1") 3rd value is an integer.

• job:form_id (Form. 2nd value is either "eq"/Equal or "ne"/Not Equal) 3rd value is the ID of a Job Form.

If you have the "y_axis" parameter set to an Asset Table and the "event_type" parameter set to the ID of an Asset Table Field (DateTime type, specifically), this field can also be considered a condition to note, e.g [["1","is_in","test string to find",0]]

2nd value in this case can be:

• eq (Equal)

• ne (Not Equal)

• contains

• is_in

3rd value is a string to be related to the Asset Table Field.

The 4th value sets whether this condition is dynamic or not (0=no, 1=yes)

breakdown_by

The way that data from this Report will be broken down. If this parameter is not set it will be considered as everything altogether:

• user_id

• created_by

• customer_id

• form_id

• department_id

• is_complete

• type

If the "event_type" parameter is set to "invoice-cdate" or "invoice-email_sent", this parameter should instead be set to "invoice-sent".

table

An integer of the table data if an Asset Table is picked in the "y_axis" parameter. (e.g 1696768442058)

table_value

The ID of the Asset Table Field picked for the Report.

table_value_distinct

Parameter that sets whether only distinct values will be counted in the Report or not. (0=include non-distinct values, 1=only distinct values)

grid

An array of Grid data used if the "type" parameter is set to grid.

Examples

A Report for Job Completion:

FM_api('Report_new',[
    'name'=>'test report one',
    'type'=>'linear',
    'y_axis'=>'job',
    'event_type'=>'date_completed',
    'increments'=>'days',
    'conditions'=>'[["user:id","eq","92447",0]]',
    'breakdown_by'=>'is_complete',
    'table_value_distinct'=>'0'
]);

A Report including an Asset Table:

FM_api('Report_new',[
    'name'=>'Test report two',
    'type'=>'barchart',
    'y_axis'=>'asset_table',
    'y_axis_scale'=>'log',
    'event_type'=>'1',
    'increments'=>'weeks',
    'conditions'=>'[["1","contains","test item within field",1],["3","eq","test condition",0]]',
    'breakdown_by'=>'form_id',
    'table'=>'1696768442058',
    'table_value'=>'3',
    'table_value_distinct'=>'1'
]);

A Grid type of Report:

FM_api('Report_new',[
    'name'=>'Test Grid Report',
    'type'=>'grid',
    'y_axis'=>'asset_table',
    'increments'=>'days',
    'table'=>'1607682750',
    'table_value'=>'2',
    'table_value_distinct'=>'0',
    'grid'=>'[[{"t":"test field","s":{"background":"rgb(102, 102, 102)","color":"rgb(0, 255, 0)"}},{"t":"blue text","s":{"background":"rgb(255, 0, 255)","color":"rgb(0, 0, 255)"}},{"t":"vibrant data, no text color","s":{"background":"rgb(255, 153, 0)"}}],[{"t":"lower field","s":{"background":"rgb(255, 255, 0)"}},{"t":"some test text.","s":{"background":"rgb(238, 238, 238)","color":"rgb(116, 27, 71)"}},{"t":"bottom right text, no background color","s":{}}]]'
]);

Results

On Success

"{"ok":1,"id":"40035"}"

On Failure

If the "name" parameter is not set:

{"error":"missing or invalid parameter: name"}