External API
What is the External API Property?
The External API property is a relationship level property that enables a workflow to send information to a particular location and in a particular way. By using the External API property, TAP can communicate with other applications and "do" certain things to them. To learn more about what an API is, click here.
How do I set up an External API with TAP?
TAP has out-of-box Salesforce, Team Connect, and e-Signature integrations, which means that the API has already been set up and is within the infrastructure of TAP. If you want to integrate with another software that is not out of box, you can do that with an external API by following the instructions below.
- First, navigate to the workflow builder in the designer tool, and select the relationship at which you would like to communicate with another application.
- After selecting the relevant relationship or stage, click on the
External API icon. A dialog box will appear.
- To create a call, click the 'Add' button in the bottom right hand corner.
Each stage/relationship can have multiple API calls configured. At the stage level, calls will be triggered according to the parameters set within the configuration. At the relationship level, all calls will proceed in series once the stage has been submitted.
You can set up multiple calls at relationship level. For instance, one call to collect the API token and other to GET files or upload documents using POST method. All these calls will be displayed in the External API main screen as labels.
At the stage level there is a limit to add API calls which is dependent on the setting 'TriggerCountThreshold'.
Follow the steps listed in each section to correctly set up an external API.
Main Info
- In the Configuration Name box, type the API configuration name which will appear as label on the External API screen.
- In the API URL box, type in the API end point.
- In the Method drop down, select the type of API call you wish to make, whether a GET request, POST request, etc.
- Select the checkbox for Prevent workflow submission if response is invalid if this fits in with your business needs. This setting ensures that a bad call prohibits further movement in the workflow.
- Click the Add button to add headers, which provide metadata within the request. This is not required but it is encouraged.
Request
For POST, PUT, DELETE, HEAD, OPTIONS, PATCH, and MERGE methods the request section becomes available.
Response
The response is used when you need to return information to a TAP field. For example, if you have an authorization call and receive a token, you can return that token into a TAP field. Then, you can set up a second API call to push that information forward.
- Select the text field into which you would like to parse your data. Use the ID of the response in the Use Formula Calculation.
Aliases
When you get a response from an API it has it's own formatting. With the Aliases function, you can rename that response whatever is most helpful for you.
Note: You only need to do aliases if you're going to refer to it in your responses.
- The Alias key is the value you want to return.
- Body identifies where in the response you will display this value.
- Object navigation is the untouched response from the API call.
Validation
Validation allows you to set up custom error messages.
- Add a custom message in the Custom error message box.
- Click the Add new condition rule to attach conditions to the error message or validation.
Authorization
Authorization allows you to set up authorizations. You may choose no auth, basic, Oath 2.0, or use existing from another relationship. Form field results may used to pull in values when using basic auth.
Files
If part of your API response sends a file, setting up files allows you to return those files into your TAP form.
Click Save when finished.
