Overview

Actionflows can be setup to provide an API end point which enables external systems to make calls to PhixFlow.

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 setting are described below:

Step 1 - Actionflow Properties

1. Create an 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  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.  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.  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:

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

Example URL

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

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.

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  System Console:

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

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

API End-Point Details

To see the results of the API End-Points processing in the  System 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.

Adding Authentication

Step 7 - Enable Authentication

1. Open the Incoming API Actionflow.
2. On the toolbar click  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.  Apply the changes

Step 8 - Create Authentication User

1. In the  Repository, expand the application with the Incoming API.
2. Expand  Roles and create an New Role by clicking .
   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  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. 
   7.  Apply the changes
3. In the  User Groups section, click  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. Click  Apply and close the tab.
   2. Now drag the new user group into the  User Groups section of the new privilege.
   3.  Apply the changes
4. The setup should look similar to:
   1. 

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 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. Login as this user
   1. 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  Repository, scroll down to the Full Repository section and expand it
4. Expand the  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

Step API Responses