> For the complete documentation index, see [llms.txt](https://docs.fieldmotion.com/fieldmotion-api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fieldmotion.com/fieldmotion-api-docs/report/_new.md).

# \_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"}
```