> 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"}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.fieldmotion.com/fieldmotion-api-docs/report/_new.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.