Overview

Excerpt
name API_end_point
Actionflows can be setup to provide an API end point which enables external systems to make calls to PhixFlow. Actionflows set up as API end points have a Insert excerpt _actionflow_api_endpoint _actionflow_api_endpoint nopanel true  icon on the Actionflow home screen.

This functionality has been enhanced between version 10 and version 11, please refer to the relevant section below.

Incoming API SetupImage Added Actionflow from the Actionflow home page

Set a unique name and provide a useful description

1. Note if using a pre 10.1 version of PhixFlow the name must be unique across all applications on PhixFlow.

When the Actionflow opens, on the toolbar click 

In the API section of the properties, enable API End-PointImage Added Properties

In the Basic Settings section of the properties, click API End-Point

1. This turns the Actionflow into an incoming API.

Enable Click Allow Anonymous Connections

AllowAnonymousConnections

This allows anyone with the URL for the API to call it, the audit trail records the system as running performing the API call.

 Adding authorization is covered later on this page.

Image Added Apply your changes

Step 2 - Input Connection Point Input Parameters

Incoming APIs require a specific set of Input Parameters on the connection point.

1. Click on the Connection Point In
2. In the Properties that open, in the Input Parameters section add the following attributes, the names are case sensitive:

Expand
title Version 11	10
To enable an actionflow as an incoming API, we need to define it as an end point and configure an incoming connection point with a set of predefined input parameters. These settings are described below: Step 1 - Actionflow Properties Create an
Insert excerpt
_actionflow	_actionflow
nopanel	true
Insert excerpt
_property_settings	_property_settings
nopanel	true
Excerpt
name
Insert excerpt
_save	_save
nopanel	true

Name	Type	Description
body	String	provides the information sent in the body of the API call.
contentType	String	Provides details of the Content Type
headers	String	Provides the information sent in the API call header.
url	String	Provides the complete URL that was used to call the API. This can be used to pass parameters to the API.

 3. 

Image Added Apply your changes

Step 3 - Configure your Actionflow

Configure the

actionflow to perform the required tasks

.

If you wish to return data from the API, 

1. Add a new Connection of type Output
   
   1. The name of the Output Connection Point will be used to retrieve the data as part of the path. This is covered in Calling a PhixFlow API (below).
2. Add the required Output Attributes i.e. the data you wish the API to return. Output Attributes

Calling a PhixFlow API

Step 4 - HTTP Method

To call a PhixFlow API use the HTTP

Method GET or 

Method POST

:

GET simply calls the API with data passed in the body of the request.

POST calls the URL and sends data in the body of the request. The body data is passed into the body attribute of the Actionflow setup above as an Input Connection point. 

API Mode

1. Wait for result (Synchronous) (Default): The API waits for the results or the timeout to occur. Note: If the timeout occurs the command is aborted.
2. Poll for result (Asynchronous): The API is called and a response is returned immediately including the process ID. Subsequent API calls can be made using the process ID to fetch the status of the action. The asynchronous mode can be thought of as “fire and forget”.

Step 5 - API URL

The API URL can be found in the Actionflow Properties → API Section → URL value

Example URL: https://app.phixflow.

Step 5 - API URL

The API can be called using a URL which is constructed as follows:

https://<<Server Name>>/phixflow/api/1/action/<<Actionflow Name>>/trigger

Example URL

https://app.phixflow.com/phixflow/api/1/action/MyApp/My%20API/trigger

The structure of the URL is as follows:

https://<<Server Name>>/phixflow/api/1/action/<<Application Name>>/<<Actionflow Name>>/trigger

note: In version 10 the url structure differed, this old structure has been deprecated: https://<<Server Name>>/phixflow/api/1/action/<<Actionflow Name>>/trigger 
Integrations using this old structure should be updated, however the url structure will still work in version 11.

Step 5.1 - API Status Check (Poll for Result)

1. If calling a PhixFlow Asynchronous API only, a result will be immediately returned which includes a Process ID for that run.
2. The Process ID is returned on the path:
   1. $.processId
   2. This can be accessed in an Output attribute using, _result.value
3. The Process ID can be used to call the following URL which will return the current state of the run:
   1. https://<<Server Name>>/phixflow/api/1/action/<<Application Name>>/<<Actionflow Name>>/poll/<<processID>>

Step 6 - Returned Data JSON Path

If your API has been configured to return data the path will be in the format:

$.data.<<Output Name>> 

Where <<Output Name>> is the Output connection point setup in step 3.

Adding Authentication

Step 7 - Enable Authentication

Step 8 - Create an Authentication User

Image Removed

Step 9 - Authentication Token KeyStore

A signing key is used to generate the Phixflow API key and this is stored on the server to ensure secure access.

Using the page Configure a Keystore and Aliases, configure phixflow-api-key to be used as the signing key for PhixFlow API Keys in the same way as the pepperKey is configured. This secret string must be a minimum of 32 bytes length.

Step 10 - Generate Authentication Token

Step 11 - Send Authorization

When calling the Incoming API, the authorisation token must be passed in as a header called: Authorization

Server Console Responses

The item calling the API End-Point will receive the a Response from the API End-Point stating whether it has run successfully (Success) or not (Fail). Responses can be customised to return specific messages.

If you are making the call using PhixFlow the Responses can be access as follows:

1. Click the ActionFlow entry
   1. Image Removed
2. In the Messages section which is opened below, double-click the lines that begin Response
   1. Image Removed
3. Click the Message Details tab to see the response.

API End-Point Results

1. Click the ActionFlow entry for the API End-Point
2. In the Messages section which is opened below, double-click any of the Messages to see more details
3. If you are using a debug() statement these will appear here.

Failures

An API End-Point will fail if the logic in the Actionflow fails or if the error() function is used to force a failure.

If records are passed to the API End-Point individually a failure will only impact the specific record being processed.

To enable an actionflow as an incoming API, we need to define it as an end point and configure an incoming connection point with a set of predefined input parameters. These settings are described below:

Step 1 - Actionflow Properties

1. Create an Image Removed Actionflow from the Actionflow home page
2. Set a unique name and provide a useful description
   1. Note the name must be unique across all applications on PhixFlow.
3. When the Actionflow opens, on the toolbar click Image Removed Properties
4. In the Basic Settings section of the properties, click API End-Point
   1. This turns the Actionflow into an incoming API.
5. Click Allow Anonymous Connections

   1. This allows anyone with the URL for the API to call it, the audit trail records the system as running performing the API call.

       Adding authorization is covered later on this page.

6. Image Removed Apply your changes

Step 2 - Input Connection Point Input Parameters

Incoming APIs require a specific set of Input Parameters on the connection point.

1. Click on the Connection Point In
2. In the Properties that open, in the Input Parameters section add the following attributes, the names are case sensitive:

 3. Image Removed Apply your changes

Step 3 - Configure your Actionflow

Configure the actionflow to perform the required tasks.

If you wish to return data from the API, 

1. Add a new Connection of type Output
   
   1. The name of the Output Connection Point will be used to retrieve the data as part of the path. This is covered in Calling a PhixFlow API (below).
2. Add the required Output Attributes

Calling a PhixFlow API

Step 4 - HTTP Method

To call a PhixFlow API use the HTTP Method POST

Step 5 - API URL

The API can be called using a URL which is constructed as follows:

Step 6 - Returned Data JSON Path

If your API has been configured to return data the path will be in the format:

$.data.<<Output Name>> 

Where <<Output Name>> is the Output connection point setup in step 3.

Adding Authentication

Step 7 - Enable Authentication

1. Open the Incoming API Actionflow.
2. On the toolbar click Image Added Properties
3. In the Basic Settings section of the properties, click Allow Anonymous Connection so that it is disabled, it will appear greyed out.
4. Image Added Apply the changes

Step 8 - Create an Authentication User

1. In the Image Added Repository, expand the application with the Incoming API.
2. Expand Image Added Roles and create an New Role by clicking Image Added.
   1. Pin the tab as we will need it to remain open.
   2. Provide a useful Name e.g. GenerateToken
   3. In the Privileges section, click Image Added Privileges
   4. Scroll down to the Full Repository, expand it and search for  the privilege: Use API Key
   5. Drag the Use API Key into the privileges section of the Role.
   6. Image Added
   7. Image Added Apply the changes
3. In the Image Added User Groups section, click Image Added User Groups
   1. Add a new Group for you Role.
      1. Give it a useful Name e.g. API Users.
      2. Add any users you require to be able to run the API. This could be a dedicated API user with limited privileges.
         1. To create a user see Managing User Accounts → Creating Users.
      3. In the Roles section, assign the role, User
      4. Click Image Added Apply and close the tab.
   2. Now drag the new user group into the Image Added User Groups section of the new privilege.
   3. Image Added Apply the changes
4. The setup should look similar to:
   1. Image Added

Step 9 - Authentication Token KeyStore

A signing key is used to generate the Phixflow API key and this is stored on the server to ensure secure access.

Using the page Configure a Keystore and Aliases, configure phixflow-api-key to be used as the signing key for PhixFlow API Keys in the same way as the pepperKey is configured. This secret string must be a minimum of 32 bytes length.

Step 10 - Generate Authentication Token

1. The Incoming API will run as a specified user, this means when it is called the audit trail will show the specified user as having performed the Incoming API actionflow
2. You do not need to login as this user, however, if you were already logged in as this user when performing Step 1 above, you will need to logout and login again to pick up the user group change
3. In the Image Added Repository, scroll down to the Full Repository section and expand it
4. Expand the Image Added Users section
5. Double click on the user who will run the Incoming API
6. Click the 3-dot more menu in the top right of the user properties
7. Click Generate API Key
8. Copy the value displayed and store it somewhere safe

Step 11 - Send Authorization

When calling the Incoming API, the authorisation token must be passed in as a header called: Authorization and referenced in the Expression using the syntax, ${_datasource.KeyName} where KeyName is the name of the Secret Key.

Image Added

Server Console Responses

The item calling the API End-Point will receive the a Response from the API End-Point stating whether it has run successfully (Success) or not (Fail). Responses can be customised to return specific messages.

The response recorded in the Image Added Console:

If you are making the call using PhixFlow the Responses can be access as follows:

1. Click the ActionFlow entry
   1. Image Added
2. In the Messages section which is opened below, double-click the lines that begin Response
   1. Image Added
3. Click the Message Details tab to see the response.

API End-Point Results

To see the results of the API End-Points processing in the Image Added Console:

1. Click the ActionFlow entry for the API End-Point
2. In the Messages section which is opened below, double-click any of the Messages to see more details
3. If you are using a debug() statement these will appear here.

Failures

An API End-Point will fail if the logic in the Actionflow fails or if the error() function is used to force a failure.

If records are passed to the API End-Point individually a failure will only impact the specific record being processed.

Version 11

Incoming API Setup

To enable an actionflow as an incoming API, we need to define it as an end point and configure an incoming connection point with a set of predefined input parameters. These settings are described below:

Step 1 - Actionflow Properties

1. Create an 

   Insert excerpt
   _actionflow _actionflow nopanel true

    from the Actionflow home page
2. Set a unique name and provide a useful description
   1. Note if using a pre 10.1 version of PhixFlow the name must be unique across all applications.
3. When the Actionflow opens, on the toolbar click 

   Insert excerpt
   _property_settings _property_settings nopanel true

4. In the API section of the properties, enable API End-Point
   1. This turns the Actionflow into an incoming API.
5. Enable Allow Anonymous Connections

   1. 
      

      Excerpt
      name AllowAnonymousConnections
      This allows anyone with the URL for the API to call it, the audit trail records the system as running performing the API call.

      
      

   2. Adding authorization is covered later on this page.

6. Insert excerpt
   _save _save nopanel true

    your changes

Step 2 - Input Connection Point Input Parameters

Incoming APIs require a specific set of Input Parameters on the connection point.

1. Click on the Connection Point In
2. In the Properties that open, in the Input Parameters section add the following attributes, the names are case sensitive:

Step 3 - Configure your Actionflow

1. Configure the Actionflow to perform the required tasks, for example return all company data , or pass in a date and return all companies onboarded after this date.
2. If you wish to return data from the API, 
   1. Add a new Connection of type Output
      
      1. The name of the Output Connection Point will be used to retrieve the data as part of the path. This is covered in Calling a PhixFlow API below.
      2. Add the required Output Attributes i.e. the data you wish the API to return.

Calling a PhixFlow API

Step 4 - HTTP Method and API Mode

1. HTTP Method
   1. To call a PhixFlow API use the HTTP Method GET or POST:
   2. GET simply calls the API with data passed in the body of the request.
   3. POST calls the URL and sends data in the body of the request. The body data is passed into the body attribute of the Actionflow setup above as an Input Connection point. 
2. API Mode
   1. Wait for result (Synchronous) (Default): The API waits for the results or the timeout to occur. Note: If the timeout occurs the command is aborted.
   2. Poll for result (Asynchronous): The API is called and a response is returned immediately including the process ID. Subsequent API calls can be made using the process ID to fetch the status of the action. The asynchronous mode can be thought of as “fire and forget”.

Step 5 - API URL

The API URL can be found in the Actionflow Properties → API Section → URL value

Example URL: https://app.phixflow.com/phixflow/api/1/action/MyApp/My%20API/trigger

Example URL

https://app.phixflow.comtrigger 
Integrations using this old structure should be updated, however the url structure will still work in version 11.

Step 5.1 - API Status Check (Poll for Result)

1. If calling a PhixFlow Asynchronous API only, a result will be immediately returned which includes a Process ID for that run.
2. The Process ID is returned on the path:
   1. $.processId
   2. This can be accessed in an Output attribute using, _result.value
3. The Process ID can be used to call the following URL which will return the current state of the run:
   1. https://<<Server Name>>/phixflow/api/1/action

1. 1. /<<Application Name>>/<<Actionflow Name>>/poll/<<processID>>

Step 6 - Returned Data JSON Path

If your API has been configured to return data the path will be in the format:

$.data.<<Output Name>> 

Where <<Output Name>> is the Output connection point setup in step 3.

Adding Authentication

Step 7 - Enable Authentication

1. Open the Incoming API Actionflow.
2. On the toolbar click 

Image Removed Properties

1. Insert excerpt
   _property_settings _property_settings nopanel true

2. In the

1. Basic Settings

1. section of the properties, click

1. Allow Anonymous Connection

1. so that it is disabled, it will appear

Image Removed Apply

1. greyed out.

2. Insert excerpt
   _save _save nopanel true

    the changes

Step 8 - Create an Authentication User

1. In the

Image Removed Repository

1. Insert excerpt
   _repository _repository nopanel true

   , expand the application with the Incoming API.
2. Expand

Image Removed Roles

1. Insert excerpt
   _roles _roles nopanel true

    and create an New Role by

Image Removed

1. clicking 

   Insert excerpt
   _addIcon _addIcon nopanel true

   .
   1. Pin the tab as we will need it to remain open.
   2. Provide a useful

1. 1. Name

1. 1. e.g. GenerateToken
   2. In the Privileges section, click 

Image Removed Privileges

1. 1. Insert excerpt
      _privilege _privilege nopanel true

   2. Scroll down to the

1. 1. Full Repository, expand it and search for  the privilege: Use API Key
   2. Drag the Use API Key into the privileges section of the Role.
   3. Image Modified

Image Removed Apply

1. 2. Insert excerpt
      _save _save nopanel true

       the changes
2. In the 

Image Removed User Groups

Image Removed User Groups

1. Insert excerpt
   _user_group _user_group nopanel true

    section, click 

   Insert excerpt
   _user_group _user_group nopanel true

   1. Add a new

1. 1. Group

1. 1. for

1. 1. your Role.
      1. Give it a useful

1. 1. 1. Name

1. 1. 1. e.g. API Users.
      2. Add any users you require to be able to run the API. This could be a dedicated API user with limited privileges.
         1. To create a user see Managing User Accounts → Creating Users

Image Removed Apply

1. 1. 1. 1. .
      2. In the Roles section, assign the role, User
      3. Click 

         Insert excerpt
         _save _save nopanel true

          and close the tab.
   2. Now drag the new user group into the 

Image Removed User Groups

1. 1. Insert excerpt
      _user_group _user_group nopanel true

       section of the new privilege.

Image Removed Apply

1. 2. Insert excerpt
      _save _save nopanel true

       the changes
2. The setup should look similar to:
   1. Image Modified

Step 9 - Authentication Token KeyStore

A signing key is used to generate the Phixflow API key and this is stored on the server to ensure secure access.

Using the page Configure a Keystore and Aliases, configure phixflow-api-key to be used as the signing key for PhixFlow API Keys in the same way as the pepperKey is configured. This secret string must be a minimum of 32 bytes length.

Step 10 - Generate Authentication Token

1. The Incoming API will run as a specified user, this means when it is called the audit trail will show the specified user as having performed the Incoming API actionflow
2. You do not need to login as this user, however, if you were already logged in as this user when performing Step 1 above, you will need to logout and login again to pick up the user group change
3. In the 

Image Removed Repository

1. Insert excerpt
   _repository _repository nopanel true

   , scroll down to the

1. Full Repository section and expand it
2. Expand the

Image Removed Users

1. Insert excerpt
   _user _user nopanel true

    section
2. Double click on the user who will run the Incoming API
3. Click the 3-dot more menu in the top right of the user properties
4. Click

1. Generate API Key
2. Copy the value displayed and store it somewhere safe

Step 11 - Send Authorization

When calling the Incoming API

, the authorisation token must be passed in as a header called: Authorization and referenced in the Expression using the syntax, ${_datasource.KeyName} where KeyName is the name of the Secret Key.

Image Added

Server Console Responses

The item calling the API End-Point will receive the a Response from the API End-Point stating whether it has run successfully (Success) or not (Fail). Responses can be customised to return specific messages.

The response recorded in the

Image Removed Console

If you are making the call using PhixFlow the Responses can be access as follows:

1. Click the ActionFlow entry
   1. Image Modified
2. In the

1. Messages section which is opened below, double-click the lines that begin

1. Response
   1. Image Modified
2. Click the Message Details tab to see the response.

API End-Point Results

To see the results of the API End-Points processing in the 

Image Removed Console

1. Click the ActionFlow entry for the API End-Point
2. In the

1. Messages section which is opened below, double-click any of the Messages to see more details
2. If you are using a debug() statement these will appear here.

Failures

An API End-Point will fail if the logic in the Actionflow fails or if the

error() function is used to force a failure.

If records are passed to the API End-Point individually a failure will only impact the specific record being processed.