Action Configuration

Actions define the operations available for each entity. FlowOn API supports seven action types:

Action Type	HTTP Method	Description
Create	POST	Create new records
Update	PUT/PATCH	Modify existing records
Read	GET	Retrieve a single record by ID
Delete	DELETE	Remove records
Upload	POST	Upload files/attachments
Download	GET	Download files/attachments
Process	POST	Execute custom actions

Common Action Components

All actions share these configuration components:

Definition

Property	Required	Description
Endpoint Name	Yes	The URL path segment for this action

Documentation

Property	Required	Description
Title	Yes	Short, descriptive name for the action
Description	No	Detailed explanation of what the action does

Inputs

Inputs define the parameters accepted by the API endpoint.

Property	Description
Name	Parameter identifier
Type	Data type (String, Integer, Money, DateTime, Entity Reference, etc.)
Required	Whether the parameter must be provided
Default Value	Value used if parameter is not provided
Validation	Validation rules (min/max, pattern, etc.)
Description	Documentation for API consumers

Data Fetcher

The Data Fetcher allows you to execute queries before the main action. This is useful when the action depends on data that must be retrieved first.

Property	Description
Query Name	Identifier for referencing the fetched data
Query Definition	The query to execute (can reference inputs)
Result Variable	Variable name to store the query result

Use Cases for Data Fetcher:

Validate that a referenced record exists
Retrieve default values from a related record
Check business rules against existing data
Fetch configuration values needed for the action

Access Control

See Access Control for complete details on Authorization Policy and Pre-conditions.

Create Action

The Create Action exposes an endpoint for creating new records of the entity.

Create Action Structure

┌─────────────────────────────────────────────────────────────────────┐
│                      CREATE ACTION STRUCTURE                         │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ DEFINITION                                                   │   │
│  │   • Endpoint Name (URL path)                                │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ DOCUMENTATION                                                │   │
│  │   • Title                                                    │   │
│  │   • Description                                              │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ INPUTS                                                       │   │
│  │   • Input parameters from API request                        │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ DATA FETCHER                                                 │   │
│  │   • Pre-fetch queries for dependent data                     │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ ACCESS CONTROL                                               │   │
│  │   • Authorization Policy                                     │   │
│  │   • Pre-conditions                                           │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ ENTITY PROPERTIES                                            │   │
│  │   • Field bindings with inputs                               │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Entity Properties

Entity Properties define how inputs map to the Dynamics 365 entity fields when creating the record.

Property	Description
Entity Field	The Dynamics 365 field name
Binding	The input parameter, fetched data, or expression to use
Transform	Optional transformation applied before saving

API Request Example

POST /api/sales/accounts
Content-Type: application/json
Authorization: Bearer {token}

{
  "name": "Contoso Ltd",
  "email": "info@contoso.com",
  "phone": "+1-555-0100",
  "categoryCode": 1,
  "primaryContact": "contact-guid-here",
  "creditLimit": 50000.00
}

API Response

Success (200 OK):

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Update Action

The Update Action exposes an endpoint for modifying existing records. It supports both full updates (PUT) and partial updates (PATCH).

Update Action Features

Full Update (PUT): All fields are updated; missing fields are set to null
Partial Update (PATCH): Only provided fields are updated; missing fields retain their values
Data Validation: Pre-conditions can validate business rules before updates
Audit Trail: Changes can be tracked through Dynamics 365 audit

API Request Examples

Full Update (PUT):

PUT /api/sales/accounts/a1b2c3d4-e5f6-7890-abcd-ef1234567890
Content-Type: application/json
Authorization: Bearer {token}

{
  "name": "Contoso Corporation",
  "email": "info@contoso.com",
  "phone": "+1-555-0200",
  "creditLimit": 75000.00
}

Partial Update (PATCH):

PATCH /api/sales/accounts/a1b2c3d4-e5f6-7890-abcd-ef1234567890
Content-Type: application/json
Authorization: Bearer {token}

{
  "phone": "+1-555-0300",
  "creditLimit": 100000.00
}

API Response

Success (200 OK):

{}

Note: Update operations return an empty response body on success.

Read Action

The Read Action exposes an endpoint for retrieving a single record by its identifier.

Read Action Configuration

Property	Required	Description
Endpoint Name	Yes	URL path segment (e.g., `accounts/{accountId}`)
Retrieve Attachment List	No	Include list of attachments in response

Properties Configuration

Properties define which fields are returned in the API response:

Property Attribute	Description
Field Name	The Dynamics 365 field to include
API Name	The name used in the JSON response
Type	Data type for serialization
Expand	For lookups, which related fields to include
Computed	Calculated values derived from other fields

Retrieve Attachment List

When enabled, the response includes metadata about all attachments:

{
  "accountId": "...",
  "name": "Contoso Ltd",
  "attachments": [
    {
      "attachmentId": "note-guid-1",
      "fileName": "contract.pdf",
      "fileSize": 245678,
      "mimeType": "application/pdf",
      "createdOn": "2024-01-15T10:30:00Z",
      "createdBy": "John Smith"
    }
  ]
}

API Request

GET /api/sales/accounts/a1b2c3d4-e5f6-7890-abcd-ef1234567890
Authorization: Bearer {token}

API Response

Success (200 OK):

{
  "accountId": "a1b2c3d4-...",
  "name": "Contoso Ltd",
  "telephone1": "+1-555-0100",
  "emailAddress1": "info@contoso.com",
  "primaryContact": {
    "id": "contact-guid",
    "name": "Jane Doe"
  }
}

Not Found (204 No Content): When the record doesn't exist, returns 204 with no response body.

Delete Action

The Delete Action exposes an endpoint for removing records. Delete operations typically require the strictest access control.

Delete Action Best Practices

Data Fetcher Considerations:

Verify the record exists before deletion
Check for related records that would be orphaned
Validate business rules (status, ownership, time restrictions)
Gather audit information before deletion

Common Pre-conditions:

Pre-condition Type	Example
Record exists	Return 404 if not found
Record is inactive	Require deactivation before deletion
No dependent records	Prevent orphaning child records
Ownership check	Only owner or admin can delete
Approval status	Cannot delete approved/finalized records

API Request

DELETE /api/sales/accounts/a1b2c3d4-e5f6-7890-abcd-ef1234567890
Authorization: Bearer {token}

API Response

Success (200 OK):

{}

Upload Action

The Upload Action allows files to be attached to entity records.

Upload Configuration

Property	Required	Description
Name	Yes	Action identifier (e.g., "upload-document")
Allowed Extensions	Yes	Permitted file types (e.g., ".pdf,.doc,.xlsx")
Max File Size	No	Maximum file size in bytes
Max Files Per Request	No	Maximum number of files per upload

API Request

POST /api/support/cases/{caseId}/upload-documents
Content-Type: multipart/form-data
Authorization: Bearer {token}

------WebKitFormBoundary
Content-Disposition: form-data; name="files"; filename="document.pdf"
Content-Type: application/pdf

[file binary data]
------WebKitFormBoundary--

API Response

Success (200 OK):

HTTP/1.1 200 OK
Content-Length: 0

Error Responses

File Too Large (400):

{
  "errorCode": "FILE_TOO_LARGE",
  "errorMessage": "File too large. Maximum size: 10 MB"
}

Invalid File Type (400):

{
  "errorCode": "INVALID_FILE_TYPE",
  "errorMessage": "File type not allowed. Allowed extensions: .pdf, .doc, .docx"
}

Download Action

The Download Action retrieves files from entity records.

Download Configuration

Property	Required	Description
Name	Yes	Action identifier
Attachment Name	Yes	Identifies which attachment to download

API Request

GET /api/support/cases/{caseId}/download/{attachmentId}
Authorization: Bearer {token}

API Response

Success (200 OK): Returns the file binary data with appropriate headers:

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="contract.pdf"
Content-Length: 245678

[file binary data]

Not Found (404):

{
  "errorCode": "ATTACHMENT_NOT_FOUND",
  "errorMessage": "The requested attachment was not found"
}

Process Action

Process Actions expose Dynamics 365 custom actions (processes) through the API. They can be either Local (bound to an entity) or Global (unbound).

Process Action Types

Type	URL Pattern	Use Case
Local	`/entities/{id}/actions/{action}`	Entity-specific operations
Global	`/processes/{action}`	Cross-entity or standalone operations

Process Action Binding

Process Input Arguments: Maps API inputs to the custom action's input parameters.

Property	Description
Process Argument	The custom action's input parameter name
Binding	The API input, fetched data, or expression to use

Process Output Arguments: Maps the custom action's output parameters to the API response.

Property	Description
Process Argument	The custom action's output parameter name
Response Field	The field name in the API response
Transform	Optional transformation before returning

API Request Example

POST /api/sales/`/accounts/\{accountId\}/actions/approve`
Content-Type: application/json
Authorization: Bearer {token}

{
  "approvalNotes": "Credit check passed",
  "creditLimit": 50000.00
}

API Response

Success (200 OK):

{}

Note: Process actions typically return an empty response body on success, or may return output parameters if defined.

Common Action Components​

Definition​

Documentation​

Inputs​

Data Fetcher​

Access Control​

Create Action​

Create Action Structure​

Entity Properties​

API Request Example​

API Response​

Update Action​

Update Action Features​

API Request Examples​

API Response​

Read Action​

Read Action Configuration​

Properties Configuration​

Retrieve Attachment List​

API Request​

API Response​

Delete Action​

Delete Action Best Practices​

API Request​

API Response​

Upload Action​

Upload Configuration​

API Request​

API Response​

Error Responses​

Download Action​

Download Configuration​

API Request​

API Response​

Process Action​

Process Action Types​

Process Action Binding​

API Request Example​

API Response​

Common Action Components

Definition

Documentation

Inputs

Data Fetcher

Access Control

Create Action

Create Action Structure

Entity Properties

API Request Example

API Response

Update Action

Update Action Features

API Request Examples

API Response

Read Action

Read Action Configuration

Properties Configuration

Retrieve Attachment List

API Request

API Response

Delete Action

Delete Action Best Practices

API Request

API Response

Upload Action

Upload Configuration

API Request

API Response

Error Responses

Download Action

Download Configuration

API Request

API Response

Process Action

Process Action Types

Process Action Binding

API Request Example

API Response